pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTOC: List of Figures
14+ messages / 7 participants
[nested] [flat]
* TOC: List of Figures
@ 2019-07-02 08:13 Jürgen Purtz <juergen@purtz.de>
0 siblings, 4 replies; 14+ messages in thread
From: Jürgen Purtz @ 2019-07-02 08:13 UTC (permalink / raw)
To: Pg Docs <pgsql-docs@lists.postgresql.org>
After the integration of figures into the documentation it may be
helpful to extent the TOC with a 'List of Figures'. Any opinion?
If yes: The same for 'List of Tables' and 'List of Examples'?
There is a simple way to enable this feature: change line 56 of
stylesheet-html-common.xsl to: "book toc,title,figure,table,example". As
shown in a previous thread this leads to an ugly swelling of the TOC
similar to the formerly handling of release notes - especially for
tables and examples -, see attachment 1.
The alternative is a downshift of the postings by one level, see
attachment 2. How to realize this behavior is shown in attachment 3.
Attachments:
Screenshot from 2019-07-01 17-26-13.png (image/png, 58.0K) download
view image
Screenshot from 2019-07-01 17-27-39.png (image/png, 13.0K) download
view image
toc.patch (text/x-patch, 1.8K) download
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 3e115f1c76..6a1b5228d0 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -281,6 +281,22 @@
</part>
+ <part>
+ <title>Lists of Figures, Tables and Examples</title>
+ <appendix id="list-of-figures">
+ <title>List of Figures</title>
+ <para />
+ </appendix>
+ <appendix id="list-of-tables">
+ <title>List of Tables</title>
+ <para />
+ </appendix>
+ <appendix id="list-of-examples">
+ <title>List of Examples</title>
+ <para />
+ </appendix>
+ </part>
+
&biblio;
<index id="bookindex"></index>
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index 9edce52a10..eb04549fb9 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -81,6 +81,27 @@ set toc,title
</xsl:call-template>
</xsl:template>
+<!-- List of Figures and more -->
+<xsl:template match="/book/part/appendix[@id='list-of-figures']/para">
+ <xsl:call-template name="list.of.titles">
+ <xsl:with-param name="titles" select="'figure'"/>
+ <xsl:with-param name="nodes" select="//figure"/>
+ </xsl:call-template>
+</xsl:template>
+
+<xsl:template match="/book/part/appendix[@id='list-of-tables']/para">
+ <xsl:call-template name="list.of.titles">
+ <xsl:with-param name="titles" select="'table'"/>
+ <xsl:with-param name="nodes" select="//table"/>
+ </xsl:call-template>
+</xsl:template>
+
+<xsl:template match="/book/part/appendix[@id='list-of-examples']/para">
+ <xsl:call-template name="list.of.titles">
+ <xsl:with-param name="titles" select="'example'"/>
+ <xsl:with-param name="nodes" select="//example"/>
+ </xsl:call-template>
+</xsl:template>
<!-- Put index "quicklinks" (A | B | C | ...) at the top of the bookindex page. -->
* Re: TOC: List of Figures
@ 2019-07-02 08:43 Daniel Gustafsson <daniel@yesql.se>
parent: Jürgen Purtz <juergen@purtz.de>
3 siblings, 2 replies; 14+ messages in thread
From: Daniel Gustafsson @ 2019-07-02 08:43 UTC (permalink / raw)
To: Jürgen Purtz <juergen@purtz.de>; +Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
> On 2 Jul 2019, at 10:13, Jürgen Purtz <juergen@purtz.de> wrote:
> After the integration of figures into the documentation it may be helpful to extent the TOC with a 'List of Figures'. Any opinion?
+1, I think we should.
> The alternative is a downshift of the postings by one level, see attachment 2. How to realize this behavior is shown in attachment 3.
This alternative seems a better idea.
cheers ./daniel
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-02 11:58 Jonathan S. Katz <jkatz@postgresql.org>
parent: Daniel Gustafsson <daniel@yesql.se>
1 sibling, 0 replies; 14+ messages in thread
From: Jonathan S. Katz @ 2019-07-02 11:58 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Jürgen Purtz <juergen@purtz.de>; +Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
On 7/2/19 4:43 AM, Daniel Gustafsson wrote:
>> On 2 Jul 2019, at 10:13, Jürgen Purtz <juergen@purtz.de> wrote:
>
>> After the integration of figures into the documentation it may be helpful to extent the TOC with a 'List of Figures'. Any opinion?
>
> +1, I think we should.
+1
>
>> The alternative is a downshift of the postings by one level, see attachment 2. How to realize this behavior is shown in attachment 3.
>
> This alternative seems a better idea.
+1, seems like an easier grouping to follow.
Jonathan
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-02 12:35 Oleg Bartunov <obartunov@gmail.com>
parent: Jürgen Purtz <juergen@purtz.de>
3 siblings, 0 replies; 14+ messages in thread
From: Oleg Bartunov @ 2019-07-02 12:35 UTC (permalink / raw)
To: Jürgen Purtz <juergen@purtz.de>; +Cc: Pg Docs <pgsql-docs@lists.postgresql.org>
On 2 Jul 2019, at 11:13, Jürgen Purtz <juergen@purtz.de> wrote:
After the integration of figures into the documentation it may be helpful
to extent the TOC with a 'List of Figures'. Any opinion?
If yes: The same for 'List of Tables' and 'List of Examples'?
There is a simple way to enable this feature: change line 56 of
stylesheet-html-common.xsl to: "book toc,title,figure,table,example". As
shown in a previous thread this leads to an ugly swelling of the TOC
similar to the formerly handling of release notes - especially for tables
and examples -, see attachment 1.
+1
The alternative is a downshift of the postings by one level, see attachment
2. How to realize this behavior is shown in attachment 3.
<Screenshot from 2019-07-01 17-26-13.png><Screenshot from 2019-07-01
17-27-39.png><toc.patch>
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-02 17:07 Alvaro Herrera <alvherre@2ndquadrant.com>
parent: Daniel Gustafsson <daniel@yesql.se>
1 sibling, 0 replies; 14+ messages in thread
From: Alvaro Herrera @ 2019-07-02 17:07 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Jürgen Purtz <juergen@purtz.de>; Pg Docs <pgsql-docs@lists.postgresql.org>
On 2019-Jul-02, Daniel Gustafsson wrote:
> > On 2 Jul 2019, at 10:13, Jürgen Purtz <juergen@purtz.de> wrote:
>
> > The alternative is a downshift of the postings by one level, see attachment 2. How to realize this behavior is shown in attachment 3.
>
> This alternative seems a better idea.
I agree -- the other way seems to put too many lines in the overall TOC.
As we grow more figures, it'll become unsightly, and scrolling through
that list is not something people would do often.
--
Álvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-03 14:03 Jürgen Purtz <juergen@purtz.de>
parent: Jürgen Purtz <juergen@purtz.de>
3 siblings, 0 replies; 14+ messages in thread
From: Jürgen Purtz @ 2019-07-03 14:03 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
> After the integration of figures into the documentation it may be
> helpful to extent the TOC with a 'List of Figures'. Any opinion?
>
> If yes: The same for 'List of Tables' and 'List of Examples'?
>
> There is a simple way to enable this feature: change line 56 of
> stylesheet-html-common.xsl to: "book toc,title,figure,table,example".
> As shown in a previous thread this leads to an ugly swelling of the
> TOC similar to the formerly handling of release notes - especially for
> tables and examples -, see attachment 1.
>
> The alternative is a downshift of the postings by one level, see
> attachment 2. How to realize this behavior is shown in attachment 3.
I understood that the majority of voters recommend the 'list of figures'
but refuses lists for 'tables' and 'examples' (please consider that PDF
generates all of them by default). The attached patch realizes the
desired behavior. In 'func.sgml' there is also a modification because
the given example isn't a figure, it's an example/programlisting.
Jürgen Purtz
Attachments:
Screenshot from 2019-07-03 15-44-45.png (image/png, 11.8K) download
view image
Screenshot from 2019-07-03 15-48-00.png (image/png, 14.4K) download
view image
toc_1.patch (text/x-patch, 1.6K) download
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 3a8581d205..538a9c45fd 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11444,7 +11444,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"?>
@@ -11492,7 +11492,7 @@ table2-mapping
</xsl:stylesheet>
]]></programlisting>
- </figure>
+ </example>
</sect2>
</sect1>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 3e115f1c76..626b19bfe8 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -279,6 +279,11 @@
&limits;
&acronyms;
+ <appendix id="list-of-figures">
+ <title>List of Figures</title>
+ <para />
+ </appendix>
+
</part>
&biblio;
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index 9edce52a10..d730f469a4 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -81,6 +81,13 @@ set toc,title
</xsl:call-template>
</xsl:template>
+<!-- List of Figures -->
+<xsl:template match="/book/part/appendix[@id='list-of-figures']/para">
+ <xsl:call-template name="list.of.titles">
+ <xsl:with-param name="titles" select="'figure'"/>
+ <xsl:with-param name="nodes" select="//figure"/>
+ </xsl:call-template>
+</xsl:template>
<!-- Put index "quicklinks" (A | B | C | ...) at the top of the bookindex page. -->
* Re: TOC: List of Figures
@ 2019-07-07 18:32 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Jürgen Purtz <juergen@purtz.de>
3 siblings, 1 reply; 14+ messages in thread
From: Peter Eisentraut @ 2019-07-07 18:32 UTC (permalink / raw)
To: Jürgen Purtz <juergen@purtz.de>; Pg Docs <pgsql-docs@lists.postgresql.org>
On 2019-07-02 10:13, Jürgen Purtz wrote:
> After the integration of figures into the documentation it may be
> helpful to extent the TOC with a 'List of Figures'. Any opinion?
>
> If yes: The same for 'List of Tables' and 'List of Examples'?
I have never found these useful. What would you use them for? Who goes
to the documentation (or any other book-like material) thinking, I'm in
the mood to look at some tables today, let's see what's in them.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-07 18:37 Tom Lane <tgl@sss.pgh.pa.us>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 14+ messages in thread
From: Tom Lane @ 2019-07-07 18:37 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Jürgen Purtz <juergen@purtz.de>; Pg Docs <pgsql-docs@lists.postgresql.org>
Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> On 2019-07-02 10:13, Jürgen Purtz wrote:
>> After the integration of figures into the documentation it may be
>> helpful to extent the TOC with a 'List of Figures'. Any opinion?
>>
>> If yes: The same for 'List of Tables' and 'List of Examples'?
> I have never found these useful. What would you use them for? Who goes
> to the documentation (or any other book-like material) thinking, I'm in
> the mood to look at some tables today, let's see what's in them.
+1. I have a vague recollection that we once had such lists in the
TOC (because that was the default behavior for whatever toolchain we
were then using) and later took them out precisely because they were
useless. Not sure how a list of figures would be any more useful.
regards, tom lane
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-08 05:20 Jürgen Purtz <juergen@purtz.de>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 14+ messages in thread
From: Jürgen Purtz @ 2019-07-08 05:20 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
>> On 2019-07-02 10:13, Jürgen Purtz wrote:
>>> After the integration of figures into the documentation it may be
>>> helpful to extent the TOC with a 'List of Figures'. Any opinion?
>>>
>>> If yes: The same for 'List of Tables' and 'List of Examples'?
>> I have never found these useful. What would you use them for? Who goes
>> to the documentation (or any other book-like material) thinking, I'm in
>> the mood to look at some tables today, let's see what's in them.
> +1. I have a vague recollection that we once had such lists in the
> TOC (because that was the default behavior for whatever toolchain we
> were then using) and later took them out precisely because they were
> useless. Not sure how a list of figures would be any more useful.
>
> regards, tom lane
>
The two main reasons for using the documentation are 'reference for
concepts and syntax' and 'learning'. For the first issue figures are
less important - at least as BNF is not presented graphically. The
second issue is important for all persons which are not very familiar
with PG. Pedagogues tell us, that learning is done best with different
media types, where typical methods are direct speech, videos (see the
huge number of learning videos at YouTube), graphics, exercises, reading
manuals. In essence, they recommend some kind of 'media changes' within
each lesson. Currently our documentation is not much more than a manual,
the rising element 'graphics' is and will be tiny small (unless we
integrate BNF). To support the didactic method of media changes we
should promote graphics with a summarizing list at a prominent place in
front of the manual.
Kind regards, Jürgen Purtz
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-08 19:43 Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
parent: Jürgen Purtz <juergen@purtz.de>
0 siblings, 1 reply; 14+ messages in thread
From: Peter Eisentraut @ 2019-07-08 19:43 UTC (permalink / raw)
To: Jürgen Purtz <juergen@purtz.de>; pgsql-docs@lists.postgresql.org
On 2019-07-08 07:20, Jürgen Purtz wrote:
> To support the didactic method of media changes we
> should promote graphics with a summarizing list at a prominent place in
> front of the manual.
This would make sense if we had fifty images spread evenly throughout
the documentation, or moreover, we had an image for every topic. Then
learning by just flipping through the images would be interesting. But
we are not nearly there yet. Promoting a list of images now would just
make those looking for that kind of learning sad.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-08 19:54 Daniel Gustafsson <daniel@yesql.se>
parent: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
0 siblings, 1 reply; 14+ messages in thread
From: Daniel Gustafsson @ 2019-07-08 19:54 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; +Cc: Jürgen Purtz <juergen@purtz.de>; pgsql-docs@lists.postgresql.org
> On 8 Jul 2019, at 21:43, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>
> On 2019-07-08 07:20, Jürgen Purtz wrote:
>> To support the didactic method of media changes we
>> should promote graphics with a summarizing list at a prominent place in
>> front of the manual.
>
> This would make sense if we had fifty images spread evenly throughout
> the documentation, or moreover, we had an image for every topic. Then
> learning by just flipping through the images would be interesting. But
> we are not nearly there yet. Promoting a list of images now would just
> make those looking for that kind of learning sad.
We regularly include scaffolding for things to come in Postgres, I don’t see
this being much different. It will have just a few images now, but by the time
v13 ships we are likely to have a longer list which increase the value of this
further.
cheers ./daniel
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-08 20:10 Tom Lane <tgl@sss.pgh.pa.us>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 14+ messages in thread
From: Tom Lane @ 2019-07-08 20:10 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; Jürgen Purtz <juergen@purtz.de>; pgsql-docs@lists.postgresql.org
Daniel Gustafsson <daniel@yesql.se> writes:
>> On 8 Jul 2019, at 21:43, Peter Eisentraut <peter.eisentraut@2ndquadrant.com> wrote:
>> This would make sense if we had fifty images spread evenly throughout
>> the documentation, or moreover, we had an image for every topic. Then
>> learning by just flipping through the images would be interesting. But
>> we are not nearly there yet. Promoting a list of images now would just
>> make those looking for that kind of learning sad.
> We regularly include scaffolding for things to come in Postgres, I don’t see
> this being much different. It will have just a few images now, but by the time
> v13 ships we are likely to have a longer list which increase the value of this
> further.
I tend to agree with Peter's argument here --- let's wait till there's a
meaningful number of figures and then reconsider whether there's use in
a list of them. It's not like it will be any harder to make that change
in a year or two than it is today.
regards, tom lane
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-08 20:21 Daniel Gustafsson <daniel@yesql.se>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 14+ messages in thread
From: Daniel Gustafsson @ 2019-07-08 20:21 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; Jürgen Purtz <juergen@purtz.de>; pgsql-docs@lists.postgresql.org
> On 8 Jul 2019, at 22:10, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> let's wait till there's a
> meaningful number of figures and then reconsider whether there's use in
> a list of them. It's not like it will be any harder to make that change
> in a year or two than it is today.
In that case, let’s record this in the commitfest app and punt it forwards
towards the release as the CFs move along so we don’t forget to re-evaluate in
the last commitfest before 13.
cheers ./daniel
^ permalink raw reply [nested|flat] 14+ messages in thread
* Re: TOC: List of Figures
@ 2019-07-08 21:51 Jonathan S. Katz <jkatz@postgresql.org>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 14+ messages in thread
From: Jonathan S. Katz @ 2019-07-08 21:51 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>; Jürgen Purtz <juergen@purtz.de>; pgsql-docs@lists.postgresql.org
On 7/8/19 4:21 PM, Daniel Gustafsson wrote:
>> On 8 Jul 2019, at 22:10, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
>> let's wait till there's a
>> meaningful number of figures and then reconsider whether there's use in
>> a list of them. It's not like it will be any harder to make that change
>> in a year or two than it is today.
>
> In that case, let’s record this in the commitfest app and punt it forwards
> towards the release as the CFs move along so we don’t forget to re-evaluate in
> the last commitfest before 13.
Done[1].
Jonathan
[1] https://commitfest.postgresql.org/24/2204/
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 14+ messages in thread
end of thread, other threads:[~2019-07-08 21:51 UTC | newest]
Thread overview: 14+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-07-02 08:13 TOC: List of Figures Jürgen Purtz <juergen@purtz.de>
2019-07-02 08:43 ` Daniel Gustafsson <daniel@yesql.se>
2019-07-02 11:58 ` Jonathan S. Katz <jkatz@postgresql.org>
2019-07-02 17:07 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2019-07-02 12:35 ` Oleg Bartunov <obartunov@gmail.com>
2019-07-03 14:03 ` Jürgen Purtz <juergen@purtz.de>
2019-07-07 18:32 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-07-07 18:37 ` Tom Lane <tgl@sss.pgh.pa.us>
2019-07-08 05:20 ` Jürgen Purtz <juergen@purtz.de>
2019-07-08 19:43 ` Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
2019-07-08 19:54 ` Daniel Gustafsson <daniel@yesql.se>
2019-07-08 20:10 ` Tom Lane <tgl@sss.pgh.pa.us>
2019-07-08 20:21 ` Daniel Gustafsson <daniel@yesql.se>
2019-07-08 21:51 ` Jonathan S. Katz <jkatz@postgresql.org>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox