[Build-common-hackers] Documenting CDBS

[Jonas Smedegaard]

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?

Then after it is merged, I will try convert to Markdown.  Unless Marc or 
anyone else chimes in recommending against before we reach that far.


Thanks for your help so far,

 - 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/20101226/c4319a81/attachment-0001.pgp>