Am Donnerstag, 30. Juli 2015, 09:25:12 schrieb Jaroslaw Staniek: > 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.
Yes we have converted plaintext, wiki pages, docbook exported from office apps and whatnot into docbook we use in KDE, that never was a problem. > But the work on docs is iterative and why > not having the semi-final markup produced during the (creative) work > already? That's no problem, master in plasma + applications is always open for commits except the last 3 weeks before a new major release. In theory stable branches are always frozen, but we (translation team) backport since around 10 years everything from master once a month to get doc updates into the next minor stable release. So I see no issues with iterative doc updates. > That's what I see light markup tools give us. > > At least I am motivated to try and will let you know what happens. > We should have a small new documentation in asciidoc format e.g an article for a systemsettings module <hint>Activities has no doc - anyone?</hint> to test the workflow first manually, identify any problems and are then able to integrate this format into the docbook workflow. > 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. -- Burkhard Lück _______________________________________________ calligra-devel mailing list calligra-devel@kde.org https://mail.kde.org/mailman/listinfo/calligra-devel
