community-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [DISCUSS] Documentation
Date Mon, 14 Nov 2016 23:39:38 GMT
It's useful to be able to read commit diffs.

AIUI OpenOffice docs are zipped so diffs aren't generated by SVN/Git etc.

Also if the documentation source is all text-based then it's a lot
easier to do searches and scripted edits (e.g. to fix common typos)



On 14 November 2016 at 19:54, Manfred Moser <manfred@simpligility.com> wrote:
> I have used all those as well and my preference still sits with asciidoc. Mostly because
I have a larger choice of quality output.
>
> If I have the choice overall and write more complex stuff on my own I would probably
go back to LaTeX ;-)
>
> manfred
>
> Martin Desruisseaux wrote on 2016-11-14 11:16:
>
>> Le 14/11/16 à 19:10, Manfred Moser a écrit :
>>> Switching from Asciidoc to OpenOffice seems like a recipe for disaster to me.
>>> Asciidoc (or asciidoctor) is very capable for PDF creation and is used in
>>> publishing companies like OReilly.
>>
>> On my side I used at different time OpenOffice, Asciidoc, Docbook, Maven
>> APT and Markdown. After all those attempts, my preference now (for the
>> documentation that I write) is plain HTML with a CSS complete enough for
>> avoiding formatting code in most places of HTML files. I found Asciidoc
>> or Maven APT too limited (I often needed more advanced features like
>> tables with some merged cells, equations, etc). Markdown allows to write
>> HTML inline, but when I start doing that I could as well write the full
>> document in HTML and get the help of HTML editors. Docbook is very rich,
>> but requires learning a new language which is not that much simpler than
>> HTML 5.
>>
>> Another reason is for introducing some semantic in the documents.
>> Asciidoc, Maven APT or Markdown allows to said "put this text in italic"
>> while HTML 5 or Docbook allows to said "this text is a citation" or
>> "emphases this text". The rendering is the same, but I presume that the
>> value of HTML approach may slowly increase in the next years with the
>> progress of semantic web.
>>
>>    Martin
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
>> For additional commands, e-mail: dev-help@community.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org


Mime
View raw message