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

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

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

diff --git a/man1/memusage.1 b/man1/memusage.1
index 7ceaece56..f7b62bb6c 100644
--- a/man1/memusage.1
+++ b/man1/memusage.1
@@ -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"
diff --git a/man7/uri.7 b/man7/uri.7
index c23cbce59..a36c2f2c3 100644
--- a/man7/uri.7
+++ b/man7/uri.7
@@ -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
diff --git a/man7/user-keyring.7 b/man7/user-keyring.7
index 4b249d60d..7938bd40c 100644
--- a/man7/user-keyring.7
+++ b/man7/user-keyring.7
@@ -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
diff --git a/man7/user-session-keyring.7 b/man7/user-session-keyring.7
index 22560bd19..df7482b2a 100644
--- a/man7/user-session-keyring.7
+++ b/man7/user-session-keyring.7
@@ -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
diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 614a112a4..553ded9f1 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -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
diff --git a/man8/tzselect.8 b/man8/tzselect.8
index e9dcd1265..fd17bca53 100644
--- a/man8/tzselect.8
+++ b/man8/tzselect.8
@@ -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
-- 
2.28.0

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

[Michael Kerrisk (man-pages)]

Hi Alex,

Briefly...

> 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.

> 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

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

[Alejandro Colomar (man-pages)]

Hi Michael,

On 11/15/20 9:54 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
> 
> Briefly...
> 
>> 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.

Okay.

> 
>> 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.

> 
> Thanks,
> 
> Michael
> 

Thanks,

Alex

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

[Michael Kerrisk (man-pages)]

On Sun, 15 Nov 2020 at 21:54, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
>
> Hi Alex,
>
> Briefly...
>
> > 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.
>
> > 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

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

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

[Michael Kerrisk (man-pages)]

Hi ALex,

On 11/16/20 1:33 AM, Alejandro Colomar (man-pages) wrote:
> Hi Michael,
> 
> On 11/15/20 9:54 PM, Michael Kerrisk (man-pages) wrote:

[...]

> 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

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