Обсуждение: An XSLT example script
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.
Вложения
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 +
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
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 +
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
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
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
=?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