sgml cleanup
Hi all,
In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
empty closing tags when I ran
sh$ nsgmls -s -wall ./book-decl.sgml ./reference.sgml
from doc/src/sgml. I know little about docbook, so I fixed the
tags to see if that would fix my problems in making man.tar, but
I still haven't gotten the man.tar to make properly :-( I have a
patch against head to fix the empty tags, but it is quite large and
touches a /lot/ of files (listed below). If this is a real problem,
let me know, and I'll send the patch to -patches (the gzipped patch
is about 17k).
I also have modifications to config/docbook.m4 and doc/src/Makefile.in
to allow docs to (almost) build on my debian box. The last outstanding
problem is that the names of the generated man pages have whitespace
between the program name and the appended ".1"...
brent$ tar tvf man.tar
drwxr-sr-x brent/brent 0 2001-11-21 21:16:24 man1/
-rw-r--r-- brent/brent 3797 2001-11-21 21:16:21 man1/createdb.1
-rw-r--r-- brent/brent 3041 2001-11-21 21:16:21 man1/createlang.1
-rw-r--r-- brent/brent 3748 2001-11-21 21:16:21 man1/createuser.1
-rw-r--r-- brent/brent 2821 2001-11-21 21:16:21 man1/dropdb.1
-rw-r--r-- brent/brent 2573 2001-11-21 21:16:22 man1/droplang.1
-rw-r--r-- brent/brent 2887 2001-11-21 21:16:22 man1/dropuser.1
-rw-r--r-- brent/brent 5987 2001-11-21 20:39:25 man1/ecpg .1
-rw-r--r-- brent/brent 4648 2001-11-21 21:16:23 man1/initdb.1
-rw-r--r-- brent/brent 1562 2001-11-21 21:16:23 man1/initlocation.1
-rw-r--r-- brent/brent 1721 2001-11-21 21:16:23 man1/ipcclean.1
-rw-r--r-- brent/brent 2832 2001-11-21 21:16:22 man1/pg_config.1
-rw-r--r-- brent/brent 6409 2001-11-21 21:16:23 man1/pg_ctl.1
-rw-r--r-- brent/brent 12585 2001-11-21 20:39:26 man1/pg_dump\n .1
-rw-r--r-- brent/brent 3669 2001-11-21 21:16:22 man1/pg_dumpall.1
-rw-r--r-- brent/brent 2678 2001-11-21 21:16:23 man1/pg_passwd.1
-rw-r--r-- brent/brent 12277 2001-11-21 20:39:26 man1/pg_restore\n .1
-rw-r--r-- brent/brent 3613 2001-11-21 21:16:22 man1/pgaccess.1
-rw-r--r-- brent/brent 1098 2001-11-21 20:39:27 man1/pgtclsh\n .1
-rw-r--r-- brent/brent 1196 2001-11-21 20:33:55 man1/pgtksh\n .1
Anyone care to share the details of the patched docbook2man-spec.pl
file mentioned in doc/src/Makefile.in? Do these modifications fix the
problems seen above?
cheers.
brent
brent$ grep '^Index: ' pgsql-doc.diff
Index: doc/src/sgml/protocol.sgml
Index: doc/src/sgml/ref/abort.sgml
Index: doc/src/sgml/ref/alter_group.sgml
Index: doc/src/sgml/ref/alter_table.sgml
Index: doc/src/sgml/ref/alter_user.sgml
Index: doc/src/sgml/ref/analyze.sgml
Index: doc/src/sgml/ref/begin.sgml
Index: doc/src/sgml/ref/close.sgml
Index: doc/src/sgml/ref/cluster.sgml
Index: doc/src/sgml/ref/comment.sgml
Index: doc/src/sgml/ref/commit.sgml
Index: doc/src/sgml/ref/copy.sgml
Index: doc/src/sgml/ref/create_aggregate.sgml
Index: doc/src/sgml/ref/create_constraint.sgml
Index: doc/src/sgml/ref/create_database.sgml
Index: doc/src/sgml/ref/create_function.sgml
Index: doc/src/sgml/ref/create_group.sgml
Index: doc/src/sgml/ref/create_index.sgml
Index: doc/src/sgml/ref/create_operator.sgml
Index: doc/src/sgml/ref/create_rule.sgml
Index: doc/src/sgml/ref/create_sequence.sgml
Index: doc/src/sgml/ref/create_table.sgml
Index: doc/src/sgml/ref/create_table_as.sgml
Index: doc/src/sgml/ref/create_type.sgml
Index: doc/src/sgml/ref/create_user.sgml
Index: doc/src/sgml/ref/create_view.sgml
Index: doc/src/sgml/ref/declare.sgml
Index: doc/src/sgml/ref/drop_aggregate.sgml
Index: doc/src/sgml/ref/drop_database.sgml
Index: doc/src/sgml/ref/drop_function.sgml
Index: doc/src/sgml/ref/drop_group.sgml
Index: doc/src/sgml/ref/drop_index.sgml
Index: doc/src/sgml/ref/drop_operator.sgml
Index: doc/src/sgml/ref/drop_rule.sgml
Index: doc/src/sgml/ref/drop_sequence.sgml
Index: doc/src/sgml/ref/drop_table.sgml
Index: doc/src/sgml/ref/drop_trigger.sgml
Index: doc/src/sgml/ref/drop_type.sgml
Index: doc/src/sgml/ref/drop_user.sgml
Index: doc/src/sgml/ref/drop_view.sgml
Index: doc/src/sgml/ref/ecpg-ref.sgml
Index: doc/src/sgml/ref/end.sgml
Index: doc/src/sgml/ref/explain.sgml
Index: doc/src/sgml/ref/fetch.sgml
Index: doc/src/sgml/ref/listen.sgml
Index: doc/src/sgml/ref/lock.sgml
Index: doc/src/sgml/ref/move.sgml
Index: doc/src/sgml/ref/notify.sgml
Index: doc/src/sgml/ref/pg_config-ref.sgml
Index: doc/src/sgml/ref/pg_dump.sgml
Index: doc/src/sgml/ref/pg_restore.sgml
Index: doc/src/sgml/ref/pg_upgrade.sgml
Index: doc/src/sgml/ref/pgtclsh.sgml
Index: doc/src/sgml/ref/pgtksh.sgml
Index: doc/src/sgml/ref/reindex.sgml
Index: doc/src/sgml/ref/rollback.sgml
Index: doc/src/sgml/ref/select.sgml
Index: doc/src/sgml/ref/select_into.sgml
Index: doc/src/sgml/ref/truncate.sgml
Index: doc/src/sgml/ref/unlisten.sgml
Index: doc/src/sgml/ref/update.sgml
Index: doc/src/sgml/ref/vacuum.sgml--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing." -- Duane Allman
Brent Verner <brent@rcfile.org> writes:
In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
empty closing tags when I ran
?? I'm not seeing any of these problems. Are you using the recommended
docs toolchain?
regards, tom lane
On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
| Brent Verner <brent@rcfile.org> writes:
| > In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
| > empty closing tags when I ran
|
| ?? I'm not seeing any of these problems. Are you using the recommended
| docs toolchain?
I have no clue about the recommended docs toolchain. I must not be,
since my docbook2man-spec.pl does not (seem to) accept command line
arguments. I've built postgresql.tar, but man.tar is still giving
me fits. The built html files can be seen at
http://rcfile.org/posthack/pgdocs/
What I am seeing from a fresh update (at 11:19 EST) is this.
sleepy:~/pgsql/doc/src
brent$ grep '</>' sgml/* |wc -l
grep: sgml/CVS: Is a directory
grep: sgml/ref: Is a directory
1639
sleepy:~/pgsql/doc/src
brent$ grep -Hn '</>' sgml/xoper.sgml
sgml/xoper.sgml:116: operators <literal><</> and <literal>></> for a particular data type are usually each others'
sgml/xoper.sgml:117: commutators, and operator <literal>+</> is usually commutative with itself.
sgml/xoper.sgml:118: But operator <literal>-</> is usually not commutative with anything.
sgml/xoper.sgml:179: For example, <literal><</> and <literal>>=</> are a negator pair for most data types.
sgml/xoper.sgml:242: make sense if you think about it. <literal>=</> will typically accept only
sgml/xoper.sgml:243: a small fraction of the rows in a table; <literal><></> will typically reject
sgml/xoper.sgml:244: only a small fraction. <literal><</> will accept a fraction that depends on
sgml/xoper.sgml:248: <literal><=</> will accept a slightly larger fraction than <literal><</> for the same
sgml/xoper.sgml:251: rough guess anyhow. Similar remarks apply to <literal>></> and <literal>>=</>.
sgml/xoper.sgml:359: joins. On machines that meet the <acronym>IEEE</> floating point standard, minus
sgml/xoper.sgml:389: that can only succeed for pairs of values that fall at the <quote>same place</>
sgml/xoper.sgml:413: In practice you should only write SORT clauses for an <literal>=</> operator,
sgml/xoper.sgml:414: and the two referenced operators should always be named <literal><</>. Trying
sgml/xoper.sgml:436: There must be <literal><</> and <literal>></> ordering operators having the same left and
sgml/xoper.sgml:438: operators <emphasis>must</emphasis> be named <literal><</> and <literal>></>; you do
confused,
brent
--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing." -- Duane Allman
Brent Verner <brent@rcfile.org> writes:
On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
| ?? I'm not seeing any of these problems. Are you using the recommended
| docs toolchain?
I have no clue about the recommended docs toolchain.
I don't claim to be excessively clued either ... all I know is what I
read in the PG docs:
http://www.ca.postgresql.org/users-lounge/docs/7.1/postgres/doc-toolsets.html
regards, tom lane
Brent Verner <brent@rcfile.org> writes:
On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
| ?? I'm not seeing any of these problems. Are you using the recommended
| docs toolchain?I have no clue about the recommended docs toolchain.
I don't claim to be excessively clued either ... all I know is what I
read in the PG docs:
http://www.ca.postgresql.org/users-lounge/docs/7.1/postgres/doc-toolsets.html
I think we use docbook 3.2 while 4.0 doesn't support </>, or something
like that.
--
Bruce Momjian | http://candle.pha.pa.us
pgman@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 19026On 22 Nov 2001 at 00:07 (-0500), Bruce Momjian wrote:
| > Brent Verner <brent@rcfile.org> writes:
| > > On 21 Nov 2001 at 23:11 (-0500), Tom Lane wrote:
| > > | ?? I'm not seeing any of these problems. Are you using the recommended
| > > | docs toolchain?
| >
| > > I have no clue about the recommended docs toolchain.
| >
| > I don't claim to be excessively clued either ... all I know is what I
| > read in the PG docs:
| > http://www.ca.postgresql.org/users-lounge/docs/7.1/postgres/doc-toolsets.html
|
| I think we use docbook 3.2 while 4.0 doesn't support </>, or something
| like that.
ah, so "</>" _is_ a legal closing tag. I suspected as much after
seeing how many there were, and the fact that I could get thru the
postgres.tar build.
I found that I had to have the 0.7.0 version of docbook2man-spec.pl
instead of the version installed on my system (0.6.9). After tweaking
the script to run, I finally got the man.tar made :-)
sorry for the noise.
brent
Happy Thanksgiving to you all!
--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing." -- Duane Allman
Brent Verner writes:
In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
empty closing tags when I ransh$ nsgmls -s -wall ./book-decl.sgml ./reference.sgml
The -wall option isn't very useful. Empty closing tags are perfectly
legal. I don't know if they're good style, but as long as you don't
exaggerate I don't feel that they aren't. They're not allowed in XML,
though.
Anyone care to share the details of the patched docbook2man-spec.pl
file mentioned in doc/src/Makefile.in? Do these modifications fix the
problems seen above?
The man pages for release 7.1 where built with docbook2X 0.6.1 plus the
patch available on my web page[1]http://webmail.postgresql.org/~petere/docbook2man.html. 7.2 is probably going to be the same.
[1]: http://webmail.postgresql.org/~petere/docbook2man.html
--
Peter Eisentraut peter_e@gmx.net
On 22 Nov 2001 at 18:21 (+0100), Peter Eisentraut wrote:
| Brent Verner writes:
|
| > In trying to get the doc/ tree in cvs to build, I noticed a _lot_ of
| > empty closing tags when I ran
| >
| > sh$ nsgmls -s -wall ./book-decl.sgml ./reference.sgml
|
| The -wall option isn't very useful. Empty closing tags are perfectly
| legal. I don't know if they're good style, but as long as you don't
| exaggerate I don't feel that they aren't. They're not allowed in XML,
| though.
gotcha. When I hit problems with the man.tar build, I started looking
for /any/ cause. The '</>' was the first thing I noticed.
| > Anyone care to share the details of the patched docbook2man-spec.pl
| > file mentioned in doc/src/Makefile.in? Do these modifications fix the
| > problems seen above?
|
| The man pages for release 7.1 where built with docbook2X 0.6.1 plus the
| patch available on my web page[1]patch attached for this as well.. 7.2 is probably going to be the same.
|
| [1]patch attached for this as well. http://webmail.postgresql.org/~petere/docbook2man.html
cool. I ended up fixing up the newest (0.7.0) release of his script,
and finally did get man.tar built. Is there any desire to distribute
a copy of the patched script in cvs? This would make it much easier
for people who might want to package a given cvs snapshot...
I've attached a patch which adds a directory to search for docbook
stylesheets in the config/docbook.m4 if there is any interest in
supporting another platform for building the cvs docs. This (in
addition to minor doc/src/Makefile mods[1]patch attached for this as well.) allows me to build on
a debian (unstable) box.
[1]: patch attached for this as well.
thanks.
brent
--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing." -- Duane Allman
Brent Verner writes:
This (in addition to minor doc/src/Makefile mods[1]) allows me to
build on a debian (unstable) box.
I don't understand that patch.
--
Peter Eisentraut peter_e@gmx.net
On 22 Nov 2001 at 19:44 (+0100), Peter Eisentraut wrote:
| Brent Verner writes:
|
| > This (in addition to minor doc/src/Makefile mods[1]) allows me to
| > build on a debian (unstable) box.
|
| I don't understand that patch.
I'm sorry, I wrote "doc/src/Makefile mods..." That should have been
"doc/src/sgml/Makefile mods..."
On my system, collateindex.pl is not in $(DOCBOOKSTYLE)/bin. With
that patch applied I can do
sh$ make man.tar COLLATEINDEX=/usr/bin/collateindex.pl D2MDIR=/usr/local/bin
IMO, these patches are not very important, which is why I didn't send
them to -patches. If you don't feel the changes are useful to others,
I won't mind keeping up with the changes locally.
cheers.
brent
--
"Develop your talent, man, and leave the world something. Records are
really gifts from people. To think that an artist would love you enough
to share his music with anyone is a beautiful thing." -- Duane Allman