Обсуждение: 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'.
Anyopinion? 

+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
inattachment 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
inattachment 3. 
>
> This alternative seems a better idea.

+1, seems like an easier grouping to follow.

Jonathan

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

Jonathan

[1] https://commitfest.postgresql.org/24/2204/