Subject: An XSLT example script

From: Jürgen Purtz <[email-masked]>
Date: Tue, 14 Apr 2020 10:03:53 +0200

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.

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>

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 20 Apr 2020 21:41:27 -0400

On Tue, Apr 14, 2020 at 10:03:53AM +0200, Jürgen Purtz wrote:
> 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.

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

-- 
  Bruce Momjian  <[email-masked]>        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 +

---

From: Peter Eisentraut <[email-masked]>
Date: Tue, 21 Apr 2020 20:10:09 +0200

On 2020-04-14 10:03, Jürgen Purtz wrote:
> 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

Why is it wrong to make this a figure?

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

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 21 Apr 2020 15:04:55 -0400

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

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

---

From: Jürgen Purtz <[email-masked]>
Date: Tue, 21 Apr 2020 21:23:33 +0200

> 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

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 23 Apr 2020 11:40:22 +0200

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

---

From: Jürgen Purtz <[email-masked]>
Date: Thu, 23 Apr 2020 17:16:14 +0200

> 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

---

From: Tom Lane <[email-masked]>
Date: Thu, 23 Apr 2020 11:40:52 -0400

> 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