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

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
> 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