[Build-common-hackers] Documenting CDBS

[Felipe Sateler]

On Sat, Dec 25, 2010 at 21:43, Jonas Smedegaard <dr at jones.dk> wrote:
> On Sat, Dec 25, 2010 at 09:28:25PM -0300, Felipe Sateler wrote:
>>
>> 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.
>
> And thanks for that.  Appreciated - I learned something!
>
> Can you be persuaded to look at merging the docs by Marc?

Sure. I'll try to find a commit with common content, to preserve
history. Wish me luck!


-- 

Saludos,
Felipe Sateler