From: Jürgen Purtz <juergen@purtz.de>
To: Heikki Linnakangas <hlinnaka@iki.fi>
To: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
To: Michael Paquier <michael@paquier.xyz>
Cc: pgsql-hackers@lists.postgresql.org
Subject: Re: [PATCH] Add section headings to index types doc
Date: Sat, 3 Oct 2020 06:59:39 +0200
Message-ID: <de5409ae-4840-e4fd-317b-b9b8139ae998@purtz.de> (raw)
In-Reply-To: <87d3f5b9-641f-0891-6f02-90b3cc8ecf77@iki.fi>
References: <877dukhvzg.fsf@wibble.ilmari.org>
<2268714.1596457003@sss.pgh.pa.us>
<159706393772.790.11301900224459454375.pgcf@coridan.postgresql.org>
<20200930063423.GG1996@paquier.xyz>
<87pn63ecc0.fsf@wibble.ilmari.org>
<87d3f5b9-641f-0891-6f02-90b3cc8ecf77@iki.fi>
On 30.09.20 14:53, Heikki Linnakangas wrote:
> On 30/09/2020 14:25, Dagfinn Ilmari Mannsåker wrote:
>> Michael Paquier <michael@paquier.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>
>> + - * / < > = ~ ! @ # % ^ & | ` ?
>> </literallayout>
>
> Reading up on the meaning of "literallayout" at
> https://tdg.docbook.org/tdg/4.5/literallayout.html, 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><</literal></member> ... is very chatty:
it needs the additional 'columns' attribute and the additional 'member'
element.
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
Attachments:
[image/png] ibedbibedcnhbpod.png (35.9K, ../de5409ae-4840-e4fd-317b-b9b8139ae998@purtz.de/3-ibedbibedcnhbpod.png)
download | view image
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: juergen@purtz.de, hlinnaka@iki.fi, ilmari@ilmari.org, michael@paquier.xyz, pgsql-hackers@lists.postgresql.org
Subject: Re: [PATCH] Add section headings to index types doc
In-Reply-To: <de5409ae-4840-e4fd-317b-b9b8139ae998@purtz.de>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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