Now that we have the LIBRARY section, and a 4th argument that
already tells that it's a page from the Linux man-pages project,
the 5th argument isn't telling any information that the default
value wouldn't. So let's just remove it.
Scripted change:
$ find man* -type f \
| xargs sed -Ei '/^.TH /s/(.TH +[^ ]+ +[^ ]+ +[^ ]+ +"[^"]+") .*/\1/'
All pages: Replace the 4th argument to .TH by "Linux man-pages (unreleased)"
On 8/20/22 13:57, Alejandro Colomar wrote:
> On 8/20/22 07:43, G. Branden Robinson wrote:
>>
>> In my opinion it would benefit readers of the Linux man-pages if the
>> fourth argument to `TH` were what it is in many other man pages: an
>> identifier for the name and version number of the release originating
>> them. In every page it would be clear what version of the man-pages was
>> being viewed. Little sophistication would be demanded of the user to
>> check the Web to determine the relative age of the pages, independently
>> of the modification date of the particular page. Such usage would be
>> congruent with the argument's purpose in AT&T and BSD Unix, where this
>> datum was "7th Edition", "System III", or "4.2 Berkeley Distribution",
>> or similar.
>
> I thought about it in the past... That field was the only thing that
> said where a function came from. If we removed GNU (or something else),
> how would someone know where does the function or whatever comes from??
>
> I guess that's also why the colophon was appended to the pages by
> Michael. Since we couldn't use the 4th field for that, we had to have a
> COLOPHON section.
>
> However, the addition of the LIBRARY section seems to fix this issue,
> and so now we have an even more precise way to determine where a given
> function comes from (including the library file name, and the linker
> option).
>
> This gives me another argument for those who don't like to have a
> LIBRARY section for libc stuff (since -lc is unnecessary), and consider
> it noise.
>
>>
>> Further, as the libc-related man pages in this project expand coverage
>> to other libcs than GNU's, the alternatives to the empty string
>> proferred in man-pages(7) seem less and less appropriate.
>
> Agree. LIBRARY seems much more appropriate for that purpose.
>
> And this helps remove the COLOPHON section (or at least, we don't need
> to autogenerate it, since the version number now comes in .TH, and the
> COLOPHON is static; so I can even move it to a smaller REPORTING BUGS
> section).
Also add a hint of how intmax(3) and other functions using
[u]intmax_t types could be better defined by ISO C, by requiring
that they're implemented as type-generic macros, to avoid having
problems with the ABI.
Use tbl(1) instead of a magic sequence of spaces and tabs to get a
nice formatting. This fixes the following warnings:
mandoc: man7/spufs.7:748:7: WARNING: tab in filled text
mandoc: man7/spufs.7:748:14: WARNING: tab in filled text
mandoc: man7/spufs.7:748:22: WARNING: tab in filled text
mandoc: man7/spufs.7:748:32: WARNING: tab in filled text
mandoc: man7/spufs.7:748:34: WARNING: tab in filled text
Use tables to represent tables.
Use .EX/.EE to represent a code example.
Use \& to prevent .SS of being interpreted as man(7) source.
an.tmac:man7/man-pages.7:900: style: 5 leading space(s) on input line
an.tmac:man7/man-pages.7:901: style: 5 leading space(s) on input line
an.tmac:man7/man-pages.7:902: style: 5 leading space(s) on input line
an.tmac:man7/man-pages.7:903: style: 5 leading space(s) on input line
an.tmac:man7/man-pages.7:965: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:966: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:967: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:968: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:969: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:970: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:978: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:979: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:980: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:981: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:982: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:983: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:984: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:985: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:986: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:987: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:988: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:989: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:990: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:991: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:992: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:993: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:994: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:995: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:996: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:997: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:1003: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:1004: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:1005: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:1006: style: 4 leading space(s) on input line
an.tmac:man7/man-pages.7:1137: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2010: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2011: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2012: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2013: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2014: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2015: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2016: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2017: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2018: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2019: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2020: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2021: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2022: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2023: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2024: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2025: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2026: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2027: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2028: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2029: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2030: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2031: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2032: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2033: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2034: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2035: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2036: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2037: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2038: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2039: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2040: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:2041: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3332: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3333: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3334: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3335: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3336: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3337: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3338: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3339: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3340: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3341: style: 5 leading space(s) on input line
an.tmac:man5/proc.5:3342: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3343: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3344: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3345: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3346: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3347: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3348: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3349: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3350: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3351: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3352: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3353: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3354: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3355: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3357: style: 4 leading space(s) on input line
an.tmac:man5/proc.5:3359: style: 4 leading space(s) on input line
an.tmac:man4/st.4:715: style: use of deprecated macro: .HP
an.tmac:man4/st.4:721: style: use of deprecated macro: .HP
an.tmac:man4/st.4:727: style: use of deprecated macro: .HP
an.tmac:man4/st.4:730: style: use of deprecated macro: .HP
an.tmac:man4/st.4:736: style: use of deprecated macro: .HP
an.tmac:man4/st.4:739: style: use of deprecated macro: .HP
an.tmac:man4/st.4:744: style: use of deprecated macro: .HP
an.tmac:man4/st.4:749: style: use of deprecated macro: .HP
an.tmac:man4/st.4:753: style: use of deprecated macro: .HP
an.tmac:man4/st.4:756: style: use of deprecated macro: .HP
an.tmac:man4/st.4:764: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:89: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:91: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:94: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:97: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:101: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:103: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:105: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:107: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:109: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:111: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:113: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:604: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:606: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:608: style: use of deprecated macro: .HP
an.tmac:man4/console_codes.4:610: style: use of deprecated macro: .HP
an.tmac:man4/cciss.4:100: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:101: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:102: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:103: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:104: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:105: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:106: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:107: style: 4 leading space(s) on input line
an.tmac:man4/cciss.4:281: style: 4 leading space(s) on input line
an.tmac:man3/__setfpucw.3:58: style: 5 leading space(s) on input line
an.tmac:man3/__setfpucw.3:59: style: 5 leading space(s) on input line
an.tmac:man3/__setfpucw.3:60: style: 5 leading space(s) on input line
Format the table using tbl(1), to fix the following warnings.
an.tmac:man2/membarrier.2:222: style: 23 leading space(s) on input line
an.tmac:man2/membarrier.2:223: style: 7 leading space(s) on input line
an.tmac:man2/membarrier.2:224: style: 7 leading space(s) on input line
an.tmac:man2/membarrier.2:225: style: 7 leading space(s) on input line
Replace "shall" wordings by simpler text, to not resemble a
standards document.
When saying something like "According to POSIX/ISO C, ...", if
the mentioned standard is the same one described in STANDARDS,
remove that text (it is redundant). However, if ISO C is the
main standard that describes a type, but POSIX applies further
restrictions, keep that text.
Remove pedantic notes that may only be interesting to compiler
writers.
Replace "shall" wordings by simpler text, to not resemble a
standards document.
When saying something like "According to POSIX/ISO C, ...", if
the mentioned standard is the same one described in STANDARDS,
remove that text (it is redundant). However, if ISO C is the
main standard that describes a type, but POSIX applies further
restrictions, keep that text.
Remove pedantic notes that may only be interesting to compiler
writers.
Many pages: Use STANDARDS instead of CONFORMING TO
STANDARDS seems to be much more extended than CONFORMING TO. For
consistency across the whole manual pages corpus, let's try to
unify, by following the most commonly used section name.
On 7/27/22 12:49, Ingo Schwarze wrote:
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:
> > We use CONFORMING TO in Linux. Don't know why; just history, I guess.
> > See man-pages(7).
>
> Weird.
>
> I failed to find a single instance of "CONFORMING TO" in AT&T UNIX
> (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in
> any version of UCB CSRG BSD. So considering that System V and BSD are
> widely considered the two main original branches of the development
> of Unix-like operating systems and Linux is often considered to have
> drawn inspiration from both, the section name "CONFORMING TO" does
> not appear to be a UNIX thing. For example, Aeleen Frisch, "Essential
> System Administration", O'Reilly, Cambridge 1995, considers Linux
> as slightly more influenced by 4.3BSD than by System V Release 3.
>
> STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990).
>
> 4.3BSD-Reno predates the first version of the Linux kernel by more than
> a year, and the first Linux manual pages probably for longer than that.
>
> So i have no idea where "CONFORMING TO" may have come from.
Scripted change:
$ find man* -type f | xargs sed -i 's/CONFORMING TO/STANDARDS/'
The first sentence in
getsid(0) returns the session ID of the calling process.
getsid() returns the session ID of the process with process ID pid.
If pid is 0, getsid() returns the session ID of the calling process.
blames to beginning of git, duplicates the third one,
and doesn't stylistically match current formatting
CAVEATS is an interesting section. There's a slight difference
between CAVEATS and BUGS. We usually have a hard time fitting
what would go into CAVEATS into other sections (usually BUGS and
NOTES); it would be easier if we had the section. Let's add it.
This section has been used in manual pages by authors from a wide
range of projects including AT&T, Korn shell, Perl, GNU and BSD
since the early 1980s. Using the section was first officially
recommended in 2002 by the file </usr/share/misc/mdoc.template> in
NetBSD and OpenBSD.
Many pages: Use man3type/ and man2type/ for type pages
Quoting Ingo:
[
The mandoc(1) program is also able to handle paths like
"man3/id_t.3type". It will consider that page to be *both* in section
"3" (as specified by the directory name) and in section "3type" (as
specified by the file name and by the .TH macro). I would consider
it better style to keep section names consistent, i.e. to use either
"man3/id_t.3" .TH id_t 3 or "man3type/id_t.3type" .TH id_t 3type,
but it's not a big deal: since many systems (in particular various
Linux distros) suffer from such inconsistencies, handling such
inconsistencies gracefully is an important feature that certainly
won't get removed.
]
Let's be nice, and do things right here, in the hope that others
may follow the example.
===
Most of this patch has been scripted:
$ mkdir man2type man3type
$ find man2 | grep type$ | while read f; do mv -t man2type $f; done
$ find man3 | grep type$ | while read f; do mv -t man3type $f; done
$ grep -rl man3/.*type man* | xargs sed -i 's,man3/,man3type/,'
Apart from that, I adapted the Makefiles, and moved va_list into
the man3type subsection (it was accidentally placed in the main 3
section).