Re: [PATCH] circleq.3, list.3, slist.3, stailq.3, tailq.3: Improve readability, especially in SYNOPSIS

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Alex,

On 1/4/21 11:45 PM, Alejandro Colomar wrote:
> - Group macros by kinds.

Looks good.

> - Align so that it's easiest to distinguish differences>   between related macros.

The problem with this is that it doesn't render well in PDF [1],
I think. The spaces render small in PDF, and the alignment looks
random. Better to use the same indent for all continuations.
Could you amend and resend please.

> - Fix minor typos.

Okay.

> - Remove redundant text ('The macro xxx() ...')>   The first paragraph already says that these are macros.

Okay.

> - Fit lines into 78 columns.

Okay.

> I noticed a bug which should be fixed next:
> CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

Okay.

> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> ---
> 
> Hi Michael,
> 
> Here's my attempt of making queue.3 pages more readable.
> I think it's quite nicer now.

Agreed.

> But please, review it, because I may have introduced a few bugs
> while moving the text around.

At aa quick glance, it looks okay to me.

> Also, if you feel something could be nicer, please tell me.
> 
> BTW, it's been the first time I use Vim for something not trivial,
> and I quite liked it.
> I think I'll stop using Gedit for a while :-)

Good choice :-).

[...]

Cheers,

Michael

[1]
Usage: pdfman <man-page.n>

function pdfman {
    man -Tps -l $1 > /tmp/$(basename $1).$$.ps
    ps2pdf /tmp/$(basename $1).$$.ps $1.pdf
    evince $1.pdf
}

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/