On 29 July 2015 at 22:38, Burkhard Lück <lu...@hube-lueck.de> wrote: > 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. >
Thanks so much for checking it, Burkhard. > *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. I can only say how it works for me. I am getting distracted by heavy markup of docbook. Also with the wiki where navigation links have to be hardcoded. A side note, I remember that the Doc Team offered help when someone sends docs in plain text. But the work on docs is iterative and why not having the semi-final markup produced during the (creative) work already? That's what I see light markup tools give us. At least I am motivated to try and will let you know what happens. I also like the idea that asciidoc and its generators are extensible and we like tweaking. (not tried anything though, I have just read the docs, like you) Maybe even it could be possible to exchange what's this/tooltip info between an app an the docs. (just an idea) Thanks. -- regards, Jaroslaw Staniek KDE: : A world-wide network of software engineers, artists, writers, translators : and facilitators committed to Free Software development - http://kde.org Calligra Suite: : A graphic art and office suite - http://calligra.org Kexi: : A visual database apps builder - http://calligra.org/kexi Qt Certified Specialist: : http://www.linkedin.com/in/jstaniek _______________________________________________ calligra-devel mailing list calligra-devel@kde.org https://mail.kde.org/mailman/listinfo/calligra-devel
