Re: broken doc

CVS HEAD doc won't compile due to broken mark up. Please someone
commit following patches if they are appropreate.

Also please do not commit broken sgml files without trying to compile
them.
--
Tatsuo Ishii
SRA OSS, Inc. Japan

Index: array.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/array.sgml,v
retrieving revision 1.58
diff -c -r1.58 array.sgml
*** array.sgml 20 Feb 2007 14:54:47 -0000 1.58
--- array.sgml 2 Mar 2007 05:29:24 -0000
***************
*** 243,254 ****
(1 row)
</programlisting>

If any dimension is written as a slice, i.e contains a colon, then all
dimensions are treated as slices. If a dimension is missing, it is
assumed to be <literal>[1:1]</>. If a dimension has only a single
number (no colon), that dimension is treated as being from <literal>1</>
to the number specified. For example, <literal>[2]</> is treated as
! <literal>[1:2], as in this example:

<programlisting>
SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';
--- 243,257 ----
(1 row)
</programlisting>

+ </para>
+
+ <para>
If any dimension is written as a slice, i.e contains a colon, then all
dimensions are treated as slices. If a dimension is missing, it is
assumed to be <literal>[1:1]</>. If a dimension has only a single
number (no colon), that dimension is treated as being from <literal>1</>
to the number specified. For example, <literal>[2]</> is treated as
! <literal>[1:2]</>, as in this example:

<programlisting>
SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill';
[t-ishii(at)localhost sgml]$

Tatsuo Ishii <ishii(at)sraoss(dot)co(dot)jp> writes:
> CVS HEAD doc won't compile due to broken mark up. Please someone
> commit following patches if they are appropreate.

Done.

> Also please do not commit broken sgml files without trying to compile
> them.

Some committers are using DocBook installations that seem quite lax
about closing tags :-(, so they fail to see this type of breakage.

regards, tom lane

> Tatsuo Ishii <ishii(at)sraoss(dot)co(dot)jp> writes:
> > CVS HEAD doc won't compile due to broken mark up. Please someone
> > commit following patches if they are appropreate.
>
> Done.

Thanks.

> > Also please do not commit broken sgml files without trying to compile
> > them.
>
> Some committers are using DocBook installations that seem quite lax
> about closing tags :-(, so they fail to see this type of breakage.

Oh, I didn't know that(in my case I'm using Linux packages).
--
Tatsuo Ishii
SRA OSS, Inc. Japan

Tom Lane wrote:
> Tatsuo Ishii <ishii(at)sraoss(dot)co(dot)jp> writes:
> > CVS HEAD doc won't compile due to broken mark up. Please someone
> > commit following patches if they are appropreate.
>
> Done.
>
> > Also please do not commit broken sgml files without trying to compile
> > them.
>
> Some committers are using DocBook installations that seem quite lax
> about closing tags :-(, so they fail to see this type of breakage.

Yep. What should I upgrade, and to what version?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Tom Lane wrote:
>> Some committers are using DocBook installations that seem quite lax
>> about closing tags :-(, so they fail to see this type of breakage.

> Yep. What should I upgrade, and to what version?

I dunno --- I just use what ships with Fedora. The relevant FC6
packages seem to be

docbook-dtds-1.0-30
docbook-simple-1.0-2.1
docbook-slides-3.3.1-2.1
docbook-style-dsssl-1.79-4
docbook-style-xsl-1.69.1-5
docbook-utils-0.6.14-5
docbook-utils-pdf-0.6.14-5
linuxdoc-tools-0.9.21-6.2.1

but I've got no idea which of these is the critical factor.

regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce(at)momjian(dot)us> writes:
>> Tom Lane wrote:
>>> Some committers are using DocBook installations that seem quite lax
>>> about closing tags :-(, so they fail to see this type of breakage.
>
>> Yep. What should I upgrade, and to what version?
>
> I dunno --- I just use what ships with Fedora. The relevant FC6
> packages seem to be
>
> docbook-dtds-1.0-30
> docbook-simple-1.0-2.1
> docbook-slides-3.3.1-2.1
> docbook-style-dsssl-1.79-4
> docbook-style-xsl-1.69.1-5
> docbook-utils-0.6.14-5
> docbook-utils-pdf-0.6.14-5
> linuxdoc-tools-0.9.21-6.2.1
>
> but I've got no idea which of these is the critical factor.

I am pulling this way out of the back of my head, and Peter might be a
better one to ask but I seem to recall that you can set the closing
bracket requirement in the stylesheet itself.

Joshua D. Drake

>
> regards, tom lane
>
> ---------------------------(end of broadcast)---------------------------
> TIP 4: Have you searched our list archives?
>
> http://archives.postgresql.org
>

--

=== The PostgreSQL Company: Command Prompt, Inc. ===
Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240
Providing the most comprehensive PostgreSQL solutions since 1997
http://www.commandprompt.com/

Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate
PostgreSQL Replication: http://www.commandprompt.com/products/

On Friday 02 March 2007 16:46, Joshua D. Drake wrote:
> I am pulling this way out of the back of my head, and Peter might be a
> better one to ask but I seem to recall that you can set the closing
> bracket requirement in the stylesheet itself.

XML should require the closing tag. Is it possible that you are using the SGML
processor to generate the document instead of the XML processor?

wt
--
Warren Turkal (w00t)

Joshua D. Drake wrote:
> I am pulling this way out of the back of my head, and Peter might be
> a better one to ask but I seem to recall that you can set the closing
> bracket requirement in the stylesheet itself.

That is incorrect.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Warren Turkal wrote:
> XML should require the closing tag.

But this is not XML.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/

Warren Turkal wrote:
> On Friday 02 March 2007 16:46, Joshua D. Drake wrote:
>> I am pulling this way out of the back of my head, and Peter might be a
>> better one to ask but I seem to recall that you can set the closing
>> bracket requirement in the stylesheet itself.
>
> XML should require the closing tag. Is it possible that you are using the
> SGML
> processor to generate the document instead of the XML processor?

the docs are in SGML ...

cheers

andrew

Joshua D. Drake wrote:
> Tom Lane wrote:
> > Bruce Momjian <bruce(at)momjian(dot)us> writes:
> >> Tom Lane wrote:
> >>> Some committers are using DocBook installations that seem quite lax
> >>> about closing tags :-(, so they fail to see this type of breakage.
> >
> >> Yep. What should I upgrade, and to what version?
> >
> > I dunno --- I just use what ships with Fedora. The relevant FC6
> > packages seem to be
> >
> > docbook-dtds-1.0-30
> > docbook-simple-1.0-2.1
> > docbook-slides-3.3.1-2.1
> > docbook-style-dsssl-1.79-4
> > docbook-style-xsl-1.69.1-5
> > docbook-utils-0.6.14-5
> > docbook-utils-pdf-0.6.14-5
> > linuxdoc-tools-0.9.21-6.2.1
> >
> > but I've got no idea which of these is the critical factor.
>
> I am pulling this way out of the back of my head, and Peter might be a
> better one to ask but I seem to recall that you can set the closing
> bracket requirement in the stylesheet itself.

I figured out how to make my toolchain warn about missing tags like
newer tool chains. My openjade needs the "-wfully-tagged" warning. I
added it to sgml/Makefile.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

> Joshua D. Drake wrote:
> > Tom Lane wrote:
> > > Bruce Momjian <bruce(at)momjian(dot)us> writes:
> > >> Tom Lane wrote:
> > >>> Some committers are using DocBook installations that seem quite lax
> > >>> about closing tags :-(, so they fail to see this type of breakage.
> > >
> > >> Yep. What should I upgrade, and to what version?
> > >
> > > I dunno --- I just use what ships with Fedora. The relevant FC6
> > > packages seem to be
> > >
> > > docbook-dtds-1.0-30
> > > docbook-simple-1.0-2.1
> > > docbook-slides-3.3.1-2.1
> > > docbook-style-dsssl-1.79-4
> > > docbook-style-xsl-1.69.1-5
> > > docbook-utils-0.6.14-5
> > > docbook-utils-pdf-0.6.14-5
> > > linuxdoc-tools-0.9.21-6.2.1
> > >
> > > but I've got no idea which of these is the critical factor.
> >
> > I am pulling this way out of the back of my head, and Peter might be a
> > better one to ask but I seem to recall that you can set the closing
> > bracket requirement in the stylesheet itself.
>
> I figured out how to make my toolchain warn about missing tags like
> newer tool chains. My openjade needs the "-wfully-tagged" warning. I
> added it to sgml/Makefile.
>
> --
> Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
> EnterpriseDB http://www.enterprisedb.com
>
> + If your life is a hard drive, Christ can be your backup. +

Can someone please fix this?

openjade -wall -wno-unused-param -wno-empty -wfully-tagged -D . -c /usr/share/sgml/docbook/dsssl-stylesheets/catalog -d stylesheet.dsl -i output-html -t sgml postgres.sgml
openjade:bookindex.sgml:2731:0:E: character data is not allowed here
openjade:bookindex.sgml:2732:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
openjade:bookindex.sgml:2744:0:E: character data is not allowed here
openjade:bookindex.sgml:2745:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
--
Tatsuo Ishii
SRA OSS, Inc. Japan

Tatsuo Ishii wrote:
> > I figured out how to make my toolchain warn about missing tags like
> > newer tool chains. My openjade needs the "-wfully-tagged" warning. I
> > added it to sgml/Makefile.
> >
> > --
> > Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
> > EnterpriseDB http://www.enterprisedb.com
> >
> > + If your life is a hard drive, Christ can be your backup. +
>
> Can someone please fix this?
>
> openjade -wall -wno-unused-param -wno-empty -wfully-tagged -D . -c /usr/share/sgml/docbook/dsssl-stylesheets/catalog -d stylesheet.dsl -i output-html -t sgml postgres.sgml
> openjade:bookindex.sgml:2731:0:E: character data is not allowed here
> openjade:bookindex.sgml:2732:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
> openjade:bookindex.sgml:2744:0:E: character data is not allowed here
> openjade:bookindex.sgml:2745:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag

Yes, committing a fix now, and asking on docs how to fix it for good.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Tatsuo Ishii wrote
> Can someone please fix this?
>
> openjade -wall -wno-unused-param -wno-empty -wfully-tagged -D . -c /usr/share/sgml/docbook/dsssl-stylesheets/catalog -d stylesheet.dsl -i output-html -t sgml postgres.sgml
> openjade:bookindex.sgml:2731:0:E: character data is not allowed here
> openjade:bookindex.sgml:2732:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
> openjade:bookindex.sgml:2744:0:E: character data is not allowed here
> openjade:bookindex.sgml:2745:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
>
>

It's working for me

cheers

andrew

> Tatsuo Ishii wrote:
> > > I figured out how to make my toolchain warn about missing tags like
> > > newer tool chains. My openjade needs the "-wfully-tagged" warning. I
> > > added it to sgml/Makefile.
> > >
> > > --
> > > Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
> > > EnterpriseDB http://www.enterprisedb.com
> > >
> > > + If your life is a hard drive, Christ can be your backup. +
> >
> > Can someone please fix this?
> >
> > openjade -wall -wno-unused-param -wno-empty -wfully-tagged -D . -c /usr/share/sgml/docbook/dsssl-stylesheets/catalog -d stylesheet.dsl -i output-html -t sgml postgres.sgml
> > openjade:bookindex.sgml:2731:0:E: character data is not allowed here
> > openjade:bookindex.sgml:2732:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
> > openjade:bookindex.sgml:2744:0:E: character data is not allowed here
> > openjade:bookindex.sgml:2745:66:E: document type does not allow element "ULINK" here; missing one of "SEEIE", "SEEALSOIE", "SECONDARYIE" start-tag
>
> Yes, committing a fix now, and asking on docs how to fix it for good.

Thanks. Working for me now.
--
Tatsuo Ishii
SRA OSS, Inc. Japan

Andrew Dunstan <andrew(at)dunslane(dot)net> writes:
> Tatsuo Ishii wrote
>> Can someone please fix this?

> It's working for me

On Fedora Core 6's sgml toolchain, HEAD builds but un-commenting those
two index entries fails, just as Tatsuo says.

I'm no expert in this, but looking at the complained-of bookindex.sgml
entries makes me think that those index entries have a semantic conflict
with these entries over in indices.sgml:

<indexterm>
<primary>GiST</primary>
<see>index</see>
</indexterm>

<indexterm>
<primary>GIN</primary>
<see>index</see>
</indexterm>

Perhaps we need to have a meeting of the minds on who gets to define the
primary index entries about GiST and GIN?

Peter will probably have a clearer idea about how to fix this ...

regards, tom lane

Am Freitag, 31. August 2007 06:06 schrieb Tom Lane:
> I'm no expert in this, but looking at the complained-of bookindex.sgml
> entries makes me think that those index entries have a semantic conflict
> with these entries over in indices.sgml:
>
> <indexterm>
> <primary>GiST</primary>
> <see>index</see>
> </indexterm>

Yeah, apparently it is not supported to have a single term being a "see
$elsewhere" and a direct link. The semantics of that are debatable anyway.
The index building tool just creates garbage in that case.

> Perhaps we need to have a meeting of the minds on who gets to define the
> primary index entries about GiST and GIN?

I'd say that the text search section shouldn't be the primary source on GiST
and GIN, just like the section on arithmetic operators isn't the primary
source on B-tree. That might require moving some text around, though.

--
Peter Eisentraut
http://developer.postgresql.org/~petere/