Is asciidoc for us? (dogfooding Calligra Words)

[Jos van den Oever]

On 11/06/2015 09:30 AM, Jaroslaw Staniek wrote:
> On 6 November 2015 at 07:23, Jos van den Oever <jos.van.den.oever at kogmbh.com
>> wrote:
>
>> 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 conver
>> ​​
>> ted 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.
>>
>>
> ​Jos
> I share the sentiment. Yes, gitbook competes with what Author would be.
>
> But I see the same category there are following observation:
>
> - we, technical people are still using command line and so frequently
> non-GUI editors instead of Kate, despite the fact that using Kate more can
> improve it
>
> - we, technical people do versioning via git, mostly because it's close to
> command line and text content to, we don't use zip files to despite the
> fact that doing that would improve, say, Ark
>
> - we, technical people use Phabricator for light project management instead
> of Calligra Plan, despite the fact that using Plan would improve it
>
> - same for TODO lists: I've seen dozens of command line tools for that,
> many used by KDE people, despite the fact that using Kontact would improve
> it
>
> - did I mention KMail?

I use KMail. :-)



>
> So for me that's: use best tools available for the job. And that there's
> some fundamental difference between the approaches that drag people to less
> 'integrated' tools.
>
> Technical limitation of XML diffs is also somewhat important, even if we
> use fodf. I am looking forward to try your results. And I'd like to seem,
> say LO's help converted to the format and developed this way. Someone
> should convince me that LO would depend on Calligra for own document
> tooling needs.
>
> I think Calligra-based solution shall be much better to balance the issue
> with difficult deployment (on Linux statistically people have no access to
> current Calligra, on Windows the Docbook dependencies are just a nightmare
> to have installed and maintained -- not many users of that, end even if,
> the "KDE" flavour is used just by the fraction of KDE devs, while competing
> solutions). If it's just "like" plain asciidoc or gitbook-like solutions,
> there's no market IMHO. BTW, gitbook.com has some business model, while we
> depend on donations shared with entire KDE.
>
> Summing up for now: I don't see anyone who cares until there's excellent
> solution. KDE's own needs form too small 'market' and even within KDE
> there's not much interest from what I observe.
>
> One solution could be: make our apps more agile and command-line friendly.
> This is huge non-programming task.

It is not just about the user interface but also the file format.

I saw a very interesting and entertaining presentation today about 
exactly the tendency of developers to use custom markups for specific 
simplified purposes instead of using a rich xml format.
  http://ndw.github.io/presentations-2015-xml-amsterdam/#/
It also mention asciidoc and docbook.

Cheers,
Jos