[Build-common-hackers] Documenting CDBS

[Felipe Sateler]

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.


-- 

Saludos,
Felipe Sateler