Re: [PATCH] Add section headings to index types doc

From: Jürgen Purtz <juergen(at)purtz(dot)de>
To: Heikki Linnakangas <hlinnaka(at)iki(dot)fi>, Dagfinn Ilmari Mannsåker <ilmari(at)ilmari(dot)org>, Michael Paquier <michael(at)paquier(dot)xyz>
Cc: pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Re: [PATCH] Add section headings to index types doc
Date: 2020-10-03 04:59:39
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On 30.09.20 14:53, Heikki Linnakangas wrote:
> On 30/09/2020 14:25, Dagfinn Ilmari Mannsåker wrote:
>> Michael Paquier <michael(at)paquier(dot)xyz> writes:
>>> On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote:
>>>> The new status of this patch is: Waiting on Author
>>> This has not been answered yet, so I have marked the patch as returned
>>> with feedback.
>> Updated patch attached, wich reformats the operator lists as requested
>> by Jürgen, and skips the reindentation as suggested by Tom.
> I wonder if "synopsis" is the right markup for the operator lists. I'm
> not too familiar with SGML, but the closest similar list I could find
> is this in create_operator.sgml:
>>    The operator name is a sequence of up to
>> <symbol>NAMEDATALEN</symbol>-1
>>    (63 by default) characters from the following list:
>> <literallayout>
>> + - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?
>> </literallayout>
> Reading up on the meaning of "literallayout" at
>, though, it doesn't
> sound quite right either. Maybe "<simplelist type=horiz'>" ?
> - Heikki

<literallyout> loses the aqua background color (in comparison to the
existing documentation).

<simplelist type="horiz"
columns="5"><member><literal>&lt;</literal></member> ... is very chatty:
it needs the additional 'columns' attribute and the additional 'member'

Therefor I am in favor of the <synopsis> solution as given in the last
patch of Dagfinn.

Playing around I found another solution, which also looks quite good.
The chapter uses operators within the text flow at different places. All
of them are embedded in a <literal> element (inline). Using this
<literal> element also for the index-specific operators, the reading of
the page gets easier and the rendering is consistent. But the drawback
is that these operator are no longer accentuated. Because they
'represents' the possible access methods per index-type, one can argue
that they should be shown in a special way, eg.: in a separate paragraph
as in Dagfin's patch. (I suppose that this was the original intention of
the huge number of line-breaks.) It would look like the following, but I
don't recommend to use it:


Jürgen Purtz

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Peter Eisentraut 2020-10-03 06:40:31 Add primary keys to system catalogs
Previous Message Masahiko Sawada 2020-10-03 03:56:11 Re: Resetting spilled txn statistics in pg_stat_replication