Обсуждение: Re: pg_dump new -n flag

> Did you update the man pages or docs?  I don't see the man page
> changed. Do you want me to do it?

Funny you should ask...

I'm just in the process of converting all of the "utilities" man pages
to sgml. For this release, we should keep the man pages as-is, but we
will have equivalent info in hardcopy and html.

So, I haven't updated the man page yet, but I'll do that. I did update
the usage printout from pg_dump itself.

And, can we be sure to update both sgml and man pages from here to
release to keep them in sync? I should be able to commit most sgml
sources for the utilities this evening; on my list of "must-haves" just
pg_dump, pg_dumpall, and vacuum are left to do.

btw, is "-n" an acceptable choice for the flag? I'd be happy with
anything, but decided that "-q" probably shouldn't be used since many
programs use it to mean "quiet". So -n for "No quotes" is what I chose
instead...

                     - Tom

> > Did you update the man pages or docs?  I don't see the man page
> > changed. Do you want me to do it?
>
> Funny you should ask...
>
> I'm just in the process of converting all of the "utilities" man pages
> to sgml. For this release, we should keep the man pages as-is, but we
> will have equivalent info in hardcopy and html.

Good.

> So, I haven't updated the man page yet, but I'll do that. I did update
> the usage printout from pg_dump itself.

I saw that.

> And, can we be sure to update both sgml and man pages from here to
> release to keep them in sync? I should be able to commit most sgml
> sources for the utilities this evening; on my list of "must-haves" just
> pg_dump, pg_dumpall, and vacuum are left to do.

Yes.  Good idea.  Just one question.  Are we sure we have all the man
page sync with the sgml?  I remember Tom Lane saying there was some
stuff missing from the sgml.


> btw, is "-n" an acceptable choice for the flag? I'd be happy with
> anything, but decided that "-q" probably shouldn't be used since many
> programs use it to mean "quiet". So -n for "No quotes" is what I chose
> instead...

Seems good.

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

> > And, can we be sure to update both sgml and man pages from here to
> > release to keep them in sync?
> Yes.  Good idea.  Just one question.  Are we sure we have all the man
> page sync with the sgml?  I remember Tom Lane saying there was some
> stuff missing from the sgml.

I just committed a bunch of new sgml sources covering the essential
utilities. They are based on the equivalent man pages, so we should try
to keep them in sync until after the upcoming release.

I think that Tom Lane is working on the sgml docs right now, and I saw a
commit of at least one already. I'll go ahead and remove one or two more
of the man page docs which are obsolete.

I still have to consolidate or write new info for the SERIAL, INT8, and
CIDR data types (I've got Tom H's info on CIDR, but expect to have to
move things around a bit).

btw, I'm thinking of changing the src/ and doc/ Makefiles to have the
man pages installed from the doc directory, not the src directory. So,
one would get the man pages installed by doing

  % cd doc
  % make install

rather than having them installed every time you install a new
executable, as currently happens. I won't move the location of the man
sources, just change the makefiles.

Comments?

                      - Tom

Bruce Momjian <maillist@candle.pha.pa.us> writes:
> I remember Tom Lane saying there was some
> stuff missing from the sgml.

Last night I committed a ton of revisions to libpq.sgml; it's in good
shape now (except possibly for some bugs in sgml markup, which I don't
have an easy way to check here).  I still need to work on libpgtcl.sgml.

I've recommended to Tom Lockhart that we drop libpq.3 (for now), because
I don't want to transpose the results of that mammoth editing session
back into nroff format.  Eventually it ought to be possible to generate
man format from the sgml, if you prefer man pages.

            regards, tom lane

"Thomas G. Lockhart" <lockhart@alumni.caltech.edu> writes:
> btw, I'm thinking of changing the src/ and doc/ Makefiles to have the
> man pages installed from the doc directory, not the src directory. So,
> one would get the man pages installed by doing
>   % cd doc
>   % make install
> rather than having them installed every time you install a new
> executable, as currently happens.

That sounds good...

> I won't move the location of the man
> sources, just change the makefiles.

... but as long as the man pages live under src/man, I think they ought
to be installed by the src makefile.  Cross-subtree installs are confusing.
I'd vote for going all the way and moving the src/man subdirectory into
the doc tree.

            regards, tom lane

> > I won't move the location of the man
> > sources, just change the makefiles.
> ... but as long as the man pages live under src/man, I think they
> ought to be installed by the src makefile.  Cross-subtree installs are
> confusing.
> I'd vote for going all the way and moving the src/man subdirectory
> into the doc tree.

I agree, but would like to keep it this way for this release for three
reasons:

1) the src/ makefile is actually doing the install. So from src/ you can
do a

  make install-man

but it is no longer part of "src/make install". The doc/ makefile simply
does the above make.

2) moving the files will (unfortunately) eliminate the cvs log
information (unless I do bad stuff with the RCS tree behind cvs, and I'm
not touching that :)

3) the next release should have man pages derived from sgml so it won't
be an issue.

                  - Tom