Re: [HACKERS] Re: [QUESTIONS] varchar vs text

> I had a chance to look at the users and programmers manuals you just
> installed. Very nice. Lots of new stuff and cleanup, and you
> integrated much of the separate documentation in one place. I have
> added a mention of it in my release summary.
>
> I can easily send you html of what I am doing. The FAQ is already html,
> and the TODO list is ascii, but converted using txt2html from
> http://www.cs.wustl.edu/~seth/txt2html/. Works really well. It
> recoginizes certain text formatting styles, and outputs HTML to make it
> look correct on a web page. Perhaps we could use that to convert over
> some of the ASCII-only stuff we have.

Yes, that would help, and then I can run a brute-force filter to convert the html to
almost-DocBook sgml. From there on we can turn it around and generate html from the
DocBook sources, for posting on the web page etc.

> Seems it may be nice to have all the docs in the separate directories
> all in html, and have 'make' grab them and convert them into the manual.
> I really don't know what is involved, or whether you can just grab html
> and place it into sgml documents, but it is an idea. Actually, the
> doc/src/*.sgml files look pretty easy to understand, so maybe we all
> need to learn it.

Well, it works _almost_ like this. Without getting caught up in the fact that html
_is_ sgml, just not sufficient to fully specify document content, the document
source would all be in DocBook sgml, then converted to html, hardcopy, ascii, and
man pages from there.

DocBook has a learning curve when starting from scratch, but I've put in the 100
hours to get over that hump. From here on, the docs can evolve from existing
documents, and stealing formatting specs from those will make a new doc easy to
write.

For each of the current plain text, man page, or html _source_ docs we will need to
get the maintainer to agree to try using sgml for that. I'll do, or assist with, the
conversion to sgml and from then on the maintainer would make maintenance changes to
the sgml source. I figured we can tackle that one at a time over the next couple of
months.

> I guess the manual is so nice, I want to make sure it can stay
> up-to-date without much effort on your part. I am sure you have already
> thought of that.

Well, that is the advantage to using sgml, as long as others are willing to maintain
information in that format. I'll stress that _new_ information can be written
without sgml in plain text and someone can then help convert it. From then on, it
would be easiest if it were maintained from the sgml sources.

> You have certainly jump-started our documentation, and now that it is so
> nice, I am sure people will start getting involved.

Thanks. I really hope so :)

Lots of open issues with content, presentation, etc. and as we discuss it on the
Docs list we can start a ToDo to keep track of where we are headed.

- Tom