Wiki-like markup for Guide

[markd at macports.org]

>>> + 1. make guide use a reasonable (wiki-like) markup, not docbook-xml.
>>
>> I think we like our docbook-xml Guide... a lot of work was put into
>getting
>> it the way it is. What objections do you have to the way it's being done
>> now? Let's discuss.
>
>I dislike editing XML, because it is so quirky. And I dislike docbook-xml
>because it has this vast vocabulary, which few poeple really use. Only a
>very
>small subset of it is used in the guide. And this makes it hard for
>new or occasional
>contributers (like me) to help. I think there are solutions out there
>that don't force
>me to think about online and offline document type definitions,
>well-formedness
>of ampersands, and if I can nest a certain element at this tree position.
>I find thinking of a text as a tree quite unnatural. Why not keep it as
>a stream of characters? But xml forces one to look at it as a tree.
>
>Mark once kindly offered me to accept text changes and make the actual
>editing.
>That's very generous. I'm sure he offers that to everyone else as well.
>But that still feels a bit indirect, and I don't really want to bother
>somebody else
>with a small change. I guess others are reluctant to do so as well. Still
>the
>many but small changes are the important asset in any open source project,
>and they are the means to get tedious work like documentation done.
>
>So a simple and straightforward, maybe even well-known markup as wikis
>tend to use them might help. I know about all the semantics and the
>structure
>arguments, and that the rendering is a separate matter. But
>documenting should not become
>harder than just writing an understandable text, which is hard enough
>in it's own right.
>
>So, these are my points against docbook. OTOH, if the majority is happy
>with
>the current setup, then let's leave it as it is, by all means. But if
>not, then
>such a change might help to get more contributions here, and thereby more
>current documentation.

There are several issues that I think have made wikis not sufficiently
attractive for us.

1) Editorial control - It isn't practical for many people to make major
edits.  It can fragment the docs so they lose overall coherence.  However,
one of my goals for the new guide was that incremental changes were easy
to make and I think we have had some great commits of additional reference
material by our base coders and I thought that was great.

2) Single source - We want to source the man pages out of the guide and
we're really only a few days of hard work from that, despite the fact that
not a lot of documentation work has happened in the past year.  Using a
single source is the only way to have accurate docs and guide, which will
eliminate a lot of work and the innaccuracy that has plagued the docs in
the past.

I think docbook works well considering the overall goals we have.  And i
think the goals will make for better and more accurate docs.  The single
source issue is huge -no way for us to have separate man and guide docs
that are accurate otherwise.  And I don't think we can do that without
xml.  Also, I use a wysiwyg editor so I do very little xml coding
directly.  And I'm open to any method of contribution.  Using Trac leaves
something to be desired.  Maybe a wiki scratchpad of some sort would be
better.  And at least by summer's end I intend to have the missing parts
of the guide filled in and make a transition to the single source man
pages with Simon's help.

I understand your frustrations though, so I'm not sure how satisfying
these answers will be.  But I hope that helps.

Mark