[Build-common-hackers] Documenting CDBS
Jonas Smedegaard
dr at jones.dk
Sun Dec 26 00:43:02 UTC 2010
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>
More information about the Build-common-hackers
mailing list