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

[Burkhard Lück]

Am Donnerstag, 30. Juli 2015, 09:25:12 schrieb Jaroslaw Staniek:
> On 29 July 2015 at 22:38, Burkhard Lück <lueck at 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