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

[Alec Warner]

On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico <zmedico@g.o> 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
>
>