Skip to contentSkip to conversation

memusage.1, uri.7, user-keyring.7, user-session-keyring.7, ld.so.8, tzselect.8: srcfix: Replace \f markup by .

RFC In review Alejandro Colomar 2 participants 5 messages Nov 15, 2020 – Nov 16, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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
index 7ceaece56..f7b62bb6c 100644
@@ -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
index c23cbce59..a36c2f2c3 100644
@@ -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
index 4b249d60d..7938bd40c 100644
@@ -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
index 22560bd19..df7482b2a 100644
@@ -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
index 614a112a4..553ded9f1 100644
@@ -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
index e9dcd1265..fd17bca53 100644
@@ -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
#1 lore raw

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

#2 lore raw

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

#3 lore raw

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/
#4 lore raw
In reply to Michael Kerrisk (man-pages)
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/