Re: [HACKERS] Open 6.4 items - Mailing list pgsql-hackers

> > 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 am concerned about people installing on systems that don't have
graphic monitors or can print postscript.  What do we tell them?

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

OK.  As long as we can generate flat too for those that can't use fancy
stuff.  Certainly it is better than flat files if both are available for
novices trying to get started.

I agree we have TONS of stuff that needs serious organization.  But I
also like to have the stuff availble in quick format like man pages and
ascii files that I can grep and pull up quickly.

psql has the \h help command because it gives people information in a
handy way.  Man pages are the same.  'more INSTALL' may be the same?

Right now, we have great docs that someone can sit down and read as a
book, chapter by chapter.  For people who are in the middle of
something, psql \h or man or 'more INSTALL' may be easier, and no one is
really going to sit down and study those, I think.  Maybe I am wrong.

--
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.us              |  Drexel Hill, Pennsylvania 19026
  +  If your life is a hard drive,     |  (610) 353-9879(w)
  +  Christ can be your backup.        |  (610) 853-3000(h)