Re: Need help with SGML again - Mailing list pgsql-docs

Josh Berkus writes:

> 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.

Even in HTML, I don't think that direct links are a good idea.  If you
click on foo.html#bar, does the browser display a red arrow showing the
user what the setter of the link wanted you to read?  No, it just displays
the page near the anchor, and the user is going to have to scroll and
search anyway.  So if you link to the nearest containing section, I think
it's going to be just as good and doesn't make presumptions about the
output mode mechanics.

> The way I see it, lack of linking leaves me with 3 choices:

I really don't know what you're writing, so I can't give you an answer to
this.

> Something I could edit WYSWYG comes to mind,

There are tools for DocBook that do that.  I've never felt the urge to
find out more about them, but you should be able to find information about
them on the docbook-tools list.

> or at least standard enough DocBook that I could use OpenOffice.org on
> it.

DocBook is a standard and our DocBook follows that standard.  What degree
of standard do you need for your tool?

> 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.

It's not like we're some elite crowd that shuns WYSIWYG for the fun of it.
Whereever you look, people use DocBook.  FreeBSD, KDE, Gnome, Debian, even
the FSF is slowly migrating from Texinfo to DocBook, and every other
random project I see on the net that has some documentation has quite
obviously produced it using DocBook.  Sun and other commercial entities
use it.  Publishers like O'Reilly accept books written in it.  People,
including myself, produce websites, articles, and presentations with it
and take advantage of the common environment.

WYSIWYG is not a good idea for producing large, quality documentation.
That has been known at least since LaTeX, and the W3C preaches it every
day.  When people do WYSIWYG, they start looking for eye candy and don't
concentrate on producing quality content.  The result of that is the web
today: most of what is written in HTML is completely unmaintainable,
unprocessable by anything except possibly the human eye.

--
Peter Eisentraut   peter_e@gmx.net