[Build-common-hackers] Documenting CDBS

[Jonas Smedegaard]

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?"

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

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?


  - Jonas

-- 
  * Jonas Smedegaard - idealist & Internet-arkitekt
  * Tlf.: +45 40843136  Website: http://dr.jones.dk/

  [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/build-common-hackers/attachments/20101225/1176bac4/attachment.pgp>