Thread: 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

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

OK.  I recommend you just grab the TODO and FAQ from the web site,
unless you want HTML versions of them in the distribution along with the
ASCII verions.

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

> > > 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.
>
> OK.  I recommend you just grab the TODO and FAQ from the web site,
> unless you want HTML versions of them in the distribution along with the
> ASCII verions.

Assuming we aren't doing this until post-v6.3 release, will let you know when we are
ready to start the conversion. Need to draw a line at how much can go into v6.3, and I
think we are past it wrt the docs except for perhaps goof-up fixes of the packages.

My first project after v6.3 will be getting jade/DocBook going on postgresql.org (perhaps
it already is; Marc pointed me at something which looked like a jade package). Then, we
can demonstrate how to run it on that machine, and perhaps tie it in to an automatic html
documentation update from cron or from cvs. Also, I'm hoping to be busy answering
questions and helping all those new documenters out there :)

                                                 - Tom

On Sun, 1 Mar 1998, Thomas G. Lockhart wrote:

>
> My first project after v6.3 will be getting jade/DocBook going on
> postgresql.org (perhaps it already is; Marc pointed me at something
> which looked like a jade package). Then, we can demonstrate how to run
> it on that machine, and perhaps tie it in to an automatic html
> documentation update from cron or from cvs. Also, I'm hoping to be busy
> answering questions and helping all those new documenters out there :)

    jade was installed ~Jan 13th :)  Of course, it hasn't been tested
yet, but let me know if there are any problems :)

Marc G. Fournier
Systems Administrator @ hub.org
primary: scrappy@hub.org           secondary: scrappy@{freebsd|postgresql}.org

>         jade was installed ~Jan 13th :)  Of course, it hasn't been tested
> yet, but let me know if there are any problems :)

OK, jade is there, but I need the DocBook DTD integrated into jade's catalog:

> gmake admin.tar.gz
gmake -C sgml clean
gmake[1]: Entering directory `/home/users/t/thomas/pgsql/doc/src/sgml'
(rm -rf *.html *.htm)
gmake[1]: Leaving directory `/home/users/t/thomas/pgsql/doc/src/sgml'
gmake -C sgml admin.html
gmake[1]: Entering directory `/home/users/t/thomas/pgsql/doc/src/sgml'
(rm -rf *.htm)
jade  -D sgml -d /home/users/t/thomas/db107.d/docbook/html/docbook.dsl -t sgml
admin.sgml
jade:admin.sgml:8:59:W: cannot generate system identifier for public text
"-//Davenport//DTD DocBook V3.0//EN"
jade:admin.sgml:19:0:E: reference to entity "BOOK" for which no system identifier
could be generated
jade:admin.sgml:8:0: entity was defined here
jade:admin.sgml:19:0:E: DTD did not contain element declaration for document type
name
jade:admin.sgml:21:5:E: element "BOOK" undefined
jade:admin.sgml:25:6:E: element "TITLE" undefined
...

I had given you a reference for the source packages for my installation; do you
need that again? I think, as a first step, we just need the catalog stuff
updated.

                                                        - Tom