Thread
-
Re: [HACKERS] Re: [QUESTIONS] varchar vs text
Thomas Lockhart <lockhart@alumni.caltech.edu> — 1998-03-01T22:55:11Z
> 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 -
Re: [HACKERS] Re: [QUESTIONS] varchar vs text
Bruce Momjian <maillist@candle.pha.pa.us> — 1998-03-01T23:09:18Z
> > > 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)
-
Re: [DOCS] Re: [HACKERS] Re: [QUESTIONS] varchar vs text
Thomas Lockhart <lockhart@alumni.caltech.edu> — 1998-03-01T23:50:19Z
> > > 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 -
Re: [DOCS] Re: [HACKERS] Re: [QUESTIONS] varchar vs text
Marc Fournier <scrappy@hub.org> — 1998-03-02T01:22:42Z
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 -
Re: [DOCS] Re: [HACKERS] Re: [QUESTIONS] varchar vs text
Thomas Lockhart <lockhart@alumni.caltech.edu> — 1998-03-02T01:54:24Z
> 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