[Build-common-hackers] Documenting CDBS

[Jonas Smedegaard]

On Tue, Dec 21, 2010 at 08:51:29PM -0300, Felipe Sateler wrote:
>, Jonas Smedegaard <dr at jones.dk> wrote:
>> From a brief look, it seems [http://cdbs-doc.duckcorp.org/] is in a 
>> better shape than the included one.  So perhaps a first step should 
>> be to try merge them?
>>
>> I have Cc'ed Marc to get his opinion too.
>
>Indeed, that documentation is a lot better than the included one. It
>would be a big improvement if it were merged.

Let's give some time for Marc to respond.  He does not receive my emails 
(seems he is rejecting my MX host due to lack of reverse record) but I 
guess he got my message via your response (and maybe also via the list).


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


Kind regards,

  - Jonas

-- 
  * Jonas Smedegaard - idealist & Internet-arkitekt
  * Tlf.: +45 40843136  Website: http://dr.jones.dk/

  [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/build-common-hackers/attachments/20101222/ca2166f9/attachment.pgp>