community-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <>
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 <> 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:
>> For additional commands, e-mail:
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message