[Firebird-docs] Documentation Source Format

[Andy C. <an...@ad...>]

Here's what I see so far:

1. A page available on the world wide web which is the top of a tree; =
the tree functions as a "User's Manual" for Firebird. Anyone on the =
World Wide Web can read the tree.

2. Any reader can obtain the source for one of the pages on that tree. =
If the master source is HTML, then the page itself is the master source. =
If the master source is something else, then we'll need a link to obtain =
the source.

3. Any reader can then update the material of that page and submit it. =
Certain trusted people can put it directly in the CVS tree; general =
population will have to e-mail it to a reviewer who will confirm and =
check it in.

4. According to one poster, checking in something in the CVS tree can =
automatically update the documentation tree web site.

I did not originally envision using CVS simply because I'm not familiar =
with it, but I can imagine how it helps to be able to track back what =
changes were made when and by whom. It is not clear whether step [2] =
needs to include some kind of "Check out" operation.

I am leery of the master source being in some format other than HTML. =
HTML can be viewed by anyone on any computer using any browser. HTML can =
be edited by anyone on any computer using any ASCII text editor such as =
Notepad or VI. I certainly want readers to be able to make contributions =
without having to install special software on their machines.=20

One distinction is that I don't see this as the production of a few =
documentation writers. I see this as the organized knowledge of the =
Firebird community. The more pretty we want the output, the fewer people =
we can get to contribute.

One note: when you make your suggestions, please remember that I am 12 =
time zones from New York City. I am out of touch, somewhat out of date, =
and have no access to any UNIX computer. Someone suggesting using =
DocBook(x) xml format; please give me a link where I can learn about =
this. Thanks.