Is asciidoc for us? (dogfooding Calligra Words)

[Jos van den Oever]

On 07/28/2015 07:33 PM, Jaroslaw Staniek wrote:
> Hi!
> 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.
>
> [1] http://www.methods.co.nz/asciidoc/
>

Calligra comes with two word processors: Words and Author. Those have 
the file format ODF. ODF has all the features needed for documentation. 
Using your own tools for documentation is a good way of dogfooding. 
Certainly Calligra Words is good enough for the developers to use 
themselves. It is good to show confidence in your own tools by using them.

With a nice styles.xml and sane style names, writing the ODF with 
Calligra or any other editor should work fine. You could use the XML 
serialization of ODF. With some XSLT that could then be converted to 
Docbook for use in the KDE toolchain.

I'm developing a tool that cleans up ODF files so the diffs in git are 
small. The ODF TC is using this tool for comming clean versions of the 
specification in the source control system.

   https://gitlab.com/odfplugfest/odfhistory/

Using Calligra Words for documentation will really improve Calligra 
Words and the documentation.

Cheers,
Jos