[Build-common-hackers] Documenting CDBS

[Felipe Sateler]

On Sat, Dec 25, 2010 at 19:12, Jonas Smedegaard <dr at jones.dk> wrote:
> On Sat, Dec 25, 2010 at 11:32:29AM -0300, Felipe Sateler wrote:
>>
>> On Wed, Dec 22, 2010 at 09:29, Jonas Smedegaard <dr at jones.dk> wrote:
>>>
>>> On Wed, Dec 22, 2010 at 08:34:19AM -0300, Felipe Sateler wrote:
>>>>
>>>> On Wed, Dec 22, 2010 at 07:17, Jonas Smedegaard <dr at jones.dk> wrote:
>>>>>
>>>>> On Tue, Dec 21, 2010 at 08:51:29PM -0300, Felipe Sateler wrote:
>>>>>>
>>>>>> 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?
>>>>>
>>>>> Sure Docbook can do a lot that simpler formats cannot.  But please let
>>>>> os only emphasize issues relevant to ourselves for this project.
>>>>>
>>>>> Do you find that cross-referencing feature important here?  If so,
>>>>> please elaborate, as I am not quite sure what it is (guessing it is more
>>>>> than generating a table of contents).
>>>
>>>> The most obvious cross-referencing applications is for variables and
>>>> targets tables/lists. They can be used in the more tutorial-like part of the
>>>> documentation and then put as reference in an appendix for already users of
>>>> CDBS. Can Markdown do this, without involving copy/paste or links to other
>>>> pages?
>>>
>>> Sorry, I still don't get it.  Could you perhaps point to an example of
>>> that use?
>>
>> Debian policy has lots of references from one section to others. These are
>> not maintained by linking directly to a page but by keeping a symbolic name
>> for each section and then placing the link to that symbolic name.
>
> Ok.  I understand now what it is.
>
> No, Pandoc flavor of Markdown (altough enhanced compared to original parser)
> do not support such cross references.
>
> Question remains: Is it relevant here?
>
> Not just "is it useful?" - no doubt it is - but more of "is it more useful
> than being easier to edit?"

After considering, the size of the CDBS docs will probably not warrant
the trade-off between ease of editing and usefulness of this
particular feature.

>
> Is it used already (and a big loss to drop) in current CDBS docs?

Not that I can see.

>
> Do you intend to devote time to CDBS documentation and prefer this feature
> (and other Docbook benefits) over the (claimed) simplification of switching
> to Pandoc Markdown?

I prefer to not stand in the way of others contributing. I was not in
an "either or" stance, just stating some benefits that may have been
useful to know.

-- 

Saludos,
Felipe Sateler