[Build-common-hackers] Documenting CDBS

[Felipe Sateler]

On Wed, Dec 22, 2010 at 07:17, Jonas Smedegaard <dr at jones.dk> wrote:
> On Tue, Dec 21, 2010 at 08:51:29PM -0300, Felipe Sateler wrote:
>>
>> , Jonas Smedegaard <dr at jones.dk> wrote:
>>>
>
>>> Personally I have a hard time editing in Docbook XML format.  It is
>>> difficult enough documenting at all, but trying to do it in that XML format
>>> is a showstopper for me.  I like Markdown, and have considered to "flatten"
>>> the docbook file (using Pandoc) and in the future use Markdown as source
>>> format for the documentation.  How do others feel about that?
>>
>> I have no particular love for XML, but docbook does have the advantage
>> (that the current documentation is not taking) of splitting stuff into
>> smaller files and then do cross-references among them (or even subsections
>> of files). Can Markdown do that?
>
> Sure Docbook can do a lot that simpler formats cannot.  But please let os
> only emphasize issues relevant to ourselves for this project.
>
> Do you find that cross-referencing feature important here?  If so, please
> elaborate, as I am not quite sure what it is (guessing it is more than
> generating a table of contents).
>
> My points, important for my own contributing, are these:
>
>  * Markdown is vastly simpler to edit than Docbook
>  * Markdown is also gettext translatable (using po4a)
>  * I am familiar with the po4a Markdown plugin (as I wrote it)
>  * I am familiar with Pandoc Markdown parser (as I maintain it)
>  * I don't mind loosing some markup vocabulary
>
>
> Please add your points - anyone who (like me) consider contributing to the
> documentation.

The most obvious cross-referencing applications is for variables and
targets tables/lists. They can be used in the more tutorial-like part
of the documentation and then put as reference in an appendix for
already users of CDBS. Can Markdown do this, without involving
copy/paste or links to other pages?

I do agree that Markdown is simpler to edit.


-- 

Saludos,
Felipe Sateler