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

  Hi Michael,

I finished one of the pages: list.3

Would you maybe call the page LIST.3 instead?
I didn't write the link pages yet in case we call it differently.

Please comment any improvements you may find.


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').


Cheers,

Alex

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

 man3/list.3  | 347 +++++++++++++++++++++++++++++++++++++++++++++++++++
 man3/queue.3 | 237 -----------------------------------
 2 files changed, 347 insertions(+), 237 deletions(-)
 create mode 100644 man3/list.3
  

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
  

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
>
  

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