Skip to contentSkip to conversation

system_data_types.7: srcfix

PATCH In review Alejandro Colomar 2 participants 4 messages Oct 26, 2020 – Oct 27, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 system_data_types.7: srcfix

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.

---
 man7/system_data_types.7 | 22 ----------------------
 1 file changed, 22 deletions(-)
man7/system_data_types.7 +0 -22
index 4930aac8b..7eba87cde 100644
@@ -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
Signature · 1 line
2.28.0
#1 lore raw

Hi Alex,

Quoted 7 lines · 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.

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

Quoted 39 lines
---
 man7/system_data_types.7 | 22 ----------------------
 1 file changed, 22 deletions(-)
man7/system_data_types.7 +0 -22
index 4930aac8b..7eba87cde 100644
@@ -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
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw

Hi Michael,

Quoted 9 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 6 lines · 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.

Quoted 5 lines
Quoted 1 line

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 :)

Quoted 3 lines

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

I'm not sure what you mean about this.

Cheers,

Alex

#3 lore raw
Quoted 24 lines · Alejandro Colomar

Hi Michael,

Quoted 9 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 6 lines · 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.

Quoted 5 lines
Quoted 1 line

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 :)

Quoted 1 line
Quoted 5 lines
Quoted 2 lines

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

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