Wiki-like markup for Guide

[C. Florian Ebeling]

On Tue, Jan 13, 2009 at 1:41 AM, Ryan Schmidt <ryandesign at macports.org> wrote:
> On Jan 12, 2009, at 07:15, MacPorts wrote:
>
>> + 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.

Florian

-- 
Florian Ebeling
Twitter: febeling
florian.ebeling at gmail.com