Hi Alex, On 10/20/20 9:21 PM, Alejandro Colomar wrote: > > > 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? I think that would be fine, but I suspect you might have to fix a lot of conflicts if you reorder the patches so much, I wanted to save you having to do that work. I could live with either way, but I'd prefer to minimize the effort you need to invest to make the change. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
