An XSLT example script

Started by Jürgen Purtzabout 6 years ago8 messagesdocs

juergen@purtz.de

about 6 years ago

The example "XSLT Stylesheet for Converting SQL/XML Output to HTML" is
tagged as <figure>, but it isn't a figure, it's an example script. The
PDF output contains lists for examples, figures and tables and shows it
in the wrong list. We should change the tagging.

Jürgen P.

Bruce Momjian

bruce@momjian.us

almost 6 years ago

In reply to: Jürgen Purtz (#1)

Re: An XSLT example script

On Tue, Apr 14, 2020 at 10:03:53AM +0200, Jï¿½rgen Purtz wrote:

The example "XSLT Stylesheet for Converting SQL/XML Output to HTML" is
tagged as <figure>, but it isn't a figure, it's an example script. The PDF
output contains lists for examples, figures and tables and shows it in the
wrong list. We should change the tagging.

Agreed. Backpatched through 9.5. Thanks.

---------------------------------------------------------------------------

Jï¿½rgen P.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7a270eb0ab..2f1cf46c2a 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11499,7 +11499,7 @@ table2-mapping
converted into other XML-based formats.
</para>

-   <figure id="xslt-xml-html">
+   <example id="xslt-xml-html">
<title>XSLT Stylesheet for Converting SQL/XML Output to HTML</title>
<programlisting><![CDATA[
<?xml version="1.0"?>
@@ -11547,7 +11547,7 @@ table2-mapping

</xsl:stylesheet>
]]></programlisting>
- </figure>
+ </example>
</sect2>
</sect1>

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Peter Eisentraut

peter_e@gmx.net

almost 6 years ago

In reply to: Jürgen Purtz (#1)

Re: An XSLT example script

On 2020-04-14 10:03, Jürgen Purtz wrote:

The example "XSLT Stylesheet for Converting SQL/XML Output to HTML" is
tagged as <figure>, but it isn't a figure, it's an example script.

It's not an example, it's an actual script that you are supposed to use.

The
PDF output contains lists for examples, figures and tables and shows it
in the wrong list. We should change the tagging.

Why is it wrong to make this a figure?

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Bruce Momjian

bruce@momjian.us

almost 6 years ago

In reply to: Peter Eisentraut (#3)

Re: An XSLT example script

On Tue, Apr 21, 2020 at 08:10:09PM +0200, Peter Eisentraut wrote:

On 2020-04-14 10:03, Jï¿½rgen Purtz wrote:

The example "XSLT Stylesheet for Converting SQL/XML Output to HTML" is
tagged as <figure>, but it isn't a figure, it's an example script.

It's not an example, it's an actual script that you are supposed to use.

Uh, the text said "example", and all the other figures we had used SVG
files, so it didn't see to match our other markup.

The
PDF output contains lists for examples, figures and tables and shows it
in the wrong list. We should change the tagging.

Why is it wrong to make this a figure?

I thought figure was just images. Was figure really right, or something
else? This is the only script we use? programlisting maybe?

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Jürgen Purtz

juergen@purtz.de

almost 6 years ago

In reply to: Peter Eisentraut (#3)

Re: An XSLT example script

On 21.04.20 20:10, Peter Eisentraut wrote:

On 2020-04-14 10:03, Jürgen Purtz wrote:

The example "XSLT Stylesheet for Converting SQL/XML Output to HTML" is
tagged as <figure>, but it isn't a figure, it's an example script.

It's not an example, it's an actual script that you are supposed to use.

The
PDF output contains lists for examples, figures and tables and shows it
in the wrong list. We should change the tagging.

Why is it wrong to make this a figure?

Sorry, I don't understand. Do we speak about the same position in the
documentation?

https://www.postgresql.org/docs/12/functions-xml.html#XSLT-XML-HTML

Scripts usually are tagged as "screen", "programmlisting", "example",
"synopsis/function" (for functions) - but never as a figure. The
introductory text explicitly says "As an example ...". Therefor
"example" seems to be appropriate. IMO "programmlisting" is also possible.

And: there is no single graphical element like a line, a circle, a
color, or an UML-symbol.

Jürgen Purtz

Peter Eisentraut

peter_e@gmx.net

almost 6 years ago

In reply to: Bruce Momjian (#4)

Re: An XSLT example script

On 2020-04-21 21:04, Bruce Momjian wrote:

On Tue, Apr 21, 2020 at 08:10:09PM +0200, Peter Eisentraut wrote:

On 2020-04-14 10:03, Jürgen Purtz wrote:

The example "XSLT Stylesheet for Converting SQL/XML Output to HTML" is
tagged as <figure>, but it isn't a figure, it's an example script.

It's not an example, it's an actual script that you are supposed to use.

Uh, the text said "example", and all the other figures we had used SVG
files, so it didn't see to match our other markup.

The
PDF output contains lists for examples, figures and tables and shows it
in the wrong list. We should change the tagging.

Why is it wrong to make this a figure?

I thought figure was just images. Was figure really right, or something
else? This is the only script we use? programlisting maybe?

Maybe it's just easier to remove the wrapping in either <figure> or
<example> if that is confusing.

But I request that the backpatching of this be reverted. This would
renumber all the other examples and/or figures, and then it won't be
clear what future bug reports will refer to. This issue isn't that
drastic to make that worth it.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Jürgen Purtz

juergen@purtz.de

almost 6 years ago

In reply to: Peter Eisentraut (#6)

Re: An XSLT example script

On 23.04.20 11:40, Peter Eisentraut wrote:

Maybe it's just easier to remove the wrapping in either <figure> or
<example> if that is confusing.

But I request that the backpatching of this be reverted. This would
renumber all the other examples and/or figures, and then it won't be
clear what future bug reports will refer to. This issue isn't that
drastic to make that worth it.

This is a tiny patch, backpatching isn't important for me.

The chapter doesn't contain any other example or figure. Therefore we
shouldn't face any side effect concerning numbering. Those numbers
restart in every chapter for figures, examples, and tables (there is an
additional table in the huge list of tables of this chapter: "Bit String
Functions" after "Bit String Operators").

Jürgen Purtz

Tom Lane

tgl@sss.pgh.pa.us

almost 6 years ago

In reply to: Jürgen Purtz (#7)

Re: An XSLT example script

=?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> writes:

On 23.04.20 11:40, Peter Eisentraut wrote:

But I request that the backpatching of this be reverted. This would
renumber all the other examples and/or figures, and then it won't be
clear what future bug reports will refer to. This issue isn't that
drastic to make that worth it.

The chapter doesn't contain any other example or figure. Therefore we
shouldn't face any side effect concerning numbering. Those numbers
restart in every chapter for figures, examples, and tables (there is an
additional table in the huge list of tables of this chapter: "Bit String
Functions" after "Bit String Operators").

Yeah, Peter's point would be a good one if there were other <figure>s
or <example>s in chapter 9, but there are none today.

I personally wouldn't have bothered with back-patching on the grounds
of "it's unimportant" ... but now that it's done, I wouldn't revert it,
on the same grounds.

regards, tom lane

An XSLT example script

Attachments: