[Build-common-hackers] Documenting CDBS

[Jonas Smedegaard]

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.


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?



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