Обсуждение: 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
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
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 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 19026
On 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 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. > 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]. 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]. 7.2 is probably going to be the same. | | [1] 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]) 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