An XSLT example script

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

An XSLT example script

Jürgen Purtz
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.



0001-xslt-example.patch (600 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

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


Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

Peter Eisentraut-6
In reply to this post by Jürgen Purtz
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


Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

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


Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

Jürgen Purtz
In reply to this post by Peter Eisentraut-6
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




Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

Peter Eisentraut-6
In reply to this post by Bruce Momjian
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


Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

Jürgen Purtz
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




Reply | Threaded
Open this post in threaded view
|

Re: An XSLT example script

Tom Lane-2
=?UTF-8?Q?J=c3=bcrgen_Purtz?= <[hidden email]> 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