[Build-common-hackers] Bug#649151: cdbs: documentation missing

[Jonathan Nieder]

Hi Jonas,

Jonathan Wiltshire wrote:

> This bug originates from a commit [1], I could not find any mentioned 
> reason for it.
>
> 1: 
> http://anonscm.debian.org/gitweb/?p=collab-maint/cdbs.git;a=commit;h=6b0828d3925098f6f0baf83cc798413066f544df

Jonas Smedegaard wrote:

> My idea is to...
>
>  1. Convert the official documentation to (Pandoc flavor of) Markdown
>  2. Convert and merge in the unofficial documentation
>  3. Convert translations of unofficial documentation using po4a
>  4. Update with recent changes to CDBS
>  5. Release as a separate cdbs-doc source package
>
> I don't know how fast this can be done.  I disagree about the severity 
> of this bugreport, just annoyed by the bug-pingpong.  I may downgrade it 
> if it stalls too much other more important changes from entering 
> testing.

I just noticed this bug in the context of general RC bugfixing, but it
has affected me before so I can understand where Steve was coming from.
(If it were me, I'd treat it as important, not serious, though.)  What
documentation do you recommend

 (1) that someone new to cdbs start with
 (2) that someone familiar with cdbs use as a reference

?  For simplicity, I think it would be fine to render it as plain text
and treat that as the canonical form in the short term, for example.

What do you think?

Thanks and hope that helps,
Jonathan