> Do we have to sgml everything? Perhaps we can add an sgml mode to
> psql like the html mode we have?
No, we don't have to sgml everything. But, it makes the difference
between flat text files and true documentation. Not everyone wants to
bother writing it, but it really makes the difference between hacker
code and a usable system imho.
> I think some things that are referenced only occasionally or on screen
> are better left as flat text files. Why not just let them pull it up
> with more or vi?
That is possible. But why are fundamental things like installation
instructions or release notes better left as flat files? Can't quite see
why a user would think so. We can choose what docs we write and maintain
for the system, and we can choose how we make them look. It maybe isn't
too suprising how little interest people have in writing documentation,
but I'm the wrong person to ask whether sgml is the right way to go.
I'm currently listing 326 source and product files of documentation
resources in the Postgres system (a few files are obsolete with
conversion to sgml). This does not including html output files. There
are 50 README files. There are over 88 man pages. These are all
unstructured docs, with no clear organization. How should someone
remember which README to look in? Or what man page to try?? It's a
volume of information which needs organizing and structuring into a
predictable presentation for a user. I'm using as my model for
documentation those I've found useful over the years. None of them
struck me as something better left as a flat text file.
Anyway, that's my $0.02...
- Tom
