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

[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. 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