Обсуждение: So what is the current documentation status?
I need to make some more updates to the libpq documentation, and I'm
confused (again) about whether to work on libpq.sgml or libpq.3.
The last I heard libpq.3 was the primary doco, but I find that
yesterday someone stuck this notice on it:
: Current documentation for this topic is available in the new
: Programmer's Guide chapter on libpq. This man page is obsolete, though
: in sync with the Programmer's Guide as of 1998/08/15.
which I'd be willing to believe if it weren't an evident falsehood
(the files are NOT in sync). Do I have to do the syncing? Or should
I just wait for the docs crew to do whatever they're planning to do?
regards, tom lane
> I need to make some more updates to the libpq documentation, and I'm
> confused (again) about whether to work on libpq.sgml or libpq.3.
> The last I heard libpq.3 was the primary doco, but I find that
> yesterday someone stuck this notice on it:
>
> : Current documentation for this topic is available in the new
> : Programmer's Guide chapter on libpq. This man page is obsolete,
> : though in sync with the Programmer's Guide as of 1998/08/15.
>
> which I'd be willing to believe if it weren't an evident falsehood
> (the files are NOT in sync). Do I have to do the syncing? Or should
> I just wait for the docs crew to do whatever they're planning to do?
The "doc's crew" is me, at least for this stuff :/
I put the note in, since Bruce pointed out that it is difficult to tell
which versions of which docs should be maintained. I've also put a
_complete_ list of all documentation resources into docguide.sgml, with
notes for some of the files on the current status or future prospects. I
hope that this helps the developers get on the same page with the
direction the docs are going. Unfortunately, most developers don't
actually read the docs, and it wouldn't help here anyway especially
since recent changes aren't formatted for use yet (see below) :)
How are the docs (sources) not in sync? I found some words on
PQsetNoticeProcessor() in libpq.3 which were not in an earlier version,
and moved those into libpq.sgml. I recall you (or someone else?)
submitting some previous docs patches which covered both versions. Let
me know the scope of the problem and we can work out the best way to
remerge.
I'm planning on updating the web page with new, intermediate versions of
the sgml/html docs, both online and in tar files. That way people can
see the results of contributions.
Now, there *is* the issue of whether libpq.3 is appropriate for a man
page. I believe it is not, since there is *so* much information needed
to understand and since man pages have such a flat structure. Other
interface libraries do not have man pages at all, for Postgres and for
my system in general. At the moment, the man page comes out to 22 pages
of info on my machine.
The man pages which are not candidates for v6.4 replacement are those
for SQL commands and for programs. The pages for SQL commands are
partially replaced by Jose's and Oliver's sgml reference pages, but
there is some info in the man pages which needs to move to the User's
Guide for "how-to" reading. Don't know if we'll get to this for v6.4. If
not then, that leaves something for me to do on v6.5...
Let me know how this sounds and what would be easiest for you. I'll see
if I can get enough finished on the web site pages to update them with
new info today.
- Tom
"Thomas G. Lockhart" <lockhart@alumni.caltech.edu> writes:
> How are the docs (sources) not in sync? I found some words on
> PQsetNoticeProcessor() in libpq.3 which were not in an earlier version,
> and moved those into libpq.sgml.
There's bits and pieces in each file that are not in the other one ---
I'm afraid there's no substitute for going through both files manually
to bring libpq.sgml fully up to speed. I'm willing to do that; I was
just waiting until things had reached the point where everybody agrees
that the .sgml version is the one that will be maintained. The last
time I asked about this, I was told (by Bruce? I forget) that the man
page version was still the one to maintain. I'm not willing to do that
comparison more than once, so I left well enough alone for a while.
> Now, there *is* the issue of whether libpq.3 is appropriate for a man
> page. I believe it is not, since there is *so* much information needed
> to understand and since man pages have such a flat structure.
I concur; the libpq doco is unwieldy for a man page. I don't have any
problem with dropping the man page --- I'm just waiting for the
merry-go-round to come to a stop.
> Let me know how this sounds and what would be easiest for you. I'll see
> if I can get enough finished on the web site pages to update them with
> new info today.
If anyone has any un-checked-in changes for either libpq.3 or
libpq.sgml, please check them in soon or at least let me know about
them. I'll try to get to the documentation update work in a few days.
regards, tom lane
> There's bits and pieces in each file that are not in the other one ---
> I'm afraid there's no substitute for going through both files manually
> to bring libpq.sgml fully up to speed. I'm willing to do that...
Thanks. At your convenience, and I'll regenerate snapshot output.
> I concur; the libpq doco is unwieldy for a man page. I don't have any
> problem with dropping the man page --- I'm just waiting for the
> merry-go-round to come to a stop.
OK, it is stopped, at least for libpq. Thanks for supporting this; the
new docs really look nice and the html and hardcopy output seems to be a
good way to present information.
There is now a list of all docs sources, with suggestions for some on
whether they are current, obsolete, or in need of replacement. The list
is in the Documentation appendix in either the integrated document
(postgres.tar.gz) or the Programmer's Guide (programmer.tar.gz).
>
> > I'll see if I can get enough finished on the web site pages to
> > update them with new info today.
The web page is now updated, and I've put full copies of several html
documents in ftp://postgresql.org/pub/patches/*.tar.gz, which is pointed
to by the web page.
> If anyone has any un-checked-in changes for either libpq.3 or
> libpq.sgml, please check them in soon or at least let me know about
> them. I'll try to get to the documentation update work in a few days.
Sorry things got out of sync. I'll try to be more active in coordinating
things. Please make suggestions on what you would find useful (got to
keep those docs writers happy! :)
- Thomas
> The "doc's crew" is me, at least for this stuff :/ > > I put the note in, since Bruce pointed out that it is difficult to tell > which versions of which docs should be maintained. I've also put a > _complete_ list of all documentation resources into docguide.sgml, with > notes for some of the files on the current status or future prospects. I > hope that this helps the developers get on the same page with the > direction the docs are going. Unfortunately, most developers don't > actually read the docs, and it wouldn't help here anyway especially > since recent changes aren't formatted for use yet (see below) :) > > How are the docs (sources) not in sync? I found some words on > PQsetNoticeProcessor() in libpq.3 which were not in an earlier version, > and moved those into libpq.sgml. I recall you (or someone else?) > submitting some previous docs patches which covered both versions. Let > me know the scope of the problem and we can work out the best way to > remerge. You have to do a cvs diff for the file from the time you created libpq.sgml to current. You will see lots of things. > > I'm planning on updating the web page with new, intermediate versions of > the sgml/html docs, both online and in tar files. That way people can > see the results of contributions. > > Now, there *is* the issue of whether libpq.3 is appropriate for a man > page. I believe it is not, since there is *so* much information needed > to understand and since man pages have such a flat structure. Other > interface libraries do not have man pages at all, for Postgres and for > my system in general. At the moment, the man page comes out to 22 pages > of info on my I really like libpq.3 as a manual page. I use it for quick reference. I have printf as a manual pages, and that is a library function. How is libpq.3 different? Perhaps we could remove the examples, but that is really not going to save us much. > The man pages which are not candidates for v6.4 replacement are those > for SQL commands and for programs. The pages for SQL commands are > partially replaced by Jose's and Oliver's sgml reference pages, but > there is some info in the man pages which needs to move to the User's > Guide for "how-to" reading. Don't know if we'll get to this for v6.4. If > not then, that leaves something for me to do on v6.5... > > Let me know how this sounds and what would be easiest for you. I'll see > if I can get enough finished on the web site pages to update them with > new info today. -- 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)
> "Thomas G. Lockhart" <lockhart@alumni.caltech.edu> writes: > > How are the docs (sources) not in sync? I found some words on > > PQsetNoticeProcessor() in libpq.3 which were not in an earlier version, > > and moved those into libpq.sgml. > > There's bits and pieces in each file that are not in the other one --- > I'm afraid there's no substitute for going through both files manually > to bring libpq.sgml fully up to speed. I'm willing to do that; I was > just waiting until things had reached the point where everybody agrees > that the .sgml version is the one that will be maintained. The last > time I asked about this, I was told (by Bruce? I forget) that the man > page version was still the one to maintain. I'm not willing to do that > comparison more than once, so I left well enough alone for a while. > > > Now, there *is* the issue of whether libpq.3 is appropriate for a man > > page. I believe it is not, since there is *so* much information needed > > to understand and since man pages have such a flat structure. > > I concur; the libpq doco is unwieldy for a man page. I don't have any > problem with dropping the man page --- I'm just waiting for the > merry-go-round to come to a stop. > > > Let me know how this sounds and what would be easiest for you. I'll see > > if I can get enough finished on the web site pages to update them with > > new info today. > > If anyone has any un-checked-in changes for either libpq.3 or > libpq.sgml, please check them in soon or at least let me know about > them. I'll try to get to the documentation update work in a few days. Go for it. I can easily generate the cvs diff file which make things very easy. -- 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 really like libpq.3 as a manual page. I use it for quick reference.
> I have printf as a manual pages, and that is a library function.
> How is libpq.3 different?
printf == single function
libpq == entire library of functions
It should be noted that many people have trouble giving up man pages.
But we have limited resources for documentation, and man pages clearly
fall at the bottom of the list in usefulness and viability (at least for
things like full library interfaces). We should choose the most
appropriate format for each of our documentation resources, at least
until we have the documentation under control.
There is someone working on a man page output from the sgml, and if that
comes through then this is pretty much a moot point.
btw, had a chance to look at the new reference pages? They are near the
end of the User's Guide on the web site and in /pub/patches on the ftp
site.
- Tom
> > I really like libpq.3 as a manual page. I use it for quick reference. > > I have printf as a manual pages, and that is a library function. > > How is libpq.3 different? > > printf == single function > libpq == entire library of functions > > It should be noted that many people have trouble giving up man pages. > But we have limited resources for documentation, and man pages clearly > fall at the bottom of the list in usefulness and viability (at least for > things like full library interfaces). We should choose the most > appropriate format for each of our documentation resources, at least > until we have the documentation under control. OK, I am happy if you can output html to use that, or convert it myself to man pages from that. Why not? > > There is someone working on a man page output from the sgml, and if that > comes through then this is pretty much a moot point. > > btw, had a chance to look at the new reference pages? They are near the > end of the User's Guide on the web site and in /pub/patches on the ftp > site. No, but I need to look up the access method stuff, and was really useful. However, the class diagram was unreadable, and I see that converting it to gif with any normal resolution may be too large. Maybe someone could do a rewrite in xfig? I have added the old catalog.gif to the distribution so we can use that if we need to. I am burried in a patch that is already 12k lines of diff, and I haven't even started testing the regression tests or reviewing the diff. -- 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)
"Thomas G. Lockhart" <lockhart@alumni.caltech.edu> writes:
> There is someone working on a man page output from the sgml, and if that
> comes through then this is pretty much a moot point.
Right, that's the ultimate solution for not having to maintain two sets
of doc files. I was kinda hoping that that would happen for 6.4,
actually. Any estimate how soon that will be possible?
regards, tom lane