[Build-common-hackers] Documenting CDBS

Jonas Smedegaard dr at jones.dk
Tue Dec 21 20:51:40 UTC 2010

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 

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.

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?


 - 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/20101221/4e3c5797/attachment.pgp>

More information about the Build-common-hackers mailing list