[Build-common-hackers] Documenting CDBS

[Felipe Sateler]

-- 

Saludos,
Felipe Sateler

, Jonas Smedegaard <dr at jones.dk> wrote:
> Hi Felipe,
>
> On Sat, Dec 18, 2010 at 02:09:01PM -0300, Felipe Sateler wrote:
>>
>> CDBS documentation is lacking, to say the least. What is really needed is
>> a reference guide that will tell users which variables and targets are
>> available in each file, and what they are for. I've been looking around but
>> I haven't found a doxygen-like tool for makefiles (well, I did but it seemed
>> dead, mkdoxy). Looking around, some people prefer to have a help target that
>> will output the available targets. I think the amount of targets in CDBS
>> will make this approach not very useful. One could also extend the cdbs
>> manual with an appendix with all of this information. What do you think is a
>> reasonable approach on this issue?
>> I think the last approach is better, although it would possibly
>> require more maintainance (although do variables and targets change
>> that often?).  I can start it, but help would be appreciated.
>
> Thanks a lot for raising this issue.
>
> Some time ago I stumbled upon this: http://cdbs-doc.duckcorp.org/
>
> I don't know the reason for the fork, but I would sure like to join forces.
>
> From a brief look, it seems that documentation 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.

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


-- 

Saludos,
Felipe Sateler