[kde-doc-english] Is asciidoc for us?

[Burkhard Lück]

Hi Jaroslaw,

thanks for caring about tools to ease writing documentation.

Am Dienstag, 28. Juli 2015, 21:33:20 schrieb Jaroslaw Staniek:

> My use of docbook failed due to complexity. Also userbase-based docs
> (at least for Kexi, for which a finished book could be easily over 300
> pages) are far from perfect and not too actively maintained. No
> surprise as it's too much of work if it's used "just" by KDE.
> 
> Still I am grateful for tools that we have now!
> 
> In the meantime I just installed asciidoc.[1] Some projects like git
> use it for all documentation needs. There's support for localization
> via po4a.
> There's even more than one implementation.
> 
> Anyone considered asciidoc as a docbook replacement? It would be good
> to discuss this and see how it fits for our needs.
> 
Afair kde-doc-english never considered asciidoc as a docbook replacement.

I have not used asciidoc so far, so I had to read the documentation you 
provided in your link, but did not test any tools for transformation 
asciidoc>docbook or the translation tools.

Some comments from my pov:

* Syntax looks similar to the syntax used in our wikis (?)

* Asciidoc has probably the same "weak" syntax compared to docbook, but that 
should not be a problem, we are able to extract nearly everything from 
userbase on the fly, we just have to adjust the "quirks" mode in the extraction 
script

* assuming the tools mentioned on the asciidoc page works as expected, it 
should be no problem to integrate asciidoc into our workflow:

  * asciidoc could be converted via create_handbook macro at build time into
    docbook
  * alternatively this could/should be done by scripty on his daily run
  * converting asciidoc into docbook in the source code repo would leave the
    complete documentation translation toolchain unchanged, translation teams
    won't even notice that they translate docs written in asciidoc format

The only downside in asciidoc I see is the missing support in Kate, which is 
excellent for docbook.

*But* even if if I see no technical problems to use asciidoc format:
I really doubt the the docbook format is the reason of missing user 
documentation and a switch to asciidoc would solve that issue.

Thanks.

-- 
Burkhard Lück