On 2020-10-20 20:57, Michael Kerrisk (man-pages) wrote:
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.)
I can't find the source
(I think it was some kernel guide for sending patches),
but I read some time ago that I should separate code movement
from any other changes;
otherwise git might not be able to follow that movement.
So I would reorder and squash the commits as:
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, queue.3: SYNOPSIS: Move code from queue.3 to list.3
list.3, queue.3: DESCRIPTION: Move list specific code from queue.3 to
list.3
list.3, queue.3: EXAMPLES: Move example program from queue.3 to list.3
list.3: SYNOPSIS: Copy include from queue.3
list.3: DESCRIPTION: Copy description about naming of macros from
queue.3
list.3: CONFORMING TO: Copy from queue.3
list.3: DESCRIPTION: Remove unrelated code to adapt to this page
list.3: DESCRIPTION: Remove line pointing to the EXAMPLES
list.3: CONFORMING TO: Adapt to this page
squash as list.3: Copy and adapt code from queue.3
list.3: NAME: ffix: Use man markup
list.3: SYNOPSIS: ffix: Use man markup
list.3: DESCRIPTION: ffix: Use man markup
list.3: DESCRIPTION: ffix: Use man markup
list.3: CONFORMING TO: ffix: Use man markup
list.3: EXAMPLES: ffix: Use man markup
squash as list.3: ffix: Use man markup
list.3: NAME: Add description
list.3: DESCRIPTION: Add short description
list.3: SEE ALSO: Add insque(3) and queue(3)
list.3: BUGS: Note LIST_FOREACH() limitations
list.3: RETURN VALUE: Add details about the return value of those
macros that "return" a value
squash as list.3: Add details
I'll keep the messages of the squashed commits inside the commit msg.
This would mean 8 patches.
Sounds good?
Thanks,
Alex
Thanks,
Michael
