TOC: List of Figures
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.
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
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
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>
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
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
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
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
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
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
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
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
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
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]https://commitfest.postgresql.org/24/2204/.
Jonathan