Re: Need help with SGML again

Peter,

> You should consider the documentation like a book. That has two
> consequences:
>
> 1. Linking to anything that is not a formal object (having a title and a
> number) does not render well in print. ("for more information, see
> paragraph 3 on page 15"?)

I see what you mean. Given that I do 95% of my doc browsing in HTML, this
seems very redundant to me, though; I think it would be interesting to see
how many users refer to a paper version of the docs. We may find it's a tiny
minority.

I'm also annoyed that I found out that the doc strucutre I wanted to use was
not permitted only after I typed & marked it, but that's hardly your fault.

The way I see it, lack of linking leaves me with 3 choices:
1) Leave things the way they are, which will force new DBAs to scroll/click
through runtime.sgml looking for the terms I've defined.

2) Create a seperate page/section giving just the basic settings and move the
tuning information for the 10 settings I've augmennted to that document,
making things more convenient for new DBAs but annoying experienced ones who
need to swtich between the new page and the main GUC listing.

3) Copy the information to *both* places, adding repeated text to
runtime.sgml, and the possibility of the two versions of each text getting
out of synch.

I'm leaning toward (2). Thoughts?

> > Any thoughts on replacing Docbook with something else, someday?
>
> I don't see anything better arising.

Something I could edit WYSWYG comes to mind, or at least standard enough
DocBook that I could use OpenOffice.org on it.

I'm serious about this. Documentation writing, like advocacy, is a great task
for people who want to contribute to the project but don't have the coding
skills. Currently, it's very difficult to involve any of those people in
adding to the docs becuase they have to learn an arcane markup format first,
for which there are no good tools on Windows.

If we could move the docs to a format supported by a multi-platform WYSWYG
editor, I'd bet you dinner that we could get at least 4 more regular
documentation contributors, if not a dozen.

--
Josh Berkus
Aglio Database Solutions
San Francisco