Thread

TODO list

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-04T21:59:06Z

I have removed the CHANGES section from the bottom of the TODO list, and
installed the HISTORY file on the web site.

I had combined them because at one time I was e-mailing it to the list
as one file.  With web publication, there is no need to have them as one
file.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: [DOCS] TODO list

Hal Snyder <hal@enteract.com> — 1999-01-04T22:35:37Z

Bruce Momjian <maillist@candle.pha.pa.us> writes:

> I have removed the CHANGES section from the bottom of the TODO list, and
> installed the HISTORY file on the web site.
> 
> I had combined them because at one time I was e-mailing it to the list
> as one file.  With web publication, there is no need to have them as one
> file.

Bruce-

I've started keeping web pages for www.postgresql.org in CVS, module
"www", with submodules "www/html" and "www/cgi", etc. mirroring the
web site tree. Marc and I get email automatically on commits to
"www".

Not all files are in CVS yet - any time I touch a file on the site, I
put it under CVS if it's not already there. Sometime soon, all live
pages need to be committed.

At www/html, there's a script called push.sh (needs to be renamed and
moved) that will copy files from a local or remote CVS work area into
the production web site tree.

Can you start using CVS for web content? I don't want to step on any
of your edits!

Do you want to get email on commits to any parts of the web site?

Hal

Re: [DOCS] TODO list

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-04T23:15:35Z

> Bruce-
> 
> I've started keeping web pages for www.postgresql.org in CVS, module
> "www", with submodules "www/html" and "www/cgi", etc. mirroring the
> web site tree. Marc and I get email automatically on commits to
> "www".
> 
> Not all files are in CVS yet - any time I touch a file on the site, I
> put it under CVS if it's not already there. Sometime soon, all live
> pages need to be committed.
> 
> At www/html, there's a script called push.sh (needs to be renamed and
> moved) that will copy files from a local or remote CVS work area into
> the production web site tree.
> 
> Can you start using CVS for web content? I don't want to step on any
> of your edits!
> 
> Do you want to get email on commits to any parts of the web site?

Yes, I do want to get e-mail on commits.

OK, I see.  I will pull down the www cvs now, and make my changes there.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: [DOCS] TODO listt

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-04T23:58:31Z

> > Do you want to get email on commits to any parts of the web site?
> 
> Yes, I do want to get e-mail on commits.
> 
> OK, I see.  I will pull down the www cvs now, and make my changes there.

OK, changes made to index.html in the cvs tree, and put on the server
via ftp.  I don't have rsync here, so the push.sh did not work.

If we can just make the web directores rw for all postgres-group users,
that would make ftp easier.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: [DOCS] TODO list

Thomas Lockhart <lockhart@alumni.caltech.edu> — 1999-01-05T02:18:07Z

> > Can you start using CVS for web content? I don't want to step on any
> > of your edits!

If it's ok, I'd like to get the ToDo and release notes content into
sgml, and then have html generated automatically for the web site. Will
look at setting up my cvs checkout tree to generate new docs and allow
others (like Bruce) to do so on demand.

No point in putting these things into cvs in two places; we have this
content in sgml for previous releases already...

                       - Tom

Re: [DOCS] TODO list

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-05T03:27:41Z

> > > Can you start using CVS for web content? I don't want to step on any
> > > of your edits!
> 
> If it's ok, I'd like to get the ToDo and release notes content into
> sgml, and then have html generated automatically for the web site. Will
> look at setting up my cvs checkout tree to generate new docs and allow
> others (like Bruce) to do so on demand.

I thought the release notes were already sgml.  The TODO list is quite
fluid, and I can't really see how sgml'ing it is going to get us
anything.  I can already generate decent html automatically, and a quick
search/release or sed could convert those html tags to sgml, no?

I maintain it as an ASCII file, and having tags on every item is going
to be a pain.


> 
> No point in putting these things into cvs in two places; we have this
> content in sgml for previous releases already...

I don't see the TODO list in sgml anywhere.

What I could do is to keep maintaining it in ASCII, and generate html
and sgml from that ASCII file.  If you can mark up the todo list in
sgml, I will map the html tags to sgml, and auto-convert to html and
sgml when I change the file.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: [DOCS] TODO list

Thomas Lockhart <lockhart@alumni.caltech.edu> — 1999-01-05T03:43:53Z

> I don't see the TODO list in sgml anywhere.
> What I could do is to keep maintaining it in ASCII, and generate html
> and sgml from that ASCII file.  If you can mark up the todo list in
> sgml, I will map the html tags to sgml, and auto-convert to html and
> sgml when I change the file.

I must be confusing the ToDo list with the one-liner release notes,
which have a similar format? The info I'm looking for is the stuff in
current.sgml and release.sgml

                  - Tom

Re: [DOCS] TODO list

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-05T04:01:56Z

> > I don't see the TODO list in sgml anywhere.
> > What I could do is to keep maintaining it in ASCII, and generate html
> > and sgml from that ASCII file.  If you can mark up the todo list in
> > sgml, I will map the html tags to sgml, and auto-convert to html and
> > sgml when I change the file.
> 
> I must be confusing the ToDo list with the one-liner release notes,
> which have a similar format? The info I'm looking for is the stuff in
> current.sgml and release.sgml

Current.sgml is the list of changes that appear in the HISTORY file. 
They used to appear at the bottom of the TODO list, so it makes sense
you had them confused.  It is gone from the TODO as of today.

It is now only at the top of the HISTORY file.  You had a narrative at
the top to highlight the new items in current.sgml too.  Because people
are upgrading by often jumping several releases, from 6.3.1 to 6.4.2 for
example, giving a list of the new features JUST in the current release is
not really a good idea anymore.

Pointing them to the entire HISTORY file allows them to go backwards
until they hit the release they are currently running.

As I remember, you just include the HISTORY files's changes in the sgml
output, without any formatting, so it appears we don't have to make any
changes.  You just grab the current HISTORY contents when you package
the docs for the release.  Because the docs typically arn't updated
during minor releases, they should be looking at the HISTORY file
anyway.  In fact, that give a good argument not to include the HISTORY
file in the docs at all.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: [DOCS] TODO list

Thomas Lockhart <lockhart@alumni.caltech.edu> — 1999-01-05T06:01:15Z

> Current.sgml is the list of changes that appear in the HISTORY file.
> They used to appear at the bottom of the TODO list, so it makes sense
> you had them confused.  It is gone from the TODO as of today.
> It is now only at the top of the HISTORY file.  You had a narrative at
> the top to highlight the new items in current.sgml too.  Because 
> people are upgrading by often jumping several releases, from 6.3.1 to 
> 6.4.2 for example, giving a list of the new features JUST in the 
> current release is not really a good idea anymore.

?? current.sgml and release.sgml go together, and together have all of
the info in HISTORY, plus some notes on highlights. Please look at the
current html docs generated from the sgml sources to see how it is laid
out! I tried separating the most recent release info into current.sgml
hoping that you could work with it more easily :( The chapter of release
notes in the full docs has a section for every release we have had,
including a few paragraphs on highlights. We should have more imho.

> Pointing them to the entire HISTORY file allows them to go backwards
> until they hit the release they are currently running.
> As I remember, you just include the HISTORY files's changes in the 
> sgml output, without any formatting, so it appears we don't have to 
> make any changes.

This isn't by my choice. Since you maintain HISTORY as a flat file, and
update it very near to a release, that is the only way I can incorporate
info into the sgml-based docs.

> You just grab the current HISTORY contents when you package
> the docs for the release.  Because the docs typically arn't updated
> during minor releases, they should be looking at the HISTORY file
> anyway.  In fact, that give a good argument not to include the HISTORY
> file in the docs at all.

Ack! The docs (especially the html) can easily be updated for minor
releases if we choose to do so. I have been hoping that we could switch
to store this info in sgml at some point. I've had to write last minute
highlights for the last couple of releases which would be much better if
done earlier and brought along with the other info currently at the top
of HISTORY or in a new version of current.sgml.

An example of info which should end up in release.sgml/current.sgml is
the newly-revealed fact that v6.3 can not be dump/reloaded to v6.4.x,
but that v6.3.1 and v6.3.2 can. That will be useful information long
into the future, and can be presented from sgml-based docs more
effectively, with cross-references etc.

                       - Tom

Re: [DOCS] TODO list

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-05T18:46:52Z

> > Current.sgml is the list of changes that appear in the HISTORY file.
> > They used to appear at the bottom of the TODO list, so it makes sense
> > you had them confused.  It is gone from the TODO as of today.
> > It is now only at the top of the HISTORY file.  You had a narrative at
> > the top to highlight the new items in current.sgml too.  Because 
> > people are upgrading by often jumping several releases, from 6.3.1 to 
> > 6.4.2 for example, giving a list of the new features JUST in the 
> > current release is not really a good idea anymore.
> 
> ?? current.sgml and release.sgml go together, and together have all of
> the info in HISTORY, plus some notes on highlights. Please look at the
> current html docs generated from the sgml sources to see how it is laid
> out! I tried separating the most recent release info into current.sgml
> hoping that you could work with it more easily :( The chapter of release
> notes in the full docs has a section for every release we have had,
> including a few paragraphs on highlights. We should have more imho.

I think we should merge them into one file.

The big problem, which has existed since using sgml, is that I can't
generate the html and ASCII output I need when I change the sgml file.
This is also a problem with the man pages.

I can change to sgml, but I still need to generate an ASCII HISTORY file.

I looked at the html release output, and this really does look nice.

> 
> > Pointing them to the entire HISTORY file allows them to go backwards
> > until they hit the release they are currently running.
> > As I remember, you just include the HISTORY files's changes in the 
> > sgml output, without any formatting, so it appears we don't have to 
> > make any changes.
> 
> This isn't by my choice. Since you maintain HISTORY as a flat file, and
> update it very near to a release, that is the only way I can incorporate
> info into the sgml-based docs.

I have no way to generate the HISTORY file earlier in the release
process.  We are adding fixes up to the end.

> 
> > You just grab the current HISTORY contents when you package
> > the docs for the release.  Because the docs typically arn't updated
> > during minor releases, they should be looking at the HISTORY file
> > anyway.  In fact, that give a good argument not to include the HISTORY
> > file in the docs at all.
> 
> Ack! The docs (especially the html) can easily be updated for minor
> releases if we choose to do so. I have been hoping that we could switch
> to store this info in sgml at some point. I've had to write last minute
> highlights for the last couple of releases which would be much better if
> done earlier and brought along with the other info currently at the top
> of HISTORY or in a new version of current.sgml.
> 
> An example of info which should end up in release.sgml/current.sgml is
> the newly-revealed fact that v6.3 can not be dump/reloaded to v6.4.x,
> but that v6.3.1 and v6.3.2 can. That will be useful information long
> into the future, and can be presented from sgml-based docs more
> effectively, with cross-references etc.

Yep, but we need html/man/output from sgml.  Without this, we are going
to continue having problems.

Making changes in two places always causes problems.  I need a clear
description of what is sgml, and what gets generated from sgml, and
steps to do this, perhaps from the postgresql.org machine.

-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

Re: [DOCS] TODO list

Hal Snyder <hal@enteract.com> — 1999-01-05T19:14:20Z

I'm coming into this late, so pardon me if this has already been
mentioned.

At Vail we used linuxdoc and sgmlfmt to generate ASCII, Postscript,
HTML, and PDF from sgml source when documenting projects. The HTML was
on a an intranet server, and all the programmer had to do was "gmake
install" in the docs directory for a module and the online doc was
updated as well as printable manuals.

Bruce Momjian <maillist@candle.pha.pa.us> writes:
...
> I can change to sgml, but I still need to generate an ASCII HISTORY file.
> 
> I looked at the html release output, and this really does look nice.
...

Re: [DOCS] TODO list

Thomas Lockhart <lockhart@alumni.caltech.edu> — 1999-01-06T15:05:00Z

> At Vail we used linuxdoc and sgmlfmt to generate ASCII, Postscript,
> HTML, and PDF from sgml source when documenting projects. The HTML was
> on a an intranet server, and all the programmer had to do was "gmake
> install" in the docs directory for a module and the online doc was
> updated as well as printable manuals.
> > I can change to sgml, but I still need to generate an ASCII HISTORY 
> > file.

For the last release I generated an ASCII version of the INSTALL file
from the sgml sources. It was easy, though not completely transparent; I
would generate RTF, import into Applix, do some minor formatting touchup
(this is optional), then save as a formatted ASCII file.

Brandon Ibach was interested in helping with the sgml->troff/man
conversion problem, and from what I gather from seeing his postings on
an sgml mailing list has been working extensively with the sgml toolset.
Don't know if he still has plans to look at the troff or plain text
output issue though.

Just yesterday I set up my hub.org account to generate the full html doc
set with a single command, and I believe that I have the group
permissions set so that Bruce or others could do the same in my
directory. Bruce and others could also generate any RTF files from my
cvs tree on hub.org, or copy my setup and do it in their own tree. I
need to touch up a couple of files to get the tutorial building again
(we didn't bother building a new one for v6.4) and will send more
detailed instructions soon.

Bruce, do you have an editor which can read RTF and output plain text?

btw, this brings up a question: if we generate snapshot docs on a, say,
daily basis and post them on the web site should that be in a different
place than where they are posted currently? There should probably be a
stable set of docs from the last release and then a different place for
docs related to the current development tree.

What do you think Hal? Where should development or snapshot docs go??

                   - Tom

Re: [DOCS] TODO list

Bruce Momjian <maillist@candle.pha.pa.us> — 1999-01-06T16:00:48Z

> Just yesterday I set up my hub.org account to generate the full html doc
> set with a single command, and I believe that I have the group
> permissions set so that Bruce or others could do the same in my
> directory. Bruce and others could also generate any RTF files from my
> cvs tree on hub.org, or copy my setup and do it in their own tree. I
> need to touch up a couple of files to get the tutorial building again
> (we didn't bother building a new one for v6.4) and will send more
> detailed instructions soon.
> 
> Bruce, do you have an editor which can read RTF and output plain text?

No.  I have lyx, but that's about it.  I just installed that last week.

That is one thing that bugged my about latex/lyx too.  The dump to ASCII
was very poor compared to troff.


-- 
  Bruce Momjian                        |  http://www.op.net/~candle
  maillist@candle.pha.pa.us            |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026