Re: [gentoo-portage-dev] portage docbook documentation -> why not asciidoc ?

[Lionel Orry]

On Sat, Nov 27, 2010 at 10:25 AM, Sebastian Pipping <sping@g.o> wrote:
> On 11/26/10 21:18, Zac Medico wrote:
>> On 11/26/2010 08:32 AM, Lionel Orry wrote:
>>> Dear all,
>>>
>>> I just made a try to convert the portage documentation
>>> (http://dev.gentoo.org/~zmedico/portage/doc/) to asciidoc so that it
>>> would be easier to maintain and with a standard layout and style that
>>> is IMHO not bad and makes the doc easier to read. Are you interested?
>>>
>>> I attach the asciidoc sources, a tiny makefile and an already
>>> generated version in the 'portage.chunked' directory. All you need to
>>> generate the doc is 'emerge asciidoc'.
>
> What I have seen of the output looked awesome, the sources look clean.

[Lionel] Thanks, but please note that I did not customisation to the
standard style shipped with asciidoc. This default css is quite good
most of the time, but it's still interesting to know that a
customization layer is very easy to add, for example to get closer to
a gentoo style.

>
> I noticed that on the index page the table of contents are not as
> detailed as in the current version online.  Is that wanted or a
> limitation?  If the latter: is that a problem?

[Lionel] In fact you can customize the toc level with a 'toclevel'
attribute on the command-line, see the Makefile. I did several tries
but you can get the same level as the original doc with '-a
toclevels=4' if I remember well. In short, it's not a problem.

>
> On the conversion: did you come across any limitations?
> Anything that you were not able to map 1:1?
>

[Lionel] Indeed, a few things :

1. I must investigate how to include several tocs (one per each part)
as the original doc does. I think this is a matter of docbook backend
customization. Again, a customization layer is easy to add, we just
have to create a 'docbook.conf' file in the same directory as the
input 'portage.txt' file and only include overrides in it. I will do
it your team thinks it's worth looking deeper at switching to
asciidoc.

2. Only 5 section levels are allowed by asciidoc, most of the time
they are really enough, but it seems the portage documentation uses
many more nested levels (7 or maybe 8). So I tricked a bit by
replacing these section titles by stylized paragraphs (strong for
level 6 and emphasized (italic) for level 7. I can't remember if there
were level 8, if it was the case, I think I used a normal paragraph.
This implies a loss of semantics and not-that-good look and feel in my
opinion, but there's a good point for asciidoc: independently of the
backend/tool used to write a technical documentation, I feel like
using more than 5 levels of nesting shows that the doc has a problem.
It should either be restructured, or split in several documentations.
It's hard to follow the logic line of a doc that uses so many nested
levels. That's a personal opinion, and I don't consider myself a good
doc writer either.

One should note that sections is not the only way to structure the
doc. Lists (ordered, itemized and labeled (definition lists)) help a
lot in doing so, and both asciidoc and docbook allow to inserts
anchors on such elements so the cross-referencing is possible.

3. The multiple author issue explained below. One solution is already
given below, I will look at it deeper if it's not a loss of time.

>
>>> The only issue I had was including several authors, so this part is
>>> commented out. But if we stick to the docbook backend, we can include
>>> a docinfo file that solves the problem.
>>>
>>> Hope you'll find this useful...
>>
>> The asciidoc format seems nice, but personally, I think I prefer docbook
>> since the SGML/XML approach seems more flexible and extensible.
>
> Are you making use of that flexibility anywhere at the moment?  If not
> is such use planned for something specific?
>
> In case DocBook is keeping contributions down than cutting away certain
> flexibility to increase contributions could be a good trade-off, too.

[Lionel] I can only agree with you about that. Docbook is certainly a
very good standard, but writing xml does scare people and it is
probably a blocker for contributions. asciidoc (or other similar
formats like RST and such) helps contributions, it's like editing a
plain README. But one thing I don't know, is that whether that doc
asks for external contributions or is kept as an internal reference
and should only be taken care of by the devs.

>
>
>> Maybe
>> XML isn't quite as easy to read and edit, but it seems like a good
>> trade-off to me.
>
> I migrated the documentation of Layman from DocBook to AsciiDoc recently
> [1], because I noticed that the one reason I never really touched the
> documentation after taking Layman over (besides version upgrades) was
> DocBook.  And that despite the fact that I started using AsciiDoc only a
> few months ago (on the enum project [2]).

[Lionel] Thanks for sharing your ideas! In my case, I already helped
the waf project to migrate from docbook to asciidoc and its maintainer
is quite happy about the change. See
http://waf.googlecode.com/svn/docs/wafbook/single.html

Best regards,
Lionel

>
> Best,
>
>
>
> Sebastian
>
>
> [1]
> http://layman.git.sourceforge.net/git/gitweb.cgi?p=layman/layman;a=commitdiff;h=a8eee022c6dc2085d4e37e838ffb45404f77242b
> [2]
> http://git.fedorahosted.org/git/?p=enum.git;a=blob;f=man/enum.1.txt;hb=HEAD
>
>