Wiki-like markup for Guide

[William Siegrist]

On Jan 14, 2009, at 9:18 AM, C. Florian Ebeling wrote:

> On Wed, Jan 14, 2009 at 6:01 PM,  <markd at macports.org> wrote:
>>>> There are several issues that I think have made wikis not  
>>>> sufficiently
>>>> attractive for us.
>>>
>>> Ok, I guess I didn't make my intent clear enough. My suggestion is  
>>> not
>>> to use a wiki as documentation. I think we have that already,  
>>> that's fine,
>>> and it serves a different need.
>>>
>>> My suggestion is about using a different format: instead of an  
>>> complicated
>>> XML vocabulary a lightweight markup language [1]. I think Textile  
>>> and
>>> Markdown
>>> are the most commonly used ones. Those are best known as the raw  
>>> format of
>>> wikis, that's why I called it wiki-like. That way the documentation
>>> would still be in
>>> a single place in the svn. I find that an important property as  
>>> well.
>>> But it does
>>> not necessitate use of xml.
>>
>> But there is more to it than having it in a single place.  It must  
>> have
>> enough of a data structure to support what we're doing.  There is a
>> current toolchain to get us from XML DocBook to man pages  
>> automatically.
>> I think we'd end up rolling our own toolchain to accomplish the  
>> same thing
>> with markdown.  Simon could give a better answer because he's been  
>> doing
>> the scripting work, but I suspect there would be new challenges with
>> something like markdown to man pages.
>>
>> And I think the more complex structured environment of DocBook has  
>> been a
>> benefit.  I realize that markdown (and other ones) support a  
>> structure as
>> well, but we'd I think we'd have to come up with a fairly complex  
>> style
>> guide for its use to support a consistent style to get the  
>> functionality
>> we now have.  In other words, we'd end up creating a DTD, which is  
>> what
>> DocBook is.  So my opinion is that it would take a lot of work to  
>> get the
>> functionality we now have, and we'd likely not do a good enough job  
>> with a
>> DTD to have as consistent a style as we have now.
>
> Ok, then let's just keep docbook. I thought other might consider it  
> combersome
> as well, but if that's not the case, then so be it :)
>
> Those who'd better like something else still can alleviate their pain
> with Pandoc:
> http://johnmacfarlane.net/pandoc/try
>

So you dont feel like you're the only one... :) It is definitely  
cumbersome to edit manually. The few times I've had to touch the guide  
I did it with vi. So I agree on that point, but also agree that the  
structure gives a lot of benefits. The bottom line is if you're going  
to spend any significant time on the guide, find a gui or other tool  
to do the xml for you.

-Bill

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2421 bytes
Desc: not available
URL: <http://lists.macosforge.org/pipermail/macports-dev/attachments/20090114/7d20f0cd/attachment.bin>