Re: [PATCH] Add section headings to index types doc - Mailing list pgsql-hackers

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>
+ - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?
</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>&lt;</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