FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Gentoo > Gentoo Portage Developer

 
 
LinkBack Thread Tools
 
Old 11-26-2010, 03:32 PM
Lionel Orry
 
Default portage docbook documentation -> why not asciidoc ?

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

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

Kind regards,
Lionel
 
Old 11-26-2010, 07:18 PM
Zac Medico
 
Default portage docbook documentation -> why not asciidoc ?

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'.
>
> 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. Maybe
XML isn't quite as easy to read and edit, but it seems like a good
trade-off to me.
--
Thanks,
Zac
 
Old 11-26-2010, 07:37 PM
Lionel Orry
 
Default portage docbook documentation -> why not asciidoc ?

The fact is, asciidoc does generate native docbook output. The result
I gave was made using docbook-xsl-stylesheets and a css file. So you
wouldn't loose the docbook flexibility then...

My 2 cents. It's up to you, of course.
Lionel

On Fri, Nov 26, 2010 at 9:18 PM, Zac Medico <zmedico@gentoo.org> 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'.
>>
>> 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. Maybe
> XML isn't quite as easy to read and edit, but it seems like a good
> trade-off to me.
> --
> Thanks,
> Zac
>
>
 
Old 11-26-2010, 08:03 PM
Zac Medico
 
Default portage docbook documentation -> why not asciidoc ?

On 11/26/2010 12:37 PM, Lionel Orry wrote:
> The fact is, asciidoc does generate native docbook output. The result
> I gave was made using docbook-xsl-stylesheets and a css file. So you
> wouldn't loose the docbook flexibility then...

Hmm, do it's like an extra translation layer on top of docbook? For ease
in reading/editing, I think that I'd prefer to use some type of
automated editing tool that to add an additional layer of markup.
--
Thanks,
Zac
 
Old 11-27-2010, 08:25 AM
Sebastian Pipping
 
Default portage docbook documentation -> why not asciidoc ?

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.

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?

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


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


> 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]).

Best,



Sebastian


[1]
http://layman.git.sourceforge.net/git/gitweb.cgi?p=layman/layman;a=commitdiff;h=a8eee022c6dc2085d4e37e838ffb 45404f77242b
[2]
http://git.fedorahosted.org/git/?p=enum.git;a=blob;f=man/enum.1.txt;hb=HEAD
 
Old 11-27-2010, 11:27 AM
Lionel Orry
 
Default portage docbook documentation -> why not asciidoc ?

On Sat, Nov 27, 2010 at 10:25 AM, Sebastian Pipping <sping@gentoo.org> 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=a8eee022c6dc2085d4e37e838ffb 45404f77242b
> [2]
> http://git.fedorahosted.org/git/?p=enum.git;a=blob;f=man/enum.1.txt;hb=HEAD
>
>
 
Old 11-27-2010, 12:10 PM
Sebastian Pipping
 
Default portage docbook documentation -> why not asciidoc ?

On 11/27/10 13:27, Lionel Orry wrote:
> [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.

I see, thanks.


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

That would mean it stays unnecessarily hard for new devs to join if I
understand your point correctly.

Best,



Sebastian
 
Old 11-27-2010, 01:53 PM
Zac Medico
 
Default portage docbook documentation -> why not asciidoc ?

On 11/27/2010 01:25 AM, Sebastian Pipping wrote:
> On 11/26/10 21:18, Zac Medico wrote:
>> 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?

Honestly, I don't know.

> In case DocBook is keeping contributions down than cutting away certain
> flexibility to increase contributions could be a good trade-off, too.

I'm not sure that docbook represents a significant barrier in this
respect. It's hard to speculate. Maybe if we had a survey sampling the
opinions of a broad spectrum of open-source developers, then we'd have
more to go on.

As it is, I'm fairly comfortable with docbook. Now you want me to learn
a new format, with possible drawbacks, in order to try and draw in some
contributions that may never happen?
--
Thanks,
Zac
 
Old 11-27-2010, 08:39 PM
Alec Warner
 
Default portage docbook documentation -> why not asciidoc ?

On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico <zmedico@gentoo.org> wrote:
> On 11/27/2010 01:25 AM, Sebastian Pipping wrote:
>> On 11/26/10 21:18, Zac Medico wrote:
>>> 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?
>
> Honestly, I don't know.
>
>> In case DocBook is keeping contributions down than cutting away certain
>> flexibility to increase contributions could be a good trade-off, too.
>
> I'm not sure that docbook represents a significant barrier in this
> respect. It's hard to speculate. Maybe if we had a survey sampling the
> opinions of a broad spectrum of open-source developers, then we'd have
> more to go on.

In general I don't see docbook as a problem. If I file a portage bug
and say something needs to be changed or documented then attaching
plain text additions is usually sufficient for inclusion. The bigger
problem portage faces is that very few people actually know enough
about how it works and this leaves only a few people who can actually
write (or verify) that documentation is correct.

>
> As it is, I'm fairly comfortable with docbook. Now you want me to learn
> a new format, with possible drawbacks, in order to try and draw in some
> contributions that may never happen?

Here is where I would look for data. Are there pending contributions?
I have not seen anyone on this list specifically say "I'd write some
documentation if it was not in docbook." I have had issues (years
ago) getting vapier to write documentation; but I assumed that was
because he hated writing docs and he contributed documentation after a
while.

> --
> Thanks,
> Zac
>
>
 
Old 11-27-2010, 08:50 PM
Mike Frysinger
 
Default portage docbook documentation -> why not asciidoc ?

On Saturday, November 27, 2010 16:39:04 Alec Warner wrote:
> On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote:
> > As it is, I'm fairly comfortable with docbook. Now you want me to learn
> > a new format, with possible drawbacks, in order to try and draw in some
> > contributions that may never happen?
>
> Here is where I would look for data. Are there pending contributions?
> I have not seen anyone on this list specifically say "I'd write some
> documentation if it was not in docbook." I have had issues (years
> ago) getting vapier to write documentation; but I assumed that was
> because he hated writing docs and he contributed documentation after a
> while.

not sure where you're going with this, but i'm the one who started the doc/
dir and introduced the docbook system. obviously i have no problem with it
and would rather see real examples of people who are being impeded by it
rather than yet another "omg we need to switch to this awesome new format
because it is so awesome".
-mike
 

Thread Tools




All times are GMT. The time now is 09:54 PM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org