[PATCH 1/9] ldconfig.8: Fix markup nits

[PATCH 1/9] ldconfig.8: Fix markup nits

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 6730 bytes --]

* Drop stale FIXME annotation regarding commit ID for `-i` option.
* Rewrite synopses to use man(7) font macros instead of *roff font
  selection escape sequences.
* Drop redundant `PD` macro calls.
* Rewrite option list to use man(7) font macros instead of *roff font
  selection escape sequences.
* Use `TQ` macro to include multiple tags for options with long synonyms
  instead of comma notation.
* Break input lines after commas.
* Set multi-word parentheticals on their own input lines.
* Break input lines at phrase boundaries more often.
* Protect literals from automatic hyphenation with `\%` escape sequence.
* Use \~ escape sequence instead of quoted arguments at word
  boundaries in option synopses.

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 man8/ldconfig.8 | 109 +++++++++++++++++++++++++++++++-----------------
 1 file changed, 71 insertions(+), 38 deletions(-)

diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
index d608aaf56..0e74c1791 100644
--- a/man8/ldconfig.8
+++ b/man8/ldconfig.8
@@ -9,22 +9,29 @@
 .SH NAME
 ldconfig \- configure dynamic linker run-time bindings
 .SH SYNOPSIS
-.BR /sbin/ldconfig " [" \-nNvXV "] [" \-f " \fIconf\fP] [" \-C " \fIcache\fP] [" \-r " \fIroot\fP]"
-.IR directory \...
 .PD 0
+.\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache,
+.\" --verbose, -V, --version, -?, --help, --usage
+.B /sbin/ldconfig
+.RB [ \-nNvXV ]
+.RB [ \-f
+.IR conf ]
+.RB [ \-C
+.IR cache ]
+.RB [ \-r
+.IR root ]
+.IR directory ...
 .PP
-.PD
 .B /sbin/ldconfig
 .B \-l
 .RB [ \-v ]
-.IR library \...
-.PD 0
+.IR library ...
 .PP
-.PD
 .B /sbin/ldconfig
 .B \-p
+.PD
 .SH DESCRIPTION
-.B ldconfig
+.B \%ldconfig
 creates the necessary links and cache to the most recent shared
 libraries found in the directories specified on the command line,
 in the file
@@ -37,7 +44,8 @@ and
 .I /lib
 and
 .I /usr/lib
-are the trusted directories for 32-bit libraries, while
+are the trusted directories for 32-bit libraries,
+while
 .I /lib64
 and
 .I /usr/lib64
@@ -47,13 +55,17 @@ The cache is used by the run-time linker,
 .I ld.so
 or
 .IR ld\-linux.so .
-.B ldconfig
+.B \%ldconfig
 checks the header and filenames of the libraries it encounters when
 determining which versions should have their links updated.
 .PP
-.B ldconfig
-will attempt to deduce the type of ELF libraries (i.e., libc5 or libc6/glibc)
-based on what C libraries, if any, the library was linked against.
+.B \%ldconfig
+will attempt to deduce the type of ELF libraries
+(i.e.,
+libc5 or libc6/glibc)
+based on what C libraries,
+if any,
+the library was linked against.
 .\" The following sentence looks suspect
 .\" (perhaps historical cruft) -- MTK, Jul 2005
 .\" Therefore, when making dynamic libraries,
@@ -61,14 +73,18 @@ based on what C libraries, if any, the library was linked against.
 .PP
 Some existing libraries do not contain enough information
 to allow the deduction of their type.
-Therefore, the
+Therefore,
+the
 .I /etc/ld.so.conf
 file format allows the specification of an expected type.
 This is used
 .I only
 for those ELF libraries which we can not work out.
 The format
-is "dirname=TYPE", where TYPE can be libc4, libc5, or libc6.
+is "dirname=TYPE",
+where TYPE can be libc4,
+libc5,
+or libc6.
 (This syntax also works on the command line.)
 Spaces are
 .I not
@@ -76,12 +92,12 @@ allowed.
 Also see the
 .B \-p
 option.
-.B ldconfig
+.B \%ldconfig
 should normally be run by the superuser as it may require write
 permission on some root owned directories and files.
 .PP
 Note that
-.B ldconfig
+.B \%ldconfig
 will only look at files that are named
 .I lib*.so*
 (for regular shared objects) or
@@ -89,9 +105,10 @@ will only look at files that are named
 (for the dynamic loader itself).
 Other files will be ignored.
 Also,
-.B ldconfig
-expects a certain pattern to how the symlinks are set up, like this
-example, where the middle file
+.B \%ldconfig
+expects a certain pattern to how the symlinks are set up,
+like this example,
+where the middle file
 .RB ( libfoo.so.1
 here) is the SONAME for the library:
 .PP
@@ -105,35 +122,41 @@ Failure to follow this pattern may result in compatibility issues
 after an upgrade.
 .SH OPTIONS
 .TP
-.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
+.BI \-c\~ fmt
+.TQ
+.BI \-\-format= fmt
 (Since glibc 2.2)
+.\" commit 45eca4d141c047950db48c69c8941163d0a61fcd
 Cache format to use:
 .IR old ,
 .IR new ,
 or
-.IR compat .
-Since glibc 2.32, the default is
+.IR \%compat .
+Since glibc 2.32,
+the default is
 .IR new .
 .\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
-Before that, it was
-.IR compat .
+Before that,
+it was
+.IR \%compat .
 .TP
-.BI "\-C " cache
+.BI \-C\~ cache
 Use
 .I cache
 instead of
 .IR /etc/ld.so.cache .
 .TP
-.BI "\-f " conf
+.BI \-f\~ conf
 Use
 .I conf
 instead of
 .IR /etc/ld.so.conf .
-.\" FIXME glibc 2.7 added -i
 .TP
-.BR \-i ", " \-\-ignore\-aux\-cache
+.B \-i
+.TQ
+.B \-\-ignore\-aux\-cache
 (Since glibc 2.7)
-.\"             commit 27d9ffda17df4d2388687afd12897774fde39bcc
+.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc
 Ignore auxiliary cache file.
 .TP
 .B \-l
@@ -154,31 +177,40 @@ Implies
 Don't rebuild the cache.
 Unless
 .B \-X
-is also specified, links are still updated.
+is also specified,
+links are still updated.
 .TP
-.BR \-p ", " \-\-print\-cache
+.B \-p
+.TQ
+.B \-\-print\-cache
 Print the lists of directories and candidate libraries stored in
 the current cache.
 .TP
-.BI "\-r " root
+.BI \-r\~ root
 Change to and use
 .I root
 as the root directory.
 .TP
-.BR \-v ", " \-\-verbose
+.B \-v
+.TQ
+.B \-\-verbose
 Verbose mode.
-Print current version number, the name of each directory as it
-is scanned, and any links that are created.
+Print current version number,
+the name of each directory as it is scanned,
+and any links that are created.
 Overrides quiet mode.
 .TP
-.BR \-V ", " \-\-version
+.B \-V
+.TQ
+.B \-\-version
 Print program version.
 .TP
 .B \-X
 Don't update links.
 Unless
 .B \-N
-is also specified, the cache is still rebuilt.
+is also specified,
+the cache is still rebuilt.
 .SH FILES
 .\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf
 .\"
@@ -189,7 +221,8 @@ is also specified, the cache is still rebuilt.
 Run-time linker/loader.
 .TP
 .I /etc/ld.so.conf
-File containing a list of directories, one per line,
+File containing a list of directories,
+one per line,
 in which to search for libraries.
 .TP
 .I /etc/ld.so.cache
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3962 bytes --]

Hi Branden,

On 1/4/23 08:38, G. Branden Robinson wrote:
> * Drop stale FIXME annotation regarding commit ID for `-i` option.
> * Rewrite synopses to use man(7) font macros instead of *roff font
>    selection escape sequences.
> * Drop redundant `PD` macro calls.
> * Rewrite option list to use man(7) font macros instead of *roff font
>    selection escape sequences.
> * Use `TQ` macro to include multiple tags for options with long synonyms
>    instead of comma notation.
> * Break input lines after commas.
> * Set multi-word parentheticals on their own input lines.
> * Break input lines at phrase boundaries more often.
> * Protect literals from automatic hyphenation with `\%` escape sequence.
> * Use \~ escape sequence instead of quoted arguments at word
>    boundaries in option synopses.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

This patch looks good to me.  However, I didn't apply it, since I have a few 
comments below.
> ---
>   man8/ldconfig.8 | 109 +++++++++++++++++++++++++++++++-----------------
>   1 file changed, 71 insertions(+), 38 deletions(-)
> 
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index d608aaf56..0e74c1791 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -9,22 +9,29 @@
>   .SH NAME
>   ldconfig \- configure dynamic linker run-time bindings
>   .SH SYNOPSIS

We should wrap this in .nf/.fi

Although maybe this goes better in the style patch, since it's a formatting fix.

> -.BR /sbin/ldconfig " [" \-nNvXV "] [" \-f " \fIconf\fP] [" \-C " \fIcache\fP] [" \-r " \fIroot\fP]"
> -.IR directory \...
>   .PD 0
> +.\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache,
> +.\" --verbose, -V, --version, -?, --help, --usage
> +.B /sbin/ldconfig
> +.RB [ \-nNvXV ]
> +.RB [ \-f
> +.IR conf ]
> +.RB [ \-C
> +.IR cache ]
> +.RB [ \-r
> +.IR root ]
> +.IR directory ...
>   .PP
> -.PD
>   .B /sbin/ldconfig
>   .B \-l
>   .RB [ \-v ]
> -.IR library \...
> -.PD 0
> +.IR library ...
>   .PP
> -.PD
>   .B /sbin/ldconfig
>   .B \-p
> +.PD
>   .SH DESCRIPTION
> -.B ldconfig
> +.B \%ldconfig

I will suggest again that I believe \% should be the default in manual pages. 
Count how many times you want to break highlighted stuff vs how many times you 
want to not break such stuff.

>   creates the necessary links and cache to the most recent shared
>   libraries found in the directories specified on the command line,
>   in the file
> @@ -37,7 +44,8 @@ and

[...]

> @@ -105,35 +122,41 @@ Failure to follow this pattern may result in compatibility issues
>   after an upgrade.
>   .SH OPTIONS
>   .TP
> -.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
> +.BI \-c\~ fmt
> +.TQ
> +.BI \-\-format= fmt
>   (Since glibc 2.2)
> +.\" commit 45eca4d141c047950db48c69c8941163d0a61fcd
>   Cache format to use:
>   .IR old ,
>   .IR new ,
>   or
> -.IR compat .
> -Since glibc 2.32, the default is
> +.IR \%compat .
> +Since glibc 2.32,
> +the default is
>   .IR new .
>   .\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
> -Before that, it was
> -.IR compat .
> +Before that,
> +it was
> +.IR \%compat .
>   .TP
> -.BI "\-C " cache
> +.BI \-C\~ cache
>   Use
>   .I cache
>   instead of
>   .IR /etc/ld.so.cache .
>   .TP
> -.BI "\-f " conf
> +.BI \-f\~ conf
>   Use
>   .I conf
>   instead of
>   .IR /etc/ld.so.conf .
> -.\" FIXME glibc 2.7 added -i

And this is why comments are harmful.  I fint it rather uncommon for comments to 
be up-to-date with the code :P

>   .TP
> -.BR \-i ", " \-\-ignore\-aux\-cache
> +.B \-i
> +.TQ
> +.B \-\-ignore\-aux\-cache
>   (Since glibc 2.7)
> -.\"             commit 27d9ffda17df4d2388687afd12897774fde39bcc
> +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc
>   Ignore auxiliary cache file.
>   .TP
>   .B \-l
> @@ -154,31 +177,40 @@ Implies

[...]


-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4345 bytes --]



On 1/4/23 13:26, Alejandro Colomar wrote:
> Hi Branden,
> 
> On 1/4/23 08:38, G. Branden Robinson wrote:
>> * Drop stale FIXME annotation regarding commit ID for `-i` option.
>> * Rewrite synopses to use man(7) font macros instead of *roff font
>>    selection escape sequences.
>> * Drop redundant `PD` macro calls.
>> * Rewrite option list to use man(7) font macros instead of *roff font
>>    selection escape sequences.
>> * Use `TQ` macro to include multiple tags for options with long synonyms
>>    instead of comma notation.

BTW, this would qualify as a style change (in my book, a ffix).  No?

Cheers,

Alex

>> * Break input lines after commas.
>> * Set multi-word parentheticals on their own input lines.
>> * Break input lines at phrase boundaries more often.
>> * Protect literals from automatic hyphenation with `\%` escape sequence.
>> * Use \~ escape sequence instead of quoted arguments at word
>>    boundaries in option synopses.
>>
>> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> 
> This patch looks good to me.  However, I didn't apply it, since I have a few 
> comments below.
>> ---
>>   man8/ldconfig.8 | 109 +++++++++++++++++++++++++++++++-----------------
>>   1 file changed, 71 insertions(+), 38 deletions(-)
>>
>> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
>> index d608aaf56..0e74c1791 100644
>> --- a/man8/ldconfig.8
>> +++ b/man8/ldconfig.8
>> @@ -9,22 +9,29 @@
>>   .SH NAME
>>   ldconfig \- configure dynamic linker run-time bindings
>>   .SH SYNOPSIS
> 
> We should wrap this in .nf/.fi
> 
> Although maybe this goes better in the style patch, since it's a formatting fix.
> 
>> -.BR /sbin/ldconfig " [" \-nNvXV "] [" \-f " \fIconf\fP] [" \-C " \fIcache\fP] 
>> [" \-r " \fIroot\fP]"
>> -.IR directory \...
>>   .PD 0
>> +.\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache,
>> +.\" --verbose, -V, --version, -?, --help, --usage
>> +.B /sbin/ldconfig
>> +.RB [ \-nNvXV ]
>> +.RB [ \-f
>> +.IR conf ]
>> +.RB [ \-C
>> +.IR cache ]
>> +.RB [ \-r
>> +.IR root ]
>> +.IR directory ...
>>   .PP
>> -.PD
>>   .B /sbin/ldconfig
>>   .B \-l
>>   .RB [ \-v ]
>> -.IR library \...
>> -.PD 0
>> +.IR library ...
>>   .PP
>> -.PD
>>   .B /sbin/ldconfig
>>   .B \-p
>> +.PD
>>   .SH DESCRIPTION
>> -.B ldconfig
>> +.B \%ldconfig
> 
> I will suggest again that I believe \% should be the default in manual pages. 
> Count how many times you want to break highlighted stuff vs how many times you 
> want to not break such stuff.
> 
>>   creates the necessary links and cache to the most recent shared
>>   libraries found in the directories specified on the command line,
>>   in the file
>> @@ -37,7 +44,8 @@ and
> 
> [...]
> 
>> @@ -105,35 +122,41 @@ Failure to follow this pattern may result in 
>> compatibility issues
>>   after an upgrade.
>>   .SH OPTIONS
>>   .TP
>> -.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
>> +.BI \-c\~ fmt
>> +.TQ
>> +.BI \-\-format= fmt
>>   (Since glibc 2.2)
>> +.\" commit 45eca4d141c047950db48c69c8941163d0a61fcd
>>   Cache format to use:
>>   .IR old ,
>>   .IR new ,
>>   or
>> -.IR compat .
>> -Since glibc 2.32, the default is
>> +.IR \%compat .
>> +Since glibc 2.32,
>> +the default is
>>   .IR new .
>>   .\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
>> -Before that, it was
>> -.IR compat .
>> +Before that,
>> +it was
>> +.IR \%compat .
>>   .TP
>> -.BI "\-C " cache
>> +.BI \-C\~ cache
>>   Use
>>   .I cache
>>   instead of
>>   .IR /etc/ld.so.cache .
>>   .TP
>> -.BI "\-f " conf
>> +.BI \-f\~ conf
>>   Use
>>   .I conf
>>   instead of
>>   .IR /etc/ld.so.conf .
>> -.\" FIXME glibc 2.7 added -i
> 
> And this is why comments are harmful.  I fint it rather uncommon for comments to 
> be up-to-date with the code :P
> 
>>   .TP
>> -.BR \-i ", " \-\-ignore\-aux\-cache
>> +.B \-i
>> +.TQ
>> +.B \-\-ignore\-aux\-cache
>>   (Since glibc 2.7)
>> -.\"             commit 27d9ffda17df4d2388687afd12897774fde39bcc
>> +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc
>>   Ignore auxiliary cache file.
>>   .TP
>>   .B \-l
>> @@ -154,31 +177,40 @@ Implies
> 
> [...]
> 
> 

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2395 bytes --]

Hi Alex,

At 2023-01-04T13:26:33+0100, Alejandro Colomar wrote:
> This patch looks good to me.  However, I didn't apply it, since I have
> a few comments below.

Ok.  V3, here we come!

> >   .SH NAME
> >   ldconfig \- configure dynamic linker run-time bindings
> >   .SH SYNOPSIS
> 
> We should wrap this in .nf/.fi

That will have a cost.  It will mean using a lot of \c escape sequences
to connect the output lines.

The existing synopsis fits within 74 output columns on a terminal.

Do you think it's worth it?

> Although maybe this goes better in the style patch, since it's a
> formatting fix.

I can shift it.

> I will suggest again that I believe \% should be the default in manual
> pages. Count how many times you want to break highlighted stuff vs how
> many times you want to not break such stuff.

I don't see good prospects of this for the same reason that I was able
to talk Ingo Schwarze out of keeping section headings in shouting
capitals.  It's a matter of preference, but one preference means
discarding information irrevocably in the source document, and the other
means that the information is present but unused.

groff man(7) _has_ a mechanism for this, and has since groff 1.19
(2003).  It's the `HY` register.  People can put this in their man.local
files (on Debian-based systems, that's in /etc/groff).

.nr HY 0

Colin Watson's man-db man(1) also has a feature to suppress hyphenation,
using a hack; it's not pretty but it works even on other *roff
formatters.

I don't insist that people keep hyphenation enabled, but assuming that
no one will do so will keep us from putting worthwhile information in
our man pages.

If you dread the tedium of adding \% escape sequences to "keywords" all
over the place, I don't blame you.  This is one reason I proposed my
most ambitious man(7) extension yet, a two-macro semantic tag mechanism.

https://marc.info/?l=linux-man&m=165868366126909&w=2

As with the new `MR` in groff 1.23, you could then suppress hyphenation
in the internal macros that wrap "tagged" keywords.

> > -.\" FIXME glibc 2.7 added -i
> 
> And this is why comments are harmful.  I fint it rather uncommon for
> comments to be up-to-date with the code :P

I generally find FIXME comments useful.  It's a happy day when I find
one that's already been addressed.  :)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 358 bytes --]

Hi Alex,

At 2023-01-04T13:36:38+0100, Alejandro Colomar wrote:
> On 1/4/23 13:26, Alejandro Colomar wrote:
> > > * Use `TQ` macro to include multiple tags for options with long synonyms
> > >    instead of comma notation.
> 
> BTW, this would qualify as a style change (in my book, a ffix).  No?

Sure.  I will reclassify it.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4099 bytes --]

Hi Branden,

On 1/4/23 16:55, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-04T13:26:33+0100, Alejandro Colomar wrote:
>> This patch looks good to me.  However, I didn't apply it, since I have
>> a few comments below.
> 
> Ok.  V3, here we come!
> 
>>>    .SH NAME
>>>    ldconfig \- configure dynamic linker run-time bindings
>>>    .SH SYNOPSIS
>>
>> We should wrap this in .nf/.fi
> 
> That will have a cost.  It will mean using a lot of \c escape sequences
> to connect the output lines.
> 
> The existing synopsis fits within 74 output columns on a terminal.
> 
> Do you think it's worth it?

But, it we don't use it, if someone uses a smaller terminal, there might appear 
our beloved hyphens breaking a word...

> 
>> Although maybe this goes better in the style patch, since it's a
>> formatting fix.
> 
> I can shift it.
> 
>> I will suggest again that I believe \% should be the default in manual
>> pages. Count how many times you want to break highlighted stuff vs how
>> many times you want to not break such stuff.
> 
> I don't see good prospects of this for the same reason that I was able
> to talk Ingo Schwarze out of keeping section headings in shouting
> capitals.  It's a matter of preference, but one preference means
> discarding information irrevocably in the source document, and the other
> means that the information is present but unused.

Is there anything that "reverts" \%?  So that if it were the default, we could 
use \anti-% to say "groff, you might break this word"?

> 
> groff man(7) _has_ a mechanism for this, and has since groff 1.19
> (2003).  It's the `HY` register.  People can put this in their man.local
> files (on Debian-based systems, that's in /etc/groff).
> 
> .nr HY 0

I know, but I don't think we should write manual pages in a way that forces 
distributors to use such a thing.  Either the pages are written plagued with \%, 
and the distros don't need to use .HY, or we write pages lazily so that distros 
need to fix the hyphenation.  But writing the pages lazily and having 
distributors ignore it would result in suboptimal pages for our readers.

> 
> Colin Watson's man-db man(1) also has a feature to suppress hyphenation,
> using a hack; it's not pretty but it works even on other *roff
> formatters.

Does that disable hyphenation for macros, or for the entire document?  I only 
want to disable it in highlighting macros.

> 
> I don't insist that people keep hyphenation enabled, but assuming that
> no one will do so will keep us from putting worthwhile information in
> our man pages.
> 
> If you dread the tedium of adding \% escape sequences to "keywords" all
> over the place, I don't blame you.  This is one reason I proposed my
> most ambitious man(7) extension yet, a two-macro semantic tag mechanism.
> 
> https://marc.info/?l=linux-man&m=165868366126909&w=2

I still don't know what to think about that.

> 
> As with the new `MR` in groff 1.23, you could then suppress hyphenation
> in the internal macros that wrap "tagged" keywords.
> 
>>> -.\" FIXME glibc 2.7 added -i
>>
>> And this is why comments are harmful.  I fint it rather uncommon for
>> comments to be up-to-date with the code :P
> 
> I generally find FIXME comments useful.  It's a happy day when I find
> one that's already been addressed.  :)

:)

I had fun with one last month:

<https://github.com/shadow-maint/shadow/commit/428a2078b6c435f1780ec8f381033e7bd937d29e>

I'll quote it here:

"XXX - quick hack, should disappear before anyone notices :)."

Of course, the quick hack never disappeared after Oct 7, 2007, when it was 
written in stone.

I have plans to get rid of it, but other dinosaurs and magic creatures keep 
getting in my way.


And another one (this one I got rid of it):

<https://github.com/shadow-maint/shadow/commit/6b6e005ce1cc4a5e4fc7fc40a52f2ed229f54b5b>

"XXX - is the above ok or should it be <time.h> on ultrix?"

> 
> Regards,
> Branden

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 7141 bytes --]

Hi Alex,

At 2023-01-04T19:41:51+0100, Alejandro Colomar wrote:
> On 1/4/23 16:55, G. Branden Robinson wrote:
> > At 2023-01-04T13:26:33+0100, Alejandro Colomar wrote:
> > > >    .SH NAME
> > > >    ldconfig \- configure dynamic linker run-time bindings
> > > >    .SH SYNOPSIS
> > > 
> > > We should wrap this in .nf/.fi
> > 
> > That will have a cost.  It will mean using a lot of \c escape
> > sequences to connect the output lines.
> > 
> > The existing synopsis fits within 74 output columns on a terminal.
> > 
> > Do you think it's worth it?
> 
> But, it we don't use it, if someone uses a smaller terminal, there
> might appear our beloved hyphens breaking a word...

That's true.  But what is _not_ true is that you don't have a minimum
expected terminal width.  You do, you just might not know what it is and
it may not even have been consciously chosen.

The minimum expected terminal width for the Linux man-pages corpus is
the longest output line produced by an unfilled (.nf/.fi) region or a
tbl(1) row that doesn't use a text block.  Somewhere in the ~2,539 man
pages, a longest unfilled line lurks...and its identity may change
depending on the output device used to render it (terminal vs.
typesetter).

If you _do_ know what that expected minimum is, please document it.

The nearest thing I see is:

"Please limit source code line length to no more than about 75
characters wherever possible." -- man-pages(7)

But the relationship between input document line length for and
formatted output line length is a loose one.

In any event, groff man(7)'s SY/YS extension macros are _built_ for this
application.  I'm happy to "port" this page to use them; doing so will
permit removal of the PD macro calls, among other benefits.

> Is there anything that "reverts" \%?  So that if it were the default,
> we could use \anti-% to say "groff, you might break this word"?

Yes.  \% itself does that.

From the groff 1.23 Texinfo manual (with stuff irrelevant to man(7)
usage stripped out):

 -- Escape sequence: \%
 -- Escape sequence: \:
     To tell GNU 'troff' how to hyphenate words as they occur in input,
     use the '\%' escape sequence; it is the default "hyphenation
     character".  Each instance within a word indicates to GNU 'troff'
     that the word may be hyphenated at that point, while prefixing a
     word with this escape sequence prevents it from being otherwise
     hyphenated.  This mechanism affects only that occurrence of the
     word; [...]

[...]

     '\:' inserts a non-printing break point; that is, a word can break
     there, but the soft hyphen glyph (see below) is not written to the
     output if it does.  This escape sequence is an input word boundary,
     so the remainder of the word is subject to hyphenation as normal.

     You can use '\:' and '\%' in combination to control breaking of a
     file name or URL or to permit hyphenation only after certain
     explicit hyphens within a word.

          The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
          was, in retrospect, inevitable once the contents of
          \%/var/log/\:\%httpd/\:\%access_log on the family web
          server came to light, revealing visitors from Hogwarts.

> > groff man(7) _has_ a mechanism for this, and has since groff 1.19
> > (2003).  It's the `HY` register.  People can put this in their
> > man.local files (on Debian-based systems, that's in /etc/groff).
> > 
> > .nr HY 0
> 
> I know, but I don't think we should write manual pages in a way that
> forces distributors to use such a thing.

As far as I know, most distributors aren't configuring man.local this
way today, despite it having been possible for almost 20 years.  Adding
explicit hyphenation breakpoints (or their suppression) isn't going to
force them any harder than they have been for 2 decades; it will in fact
reduce any such pressure by reducing the number of bogus hyphenation
breaks when hyphenation is enabled.

> Either the pages are written plagued with \%,

Like changes in lettercase, this is _information_.

> and the distros don't need to use .HY, or we write pages lazily so
> that distros need to fix the hyphenation.

Distributors' laziness seems to be a match for Linux man-pages's own;
users seem to muddle through without much evident complaint.  I suppose
people who copy-and-paste multiple lines from a man page realize they
need to remove the hyphens along with newlines.  Fortunately, on UTF-8
terminals, they have hope of seeing the difference between hyphens and
the ASCII hyphen-minus that is always(?) meant as a literal.

> But writing the pages lazily and having distributors ignore it would
> result in suboptimal pages for our readers.

I think marking break points, hyphenated and otherwise (as with URLs),
is the opposite of laziness.  It is a level of fastidiousness I don't
actually expect of many man(7) writers apart from myself.

> > Colin Watson's man-db man(1) also has a feature to suppress
> > hyphenation, using a hack; it's not pretty but it works even on
> > other *roff formatters.
> 
> Does that disable hyphenation for macros, or for the entire document?
> I only want to disable it in highlighting macros.

I don't quite understand what you mean by "macros" here.  Macro
interpolation is textual replacement, there isn't really a macro "mode"
that is visible to the formatter when hyphenation decisions are made.

But if by "highlighting macros" you mean font selection and
alternation macros in man(7) (.B, .I, .BR, etc.), then the answer is
"for the entire document".  You don't always want to disable hyphenation
when using these macros anyway.  Not everything is a literal.  The font
macros are presentational, not semantic.

Even then, I would not suppress hyphenation of a metasyntactic variable,
like "directory".  The whole point of these is that they are textually
replaced _by the reader_.

> > I don't insist that people keep hyphenation enabled, but assuming
> > that no one will do so will keep us from putting worthwhile
> > information in our man pages.
> > 
> > If you dread the tedium of adding \% escape sequences to "keywords"
> > all over the place, I don't blame you.  This is one reason I
> > proposed my most ambitious man(7) extension yet, a two-macro
> > semantic tag mechanism.
> > 
> > https://marc.info/?l=linux-man&m=165868366126909&w=2
> 
> I still don't know what to think about that.

That's okay.  Its realization is some ways off, if ever.  First I need
Bertrand to recover from holidays.  :-O

> "XXX - quick hack, should disappear before anyone notices :)."
> 
> Of course, the quick hack never disappeared after Oct 7, 2007, when it
> was written in stone.

Of course!

> <https://github.com/shadow-maint/shadow/commit/6b6e005ce1cc4a5e4fc7fc40a52f2ed229f54b5b>
> 
> "XXX - is the above ok or should it be <time.h> on ultrix?"

If you pine for a stagnant commercial Unix to kick around, Solaris 10
will be around for another year or so...

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 10210 bytes --]

Hi Branden,

On 1/4/23 20:11, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-04T19:41:51+0100, Alejandro Colomar wrote:
>> On 1/4/23 16:55, G. Branden Robinson wrote:
>>> At 2023-01-04T13:26:33+0100, Alejandro Colomar wrote:
>>>>>     .SH NAME
>>>>>     ldconfig \- configure dynamic linker run-time bindings
>>>>>     .SH SYNOPSIS
>>>>
>>>> We should wrap this in .nf/.fi
>>>
>>> That will have a cost.  It will mean using a lot of \c escape
>>> sequences to connect the output lines.
>>>
>>> The existing synopsis fits within 74 output columns on a terminal.
>>>
>>> Do you think it's worth it?
>>
>> But, it we don't use it, if someone uses a smaller terminal, there
>> might appear our beloved hyphens breaking a word...
> 
> That's true.  But what is _not_ true is that you don't have a minimum
> expected terminal width.  You do, you just might not know what it is and
> it may not even have been consciously chosen.

I haven't consciously chosen it, but I often use 66-col terminals, especially 
when I plan to paste text into an email.

> 
> The minimum expected terminal width for the Linux man-pages corpus is
> the longest output line produced by an unfilled (.nf/.fi) region or a
> tbl(1) row that doesn't use a text block.  Somewhere in the ~2,539 man
> pages, a longest unfilled line lurks...and its identity may change
> depending on the output device used to render it (terminal vs.
> typesetter).

Even if unfilled blocks exceed the terminal width, and therefore might be 
unpleasant to the eyes, they have a nice feature: the line never breaks, and you 
can still pipe it to other programs, or paste it, and it will be a single line.

> 
> If you _do_ know what that expected minimum is, please document it.
> 
> The nearest thing I see is:
> 
> "Please limit source code line length to no more than about 75
> characters wherever possible." -- man-pages(7)
> 
> But the relationship between input document line length for and
> formatted output line length is a loose one.
> 
> In any event, groff man(7)'s SY/YS extension macros are _built_ for this
> application.  I'm happy to "port" this page to use them; doing so will
> permit removal of the PD macro calls, among other benefits.

Yup, that would be nice!

> 
>> Is there anything that "reverts" \%?  So that if it were the default,
>> we could use \anti-% to say "groff, you might break this word"?
> 
> Yes.  \% itself does that.
I mean something like \X\%foobar, so that the \X "cancels" the \%.  Not manually 
inserting break points.  So, imagining a world in which hyphenation was disabled 
_only_ within font-selection macros, I could specify that a word is fine to be 
hyphenated like this:

.B \Xidontcareifthisishyphenated

> 
>  From the groff 1.23 Texinfo manual (with stuff irrelevant to man(7)
> usage stripped out):
> 
>   -- Escape sequence: \%
>   -- Escape sequence: \:
>       To tell GNU 'troff' how to hyphenate words as they occur in input,
>       use the '\%' escape sequence; it is the default "hyphenation
>       character".  Each instance within a word indicates to GNU 'troff'
>       that the word may be hyphenated at that point, while prefixing a
>       word with this escape sequence prevents it from being otherwise
>       hyphenated.  This mechanism affects only that occurrence of the
>       word; [...]
> 
> [...]
> 
>       '\:' inserts a non-printing break point; that is, a word can break
>       there, but the soft hyphen glyph (see below) is not written to the
>       output if it does.  This escape sequence is an input word boundary,
>       so the remainder of the word is subject to hyphenation as normal.
> 
>       You can use '\:' and '\%' in combination to control breaking of a
>       file name or URL or to permit hyphenation only after certain
>       explicit hyphens within a word.
> 
>            The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
>            was, in retrospect, inevitable once the contents of
>            \%/var/log/\:\%httpd/\:\%access_log on the family web
>            server came to light, revealing visitors from Hogwarts.
> 
>>> groff man(7) _has_ a mechanism for this, and has since groff 1.19
>>> (2003).  It's the `HY` register.  People can put this in their
>>> man.local files (on Debian-based systems, that's in /etc/groff).
>>>
>>> .nr HY 0
>>
>> I know, but I don't think we should write manual pages in a way that
>> forces distributors to use such a thing.
> 
> As far as I know, most distributors aren't configuring man.local this
> way today, despite it having been possible for almost 20 years.

Touche.

>  Adding
> explicit hyphenation breakpoints (or their suppression) isn't going to
> force them any harder than they have been for 2 decades; it will in fact
> reduce any such pressure by reducing the number of bogus hyphenation
> breaks when hyphenation is enabled.
> 
>> Either the pages are written plagued with \%,
> 
> Like changes in lettercase, this is _information_.

I don't argue against that, but if there was a way to return that information 
explicitly, we wouldn't be loosing it.

> 
>> and the distros don't need to use .HY, or we write pages lazily so
>> that distros need to fix the hyphenation.
> 
> Distributors' laziness seems to be a match for Linux man-pages's own;
> users seem to muddle through without much evident complaint.

Oh, I do complain a lot; however, I don't express it too much in the form of bug 
reports, since I don't believe it's the fault of the writer, but rather lack of 
support from groff(1).

But I do find it very uncomfortable, similar to when manual page authors don't 
use the proper \-.  However, I do think that one is fault of the author, and you 
can already find many such reports signed by me :)

>  I suppose
> people who copy-and-paste multiple lines from a man page realize they
> need to remove the hyphens along with newlines.  Fortunately, on UTF-8
> terminals, they have hope of seeing the difference between hyphens and
> the ASCII hyphen-minus that is always(?) meant as a literal.

My problem is not about pasting text.  That's very minor.  My problem is finding 
text.

For finding command options, I usually type:

/   --foo

If \- hasn't been used, I need to use:

/   ..foo

and skip all the noise.  When there's too much noise, sometimes using an anchor 
(^) helps.  But it's way nicer when writers use \-.  I keep finding such bugs, 
and reporting them as much as I can.

When searching for keywords, the problem is the following:  I do `/keyword`, but 
then if the keyword is hyphenated... well, good luck.

> 
>> But writing the pages lazily and having distributors ignore it would
>> result in suboptimal pages for our readers.
> 
> I think marking break points, hyphenated and otherwise (as with URLs),
> is the opposite of laziness.  It is a level of fastidiousness I don't
> actually expect of many man(7) writers apart from myself.

I would want to use \:.  What I want is a tool which re-enables the default 
hyphenation points after they have been cancelled.

> 
>>> Colin Watson's man-db man(1) also has a feature to suppress
>>> hyphenation, using a hack; it's not pretty but it works even on
>>> other *roff formatters.
>>
>> Does that disable hyphenation for macros, or for the entire document?
>> I only want to disable it in highlighting macros.
> 
> I don't quite understand what you mean by "macros" here.  Macro
> interpolation is textual replacement, there isn't really a macro "mode"
> that is visible to the formatter when hyphenation decisions are made.
> 
> But if by "highlighting macros" you mean font selection and
> alternation macros in man(7) (.B, .I, .BR, etc.), then the answer is
> "for the entire document".  You don't always want to disable hyphenation
> when using these macros anyway.  Not everything is a literal.  The font
> macros are presentational, not semantic.
> 
> Even then, I would not suppress hyphenation of a metasyntactic variable,
> like "directory".  The whole point of these is that they are textually
> replaced _by the reader_.

I would.  I wouldn't be able to count how many times I've tried to search for 
such a keyword, and it was hyphenated.

> 
>>> I don't insist that people keep hyphenation enabled, but assuming
>>> that no one will do so will keep us from putting worthwhile
>>> information in our man pages.
>>>
>>> If you dread the tedium of adding \% escape sequences to "keywords"
>>> all over the place, I don't blame you.  This is one reason I
>>> proposed my most ambitious man(7) extension yet, a two-macro
>>> semantic tag mechanism.
>>>
>>> https://marc.info/?l=linux-man&m=165868366126909&w=2
>>
>> I still don't know what to think about that.
> 
> That's okay.  Its realization is some ways off, if ever.  First I need
> Bertrand to recover from holidays.  :-O
> 
>> "XXX - quick hack, should disappear before anyone notices :)."
>>
>> Of course, the quick hack never disappeared after Oct 7, 2007, when it
>> was written in stone.
> 
> Of course!
> 
>> <https://github.com/shadow-maint/shadow/commit/6b6e005ce1cc4a5e4fc7fc40a52f2ed229f54b5b>
>>
>> "XXX - is the above ok or should it be <time.h> on ultrix?"
> 
> If you pine for a stagnant commercial Unix to kick around, Solaris 10
> will be around for another year or so...

Solaris 10, I already remove code that supports it at every chance that I have :)

I wonder when the day will come that things like C89 will officially be declared 
dead by consensus.  I wish GCC would drop -std=gnu89 some day.

Seeing how some people strongly defend portability to dinosaur shells, because 
POSIX is not portable enough...  well, I don't think we'll get rid of C89 in 
another 50 years...

But hey, when you don't care about big piles o'money, you can write 
"non-portable" POSIX-only code.  I prefer writing non-portable code, than 
Solaris-3-portable code for a big pile o'money. :)

> 
> Regards,
> Branden

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 7290 bytes --]

Hi Alex,

At 2023-01-04T21:15:00+0100, Alejandro Colomar wrote:
> > That's true.  But what is _not_ true is that you don't have a
> > minimum expected terminal width.  You do, you just might not know
> > what it is and it may not even have been consciously chosen.
> 
> I haven't consciously chosen it, but I often use 66-col terminals,
> especially when I plan to paste text into an email.

Well, by "you" I mean in your capacity as Linux man-pages maintainer.

There is some threshold of terminal width in the corpus of pages below
which things start to look really horrible.

Maybe you'd like my shell wrapper for man(1).

    # View a man page but report all warnings.
    man () {
        if command man "$@"
        then
            command man --warnings=w "$@" >/dev/null
        fi
    }

It shows me the formatter's warnings _after_ the page is rendered.

> Even if unfilled blocks exceed the terminal width, and therefore might
> be unpleasant to the eyes, they have a nice feature: the line never
> breaks, and you can still pipe it to other programs, or paste it, and
> it will be a single line.

You can therefore simulate this for any man page by setting the `LL`
register to some large value.  Once it exceeds your terminal width, it
will certainly be ugly as hell, but if you want line-by-line
piping/pasting, maybe you'll find it useful.

    -rLL=line‐length
        Set line length; the default is 78n for terminal devices and
        6.5i for typesetter devices.

man-db man(1) simulates this with the MANWIDTH environment variable.
Presently it uses a hack, which I hope will go away after groff 1.23.

https://savannah.gnu.org/bugs/index.php?58992

> > In any event, groff man(7)'s SY/YS extension macros are _built_ for
> > this application.  I'm happy to "port" this page to use them; doing
> > so will permit removal of the PD macro calls, among other benefits.
> 
> Yup, that would be nice!

Okay, there's another change for v3, then!  :)

> > > Is there anything that "reverts" \%?  So that if it were the
> > > default, we could use \anti-% to say "groff, you might break this
> > > word"?
> > 
> > Yes.  \% itself does that.
>
> I mean something like \X\%foobar, so that the \X "cancels" the \%.
> Not manually inserting break points.  So, imagining a world in which
> hyphenation was disabled _only_ within font-selection macros, I could
> specify that a word is fine to be hyphenated like this:
> 
> .B \Xidontcareifthisishyphenated

Hmm, no, there is no *roff escape sequence for "apply automatic
hyphenation to the following word".

But your hypothetical is already a counterfactual.  Macros like .B
_already_ don't disable hyphenation.  So it seems to me like you're
proposing second-order machinery to get yourself out of the bind you're
creating with your first-order demand to make the font macros disable
hyphenation.

It really seems better to me to leave the font macros alone and have
a semantic tagging facility for those things you really don't want
hyphenated.

Or, proceed as the groff man pages have to date, stick to the font
selection macros as they are, and use \% with them.

Most of the 94 printable Basic Latin characters already have meaning
as *roff escape sequences when preceded by an escape character.  The
scarce name space that remains must be occupied only with great
consideration.  Dave Kemper and I have kicked around ideas for an
"extension" character for escape sequences to surmount this problem.  \<
is available, and despite giving me nightmare memories of HTML, it might
be the best choice among what remains.[1]

> > Like changes in lettercase, this is _information_.
> 
> I don't argue against that, but if there was a way to return that
> information explicitly, we wouldn't be loosing it.

As noted above, I think a good way to achieve that is by not discarding
it such that it needs recovery later.

> Oh, I do complain a lot; however, I don't express it too much in the
> form of bug reports, since I don't believe it's the fault of the
> writer, but rather lack of support from groff(1).

I don't think groff is missing support for anything you want here; we
have a disagreement over the design of the man(7) package.

> But I do find it very uncomfortable, similar to when manual page authors
> don't use the proper \-.  However, I do think that one is fault of the
> author, and you can already find many such reports signed by me :)

My Debian colleagues teased me twenty years for railing against man
pages that didn't escape their hyphens.  I was an early adopter of UTF-8
terminal emulators.

> > I suppose people who copy-and-paste multiple lines from a man page
> > realize they need to remove the hyphens along with newlines.
> > Fortunately, on UTF-8 terminals, they have hope of seeing the
> > difference between hyphens and the ASCII hyphen-minus that is
> > always(?) meant as a literal.
> 
> My problem is not about pasting text.  That's very minor.  My problem
> is finding text.

Yes, I've seen many people complain about this, justifiably, over the
years.  When people leave hyphenation enabled and try full-text searches
of man pages, often inside less(1), they get frustrated by the broken
words.

> For finding command options, I usually type:
> 
> /   --foo
> 
> If \- hasn't been used, I need to use:
> 
> /   ..foo
> 
> and skip all the noise.  When there's too much noise, sometimes using
> an anchor (^) helps.  But it's way nicer when writers use \-.  I keep
> finding such bugs, and reporting them as much as I can.

Yup.  Improving hyphen-minus hygiene here produces wins.

> When searching for keywords, the problem is the following:  I do
> `/keyword`, but then if the keyword is hyphenated... well, good luck.

Right.  less(1) is an interesting program.  It has lots of features,
many more than any one user will use.  But it seems to be pretty
indifferent to helping with searches for hyphenated words.

It's _possible_ to design an extension to ISO 6429 for communicating
hyphenation break information to terminals (and pagers).  A big question
is what would bother to use that information.  If Mark Nudelmann doesn't
want to support it, it's DOA, and he views ISO 6429 grudgingly enough in
the first place, hence "less -R".

I have only two recommendations.

1.  Disable hyphenation in your man.local; or
2.  Back my play for semantic tagging in man(7).  ;-)

> > I think marking break points, hyphenated and otherwise (as with
> > URLs), is the opposite of laziness.  It is a level of fastidiousness
> > I don't actually expect of many man(7) writers apart from myself.
> 
> I would want to use \:.  What I want is a tool which re-enables the
> default hyphenation points after they have been cancelled.

I submit again: if you don't cancel them in the first place, they don't
have to be reconstructed.

> I would.  I wouldn't be able to count how many times I've tried to
> search for such a keyword, and it was hyphenated.

Semantic tags would solve this problem.

Regards,
Branden

[1] What's available?

    \+ \1 \2 \3 \4 \5 \6 \7 \8 \9 \; \< \= \> \@
    \G \i \I \j \J \P \T \U \W \y \]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/9] ldconfig.8: Fix markup nits

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 6279 bytes --]

Hi Branden,

On 1/4/23 21:59, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-04T21:15:00+0100, Alejandro Colomar wrote:
>>> That's true.  But what is _not_ true is that you don't have a
>>> minimum expected terminal width.  You do, you just might not know
>>> what it is and it may not even have been consciously chosen.
>>
>> I haven't consciously chosen it, but I often use 66-col terminals,
>> especially when I plan to paste text into an email.
> 
> Well, by "you" I mean in your capacity as Linux man-pages maintainer.
> 
> There is some threshold of terminal width in the corpus of pages below
> which things start to look really horrible.
> 
> Maybe you'd like my shell wrapper for man(1).
> 
>      # View a man page but report all warnings.
>      man () {
>          if command man "$@"
>          then
>              command man --warnings=w "$@" >/dev/null
>          fi
>      }
> 
> It shows me the formatter's warnings _after_ the page is rendered.

Hmmm, yes, I'll get that one!

[...]

>> I mean something like \X\%foobar, so that the \X "cancels" the \%.
>> Not manually inserting break points.  So, imagining a world in which
>> hyphenation was disabled _only_ within font-selection macros, I could
>> specify that a word is fine to be hyphenated like this:
>>
>> .B \Xidontcareifthisishyphenated
> 
> Hmm, no, there is no *roff escape sequence for "apply automatic
> hyphenation to the following word".
> 
> But your hypothetical is already a counterfactual.  Macros like .B
> _already_ don't disable hyphenation.  So it seems to me like you're
> proposing second-order machinery to get yourself out of the bind you're
> creating with your first-order demand to make the font macros disable
> hyphenation.
> 
> It really seems better to me to leave the font macros alone and have
> a semantic tagging facility for those things you really don't want
> hyphenated.
> 
> Or, proceed as the groff man pages have to date, stick to the font
> selection macros as they are, and use \% with them.
> 
> Most of the 94 printable Basic Latin characters already have meaning
> as *roff escape sequences when preceded by an escape character.  The
> scarce name space that remains must be occupied only with great
> consideration.  Dave Kemper and I have kicked around ideas for an
> "extension" character for escape sequences to surmount this problem.  \<
> is available, and despite giving me nightmare memories of HTML, it might
> be the best choice among what remains.[1]
> 
>>> Like changes in lettercase, this is _information_.
>>
>> I don't argue against that, but if there was a way to return that
>> information explicitly, we wouldn't be loosing it.
> 
> As noted above, I think a good way to achieve that is by not discarding
> it such that it needs recovery later.
> 
>> Oh, I do complain a lot; however, I don't express it too much in the
>> form of bug reports, since I don't believe it's the fault of the
>> writer, but rather lack of support from groff(1).
> 
> I don't think groff is missing support for anything you want here; we
> have a disagreement over the design of the man(7) package.

Yes, that might be another way to phrase it; probably a more accurate one.

So, you defend hyphenation within .I and .B because they are not semantic macros.

But, of course, by presenting a word differently, you're implying that it's more 
important than the surrounding words.  And since we try to avoid overuse of 
presentational macros, this importance should be somewhat consistent.

If a word is more important than the others, it is very likely that readers will 
try to search for it more often (for which hyphenation is a big problem in less(1)).

It also makes sense to not hyphenate it so that it stands more readable.

Isn't it an exception when you don't mind hyphenating a B or I word, rather than 
a rule?

Do you have any statistics?  Could you get an approximate ratio of words where 
you don't mind at all hyphenating, compared to those where you don't want 
hyphenation?

Something like of course restricted to B or I words):

	                       words that can hyphenate
         -----------------------------------------------------------------------
         words that can't hyphenate  +  w. that use \%  +  w. that can hyphenate

Could you get that from groff's pages?  I expect those will be the most 
consistent ones in use of \%.

I expect that to be less than 0.1; probably even below 0.01.  Isn't that a good 
hint that it would be better to flip the default there?

[...]

>>
>> My problem is not about pasting text.  That's very minor.  My problem
>> is finding text.
> 
> Yes, I've seen many people complain about this, justifiably, over the
> years.  When people leave hyphenation enabled and try full-text searches
> of man pages, often inside less(1), they get frustrated by the broken
> words.
> 

Yeah, for full-text searches, I cd(1) into the man-pages dir and search in the 
source :).

[...]

> 
> I have only two recommendations.
> 
> 1.  Disable hyphenation in your man.local; or

I try to avoid custom configuration files.  That has several advantages; one of 
them in the case of manual pages is noticing when inexpert users will find them 
less useful than I will.

> 2.  Back my play for semantic tagging in man(7).  ;-)

:)

> 
>>> I think marking break points, hyphenated and otherwise (as with
>>> URLs), is the opposite of laziness.  It is a level of fastidiousness
>>> I don't actually expect of many man(7) writers apart from myself.
>>
>> I would want to use \:.  What I want is a tool which re-enables the
>> default hyphenation points after they have been cancelled.
> 
> I submit again: if you don't cancel them in the first place, they don't
> have to be reconstructed.
> 
>> I would.  I wouldn't be able to count how many times I've tried to
>> search for such a keyword, and it was hyphenated.
> 
> Semantic tags would solve this problem.
> 
> Regards,
> Branden
> 
> [1] What's available?
> 
>      \+ \1 \2 \3 \4 \5 \6 \7 \8 \9 \; \< \= \> \@
>      \G \i \I \j \J \P \T \U \W \y \]

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]