Re: [PATCH 00/22] list.3: New page forked from queue.3

["Michael Kerrisk \(man-pages\) via Libc-alpha" <libc-alpha@sourceware.org>]

Hi Alex,

On 10/20/20 4:21 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> I finished one of the pages: list.3
> 
> Would you maybe call the page LIST.3 instead?

I think list.3 is okay.

> I didn't write the link pages yet in case we call it differently.
> 
> Please comment any improvements you may find.

Overall, I think the result is fine, but:

> There are too many patches, so you may prefer to pull from my repo,
> where I created the tag 'list_v1' for this patchset:
> 
> 	https://github.com/alejandro-colomar/man-pages.git  list_v1
> 
> As you can probably guess, if you prefer to pull from the repo,
> I'll create similar tags for revisions of this patchset (e.g., 'list_v2').

I suppose if I was doing this work I would chunk it up into bigger
pieces. I appreciate that you are trying to meticulously show the
steps that you took to build the page, but 22 patches does
really feel like too much. And I would have combined the
"Use man markup" patches into one step at the end, and I'd prefer
you do that for future patches (but I can live with things as they
are in this patch series).

In terms of fewer patches, how would you feel about squashing the
patches as per the blank line separators below (and consequently
having bigger commit messages):

> Alejandro Colomar (22):
>   list.3: New page that will hold the (list) contents of queue.3

>   list.3, queue.3: NAME: Move code from queue.3 to list.3
>   list.3: NAME: ffix: Use man markup
>   list.3: NAME: Add description

>   list.3, queue.3: SYNOPSIS: Move code from queue.3 to list.3
>   list.3: SYNOPSIS: Copy include from queue.3
>   list.3: SYNOPSIS: ffix: Use man markup

>   list.3: DESCRIPTION: Add short description
>   list.3: DESCRIPTION: Copy description about naming of macros from
>     queue.3
>   list.3: DESCRIPTION: Remove unrelated code to adapt to this page
>   list.3: DESCRIPTION: ffix: Use man markup

>   list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
>     list.3
>   list.3: DESCRIPTION: ffix: Use man markup
>   list.3: DESCRIPTION: Remove line pointing to the EXAMPLES

>   list.3: CONFORMING TO: Copy from queue.3
>   list.3: CONFORMING TO: Adapt to this page
>   list.3: CONFORMING TO: ffix: Use man markup

>   list.3: SEE ALSO: Add insque(3) and queue(3)

>   list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3
>   list.3: EXAMPLES: ffix: Use man markup

>   list.3: BUGS: Note LIST_FOREACH() limitations

>   list.3: RETURN VALUE: Add details about the return value of those
>     macros that "return" a value

Squashing as above would yield 10 patches, and I'd kind of prefer
that so as to avoid quite so many commits in the history.
(For future patches though, I would prefer to split out the
"Use man markup" into a single  patch at the end of the series.)

Thanks,

Michael

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