[Build-common-hackers] Documenting CDBS
fsateler at debian.org
Tue Dec 21 23:51:29 UTC 2010
, 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?
More information about the Build-common-hackers