[PATCH] system_data_types.7: srcfix

[PATCH] system_data_types.7: srcfix

[Alejandro Colomar]

Remove comment specifying the layout of the page.

The page has grown enough to document the layout by itself.
Anything that is not clear enough in the current layout
should follow documented conventions.

This comment is not needed anymore.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 22 ----------------------
 1 file changed, 22 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 4930aac8b..7eba87cde 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -28,28 +28,6 @@
 .SH NAME
 system_data_types \- overview of system data types
 .SH DESCRIPTION
-.\" Layout:
-.\"	A list of type names (the struct/union keyword will be omitted).
-.\"	Each entry will have the following parts:
-.\"		* Include (see NOTES)
-.\"
-.\"		* Definition (no "Definition" header)
-.\"			Only struct/union types will have definition;
-.\"			typedefs will remain opaque.
-.\"
-.\"		* Description (no "Description" header)
-.\"			A few lines describing the type.
-.\"
-.\"		* Versions (optional)
-.\"
-.\"		* Conforming to (see NOTES)
-.\"			Format: CXY and later; POSIX.1-XXXX and later.
-.\"
-.\"		* Notes (optional)
-.\"
-.\"		* Bugs (if any)
-.\"
-.\"		* See also
 .\"------------------------------------- aiocb ------------------------/
 .TP
 .I aiocb
-- 
2.28.0

Re: [PATCH] system_data_types.7: srcfix

[Michael Kerrisk (man-pages)]

Hi Alex,

On 10/26/20 11:34 PM, Alejandro Colomar wrote:
> Remove comment specifying the layout of the page.
> 
> The page has grown enough to document the layout by itself.
> Anything that is not clear enough in the current layout
> should follow documented conventions.
> 
> This comment is not needed anymore.

I think there's still some value in retaining this comment!
IMO, it's not completely obvious how each type should be
described from simply reading the existing entries.

If we retain the comment, the "Notes" piece could 
definitely be removed though.

Thanks,

Michael

> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 22 ----------------------
>  1 file changed, 22 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 4930aac8b..7eba87cde 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -28,28 +28,6 @@
>  .SH NAME
>  system_data_types \- overview of system data types
>  .SH DESCRIPTION
> -.\" Layout:
> -.\"	A list of type names (the struct/union keyword will be omitted).
> -.\"	Each entry will have the following parts:
> -.\"		* Include (see NOTES)
> -.\"
> -.\"		* Definition (no "Definition" header)
> -.\"			Only struct/union types will have definition;
> -.\"			typedefs will remain opaque.
> -.\"
> -.\"		* Description (no "Description" header)
> -.\"			A few lines describing the type.
> -.\"
> -.\"		* Versions (optional)
> -.\"
> -.\"		* Conforming to (see NOTES)
> -.\"			Format: CXY and later; POSIX.1-XXXX and later.
> -.\"
> -.\"		* Notes (optional)
> -.\"
> -.\"		* Bugs (if any)
> -.\"
> -.\"		* See also
>  .\"------------------------------------- aiocb ------------------------/
>  .TP
>  .I aiocb
> 


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

Re: [PATCH] system_data_types.7: srcfix

[Alejandro Colomar]

Hi Michael,

On 2020-10-27 06:54, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> On 10/26/20 11:34 PM, Alejandro Colomar wrote:
>> Remove comment specifying the layout of the page.
>>
>> The page has grown enough to document the layout by itself.
>> Anything that is not clear enough in the current layout
>> should follow documented conventions.
>>
>> This comment is not needed anymore.
> 
> I think there's still some value in retaining this comment!
> IMO, it's not completely obvious how each type should be
> described from simply reading the existing entries.


Okay.
I'll keep this patch in the 'rejected' branch,
and maybe some day I'll pick it again :)

> 
> If we retain the comment, the "Notes" piece could
> definitely be removed though.


I'm not sure what you mean about this.

Cheers,

Alex

Re: [PATCH] system_data_types.7: srcfix

[Michael Kerrisk (man-pages)]

On 10/27/20 11:27 AM, Alejandro Colomar wrote:
> Hi Michael,
> 
> On 2020-10-27 06:54, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On 10/26/20 11:34 PM, Alejandro Colomar wrote:
>>> Remove comment specifying the layout of the page.
>>>
>>> The page has grown enough to document the layout by itself.
>>> Anything that is not clear enough in the current layout
>>> should follow documented conventions.
>>>
>>> This comment is not needed anymore.
>>
>> I think there's still some value in retaining this comment!
>> IMO, it's not completely obvious how each type should be
>> described from simply reading the existing entries.
> 
> 
> Okay.
> I'll keep this patch in the 'rejected' branch,
> and maybe some day I'll pick it again :)
> 
>>
>> If we retain the comment, the "Notes" piece could
>> definitely be removed though.
> 
> 
> I'm not sure what you mean about this.

I mean, this piece seems redundant:

.\"             * Notes (optional)
.\"

Or did I miss something?

Thanks,

Michael


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