memusage.1, uri.7, user-keyring.7, user-session-keyring.7, ld.so.8, tzselect.8: srcfix: Replace \f markup by .
RFC 1/1 memusage.1, uri.7, user-keyring.7, user-session-keyring.7, ld.so.8, tzselect.8: srcfix: Replace \f markup by .
---
Hi,
I was trying to see if I can write a script to fix these. Here's a sample of what I would change.
It seems a bit complicated. There are exceptions:
* I think for code inside [.EX/.EE], [\f] is more appropriate than [.]; what do you think about it?
* And for [.TP] tags, [\f] seems to be the only solution (for more than 2 different formattings in a line).
So I would try to write a script that omits code inside [.EX/.EE], and also just after [.TP].
And I also found a few weird files (such as zic.8 and zdump.8). Where do those come from?
I'll try to rewrite them using man(7) markup.
In the meantime,
I would also have to omit those files from the input to the script. Do you have a list of such files?
Cheers,
Alex
man1/memusage.1 | 29 +++++++++++++++++++++-------- man7/uri.7 | 6 ++++-- man7/user-keyring.7 | 4 +++- man7/user-session-keyring.7 | 4 +++- man8/ld.so.8 | 7 +++++-- man8/tzselect.8 | 6 +++--- 6 files changed, 39 insertions(+), 17 deletions(-)
man1/memusage.1 +21 -8
@@ -65,14 +65,20 @@ The "Memory usage summary" line output by contains three fields: .RS 4 .TP -\fBheap total\fR -Sum of \fIsize\fR arguments of all +.B heap total +Sum of +.I size +arguments of all .BR malloc (3) calls, -products of arguments (\fInmemb\fR*\fIsize\fR) of all +products of arguments +.RI ( nmemb * size ) +of all .BR calloc (3) calls, -and sum of \fIlength\fR arguments of all +and sum of +.I length +arguments of all .BR mmap (2) calls. In the case of
@@ -83,17 +89,24 @@ if the new size of an allocation is larger than the previous size, the sum of all such differences (new size minus old size) is added. .TP .B "heap peak" -Maximum of all \fIsize\fR arguments of +Maximum of all +.I size +arguments of .BR malloc (3), -all products of \fInmemb\fR*\fIsize\fR of +all products of +.IR nmemb * size +of .BR calloc (3), -all \fIsize\fR arguments of +all +.I size +arguments of .BR realloc (3), .I length arguments of .BR mmap (2), and -\fInew_size\fR arguments of +.I new_size +arguments of .BR mremap (2). .TP .B "stack peak"
man7/uri.7 +4 -2
@@ -600,10 +600,12 @@ Technically the fragment isn't part of the URI. .PP For information on how to embed URIs (including URLs) in a data format, see documentation on that format. -HTML uses the format <A HREF="\fIuri\fP"> +HTML uses the format <A +.RI HREF=\(dq uri \(dq> .I text </A>. -Texinfo files use the format @uref{\fIuri\fP}. +Texinfo files use the format +.RI @uref{ uri }. Man and mdoc have the recently added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI). .PP
man7/user-keyring.7 +3 -1
@@ -51,7 +51,9 @@ the calling process's user keyring. .PP From the .BR keyctl (1) -utility, '\fB@u\fP' can be used instead of a numeric key ID in +utility, +.RB \(aq @u \(aq +can be used instead of a numeric key ID in much the same way. .PP User keyrings are independent of
man7/user-session-keyring.7 +3 -1
@@ -54,7 +54,9 @@ the calling process's user session keyring. .PP From the .BR keyctl (1) -utility, '\fB@us\fP' can be used instead of a numeric key ID in +utility, +.RB \(aq @us \(aq +can be used instead of a numeric key ID in much the same way. .PP User session keyrings are independent of
man8/ld.so.8 +5 -2
@@ -38,7 +38,10 @@ The program handles a.out binaries, a binary format used long ago. The program .B ld\-linux.so* -(\fI/lib/ld\-linux.so.1\fP for libc5, \fI/lib/ld\-linux.so.2\fP for glibc2) +.RI ( /lib/ld\-linux.so.1 +for libc5, +.I /lib/ld\-linux.so.2 +for glibc2) handles binaries that are in the more modern ELF format. Both programs have the same behavior, and use the same support files and programs
@@ -648,7 +651,7 @@ which is now always enabled. The name of a (single) shared object to be profiled, specified either as a pathname or a soname. Profiling output is appended to the file whose name is: -"\fI$LD_PROFILE_OUTPUT\fP/\fI$LD_PROFILE\fP.profile". +.RI \(dq $LD_PROFILE_OUTPUT / $LD_PROFILE .profile\(dq. .IP Since glibc 2.2.5, .BR LD_PROFILE
man8/tzselect.8 +3 -3
@@ -34,14 +34,14 @@ Name of the directory containing timezone data files (default: .\" or perhaps /usr/local/etc/zoneinfo in some older systems. .SH FILES .TP -\fBTZDIR\fP\fI/iso3166.tab\fP +.BI TZDIR /iso3166.tab Table of ISO 3166 2-letter country codes and country names. .TP -\fBTZDIR\fP\fI/zone.tab\fP +.BI TZDIR /zone.tab Table of country codes, latitude and longitude, TZ values, and descriptive comments. .TP -\fBTZDIR\fP\fI/\fP\fITZ\fP +.BI TZDIR /TZ Timezone data file for timezone .IR TZ . .SH SEE ALSO
Signature · 1 line
2.28.0
Hi Alex,
Briefly...
Quoted 3 lines
And I also found a few weird files (such as zic.8 and zdump.8). Where do those come from?
I'll try to rewrite them using man(7) markup.
Stop!! These pages are special. They are periodically imported from the tz project. It's an odd situation. Glibc imports these tools from the tz project, but does not release manual pages. So, periodically (when Paul Eggert reminds me), I resync the pages from the tz project. In general, I try to just leave them alone (although I have suggested a few fixes upstream to Paul), although I see I have touched some of those pages in global edits.
Quoted 3 lines
In the meantime,
I would also have to omit those files from the input to the script. Do you have a list of such files?
AFAIR, the only other special page is bpf-helpers.7, which is generated from the kernel source files using scripts. Every few months, I try to remember to run the scripts to resync.
Thanks,
Michael
Hi Michael,
Quoted 8 lines · Michael Kerrisk (man-pages)
Hi Alex,
Briefly...
Quoted 3 lines
And I also found a few weird files (such as zic.8 and zdump.8). Where do those come from?
I'll try to rewrite them using man(7) markup.
Quoted 7 lines
Stop!! These pages are special. They are periodically imported from the tz project. It's an odd situation. Glibc imports these tools from the tz project, but does not release manual pages. So, periodically (when Paul Eggert reminds me), I resync the pages from the tz project. In general, I try to just leave them alone (although I have suggested a few fixes upstream to Paul), although I see I have touched some of those pages in global edits.
Okay.
Quoted 9 lines
Quoted 4 lines
In the meantime,
I would also have to omit those files from the input to the script. Do you have a list of such files?AFAIR, the only other special page is bpf-helpers.7, which is generated from the kernel source files using scripts. Every few months, I try to remember to run the scripts to resync.
So, except for zic.8, zdump.8, and bpf-helpers.7, what do you think about the current usage of \f?
I've seen a lot of appearances (many thousands), and many of them should probably be fixed.
I think a script to fix them might be a bit difficult, but a small C program might be easier to write.
Quoted 5 lines
Thanks,
Michael
Thanks,
Alex
Hi ALex,
Quoted 3 lines · Alejandro Colomar (man-pages)
Hi Michael,
On 11/15/20 9:54 PM, Michael Kerrisk (man-pages) wrote:
[...]
Quoted 8 lines
So, except for zic.8, zdump.8, and bpf-helpers.7, what do you think about the current usage of \f?
I've seen a lot of appearances (many thousands), and many of them should probably be fixed.
I think a script to fix them might be a bit difficult, but a small C program might be easier to write.
My preference is to avoid \f in favor of .I/.B/etc where possible, since I find the latter form is often easier to read in the source.
But, as you note, that's not easy in some cases. Every now and then, when I'm edit some part of a page that uses \f, I'll switch over to .I/.B/etc.
But, I would prefer not to have a global edit, since:
* Nothing is really broken.
* It's a lot of churn.
* There's the possibility of errors in the change.
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/
Quoted 17 lines · Michael Kerrisk (man-pages)
Hi Alex,
Briefly...
Quoted 3 lines
And I also found a few weird files (such as zic.8 and zdump.8). Where do those come from?
I'll try to rewrite them using man(7) markup.Stop!! These pages are special. They are periodically imported from the tz project. It's an odd situation. Glibc imports these tools from the tz project, but does not release manual pages. So, periodically (when Paul Eggert reminds me), I resync the pages from the tz project. In general, I try to just leave them alone (although I have suggested a few fixes upstream to Paul), although I see I have touched some of those pages in global edits.
Quoted 8 lines
Quoted 3 lines
In the meantime,
I would also have to omit those files from the input to the script. Do you have a list of such files?AFAIR, the only other special page is bpf-helpers.7, which is generated from the kernel source files using scripts. Every few months, I try to remember to run the scripts to resync.
One more page that I forgot: tzfile.5 also comes from the tz project.
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/