[PATCH] scripts/LinuxManBook/gropdf: use symlink instead of hard coded groff version

[PATCH] scripts/LinuxManBook/gropdf: use symlink instead of hard coded groff version

[Brian Inglis]

man-pages custom script gropdf has hard coded groff version used in font path
groff provides symlink current for version to avoid the issue; use it in gropdf
specify failing font path used to open font description file in error message

Signed-off-by: Brian Inglis <Brian.Inglis@Shaw.ca>
---
 scripts/LinuxManBook/gropdf | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/LinuxManBook/gropdf b/scripts/LinuxManBook/gropdf
index 8474e583f57d..fb205395015b 100755
--- a/scripts/LinuxManBook/gropdf
+++ b/scripts/LinuxManBook/gropdf
@@ -58,8 +58,8 @@ else
 
 my %cfg;
 
-$cfg{GROFF_VERSION}='1.22.4';
-$cfg{GROFF_FONT_PATH}='/usr/share/groff/site-font:/usr/share/groff/1.22.4/font:/usr/lib/font';
+$cfg{GROFF_VERSION}='current';
+$cfg{GROFF_FONT_PATH}="/usr/share/groff/site-font:/usr/share/groff/$cfg{GROFF_VERSION}/font:/usr/lib/font";
 $cfg{RT_SEP}=':';
 binmode(STDOUT);
 
@@ -690,7 +690,7 @@ sub LoadDesc
     my $f;
 
     OpenFile(\$f,$fontdir,"DESC");
-    Msg(1,"Failed to open 'DESC'") if !defined($f);
+    Msg(1,"Failed to open 'DESC' in '$fontdir'") if !defined($f);
 
     while (<$f>)
     {
-- 
2.39.0

No 6.05/.01 pdf book available

[Brian Inglis]

Hi Alex,

I noticed there appears to be no 6.05/.01 pdf book available yet.
Are there build issues?

When I run the script/LinuxManBook/BuildLinuxMan.pl, after applying the gropdf 
patch, manually in the build dir, I get a pdf, but without any man page footers.

Are there any other scripts which need to be run and/or groff commands or data 
which need to be supplied?

It would be nice to see this eventually added to your RELEASE doc, and maybe 
also to the make scripts.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: [PATCH] scripts/LinuxManBook/gropdf: use symlink instead of hard coded groff version

[Alejandro Colomar]

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

On 2023-08-07 03:16, Brian Inglis wrote:
> man-pages custom script gropdf has hard coded groff version used in font path
> groff provides symlink current for version to avoid the issue; use it in gropdf
> specify failing font path used to open font description file in error message
> 
> Signed-off-by: Brian Inglis <Brian.Inglis@Shaw.ca>

Hi Brian!

Please CC Deri, as he's the author, and will be able to review better than I can.

Thanks,
Alex

> ---
>  scripts/LinuxManBook/gropdf | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/scripts/LinuxManBook/gropdf b/scripts/LinuxManBook/gropdf
> index 8474e583f57d..fb205395015b 100755
> --- a/scripts/LinuxManBook/gropdf
> +++ b/scripts/LinuxManBook/gropdf
> @@ -58,8 +58,8 @@ else
>  
>  my %cfg;
>  
> -$cfg{GROFF_VERSION}='1.22.4';
> -$cfg{GROFF_FONT_PATH}='/usr/share/groff/site-font:/usr/share/groff/1.22.4/font:/usr/lib/font';
> +$cfg{GROFF_VERSION}='current';
> +$cfg{GROFF_FONT_PATH}="/usr/share/groff/site-font:/usr/share/groff/$cfg{GROFF_VERSION}/font:/usr/lib/font";
>  $cfg{RT_SEP}=':';
>  binmode(STDOUT);
>  
> @@ -690,7 +690,7 @@ sub LoadDesc
>      my $f;
>  
>      OpenFile(\$f,$fontdir,"DESC");
> -    Msg(1,"Failed to open 'DESC'") if !defined($f);
> +    Msg(1,"Failed to open 'DESC' in '$fontdir'") if !defined($f);
>  
>      while (<$f>)
>      {

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Brian, Deri,

On 2023-08-07 04:46, Brian Inglis wrote:
> Hi Alex,
> 
> I noticed there appears to be no 6.05/.01 pdf book available yet.
> Are there build issues?

Yup.

$ pwd
/home/alx/src/linux/man-pages/man-pages/6.04/scripts/LinuxManBook
$ ./BuildLinuxMan.pl  ../../
[...]
Failed to open 'DESC'


> 
> When I run the script/LinuxManBook/BuildLinuxMan.pl, after applying the gropdf 
> patch, manually in the build dir, I get a pdf, but without any man page footers.

Hmm, that's weird.  After applying your patch, It works fine for me.
I do see the page footers.  However, I have old builds of groff in my
system, which I haven't cleaned up, so maybe they interfere positively
to that outcome.  Maybe from a clean installation of Debian Sid I
wouldn't be able to reproduce that.

Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
for 1.22.4 which should be removed after the release of 1.23.0, so it
seems that the time has come to chop a lot of stuff from there.

Deri, would you mind simplifying the scripts assuming a Build-dep of
groff(>=1.23.0)?

> 
> Are there any other scripts which need to be run and/or groff commands or data 
> which need to be supplied?

No.  It's just:

$ cd scripts/LinuxManBook/
$ ./BuildLinuxMan.pl ../../

> 
> It would be nice to see this eventually added to your RELEASE doc, and maybe 
> also to the make scripts.

Yes.  I first want to put it in the Makefiles, and then add it to
INSTALL.  Then something to RELEASE.  But I first want to simplify
the script so I can understand it.

Cheers,
Alex

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

On 2023-08-07 10:45, Alejandro Colomar wrote:
> Hi Brian, Deri,
> 
> On 2023-08-07 04:46, Brian Inglis wrote:
>> Hi Alex,
>>
>> I noticed there appears to be no 6.05/.01 pdf book available yet.
>> Are there build issues?
> 
> Yup.
> 
> $ pwd
> /home/alx/src/linux/man-pages/man-pages/6.04/scripts/LinuxManBook
> $ ./BuildLinuxMan.pl  ../../
> [...]
> Failed to open 'DESC'
> 
> 
>>
>> When I run the script/LinuxManBook/BuildLinuxMan.pl, after applying the gropdf 
>> patch, manually in the build dir, I get a pdf, but without any man page footers.
> 
> Hmm, that's weird.  After applying your patch, It works fine for me.
> I do see the page footers.  However, I have old builds of groff in my
> system, which I haven't cleaned up, so maybe they interfere positively
> to that outcome.  Maybe from a clean installation of Debian Sid I
> wouldn't be able to reproduce that.

I have uploaded the 6.05.01 book now.

Cheers,
Alex

> 
> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
> for 1.22.4 which should be removed after the release of 1.23.0, so it
> seems that the time has come to chop a lot of stuff from there.
> 
> Deri, would you mind simplifying the scripts assuming a Build-dep of
> groff(>=1.23.0)?
> 
>>
>> Are there any other scripts which need to be run and/or groff commands or data 
>> which need to be supplied?
> 
> No.  It's just:
> 
> $ cd scripts/LinuxManBook/
> $ ./BuildLinuxMan.pl ../../
> 
>>
>> It would be nice to see this eventually added to your RELEASE doc, and maybe 
>> also to the make scripts.
> 
> Yes.  I first want to put it in the Makefiles, and then add it to
> INSTALL.  Then something to RELEASE.  But I first want to simplify
> the script so I can understand it.
> 
> Cheers,
> Alex
> 
>>
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

[PATCH] scripts/LinuxManBook/gropdf: use symlink instead of hard coded groff version

[Brian Inglis]

man-pages custom script gropdf has hard coded groff version used in font path
groff provides symlink current for version to avoid the issue; use it in gropdf
specify failing font path used to open font description file in error message

Signed-off-by: Brian Inglis <Brian.Inglis@Shaw.ca>
---
 scripts/LinuxManBook/gropdf | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/LinuxManBook/gropdf b/scripts/LinuxManBook/gropdf
index 8474e583f57d..fb205395015b 100755
--- a/scripts/LinuxManBook/gropdf
+++ b/scripts/LinuxManBook/gropdf
@@ -58,8 +58,8 @@ else
 
 my %cfg;
 
-$cfg{GROFF_VERSION}='1.22.4';
-$cfg{GROFF_FONT_PATH}='/usr/share/groff/site-font:/usr/share/groff/1.22.4/font:/usr/lib/font';
+$cfg{GROFF_VERSION}='current';
+$cfg{GROFF_FONT_PATH}="/usr/share/groff/site-font:/usr/share/groff/$cfg{GROFF_VERSION}/font:/usr/lib/font";
 $cfg{RT_SEP}=':';
 binmode(STDOUT);
 
@@ -690,7 +690,7 @@ sub LoadDesc
     my $f;
 
     OpenFile(\$f,$fontdir,"DESC");
-    Msg(1,"Failed to open 'DESC'") if !defined($f);
+    Msg(1,"Failed to open 'DESC' in '$fontdir'") if !defined($f);
 
     while (<$f>)
     {
-- 
2.39.0

Re: No 6.05/.01 pdf book available

[Brian Inglis]

On 2023-08-07 03:16, Alejandro Colomar wrote:
> On 2023-08-07 10:45, Alejandro Colomar wrote:
>> On 2023-08-07 04:46, Brian Inglis wrote:
>>> I noticed there appears to be no 6.05/.01 pdf book available yet.
>>> Are there build issues?

>> Yup.
>>
>> $ pwd
>> /home/alx/src/linux/man-pages/man-pages/6.04/scripts/LinuxManBook
>> $ ./BuildLinuxMan.pl  ../../
>> [...]
>> Failed to open 'DESC'

That annoyingly minimal message provoked the patch submitted.

>>> When I run the script/LinuxManBook/BuildLinuxMan.pl, after applying the gropdf
>>> patch, manually in the build dir, I get a pdf, but without any man page footers.

>> Hmm, that's weird.  After applying your patch, It works fine for me.
>> I do see the page footers.  However, I have old builds of groff in my
>> system, which I haven't cleaned up, so maybe they interfere positively
>> to that outcome.  Maybe from a clean installation of Debian Sid I
>> wouldn't be able to reproduce that.

> I have uploaded the 6.05.01 book now.

Nice - with current page footers!

>> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
>> for 1.22.4 which should be removed after the release of 1.23.0, so it
>> seems that the time has come to chop a lot of stuff from there.
>>
>> Deri, would you mind simplifying the scripts assuming a Build-dep of
>> groff(>=1.23.0)?

Resent the patch cc Deri.

Would it make sense to merge changes into/from groff 1.23 grodpf, which I also 
tried, and also did not produce page footers, but did produce lots of 
*different* messages.
It seems likely that changes made to build the huge man book might also benefit 
other projects with large docs.

>>> Are there any other scripts which need to be run and/or groff commands or data
>>> which need to be supplied?

>> No.  It's just:
>>
>> $ cd scripts/LinuxManBook/
>> $ ./BuildLinuxMan.pl ../../

>>> It would be nice to see this eventually added to your RELEASE doc, and maybe
>>> also to the make scripts.

>> Yes.  I first want to put it in the Makefiles, and then add it to
>> INSTALL.  Then something to RELEASE.  But I first want to simplify
>> the script so I can understand it.

See below ;^>

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Deri, Brian,

On 2023-08-08 01:14, Deri wrote:
> On Monday, 7 August 2023 09:45:22 BST Alejandro Colomar wrote:
>> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
>> for 1.22.4 which should be removed after the release of 1.23.0, so it
>> seems that the time has come to chop a lot of stuff from there.
>>
>> Deri, would you mind simplifying the scripts assuming a Build-dep of
>> groff(>=1.23.0)?
> 
> Hi Alex, Brian,
> 
> I have done some work on building the pdf. One improvement is any warnings 
> output by groff, i.e. use of the deprecated .PDF macro, now identify the 
> particular man page and line number accurately.
> 
> I have attached two new replacement LinuxManBook directories. The first, 
> 1.23.0, will run on a stock groff 1.23.0 system.

Thanks!  I've applied that change.  It's great to see the LinuxManBook/
dir reduce most of its contents.


> The second, 1.23.0+, runs 
> with the latest gropdf which has a number of advantages for this project - you 
> will find the resulting pdf to be more than 5mb smaller, and the page numbers 
> in the overview pane match up with the page number at the bottom of each page.

Hmm, I'm reluctant to apply that.  I don't want to maintain a copy of
gropdf(1) and all the files that accompany it.  However, I think that the
directory that uses the system groff (1.23.0) should work with the new
gropdf(1) from 1.23+ if I build from source in my system.

But, I installed groff from git HEAD a moment ago, and I didn't notice the
5 MiB improvements that you claimed, and the page numbers are wrong, so maybe
I'm doing something wrong, or have a non-clean groff installation in place?

> 
> The file NewGropdf.pdf contains description of some of the features in the new 
> gropdf.
> 
> Both of these should continue to work if the groff version changes, thanks to 
> Brian's helpful suggestion to include /usr/share/groff/current in the font 
> path, but I have achieved this by specifying it in an -F flag rather than 
> patching gropdf.


$ tree scripts/LinuxManBook/
scripts/LinuxManBook/
├── BuildLinuxMan.pl
├── LMBfront.t
├── an.tmac
├── anmark.tmac
├── devpdf
│   ├── TINOR
│   ├── Tinos.pfa
│   └── download
└── utp.mac

2 directories, 8 files


Do we really need all of those files?  groff(1) can probably take the an.tmac
and a few others from the system, no?  I'd like to reduce this to the bare
minimum.


Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: [PATCH] scripts/LinuxManBook/gropdf: use symlink instead of hard coded groff version

[Alejandro Colomar]

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

Hi Brian,

On 2023-08-07 17:01, Brian Inglis wrote:
> man-pages custom script gropdf has hard coded groff version used in font path
> groff provides symlink current for version to avoid the issue; use it in gropdf
> specify failing font path used to open font description file in error message
> 
> Signed-off-by: Brian Inglis <Brian.Inglis@Shaw.ca>

Deri removed our gropdf(1) copy, so this patch is not necessary anymore.  :)

Cheers,
Alex

> ---
>  scripts/LinuxManBook/gropdf | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/scripts/LinuxManBook/gropdf b/scripts/LinuxManBook/gropdf
> index 8474e583f57d..fb205395015b 100755
> --- a/scripts/LinuxManBook/gropdf
> +++ b/scripts/LinuxManBook/gropdf
> @@ -58,8 +58,8 @@ else
>  
>  my %cfg;
>  
> -$cfg{GROFF_VERSION}='1.22.4';
> -$cfg{GROFF_FONT_PATH}='/usr/share/groff/site-font:/usr/share/groff/1.22.4/font:/usr/lib/font';
> +$cfg{GROFF_VERSION}='current';
> +$cfg{GROFF_FONT_PATH}="/usr/share/groff/site-font:/usr/share/groff/$cfg{GROFF_VERSION}/font:/usr/lib/font";
>  $cfg{RT_SEP}=':';
>  binmode(STDOUT);
>  
> @@ -690,7 +690,7 @@ sub LoadDesc
>      my $f;
>  
>      OpenFile(\$f,$fontdir,"DESC");
> -    Msg(1,"Failed to open 'DESC'") if !defined($f);
> +    Msg(1,"Failed to open 'DESC' in '$fontdir'") if !defined($f);
>  
>      while (<$f>)
>      {

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Brian,

On 2023-08-07 18:21, Brian Inglis wrote:
[...]

>>> $ pwd
>>> /home/alx/src/linux/man-pages/man-pages/6.04/scripts/LinuxManBook
>>> $ ./BuildLinuxMan.pl  ../../
>>> [...]
>>> Failed to open 'DESC'
> 
> That annoyingly minimal message provoked the patch submitted.

Yeah; it took me some time to find the cause.  The error message doesn't
even tell who failed --was it the shell, was it gropdf, was it troff?--.

:)

> 
>>>> When I run the script/LinuxManBook/BuildLinuxMan.pl, after applying the gropdf
>>>> patch, manually in the build dir, I get a pdf, but without any man page footers.
> 
>>> Hmm, that's weird.  After applying your patch, It works fine for me.
>>> I do see the page footers.  However, I have old builds of groff in my
>>> system, which I haven't cleaned up, so maybe they interfere positively
>>> to that outcome.  Maybe from a clean installation of Debian Sid I
>>> wouldn't be able to reproduce that.
> 
>> I have uploaded the 6.05.01 book now.
> 
> Nice - with current page footers!

Can you confirm if you can build the book correctly after I pushed Deri's
change?  I'm worried that I couldn't reproduce your problem, and would
like to know if it has gone away or persists for you.

> 
>>> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
>>> for 1.22.4 which should be removed after the release of 1.23.0, so it
>>> seems that the time has come to chop a lot of stuff from there.
>>>
>>> Deri, would you mind simplifying the scripts assuming a Build-dep of
>>> groff(>=1.23.0)?
> 
> Resent the patch cc Deri.
> 
> Would it make sense to merge changes into/from groff 1.23 grodpf, which I also 
> tried, and also did not produce page footers, but did produce lots of 
> *different* messages.
> It seems likely that changes made to build the huge man book might also benefit 
> other projects with large docs.

We don't have a gropdf(1) copy anymore.  :)

> 
>>>> Are there any other scripts which need to be run and/or groff commands or data
>>>> which need to be supplied?
> 
>>> No.  It's just:
>>>
>>> $ cd scripts/LinuxManBook/
>>> $ ./BuildLinuxMan.pl ../../
> 
>>>> It would be nice to see this eventually added to your RELEASE doc, and maybe
>>>> also to the make scripts.
> 
>>> Yes.  I first want to put it in the Makefiles, and then add it to
>>> INSTALL.  Then something to RELEASE.  But I first want to simplify
>>> the script so I can understand it.
> 
> See below ;^>

Sooo true.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[G. Branden Robinson]

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

Hi Alex,

At 2023-08-12T02:02:49+0200, Alejandro Colomar wrote:
> On 2023-08-07 18:21, Brian Inglis wrote:
> >>> $ pwd
> >>> /home/alx/src/linux/man-pages/man-pages/6.04/scripts/LinuxManBook
> >>> $ ./BuildLinuxMan.pl  ../../
> >>> [...]
> >>> Failed to open 'DESC'
> > 
> > That annoyingly minimal message provoked the patch submitted.
> 
> Yeah; it took me some time to find the cause.  The error message
> doesn't even tell who failed --was it the shell, was it gropdf, was it
> troff?--.
> 
> :)

This sort of thing makes me purple with rage and I have tried to purge
groff of such unhelpful diagnostics--especially those that are uttered
furtively by programs (or, worse, libraries) that attempt to remain
anonymous.  Doug McIlroy was telling people to cut this crap out in 1986
(or maybe a decade before that, even) and people _still_ ignore him.

https://www.cs.dartmouth.edu/~doug/reader.pdf (p. 9)

Much work was done on groff 1.23 to fix this, but I'm not certain all
such offenders have been rehabilitated.

https://savannah.gnu.org/bugs/?52463

When you encounter one, strike it with lightning.

Regards,
Branden

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

Re: No 6.05/.01 pdf book available

[G. Branden Robinson]

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

At 2023-08-12T01:51:31+0200, Alejandro Colomar wrote:
> But, I installed groff from git HEAD a moment ago, and I didn't notice
> the 5 MiB improvements that you claimed, and the page numbers are
> wrong, so maybe I'm doing something wrong, or have a non-clean groff
> installation in place?

Deri's working on a branch.

https://git.savannah.gnu.org/cgit/groff.git/log/?h=deri-gropdf-ng

Regards,
Branden

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

Re: No 6.05/.01 pdf book available

[Brian Inglis]

On 2023-08-07 17:14, Deri wrote:
> On Monday, 7 August 2023 09:45:22 BST Alejandro Colomar wrote:
>> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
>> for 1.22.4 which should be removed after the release of 1.23.0, so it
>> seems that the time has come to chop a lot of stuff from there.
>>
>> Deri, would you mind simplifying the scripts assuming a Build-dep of
>> groff(>=1.23.0)?
> 
> Hi Alex, Brian,
> 
> I have done some work on building the pdf. One improvement is any warnings
> output by groff, i.e. use of the deprecated .PDF macro, now identify the
> particular man page and line number accurately.
> 
> I have attached two new replacement LinuxManBook directories. The first,
> 1.23.0, will run on a stock groff 1.23.0 system. The second, 1.23.0+, runs
> with the latest gropdf which has a number of advantages for this project - you
> will find the resulting pdf to be more than 5mb smaller, and the page numbers
> in the overview pane match up with the page number at the bottom of each page.
> 
> The file NewGropdf.pdf contains description of some of the features in the new
> gropdf.
> 
> Both of these should continue to work if the groff version changes, thanks to
> Brian's helpful suggestion to include /usr/share/groff/current in the font
> path, but I have achieved this by specifying it in an -F flag rather than
> patching gropdf.

Nice work Deri!

The official 6.05.01 book hyphenates words across page breaks more than standard 
1.23.0 and new 1.23.0+ gropdf books.

File sizes are official 6.05.01 ~13.3MB, 200k more than standard 1.23.0 ~13MB, 
which is >~5MB more than new 1.23.0+ gropdf <~8MB.

I now see page footers on all pages!

I noticed that new 1.23.0+ seems to set some lines, especially tables, a little 
tighter (perhaps because of space handling), but *only* the first page 
"intro(1)" has half the normal spacing from the page header to the first heading!

[I also noticed that *poppler* `pdf2text -layout` (used to diff the content amd 
layout) prints the .SH NAME and options dashes as en-dash from the official 
6.05.01 book, but prints minus from standard 1.23.0 and new 1.23.0+ gropdf.]

I notice a number of widows and orphans, but that may be the man macros or groff 
commands not checking for sufficient space left on the page before rendering 
text: allowing 4em before heading spacing, 3em before para spacing would 
probably help, at the cost of larger bottom margins; and groff footers need to 
allow extra space to prevent widows by allowing them to intrude.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: No 6.05/.01 pdf book available

[Deri]

On Saturday, 12 August 2023 18:02:24 BST Brian Inglis wrote:
> On 2023-08-07 17:14, Deri wrote:
> > On Monday, 7 August 2023 09:45:22 BST Alejandro Colomar wrote:
> >> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
> >> for 1.22.4 which should be removed after the release of 1.23.0, so it
> >> seems that the time has come to chop a lot of stuff from there.
> >> 
> >> Deri, would you mind simplifying the scripts assuming a Build-dep of
> >> groff(>=1.23.0)?
> > 
> > Hi Alex, Brian,
> > 
> > I have done some work on building the pdf. One improvement is any warnings
> > output by groff, i.e. use of the deprecated .PDF macro, now identify the
> > particular man page and line number accurately.
> > 
> > I have attached two new replacement LinuxManBook directories. The first,
> > 1.23.0, will run on a stock groff 1.23.0 system. The second, 1.23.0+, runs
> > with the latest gropdf which has a number of advantages for this project -
> > you will find the resulting pdf to be more than 5mb smaller, and the page
> > numbers in the overview pane match up with the page number at the bottom
> > of each page.
> > 
> > The file NewGropdf.pdf contains description of some of the features in the
> > new gropdf.
> > 
> > Both of these should continue to work if the groff version changes, thanks
> > to Brian's helpful suggestion to include /usr/share/groff/current in the
> > font path, but I have achieved this by specifying it in an -F flag rather
> > than patching gropdf.
> 
> Nice work Deri!
> 
> The official 6.05.01 book hyphenates words across page breaks more than
> standard 1.23.0 and new 1.23.0+ gropdf books.

Hi Brian,

I'd like to investigate this to understand why this is happening, please can 
you give me example page numbers which illustrate this.

> File sizes are official 6.05.01 ~13.3MB, 200k more than standard 1.23.0
> ~13MB, which is >~5MB more than new 1.23.0+ gropdf <~8MB.
> 
> I now see page footers on all pages!
> 
> I noticed that new 1.23.0+ seems to set some lines, especially tables, a
> little tighter (perhaps because of space handling), but *only* the first
> page "intro(1)" has half the normal spacing from the page header to the
> first heading!

Yes, I can see the difference in intro(1) and I can see a bug in the version 
of an.tmac I provided which may affect hyphenation. Also a page number example 
of the tighter table would be helpful.

> [I also noticed that *poppler* `pdf2text -layout` (used to diff the content
> amd layout) prints the .SH NAME and options dashes as en-dash from the
> official 6.05.01 book, but prints minus from standard 1.23.0 and new
> 1.23.0+ gropdf.]

This is intentional (and probably desirable). The pdf has a mapping so that 
the groff character \- is displayed as HYPHEN (U+0201) but when text is copy/
pasted from the pdf it is converted to HYPHEN-MINUS (U+002D) which is the 
character you get when you hit hyphen on the keyboard. This means that if you 
are copy/pasteing from examples in the man page which includes hyphens then 
your shell will interpret it correctly.

> I notice a number of widows and orphans, but that may be the man macros or
> groff commands not checking for sufficient space left on the page before
> rendering text: allowing 4em before heading spacing, 3em before para
> spacing would probably help, at the cost of larger bottom margins; and
> groff footers need to allow extra space to prevent widows by allowing them
> to intrude.

This probably needs a bit of tender curation! Bear in mind that the 
BuildLinuxMan.pl script uses the flags "-dpaper=a4 -P-pa4" so if the man page 
author has designed for a different page size the widows/orphans may well be 
different.

Thanks for your help.

Cheers

Deri

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Branden,

On 2023-08-12 03:48, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-08-12T02:02:49+0200, Alejandro Colomar wrote:
>> On 2023-08-07 18:21, Brian Inglis wrote:
>>>>> $ pwd
>>>>> /home/alx/src/linux/man-pages/man-pages/6.04/scripts/LinuxManBook
>>>>> $ ./BuildLinuxMan.pl  ../../
>>>>> [...]
>>>>> Failed to open 'DESC'
>>>
>>> That annoyingly minimal message provoked the patch submitted.
>>
>> Yeah; it took me some time to find the cause.  The error message
>> doesn't even tell who failed --was it the shell, was it gropdf, was it
>> troff?--.
>>
>> :)
> 
> This sort of thing makes me purple with rage and I have tried to purge
> groff of such unhelpful diagnostics--especially those that are uttered
> furtively by programs (or, worse, libraries) that attempt to remain
> anonymous.  Doug McIlroy was telling people to cut this crap out in 1986
> (or maybe a decade before that, even) and people _still_ ignore him.
> 
> https://www.cs.dartmouth.edu/~doug/reader.pdf (p. 9)

Hmm, that was an interesting read.  It explains a few inconsistencies
in the design of UNIX that I didn't understand.  I didn't know pipes
came so late into the timeline.  :)

Cheers,
Alex

> 
> Much work was done on groff 1.23 to fix this, but I'm not certain all
> such offenders have been rehabilitated.
> 
> https://savannah.gnu.org/bugs/?52463
> 
> When you encounter one, strike it with lightning.
> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

On 2023-08-12 05:04, G. Branden Robinson wrote:
> At 2023-08-12T01:51:31+0200, Alejandro Colomar wrote:
>> But, I installed groff from git HEAD a moment ago, and I didn't notice
>> the 5 MiB improvements that you claimed, and the page numbers are
>> wrong, so maybe I'm doing something wrong, or have a non-clean groff
>> installation in place?
> 
> Deri's working on a branch.
> 
> https://git.savannah.gnu.org/cgit/groff.git/log/?h=deri-gropdf-ng
> 

Thanks!  How often do you merge that thing?  I'd like to use that
thing without losing the improvements to troff of git HEAD.

Cheers,
Alex

> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Brian Inglis]

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

On 2023-08-12 14:02, Deri wrote:
> On Saturday, 12 August 2023 18:02:24 BST Brian Inglis wrote:
>> On 2023-08-07 17:14, Deri wrote:
>>> On Monday, 7 August 2023 09:45:22 BST Alejandro Colomar wrote:
>>>> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
>>>> for 1.22.4 which should be removed after the release of 1.23.0, so it
>>>> seems that the time has come to chop a lot of stuff from there.
>>>>
>>>> Deri, would you mind simplifying the scripts assuming a Build-dep of
>>>> groff(>=1.23.0)?
>>>
>>> Hi Alex, Brian,
>>>
>>> I have done some work on building the pdf. One improvement is any warnings
>>> output by groff, i.e. use of the deprecated .PDF macro, now identify the
>>> particular man page and line number accurately.
>>>
>>> I have attached two new replacement LinuxManBook directories. The first,
>>> 1.23.0, will run on a stock groff 1.23.0 system. The second, 1.23.0+, runs
>>> with the latest gropdf which has a number of advantages for this project -
>>> you will find the resulting pdf to be more than 5mb smaller, and the page
>>> numbers in the overview pane match up with the page number at the bottom
>>> of each page.
>>>
>>> The file NewGropdf.pdf contains description of some of the features in the
>>> new gropdf.
>>>
>>> Both of these should continue to work if the groff version changes, thanks
>>> to Brian's helpful suggestion to include /usr/share/groff/current in the
>>> font path, but I have achieved this by specifying it in an -F flag rather
>>> than patching gropdf.

>> Nice work Deri!
>>
>> The official 6.05.01 book hyphenates words across page breaks more than
>> standard 1.23.0 and new 1.23.0+ gropdf books.

> I'd like to investigate this to understand why this is happening, please can
> you give me example page numbers which illustrate this.

Hi Deri,

Please see attached awk script and logs showing pages with end of page "hyphens" 
in text of PDFs from `pdftotext -layout`: "official" PDF has 47, newer PDFs 
break only at 5 compound word joins or double dashes.

>> File sizes are official 6.05.01 ~13.3MB, 200k more than standard 1.23.0
>> ~13MB, which is >~5MB more than new 1.23.0+ gropdf <~8MB.
>>
>> I now see page footers on all pages!
>>
>> I noticed that new 1.23.0+ seems to set some lines, especially tables, a
>> little tighter (perhaps because of space handling), but *only* the first
>> page "intro(1)" has half the normal spacing from the page header to the
>> first heading!
> 
> Yes, I can see the difference in intro(1) and I can see a bug in the version
> of an.tmac I provided which may affect hyphenation. Also a page number example
> of the tighter table would be helpful.

The impression of tighter table spacing seems to be an artifact of more 
consistent text and space rendering by pdftotext as pointed out in the diffs, 
and as you explain below.

>> [I also noticed that *poppler* `pdf2text -layout` (used to diff the content
>> amd layout) prints the .SH NAME and options dashes as en-dash from the
>> official 6.05.01 book, but prints minus from standard 1.23.0 and new
>> 1.23.0+ gropdf.]

> This is intentional (and probably desirable). The pdf has a mapping so that
> the groff character \- is displayed as HYPHEN (U+0201) but when text is copy/
> pasted from the pdf it is converted to HYPHEN-MINUS (U+002D) which is the
> character you get when you hit hyphen on the keyboard. This means that if you
> are copy/pasteing from examples in the man page which includes hyphens then
> your shell will interpret it correctly.

>> I notice a number of widows and orphans, but that may be the man macros or
>> groff commands not checking for sufficient space left on the page before
>> rendering text: allowing 4em before heading spacing, 3em before para
>> spacing would probably help, at the cost of larger bottom margins; and
>> groff footers need to allow extra space to prevent widows by allowing them
>> to intrude.

> This probably needs a bit of tender curation! Bear in mind that the
> BuildLinuxMan.pl script uses the flags "-dpaper=a4 -P-pa4" so if the man page
> author has designed for a different page size the widows/orphans may well be
> different.

As a Northern-American can I change your uses of "p?a4" to letter in the script 
and expect it to work?
I added a paper variable, made the changes, it seems to work, and reduces end of 
page hyphens to one compound word instance in mbind(2); log attached:

	nodemask ... on-
	...
	line, ...

There appear to be 24 single word instances of online and 12 outdated hyphenated 
compound word instances of on-line across all man pages.

UI: I also noticed, while looking for tables to compare, that pages are ordered 
by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g ISO_8859-2 is after 
ISO_8859-16 which may not be as expected.
Used rpmvercmp in last line of perl sub sortman and works as expected.

Tech nitpick: .Z is still recognized by GUIs as compress output (UNIX-compressed 
file) - is there no other file type suffix used for ditroff intermediate output?
Aha - Alex says .set:

	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html

Added variables and changed those also in BLM-letter.pl: copy attached.

> Thanks for your help.

Happy to help in any way.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

[-- Attachment #2: lmb-eop-hy.awk --]
[-- Type: text/plain, Size: 455 bytes --]

#!/usr/bin/gawk -f
# lmb-eop-hy.awk - find LinuxManBook end of page hyphens
#			on last non-blank line before footer

# save hyphenated line and skip to next
/-$/ {
    h = $0;
    next;
}

# if hyphenated line seen and footer found, print both lines, forget line seen
h && /^Linux\sman-pages\s6\.05\.01.*[0-9]+$/ {
    print h;
    print $0;
    h = "";
}

# if hyphenated line seen and non-blank line found, forget line seen
h && NF > 0 {
    h = "";
}

[-- Attachment #3: lmb-1.23.0+-eop-hy.log --]
[-- Type: text/plain, Size: 1110 bytes --]

                map_1         map_2                                                   --| map_4 |--
Linux man-pages 6.05.01                             2023-07-28                                                   55
            ter a successful execve(), and the process would gain privilege because the set-user-ID or set-group-
Linux man-pages 6.05.01                            2023-05-03                                                  135
        To avoid corruption in multithreaded applications, mutexes are used internally to protect the memory-
Linux man-pages 6.05.01                            2023-07-20                                                 1415
             drive that supports the LOCATE command (device-specific address) or a Tandberg-
Linux man-pages 6.05.01                          2023-02-05                                               2073
      stant Bandwidth Server). To set and fetch this policy and associated attributes, one must use the Linux-
Linux man-pages 6.05.01                                 2023-02-10                                                      2649

[-- Attachment #4: lmb-1.23.0-eop-hy.log --]
[-- Type: text/plain, Size: 1110 bytes --]

                map_1         map_2                                                   --| map_4 |--
Linux man-pages 6.05.01                             2023-07-28                                                   55
            ter a successful execve(), and the process would gain privilege because the set-user-ID or set-group-
Linux man-pages 6.05.01                            2023-05-03                                                  135
        To avoid corruption in multithreaded applications, mutexes are used internally to protect the memory-
Linux man-pages 6.05.01                            2023-07-20                                                 1415
             drive that supports the LOCATE command (device-specific address) or a Tandberg-
Linux man-pages 6.05.01                          2023-02-05                                               2073
      stant Bandwidth Server). To set and fetch this policy and associated attributes, one must use the Linux-
Linux man-pages 6.05.01                                 2023-02-10                                                      2649

[-- Attachment #5: lmb-6.05.01-eop-hy.log --]
[-- Type: text/plain, Size: 10669 bytes --]

        If the CPUs in an SMP system have different clock sources, then there is no way to maintain a correla-
Linux man-pages 6.05.01                            2023-07-20                                                  87
                so would have caused the limit defined by the corresponding file in /proc/sys/user to be ex-
Linux man-pages 6.05.01                           2023-05-03                                              101
        but can be more efficient: if the unshared range extends past the current maximum number of file de-
Linux man-pages 6.05.01                             2023-05-03                                                  109
                  dicates that the peer closed its end of the channel. Subsequent reads from the channel will re-
Linux man-pages 6.05.01                              2023-04-03                                                   125
            ter a successful execve(), and the process would gain privilege because the set-user-ID or set-group-
Linux man-pages 6.05.01                            2023-05-03                                                  135
           or via a duplicate of the file descriptor created by fork(2), dup(2), fcntl() F_DUPFD, and so on) are al-
Linux man-pages 6.05.01                               2023-03-30                                                    162
        padding byte in the linux_dirent structure. Thus, on kernels up to and including Linux 2.6.3, attempt-
Linux man-pages 6.05.01                              2023-05-03                                                202
        If either field in new_value.it_value is nonzero, then the timer is armed to initially expire at the speci-
Linux man-pages 6.05.01                             2023-05-03                                                  212
             specified whether changes made to the file after the mmap() call are visible in the mapped re-
Linux man-pages 6.05.01                             2023-07-20                                                    395
                 dom writes to preallocated files, as well as cases where the MS_STRICTATIME mount op-
Linux man-pages 6.05.01                           2023-04-03                                                406
                If type is PERF_TYPE_RAW, then a custom "raw" config value is needed. Most CPUs sup-
Linux man-pages 6.05.01                         2023-05-03                                                  485
                   use of the performance counters (including the commonly enabled NMI Watchdog Timer in-
Linux man-pages 6.05.01                            2023-05-03                                                  488
                   tables. It does this by trapping the #BR exceptions that result at first use of missing bounds ta-
Linux man-pages 6.05.01                              2023-07-28                                                  551
                   system calls from executing or to SYSCALL_DISPATCH_FILTER_ALLOW to temporar-
Linux man-pages 6.05.01                            2023-07-28                                                  556
           Unlike preadv() and pwritev(), if the offset argument is −1, then the current file offset is used and up-
Linux man-pages 6.05.01                               2023-05-03                                                   605
          behavior. In this circumstance, read(2) has no effect (the datagram remains pending), while recv() con-
Linux man-pages 6.05.01                             2023-07-18                                                  613
              SECCOMP_GET_NOTIF_SIZES operation, which returns a structure of type seccomp_no-
Linux man-pages 6.05.01                            2023-05-03                                                    666
        in Linux 2.2, the fixed-size, 32-bit sigset_t type supported by that system call was no longer fit for pur-
Linux man-pages 6.05.01                            2023-05-03                                                   772
        System V also provides these semantics for signal(). This was bad because the signal might be deliv-
Linux man-pages 6.05.01                           2023-03-30                                                   778
              Linux 2.4.15. When this is so, the version where the system call appeared in both of the major ker-
Linux man-pages 6.05.01                             2023-07-30                                                  838
         mation into the notification. One needs to enable this feature explicitly using the UFFD_FEA-
Linux man-pages 6.05.01                             2023-05-03                                                  898
            malloc(3). If you need certain calls to these two functions to not allocate memory (in signal han-
Linux man-pages 6.05.01                              2023-07-20                                                     971
               than data in a register, and thus the explicit_bzero() call creates a brief time window where the sen-
Linux man-pages 6.05.01                                 2023-07-20                                                 988
               change the current directory. Note that applications should not themselves change their cur-
Linux man-pages 6.05.01                                2023-07-20                                                 1185
              not set.) In this case the sb argument passed to fn() contains information returned by per-
Linux man-pages 6.05.01                             2023-07-20                                               1189
          host byte order suitable for use as an Internet network address. On success, the converted address is re-
Linux man-pages 6.05.01                              2023-07-20                                                  1342
        To avoid corruption in multithreaded applications, mutexes are used internally to protect the memory-
Linux man-pages 6.05.01                            2023-07-20                                                 1415
                   flags are not specified, the child inherits the corresponding scheduling attributes from the par-
Linux man-pages 6.05.01                                2023-05-03                                             1524
             drive that supports the LOCATE command (device-specific address) or a Tandberg-compati-
Linux man-pages 6.05.01                          2023-02-05                                               2073
                         which have not been demand-loaded in, or which are swapped out. This value is in-
Linux man-pages 6.05.01                          2023-07-08                                                2171
                            system interrupts. The first column is the total of all interrupts serviced including un-
Linux man-pages 6.05.01                               2023-07-08                                               2190
        The interfaces can be accessed by reading or writing the /proc/sys/net/ipv4/neigh/*/* files. Each inter-
Linux man-pages 6.05.01                            2023-07-15                                               2256
                  hard disk, with Y in ’a’–’d’; ’sd’ for SCSI compatible disk, with Y in ’a’–’e’), Y the driver let-
Linux man-pages 6.05.01                             2023-02-05                                                  2266
        The special treatments of user ID 0 (root) described in this subsection can be disabled using the se-
Linux man-pages 6.05.01                                 2023-05-03                                                    2336
                 min−guide/cgroup−v1/blkio−controller.rst (or Documentation/cgroup−v1/blkio−con-
Linux man-pages 6.05.01                            2023-04-03                                                 2345
        A cpuset directory that contains no child cpuset directories, and has no attached processes, can be re-
Linux man-pages 6.05.01                           2023-07-18                                                2369
       described in time(7). The setting of sched_relax_domain_level applies only to immediate load balanc-
Linux man-pages 6.05.01                           2023-07-18                                                  2374
              value 700 (600 before glibc 2.10; 500 before glibc 2.2). In addition, various GNU-specific ex-
Linux man-pages 6.05.01                          2023-07-15                                               2413
        EINVAL when this setting is missing. sin_port contains the port in network byte order. The port num-
Linux man-pages 6.05.01                            2023-07-15                                                2446
        Always include periods in such abbreviations, as shown here. In addition, "e.g." and "i.e." should al-
Linux man-pages 6.05.01                             2023-03-30                                                  2541
        calls that operate on process IDs always operate using the process ID that is visible in the PID name-
Linux man-pages 6.05.01                           2023-03-30                                                 2593
               from write(2) to see how many bytes were actually written), and these bytes may be inter-
Linux man-pages 6.05.01                              2023-07-16                                                  2597
      stant Bandwidth Server). To set and fetch this policy and associated attributes, one must use the Linux-
Linux man-pages 6.05.01                                 2023-02-10                                                      2649
                    (logical OR), the hardware accumulates the bits that are subsequently written to it. The possi-
Linux man-pages 6.05.01                                2023-02-05                                                  2696
                fault that includes the sender’s PID, real user ID, and real group ID, if the sender did not spec-
Linux man-pages 6.05.01                             2023-07-15                                              2754
         to load an arbitrary URI that automatically detects the users’ environment (e.g., text or graphics, desk-
Linux man-pages 6.05.01                             2023-04-30                                                  2770
        records the user namespace of the creating process as the owner of the new namespace. (This associa-
Linux man-pages 6.05.01                            2023-05-03                                                  2775

[-- Attachment #6: BLM-letter.pl --]
[-- Type: text/plain, Size: 6774 bytes --]

#!/usr/bin/perl -w
#
#	BuildLinuxMan.pl	: Build Linux manpages book
#	Deri James		: 15 Dec 2022
#
#	Params:-
#
#               $1 = Directory holding the man pages
#
# (C) Copyright 2022, Deri James
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details
# (http://www.gnu.org/licenses/gpl-2.0.html).
#

use strict;

my $dir=shift || '.';
my @aliases=`egrep -l '^\\.so' $dir/man*/*`;
my %alias;
my %target;
my $inTS=0;
my $inBlock=0;

my %Sections=
(
    "1"	=> "General Commands Manual",
    "2"	=> "System Calls Manual",
    "2type"	=> "System Calls Manual (types)",
    "3"	=> "Library Functions Manual",
    "3const"	=> "Library Functions Manual (constants)",
    "3head"	=> "Library Functions Manual (headers)",
    "3type"	=> "Library Functions Manual (types)",
    "4"	=> "Kernel Interfaces Manual",
    "5"	=> "File Formats Manual",
    "6"	=> "Games Manual",
    "7"	=> "Miscellaneous Information Manual",
    "8"	=> "System Manager's Manual",
    "9"	=> "Kernel Developer's Manual",
);

my $Section='';
my $temp='LMB.man';

LoadAlias();
BuildBook();

my $format='pdf';
my $paper='letter';
my $cmdstring="-T$format -k -pet -M. -F. -mandoc -manmark -dpaper=$paper -P-p$paper -rC1 -rCHECKSTYLE=3";
my $front='LMBfront.t';
my $frontdit='LMBfront.set';
my $mandit='LinuxManBook.set';
my $book="LinuxManBook.$format";

system("groff -T$format -ms $front -Z > $frontdit");
system("groff -z -dPDF.EXPORT=1 -dLABEL.REFS=1 $temp $cmdstring 2>&1 | LC_ALL=C grep '^\\. *ds' | groff -T$format $cmdstring - $temp -Z > $mandit");
system("./gro$format -F.:/usr/share/groff/current $frontdit $mandit -p$paper > $book");
#unlink "$mandit","$temp","$frontdit";  # If you want to clean up

# Aliases are the man pages which .so another man page, so build a hash of them so
# that when we are processing referenced man page we can add the target for the
# bookmark.

sub LoadAlias
{
    foreach my $fn (@aliases)
    {
	chomp($fn);
	my (@pth)=split('/',$fn);
	my $nm=pop(@pth);
	my $bkmark="$1_$2" if $nm=~m/(.*)\.(\w+)/;

	if (open(F,"<$fn"))
	{
	    while (<F>)
	    {
		next if m/^\.\\"/;

		if (m/^.so\s+(man\w+\/(.+)\.(.+?))$/)
		{
		    $alias{$bkmark}=["$2_$3",$2,$3];
		    push(@{$target{"$2_$3"}},$bkmark);
		    last;
		}
		else
		{
		    print STDERR "Alias fail: $fn\n";
		}
	    }

	    close(F);
	}
	else
	{
	    print STDERR "Open fail: $fn\n";
	}
    }
}

sub BuildBook
{
    open(BK,">$temp");

    print BK ".pdfpagenumbering D . 1\n";

    foreach my $fn (sort sortman glob("$dir/man*/*"))
    {
	my ($nm,$sec,$srt)=GetNmSec($fn);

        my $bkmark="$1_$2" if $nm=~m/(.*)\.(\w+)/;
        my $title= "$1\\($2\\)";

# If this is an alias, just add it to the outline panel.

        if (exists($alias{$bkmark}))
        {
            print BK ".eo\n.device ps:exec [/Dest /$alias{$bkmark}->[0] /Title ($title) /Level 2 /OUT pdfmark\n.ec\n";
	    print BK ".if dPDF.EXPORT .tm .ds pdf:look($bkmark) $alias{$bkmark}->[1]($alias{$bkmark}->[2])\n";
	    next;
	}

	print BK ".\\\" >>>>>> $1($2) <<<<<<\n.lf 0 $bkmark\n";

	if (open(F,'<',$fn))
        {
            while (<F>)
            {
                if (m/^\.\\"/)
                {
                    print BK $_;
                    next;
                }

                chomp;

# This code is to determine whether we are within a tbl block and in a text block
# T{ and T}. This is fudge code particularly for the syscalls(7) page.

                $inTS=1 if m/\.TS/;
                $inTS=0,$inBlock=0 if m/\.TE/;

                s/\r$//;    # In case edited under windows i.e. CR/LF
                s/\s+$//;
                next if !$_;
#               s/^\s+//;

                if (m/^\.BR\s+([-\w\\.]+)\s+\((.+?)\)(.*)/)
                {
                    my $bkmark="$1";
                    my $sec=$2;
                    my $after=$3;
                    my $dest=$bkmark;
                    $dest=~s/\\-/-/g;
                    $_=".MR \"$bkmark\" \"$sec\" \"$after\" \"$dest\"";
                }

                s/^\.BI \\fB/.BI /;
		s/^\.BR\s+(\S+)\s*$/.B $1/;
                s/^\.BI\s+(\S+)\s*$/.B $1/;
                s/^\.IR\s+(\S+)\s*$/.I $1/;

# Fiddling for syscalls(7) :-(

                if ($inTS)
                {
                    my @cols=split(/\t/,$_);

                    foreach my $c (@cols)
                    {
                        $inBlock+=()=$c=~m/T\{/g;
                        $inBlock-=()=$c=~m/T\}/g;

                        my $mtch=$c=~s/\s*\\fB([-\w.]+)\\fP\((\w+)\)/\n.MR $1 $2 \\c\n/g;
                        $c="T{\n${c}\nT}" if $mtch and !$inBlock;
                    }

                    $_=join("\t",@cols);
                    s/\n\n/\n/g;
                }

                if (m/^\.TH\s+([-\w\\.]+)\s+(\w+)/)
                {

                    # if new section add top level bookmark

                    if ($sec ne $Section)
                    {
			print BK ".nr PDFOUTLINE.FOLDLEVEL 1\n.fl\n";
			print BK ".pdfbookmark 1 $Sections{$sec}\n";
			print BK ".nr PDFOUTLINE.FOLDLEVEL 2\n";
			$Section=$sec;
                    }

                    print BK "$_\n";

# Add a level two bookmark. We don't set it in the TH macro since the name passed
# may be different from the filename, i.e. file = unimplemented.2, TH = UNIMPLEMENTED 2

                    print BK ".pdfbookmark -T $bkmark 2 $1($2)\n";

# If this page is referenced by an alias plant a destination label for the alias.

                    if (exists($target{$bkmark}))
                    {
                        foreach my $targ (@{$target{$bkmark}})
			{
			    print BK ".pdf*href.set $targ\n";
			}
		    }

		    next;
		}

		print BK "$_\n";

	    }

	    close(F);

	}
    }

    close(BK);
}

sub GetNmSec
{
    my (@pth)=split('/',shift);
    my $nm=pop(@pth);
    my $sec=substr(pop(@pth),3);
    my $srt=$nm;
    $srt=~s/^_+//;
    $srt="$sec/$srt";
    return($nm,$sec,$srt);
}

# add rpmvercmp
use RPM::VersionSort;

sub sortman
{
# Sort - ignore case but frig it so that intro is the first entry.

    my (undef,$s1,$c)=GetNmSec($a);
    my (undef,$s2,$d)=GetNmSec($b);

    my $cmp=$s1 cmp $s2;

    return $cmp if $cmp;
    return -1 if ($c=~m/\/intro/ and $d!~m/\/intro/);
    return  1 if ($d=~m/\/intro/ and $c!~m/\/intro/);
    return rpmvercmp(lc($c),lc($d));
#   return (lc($c) cmp lc($d));
}

[-- Attachment #7: lmb-1.23.0+-letter-eop-hy.log --]
[-- Type: text/plain, Size: 232 bytes --]

        nodemask argument is ignored. Where a nodemask is required, it must contain at least one node that is on-
Linux man-pages 6.05.01                             2023-07-16                                                    384

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Brian,

On 2023-08-13 22:30, Brian Inglis wrote:
[...]

> UI: I also noticed, while looking for tables to compare, that pages are ordered 
> by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g ISO_8859-2 is after 
> ISO_8859-16 which may not be as expected.
> Used rpmvercmp in last line of perl sub sortman and works as expected.

Hmm, I'll update the scripts/sortman script in the man-pages repo to tuse sort -V.
I intend that script (among Makefile code) to replace Deri's perl, as I don't
speak perl.

> 
> Tech nitpick: .Z is still recognized by GUIs as compress output (UNIX-compressed 
> file)

Yep, I don't like that .Z either.

> - is there no other file type suffix used for ditroff intermediate output?
> Aha - Alex says .set:

That would be Ralph's honor.  ;)

> 
> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html

We might as well make it official in suffixes(7).

	.set	troff(1) typeset output

Hmm?

Which made me realize .roff is not documented.  Branden, as the maintainer
of groff(1), would you mind checking that page and adding all the
groff(1)-related suffixes you find (or actually, that you don't find)?  

> 
> Added variables and changed those also in BLM-letter.pl: copy attached.
> 
>> Thanks for your help.
> 
> Happy to help in any way.

Cheers,
Alex

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

hyphens at ends of pages (was: No 6.05/.01 pdf book available)

[G. Branden Robinson]

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

Hi Brian,

At 2023-08-13T14:30:34-0600, Brian Inglis wrote:
> Please see attached awk script and logs showing pages with end of page
> "hyphens" in text of PDFs from `pdftotext -layout`: "official" PDF has
> 47, newer PDFs break only at 5 compound word joins or double dashes.

If hyphenation is occurring at the ends of pages but otherwise normally,
then that is a symptom of the *roff automatic hyphenation mode being set
wrong.  The most likely suspect is an argument-free `.hy` invocation
somewhere in the page sources.

This is why I have nattered on about not messing with the hyphenation
mode in man page sources in recent mails (and commit messages) to this
list.[1]

In groff 1.23.0, we smuggled some of the explanation of *roff
hyphenation out of our Texinfo manual into the groff(7) page.  I'm
trimming a few sentences man page authors don't need.

Hyphenation
     When filling, groff hyphenates words as needed at user‐specified
     and automatically determined hyphenation points.  Explicitly
     hyphenated words such as “mother‐in‐law” are always eligible for
     breaking after each of their hyphens.  The hyphenation character \%
     and non‐printing break point \: escape sequences may be used to
     control the hyphenation and breaking of individual words.  [...]
     Otherwise, groff determines hyphenation points automatically by
     default.

     Several requests influence automatic hyphenation.  Because
     conventions vary, a variety of hyphenation modes is available to
     the .hy request; these determine whether hyphenation will apply to
     a word prior to breaking a line at the end of a page (more or less;
     see below for details), and at which positions within that word
     automatically determined hyphenation points are permissible.  The
     default is “1” for historical reasons, but this is not an
     appropriate value for the English hyphenation patterns used by
     groff; localization macro files loaded by troffrc and macro
     packages often override it.

     0    disables hyphenation.

     1    enables hyphenation except after the first and before the last
          character of a word.

     The remaining values “imply” 1; that is, they enable hyphenation
     under the same conditions as “.hy 1”, and then apply or lift
     restrictions relative to that basis.

     2    disables hyphenation of the last word on a page.  (Hyphenation
          is prevented if the next page location trap is closer to the
          vertical drawing position than the next text baseline would
          be.  See section “Traps” below.)
[...]

Regards,
Branden

[1] https://lore.kernel.org/linux-man/20230730200321.ocribgmh2fmk2gto@illithid/

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

Re: No 6.05/.01 pdf book available

[G. Branden Robinson]

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

Hi Alex,

At 2023-08-13T22:47:34+0200, Alejandro Colomar wrote:
> > Aha - Alex says .set:
[...]
> > 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
> 
> We might as well make it official in suffixes(7).
> 
> 	.set	troff(1) typeset output

I don't think this convention is very widely used.  troff(1) output is
so seldom dealt with by users that it is little wonder to me that no
convention has arisen here.

As noted earlier somewhere, I prefer ".trout" for AT&T-compatible
troff(1) output, and ".grout" for GNU troff(1) output. Strictly, the
latter suffix would only be necessary if the syntax extension for
multi-line device control commands is used, and I don't know for sure
that late-vintage DWB troff or Research Unix troff didn't support it.
Things got very murky with AT&T troff after the company decided it to
try using it as a cash cow.

> Which made me realize .roff is not documented.  Branden, as the
> maintainer of groff(1), would you mind checking that page and adding
> all the groff(1)-related suffixes you find (or actually, that you
> don't find)?

Sure, but I've got other things on the burner right now and might need a
reminder.

Regards,
Branden

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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Brian,

On 2023-08-13 22:47, Alejandro Colomar wrote:
> Hi Brian,
> 
> On 2023-08-13 22:30, Brian Inglis wrote:
> [...]
> 
>> UI: I also noticed, while looking for tables to compare, that pages are ordered 
>> by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g ISO_8859-2 is after 
>> ISO_8859-16 which may not be as expected.
>> Used rpmvercmp in last line of perl sub sortman and works as expected.
> 
> Hmm, I'll update the scripts/sortman script in the man-pages repo to tuse sort -V.
> I intend that script (among Makefile code) to replace Deri's perl, as I don't
> speak perl.
> 

I didn't try your sort, but while implementing my own shell version of it, I
found that version sort wasn't good enough, as it makes some cases be worse.  I
suggest you test it against my own script, and see if you get the same ordering.
If not, you'll need to tweak it.  The most important thing is that _exit(2)
should go next to exit(2).

Here's what I did:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=aab14503ef101d918046aeaa941f226685fe7bf5>

#!/bin/sh

# Copyright 2023, Alejandro Colomar <alx@kernel.org>
# SPDX-License-Identifier: GPL-3.0-or-later

sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
| sed -E '/\/intro./! s/.*\.([[:digit:]])\>/\11\t&/' \
| sed -E '/\/intro./! s/.*\.([[:digit:]])([[:alnum:]]+)/\12.\2\t&/' \
| sed -E '            s/\t(.*)/&\n\1/' \
| sed -E '/\t/        s/([^[:digit:]])[_-]([^[:digit:]])/\1\2/g' \
| sed -E '/\t/        s/[_-]/_/g' \
| sed -E '/\t/        {N;s/\n/\t/;}' \
| sort -fV \
| cut -f3;

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

On 2023-08-13 23:55, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-08-13T22:47:34+0200, Alejandro Colomar wrote:
>>> Aha - Alex says .set:
> [...]
>>> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
>>
>> We might as well make it official in suffixes(7).
>>
>> 	.set	troff(1) typeset output
> 
> I don't think this convention is very widely used.  troff(1) output is
> so seldom dealt with by users that it is little wonder to me that no
> convention has arisen here.
> 
> As noted earlier somewhere, I prefer ".trout" for AT&T-compatible
> troff(1) output, and ".grout" for GNU troff(1) output. Strictly, the
> latter suffix would only be necessary if the syntax extension for
> multi-line device control commands is used, and I don't know for sure
> that late-vintage DWB troff or Research Unix troff didn't support it.
> Things got very murky with AT&T troff after the company decided it to
> try using it as a cash cow.

Hmm, then let's leave it open to discussion then.

> 
>> Which made me realize .roff is not documented.  Branden, as the
>> maintainer of groff(1), would you mind checking that page and adding
>> all the groff(1)-related suffixes you find (or actually, that you
>> don't find)?
> 
> Sure, but I've got other things on the burner right now and might need a
> reminder.
> 

Sure, I'll ping you.  I see you're fixing many of my bug reports.
Thanks for the TS register, and more for making it default to 2!  ;)

Cheers,
Alex

> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: hyphens at ends of pages (was: No 6.05/.01 pdf book available)

[Brian Inglis]

On 2023-08-13 15:47, G. Branden Robinson wrote:
> At 2023-08-13T14:30:34-0600, Brian Inglis wrote:
>> Please see attached awk script and logs showing pages with end of page
>> "hyphens" in text of PDFs from `pdftotext -layout`: "official" PDF has
>> 47, newer PDFs break only at 5 compound word joins or double dashes.

Later I said:

>> I added a paper variable, made the changes [to NA letter size], it seems
>> to work, and reduces end of page hyphens to one compound word instance in 
>> mbind(2); log attached:
>> 
>>	nodemask ... on-
>>	...
>>	line, ...
>> 
>> There appear to be 24 single word instances of online and 12 outdated
>> hyphenated compound word instances of on-line across all man pages.

Generating a letter size man book using 1.23.0 gropdf eliminates all spurious 
end of page hyphens barring that case, allowed by your doc below.

With ~5% 140 more letter 2964pp than A4 2823pp pages, the latter pages break on 
5 times as many compound words.

Also note that although on-line appears 12 times, and online twice that, offline 
and dial(up|out|ing)? both appear 7 times, with no off-line or dial-up.

> If hyphenation is occurring at the ends of pages but otherwise normally,
> then that is a symptom of the *roff automatic hyphenation mode being set
> wrong.  The most likely suspect is an argument-free `.hy` invocation
> somewhere in the page sources.
> 
> This is why I have nattered on about not messing with the hyphenation
> mode in man page sources in recent mails (and commit messages) to this
> list.[1]
> 
> In groff 1.23.0, we smuggled some of the explanation of *roff
> hyphenation out of our Texinfo manual into the groff(7) page.  I'm
> trimming a few sentences man page authors don't need.
> 
> Hyphenation
>       When filling, groff hyphenates words as needed at user‐specified
>       and automatically determined hyphenation points.  Explicitly
>       hyphenated words such as “mother‐in‐law” are always eligible for
>       breaking after each of their hyphens.  The hyphenation character \%
>       and non‐printing break point \: escape sequences may be used to
>       control the hyphenation and breaking of individual words.  [...]
>       Otherwise, groff determines hyphenation points automatically by
>       default.
> 
>       Several requests influence automatic hyphenation.  Because
>       conventions vary, a variety of hyphenation modes is available to
>       the .hy request; these determine whether hyphenation will apply to
>       a word prior to breaking a line at the end of a page (more or less;
>       see below for details), and at which positions within that word
>       automatically determined hyphenation points are permissible.  The
>       default is “1” for historical reasons, but this is not an
>       appropriate value for the English hyphenation patterns used by
>       groff; localization macro files loaded by troffrc and macro
>       packages often override it.
> 
>       0    disables hyphenation.
> 
>       1    enables hyphenation except after the first and before the last
>            character of a word.
> 
>       The remaining values “imply” 1; that is, they enable hyphenation
>       under the same conditions as “.hy 1”, and then apply or lift
>       restrictions relative to that basis.
> 
>       2    disables hyphenation of the last word on a page.  (Hyphenation
>            is prevented if the next page location trap is closer to the
>            vertical drawing position than the next text baseline would
>            be.  See section “Traps” below.)

I have yet to evaluate the numbers of orphans, widows, and runts (single word 
widows) generated by each gropdf release, but there seems to be little apparent 
difference between 1.23.0 and Deri's 1.23.0+ new gropdf.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: No 6.05/.01 pdf book available

[Brian Inglis]

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

On 2023-08-13 16:18, Alejandro Colomar wrote:
> Hi Brian,
> 
> On 2023-08-13 22:47, Alejandro Colomar wrote:
>> Hi Brian,
>>
>> On 2023-08-13 22:30, Brian Inglis wrote:
>> [...]
>>
>>> UI: I also noticed, while looking for tables to compare, that pages are ordered
>>> by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g ISO_8859-2 is after
>>> ISO_8859-16 which may not be as expected.
>>> Used rpmvercmp in last line of perl sub sortman and works as expected.
>>
>> Hmm, I'll update the scripts/sortman script in the man-pages repo to tuse sort -V.
>> I intend that script (among Makefile code) to replace Deri's perl, as I don't
>> speak perl.

> I didn't try your sort, but while implementing my own shell version of it, I
> found that version sort wasn't good enough, as it makes some cases be worse.  I
> suggest you test it against my own script, and see if you get the same ordering.
> If not, you'll need to tweak it.  The most important thing is that _exit(2)
> should go next to exit(2).

Now exit.2 and _Exit.2 are aliases to _exit.2, and exit(2) is not listed, 
implemented, nor called by that wrapper, now exit_group(2) is "called" with 
syscall(2), and that is also the only interface now for exit(2).

> Here's what I did:
> 
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=aab14503ef101d918046aeaa941f226685fe7bf5>
> 
> #!/bin/sh
> 
> # Copyright 2023, Alejandro Colomar <alx@kernel.org>
> # SPDX-License-Identifier: GPL-3.0-or-later
> 
> sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
> | sed -E '/\/intro./! s/.*\.([[:digit:]])\>/\11\t&/' \
> | sed -E '/\/intro./! s/.*\.([[:digit:]])([[:alnum:]]+)/\12.\2\t&/' \
> | sed -E '            s/\t(.*)/&\n\1/' \
> | sed -E '/\t/        s/([^[:digit:]])[_-]([^[:digit:]])/\1\2/g' \
> | sed -E '/\t/        s/[_-]/_/g' \
> | sed -E '/\t/        {N;s/\n/\t/;}' \
> | sort -fV \
> | cut -f3;

Perl RPM::VersionSort rpmvercmp produces the desired order, ignoring leading 
non-alphanumerics, treating all non-alphanumerics as field delimiters, treating 
alphabetic and numeric strings as separate fields; see attached log.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

[-- Attachment #2: rpmvercmp-order.log --]
[-- Type: text/plain, Size: 13334 bytes --]

intro(1)
getent(1)
iconv(1)
ldd(1)
locale(1)
memusage(1)
memusagestat(1)
mtrace(1)
pldd(1)
time(1)
intro(2)
accept(2)
access(2)
acct(2)
add_key(2)
adjtimex(2)
alarm(2)
alloc_hugepages(2)
arch_prctl(2)
bdflush(2)
bind(2)
brk(2)
cacheflush(2)
capget(2)
chdir(2)
chmod(2)
chown(2)
chroot(2)
clock_getres(2)
clock_nanosleep(2)
clone(2)
close(2)
close_range(2)
connect(2)
copy_file_range(2)
create_module(2)
delete_module(2)
dup(2)
epoll_create(2)
epoll_ctl(2)
epoll_wait(2)
eventfd(2)
execve(2)
execveat(2)
_exit(2)
exit_group(2)
fallocate(2)
fanotify_init(2)
fanotify_mark(2)
fcntl(2)
flock(2)
fork(2)
fsync(2)
futex(2)
futimesat(2)
get_kernel_syms(2)
get_mempolicy(2)
get_robust_list(2)
getcpu(2)
getdents(2)
getdomainname(2)
getgid(2)
getgroups(2)
gethostname(2)
getitimer(2)
getpagesize(2)
getpeername(2)
getpid(2)
getpriority(2)
getrandom(2)
getresuid(2)
getrlimit(2)
getrusage(2)
getsid(2)
getsockname(2)
getsockopt(2)
gettid(2)
gettimeofday(2)
getuid(2)
getunwind(2)
getxattr(2)
idle(2)
init_module(2)
inotify_add_watch(2)
inotify_init(2)
inotify_rm_watch(2)
io_cancel(2)
io_destroy(2)
io_getevents(2)
io_setup(2)
io_submit(2)
ioctl(2)
ioctl_console(2)
ioctl_fat(2)
ioctl_ficlonerange(2)
ioctl_fideduperange(2)
ioctl_fslabel(2)
ioctl_getfsmap(2)
ioctl_iflags(2)
ioctl_ns(2)
ioctl_pipe(2)
ioctl_tty(2)
ioctl_userfaultfd(2)
ioperm(2)
iopl(2)
ioprio_set(2)
ipc(2)
kcmp(2)
kexec_load(2)
keyctl(2)
kill(2)
landlock_add_rule(2)
landlock_create_ruleset(2)
link(2)
listen(2)
listxattr(2)
_llseek(2)
lookup_dcookie(2)
lseek(2)
madvise(2)
mbind(2)
membarrier(2)
memfd_create(2)
memfd_secret(2)
migrate_pages(2)
mincore(2)
mkdir(2)
mknod(2)
mlock(2)
mmap(2)
mmap2(2)
modify_ldt(2)
mount(2)
mount_setattr(2)
move_pages(2)
mprotect(2)
mq_getsetattr(2)
mremap(2)
msgctl(2)
msgget(2)
MSGOP(2)
msync(2)
nanosleep(2)
nfsservctl(2)
nice(2)
open(2)
open_by_handle_at(2)
openat2(2)
outb(2)
pause(2)
pciconfig_read(2)
perf_event_open(2)
perfmonctl(2)
personality(2)
pidfd_getfd(2)
pidfd_open(2)
pidfd_send_signal(2)
pipe(2)
pivot_root(2)
pkey_alloc(2)
poll(2)
posix_fadvise(2)
prctl(2)
pread(2)
process_madvise(2)
process_vm_readv(2)
ptrace(2)
query_module(2)
quotactl(2)
read(2)
readahead(2)
readdir(2)
readlink(2)
readv(2)
reboot(2)
recv(2)
recvmmsg(2)
remap_file_pages(2)
removexattr(2)
rename(2)
request_key(2)
restart_syscall(2)
rmdir(2)
rt_sigqueueinfo(2)
s390_guarded_storage(2)
s390_pci_mmio_write(2)
s390_runtime_instr(2)
s390_sthyi(2)
sched_get_priority_max(2)
sched_rr_get_interval(2)
sched_setaffinity(2)
sched_setattr(2)
sched_setparam(2)
sched_setscheduler(2)
sched_yield(2)
seccomp(2)
seccomp_unotify(2)
select(2)
semctl(2)
semget(2)
semop(2)
send(2)
sendfile(2)
sendmmsg(2)
set_mempolicy(2)
set_thread_area(2)
set_tid_address(2)
seteuid(2)
setfsgid(2)
setfsuid(2)
setgid(2)
setns(2)
setpgid(2)
setresuid(2)
setreuid(2)
setsid(2)
setuid(2)
setup(2)
setxattr(2)
sgetmask(2)
shmctl(2)
shmget(2)
SHMOP(2)
shutdown(2)
sigaction(2)
sigaltstack(2)
signal(2)
signalfd(2)
sigpending(2)
sigprocmask(2)
sigreturn(2)
sigsuspend(2)
sigwaitinfo(2)
socket(2)
socketcall(2)
socketpair(2)
splice(2)
spu_create(2)
spu_run(2)
stat(2)
statfs(2)
statx(2)
stime(2)
subpage_prot(2)
swapon(2)
symlink(2)
sync(2)
sync_file_range(2)
_syscall(2)
syscall(2)
syscalls(2)
sysctl(2)
sysfs(2)
sysinfo(2)
syslog(2)
tee(2)
time(2)
timer_create(2)
timer_delete(2)
timer_getoverrun(2)
timer_settime(2)
timerfd_create(2)
times(2)
tkill(2)
truncate(2)
umask(2)
umount(2)
uname(2)
UNIMPLEMENTED(2)
unlink(2)
unshare(2)
uselib(2)
userfaultfd(2)
ustat(2)
utime(2)
utimensat(2)
vfork(2)
vhangup(2)
vm86(2)
vmsplice(2)
wait(2)
wait4(2)
write(2)
open_how(2type)
intro(3)
a64l(3)
abort(3)
abs(3)
acos(3)
acosh(3)
addseverity(3)
adjtime(3)
aio_cancel(3)
aio_error(3)
aio_fsync(3)
aio_init(3)
aio_read(3)
aio_return(3)
aio_suspend(3)
aio_write(3)
alloca(3)
arc4random(3)
argz_add(3)
asin(3)
asinh(3)
assert(3)
assert_perror(3)
atan2(3)
atan(3)
atanh(3)
atexit(3)
atoi(3)
backtrace(3)
basename(3)
bcmp(3)
bcopy(3)
bindresvport(3)
bsd_signal(3)
bsearch(3)
bstring(3)
bswap(3)
btowc(3)
btree(3)
BYTEORDER(3)
bzero(3)
cabs(3)
cacos(3)
cacosh(3)
canonicalize_file_name(3)
carg(3)
casin(3)
casinh(3)
catan(3)
catanh(3)
catgets(3)
catopen(3)
cbrt(3)
ccos(3)
ccosh(3)
ceil(3)
cexp2(3)
cexp(3)
cfree(3)
cimag(3)
CIRCLEQ(3)
clearenv(3)
clock(3)
clock_getcpuclockid(3)
clog2(3)
clog(3)
clog10(3)
closedir(3)
CMSG(3)
confstr(3)
conj(3)
copysign(3)
cos(3)
cosh(3)
cpow(3)
cproj(3)
creal(3)
crypt(3)
csin(3)
csinh(3)
csqrt(3)
ctan(3)
ctanh(3)
ctermid(3)
ctime(3)
daemon(3)
dbopen(3)
des_crypt(3)
difftime(3)
dirfd(3)
div(3)
dl_iterate_phdr(3)
dladdr(3)
dlerror(3)
dlinfo(3)
dlopen(3)
dlsym(3)
drand48(3)
drand48_r(3)
duplocale(3)
dysize(3)
ecvt(3)
ecvt_r(3)
encrypt(3)
end(3)
endian(3)
envz_add(3)
erfc(3)
err(3)
errno(3)
error(3)
ether_aton(3)
euidaccess(3)
exec(3)
exit(3)
exp2(3)
exp(3)
exp10(3)
expm1(3)
fabs(3)
fclose(3)
fcloseall(3)
fdim(3)
fenv(3)
ferror(3)
fexecve(3)
fflush(3)
ffs(3)
fgetc(3)
fgetgrent(3)
fgetpwent(3)
fgetwc(3)
fgetws(3)
fileno(3)
finite(3)
flockfile(3)
floor(3)
fma(3)
fmax(3)
fmemopen(3)
fmin(3)
fmod(3)
fmtmsg(3)
fnmatch(3)
fopen(3)
fopencookie(3)
fpclassify(3)
fpurge(3)
fputwc(3)
fputws(3)
fread(3)
frexp(3)
fseek(3)
fseeko(3)
ftime(3)
ftok(3)
fts(3)
ftw(3)
futimes(3)
fwide(3)
gamma(3)
gcvt(3)
_Generic(3)
get_nprocs(3)
get_phys_pages(3)
getaddrinfo(3)
getaddrinfo_a(3)
getauxval(3)
getcontext(3)
getcwd(3)
getdate(3)
getdirentries(3)
getdtablesize(3)
getentropy(3)
getenv(3)
getfsent(3)
getgrent(3)
getgrent_r(3)
getgrnam(3)
getgrouplist(3)
gethostbyname(3)
gethostid(3)
getifaddrs(3)
getipnodebyname(3)
getline(3)
getloadavg(3)
getlogin(3)
getmntent(3)
getnameinfo(3)
getnetent(3)
getnetent_r(3)
getopt(3)
getpass(3)
getprotoent(3)
getprotoent_r(3)
getpt(3)
getpw(3)
getpwent(3)
getpwent_r(3)
getpwnam(3)
getrpcent(3)
getrpcent_r(3)
getrpcport(3)
gets(3)
getservent(3)
getservent_r(3)
getspnam(3)
getsubopt(3)
getttyent(3)
getusershell(3)
getutent(3)
getutmp(3)
getw(3)
getwchar(3)
glob(3)
gnu_get_libc_version(3)
grantpt(3)
group_member(3)
gsignal(3)
hash(3)
hsearch(3)
hypot(3)
iconv(3)
iconv_close(3)
iconv_open(3)
if_nameindex(3)
if_nametoindex(3)
ilogb(3)
index(3)
inet(3)
inet_net_pton(3)
inet_ntop(3)
inet_pton(3)
initgroups(3)
insque(3)
isalpha(3)
isatty(3)
isfdtype(3)
isgreater(3)
iswalnum(3)
iswalpha(3)
iswblank(3)
iswcntrl(3)
iswctype(3)
iswdigit(3)
iswgraph(3)
iswlower(3)
iswprint(3)
iswpunct(3)
iswspace(3)
iswupper(3)
iswxdigit(3)
j0(3)
key_setsecret(3)
killpg(3)
ldexp(3)
lgamma(3)
lio_listio(3)
localeconv(3)
log1p(3)
log2(3)
log(3)
log10(3)
logb(3)
login(3)
lrint(3)
lround(3)
lsearch(3)
lseek64(3)
makecontext(3)
makedev(3)
mallinfo(3)
malloc(3)
malloc_get_state(3)
__malloc_hook(3)
malloc_info(3)
malloc_stats(3)
malloc_trim(3)
malloc_usable_size(3)
mallopt(3)
matherr(3)
MAX(3)
MB_CUR_MAX(3)
MB_LEN_MAX(3)
mblen(3)
mbrlen(3)
mbrtowc(3)
mbsinit(3)
mbsnrtowcs(3)
mbsrtowcs(3)
mbstowcs(3)
mbtowc(3)
mcheck(3)
memccpy(3)
memchr(3)
memcmp(3)
memcpy(3)
memfrob(3)
memmem(3)
memmove(3)
mempcpy(3)
memset(3)
mkdtemp(3)
mkfifo(3)
mkstemp(3)
mktemp(3)
mpool(3)
mq_close(3)
mq_getattr(3)
mq_notify(3)
mq_open(3)
mq_receive(3)
mq_send(3)
mq_unlink(3)
mtrace(3)
nan(3)
netlink(3)
newlocale(3)
nextafter(3)
nextup(3)
nl_langinfo(3)
ntp_gettime(3)
on_exit(3)
open_memstream(3)
opendir(3)
openpty(3)
perror(3)
popen(3)
posix_fallocate(3)
posix_madvise(3)
posix_memalign(3)
posix_openpt(3)
posix_spawn(3)
pow(3)
pow10(3)
powerof2(3)
__ppc_get_timebase(3)
__ppc_set_ppr_med(3)
__ppc_yield(3)
profil(3)
program_invocation_name(3)
psignal(3)
pthread_atfork(3)
pthread_attr_init(3)
pthread_attr_setaffinity_np(3)
pthread_attr_setdetachstate(3)
pthread_attr_setguardsize(3)
pthread_attr_setinheritsched(3)
pthread_attr_setschedparam(3)
pthread_attr_setschedpolicy(3)
pthread_attr_setscope(3)
pthread_attr_setsigmask_np(3)
pthread_attr_setstack(3)
pthread_attr_setstackaddr(3)
pthread_attr_setstacksize(3)
pthread_cancel(3)
pthread_cleanup_push(3)
pthread_cleanup_push_defer_np(3)
pthread_create(3)
pthread_detach(3)
pthread_equal(3)
pthread_exit(3)
pthread_getattr_default_np(3)
pthread_getattr_np(3)
pthread_getcpuclockid(3)
pthread_join(3)
pthread_kill(3)
pthread_kill_other_threads_np(3)
pthread_mutex_consistent(3)
pthread_mutexattr_getpshared(3)
pthread_mutexattr_init(3)
pthread_mutexattr_setrobust(3)
pthread_rwlockattr_setkind_np(3)
pthread_setaffinity_np(3)
pthread_setcancelstate(3)
pthread_setconcurrency(3)
pthread_setname_np(3)
pthread_setschedparam(3)
pthread_setschedprio(3)
pthread_sigmask(3)
pthread_sigqueue(3)
pthread_spin_init(3)
pthread_spin_lock(3)
pthread_testcancel(3)
pthread_tryjoin_np(3)
pthread_yield(3)
ptsname(3)
putenv(3)
putgrent(3)
putpwent(3)
puts(3)
putwchar(3)
qecvt(3)
qsort(3)
raise(3)
rand(3)
random(3)
random_r(3)
rcmd(3)
re_comp(3)
readdir(3)
readdir_r(3)
realpath(3)
recno(3)
regex(3)
remainder(3)
remove(3)
remquo(3)
resolver(3)
rewinddir(3)
rexec(3)
rint(3)
round(3)
roundup(3)
rpc(3)
rpmatch(3)
rtime(3)
rtnetlink(3)
scalb(3)
scalbln(3)
scandir(3)
sched_getcpu(3)
seekdir(3)
sem_close(3)
sem_destroy(3)
sem_getvalue(3)
sem_init(3)
sem_open(3)
sem_post(3)
sem_unlink(3)
sem_wait(3)
setaliasent(3)
setenv(3)
__setfpucw(3)
setjmp(3)
setlocale(3)
setlogmask(3)
setnetgrent(3)
shm_open(3)
siginterrupt(3)
signbit(3)
significand(3)
sigpause(3)
sigqueue(3)
sigset(3)
SIGSETOPS(3)
sigvec(3)
sigwait(3)
sin(3)
sincos(3)
sinh(3)
sleep(3)
sockatmark(3)
sqrt(3)
STAILQ(3)
static_assert(3)
statvfs(3)
stdarg(3)
stdin(3)
stdio(3)
stdio_ext(3)
stpncpy(3)
strcasecmp(3)
strchr(3)
strcmp(3)
strcoll(3)
strcpy(3)
strdup(3)
strerror(3)
strfmon(3)
strfromd(3)
strfry(3)
strftime(3)
string(3)
strlen(3)
strncat(3)
strnlen(3)
strpbrk(3)
strptime(3)
strsep(3)
strsignal(3)
strspn(3)
strstr(3)
strtod(3)
strtoimax(3)
strtok(3)
strtol(3)
strtoul(3)
strverscmp(3)
strxfrm(3)
swab(3)
syslog(3)
system(3)
sysv_signal(3)
TAILQ(3)
tan(3)
tanh(3)
tcgetpgrp(3)
tcgetsid(3)
telldir(3)
tempnam(3)
termios(3)
tgamma(3)
timegm(3)
timeradd(3)
tmpfile(3)
tmpnam(3)
toascii(3)
toupper(3)
towctrans(3)
towlower(3)
towupper(3)
trunc(3)
tsearch(3)
ttyname(3)
ttyslot(3)
tzset(3)
ualarm(3)
ulimit(3)
undocumented(3)
ungetwc(3)
unlocked_stdio(3)
unlockpt(3)
updwtmp(3)
uselocale(3)
usleep(3)
wcpcpy(3)
wcpncpy(3)
wcrtomb(3)
wcscasecmp(3)
wcscat(3)
wcschr(3)
wcscmp(3)
wcscpy(3)
wcscspn(3)
wcsdup(3)
wcslen(3)
wcsncasecmp(3)
wcsncat(3)
wcsncmp(3)
wcsncpy(3)
wcsnlen(3)
wcsnrtombs(3)
wcspbrk(3)
wcsrchr(3)
wcsrtombs(3)
wcsspn(3)
wcsstr(3)
wcstoimax(3)
wcstok(3)
wcstombs(3)
wcswidth(3)
wctob(3)
wctomb(3)
wctrans(3)
wctype(3)
wcwidth(3)
wmemchr(3)
wmemcmp(3)
wmemcpy(3)
wmemmove(3)
wmemset(3)
wordexp(3)
xdr(3)
y0(3)
EOF(3const)
EXIT_SUCCESS(3const)
NULL(3const)
printf.h(3head)
sysexits.h(3head)
aiocb(3type)
blkcnt_t(3type)
blksize_t(3type)
cc_t(3type)
clock_t(3type)
clockid_t(3type)
dev_t(3type)
div_t(3type)
double_t(3type)
epoll_event(3type)
fenv_t(3type)
FILE(3type)
id_t(3type)
intmax_t(3type)
intN_t(3type)
intptr_t(3type)
iovec(3type)
itimerspec(3type)
lconv(3type)
mode_t(3type)
off_t(3type)
ptrdiff_t(3type)
size_t(3type)
sockaddr(3type)
stat(3type)
time_t(3type)
timer_t(3type)
timespec(3type)
timeval(3type)
tm(3type)
va_list(3type)
void(3type)
intro(4)
cciss(4)
console_codes(4)
cpuid(4)
dsp56k(4)
fd(4)
full(4)
fuse(4)
hd(4)
hpsa(4)
initrd(4)
lirc(4)
loop(4)
lp(4)
mem(4)
mouse(4)
msr(4)
null(4)
pts(4)
ram(4)
random(4)
rtc(4)
sd(4)
sk98lin(4)
smartpqi(4)
st(4)
tty(4)
ttyS(4)
vcs(4)
veth(4)
wavelan(4)
intro(5)
acct(5)
charmap(5)
core(5)
dir_colors(5)
ELF(5)
erofs(5)
filesystems(5)
ftpusers(5)
group(5)
hosts(5)
hosts.equiv(5)
issue(5)
locale(5)
motd(5)
networks(5)
nologin(5)
nss(5)
passwd(5)
proc(5)
protocols(5)
repertoiremap(5)
rpc(5)
securetty(5)
services(5)
shells(5)
slabinfo(5)
sysfs(5)
termcap(5)
tmpfs(5)
ttytype(5)
tzfile(5)
utmp(5)
intro(6)
intro(7)
address_families(7)
AIO(7)
ARMSCII-8(7)
arp(7)
ascii(7)
attributes(7)
boot(7)
bootparam(7)
BPF-HELPERS(7)
Capabilities(7)
cgroup_namespaces(7)
cgroups(7)
charsets(7)
complex(7)
cp1251(7)
cp1252(7)
cpuset(7)
credentials(7)
ddp(7)
environ(7)
epoll(7)
fanotify(7)
feature_test_macros(7)
fifo(7)
futex(7)
glob(7)
hier(7)
hostname(7)
icmp(7)
inode(7)
inotify(7)
ip(7)
ipc_namespaces(7)
ipv6(7)
ISO_8859-1(7)
ISO_8859-2(7)
ISO_8859-3(7)
ISO_8859-4(7)
ISO_8859-5(7)
ISO_8859-6(7)
ISO_8859-7(7)
ISO_8859-8(7)
ISO_8859-9(7)
ISO_8859-10(7)
ISO_8859-11(7)
ISO_8859-13(7)
ISO_8859-14(7)
ISO_8859-15(7)
ISO_8859-16(7)
kernel_lockdown(7)
keyrings(7)
KOI8-R(7)
KOI8-U(7)
Landlock(7)
libc(7)
locale(7)
mailaddr(7)
man-pages(7)
man(7)
math_error(7)
mount_namespaces(7)
mq_overview(7)
namespaces(7)
netdevice(7)
netlink(7)
network_namespaces(7)
nptl(7)
numa(7)
operator(7)
packet(7)
path_resolution(7)
persistent-keyring(7)
pid_namespaces(7)
pipe(7)
pkeys(7)
posixoptions(7)
process-keyring(7)
pthreads(7)
pty(7)
queue(7)
random(7)
raw(7)
regex(7)
rtnetlink(7)
sched(7)
sem_overview(7)
session-keyring(7)
shm_overview(7)
sigevent(7)
signal-safety(7)
signal(7)
sock_diag(7)
socket(7)
spufs(7)
standards(7)
string_copying(7)
SUFFIXES(7)
symlink(7)
system_data_types(7)
sysvipc(7)
tcp(7)
termio(7)
thread-keyring(7)
time(7)
time_namespaces(7)
udp(7)
udplite(7)
unicode(7)
units(7)
UNIX(7)
uri(7)
user-keyring(7)
user_namespaces(7)
user-session-keyring(7)
UTF-8(7)
uts_namespaces(7)
vDSO(7)
vsock(7)
x25(7)
xattr(7)
intro(8)
iconvconfig(8)
ld.so(8)
ldconfig(8)
nscd(8)
sln(8)
tzselect(8)
zdump(8)
zic(8)

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

On 2023-08-14 08:49, Brian Inglis wrote:
>> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=aab14503ef101d918046aeaa941f226685fe7bf5>
>>
>> #!/bin/sh
>>
>> # Copyright 2023, Alejandro Colomar <alx@kernel.org>
>> # SPDX-License-Identifier: GPL-3.0-or-later
>>
>> sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
>> | sed -E '/\/intro./! s/.*\.([[:digit:]])\>/\11\t&/' \
>> | sed -E '/\/intro./! s/.*\.([[:digit:]])([[:alnum:]]+)/\12.\2\t&/' \
>> | sed -E '            s/\t(.*)/&\n\1/' \
>> | sed -E '/\t/        s/([^[:digit:]])[_-]([^[:digit:]])/\1\2/g' \
>> | sed -E '/\t/        s/[_-]/_/g' \
>> | sed -E '/\t/        {N;s/\n/\t/;}' \
>> | sort -fV \
>> | cut -f3;
> 
> Perl RPM::VersionSort rpmvercmp produces the desired order, ignoring leading 
> non-alphanumerics, treating all non-alphanumerics as field delimiters, treating 
> alphabetic and numeric strings as separate fields; see attached log.

Nice, it seems they implement a differen version sorting than GNU coreutils' sort(1).

Cheers,
Alex

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Deri]

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

On Sunday, 13 August 2023 21:30:34 BST Brian Inglis wrote:
> On 2023-08-12 14:02, Deri wrote:
> > On Saturday, 12 August 2023 18:02:24 BST Brian Inglis wrote:
> >> On 2023-08-07 17:14, Deri wrote:
> >>> On Monday, 7 August 2023 09:45:22 BST Alejandro Colomar wrote:
> >>>> Nevertheless, now I remember Deri told me he hardcoded a lot of stuff
> >>>> for 1.22.4 which should be removed after the release of 1.23.0, so it
> >>>> seems that the time has come to chop a lot of stuff from there.
> >>>> 
> >>>> Deri, would you mind simplifying the scripts assuming a Build-dep of
> >>>> groff(>=1.23.0)?
> >>> 
> >>> Hi Alex, Brian,
> >>> 
> >>> I have done some work on building the pdf. One improvement is any
> >>> warnings
> >>> output by groff, i.e. use of the deprecated .PDF macro, now identify the
> >>> particular man page and line number accurately.
> >>> 
> >>> I have attached two new replacement LinuxManBook directories. The first,
> >>> 1.23.0, will run on a stock groff 1.23.0 system. The second, 1.23.0+,
> >>> runs
> >>> with the latest gropdf which has a number of advantages for this project
> >>> -
> >>> you will find the resulting pdf to be more than 5mb smaller, and the
> >>> page
> >>> numbers in the overview pane match up with the page number at the bottom
> >>> of each page.
> >>> 
> >>> The file NewGropdf.pdf contains description of some of the features in
> >>> the
> >>> new gropdf.
> >>> 
> >>> Both of these should continue to work if the groff version changes,
> >>> thanks
> >>> to Brian's helpful suggestion to include /usr/share/groff/current in the
> >>> font path, but I have achieved this by specifying it in an -F flag
> >>> rather
> >>> than patching gropdf.
> >> 
> >> Nice work Deri!
> >> 
> >> The official 6.05.01 book hyphenates words across page breaks more than
> >> standard 1.23.0 and new 1.23.0+ gropdf books.
> > 
> > I'd like to investigate this to understand why this is happening, please
> > can you give me example page numbers which illustrate this.
> 
> Hi Deri,
> 
> Please see attached awk script and logs showing pages with end of page
> "hyphens" in text of PDFs from `pdftotext -layout`: "official" PDF has 47,
> newer PDFs break only at 5 compound word joins or double dashes.
> 
> >> File sizes are official 6.05.01 ~13.3MB, 200k more than standard 1.23.0
> >> ~13MB, which is >~5MB more than new 1.23.0+ gropdf <~8MB.
> >> 
> >> I now see page footers on all pages!
> >> 
> >> I noticed that new 1.23.0+ seems to set some lines, especially tables, a
> >> little tighter (perhaps because of space handling), but *only* the first
> >> page "intro(1)" has half the normal spacing from the page header to the
> >> first heading!
> > 
> > Yes, I can see the difference in intro(1) and I can see a bug in the
> > version of an.tmac I provided which may affect hyphenation. Also a page
> > number example of the tighter table would be helpful.
> 
> The impression of tighter table spacing seems to be an artifact of more
> consistent text and space rendering by pdftotext as pointed out in the
> diffs, and as you explain below.
> 
> >> [I also noticed that *poppler* `pdf2text -layout` (used to diff the
> >> content
> >> amd layout) prints the .SH NAME and options dashes as en-dash from the
> >> official 6.05.01 book, but prints minus from standard 1.23.0 and new
> >> 1.23.0+ gropdf.]
> > 
> > This is intentional (and probably desirable). The pdf has a mapping so
> > that
> > the groff character \- is displayed as HYPHEN (U+0201) but when text is
> > copy/ pasted from the pdf it is converted to HYPHEN-MINUS (U+002D) which
> > is the character you get when you hit hyphen on the keyboard. This means
> > that if you are copy/pasteing from examples in the man page which
> > includes hyphens then your shell will interpret it correctly.
> > 
> >> I notice a number of widows and orphans, but that may be the man macros
> >> or
> >> groff commands not checking for sufficient space left on the page before
> >> rendering text: allowing 4em before heading spacing, 3em before para
> >> spacing would probably help, at the cost of larger bottom margins; and
> >> groff footers need to allow extra space to prevent widows by allowing
> >> them
> >> to intrude.
> > 
> > This probably needs a bit of tender curation! Bear in mind that the
> > BuildLinuxMan.pl script uses the flags "-dpaper=a4 -P-pa4" so if the man
> > page author has designed for a different page size the widows/orphans may
> > well be different.
> 
> As a Northern-American can I change your uses of "p?a4" to letter in the
> script and expect it to work?
> I added a paper variable, made the changes, it seems to work, and reduces
> end of page hyphens to one compound word instance in mbind(2); log
> attached:

Hi Brian and Alex,

I'm afraid the dangling page hyphens are all my fault. :-(

Line missing in the bespoke an.tmac I provided, new version attached. I know 
Alex wants to run against a stock version of groff, with minimal 
customisation, and, once my branch is merged, there will be further pruning, 
but unless you add to Branden's wish list to include an ability to control the 
hierarchy of the bookmark panel, you will need a customised an.tmac. The 
reason is because the stock an.tmac has a hard coded hierarchy where the .TH 
line is given level 1 but as you want to have separate sections these need to 
be level one and everything else is moved up a level. Of course this just 
means making the starting level configurable on the command line, i.e. 
-r startbkmk=2 or some such. Another change which would need to be accepted is 
to allow a fourth parameter to .MR which is the destination name. Normally the 
name of the destination is derived from the first two parameters concatenated 
with "_", but if the name part of the .MR call to the man page includes non-
ascii characters (such as ".MR my\-lovely\-page 7 ,") then it needs to provide 
a "clean" destination name.

Sorting

I decided to use Sort::Versions (rather than RPM::VersionSort) because it is 
available as a package on my system. Seems to do the job.

Paper

You can now specify the paper size for the book on the command line as "-paper 
size".

Fonts

There are 2 reasons I included fonts in the build environment:-

A) The man pages which define the various iso-8859 pages contain many glyphs 
which are not defined in the standard groff fonts, so I used the Tinos font 
from google which improves the coverage. If you want to get rid of the fonts, 
and rely on just the fonts in groff, you can change line 4 of anmark.tmac to:-

.special S U-TR

Which is an improvement on the standard fonts, and should be available as 
standard if the URW fonts were found when groff was built. You will see 
differences in iso-8859-7 and iso-8859-8 for example.

B) If you build the LinuxManBook using the 1.23.0+ flavour (with the newer 
gropdf that produces a substantially smaller pdf) it requires a slightly 
different font format so needs the embedded font directory. If you have 
installed groff from the deri-gropdf-ng the new format fonts will have been 
installed, so the embedded font directory can be removed.

Makefile

The simplest option would be to add a new rule to the Makefile which is 
dependent on all the man pages have been built, and cd's into the scripts/
LinuxManBook directory and calls the program with the location where the man 
pages exist. However, I suspect Alex fancies something more complicated by 
replacing the perl with a hybrid of shell command and make magic.

I attach a new copy of BuildLinuxMan.pl which is an amalgam of mine and 
Brian's code. This has the new -paper flag.

Alex's MR branch

The new program now recognises existing .MR's in the document and provides the 
"clean" destination name, so it should run against the new branch.

> 	nodemask ... on-
> 	...
> 	line, ...
> 
> There appear to be 24 single word instances of online and 12 outdated
> hyphenated compound word instances of on-line across all man pages.
> 
> UI: I also noticed, while looking for tables to compare, that pages are
> ordered by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g
> ISO_8859-2 is after ISO_8859-16 which may not be as expected.
> Used rpmvercmp in last line of perl sub sortman and works as expected.

I have used Sort::Versions (see above), thanks for the suggestion.

> Tech nitpick: .Z is still recognized by GUIs as compress output
> (UNIX-compressed file) - is there no other file type suffix used for
> ditroff intermediate output? Aha - Alex says .set:
> 
> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
> 
Well, that's settled.

> Added variables and changed those also in BLM-letter.pl: copy attached.
> 
> > Thanks for your help.
> 
> Happy to help in any way.

Hope you're happy with this version.

Cheers

Deri

[-- Attachment #2: BuildLinuxMan.pl --]
[-- Type: application/x-perl, Size: 6960 bytes --]

[-- Attachment #3: anmark.tmac --]
[-- Type: text/plain, Size: 131 bytes --]

.nr PDFOUTLINE.FOLDLEVEL 0
.defcolor pdf:href.colour rgb 0.00 0.25 0.75
.pdfinfo /Title "The Linux man-pages Book"
.special S U-TR

[-- Attachment #4: an.tmac --]
[-- Type: text/troff, Size: 47188 bytes --]

.\" groff implementation of man(7) package
.\"
.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
.\"      Written by James Clark (jjc@jclark.com)
.\" Enhanced by: Werner Lemberg <wl@gnu.org>
.\"              Larry Kollar <kollar@alltel.net>
.\"              G. Branden Robinson <g.branden.robinson@gmail.com>
.\"
.\" Thanks to Deri James for illustrating PDF bookmark features.
.\"
.\" This file is part of groff.
.\"
.\" groff is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" groff is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see
.\" <http://www.gnu.org/licenses/>.
.
.
.\" Put site additions in the file man.local, loaded near the end of
.\" this file.  To add things to TH, use '.am1 TH'.
.
.if !\n(.g \
.  ab groff man macros require groff extensions; aborting
.
.do if d TH .nx
.
.do nr *groff_an_tmac_C \n[.cp]
.cp 0
.
.\" Package-internal names start with "an-" and are subject to change,
.\" such as migration to "an*" (in progress).
.
.\" Define a string for use in diagnostic messages.
.ds an an.tmac\"
.
.\" We use the .stringup request from groff 1.23, but nothing breaks if
.\" it is undefined; the output is unchanged in appearance from earlier
.\" releases.
.if (\n[.x]\n[.y] < 118) \{\
.  ds an-msg \*[an]: groff man macros require groff 1.18 or later,\"
.  as an-msg " but found groff \n[.x].\n[.y]; aborting\"
.  ab \*[an-msg]
.\}
.
.\" === Define macros. ===
.\"
.\" Macros that are part of the external interface (TH, SH, P, etc.) or
.\" that are called by traps of any kind must be defined with `de1`
.\" because they might be called from a context where compatibility mode
.\" is enabled.  For other macros, `de` suffices.
.
.de an-warn
.  tm \*[an]:\\n[.F]:\\n[.c]: warning: \\$*
..
.
.de an-style-warn
.  if \\n[CHECKSTYLE] \
.    tm \*[an]:\\n[.F]:\\n[.c]: style: \\$*
..
.
.de an-deprecation-warn
.  if (\\n[CHECKSTYLE] > 1) \
.    an-style-warn use of deprecated macro: .\\$0
..
.
.de1 an-blank-line-trap
.  if (\\n[CHECKSTYLE] > 2) \
.    an-style-warn blank line in input
.  sp
..
.
.de1 an-leading-space-trap
.  if (\\n[CHECKSTYLE] > 2) \
.    if \\n[.u] \
.      an-style-warn \\n[lsn] leading space(s) on input line
.  br
.  nop \h'\\n[lss]u'\c
..
.
.\" Define alternate requests to handle continuous rendering.
.\"
.\" This .ne replacement avoids page breaks; instead, the page length is
.\" increased to the necessary amount.
.de an-ne
.  ie \\n[.$] .nr an-amount (v;\\$*)
.  el         .nr an-amount 1v
.  if (\\n[an-amount] >= \\n[.t]) \
.    pl +(\\n[an-amount]u - \\n[.t]u + 1v)
.  rr an-amount
..
.
.\" This .bp replacement for continuous rendering mode adjusts the page
.\" length to the current position so that no empty lines are inserted.
.de an-bp
.  pl \\n[nl]u
..
.
.\" We need an end-of-input macro to flush any pending output line and
.\" write the footer for the final man page rendered.  We can also be
.\" called by andoc when switching to an mdoc(7) page, irrespective of
.\" continuous rendering mode.
.de1 an-end
.  if !r an-TH-was-called .return
.  if \\n[cR] \{\
.    \" We might have a pending output line that is not yet broken, and
.    \" also be 1v from the bottom of the page.  If we break (or flush)
.    \" the output line now, the page will get ejected afterward and
.    \" troff will exit because we're in an end-of-input macro--our
.    \" footer will never be output.  So, if that is the case, further
.    \" extend the page length by 1v.
.    if ((\\n[.p] - \\n[nl]) <= \\n[.V]) .pl +1v
.    br
.    pl +1v
.    sp 1v
.    an-footer
.    \" If we're processing multiple documents and have started a new
.    \" one, draw a line between this footer and the next header.
.    if !'\\n[.F]'' \{\
.      pl +1v
.      nf
.      ti 0
.      nop \D'l \\n[LL]u 0'
.      fi
.    \}
.  \}
.  rr an-TH-was-called
.  ch an-header
.  an*break-page-with-new-number
..
.
.\" Move macros into place for continuous rendering.
.de an-set-up-continuous-rendering
.  rn ne an-real-ne
.  rn bp an-real-bp
.  rn an-ne ne
.  rn an-bp bp
.  em an-end
..
.
.de an*reset-hyphenation-mode
.  ie \\n[HY] \{\
.    \" No page breaks occur in continuous rendering.
.    ie \\n[cR] \
.      nr an*hyphenation-mode \\n[\\*[locale]*hyphenation-mode-base]
.    el \
.      nr an*hyphenation-mode \\n[\\*[locale]*hyphenation-mode-trap]
.  \}
.  el \
.    nr an*hyphenation-mode 0
.  hy \\n[an*hyphenation-mode]
..
.
.de an-reset-tab-stops
.  ta T .5i
..
.
.de an-reset-paragraph-spacing
.  ie \\n[.$] .nr PD (v;\\$1)
.  el         .nr PD (.4v >? \n[.V])
..
.
.de an-reset-margin-and-inset-level
.  nr an-inset-level 1
.  nr an-margin \\n[BP]
.  nr an-saved-margin1 \\n[IN]
.  nr an-prevailing-indent \\n[IN]
.  nr an-saved-prevailing-indent1 \\n[IN]
..
.
.\" Break the page and update its number depending on the C (consecutive
.\" numbering) register.
.\"
.\" Corner case: if formatting multiple documents and P (starting page
.\" number) is defined but C is not set, start numbering each document
.\" at \n[P].  Not strictly necessary if not switching macro packages.
.de an*break-page-with-new-number
.  ie \\n[C] .bp (\\n[%] + 1) \" argument NOT redundant before page 1
.  el \{\
.    ie r P .bp \\n[P]
.    el     .bp 1
.  \}
..
.
.\" Localize manual section titles for English.
.de an*localize-strings
.  ds an*section1 General Commands Manual\"
.  ds an*section2 System Calls Manual\"
.  ds an*section3 Library Functions Manual\"
.  ds an*section4 Kernel Interfaces Manual\"
.  ds an*section5 File Formats Manual\"
.  ds an*section6 Games Manual\"
.  ds an*section7 Miscellaneous Information Manual\"
.  ds an*section8 System Manager's Manual\"
.  ds an*section9 Kernel Developer's Manual\"
..
.
.de an*cln
.  ds \\$1
.  als an*cln:res \\$1
.  shift
.  ds an*cln:res \\$*\"
.  ds an*cln:char \\*[an*cln:res]
.  stringdown an*cln:res
.  substring an*cln:char 0 0
.  if '\\*[an*cln:char]'\%' .substring an*cln:res 1
.  rm an*cln:char
..
.
.\" Write a bookmark/anchor/link target $2 at hierarchical depth $1.
.de an*bookmark
.  if \\n[an*is-output-pdf] \{\
.    if (\\n[.$]>2) .an*cln an*page-ref-nm \\$3\"
.    ie (\\$1=1) .pdfbookmark -T "\\*[an*page-ref-nm]" \\$1 \\$2
.    el .pdfbookmark \\$1 \\$2
.  \}
..
.
.\" Begin man page.
.\" .TH topic section[ extra1[ extra2[ extra3]]]
.de1 TH
.  if ((\\n[.$] < 2) : (\\n[.$] > 5)) \
.    an-style-warn .\\$0 expects 2 to 5 arguments, got \\n[.$]
.
.  blm an-blank-line-trap
.  lsm an-leading-space-trap
.
.  \" If batch processing (rendering multiple) man page documents, we
.  \" must handle the end of a previous document.
.  if \\n[an*need-titles-reset] \{\
.    if \\n[cR] .an-end
.
.    \" Clear the page header trap so it is not sprung with stale
.    \" information.
.    ch an-header
.    an*break-page-with-new-number
.  \}
.  if \\n[C] .rr P
.
.  nr an-TH-was-called 1 \" an-end can make certain assumptions.
.
.  \" Set up rendering parameters.  We do this in TH instead of only
.  \" once when initializing the package because when rendering multiple
.  \" pages, a previous page might have changed them.
.
.  fam \\*[an*body-family]
.  ft R
.
.  nr PS    10z \" default type size
.  nr PS-SS 10z
.  nr PS-SH 10.95z
.  nr VS    12p
.
.  \" use sizes similar to LaTeX
.  if t \{\
.    ie (\\n[S] == 11) \{\
.      nr PS    10.95z
.      nr PS-SS 10.95z
.      nr PS-SH 12z
.      nr VS    13.6p
.    \}
.    el \{\
.      if (\\n[S] == 12) \{\
.        nr PS    12z
.        nr PS-SS 12z
.        nr PS-SH 14.4z
.        nr VS    14.5p
.      \}
.    \}
.  \}
.
.  \" The previous document rendered in a batch may have been in a
.  \" different language.  If this one is in English, (re-)init strings.
.  if '\\*[locale]'english' .an*localize-strings
.
.  ps \\n[PS]u
.  vs \\n[VS]u
.  ad \\*[AD]
.  ll \\n[LL]u
.
.  \" We've seen no tbl(1) tables yet in this document.
.  rr TW
.  nr an-was-tbl-failure-reported 0
.
.  an*reset-hyphenation-mode
.  an-reset-tab-stops
.  an-reset-paragraph-spacing
.  an-reset-margin-and-inset-level
.
.  nr an-tag-separation 1n
.  nr an-need-no-space-mode 0
.  nr an-need-break 0
.  nr an-is-in-diversion 0
.  nr an*is-in-example 0
.
.  ds an*topic "\\$1\"
.  if \\n[CT] .stringup an*topic
.  ds an*section "\\$2\"
.  ie (\\n[.$] > 4) .ds an-extra3 "\\$5\"
.  el \{\
.    \" Simulate switch/case in roff.
.          ie '\\$2'1' .ds an-extra3 \\*[an*section1]\"
.    el \{.ie '\\$2'2' .ds an-extra3 \\*[an*section2]\"
.    el \{.ie '\\$2'2type' .ds an-extra3 \\*[an*section2type]\"
.    el \{.ie '\\$2'3' .ds an-extra3 \\*[an*section3]\"
.    el \{.ie '\\$2'3const' .ds an-extra3 \\*[an*section3const]\"
.    el \{.ie '\\$2'3head' .ds an-extra3 \\*[an*section3head]\"
.    el \{.ie '\\$2'3type' .ds an-extra3 \\*[an*section3type]\"
.    el \{.ie '\\$2'4' .ds an-extra3 \\*[an*section4]\"
.    el \{.ie '\\$2'5' .ds an-extra3 \\*[an*section5]\"
.    el \{.ie '\\$2'6' .ds an-extra3 \\*[an*section6]\"
.    el \{.ie '\\$2'7' .ds an-extra3 \\*[an*section7]\"
.    el \{.ie '\\$2'8' .ds an-extra3 \\*[an*section8]\"
.    el \{.ie '\\$2'9' .ds an-extra3 \\*[an*section9]\"
.    el                .ds an-extra3 \" empty
.    \}\}\}\}\}\}\}\}\}\}\}\}
.  \}
.
.  ds an-extra1 "\\$3\"
.  ie (\\n[.$] > 3)    .ds an-extra2 "\\$4\"
.  el                  .ds an-extra2 \" empty; but .AT/.UC can override
.
.  if '\\*[an-extra1]'' \{\
.    ds an-msg .\\$0 missing third argument; suggest document\"
.    as an-msg " modification date in ISO 8601 format (YYYY-MM-DD)\"
.    an-style-warn \\*[an-msg]
.    rm an-msg
.  \}
.
.  if '\\*[an-extra2]'' \{\
.    ds an-msg .\\$0 missing fourth argument; suggest package/project\"
.    \" Yes, that's one double quote, then three, then two.
.    as an-msg " name and version (e.g., """groff 1.23.0"")\"
.    an-style-warn \\*[an-msg]
.    rm an-msg
.  \}
.
.  if '\\$5\\*[an-extra3]'' \{\
.    ds an-msg .\\$0 missing fifth argument and second argument '\\$2'\"
.    as an-msg " not a recognized manual section; specify its title\"
.    an-style-warn \\*[an-msg]
.    rm an-msg
.  \}
.
.  \" Initialize environment for headers and footers.
.  ev an*env-header-and-footer
.  ps \\n[PS]u
.  vs \\n[VS]u
.  lt \\n[LT]u
.  an*abbreviate-page-topic
.  \" If AT or UC is called, we will need to abbreviate again.
.  an*abbreviate-inner-footer
.  ev
.
.  \" HTML gets the topic without any abbreviation, since it's metadata.
.  if \\n[an*is-output-html] \{\
.    DEVTAG-TL
.    nop \\*[an*topic]
.    DEVTAG-EO-TL
.  \}
.
.  \" A bookmark is attached to the page header, but only on the first
.  \" page of the document.
.  nr an*was-TH-bookmark-emitted 0
.  an-header
.
.  if !\\n[cR] \{\
.    wh 0 an-header
.    ie r FT .nr an*footer-location \\n[FT]
.    el      .nr an*footer-location (-.5i)
.    wh \\n[an*footer-location]u an-footer
.    wh (\\n[an*footer-location]u - .5i) an-break-body-text
.    rr an*footer-location
.    \}
.  \}
.
.  nr an*need-titles-reset 1
..
.
.\" Support legacy AT&T and BSD Unix man pages.
.
.\" Designate an AT&T Unix man page.
.\" .AT [system-id[ release-id]]
.de1 AT
.  nop \\*[an-deprecation-warn]\\
.  ds an-extra2 "7th Edition\"
.  if "\\$1"3" .ds an-extra2 "7th Edition\"
.  if "\\$1"4" .ds an-extra2 "System III\"
.  if "\\$1"5" \{\
.    ie "\\$2"" .ds an-extra2 "System V\"
.    el         .ds an-extra2 "System V Release \\$2\"
.  \}
.  ev an*env-header-and-footer
.  an*abbreviate-inner-footer
.  ev
..
.
.\" Designate a BSD Unix man page.
.\" .UC [system-id]
.de1 UC
.  nop \\*[an-deprecation-warn]\\
.  ds an-extra2 "3rd Berkeley Distribution\"
.  if "\\$1"3" .ds an-extra2 "3rd Berkeley Distribution\"
.  if "\\$1"4" .ds an-extra2 "4th Berkeley Distribution\"
.  if "\\$1"5" .ds an-extra2 "4.2 Berkeley Distribution\"
.  if "\\$1"6" .ds an-extra2 "4.3 Berkeley Distribution\"
.  if "\\$1"7" .ds an-extra2 "4.4 Berkeley Distribution\"
.  ev an*env-header-and-footer
.  an*abbreviate-inner-footer
.  ev
..
.
.\" Restore tab stops to defaults.
.de1 DT
.  nop \\*[an-deprecation-warn]\\
.  an-reset-tab-stops
..
.
.\" Restore inter-paragraph spacing to default (or set it to argument).
.\" .PD [distance]
.de1 PD
.  nop \\*[an-deprecation-warn]\\
.  nop \\*[an-reset-paragraph-spacing]\\
..
.
.\" Write the page header; can be redefined by man.local.
.\"
.\" In continuous rendering mode, we need to extend the page length to
.\" accommodate the vertical size of our header (plus any spacing).
.if d PT .ig
.de1 PT
.  ie \\n[cR] .pl +1v
.  el         .sp .5i
.  if !\\n[an*was-TH-bookmark-emitted] \{\
.\" .    an*bookmark 2 \E*[an*page-ref-string]
.    nr an*was-TH-bookmark-emitted 1
.  \}
.  tl '\\*[an-pageref]'\\*[an-extra3]'\\*[an-pageref]'
.  ie \\n[cR] \{\
.    pl +1v
.    sp 1v
.  \}
.  el .sp |1i
..
.
.\" Write the page footer; can be redefined by man.local.
.\"
.\" In continuous rendering mode, we need to extend the page length to
.\" accommodate the vertical size of our footer (plus any spacing).
.if d BT .ig
.de1 BT
.  if \\n[cR] .pl +1v
.  ie \\n[D] \{\
.    if o .tl '\\*[an*ifoot]'\\*[an-extra1]'\\*[an*ofoot]'
.    if e .tl '\\*[an*ofoot]'\\*[an-extra1]'\\*[an*ifoot]'
.  \}
.  el \
.    tl '\\*[an*ifoot]'\\*[an-extra1]'\\*[an*ofoot]'
..
.
.\" Abbreviate the page topic if it's too long for the header.  Leaves
.\" string an-pageref defined for use in .PT and .an-footer.  Also
.\" leaves an*topic-abbv for possible use by .PT and .BT re-definers.
.\" Call this only from within the header/footer environment.
.de an*abbreviate-page-topic
.  ds an*topic-abbv \\*[an*topic]\" might not get abbreviated at all
.  ds an*topic-string \\*[an*topic]\"
.  ds an-ellipsis \|.\|.\|.\|\"
.  \" an*page-ref-string is left unmodified for internal use, such as
.  \" PDF bookmarks.
.  ds an*page-ref-string \\*[an*topic](\\*[an*section])\"
.  ds an-pageref \\*[an*topic-abbv](\\*[an*section])\"
.  an*cln an*page-ref-bm-nm \\*[an*topic]_\\*[an*section]\"
.  stringdown an*page-ref-bm-nm
.  nr an-header-width \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
.  while (\\n[an-header-width] >= \\n[.lt]) \{\
.    \" The page topic is too long; trim some bits out of the middle.
.    length an*topic-length \\*[an*topic-string]
.    \" roff uses truncating division.  Remove an additional character
.    \" on each side of the midpoint to account for the ellipsis we add
.    \" later.
.    nr an-mark1 (\\n[an*topic-length] / 2 - 2)
.    nr an-mark2 (\\n[an*topic-length] / 2 + 2)
.    ds an-prefix \\*[an*topic-string]\"
.    ds an-suffix \\*[an*topic-string]\"
.    \" Use extremum operators to ensure that the first and last
.    \" characters of the topic remain intact (in cases of pathological
.    \" shortening).
.    substring an-prefix 0 (\\n[an-mark1] >? 1)
.    substring an-suffix (\\n[an-mark2] <? \\n[an*topic-length] - 1) -1
.    ds an*topic-string \\*[an-prefix]\\*[an-suffix]\"
.    ds an*topic-abbv \\*[an-prefix]\\*[an-ellipsis]\\*[an-suffix]\"
.    \" Remeasure the formatted topic; give up if we made no progress.
.    length an*topic-new-length \\*[an*topic-string]
.    ie (\\n[an*topic-new-length] >= \\n[an*topic-length]) \
.      break
.    ds an-pageref \\*[an*topic-abbv](\\*[an*section])\"
.    nr an-header-width \
       \\w'\\*[an-pageref]\\*[an-extra3]\\*[an-pageref]'
.  \}
.  ds an-pageref \\*[an-lic]\f[\\*[MF]]\\*[an*topic-abbv]\\*[an-ic]\
\f[R](\\*[an*section])\"
.  rr an*topic-length-prev
.  rr an-mark1
.  rr an-mark2
.  rm an-prefix
.  rm an-suffix
.  rm an*topic-string
.  rr an*topic-length
.  rr an-header-width
.  rm an-ellipsis
..
.
.\" Iterate through concatenation of arguments as a string.  If a bare
.\" backslash is found, make `an*string-contains-backslash` true.  Our
.\" caller should delete this register when done with it.
.de an*scan-string-for-backslash
.  nr an*string-contains-backslash 0
.  nr an*index 0
.  length an*max-index \\$*
.  while (\\n[an*index] < \\n[an*max-index]) \{\
.    ds an*char \\$*
.    substring an*char \\n[an*index] \\n[an*index]
.    ec @
.    \" Use a weird delimiter to reduce lexical colorizer confusion.
.    if _@*[an*char]_\\_ .nr an*string-contains-backslash 1
.    ec
.    if \\n[an*string-contains-backslash] .break
.    nr an*index +1
.  \}
.  rm an*char
.  rr an*max-index
.  rr an*index
..
.
.\" Abbreviate the `an-extra2` string (set by .TH) if it's too long for
.\" the footer.  The formatted width of the inner footer plus half that
.\" of the center footer must be less than half the title width or we
.\" must abbreviate.  By default, `an-extra2` is placed as the inner
.\" footer.  We call its (potential) abbreviation `an*ifoot` here and
.\" leave it defined for .BT use.  (`an*ofoot` is not treated the same
.\" way.  `an-footer` regenerates it on every page because the page
.\" number changes if present.)  Shorten the inner footer if necessary
.\" by trimming characters off the end, replacing them with an ellipsis.
.de an*abbreviate-inner-footer
.  ds an*ifoot \\*[an-extra2]\"
.  nr an*half-title-width (\\n[.lt] / 2u)
.  nr an*half-cfoot-width (\w'\\*[an-extra1]' / 2u)
.  nr an*half-footer-width \
     (\w'\\*[an*ifoot]' + \\n[an*half-cfoot-width])
.  if (\\n[an*half-footer-width] < \\n[an*half-title-width]) \{\
.    rr an*half-footer-width
.    rr an*half-cfoot-width
.    rr an*half-title-width
.    return
.  \}
.  an*scan-string-for-backslash \\*[an*ifoot]
.  if \\n[an*string-contains-backslash] \{\
.    an-warn not abbreviating fourth argument to 'TH' '\\*[an*ifoot]': \
contains unsupported escape sequence
.    rr an*string-contains-backslash
.    rr an*half-footer-width
.    rr an*half-cfoot-width
.    rr an*half-title-width
.    return
.  \}
.  ds an*saved-ifoot \\*[an*ifoot]
.  ds an*ellipsis \|.\|.\|.\|\"
.  \" Remeasure with ellipsis added to inner footer so that henceforth,
.  \" the measured width strictly decreases.
.  nr an*half-footer-width \
     (\w'\\*[an*ifoot]\\*[an*ellipsis]' + \\n[an*half-cfoot-width])
.  nr an*end-index (-2)
.  while (\\n[an*half-footer-width] >= \\n[an*half-title-width]) \{\
.    ds an*ifoot \\*[an*saved-ifoot]
.    substring an*ifoot 0 \\n[an*end-index]
.    \" Measure the string again and give up if we made no progress.
.    nr an*new-half-footer-width \
       (\w'\\*[an*ifoot]\\*[an*ellipsis]' + \\n[an*half-cfoot-width])
.    ie (\\n[an*new-half-footer-width] >= \\n[an*half-footer-width]) \
.      break
.    nr an*half-footer-width \\n[an*new-half-footer-width]
.    nr an*end-index -1
.  \}
.  ds an*ifoot \\*[an*ifoot]\\*[an*ellipsis]\"
.  rr an*end-index
.  rr an*new-half-footer-width
.  rm an*ellipsis
.  rm an*saved-ifoot
.  rr an*string-contains-backslash
.  rr an*half-footer-width
.  rr an*half-cfoot-width
.  rr an*half-title-width
..
.
.\" Prepare the header for a page of the document.
.de1 an-header
.  if \\n[an-suppress-header-and-footer] .return
.  ev an*env-header-and-footer
.  PT
.  ev
.  ns
..
.
.\" Schedule a page break when the next output line is written (not
.\" called if continuously rendering).
.de1 an-break-body-text
'  bp
..
.
.\" Prepare the footer for a page of the document.
.de1 an-footer
.  if \\n[an-suppress-header-and-footer] .return
.  ev an*env-header-and-footer
.  ie \\n[cR] \
.    ds an*ofoot "\\*[an-pageref]\"
.  el \{\
.    ds an*ofoot \\n[%]\"
.    if r X \{\
.      if (\\n[%] > \\n[X]) \{\
.        nr an-page-letter (\\n[%] - \\n[X])
.        ds an*ofoot \\n[X]\\n[an-page-letter]\"
.      \}
.    \}
.  \}
.  BT
.  rm an*ofoot
.  ev
..
.
.\" Output the tag of a tagged paragraph, or of an indented paragraph
.\" (IP) that has a tag.  Whether we break depends on the tag width.
.de an-write-paragraph-tag
.  br
.  di
.  ad \\*[AD]
.  nr an-is-in-diversion 0
.  ll
.  \" We must emit the diversion in a separate environment to ensure
.  \" that a possible margin character is printed correctly.
.  ev an-env-paragraph-tag
.  evc 0
.  mc
.  nf
.  in \\n[an-margin]u
.  \" Prevent page break between the tag and the rest of the paragraph.
.  ne (2v + 1u)
.  \" Does the tag fit within the paragraph indentation?
.  nr an-tag-fits \
     (\\n[dl] + \\n[TS] <= \\n[an-prevailing-indent])
.  if \\n[an-tag-fits] .DEVTAG-COL 1
.  an-div
.  if \\n[an-tag-fits] .sp -1v
.  ev
.  in (\\n[an-margin]u + \\n[an-prevailing-indent]u)
.  if \\n[an-tag-fits] .DEVTAG-COL 2
.  rr an-tag-fits
..
.
.\" Handle macros that may take an "argument" on the next input line
.\" producing written or drawn output: .SH, .SS, .B, .I, .SM, .SB--and
.\" .TP, which does so mandatorily.
.de1 an-input-trap
.  if \\n[an-devtag-needs-end-of-heading] .DEVTAG-EO-H
.  nr an-devtag-needs-end-of-heading 0
.  if \\n[an-devtag-needs-second-column] .DEVTAG-COL 2
.  nr an-devtag-needs-second-column 0
.  ft R
.  ps \\n[PS]u
.  vs \\n[VS]u
.  if \\n[an-need-break] \{\
.    br
.    nr an-need-break 0
.  \}
.  if \\n[an-need-no-space-mode] \{\
.    ns
.    nr an-need-no-space-mode 0
.  \}
.  if \\n[an-is-in-diversion] .an-write-paragraph-tag
..
.
.\" Break a paragraph.  Restore defaults, except for indentation.
.de an-break-paragraph
.  ft R
.  ps \\n[PS]u
.  vs \\n[VS]u
.  sp \\n[PD]u
.  ns
..
.
.\" Set arguments (or next input line producing written or drawn output
.\" if none) as a section heading.
.de1 SH
.  fam \\*[an*body-family]
.  an-break-paragraph
.  an-reset-margin-and-inset-level
.  fi
.  in \\n[BP]u
.  ti 0
.  nr an-devtag-needs-end-of-heading 1
.  DEVTAG-SH 1
.  it 1 an-input-trap
.  nr an-need-no-space-mode 1
.  nr an-need-break 1
.  ps \\n[PS-SH]u
.  ne (2v + 1u)
.  ft \\*[HF]
.  if \\n[an-remap-I-style-in-headings] .ftr I \\*[an-heading-family]BI
.  if \\n[.$] \{\
.    ds an-section-heading \\$*\"
.    if \\n[CS] .stringup an-section-heading
.    an*bookmark 3 "\\*[an-section-heading]"
\&\\*[an-section-heading]
.  \}
.  if \\n[an-remap-I-style-in-headings] .ftr I I
..
.
.\" Set arguments (or next input line producing written or drawn output
.\" if none) as a subsection heading.
.de1 SS
.  fam \\*[an*body-family]
.  an-break-paragraph
.  an-reset-margin-and-inset-level
.  fi
.  in \\n[BP]u
.  ti \\n[SN]u
.  nr an-devtag-needs-end-of-heading 1
.  DEVTAG-SH 2
.  it 1 an-input-trap
.  nr an-need-no-space-mode 1
.  nr an-need-break 1
.  ps \\n[PS-SS]u
.  ne (2v + 1u)
.  ft \\*[HF]
.  if \\n[an-remap-I-style-in-headings] .ftr I \\*[an-heading-family]BI
.  if \\n[.$] \{\
.    ds an*subsection-heading \\$*\"
.    an*bookmark 4 "\\*[an*subsection-heading]"
.    nop \&\\$*
.  \}
.  if \\n[an-remap-I-style-in-headings] .ftr I I
..
.
.\" Set arguments (or next input line producing written or drawn output
.\" if none) in bold style.
.de1 B
.  it 1 an-input-trap
.  ft B
.  if \\n[.$] \&\\$*
..
.
.\" Set arguments (or next input line producing written or drawn output
.\" if none) in italic style.
.de1 I
.  it 1 an-input-trap
.  ft I
.  if \\n[.$] \,\\$*\/
..
.
.\" Set arguments (or next input line producing written or drawn output
.\" if none) at smaller type size.
.de1 SM
.  it 1 an-input-trap
.  ps -1
.  if \\n[.$] \&\\$*
..
.
.\" Deprecated: Set arguments (or next input line producing written or
.\" drawn output if none) in bold style at smaller type size.
.\"
.\" This is a SunOS 4.0 extension.
.\"
.\" Instead of
.\"   .SB whatever
.\" say
.\"   .SM
.\"   .B whatever
.\" or
.\"   .B
.\"   .SM whatever
.\" to portably get an identical effect.
.\"
.\" .SB [text]
.de1 SB
.  nop \\*[an-deprecation-warn]\\
.  it 1 an-input-trap
.  ps -1
.  ft B
.  if \\n[.$] \&\\$*
..
.
.\" Set an ordinary paragraph.
.de1 P
.  an-break-paragraph
.  in \\n[an-margin]u
.  nr an-prevailing-indent \\n[IN]
..
.
.\" Accommodate ms(7) paragraphing refugees.
.als LP P
.als PP P
.
.\" Set a tagged paragraph.  The tag must be on the next input line
.\" producing written or drawn output.
.\" .TP [indent]
.de1 TP
.  an-break-paragraph
.  if \\n[.$] .nr an-prevailing-indent (n;\\$1)
.  itc 1 an-input-trap
.  in 0
.  if !\\n[an-is-in-diversion] \{\
.    ll -\\n[an-margin]u
.    di an-div
.    na
.  \}
.  nr an-is-in-diversion 1
..
.
.\" Set an indented paragraph.
.\" .IP [marker[ indentation-amount]]
.de1 IP
.  an-break-paragraph
.  ie !\\n[.$] \{\
.    ne (1v + 1u)
.    in (\\n[an-margin]u + \\n[an-prevailing-indent]u)
.  \}
.  el \{\
.    ie (\\n[.$] > 1) .TP "\\$2"
.    el               .TP
.    nop \&\\$1
.  \}
..
.
.\" Set a paragraph with a hanging indentation.
.\" .HP [indent]
.de1 HP
.  if !\\n[mS] \\*[an-deprecation-warn]\\
.  an-break-paragraph
.  ne (1v + 1u)
.  if \\n[.$] .nr an-prevailing-indent (n;\\$1)
.  in (\\n[an-margin]u + \\n[an-prevailing-indent]u)
.  ti \\n[an-margin]u
.  DEVTAG-COL 1
.  nr an-devtag-needs-second-column 1
..
.
.\" === Define alternating font macros. ===
.\"
.\" Implementation notes:
.\"
.\" We always emit a dummy character \& before the first argument.  This
.\" is necessary only when the calling man page is in compatibility
.\" mode; it works around the surprising AT&T semantics of \f escapes at
.\" the beginning of an input line.  See "Implementation differences" in
.\" groff_diff(7) or the groff Texinfo manual.
.\"
.\" The italic correction escapes can be visually confusing.  We apply
.\" the following rules, always on the same input line.
.\"   (1) Before any italic argument, emit a left italic correction \,
.\"       before switching to the italic style.
.\"   (2) After any italic argument, emit an italic correction \/
.\"       before switching to another style.
.\" It is true that these macros cannot know what style is used in the
.\" input stream before or after they are called.  We can make
.\" assumptions based on pragmatics.  In most cases, the caller will not
.\" precede a call to one of these macros with \c, or add it to the
.\" final argument given to one of these calls; when \c is absent, what
.\" is adjacent must be a word space or output line boundary, so italic
.\" corrections don't matter.  If \c _is_ used by the caller, we can
.\" assume that the adjacent glyphs before an IB or IR call, or the
.\" following ones after a BI or RI call, will not be italic (and thus
.\" will benefit from the italic correction we provide); otherwise the
.\" caller would simply have added the relevant characters to the
.\" arguments of the macro call.
.\"
.
.\" Set each argument in bold and italics, alternately.
.de1 BI
.  if (\\n[.$] < 2) \
.    an-style-warn .\\$0 expects at least 2 arguments, got \\n[.$]
.  if \\n[.$] \{\
.    ds an-result \&\"
.    while (\\n[.$] >= 2) \{\
.      as an-result \f[B]\\$1\,\f[I]\\$2\/\"
.      shift 2
.    \}
.    if \\n[.$] .as an-result \f[B]\\$1\"
.    nop \\*[an-result]
.    rm an-result
.    ft R
.  \}
..
.
.\" Set each argument in bold and roman, alternately.
.de1 BR
.  if (\\n[.$] < 2) \
.    an-style-warn .\\$0 expects at least 2 arguments, got \\n[.$]
.  if \\n[.$] \{\
.    ds an-result \&\"
.    while (\\n[.$] >= 2) \{\
.      as an-result \f[B]\\$1\f[R]\\$2\"
.      shift 2
.    \}
.    if \\n[.$] .as an-result \f[B]\\$1\"
.    nop \\*[an-result]
.    rm an-result
.    ft R
.  \}
..
.
.\" Set each argument in italics and bold, alternately.
.de1 IB
.  if (\\n[.$] < 2) \
.    an-style-warn .\\$0 expects at least 2 arguments, got \\n[.$]
.  if \\n[.$] \{\
.    ds an-result \&\"
.    while (\\n[.$] >= 2) \{\
.      as an-result \,\f[I]\\$1\/\f[B]\\$2\"
.      shift 2
.    \}
.    if \\n[.$] .as an-result \,\f[I]\\$1\/\"
.    nop \\*[an-result]
.    rm an-result
.    ft R
.  \}
..
.
.\" Set each argument in italics and roman, alternately.
.de1 IR
.  if (\\n[.$] < 2) \
.    an-style-warn .\\$0 expects at least 2 arguments, got \\n[.$]
.  if \\n[.$] \{\
.    ds an-result \&\"
.    while (\\n[.$] >= 2) \{\
.      as an-result \,\f[I]\\$1\/\f[R]\\$2\"
.      shift 2
.    \}
.    if \\n[.$] .as an-result \,\f[I]\\$1\/\"
.    nop \\*[an-result]
.    rm an-result
.    ft R
.  \}
..
.
.\" Set each argument in roman and bold, alternately.
.de1 RB
.  if (\\n[.$] < 2) \
.    an-style-warn .\\$0 expects at least 2 arguments, got \\n[.$]
.  if \\n[.$] \{\
.    ds an-result \&\"
.    while (\\n[.$] >= 2) \{\
.      as an-result \f[R]\\$1\f[B]\\$2\"
.      shift 2
.    \}
.    if \\n[.$] .as an-result \f[R]\\$1\"
.    nop \\*[an-result]
.    rm an-result
.    ft R
.  \}
..
.
.\" Set each argument in roman and italics, alternately.
.de1 RI
.  if (\\n[.$] < 2) \
.    an-style-warn .\\$0 expects at least 2 arguments, got \\n[.$]
.  if \\n[.$] \{\
.    ds an-result \&\"
.    while (\\n[.$] >= 2) \{\
.      as an-result \f[R]\\$1\,\f[I]\\$2\/\"
.      shift 2
.    \}
.    if \\n[.$] .as an-result \f[R]\\$1\"
.    nop \\*[an-result]
.    rm an-result
.    ft R
.  \}
..
.
.\" Start a relative inset level (by the amount given in the argument).
.\" .RS [inset-amount]
.de1 RS
.  nr an-saved-margin\\n[an-inset-level] \\n[an-margin]
.  nr an-saved-prevailing-indent\\n[an-inset-level] \
     \\n[an-prevailing-indent]
.  ie \\n[.$] .nr an-margin +(n;\\$1)
.  el         .nr an-margin +\\n[an-prevailing-indent]
.  in \\n[an-margin]u
.  nr an-prevailing-indent \\n[IN]
.  nr an-inset-level +1
..
.
.\" End relative inset level, backing up by one level (or to the level
.\" given by the argument).
.\" .RE [inset-level]
.de1 RE
.  ie \\n[.$] .nr an-RE-requested-level \\$1
.  el         .nr an-RE-requested-level (\\n[an-inset-level] - 1)
.  ie \\n[.$] \{\
.    if (\\n[an-RE-requested-level] = \\n[an-inset-level]) \
.      ds an-RE-problem already at level \\n[an-inset-level]\"
.    if (\\n[an-RE-requested-level] > \\n[an-inset-level]) \
.      ds an-RE-problem too large\"
.    if (\\n[an-RE-requested-level] < 1) \
.      ds an-RE-problem too small\"
.    if d an-RE-problem \
.      an-style-warn argument """\\$1""" to .\\$0 \\*[an-RE-problem]
.    rm an-RE-problem
.  \}
.  el .if !(\\n[an-RE-requested-level]) .an-style-warn unbalanced .\\$0
.  rr an-RE-requested-level
.  ie \\n[.$] .nr an-inset-level ((;\\$1) <? \\n[an-inset-level])
.  el         .nr an-inset-level -1
.  nr an-inset-level (1 >? \\n[an-inset-level])
.  nr an-margin \\n[an-saved-margin\\n[an-inset-level]]
.  nr an-prevailing-indent \
     \\n[an-saved-prevailing-indent\\n[an-inset-level]]
.  in \\n[an-margin]u
..
.
.\" Deprecated: Style an option with an argument (mandatory if
.\" specified) for a command synopsis.
.\"
.\" This is a Documenter's Workbench troff extension.  It is not
.\" flexible enough to handle GNU-style options like
.\" `--input=file-name`.  Use font alternation macros instead.
.\"
.\" .OP flag [option-parameter]
.de1 OP
.  nop \\*[an-deprecation-warn]\\
.  if ((\\n[.$] < 1) : (\\n[.$] > 2)) \
.    an-style-warn .\\$0 expects 1 or 2 arguments, got \\n[.$]
.  ie (\\n[.$] > 1) \
.    RI [\\f[B]\\$1\f[] \~\\$2 ]
.  el \
.    RB [ \\$1 ]
..
.
.\" Begin an example (typically of source code or shell input).
.de1 EX
.  br
.  if \\n[an*is-in-example] \{\
.    an-style-warn ignoring .\\$0 while already in example
.    return
.  \}
.  ds an*saved-family \\n[.fam]
.  nr an*saved-font \\n[.f]
.  nr an*saved-paragraph-distance \\n[PD]
.  nr PD 1v
.  nf
.  \" If using the DVI output device, we have no constant-width fonts of
.  \" bold weight and, relatedly, no constant-width family (because that
.  \" requires all four styles).  Remap the bold styles to normal ones.
.  ie '\*[.T]'dvi' \{\
.    ftr R CW
.    ftr B CW
.    ftr I CWI
.    ftr BI CWI
.  \}
.  el .fam \\*[an*example-family]
.  ft R
.  nr an*is-in-example 1
..
.
.\" End example.
.de EE
.  br
.  if !\\n[an*is-in-example] \{\
.    an-style-warn ignoring .\\$0 while not in example
.    return
.  \}
.  \" Undo the remappings from `EX`.
.  ie '\*[.T]'dvi' \{\
.    ftr R
.    ftr B
.    ftr I
.    ftr BI
.  \}
.  fam \\*[an*saved-family]
.  ft \\n[an*saved-font]
.  nr PD \\n[an*saved-paragraph-distance]
.  fi
.  rr an*saved-paragraph-distance
.  rr an*saved-font
.  rm an*saved-family
.  nr an*is-in-example 0
..
.
.\" Store the argument and begin a diversion for link text.
.de an*begin-hyperlink
.  ds an*hyperlink \\$1\"
.  \" We want the diversion to format as if it has an indentation of
.  \" zero (that comes for free when we switch environments), and we
.  \" want the line length reduced by the amount of indentation that
.  \" obtains when we output it.
.  nr an*saved-line-length \\n[.l]
.  nr an*saved-indentation \\n[.i]
.  \" We can only hyperlink if we're not in a diversion.
.  \" XXX: There's no fundamental reason for that, just a simple matter
.  \" of macro programming.
.  nr an*is-in-link-text-diversion 0
.  if '\\n(.z'' .nr an*is-in-link-text-diversion 1
.  if (\\n[an*is-in-link-text-diversion] & \\n[an*do-hyperlink]) \{\
.    \" Start diversion in a new environment.
.    ev an*link-text-env
.    di an*link-text-div
.    ll (\\n[an*saved-line-length]u - \\n[an*saved-indentation]u)
.  \}
.  rr an*saved-indentation
.  rr an*saved-line-length
..
.
.\" Emit hyperlinked text with optional trailing text.
.\"
.\" The caller should set the `an*prefix` string if the hyperlink should
.\" be prefixed with a scheme; for example, email addresses get
.\" "mailto:", but this need not be visible when rendering an email
.\" address on a device incapable of hyperlinking.
.de an*end-hyperlink
.  ie (\\n[an*is-in-link-text-diversion] & \\n[an*do-hyperlink]) \{\
.    br
.    di
.    ev
.
.    \" Was any link text present?
.    ie \\n[dn] \{\
.      if \\n[an*is-output-html] \
.        nop \X^html:<a href="\\*[an*prefix]\\*[an*hyperlink]">^\c
.      if \\n[an*is-output-terminal] \
.        nop \X^tty: link \\*[an*prefix]\\*[an*hyperlink]^\c
.      \" Strip off the final newline of the diversion and emit it.
.      chop an*link-text-div
.      an*link-text-div
\c\" XXX: If we .nop this, HTML output is corrupted (Savannah #63470).
.      if \\n[an*is-output-html] \
.        nop \X^html:</a>^\c
.      if \\n[an*is-output-terminal] \
.        nop \X^tty: link^\c
.    \}
.    \" If there was no link text, format URI as its own link text.  We
.    \" don't add angle brackets here.
.    el \{\
.      if \\n[an*is-output-html] \
.        nop \X^html:<a href="\\*[an*prefix]\\*[an*hyperlink]">\
\\*[an*hyperlink]</a>^\c
.      if \\n[an*is-output-terminal] \
.        nop \X^tty: link \\*[an*prefix]\\*[an*hyperlink]^\
\\*[an*hyperlink]\X^tty: link^\c
.    \}
.    nop \&\\$1\"
.  \}
.  \" If not hyperlinking, format URI in angle brackets.  There was no
.  \" diversion, so the link text has already been formatted normally.
.  el \{\
.    nh
.    nop \\[la]\\*[an*hyperlink]\\[ra]\\$1
.    hy \\n[an*hyphenation-mode]
.  \}
.
.  rr an*is-in-link-text-diversion
..
.
.\" Begin email hyperlink.  Input until the next `ME` call is stored in
.\" a diversion; it becomes the link text for the hyperlinked address.
.\" .MT nobody@example.com
.de1 MT
.  if !(\\n[.$] = 1) \
.    an-style-warn .\\$0 expects 1 argument, got \\n[.$]
.  ds an*prefix mailto:
.  an*begin-hyperlink \\$1
..
.
.\" End email hyperlink.  The optional argument supplies trailing
.\" punctuation (or, rarely, other text) after link text.
.\" .ME [trailing-text]
.de1 ME
.  an*end-hyperlink \\$1
.  rm an*prefix
..
.
.\" Begin web hyperlink.  Input until the next `UE` call is stored in
.\" a diversion; it becomes the link text for the hyperlinked address.
.\" .UR nobody@example.com
.de1 UR
.  if !(\\n[.$] = 1) \
.    an-style-warn .\\$0 expects 1 argument, got \\n[.$]
.  ds an*prefix \" empty
.  an*begin-hyperlink \\$1
..
.
.\" End web hyperlink.  The optional argument supplies trailing
.\" punctuation (or, rarely, other text) after link text.
.\" .UE [trailing-text]
.de1 UE
.  an*end-hyperlink \\$1
.  rm an*prefix
..
.
.\" There is no standardized format for man page URLs, but the default
.\" is expected to work (or be harmlessly ignored) everywhere except
.\" macOS.  Override in man.local if desired.
.nr an*MR-URL-format 1
.
.\" Set a man page cross reference.
.\" .MR page-topic page-section [trailing-text]
.de1 MR
.  if ((\\n[.$] < 2) : (\\n[.$] > 4)) \
.    an-style-warn .\\$0 expects 2 to 4 arguments, got \\n[.$]
.  ie \\n[an*is-output-pdf] \{\
.    nr mj \n[.hy]
.    nh
.    ds an*title \\\\$4
.    if '\\\\*[an*title]'' .ds an*title \\\\$1
.    ie \\n(.$=1 \
.      I \\$1
.    el \{\
.      an*cln an*page-ref-nm \\*[an*title]_\\$2
.      ie d pdf:look(\\*[an*page-ref-nm]) .pdfhref L -D \\*[an*page-ref-nm] -A "\\$3" -- \fI\\$1\fP(\\$2)
.      el .IR \\$1 (\\$2)\\$3
.    \}
.    hy \\n(mJ
.  \}
.  el \{\
.    ds an*url man:\\$1(\\$2)\" used everywhere but macOS
.    if (\\n[an*MR-URL-format] = 2) \
.      ds an*url x-man-page://\\$2/\\$1\" macOS/Mac OS X since 10.3
.    if (\\n[an*MR-URL-format] = 3) \
.      ds an*url man:\\$1.\\$2\" Bwana (Mac OS X)
.    if (\\n[an*MR-URL-format] = 4) \
.      ds an*url x-man-doc://\\$2/\\$1\" ManOpen (Mac OS X pre-2005)
.    nh
.    if \\n[an*do-hyperlink] \{\
.      if \\n[an*is-output-html] \
.        nop \X^html:<a href="\\*[an*url]">^\c
.      if \\n[an*is-output-terminal] \
.        nop \X^tty: link \\*[an*url]^\c
.    \}
.        nop \&\\*[an-lic]\f[\\*[MF]]\\$1\\*[an-ic]\f[R](\\$2)\c
.    if \\n[an*do-hyperlink] \{\
.      if \\n[an*is-output-html] \
.        nop \X^html:</a>^\c
.      if \\n[an*is-output-terminal] \
.        nop \X^tty: link^\c
.    \}
.    nop \&\\$3
.  \}
.  hy \\n[an*hyphenation-mode]
..
.
.\" tbl(1) table support
.
.\" Start table.
.de1 TS
.  \" If continuous rendering, tell tbl not to use keeps.
.  ie \\n[cR] .nr 3usekeeps 0
.  el         .nr 3usekeeps 1
.  if \\n[an*is-output-html] \{\
.    nr an-TS-ll \\n[.l]
.    ll 1000n
.  \}
.  HTML-IMAGE
..
.
.\" Start another table in the same region (ignored).
.de1 T&
..
.
.\" End table.
.de1 TE
.  HTML-IMAGE-END
.  if \\n[an*is-output-html] .ll \\n[an-TS-ll]u
.  if !r TW .if !\\n[an-was-tbl-failure-reported] \{\
.    ds an-msg tbl preprocessor failed, or it or soelim was not run;\"
.    as an-msg " table(s) likely not rendered\"
.    as an-msg " (TE macro called with TW register undefined)\"
.    an-warn \\*[an-msg]
.    rm an-msg
.    nr an-was-tbl-failure-reported 1
.  \}
..
.
.\" eqn(1) equation support
.
.\" Start equation.
.de1 EQ
.  if \\n[an*is-output-html] \{\
.    nr an-EQ-ll \\n[.l]
.    ll 1000n
.  \}
.  HTML-IMAGE
..
.
.\" End equation.
.de1 EN
.  HTML-IMAGE-END
.  if \\n[an*is-output-html] .ll \\n[an-EQ-ll]u
..
.
.
.\" === Define strings. ===
.\"
.\" These strings must work in compatibility mode also.
.
.ds S \s'\\n(PSu'\"
.ie c\[rg] .ds R \(rg\"
.el        .ds R (Reg.)\"
.ie c\[tm] .ds Tm \(tm\"
.el        .ds Tm (TM)\"
.ie c\[lq] .ds lq \(lq\"
.el        .ds lq ""\"
.ie c\[rq] .ds rq \(rq\"
.el        .ds rq ""\"
.
.\" === Define/remap characters. ===
.
.\" For UTF-8, map the minus sign to the hyphen-minus to facilitate
.\" copy and paste of code examples, file names, and URLs embedding it.
.if '\*[.T]'utf8' \
.  char \- \N'45'
.
.\" === Initialize. ===
.
.mso devtag.tmac
.nr an-devtag-needs-end-of-heading 0
.nr an-devtag-needs-second-column 0
.
.\" Track whether the strings that set header and footer text need to be
.\" reconfigured.  This happens when batch-rendering and starting a new
.\" page.
.nr an*need-titles-reset 0
.
.nr an*is-output-html 0
.if '\*[.T]'html' .nr an*is-output-html 1
.nr an*is-output-pdf 0
.if '\*[.T]'pdf' .nr an*is-output-pdf 1
.nr an*is-output-terminal 0
.if '\*(.T'ascii'  .nr an*is-output-terminal 1
.if '\*(.T'cp1047' .nr an*is-output-terminal 1
.if '\*(.T'latin1' .nr an*is-output-terminal 1
.if '\*(.T'utf8'   .nr an*is-output-terminal 1
.
.nr an*can-hyperlink 0
.if (  \n[an*is-output-html] \
     : \n[an*is-output-pdf] \
     : \n[an*is-output-terminal]) \
.  nr an*can-hyperlink 1
.
.ds an*body-family \n[.fam]
.ds an*example-family C \" Courier
.
.\" Map monospaced fonts to standard styles for groff's nroff devices.
.if n \{\
.  ftr CR R
.  ftr CI I
.  ftr CB B
.  ftr CBI BI
.\}
.
.\" undocumented register; unset to test an-ext.tmac extension macros
.if !r mG \
.  nr mG 1
.
.\" Load man macro extensions.
.mso an-ext.tmac
.
.\" Load site modifications.
.msoquiet man.local
.
.\" Set each rendering parameter only if its -[dr] option or man.local
.\" did not.
.
.if \n[an*is-output-pdf] \{\
.  \" FIXME: The following registers are documented only in pdf.tmac.
.  if !r PDFOUTLINE.FOLDLEVEL .nr PDFOUTLINE.FOLDLEVEL 1
.  if !r PDFHREF.VIEW.LEADING .nr PDFHREF.VIEW.LEADING 10p
.\}
.
.\" base paragraph indentation
.if !r BP \
.  nr BP 5n
.
.\" continuous rendering (one long page)
.if !r cR \{\
.  ie n .nr cR 1
.  el   .nr cR 0
.\}
.
.\" consecutive page numbering across multiple documents
.\"
.\" We must use consecutive page numbers when using PostScript to
.\" generate HTML images; we must not reset the page number at the
.\" beginning of each document (the 'ps4html' register is automatically
.\" added to the command line by the pre-HTML preprocessor).
.ie !r C \
.  nr C 0
.el \
.  if !\n[C] \
.    if \n[an*is-output-html] \{\
.       tm \*[an]: consecutive page numbering required for HTML output
.       nr C 1
.    \}
.if \n[an*is-output-html] \
.  nr C 1
.if r ps4html \
.  nr C 1
.
.\" diagnostics desired for man page style problems
.if !r CHECKSTYLE \
.  nr CHECKSTYLE 0
.
.\" full capitalization of section headings
.if !r CS \
.  nr CS 0
.
.\" full capitalization of page topic
.if !r CT \
.  nr CT 0
.
.\" double-sided layout
.ie !r D \
.  nr D 0
.el \
.  if \n[D] \
.    if \n[an*is-output-html] \{\
.       tm \*[an]: ignoring double-sided layout in HTML output
.       nr D 0
.    \}
.
.\" footer distance
.\"
.\" Unlike most of these parameters, we do not set a default for FT; the
.\" TH macro places page location traps only if not continuously
.\" rendering.
.if r FT \{\
.  \" Validate it.  Continuous rendering ignores FT.  Measuring a footer
.  \" distance from the page top isn't done.  A footer distance of over
.  \" half the page length is unlikely.  A footer distance of less than
.  \" one line height is too.
.  ie \n[cR] \
.    ds an-msg footer distance when continuously rendering\"
.  el \{\
.    nr an*tmp 1v
.    ds an*help " (1v=\n[an*tmp]u)\"
.    ie (\n[FT] : (\n[FT] = 0)) \
.      ds an-msg non-negative footer distance: \n[FT]u\*[an*help]\"
.    el \{\
.      ie (-(\n[FT]) > (\n[.p] / 2)) \{\
.        ds an-msg implausibly large footer distance:\"
.        as an-msg " \n[FT]u\*[an*help]\"
.      \}
.      el \
.        if (-(\n[FT]) < 1v) \{\
.          ds an-msg implausibly small footer distance:\"
.          as an-msg " \n[FT]u\*[an*help]\"
.        \}
.    rm an*help
.    rr an*tmp
.    \}
.  \}
.  if d an-msg \{\
.    tm \*[an]: ignoring \*[an-msg]
.    rr FT
.    rm an-msg
.  \}
.\}
.
.\" hyphenation enablement
.if !r HY \
.  nr HY 1
.
.\" standard indentation
.if !r IN \{\
.  \" We select an integer indentation value in nroff mode because this
.  \" value is used additively for multiple purposes; rounding of
.  \" accumulating fractions would produce inconsistent results.
.  ie t .nr IN 7.2n
.  el   .nr IN 7n
.\}
.
.\" line length
.if !r LL \{\
.  \" If in troff mode, respect device default.
.  ie t .nr LL \n[.l]
.  \" Otherwise, override nroff mode default of 65n.
.  el   .nr LL 78n
.\}
.
.\" title (header, footer) length
.if !r LT \
.  nr LT \n[LL]u
.
.\" starting page number
.\"
.\" Unlike most of these parameters, we do not set a default for P;
.\" troff supplies a default starting page number (1).  When rendering
.\" for the HTML output device, page numbers are concealed and used for
.\" internal purposes like image embedding.  Page numbers are not
.\" rendered at all in continuous rendering mode.
.if r P \{\
.  if \n[an*is-output-html] \
.    if !(\n[P] = 1) \
.      ds an-msg in HTML output\"
.  if \n[cR] \
.    ds an-msg when continuously rendering
.\}
.if d an-msg \{\
.  tm \*[an]: ignoring starting page number \*[an-msg]
.  rr P
.  rm an-msg
.\}
.
.\" Setting the page number turns out to be tricky when batch rendering
.\" and switching macro packages.  We must use different techniques
.\" depending on whether the transition to the first output page has
.\" happened yet.  If it has not, `nl` will be `-1` and we use `pn`.  If
.\" it has, we set `%`.  Technically this is fragile since in theory a
.\" page could assign a negative value to `nl`.  We might then be
.\" justified in saying they've broken the macro package and they get to
.\" keep both pieces.  But if not, consider using a nonce register,
.\" initially set but then permanently cleared adjacent to this logic,
.\" and whose state is shared with mdoc (and andoc.tmac, if necessary).
.\"
.\" Also, we can't use the `P` register with grohtml at all.
.ie r ps4html \{\
.  if r P \{\
.     tm \*[an]: ignoring starting page number in HTML output
.     rr P
.  \}
.\}
.el \{\
.  if r P \{\
.    ie (\n[nl] = -1) .pn 0\n[P]
.    el               .nr % 0\n[P]
.  \}
.\}
.
.\" page offset
.if r PO \
.  po \n[PO]u
.
.\" type size
.if !r S \{\
.  nr S 10
.  if '\*[.T]'X75-12' \
.    nr S 12
.  if '\*[.T]'X100-12' \
.    nr S 12
.\}
.
.\" required paragraph tag separation
.if !r TS \
.  nr TS 2n
.
.\" subsection indentation
.if !r SN \
.  nr SN 3n
.
.\" URI enablement desired
.if !r U \
.  nr U 1
.
.nr an*do-hyperlink 0
.if (\n[U] & \n[an*can-hyperlink]) .nr an*do-hyperlink 1
.
.\" page number after which to apply letter suffixes
.\"
.\" Unlike most of these parameters, we do not set a default for X; only
.\" the macro an-footer uses it.  Page numbers are not rendered at all
.\" in continuous rendering mode.
.if r X \{\
.  af an-page-letter a
.  if \n[an*is-output-html] \
.    ds an-msg in HTML output\"
.  if \n[cR] \
.    ds an-msg when continuously rendering
.\}
.if d an-msg \{\
.  tm \*[an]: ignoring page number suffix \*[an-msg]
.  rr X
.  rm an-msg
.\}
.
.\" adjustment mode
.if !d AD \
.  ds AD b\"
.
.\" (sub)section heading font
.if !d HF \
.  ds HF B\"
.
.\" If HF is a bold style, use bold italics for italics in headings.
.ds an-heading-style \*[HF]\"
.substring an-heading-style -1 -1
.ds an-heading-family \" empty
.length an-HF-length \*[HF]
.if (\n[an-HF-length] > 1) \{\
.  as an-heading-family \*[HF]\"
.  substring an-heading-family 0 -2
.\}
.if '\*[an-heading-style]'B' \
.  if F \*[an-heading-family]BI \
.    nr an-remap-I-style-in-headings 1
.rr an-HF-length
.rm an-heading-style
.
.\" man page topic font
.if !d MF \
.  ds MF I\"
.
.\" Define italic correction strings.  Initially, they are empty.  If MF
.\" is an oblique style, append the corrections.
.ds an-lic \" left italic correction
.ds an-ic \" italic correction
.ds an*topic-style \*[MF]\"
.substring an*topic-style -1 -1
.if '\*[an*topic-style]'I' \{\
.  as an-lic \,\"
.  as an-ic \/\"
.\}
.rm an*topic-style
.
.if \n[cR] \
.  an-set-up-continuous-rendering
.
.\" If rendering HTML, suppress headers and footers.
.nr an-suppress-header-and-footer 0
.if \n[an*is-output-html] .nr an-suppress-header-and-footer 1
.if r ps4html             .nr an-suppress-header-and-footer 1
.
.cp \n[*groff_an_tmac_C]
.do rr *groff_an_tmac_C
.
.\" Local Variables:
.\" mode: nroff
.\" fill-column: 72
.\" End:
.\" vim: set filetype=groff textwidth=72:

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Deri, Branden,

On 2023-08-14 18:06, Deri wrote:
[...]

> Line missing in the bespoke an.tmac I provided, new version attached.

Thanks; will try.

> I know 
> Alex wants to run against a stock version of groff, with minimal 
> customisation, and, once my branch is merged, there will be further pruning, 
> but unless you add to Branden's wish list to include an ability to control the 
> hierarchy of the bookmark panel, you will need a customised an.tmac. The 
> reason is because the stock an.tmac has a hard coded hierarchy where the .TH 
> line is given level 1 but as you want to have separate sections these need to 
> be level one and everything else is moved up a level. Of course this just 
> means making the starting level configurable on the command line, i.e. 
> -r startbkmk=2 or some such.

Deri's wish is my wish :)

> Another change which would need to be accepted is 
> to allow a fourth parameter to .MR which is the destination name. Normally the 
> name of the destination is derived from the first two parameters concatenated 
> with "_", but if the name part of the .MR call to the man page includes non-
> ascii characters (such as ".MR my\-lovely\-page 7 ,") then it needs to provide 
> a "clean" destination name.

Is this really needed?  Can't gropdf just translate them internally?  Say, do
unconditionally the equivalent of `| tr - _ |` or something like that.

[...]

> 
> Fonts
> 
> There are 2 reasons I included fonts in the build environment:-
> 
> A) The man pages which define the various iso-8859 pages contain many glyphs 
> which are not defined in the standard groff fonts, so I used the Tinos font 
> from google which improves the coverage. If you want to get rid of the fonts, 
> and rely on just the fonts in groff, you can change line 4 of anmark.tmac to:-
> 
> .special S U-TR
> 
> Which is an improvement on the standard fonts, and should be available as 
> standard if the URW fonts were found when groff was built. You will see 
> differences in iso-8859-7 and iso-8859-8 for example.

I'll try.  I wouldn't want to make those ISO-8859 pages useless, though.

> 
> B) If you build the LinuxManBook using the 1.23.0+ flavour (with the newer 
> gropdf that produces a substantially smaller pdf) it requires a slightly 
> different font format so needs the embedded font directory. If you have 
> installed groff from the deri-gropdf-ng the new format fonts will have been 
> installed, so the embedded font directory can be removed.

Do you have an estimate of how long your branch could take to merge?
As in, more than a month or less than a month?

> 
> Makefile
> 
> The simplest option would be to add a new rule to the Makefile which is 
> dependent on all the man pages have been built, and cd's into the scripts/
> LinuxManBook directory and calls the program with the location where the man 
> pages exist. However, I suspect Alex fancies something more complicated by 
> replacing the perl with a hybrid of shell command and make magic.

You suspect well.  :)

> 
> I attach a new copy of BuildLinuxMan.pl which is an amalgam of mine and 
> Brian's code. This has the new -paper flag.
> 
> Alex's MR branch
> 
> The new program now recognises existing .MR's in the document and provides the 
> "clean" destination name, so it should run against the new branch.
> 
>> 	nodemask ... on-
>> 	...
>> 	line, ...
>>
>> There appear to be 24 single word instances of online and 12 outdated
>> hyphenated compound word instances of on-line across all man pages.
>>
>> UI: I also noticed, while looking for tables to compare, that pages are
>> ordered by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g
>> ISO_8859-2 is after ISO_8859-16 which may not be as expected.
>> Used rpmvercmp in last line of perl sub sortman and works as expected.
> 
> I have used Sort::Versions (see above), thanks for the suggestion.
> 
>> Tech nitpick: .Z is still recognized by GUIs as compress output
>> (UNIX-compressed file) - is there no other file type suffix used for
>> ditroff intermediate output? Aha - Alex says .set:
>>
>> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
>>
> Well, that's settled.
> 
>> Added variables and changed those also in BLM-letter.pl: copy attached.
>>
>>> Thanks for your help.
>>
>> Happy to help in any way.
> 
> Hope you're happy with this version.

Let's open the improved Christmas present!  :D

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

On 2023-08-14 19:37, Alejandro Colomar wrote:
> 
>> Another change which would need to be accepted is 
>> to allow a fourth parameter to .MR which is the destination name. Normally the 
>> name of the destination is derived from the first two parameters concatenated 
>> with "_", but if the name part of the .MR call to the man page includes non-
>> ascii characters (such as ".MR my\-lovely\-page 7 ,") then it needs to provide 
>> a "clean" destination name.

I just re-read this, and am confused.  '\-' is an ASCII character, isn't it?
In fact, all of the Linux man-pages pathnames are composed exclusively of ASCII
characters, aren't they?

> 
> Is this really needed?  Can't gropdf just translate them internally?  Say, do
> unconditionally the equivalent of `| tr - _ |` or something like that.
> 
> [...]

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Deri]

On Monday, 14 August 2023 21:01:46 BST Alejandro Colomar wrote:
> On 2023-08-14 19:37, Alejandro Colomar wrote:
> >> Another change which would need to be accepted is
> >> to allow a fourth parameter to .MR which is the destination name.
> >> Normally the name of the destination is derived from the first two
> >> parameters concatenated with "_", but if the name part of the .MR call
> >> to the man page includes non- ascii characters (such as ".MR
> >> my\-lovely\-page 7 ,") then it needs to provide a "clean" destination
> >> name.
> 
> I just re-read this, and am confused.  '\-' is an ASCII character, isn't it?
> In fact, all of the Linux man-pages pathnames are composed exclusively of
> ASCII characters, aren't they?

Hi Alex,

You are correct, but it is not relevent since we are talking about the 
LinuxManBook. In this context .MR is a pointer to another page in the pdf, 
this is termed an internal reference, it could be forward or backwards within 
the pdf. If you look at the keyrings(7) man page you see examples such as:-

.SH SEE
.ad l
.nh
.BR keyctl (1),
.BR add_key (2),
.BR keyctl (2),
.BR request_key (2),
.BR keyctl (3),
.BR keyutils (7),
.BR persistent\-keyring (7),
.BR process\-keyring (7),
.BR session\-keyring (7),
.BR thread\-keyring (7),
.BR user\-keyring (7),
.BR user\-session\-keyring (7),
.BR pam_keyinit (8),
.BR request\-key (8)
.PP

Which when converted to .MR calls looks like:-

.SH SEE ALSO
.ad l
.nh
.MR "keyctl" "1" "," "keyctl"
.MR "add_key" "2" "," "add_key"
.MR "keyctl" "2" "," "keyctl"
.MR "request_key" "2" "," "request_key"
.MR "keyctl" "3" "," "keyctl"
.MR "keyutils" "7" "," "keyutils"
.MR "persistent\-keyring" "7" "," "persistent-keyring"
.MR "process\-keyring" "7" "," "process-keyring"
.MR "session\-keyring" "7" "," "session-keyring"
.MR "thread\-keyring" "7" "," "thread-keyring"
.MR "user\-keyring" "7" "," "user-keyring"
.MR "user\-session\-keyring" "7" "," "user-session-keyring"
.MR "pam_keyinit" "8" "," "pam_keyinit"
.MR "request\-key" "8" "" "request-key"
.PP

On the keyrings(7) page in the pdf you should be able to see the difference 
between HYPHEN (U+2010), which is what \- becomes, and HYPHEN-MINUS (U+002D) 
which is the ascii character. The problem is that the MR request is a bit 
naughty in that it uses the first two parameters for two purposes, first it is 
used as a destination, but it is also output as text. So as text it may 
contain escapes to enhance the typography, for example using \- for a better 
looking hyphen. It is not my job to impose artificial restrictions on how a 
man page author wants his creation to look, better to separate the two 
purposes, so there is no restriction.

> > Is this really needed?  Can't gropdf just translate them internally?  Say,
> > do unconditionally the equivalent of `| tr - _ |` or something like that.
> > 
> > [...]

This is all happening in groff macros way before it gets to gropdf.

Cheers 

Deri

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Deri,

On 2023-08-14 23:22, Deri wrote:
> On Monday, 14 August 2023 21:01:46 BST Alejandro Colomar wrote:
>> On 2023-08-14 19:37, Alejandro Colomar wrote:
>>>> Another change which would need to be accepted is
>>>> to allow a fourth parameter to .MR which is the destination name.
>>>> Normally the name of the destination is derived from the first two
>>>> parameters concatenated with "_", but if the name part of the .MR call
>>>> to the man page includes non- ascii characters (such as ".MR
>>>> my\-lovely\-page 7 ,") then it needs to provide a "clean" destination
>>>> name.
>>
>> I just re-read this, and am confused.  '\-' is an ASCII character, isn't it?
>> In fact, all of the Linux man-pages pathnames are composed exclusively of
>> ASCII characters, aren't they?
> 
> Hi Alex,
> 
> You are correct, but it is not relevent since we are talking about the 
> LinuxManBook. In this context .MR is a pointer to another page in the pdf, 
> this is termed an internal reference, it could be forward or backwards within 
> the pdf. If you look at the keyrings(7) man page you see examples such as:-
> 
> .SH SEE
> .ad l
> .nh
> .BR keyctl (1),
> .BR add_key (2),
> .BR keyctl (2),
> .BR request_key (2),
> .BR keyctl (3),
> .BR keyutils (7),
> .BR persistent\-keyring (7),
> .BR process\-keyring (7),
> .BR session\-keyring (7),
> .BR thread\-keyring (7),
> .BR user\-keyring (7),
> .BR user\-session\-keyring (7),
> .BR pam_keyinit (8),
> .BR request\-key (8)
> .PP
> 
> Which when converted to .MR calls looks like:-
> 
> .SH SEE ALSO
> .ad l
> .nh
> .MR "keyctl" "1" "," "keyctl"
> .MR "add_key" "2" "," "add_key"
> .MR "keyctl" "2" "," "keyctl"
> .MR "request_key" "2" "," "request_key"
> .MR "keyctl" "3" "," "keyctl"
> .MR "keyutils" "7" "," "keyutils"
> .MR "persistent\-keyring" "7" "," "persistent-keyring"
> .MR "process\-keyring" "7" "," "process-keyring"
> .MR "session\-keyring" "7" "," "session-keyring"
> .MR "thread\-keyring" "7" "," "thread-keyring"
> .MR "user\-keyring" "7" "," "user-keyring"
> .MR "user\-session\-keyring" "7" "," "user-session-keyring"
> .MR "pam_keyinit" "8" "," "pam_keyinit"
> .MR "request\-key" "8" "" "request-key"
> .PP
> 
> On the keyrings(7) page in the pdf you should be able to see the difference 
> between HYPHEN (U+2010), which is what \- becomes, and HYPHEN-MINUS (U+002D) 
> which is the ascii character.

It shouldn't be that way.  We use '\-' precisely to make it a HYPHEN-MINUS,
as it's the name of the file.  There shouldn't be any pages using '-', and
if there are, those are bugs.  All of our MR calls that have something
resembling a dash should be using '\-', which I expect to produce an ASCII
'-' (i.e., 45, 0x0D).

Am I missing something?

Cheers,
Alex

> The problem is that the MR request is a bit 
> naughty in that it uses the first two parameters for two purposes, first it is 
> used as a destination, but it is also output as text. So as text it may 
> contain escapes to enhance the typography, for example using \- for a better 
> looking hyphen. It is not my job to impose artificial restrictions on how a 
> man page author wants his creation to look, better to separate the two 
> purposes, so there is no restriction.
> 
>>> Is this really needed?  Can't gropdf just translate them internally?  Say,
>>> do unconditionally the equivalent of `| tr - _ |` or something like that.
>>>
>>> [...]
> 
> This is all happening in groff macros way before it gets to gropdf.
> 
> Cheers 
> 
> Deri
> 
> 
> 
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Deri]

On Monday, 14 August 2023 18:37:26 BST Alejandro Colomar wrote:
> Hi Deri, Branden,
> 
[...]
> 
> > Another change which would need to be accepted is
> > to allow a fourth parameter to .MR which is the destination name. Normally
> > the name of the destination is derived from the first two parameters
> > concatenated with "_", but if the name part of the .MR call to the man
> > page includes non- ascii characters (such as ".MR my\-lovely\-page 7 ,")
> > then it needs to provide a "clean" destination name.
> 
> Is this really needed?  Can't gropdf just translate them internally?  Say,
> do unconditionally the equivalent of `| tr - _ |` or something like that.

See other email.

[...]
> 
> Do you have an estimate of how long your branch could take to merge?
> As in, more than a month or less than a month?

I'm really hoping Branden's going to help me with that, I think he intimated 
that he might when he suggested I start a branch for the work. I have one more 
push to the branch to do, but I need to contact Peter since there is a minor 
tweak to om.tmac to make expandos work in mom.

> > Makefile
> > 
> > The simplest option would be to add a new rule to the Makefile which is
> > dependent on all the man pages have been built, and cd's into the scripts/
> > LinuxManBook directory and calls the program with the location where the
> > man pages exist. However, I suspect Alex fancies something more
> > complicated by replacing the perl with a hybrid of shell command and make
> > magic.
> 
> You suspect well.  :)

Just like my wife, she often tells me I'm "No longer required on the 
journey!". :-)

Cheers

Deri

> > I attach a new copy of BuildLinuxMan.pl which is an amalgam of mine and
> > Brian's code. This has the new -paper flag.
> > 
> > Alex's MR branch
> > 
> > The new program now recognises existing .MR's in the document and provides
> > the "clean" destination name, so it should run against the new branch.> 
> >> 	nodemask ... on-
> >> 	...
> >> 	line, ...
> >> 
> >> There appear to be 24 single word instances of online and 12 outdated
> >> hyphenated compound word instances of on-line across all man pages.
> >> 
> >> UI: I also noticed, while looking for tables to compare, that pages are
> >> ordered by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g
> >> ISO_8859-2 is after ISO_8859-16 which may not be as expected.
> >> Used rpmvercmp in last line of perl sub sortman and works as expected.
> > 
> > I have used Sort::Versions (see above), thanks for the suggestion.
> > 
> >> Tech nitpick: .Z is still recognized by GUIs as compress output
> >> (UNIX-compressed file) - is there no other file type suffix used for
> >> 
> >> ditroff intermediate output? Aha - Alex says .set:
> >> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
> > 
> > Well, that's settled.
> > 
> >> Added variables and changed those also in BLM-letter.pl: copy attached.
> >> 
> >>> Thanks for your help.
> >> 
> >> Happy to help in any way.
> > 
> > Hope you're happy with this version.
> 
> Let's open the improved Christmas present!  :D
> 
> Cheers,
> Alex

Re: No 6.05/.01 pdf book available

[Deri]

On Monday, 14 August 2023 22:32:49 BST Alejandro Colomar wrote:
> Hi Deri,
> 
> On 2023-08-14 23:22, Deri wrote:
> > On Monday, 14 August 2023 21:01:46 BST Alejandro Colomar wrote:
> >> On 2023-08-14 19:37, Alejandro Colomar wrote:
> >>>> Another change which would need to be accepted is
> >>>> to allow a fourth parameter to .MR which is the destination name.
> >>>> Normally the name of the destination is derived from the first two
> >>>> parameters concatenated with "_", but if the name part of the .MR call
> >>>> to the man page includes non- ascii characters (such as ".MR
> >>>> my\-lovely\-page 7 ,") then it needs to provide a "clean" destination
> >>>> name.
> >> 
> >> I just re-read this, and am confused.  '\-' is an ASCII character, isn't
> >> it? In fact, all of the Linux man-pages pathnames are composed
> >> exclusively of ASCII characters, aren't they?
> > 
> > Hi Alex,
> > 
> > You are correct, but it is not relevent since we are talking about the
> > LinuxManBook. In this context .MR is a pointer to another page in the pdf,
> > this is termed an internal reference, it could be forward or backwards
> > within the pdf. If you look at the keyrings(7) man page you see examples
> > such as:-
> > 
> > .SH SEE
> > .ad l
> > .nh
> > .BR keyctl (1),
> > .BR add_key (2),
> > .BR keyctl (2),
> > .BR request_key (2),
> > .BR keyctl (3),
> > .BR keyutils (7),
> > .BR persistent\-keyring (7),
> > .BR process\-keyring (7),
> > .BR session\-keyring (7),
> > .BR thread\-keyring (7),
> > .BR user\-keyring (7),
> > .BR user\-session\-keyring (7),
> > .BR pam_keyinit (8),
> > .BR request\-key (8)
> > .PP
> > 
> > Which when converted to .MR calls looks like:-
> > 
> > .SH SEE ALSO
> > .ad l
> > .nh
> > .MR "keyctl" "1" "," "keyctl"
> > .MR "add_key" "2" "," "add_key"
> > .MR "keyctl" "2" "," "keyctl"
> > .MR "request_key" "2" "," "request_key"
> > .MR "keyctl" "3" "," "keyctl"
> > .MR "keyutils" "7" "," "keyutils"
> > .MR "persistent\-keyring" "7" "," "persistent-keyring"
> > .MR "process\-keyring" "7" "," "process-keyring"
> > .MR "session\-keyring" "7" "," "session-keyring"
> > .MR "thread\-keyring" "7" "," "thread-keyring"
> > .MR "user\-keyring" "7" "," "user-keyring"
> > .MR "user\-session\-keyring" "7" "," "user-session-keyring"
> > .MR "pam_keyinit" "8" "," "pam_keyinit"
> > .MR "request\-key" "8" "" "request-key"
> > .PP
> > 
> > On the keyrings(7) page in the pdf you should be able to see the
> > difference
> > between HYPHEN (U+2010), which is what \- becomes, and HYPHEN-MINUS
> > (U+002D) which is the ascii character.
> 
> It shouldn't be that way.  We use '\-' precisely to make it a HYPHEN-MINUS,
> as it's the name of the file.  There shouldn't be any pages using '-', and
> if there are, those are bugs.  All of our MR calls that have something
> resembling a dash should be using '\-', which I expect to produce an ASCII
> '-' (i.e., 45, 0x0D).
> 
> Am I missing something?
> 
> Cheers,
> Alex

Hi Alex,

It turns out we are both wrong! I confused my hyphen with my minus as seen in 
the font:-

-       333,257 0       45      hyphen  002D
hy      "

\-      564,286 0       173     minus   2212

But as you can see \- is not ascii, it is unicode U+2212 which is why it can't 
be used to specify a destination, but it looks nicer as a glyph. The precise 
reason is because special characters are converted to a node internally and 
nodes can't be used as part of a .ds string name. This illustrates it:-

[derij@pip]$ echo ".ds pdflook(user\-keyring_7) 2508" | groff -z
troff:<standard input>:1: error: a special character is not allowed in an 
identifier
troff:<standard input>:1: error: bad string definition
[derij@pip]$ echo ".ds pdflook(user-keyring_7) 2508" | groff -z

In old gropdf this may in fact have worked because I fudged the issue by 
.asciifying the name which would convert \- to chr(173) which is ascii but 
this meant that you could not use any UTF-8 text which preconv converted to \
[uXXXX] since that .asciified to nothing.

There are other possible solutions. On my branch I have a new command 
.stringhex, which operates like .stringup/down but converts the contents to 
ascii hex, which hides the contents from  groff. So something like:-

[derij@pip]$ printf ".ds a user\-keyring_7
.stringhex a
.ds pdflook(\*a) 2508         
.tm \*a
"|groff -z
757365721A6B657972696E675F37


Cheers 

Deri

> > The problem is that the MR request is a bit
> > naughty in that it uses the first two parameters for two purposes, first
> > it is used as a destination, but it is also output as text. So as text it
> > may contain escapes to enhance the typography, for example using \- for a
> > better looking hyphen. It is not my job to impose artificial restrictions
> > on how a man page author wants his creation to look, better to separate
> > the two purposes, so there is no restriction.
> > 
> >>> Is this really needed?  Can't gropdf just translate them internally? 
> >>> Say,
> >>> do unconditionally the equivalent of `| tr - _ |` or something like
> >>> that.
> >>> 
> >>> [...]
> > 
> > This is all happening in groff macros way before it gets to gropdf.
> > 
> > Cheers
> > 
> > Deri

Re: No 6.05/.01 pdf book available

[Brian Inglis]

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

On 2023-08-14 10:06, Deri wrote:
> I'm afraid the dangling page hyphens are all my fault. :-(
> 
> Line missing in the bespoke an.tmac I provided, new version attached. I know
> Alex wants to run against a stock version of groff, with minimal
> customisation, and, once my branch is merged, there will be further pruning,
> but unless you add to Branden's wish list to include an ability to control the
> hierarchy of the bookmark panel, you will need a customised an.tmac. The
> reason is because the stock an.tmac has a hard coded hierarchy where the .TH
> line is given level 1 but as you want to have separate sections these need to
> be level one and everything else is moved up a level. Of course this just
> means making the starting level configurable on the command line, i.e.
> -r startbkmk=2 or some such. Another change which would need to be accepted is
> to allow a fourth parameter to .MR which is the destination name. Normally the
> name of the destination is derived from the first two parameters concatenated
> with "_", but if the name part of the .MR call to the man page includes non-
> ascii characters (such as ".MR my\-lovely\-page 7 ,") then it needs to provide
> a "clean" destination name.
> 
> Sorting
> 
> I decided to use Sort::Versions (rather than RPM::VersionSort) because it is
> available as a package on my system. Seems to do the job.
> 
> Paper
> 
> You can now specify the paper size for the book on the command line as "-paper
> size".
> 
> Fonts
> 
> There are 2 reasons I included fonts in the build environment:-
> 
> A) The man pages which define the various iso-8859 pages contain many glyphs
> which are not defined in the standard groff fonts, so I used the Tinos font
> from google which improves the coverage. If you want to get rid of the fonts,
> and rely on just the fonts in groff, you can change line 4 of anmark.tmac to:-
> 
> .special S U-TR
> 
> Which is an improvement on the standard fonts, and should be available as
> standard if the URW fonts were found when groff was built. You will see
> differences in iso-8859-7 and iso-8859-8 for example.
> 
> B) If you build the LinuxManBook using the 1.23.0+ flavour (with the newer
> gropdf that produces a substantially smaller pdf) it requires a slightly
> different font format so needs the embedded font directory. If you have
> installed groff from the deri-gropdf-ng the new format fonts will have been
> installed, so the embedded font directory can be removed.
> 
> Makefile
> 
> The simplest option would be to add a new rule to the Makefile which is
> dependent on all the man pages have been built, and cd's into the scripts/
> LinuxManBook directory and calls the program with the location where the man
> pages exist. However, I suspect Alex fancies something more complicated by
> replacing the perl with a hybrid of shell command and make magic.
> 
> I attach a new copy of BuildLinuxMan.pl which is an amalgam of mine and
> Brian's code. This has the new -paper flag.
> 
> Alex's MR branch
> 
> The new program now recognises existing .MR's in the document and provides the
> "clean" destination name, so it should run against the new branch.
> 
>> 	nodemask ... on-
>> 	...
>> 	line, ...

Looking forward to trying out the new spiffy macros and scripts.

>> There appear to be 24 single word instances of online and 12 outdated
>> hyphenated compound word instances of on-line across all man pages.
>>
>> UI: I also noticed, while looking for tables to compare, that pages are
>> ordered by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g
>> ISO_8859-2 is after ISO_8859-16 which may not be as expected.
>> Used rpmvercmp in last line of perl sub sortman and works as expected.
> 
> I have used Sort::Versions (see above), thanks for the suggestion.
> 
>> Tech nitpick: .Z is still recognized by GUIs as compress output
>> (UNIX-compressed file) - is there no other file type suffix used for
>> ditroff intermediate output? Aha - Alex says .set:
>>
>> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
>>
> Well, that's settled.
> 
>> Added variables and changed those also in BLM-letter.pl: copy attached.
>>
>>> Thanks for your help.
>>
>> Happy to help in any way.
> 
> Hope you're happy with this version.

Unlikely as versioncmp treats underscores as special rather than ignoring them 
as in rpmvercmp and sortman: see attached diffs for comparisons. ;^>

Had to drop more details as got bounced with too many attachments - retrying 
with only diffs: official-order is 6.05.01.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                  -- Antoine de Saint-Exupéry

[-- Attachment #2: sortman-noaliases-official-order.diff --]
[-- Type: text/plain, Size: 12703 bytes --]

--- sortman-noaliases-order.log	2023-08-14 18:06:36.097243800 -0600
+++ official-order.log	2023-08-14 17:42:32.058669100 -0600
@@ -2,10 +2,10 @@ intro(1)
 getent(1)
 iconv(1)
 ldd(1)
-localedef(1)
 locale(1)
-memusagestat(1)
+localedef(1)
 memusage(1)
+memusagestat(1)
 mtrace(1)
 pldd(1)
 sprof(1)
@@ -32,8 +32,8 @@ chroot(2)
 clock_getres(2)
 clock_nanosleep(2)
 clone(2)
-close_range(2)
 close(2)
+close_range(2)
 connect(2)
 copy_file_range(2)
 create_module(2)
@@ -43,10 +43,10 @@ epoll_create(2)
 epoll_ctl(2)
 epoll_wait(2)
 eventfd(2)
-execveat(2)
 execve(2)
-exit_group(2)
+execveat(2)
 _exit(2)
+exit_group(2)
 fallocate(2)
 fanotify_init(2)
 fanotify_mark(2)
@@ -56,6 +56,9 @@ fork(2)
 fsync(2)
 futex(2)
 futimesat(2)
+get_kernel_syms(2)
+get_mempolicy(2)
+get_robust_list(2)
 getcpu(2)
 getdents(2)
 getdomainname(2)
@@ -63,8 +66,6 @@ getgid(2)
 getgroups(2)
 gethostname(2)
 getitimer(2)
-get_kernel_syms(2)
-get_mempolicy(2)
 getpagesize(2)
 getpeername(2)
 getpid(2)
@@ -72,7 +73,6 @@ getpriority(2)
 getrandom(2)
 getresuid(2)
 getrlimit(2)
-get_robust_list(2)
 getrusage(2)
 getsid(2)
 getsockname(2)
@@ -88,6 +88,11 @@ inotify_add_watch(2)
 inotify_init(2)
 inotify_rm_watch(2)
 io_cancel(2)
+io_destroy(2)
+io_getevents(2)
+io_setup(2)
+io_submit(2)
+ioctl(2)
 ioctl_console(2)
 ioctl_fat(2)
 ioctl_ficlonerange(2)
@@ -99,14 +104,9 @@ ioctl_ns(2)
 ioctl_pipe(2)
 ioctl_tty(2)
 ioctl_userfaultfd(2)
-ioctl(2)
-io_destroy(2)
-io_getevents(2)
 ioperm(2)
 iopl(2)
 ioprio_set(2)
-io_setup(2)
-io_submit(2)
 ipc(2)
 kcmp(2)
 kexec_load(2)
@@ -118,7 +118,7 @@ landlock_restrict_self(2)
 link(2)
 listen(2)
 listxattr(2)
-llseek(2)
+_llseek(2)
 lookup_dcookie(2)
 lseek(2)
 madvise(2)
@@ -131,25 +131,25 @@ mincore(2)
 mkdir(2)
 mknod(2)
 mlock(2)
-mmap2(2)
 mmap(2)
+mmap2(2)
 modify_ldt(2)
-mount_setattr(2)
 mount(2)
+mount_setattr(2)
 move_pages(2)
 mprotect(2)
 mq_getsetattr(2)
 mremap(2)
 msgctl(2)
 msgget(2)
-msgop(2)
+MSGOP(2)
 msync(2)
 nanosleep(2)
 nfsservctl(2)
 nice(2)
-openat2(2)
-open_by_handle_at(2)
 open(2)
+open_by_handle_at(2)
+openat2(2)
 outb(2)
 pause(2)
 pciconfig_read(2)
@@ -171,14 +171,14 @@ process_vm_readv(2)
 ptrace(2)
 query_module(2)
 quotactl(2)
+read(2)
 readahead(2)
 readdir(2)
 readlink(2)
 readv(2)
-read(2)
 reboot(2)
-recvmmsg(2)
 recv(2)
+recvmmsg(2)
 remap_file_pages(2)
 removexattr(2)
 rename(2)
@@ -197,102 +197,102 @@ sched_setattr(2)
 sched_setparam(2)
 sched_setscheduler(2)
 sched_yield(2)
-seccomp_unotify(2)
 seccomp(2)
-select_tut(2)
+seccomp_unotify(2)
 select(2)
+SELECT_TUT(2)
 semctl(2)
 semget(2)
 semop(2)
+send(2)
 sendfile(2)
 sendmmsg(2)
-send(2)
+set_mempolicy(2)
+set_thread_area(2)
+set_tid_address(2)
 seteuid(2)
 setfsgid(2)
 setfsuid(2)
 setgid(2)
-set_mempolicy(2)
 setns(2)
 setpgid(2)
 setresuid(2)
 setreuid(2)
 setsid(2)
-set_thread_area(2)
-set_tid_address(2)
 setuid(2)
 setup(2)
 setxattr(2)
 sgetmask(2)
 shmctl(2)
 shmget(2)
-shmop(2)
+SHMOP(2)
 shutdown(2)
 sigaction(2)
 sigaltstack(2)
-signalfd(2)
 signal(2)
+signalfd(2)
 sigpending(2)
 sigprocmask(2)
 sigreturn(2)
 sigsuspend(2)
 sigwaitinfo(2)
+socket(2)
 socketcall(2)
 socketpair(2)
-socket(2)
 splice(2)
 spu_create(2)
 spu_run(2)
+stat(2)
 statfs(2)
 statx(2)
-stat(2)
 stime(2)
 subpage_prot(2)
 swapon(2)
 symlink(2)
-sync_file_range(2)
 sync(2)
-syscalls(2)
-syscall(2)
+sync_file_range(2)
 _syscall(2)
+syscall(2)
+syscalls(2)
 sysctl(2)
 sysfs(2)
 sysinfo(2)
 syslog(2)
 tee(2)
+time(2)
 timer_create(2)
 timer_delete(2)
-timerfd_create(2)
 timer_getoverrun(2)
 timer_settime(2)
+timerfd_create(2)
 times(2)
-time(2)
 tkill(2)
 truncate(2)
 umask(2)
 umount(2)
 uname(2)
-unimplemented(2)
+UNIMPLEMENTED(2)
 unlink(2)
 unshare(2)
 uselib(2)
 userfaultfd(2)
 ustat(2)
-utimensat(2)
 utime(2)
+utimensat(2)
 vfork(2)
 vhangup(2)
 vm86(2)
 vmsplice(2)
-wait4(2)
 wait(2)
+wait4(2)
 write(2)
 open_how(2type)
 intro(3)
 a64l(3)
 abort(3)
 abs(3)
-acosh(3)
 acos(3)
+acosh(3)
 addseverity(3)
 adjtime(3)
 aio_cancel(3)
@@ -306,14 +306,14 @@ aio_write(3)
 alloca(3)
 arc4random(3)
 argz_add(3)
-asinh(3)
 asin(3)
+asinh(3)
 asprintf(3)
-assert_perror(3)
 assert(3)
+assert_perror(3)
+atan(3)
 atan2(3)
 atanh(3)
-atan(3)
 atexit(3)
 atof(3)
 atoi(3)
@@ -328,51 +328,51 @@ bstring(3)
 bswap(3)
 btowc(3)
 btree(3)
-byteorder(3)
+BYTEORDER(3)
 bzero(3)
 cabs(3)
-cacosh(3)
 cacos(3)
+cacosh(3)
 canonicalize_file_name(3)
 carg(3)
-casinh(3)
 casin(3)
-catanh(3)
+casinh(3)
 catan(3)
+catanh(3)
 catgets(3)
 catopen(3)
 cbrt(3)
-ccosh(3)
 ccos(3)
+ccosh(3)
 ceil(3)
-cexp2(3)
 cexp(3)
+cexp2(3)
 cfree(3)
 cimag(3)
-circleq(3)
+CIRCLEQ(3)
 clearenv(3)
-clock_getcpuclockid(3)
 clock(3)
-clog2(3)
-clog10(3)
+clock_getcpuclockid(3)
 clog(3)
+clog10(3)
+clog2(3)
 closedir(3)
-cmsg(3)
+CMSG(3)
 confstr(3)
 conj(3)
 copysign(3)
-cosh(3)
 cos(3)
+cosh(3)
 cpow(3)
 cproj(3)
 CPU_SET(3)
 creal(3)
 crypt(3)
-csinh(3)
 csin(3)
+csinh(3)
 csqrt(3)
-ctanh(3)
 ctan(3)
+ctanh(3)
 ctermid(3)
 ctime(3)
 daemon(3)
@@ -381,38 +381,38 @@ des_crypt(3)
 difftime(3)
 dirfd(3)
 div(3)
+dl_iterate_phdr(3)
 dladdr(3)
 dlerror(3)
 dlinfo(3)
-dl_iterate_phdr(3)
 dlopen(3)
 dlsym(3)
 drand48(3)
 drand48_r(3)
 duplocale(3)
 dysize(3)
-ecvt_r(3)
 ecvt(3)
+ecvt_r(3)
 encrypt(3)
-endian(3)
 end(3)
+endian(3)
 envz_add(3)
-erfc(3)
 erf(3)
+erfc(3)
+err(3)
 errno(3)
 error(3)
-err(3)
 ether_aton(3)
 euidaccess(3)
 exec(3)
 exit(3)
-exp2(3)
+exp(3)
 exp10(3)
+exp2(3)
 expm1(3)
-exp(3)
 fabs(3)
-fcloseall(3)
 fclose(3)
+fcloseall(3)
 fdim(3)
 fenv(3)
 ferror(3)
@@ -428,15 +428,15 @@ fileno(3)
 finite(3)
 flockfile(3)
 floor(3)
-fmax(3)
 fma(3)
+fmax(3)
 fmemopen(3)
 fmin(3)
 fmod(3)
 fmtmsg(3)
 fnmatch(3)
-fopencookie(3)
 fopen(3)
+fopencookie(3)
 fpathconf(3)
 fpclassify(3)
 fpurge(3)
@@ -444,8 +444,8 @@ fputwc(3)
 fputws(3)
 fread(3)
 frexp(3)
-fseeko(3)
 fseek(3)
+fseeko(3)
 ftime(3)
 ftok(3)
 fts(3)
@@ -455,8 +455,10 @@ fwide(3)
 gamma(3)
 gcvt(3)
 _Generic(3)
-getaddrinfo_a(3)
+get_nprocs(3)
+get_phys_pages(3)
 getaddrinfo(3)
+getaddrinfo_a(3)
 getauxval(3)
 getcontext(3)
 getcwd(3)
@@ -466,8 +468,8 @@ getdtablesize(3)
 getentropy(3)
 getenv(3)
 getfsent(3)
-getgrent_r(3)
 getgrent(3)
+getgrent_r(3)
 getgrnam(3)
 getgrouplist(3)
 gethostbyname(3)
@@ -479,33 +481,31 @@ getloadavg(3)
 getlogin(3)
 getmntent(3)
 getnameinfo(3)
-getnetent_r(3)
 getnetent(3)
-get_nprocs(3)
+getnetent_r(3)
 getopt(3)
 getpass(3)
-get_phys_pages(3)
-getprotoent_r(3)
 getprotoent(3)
+getprotoent_r(3)
 getpt(3)
-getpwent_r(3)
+getpw(3)
 getpwent(3)
+getpwent_r(3)
 getpwnam(3)
-getpw(3)
-getrpcent_r(3)
 getrpcent(3)
+getrpcent_r(3)
 getrpcport(3)
-getservent_r(3)
+gets(3)
 getservent(3)
+getservent_r(3)
 getspnam(3)
 getsubopt(3)
-gets(3)
 getttyent(3)
 getusershell(3)
 getutent(3)
 getutmp(3)
-getwchar(3)
 getw(3)
+getwchar(3)
 glob(3)
 gnu_get_libc_version(3)
 grantpt(3)
@@ -514,17 +514,17 @@ gsignal(3)
 hash(3)
 hsearch(3)
 hypot(3)
+iconv(3)
 iconv_close(3)
 iconv_open(3)
-iconv(3)
 if_nameindex(3)
 if_nametoindex(3)
 ilogb(3)
 index(3)
+inet(3)
 inet_net_pton(3)
 inet_ntop(3)
 inet_pton(3)
-inet(3)
 INFINITY(3)
 initgroups(3)
 insque(3)
@@ -551,15 +551,15 @@ killpg(3)
 ldexp(3)
 lgamma(3)
 lio_listio(3)
-list(3)
+LIST(3)
 localeconv(3)
 lockf(3)
+log(3)
+log10(3)
 log1p(3)
 log2(3)
-log10(3)
 logb(3)
 login(3)
-log(3)
 lrint(3)
 lround(3)
 lsearch(3)
@@ -567,13 +567,13 @@ lseek64(3)
 makecontext(3)
 makedev(3)
 mallinfo(3)
+malloc(3)
 malloc_get_state(3)
-malloc_hook(3)
+__malloc_hook(3)
 malloc_info(3)
 malloc_stats(3)
 malloc_trim(3)
 malloc_usable_size(3)
-malloc(3)
 mallopt(3)
 matherr(3)
 MAX(3)
@@ -620,8 +620,8 @@ nl_langinfo(3)
 ntp_gettime(3)
 offsetof(3)
 on_exit(3)
-opendir(3)
 open_memstream(3)
+opendir(3)
 openpty(3)
 perror(3)
 popen(3)
@@ -630,9 +630,12 @@ posix_madvise(3)
 posix_memalign(3)
 posix_openpt(3)
 posix_spawn(3)
+pow(3)
 pow10(3)
 powerof2(3)
-pow(3)
+__ppc_get_timebase(3)
+__ppc_set_ppr_med(3)
+__ppc_yield(3)
 printf(3)
 profil(3)
 program_invocation_name(3)
@@ -647,12 +650,12 @@ pthread_attr_setschedparam(3)
 pthread_attr_setschedpolicy(3)
 pthread_attr_setscope(3)
 pthread_attr_setsigmask_np(3)
+pthread_attr_setstack(3)
 pthread_attr_setstackaddr(3)
 pthread_attr_setstacksize(3)
-pthread_attr_setstack(3)
 pthread_cancel(3)
-pthread_cleanup_push_defer_np(3)
 pthread_cleanup_push(3)
+pthread_cleanup_push_defer_np(3)
 pthread_create(3)
 pthread_detach(3)
 pthread_equal(3)
@@ -661,12 +664,12 @@ pthread_getattr_default_np(3)
 pthread_getattr_np(3)
 pthread_getcpuclockid(3)
 pthread_join(3)
-pthread_kill_other_threads_np(3)
 pthread_kill(3)
+pthread_kill_other_threads_np(3)
+pthread_mutex_consistent(3)
 pthread_mutexattr_getpshared(3)
 pthread_mutexattr_init(3)
 pthread_mutexattr_setrobust(3)
-pthread_mutex_consistent(3)
 pthread_rwlockattr_setkind_np(3)
 pthread_self(3)
 pthread_setaffinity_np(3)
@@ -691,15 +694,15 @@ putwchar(3)
 qecvt(3)
 qsort(3)
 raise(3)
-random_r(3)
-random(3)
 rand(3)
+random(3)
+random_r(3)
 rcmd(3)
-readdir_r(3)
+re_comp(3)
 readdir(3)
+readdir_r(3)
 realpath(3)
 recno(3)
-re_comp(3)
 regex(3)
 remainder(3)
 remove(3)
@@ -708,14 +711,14 @@ resolver(3)
 rewinddir(3)
 rexec(3)
 rint(3)
-roundup(3)
 round(3)
+roundup(3)
 rpc(3)
 rpmatch(3)
 rtime(3)
 rtnetlink(3)
-scalbln(3)
 scalb(3)
+scalbln(3)
 scandir(3)
 scanf(3)
 sched_getcpu(3)
@@ -731,6 +734,7 @@ sem_wait(3)
 setaliasent(3)
 setbuf(3)
 setenv(3)
+__setfpucw(3)
 setjmp(3)
 setlocale(3)
 setlogmask(3)
@@ -741,25 +745,25 @@ signbit(3)
 significand(3)
 sigpause(3)
 sigqueue(3)
-sigsetops(3)
 sigset(3)
+SIGSETOPS(3)
 sigvec(3)
 sigwait(3)
+sin(3)
 sincos(3)
 sinh(3)
-sin(3)
 sleep(3)
-slist(3)
+SLIST(3)
 sockatmark(3)
 sqrt(3)
 sscanf(3)
-stailq(3)
+STAILQ(3)
 static_assert(3)
 statvfs(3)
 stdarg(3)
 stdin(3)
-stdio_ext(3)
 stdio(3)
+stdio_ext(3)
 stpncpy(3)
 strcasecmp(3)
 strchr(3)
@@ -794,9 +798,9 @@ sysconf(3)
 syslog(3)
 system(3)
 sysv_signal(3)
-tailq(3)
-tanh(3)
+TAILQ(3)
 tan(3)
+tanh(3)
 tcgetpgrp(3)
 tcgetsid(3)
 telldir(3)
@@ -864,13 +868,9 @@ wmemmove(3)
 wmemset(3)
 wordexp(3)
 wprintf(3)
-xcrypt(3)
+XCRYPT(3)
 xdr(3)
 y0(3)
-__ppc_get_timebase(3)
-__ppc_set_ppr_med(3)
-__ppc_yield(3)
-__setfpucw(3)
 EOF(3const)
 EXIT_SUCCESS(3const)
 NULL(3const)
@@ -880,8 +880,8 @@ aiocb(3type)
 blkcnt_t(3type)
 blksize_t(3type)
 cc_t(3type)
-clockid_t(3type)
 clock_t(3type)
+clockid_t(3type)
 dev_t(3type)
 div_t(3type)
 double_t(3type)
@@ -901,9 +901,9 @@ ptrdiff_t(3type)
 size_t(3type)
 sockaddr(3type)
 stat(3type)
+time_t(3type)
 timer_t(3type)
 timespec(3type)
-time_t(3type)
 timeval(3type)
 tm(3type)
 va_list(3type)
@@ -934,8 +934,8 @@ sd(4)
 sk98lin(4)
 smartpqi(4)
 st(4)
-ttyS(4)
 tty(4)
+ttyS(4)
 vcs(4)
 veth(4)
 wavelan(4)
@@ -944,23 +944,23 @@ acct(5)
 charmap(5)
 core(5)
 dir_colors(5)
-elf(5)
+ELF(5)
 erofs(5)
 filesystems(5)
 ftpusers(5)
 gai.conf(5)
 group(5)
+host.conf(5)
 hosts(5)
 hosts.equiv(5)
-host.conf(5)
 issue(5)
 locale(5)
 motd(5)
 networks(5)
 nologin(5)
 nscd.conf(5)
-nsswitch.conf(5)
 nss(5)
+nsswitch.conf(5)
 passwd(5)
 proc(5)
 protocols(5)
@@ -980,15 +980,15 @@ utmp(5)
 intro(6)
 intro(7)
 address_families(7)
-aio(7)
-armscii-8(7)
+AIO(7)
+ARMSCII-8(7)
 arp(7)
 ascii(7)
 attributes(7)
-bootparam(7)
 boot(7)
-bpf-helpers(7)
-capabilities(7)
+bootparam(7)
+BPF-HELPERS(7)
+Capabilities(7)
 cgroup_namespaces(7)
 cgroups(7)
 charsets(7)
@@ -1010,29 +1010,29 @@ hostname(7)
 icmp(7)
 inode(7)
 inotify(7)
+ip(7)
 ipc_namespaces(7)
 ipv6(7)
-ip(7)
-iso_8859-1(7)
-iso_8859-2(7)
-iso_8859-3(7)
-iso_8859-4(7)
-iso_8859-5(7)
-iso_8859-6(7)
-iso_8859-7(7)
-iso_8859-8(7)
-iso_8859-9(7)
-iso_8859-10(7)
-iso_8859-11(7)
-iso_8859-13(7)
-iso_8859-14(7)
-iso_8859-15(7)
-iso_8859-16(7)
+ISO_8859-1(7)
+ISO_8859-10(7)
+ISO_8859-11(7)
+ISO_8859-13(7)
+ISO_8859-14(7)
+ISO_8859-15(7)
+ISO_8859-16(7)
+ISO_8859-2(7)
+ISO_8859-3(7)
+ISO_8859-4(7)
+ISO_8859-5(7)
+ISO_8859-6(7)
+ISO_8859-7(7)
+ISO_8859-8(7)
+ISO_8859-9(7)
 kernel_lockdown(7)
 keyrings(7)
-koi8-r(7)
-koi8-u(7)
-landlock(7)
+KOI8-R(7)
+KOI8-U(7)
+Landlock(7)
 libc(7)
 locale(7)
 mailaddr(7)
@@ -1062,7 +1062,7 @@ queue(7)
 random(7)
 raw(7)
 regex(7)
-rtld-audit(7)
+RTLD-AUDIT(7)
 rtnetlink(7)
 sched(7)
 sem_overview(7)
@@ -1076,34 +1076,34 @@ socket(7)
 spufs(7)
 standards(7)
 string_copying(7)
-suffixes(7)
+SUFFIXES(7)
 symlink(7)
 system_data_types(7)
 sysvipc(7)
 tcp(7)
 termio(7)
 thread-keyring(7)
-time_namespaces(7)
 time(7)
-udplite(7)
+time_namespaces(7)
 udp(7)
+udplite(7)
 unicode(7)
 units(7)
-unix(7)
+UNIX(7)
 uri(7)
 user-keyring(7)
-user_namespaces(7)
 user-session-keyring(7)
-utf-8(7)
+user_namespaces(7)
+UTF-8(7)
 uts_namespaces(7)
-vdso(7)
+vDSO(7)
 vsock(7)
 x25(7)
 xattr(7)
 intro(8)
 iconvconfig(8)
-ldconfig(8)
 ld.so(8)
+ldconfig(8)
 nscd(8)
 sln(8)
 tzselect(8)

[-- Attachment #3: rpmvercmp-versioncmp-order.diff --]
[-- Type: text/plain, Size: 4576 bytes --]

--- rpmvercmp-order.log	2023-08-14 17:42:33.044369200 -0600
+++ versioncmp-order.log	2023-08-14 17:42:33.296930300 -0600
@@ -56,9 +56,6 @@ fork(2)
 fsync(2)
 futex(2)
 futimesat(2)
-get_kernel_syms(2)
-get_mempolicy(2)
-get_robust_list(2)
 getcpu(2)
 getdents(2)
 getdomainname(2)
@@ -82,16 +79,14 @@ gettimeofday(2)
 getuid(2)
 getunwind(2)
 getxattr(2)
+get_kernel_syms(2)
+get_mempolicy(2)
+get_robust_list(2)
 idle(2)
 init_module(2)
 inotify_add_watch(2)
 inotify_init(2)
 inotify_rm_watch(2)
-io_cancel(2)
-io_destroy(2)
-io_getevents(2)
-io_setup(2)
-io_submit(2)
 ioctl(2)
 ioctl_console(2)
 ioctl_fat(2)
@@ -107,6 +102,11 @@ ioctl_userfaultfd(2)
 ioperm(2)
 iopl(2)
 ioprio_set(2)
+io_cancel(2)
+io_destroy(2)
+io_getevents(2)
+io_setup(2)
+io_submit(2)
 ipc(2)
 kcmp(2)
 kexec_load(2)
@@ -148,13 +148,13 @@ nanosleep(2)
 nfsservctl(2)
 nice(2)
 open(2)
-open_by_handle_at(2)
 openat2(2)
+open_by_handle_at(2)
 outb(2)
 pause(2)
 pciconfig_read(2)
-perf_event_open(2)
 perfmonctl(2)
+perf_event_open(2)
 personality(2)
 pidfd_getfd(2)
 pidfd_open(2)
@@ -207,9 +207,6 @@ semop(2)
 send(2)
 sendfile(2)
 sendmmsg(2)
-set_mempolicy(2)
-set_thread_area(2)
-set_tid_address(2)
 seteuid(2)
 setfsgid(2)
 setfsuid(2)
@@ -222,6 +219,9 @@ setsid(2)
 setuid(2)
 setup(2)
 setxattr(2)
+set_mempolicy(2)
+set_thread_area(2)
+set_tid_address(2)
 sgetmask(2)
 shmctl(2)
 shmget(2)
@@ -260,11 +260,11 @@ sysinfo(2)
 syslog(2)
 tee(2)
 time(2)
+timerfd_create(2)
 timer_create(2)
 timer_delete(2)
 timer_getoverrun(2)
 timer_settime(2)
-timerfd_create(2)
 times(2)
 tkill(2)
 truncate(2)
@@ -311,8 +311,8 @@ asinh(3)
 asprintf(3)
 assert(3)
 assert_perror(3)
-atan2(3)
 atan(3)
+atan2(3)
 atanh(3)
 atexit(3)
 atof(3)
@@ -345,16 +345,16 @@ cbrt(3)
 ccos(3)
 ccosh(3)
 ceil(3)
-cexp2(3)
 cexp(3)
+cexp2(3)
 cfree(3)
 cimag(3)
 CIRCLEQ(3)
 clearenv(3)
 clock(3)
 clock_getcpuclockid(3)
-clog2(3)
 clog(3)
+clog2(3)
 clog10(3)
 closedir(3)
 CMSG(3)
@@ -381,12 +381,12 @@ des_crypt(3)
 difftime(3)
 dirfd(3)
 div(3)
-dl_iterate_phdr(3)
 dladdr(3)
 dlerror(3)
 dlinfo(3)
 dlopen(3)
 dlsym(3)
+dl_iterate_phdr(3)
 drand48(3)
 drand48_r(3)
 duplocale(3)
@@ -406,8 +406,8 @@ ether_aton(3)
 euidaccess(3)
 exec(3)
 exit(3)
-exp2(3)
 exp(3)
+exp2(3)
 exp10(3)
 expm1(3)
 fabs(3)
@@ -455,8 +455,6 @@ fwide(3)
 gamma(3)
 gcvt(3)
 _Generic(3)
-get_nprocs(3)
-get_phys_pages(3)
 getaddrinfo(3)
 getaddrinfo_a(3)
 getauxval(3)
@@ -506,6 +504,8 @@ getutent(3)
 getutmp(3)
 getw(3)
 getwchar(3)
+get_nprocs(3)
+get_phys_pages(3)
 glob(3)
 gnu_get_libc_version(3)
 grantpt(3)
@@ -554,9 +554,9 @@ lio_listio(3)
 LIST(3)
 localeconv(3)
 lockf(3)
+log(3)
 log1p(3)
 log2(3)
-log(3)
 log10(3)
 logb(3)
 login(3)
@@ -577,8 +577,6 @@ malloc_usable_size(3)
 mallopt(3)
 matherr(3)
 MAX(3)
-MB_CUR_MAX(3)
-MB_LEN_MAX(3)
 mblen(3)
 mbrlen(3)
 mbrtowc(3)
@@ -587,6 +585,8 @@ mbsnrtowcs(3)
 mbsrtowcs(3)
 mbstowcs(3)
 mbtowc(3)
+MB_CUR_MAX(3)
+MB_LEN_MAX(3)
 mcheck(3)
 memccpy(3)
 memchr(3)
@@ -620,9 +620,9 @@ nl_langinfo(3)
 ntp_gettime(3)
 offsetof(3)
 on_exit(3)
-open_memstream(3)
 opendir(3)
 openpty(3)
+open_memstream(3)
 perror(3)
 popen(3)
 posix_fallocate(3)
@@ -666,10 +666,10 @@ pthread_getcpuclockid(3)
 pthread_join(3)
 pthread_kill(3)
 pthread_kill_other_threads_np(3)
-pthread_mutex_consistent(3)
 pthread_mutexattr_getpshared(3)
 pthread_mutexattr_init(3)
 pthread_mutexattr_setrobust(3)
+pthread_mutex_consistent(3)
 pthread_rwlockattr_setkind_np(3)
 pthread_self(3)
 pthread_setaffinity_np(3)
@@ -698,7 +698,6 @@ rand(3)
 random(3)
 random_r(3)
 rcmd(3)
-re_comp(3)
 readdir(3)
 readdir_r(3)
 realpath(3)
@@ -710,6 +709,7 @@ remquo(3)
 resolver(3)
 rewinddir(3)
 rexec(3)
+re_comp(3)
 rint(3)
 round(3)
 roundup(3)
@@ -880,8 +880,8 @@ aiocb(3type)
 blkcnt_t(3type)
 blksize_t(3type)
 cc_t(3type)
-clock_t(3type)
 clockid_t(3type)
+clock_t(3type)
 dev_t(3type)
 div_t(3type)
 double_t(3type)
@@ -901,10 +901,10 @@ ptrdiff_t(3type)
 size_t(3type)
 sockaddr(3type)
 stat(3type)
-time_t(3type)
 timer_t(3type)
 timespec(3type)
 timeval(3type)
+time_t(3type)
 tm(3type)
 va_list(3type)
 void(3type)
@@ -989,8 +989,8 @@ boot(7)
 bootparam(7)
 BPF-HELPERS(7)
 Capabilities(7)
-cgroup_namespaces(7)
 cgroups(7)
+cgroup_namespaces(7)
 charsets(7)
 complex(7)
 cp1251(7)
@@ -1071,8 +1071,8 @@ shm_overview(7)
 sigevent(7)
 signal-safety(7)
 signal(7)
-sock_diag(7)
 socket(7)
+sock_diag(7)
 spufs(7)
 standards(7)
 string_copying(7)
@@ -1092,8 +1092,8 @@ units(7)
 UNIX(7)
 uri(7)
 user-keyring(7)
-user_namespaces(7)
 user-session-keyring(7)
+user_namespaces(7)
 UTF-8(7)
 uts_namespaces(7)
 vDSO(7)

[-- Attachment #4: sortman-noaliases-versioncmp-order.diff --]
[-- Type: text/plain, Size: 12672 bytes --]

--- sortman-noaliases-order.log	2023-08-14 18:06:36.097243800 -0600
+++ versioncmp-order.log	2023-08-14 17:42:33.296930300 -0600
@@ -2,10 +2,10 @@ intro(1)
 getent(1)
 iconv(1)
 ldd(1)
-localedef(1)
 locale(1)
-memusagestat(1)
+localedef(1)
 memusage(1)
+memusagestat(1)
 mtrace(1)
 pldd(1)
 sprof(1)
@@ -32,8 +32,8 @@ chroot(2)
 clock_getres(2)
 clock_nanosleep(2)
 clone(2)
-close_range(2)
 close(2)
+close_range(2)
 connect(2)
 copy_file_range(2)
 create_module(2)
@@ -43,10 +43,10 @@ epoll_create(2)
 epoll_ctl(2)
 epoll_wait(2)
 eventfd(2)
-execveat(2)
 execve(2)
-exit_group(2)
+execveat(2)
 _exit(2)
+exit_group(2)
 fallocate(2)
 fanotify_init(2)
 fanotify_mark(2)
@@ -63,8 +63,6 @@ getgid(2)
 getgroups(2)
 gethostname(2)
 getitimer(2)
-get_kernel_syms(2)
-get_mempolicy(2)
 getpagesize(2)
 getpeername(2)
 getpid(2)
@@ -72,7 +70,6 @@ getpriority(2)
 getrandom(2)
 getresuid(2)
 getrlimit(2)
-get_robust_list(2)
 getrusage(2)
 getsid(2)
 getsockname(2)
@@ -82,12 +79,15 @@ gettimeofday(2)
 getuid(2)
 getunwind(2)
 getxattr(2)
+get_kernel_syms(2)
+get_mempolicy(2)
+get_robust_list(2)
 idle(2)
 init_module(2)
 inotify_add_watch(2)
 inotify_init(2)
 inotify_rm_watch(2)
-io_cancel(2)
+ioctl(2)
 ioctl_console(2)
 ioctl_fat(2)
 ioctl_ficlonerange(2)
@@ -99,12 +99,12 @@ ioctl_ns(2)
 ioctl_pipe(2)
 ioctl_tty(2)
 ioctl_userfaultfd(2)
-ioctl(2)
-io_destroy(2)
-io_getevents(2)
 ioperm(2)
 iopl(2)
 ioprio_set(2)
+io_cancel(2)
+io_destroy(2)
+io_getevents(2)
 io_setup(2)
 io_submit(2)
 ipc(2)
@@ -118,7 +118,7 @@ landlock_restrict_self(2)
 link(2)
 listen(2)
 listxattr(2)
-llseek(2)
+_llseek(2)
 lookup_dcookie(2)
 lseek(2)
 madvise(2)
@@ -131,30 +131,30 @@ mincore(2)
 mkdir(2)
 mknod(2)
 mlock(2)
-mmap2(2)
 mmap(2)
+mmap2(2)
 modify_ldt(2)
-mount_setattr(2)
 mount(2)
+mount_setattr(2)
 move_pages(2)
 mprotect(2)
 mq_getsetattr(2)
 mremap(2)
 msgctl(2)
 msgget(2)
-msgop(2)
+MSGOP(2)
 msync(2)
 nanosleep(2)
 nfsservctl(2)
 nice(2)
+open(2)
 openat2(2)
 open_by_handle_at(2)
-open(2)
 outb(2)
 pause(2)
 pciconfig_read(2)
-perf_event_open(2)
 perfmonctl(2)
+perf_event_open(2)
 personality(2)
 pidfd_getfd(2)
 pidfd_open(2)
@@ -171,14 +171,14 @@ process_vm_readv(2)
 ptrace(2)
 query_module(2)
 quotactl(2)
+read(2)
 readahead(2)
 readdir(2)
 readlink(2)
 readv(2)
-read(2)
 reboot(2)
-recvmmsg(2)
 recv(2)
+recvmmsg(2)
 remap_file_pages(2)
 removexattr(2)
 rename(2)
@@ -197,102 +197,102 @@ sched_setattr(2)
 sched_setparam(2)
 sched_setscheduler(2)
 sched_yield(2)
-seccomp_unotify(2)
 seccomp(2)
-select_tut(2)
+seccomp_unotify(2)
 select(2)
+SELECT_TUT(2)
 semctl(2)
 semget(2)
 semop(2)
+send(2)
 sendfile(2)
 sendmmsg(2)
-send(2)
 seteuid(2)
 setfsgid(2)
 setfsuid(2)
 setgid(2)
-set_mempolicy(2)
 setns(2)
 setpgid(2)
 setresuid(2)
 setreuid(2)
 setsid(2)
-set_thread_area(2)
-set_tid_address(2)
 setuid(2)
 setup(2)
 setxattr(2)
+set_mempolicy(2)
+set_thread_area(2)
+set_tid_address(2)
 sgetmask(2)
 shmctl(2)
 shmget(2)
-shmop(2)
+SHMOP(2)
 shutdown(2)
 sigaction(2)
 sigaltstack(2)
-signalfd(2)
 signal(2)
+signalfd(2)
 sigpending(2)
 sigprocmask(2)
 sigreturn(2)
 sigsuspend(2)
 sigwaitinfo(2)
+socket(2)
 socketcall(2)
 socketpair(2)
-socket(2)
 splice(2)
 spu_create(2)
 spu_run(2)
+stat(2)
 statfs(2)
 statx(2)
-stat(2)
 stime(2)
 subpage_prot(2)
 swapon(2)
 symlink(2)
-sync_file_range(2)
 sync(2)
-syscalls(2)
-syscall(2)
+sync_file_range(2)
 _syscall(2)
+syscall(2)
+syscalls(2)
 sysctl(2)
 sysfs(2)
 sysinfo(2)
 syslog(2)
 tee(2)
+time(2)
+timerfd_create(2)
 timer_create(2)
 timer_delete(2)
-timerfd_create(2)
 timer_getoverrun(2)
 timer_settime(2)
 times(2)
-time(2)
 tkill(2)
 truncate(2)
 umask(2)
 umount(2)
 uname(2)
-unimplemented(2)
+UNIMPLEMENTED(2)
 unlink(2)
 unshare(2)
 uselib(2)
 userfaultfd(2)
 ustat(2)
-utimensat(2)
 utime(2)
+utimensat(2)
 vfork(2)
 vhangup(2)
 vm86(2)
 vmsplice(2)
-wait4(2)
 wait(2)
+wait4(2)
 write(2)
 open_how(2type)
 intro(3)
 a64l(3)
 abort(3)
 abs(3)
-acosh(3)
 acos(3)
+acosh(3)
 addseverity(3)
 adjtime(3)
 aio_cancel(3)
@@ -306,14 +306,14 @@ aio_write(3)
 alloca(3)
 arc4random(3)
 argz_add(3)
-asinh(3)
 asin(3)
+asinh(3)
 asprintf(3)
-assert_perror(3)
 assert(3)
+assert_perror(3)
+atan(3)
 atan2(3)
 atanh(3)
-atan(3)
 atexit(3)
 atof(3)
 atoi(3)
@@ -328,51 +328,51 @@ bstring(3)
 bswap(3)
 btowc(3)
 btree(3)
-byteorder(3)
+BYTEORDER(3)
 bzero(3)
 cabs(3)
-cacosh(3)
 cacos(3)
+cacosh(3)
 canonicalize_file_name(3)
 carg(3)
-casinh(3)
 casin(3)
-catanh(3)
+casinh(3)
 catan(3)
+catanh(3)
 catgets(3)
 catopen(3)
 cbrt(3)
-ccosh(3)
 ccos(3)
+ccosh(3)
 ceil(3)
-cexp2(3)
 cexp(3)
+cexp2(3)
 cfree(3)
 cimag(3)
-circleq(3)
+CIRCLEQ(3)
 clearenv(3)
-clock_getcpuclockid(3)
 clock(3)
+clock_getcpuclockid(3)
+clog(3)
 clog2(3)
 clog10(3)
-clog(3)
 closedir(3)
-cmsg(3)
+CMSG(3)
 confstr(3)
 conj(3)
 copysign(3)
-cosh(3)
 cos(3)
+cosh(3)
 cpow(3)
 cproj(3)
 CPU_SET(3)
 creal(3)
 crypt(3)
-csinh(3)
 csin(3)
+csinh(3)
 csqrt(3)
-ctanh(3)
 ctan(3)
+ctanh(3)
 ctermid(3)
 ctime(3)
 daemon(3)
@@ -384,35 +384,35 @@ div(3)
 dladdr(3)
 dlerror(3)
 dlinfo(3)
-dl_iterate_phdr(3)
 dlopen(3)
 dlsym(3)
+dl_iterate_phdr(3)
 drand48(3)
 drand48_r(3)
 duplocale(3)
 dysize(3)
-ecvt_r(3)
 ecvt(3)
+ecvt_r(3)
 encrypt(3)
-endian(3)
 end(3)
+endian(3)
 envz_add(3)
-erfc(3)
 erf(3)
+erfc(3)
+err(3)
 errno(3)
 error(3)
-err(3)
 ether_aton(3)
 euidaccess(3)
 exec(3)
 exit(3)
+exp(3)
 exp2(3)
 exp10(3)
 expm1(3)
-exp(3)
 fabs(3)
-fcloseall(3)
 fclose(3)
+fcloseall(3)
 fdim(3)
 fenv(3)
 ferror(3)
@@ -428,15 +428,15 @@ fileno(3)
 finite(3)
 flockfile(3)
 floor(3)
-fmax(3)
 fma(3)
+fmax(3)
 fmemopen(3)
 fmin(3)
 fmod(3)
 fmtmsg(3)
 fnmatch(3)
-fopencookie(3)
 fopen(3)
+fopencookie(3)
 fpathconf(3)
 fpclassify(3)
 fpurge(3)
@@ -444,8 +444,8 @@ fputwc(3)
 fputws(3)
 fread(3)
 frexp(3)
-fseeko(3)
 fseek(3)
+fseeko(3)
 ftime(3)
 ftok(3)
 fts(3)
@@ -455,8 +455,8 @@ fwide(3)
 gamma(3)
 gcvt(3)
 _Generic(3)
-getaddrinfo_a(3)
 getaddrinfo(3)
+getaddrinfo_a(3)
 getauxval(3)
 getcontext(3)
 getcwd(3)
@@ -466,8 +466,8 @@ getdtablesize(3)
 getentropy(3)
 getenv(3)
 getfsent(3)
-getgrent_r(3)
 getgrent(3)
+getgrent_r(3)
 getgrnam(3)
 getgrouplist(3)
 gethostbyname(3)
@@ -479,33 +479,33 @@ getloadavg(3)
 getlogin(3)
 getmntent(3)
 getnameinfo(3)
-getnetent_r(3)
 getnetent(3)
-get_nprocs(3)
+getnetent_r(3)
 getopt(3)
 getpass(3)
-get_phys_pages(3)
-getprotoent_r(3)
 getprotoent(3)
+getprotoent_r(3)
 getpt(3)
-getpwent_r(3)
+getpw(3)
 getpwent(3)
+getpwent_r(3)
 getpwnam(3)
-getpw(3)
-getrpcent_r(3)
 getrpcent(3)
+getrpcent_r(3)
 getrpcport(3)
-getservent_r(3)
+gets(3)
 getservent(3)
+getservent_r(3)
 getspnam(3)
 getsubopt(3)
-gets(3)
 getttyent(3)
 getusershell(3)
 getutent(3)
 getutmp(3)
-getwchar(3)
 getw(3)
+getwchar(3)
+get_nprocs(3)
+get_phys_pages(3)
 glob(3)
 gnu_get_libc_version(3)
 grantpt(3)
@@ -514,17 +514,17 @@ gsignal(3)
 hash(3)
 hsearch(3)
 hypot(3)
+iconv(3)
 iconv_close(3)
 iconv_open(3)
-iconv(3)
 if_nameindex(3)
 if_nametoindex(3)
 ilogb(3)
 index(3)
+inet(3)
 inet_net_pton(3)
 inet_ntop(3)
 inet_pton(3)
-inet(3)
 INFINITY(3)
 initgroups(3)
 insque(3)
@@ -551,15 +551,15 @@ killpg(3)
 ldexp(3)
 lgamma(3)
 lio_listio(3)
-list(3)
+LIST(3)
 localeconv(3)
 lockf(3)
+log(3)
 log1p(3)
 log2(3)
 log10(3)
 logb(3)
 login(3)
-log(3)
 lrint(3)
 lround(3)
 lsearch(3)
@@ -567,18 +567,16 @@ lseek64(3)
 makecontext(3)
 makedev(3)
 mallinfo(3)
+malloc(3)
 malloc_get_state(3)
-malloc_hook(3)
+__malloc_hook(3)
 malloc_info(3)
 malloc_stats(3)
 malloc_trim(3)
 malloc_usable_size(3)
-malloc(3)
 mallopt(3)
 matherr(3)
 MAX(3)
-MB_CUR_MAX(3)
-MB_LEN_MAX(3)
 mblen(3)
 mbrlen(3)
 mbrtowc(3)
@@ -587,6 +585,8 @@ mbsnrtowcs(3)
 mbsrtowcs(3)
 mbstowcs(3)
 mbtowc(3)
+MB_CUR_MAX(3)
+MB_LEN_MAX(3)
 mcheck(3)
 memccpy(3)
 memchr(3)
@@ -621,8 +621,8 @@ ntp_gettime(3)
 offsetof(3)
 on_exit(3)
 opendir(3)
-open_memstream(3)
 openpty(3)
+open_memstream(3)
 perror(3)
 popen(3)
 posix_fallocate(3)
@@ -630,9 +630,12 @@ posix_madvise(3)
 posix_memalign(3)
 posix_openpt(3)
 posix_spawn(3)
+pow(3)
 pow10(3)
 powerof2(3)
-pow(3)
+__ppc_get_timebase(3)
+__ppc_set_ppr_med(3)
+__ppc_yield(3)
 printf(3)
 profil(3)
 program_invocation_name(3)
@@ -647,12 +650,12 @@ pthread_attr_setschedparam(3)
 pthread_attr_setschedpolicy(3)
 pthread_attr_setscope(3)
 pthread_attr_setsigmask_np(3)
+pthread_attr_setstack(3)
 pthread_attr_setstackaddr(3)
 pthread_attr_setstacksize(3)
-pthread_attr_setstack(3)
 pthread_cancel(3)
-pthread_cleanup_push_defer_np(3)
 pthread_cleanup_push(3)
+pthread_cleanup_push_defer_np(3)
 pthread_create(3)
 pthread_detach(3)
 pthread_equal(3)
@@ -661,8 +664,8 @@ pthread_getattr_default_np(3)
 pthread_getattr_np(3)
 pthread_getcpuclockid(3)
 pthread_join(3)
-pthread_kill_other_threads_np(3)
 pthread_kill(3)
+pthread_kill_other_threads_np(3)
 pthread_mutexattr_getpshared(3)
 pthread_mutexattr_init(3)
 pthread_mutexattr_setrobust(3)
@@ -691,15 +694,14 @@ putwchar(3)
 qecvt(3)
 qsort(3)
 raise(3)
-random_r(3)
-random(3)
 rand(3)
+random(3)
+random_r(3)
 rcmd(3)
-readdir_r(3)
 readdir(3)
+readdir_r(3)
 realpath(3)
 recno(3)
-re_comp(3)
 regex(3)
 remainder(3)
 remove(3)
@@ -707,15 +709,16 @@ remquo(3)
 resolver(3)
 rewinddir(3)
 rexec(3)
+re_comp(3)
 rint(3)
-roundup(3)
 round(3)
+roundup(3)
 rpc(3)
 rpmatch(3)
 rtime(3)
 rtnetlink(3)
-scalbln(3)
 scalb(3)
+scalbln(3)
 scandir(3)
 scanf(3)
 sched_getcpu(3)
@@ -731,6 +734,7 @@ sem_wait(3)
 setaliasent(3)
 setbuf(3)
 setenv(3)
+__setfpucw(3)
 setjmp(3)
 setlocale(3)
 setlogmask(3)
@@ -741,25 +745,25 @@ signbit(3)
 significand(3)
 sigpause(3)
 sigqueue(3)
-sigsetops(3)
 sigset(3)
+SIGSETOPS(3)
 sigvec(3)
 sigwait(3)
+sin(3)
 sincos(3)
 sinh(3)
-sin(3)
 sleep(3)
-slist(3)
+SLIST(3)
 sockatmark(3)
 sqrt(3)
 sscanf(3)
-stailq(3)
+STAILQ(3)
 static_assert(3)
 statvfs(3)
 stdarg(3)
 stdin(3)
-stdio_ext(3)
 stdio(3)
+stdio_ext(3)
 stpncpy(3)
 strcasecmp(3)
 strchr(3)
@@ -794,9 +798,9 @@ sysconf(3)
 syslog(3)
 system(3)
 sysv_signal(3)
-tailq(3)
-tanh(3)
+TAILQ(3)
 tan(3)
+tanh(3)
 tcgetpgrp(3)
 tcgetsid(3)
 telldir(3)
@@ -864,13 +868,9 @@ wmemmove(3)
 wmemset(3)
 wordexp(3)
 wprintf(3)
-xcrypt(3)
+XCRYPT(3)
 xdr(3)
 y0(3)
-__ppc_get_timebase(3)
-__ppc_set_ppr_med(3)
-__ppc_yield(3)
-__setfpucw(3)
 EOF(3const)
 EXIT_SUCCESS(3const)
 NULL(3const)
@@ -903,8 +903,8 @@ sockaddr(3type)
 stat(3type)
 timer_t(3type)
 timespec(3type)
-time_t(3type)
 timeval(3type)
+time_t(3type)
 tm(3type)
 va_list(3type)
 void(3type)
@@ -934,8 +934,8 @@ sd(4)
 sk98lin(4)
 smartpqi(4)
 st(4)
-ttyS(4)
 tty(4)
+ttyS(4)
 vcs(4)
 veth(4)
 wavelan(4)
@@ -944,23 +944,23 @@ acct(5)
 charmap(5)
 core(5)
 dir_colors(5)
-elf(5)
+ELF(5)
 erofs(5)
 filesystems(5)
 ftpusers(5)
 gai.conf(5)
 group(5)
+host.conf(5)
 hosts(5)
 hosts.equiv(5)
-host.conf(5)
 issue(5)
 locale(5)
 motd(5)
 networks(5)
 nologin(5)
 nscd.conf(5)
-nsswitch.conf(5)
 nss(5)
+nsswitch.conf(5)
 passwd(5)
 proc(5)
 protocols(5)
@@ -980,17 +980,17 @@ utmp(5)
 intro(6)
 intro(7)
 address_families(7)
-aio(7)
-armscii-8(7)
+AIO(7)
+ARMSCII-8(7)
 arp(7)
 ascii(7)
 attributes(7)
-bootparam(7)
 boot(7)
-bpf-helpers(7)
-capabilities(7)
-cgroup_namespaces(7)
+bootparam(7)
+BPF-HELPERS(7)
+Capabilities(7)
 cgroups(7)
+cgroup_namespaces(7)
 charsets(7)
 complex(7)
 cp1251(7)
@@ -1010,29 +1010,29 @@ hostname(7)
 icmp(7)
 inode(7)
 inotify(7)
+ip(7)
 ipc_namespaces(7)
 ipv6(7)
-ip(7)
-iso_8859-1(7)
-iso_8859-2(7)
-iso_8859-3(7)
-iso_8859-4(7)
-iso_8859-5(7)
-iso_8859-6(7)
-iso_8859-7(7)
-iso_8859-8(7)
-iso_8859-9(7)
-iso_8859-10(7)
-iso_8859-11(7)
-iso_8859-13(7)
-iso_8859-14(7)
-iso_8859-15(7)
-iso_8859-16(7)
+ISO_8859-1(7)
+ISO_8859-2(7)
+ISO_8859-3(7)
+ISO_8859-4(7)
+ISO_8859-5(7)
+ISO_8859-6(7)
+ISO_8859-7(7)
+ISO_8859-8(7)
+ISO_8859-9(7)
+ISO_8859-10(7)
+ISO_8859-11(7)
+ISO_8859-13(7)
+ISO_8859-14(7)
+ISO_8859-15(7)
+ISO_8859-16(7)
 kernel_lockdown(7)
 keyrings(7)
-koi8-r(7)
-koi8-u(7)
-landlock(7)
+KOI8-R(7)
+KOI8-U(7)
+Landlock(7)
 libc(7)
 locale(7)
 mailaddr(7)
@@ -1062,7 +1062,7 @@ queue(7)
 random(7)
 raw(7)
 regex(7)
-rtld-audit(7)
+RTLD-AUDIT(7)
 rtnetlink(7)
 sched(7)
 sem_overview(7)
@@ -1071,39 +1071,39 @@ shm_overview(7)
 sigevent(7)
 signal-safety(7)
 signal(7)
-sock_diag(7)
 socket(7)
+sock_diag(7)
 spufs(7)
 standards(7)
 string_copying(7)
-suffixes(7)
+SUFFIXES(7)
 symlink(7)
 system_data_types(7)
 sysvipc(7)
 tcp(7)
 termio(7)
 thread-keyring(7)
-time_namespaces(7)
 time(7)
-udplite(7)
+time_namespaces(7)
 udp(7)
+udplite(7)
 unicode(7)
 units(7)
-unix(7)
+UNIX(7)
 uri(7)
 user-keyring(7)
-user_namespaces(7)
 user-session-keyring(7)
-utf-8(7)
+user_namespaces(7)
+UTF-8(7)
 uts_namespaces(7)
-vdso(7)
+vDSO(7)
 vsock(7)
 x25(7)
 xattr(7)
 intro(8)
 iconvconfig(8)
-ldconfig(8)
 ld.so(8)
+ldconfig(8)
 nscd(8)
 sln(8)
 tzselect(8)

[-- Attachment #5: sortman-noaliases-rpmvercmp-order.diff --]
[-- Type: text/plain, Size: 12646 bytes --]

--- sortman-noaliases-order.log	2023-08-14 18:06:36.097243800 -0600
+++ rpmvercmp-order.log	2023-08-14 17:42:33.044369200 -0600
@@ -2,10 +2,10 @@ intro(1)
 getent(1)
 iconv(1)
 ldd(1)
-localedef(1)
 locale(1)
-memusagestat(1)
+localedef(1)
 memusage(1)
+memusagestat(1)
 mtrace(1)
 pldd(1)
 sprof(1)
@@ -32,8 +32,8 @@ chroot(2)
 clock_getres(2)
 clock_nanosleep(2)
 clone(2)
-close_range(2)
 close(2)
+close_range(2)
 connect(2)
 copy_file_range(2)
 create_module(2)
@@ -43,10 +43,10 @@ epoll_create(2)
 epoll_ctl(2)
 epoll_wait(2)
 eventfd(2)
-execveat(2)
 execve(2)
-exit_group(2)
+execveat(2)
 _exit(2)
+exit_group(2)
 fallocate(2)
 fanotify_init(2)
 fanotify_mark(2)
@@ -56,6 +56,9 @@ fork(2)
 fsync(2)
 futex(2)
 futimesat(2)
+get_kernel_syms(2)
+get_mempolicy(2)
+get_robust_list(2)
 getcpu(2)
 getdents(2)
 getdomainname(2)
@@ -63,8 +66,6 @@ getgid(2)
 getgroups(2)
 gethostname(2)
 getitimer(2)
-get_kernel_syms(2)
-get_mempolicy(2)
 getpagesize(2)
 getpeername(2)
 getpid(2)
@@ -72,7 +73,6 @@ getpriority(2)
 getrandom(2)
 getresuid(2)
 getrlimit(2)
-get_robust_list(2)
 getrusage(2)
 getsid(2)
 getsockname(2)
@@ -88,6 +88,11 @@ inotify_add_watch(2)
 inotify_init(2)
 inotify_rm_watch(2)
 io_cancel(2)
+io_destroy(2)
+io_getevents(2)
+io_setup(2)
+io_submit(2)
+ioctl(2)
 ioctl_console(2)
 ioctl_fat(2)
 ioctl_ficlonerange(2)
@@ -99,14 +104,9 @@ ioctl_ns(2)
 ioctl_pipe(2)
 ioctl_tty(2)
 ioctl_userfaultfd(2)
-ioctl(2)
-io_destroy(2)
-io_getevents(2)
 ioperm(2)
 iopl(2)
 ioprio_set(2)
-io_setup(2)
-io_submit(2)
 ipc(2)
 kcmp(2)
 kexec_load(2)
@@ -118,7 +118,7 @@ landlock_restrict_self(2)
 link(2)
 listen(2)
 listxattr(2)
-llseek(2)
+_llseek(2)
 lookup_dcookie(2)
 lseek(2)
 madvise(2)
@@ -131,25 +131,25 @@ mincore(2)
 mkdir(2)
 mknod(2)
 mlock(2)
-mmap2(2)
 mmap(2)
+mmap2(2)
 modify_ldt(2)
-mount_setattr(2)
 mount(2)
+mount_setattr(2)
 move_pages(2)
 mprotect(2)
 mq_getsetattr(2)
 mremap(2)
 msgctl(2)
 msgget(2)
-msgop(2)
+MSGOP(2)
 msync(2)
 nanosleep(2)
 nfsservctl(2)
 nice(2)
-openat2(2)
-open_by_handle_at(2)
 open(2)
+open_by_handle_at(2)
+openat2(2)
 outb(2)
 pause(2)
 pciconfig_read(2)
@@ -171,14 +171,14 @@ process_vm_readv(2)
 ptrace(2)
 query_module(2)
 quotactl(2)
+read(2)
 readahead(2)
 readdir(2)
 readlink(2)
 readv(2)
-read(2)
 reboot(2)
-recvmmsg(2)
 recv(2)
+recvmmsg(2)
 remap_file_pages(2)
 removexattr(2)
 rename(2)
@@ -197,102 +197,102 @@ sched_setattr(2)
 sched_setparam(2)
 sched_setscheduler(2)
 sched_yield(2)
-seccomp_unotify(2)
 seccomp(2)
-select_tut(2)
+seccomp_unotify(2)
 select(2)
+SELECT_TUT(2)
 semctl(2)
 semget(2)
 semop(2)
+send(2)
 sendfile(2)
 sendmmsg(2)
-send(2)
+set_mempolicy(2)
+set_thread_area(2)
+set_tid_address(2)
 seteuid(2)
 setfsgid(2)
 setfsuid(2)
 setgid(2)
-set_mempolicy(2)
 setns(2)
 setpgid(2)
 setresuid(2)
 setreuid(2)
 setsid(2)
-set_thread_area(2)
-set_tid_address(2)
 setuid(2)
 setup(2)
 setxattr(2)
 sgetmask(2)
 shmctl(2)
 shmget(2)
-shmop(2)
+SHMOP(2)
 shutdown(2)
 sigaction(2)
 sigaltstack(2)
-signalfd(2)
 signal(2)
+signalfd(2)
 sigpending(2)
 sigprocmask(2)
 sigreturn(2)
 sigsuspend(2)
 sigwaitinfo(2)
+socket(2)
 socketcall(2)
 socketpair(2)
-socket(2)
 splice(2)
 spu_create(2)
 spu_run(2)
+stat(2)
 statfs(2)
 statx(2)
-stat(2)
 stime(2)
 subpage_prot(2)
 swapon(2)
 symlink(2)
-sync_file_range(2)
 sync(2)
-syscalls(2)
-syscall(2)
+sync_file_range(2)
 _syscall(2)
+syscall(2)
+syscalls(2)
 sysctl(2)
 sysfs(2)
 sysinfo(2)
 syslog(2)
 tee(2)
+time(2)
 timer_create(2)
 timer_delete(2)
-timerfd_create(2)
 timer_getoverrun(2)
 timer_settime(2)
+timerfd_create(2)
 times(2)
-time(2)
 tkill(2)
 truncate(2)
 umask(2)
 umount(2)
 uname(2)
-unimplemented(2)
+UNIMPLEMENTED(2)
 unlink(2)
 unshare(2)
 uselib(2)
 userfaultfd(2)
 ustat(2)
-utimensat(2)
 utime(2)
+utimensat(2)
 vfork(2)
 vhangup(2)
 vm86(2)
 vmsplice(2)
-wait4(2)
 wait(2)
+wait4(2)
 write(2)
 open_how(2type)
 intro(3)
 a64l(3)
 abort(3)
 abs(3)
-acosh(3)
 acos(3)
+acosh(3)
 addseverity(3)
 adjtime(3)
 aio_cancel(3)
@@ -306,14 +306,14 @@ aio_write(3)
 alloca(3)
 arc4random(3)
 argz_add(3)
-asinh(3)
 asin(3)
+asinh(3)
 asprintf(3)
-assert_perror(3)
 assert(3)
+assert_perror(3)
 atan2(3)
-atanh(3)
 atan(3)
+atanh(3)
 atexit(3)
 atof(3)
 atoi(3)
@@ -328,51 +328,51 @@ bstring(3)
 bswap(3)
 btowc(3)
 btree(3)
-byteorder(3)
+BYTEORDER(3)
 bzero(3)
 cabs(3)
-cacosh(3)
 cacos(3)
+cacosh(3)
 canonicalize_file_name(3)
 carg(3)
-casinh(3)
 casin(3)
-catanh(3)
+casinh(3)
 catan(3)
+catanh(3)
 catgets(3)
 catopen(3)
 cbrt(3)
-ccosh(3)
 ccos(3)
+ccosh(3)
 ceil(3)
 cexp2(3)
 cexp(3)
 cfree(3)
 cimag(3)
-circleq(3)
+CIRCLEQ(3)
 clearenv(3)
-clock_getcpuclockid(3)
 clock(3)
+clock_getcpuclockid(3)
 clog2(3)
-clog10(3)
 clog(3)
+clog10(3)
 closedir(3)
-cmsg(3)
+CMSG(3)
 confstr(3)
 conj(3)
 copysign(3)
-cosh(3)
 cos(3)
+cosh(3)
 cpow(3)
 cproj(3)
 CPU_SET(3)
 creal(3)
 crypt(3)
-csinh(3)
 csin(3)
+csinh(3)
 csqrt(3)
-ctanh(3)
 ctan(3)
+ctanh(3)
 ctermid(3)
 ctime(3)
 daemon(3)
@@ -381,38 +381,38 @@ des_crypt(3)
 difftime(3)
 dirfd(3)
 div(3)
+dl_iterate_phdr(3)
 dladdr(3)
 dlerror(3)
 dlinfo(3)
-dl_iterate_phdr(3)
 dlopen(3)
 dlsym(3)
 drand48(3)
 drand48_r(3)
 duplocale(3)
 dysize(3)
-ecvt_r(3)
 ecvt(3)
+ecvt_r(3)
 encrypt(3)
-endian(3)
 end(3)
+endian(3)
 envz_add(3)
-erfc(3)
 erf(3)
+erfc(3)
+err(3)
 errno(3)
 error(3)
-err(3)
 ether_aton(3)
 euidaccess(3)
 exec(3)
 exit(3)
 exp2(3)
+exp(3)
 exp10(3)
 expm1(3)
-exp(3)
 fabs(3)
-fcloseall(3)
 fclose(3)
+fcloseall(3)
 fdim(3)
 fenv(3)
 ferror(3)
@@ -428,15 +428,15 @@ fileno(3)
 finite(3)
 flockfile(3)
 floor(3)
-fmax(3)
 fma(3)
+fmax(3)
 fmemopen(3)
 fmin(3)
 fmod(3)
 fmtmsg(3)
 fnmatch(3)
-fopencookie(3)
 fopen(3)
+fopencookie(3)
 fpathconf(3)
 fpclassify(3)
 fpurge(3)
@@ -444,8 +444,8 @@ fputwc(3)
 fputws(3)
 fread(3)
 frexp(3)
-fseeko(3)
 fseek(3)
+fseeko(3)
 ftime(3)
 ftok(3)
 fts(3)
@@ -455,8 +455,10 @@ fwide(3)
 gamma(3)
 gcvt(3)
 _Generic(3)
-getaddrinfo_a(3)
+get_nprocs(3)
+get_phys_pages(3)
 getaddrinfo(3)
+getaddrinfo_a(3)
 getauxval(3)
 getcontext(3)
 getcwd(3)
@@ -466,8 +468,8 @@ getdtablesize(3)
 getentropy(3)
 getenv(3)
 getfsent(3)
-getgrent_r(3)
 getgrent(3)
+getgrent_r(3)
 getgrnam(3)
 getgrouplist(3)
 gethostbyname(3)
@@ -479,33 +481,31 @@ getloadavg(3)
 getlogin(3)
 getmntent(3)
 getnameinfo(3)
-getnetent_r(3)
 getnetent(3)
-get_nprocs(3)
+getnetent_r(3)
 getopt(3)
 getpass(3)
-get_phys_pages(3)
-getprotoent_r(3)
 getprotoent(3)
+getprotoent_r(3)
 getpt(3)
-getpwent_r(3)
+getpw(3)
 getpwent(3)
+getpwent_r(3)
 getpwnam(3)
-getpw(3)
-getrpcent_r(3)
 getrpcent(3)
+getrpcent_r(3)
 getrpcport(3)
-getservent_r(3)
+gets(3)
 getservent(3)
+getservent_r(3)
 getspnam(3)
 getsubopt(3)
-gets(3)
 getttyent(3)
 getusershell(3)
 getutent(3)
 getutmp(3)
-getwchar(3)
 getw(3)
+getwchar(3)
 glob(3)
 gnu_get_libc_version(3)
 grantpt(3)
@@ -514,17 +514,17 @@ gsignal(3)
 hash(3)
 hsearch(3)
 hypot(3)
+iconv(3)
 iconv_close(3)
 iconv_open(3)
-iconv(3)
 if_nameindex(3)
 if_nametoindex(3)
 ilogb(3)
 index(3)
+inet(3)
 inet_net_pton(3)
 inet_ntop(3)
 inet_pton(3)
-inet(3)
 INFINITY(3)
 initgroups(3)
 insque(3)
@@ -551,15 +551,15 @@ killpg(3)
 ldexp(3)
 lgamma(3)
 lio_listio(3)
-list(3)
+LIST(3)
 localeconv(3)
 lockf(3)
 log1p(3)
 log2(3)
+log(3)
 log10(3)
 logb(3)
 login(3)
-log(3)
 lrint(3)
 lround(3)
 lsearch(3)
@@ -567,13 +567,13 @@ lseek64(3)
 makecontext(3)
 makedev(3)
 mallinfo(3)
+malloc(3)
 malloc_get_state(3)
-malloc_hook(3)
+__malloc_hook(3)
 malloc_info(3)
 malloc_stats(3)
 malloc_trim(3)
 malloc_usable_size(3)
-malloc(3)
 mallopt(3)
 matherr(3)
 MAX(3)
@@ -620,8 +620,8 @@ nl_langinfo(3)
 ntp_gettime(3)
 offsetof(3)
 on_exit(3)
-opendir(3)
 open_memstream(3)
+opendir(3)
 openpty(3)
 perror(3)
 popen(3)
@@ -630,9 +630,12 @@ posix_madvise(3)
 posix_memalign(3)
 posix_openpt(3)
 posix_spawn(3)
+pow(3)
 pow10(3)
 powerof2(3)
-pow(3)
+__ppc_get_timebase(3)
+__ppc_set_ppr_med(3)
+__ppc_yield(3)
 printf(3)
 profil(3)
 program_invocation_name(3)
@@ -647,12 +650,12 @@ pthread_attr_setschedparam(3)
 pthread_attr_setschedpolicy(3)
 pthread_attr_setscope(3)
 pthread_attr_setsigmask_np(3)
+pthread_attr_setstack(3)
 pthread_attr_setstackaddr(3)
 pthread_attr_setstacksize(3)
-pthread_attr_setstack(3)
 pthread_cancel(3)
-pthread_cleanup_push_defer_np(3)
 pthread_cleanup_push(3)
+pthread_cleanup_push_defer_np(3)
 pthread_create(3)
 pthread_detach(3)
 pthread_equal(3)
@@ -661,12 +664,12 @@ pthread_getattr_default_np(3)
 pthread_getattr_np(3)
 pthread_getcpuclockid(3)
 pthread_join(3)
-pthread_kill_other_threads_np(3)
 pthread_kill(3)
+pthread_kill_other_threads_np(3)
+pthread_mutex_consistent(3)
 pthread_mutexattr_getpshared(3)
 pthread_mutexattr_init(3)
 pthread_mutexattr_setrobust(3)
-pthread_mutex_consistent(3)
 pthread_rwlockattr_setkind_np(3)
 pthread_self(3)
 pthread_setaffinity_np(3)
@@ -691,15 +694,15 @@ putwchar(3)
 qecvt(3)
 qsort(3)
 raise(3)
-random_r(3)
-random(3)
 rand(3)
+random(3)
+random_r(3)
 rcmd(3)
-readdir_r(3)
+re_comp(3)
 readdir(3)
+readdir_r(3)
 realpath(3)
 recno(3)
-re_comp(3)
 regex(3)
 remainder(3)
 remove(3)
@@ -708,14 +711,14 @@ resolver(3)
 rewinddir(3)
 rexec(3)
 rint(3)
-roundup(3)
 round(3)
+roundup(3)
 rpc(3)
 rpmatch(3)
 rtime(3)
 rtnetlink(3)
-scalbln(3)
 scalb(3)
+scalbln(3)
 scandir(3)
 scanf(3)
 sched_getcpu(3)
@@ -731,6 +734,7 @@ sem_wait(3)
 setaliasent(3)
 setbuf(3)
 setenv(3)
+__setfpucw(3)
 setjmp(3)
 setlocale(3)
 setlogmask(3)
@@ -741,25 +745,25 @@ signbit(3)
 significand(3)
 sigpause(3)
 sigqueue(3)
-sigsetops(3)
 sigset(3)
+SIGSETOPS(3)
 sigvec(3)
 sigwait(3)
+sin(3)
 sincos(3)
 sinh(3)
-sin(3)
 sleep(3)
-slist(3)
+SLIST(3)
 sockatmark(3)
 sqrt(3)
 sscanf(3)
-stailq(3)
+STAILQ(3)
 static_assert(3)
 statvfs(3)
 stdarg(3)
 stdin(3)
-stdio_ext(3)
 stdio(3)
+stdio_ext(3)
 stpncpy(3)
 strcasecmp(3)
 strchr(3)
@@ -794,9 +798,9 @@ sysconf(3)
 syslog(3)
 system(3)
 sysv_signal(3)
-tailq(3)
-tanh(3)
+TAILQ(3)
 tan(3)
+tanh(3)
 tcgetpgrp(3)
 tcgetsid(3)
 telldir(3)
@@ -864,13 +868,9 @@ wmemmove(3)
 wmemset(3)
 wordexp(3)
 wprintf(3)
-xcrypt(3)
+XCRYPT(3)
 xdr(3)
 y0(3)
-__ppc_get_timebase(3)
-__ppc_set_ppr_med(3)
-__ppc_yield(3)
-__setfpucw(3)
 EOF(3const)
 EXIT_SUCCESS(3const)
 NULL(3const)
@@ -880,8 +880,8 @@ aiocb(3type)
 blkcnt_t(3type)
 blksize_t(3type)
 cc_t(3type)
-clockid_t(3type)
 clock_t(3type)
+clockid_t(3type)
 dev_t(3type)
 div_t(3type)
 double_t(3type)
@@ -901,9 +901,9 @@ ptrdiff_t(3type)
 size_t(3type)
 sockaddr(3type)
 stat(3type)
+time_t(3type)
 timer_t(3type)
 timespec(3type)
-time_t(3type)
 timeval(3type)
 tm(3type)
 va_list(3type)
@@ -934,8 +934,8 @@ sd(4)
 sk98lin(4)
 smartpqi(4)
 st(4)
-ttyS(4)
 tty(4)
+ttyS(4)
 vcs(4)
 veth(4)
 wavelan(4)
@@ -944,23 +944,23 @@ acct(5)
 charmap(5)
 core(5)
 dir_colors(5)
-elf(5)
+ELF(5)
 erofs(5)
 filesystems(5)
 ftpusers(5)
 gai.conf(5)
 group(5)
+host.conf(5)
 hosts(5)
 hosts.equiv(5)
-host.conf(5)
 issue(5)
 locale(5)
 motd(5)
 networks(5)
 nologin(5)
 nscd.conf(5)
-nsswitch.conf(5)
 nss(5)
+nsswitch.conf(5)
 passwd(5)
 proc(5)
 protocols(5)
@@ -980,15 +980,15 @@ utmp(5)
 intro(6)
 intro(7)
 address_families(7)
-aio(7)
-armscii-8(7)
+AIO(7)
+ARMSCII-8(7)
 arp(7)
 ascii(7)
 attributes(7)
-bootparam(7)
 boot(7)
-bpf-helpers(7)
-capabilities(7)
+bootparam(7)
+BPF-HELPERS(7)
+Capabilities(7)
 cgroup_namespaces(7)
 cgroups(7)
 charsets(7)
@@ -1010,29 +1010,29 @@ hostname(7)
 icmp(7)
 inode(7)
 inotify(7)
+ip(7)
 ipc_namespaces(7)
 ipv6(7)
-ip(7)
-iso_8859-1(7)
-iso_8859-2(7)
-iso_8859-3(7)
-iso_8859-4(7)
-iso_8859-5(7)
-iso_8859-6(7)
-iso_8859-7(7)
-iso_8859-8(7)
-iso_8859-9(7)
-iso_8859-10(7)
-iso_8859-11(7)
-iso_8859-13(7)
-iso_8859-14(7)
-iso_8859-15(7)
-iso_8859-16(7)
+ISO_8859-1(7)
+ISO_8859-2(7)
+ISO_8859-3(7)
+ISO_8859-4(7)
+ISO_8859-5(7)
+ISO_8859-6(7)
+ISO_8859-7(7)
+ISO_8859-8(7)
+ISO_8859-9(7)
+ISO_8859-10(7)
+ISO_8859-11(7)
+ISO_8859-13(7)
+ISO_8859-14(7)
+ISO_8859-15(7)
+ISO_8859-16(7)
 kernel_lockdown(7)
 keyrings(7)
-koi8-r(7)
-koi8-u(7)
-landlock(7)
+KOI8-R(7)
+KOI8-U(7)
+Landlock(7)
 libc(7)
 locale(7)
 mailaddr(7)
@@ -1062,7 +1062,7 @@ queue(7)
 random(7)
 raw(7)
 regex(7)
-rtld-audit(7)
+RTLD-AUDIT(7)
 rtnetlink(7)
 sched(7)
 sem_overview(7)
@@ -1076,34 +1076,34 @@ socket(7)
 spufs(7)
 standards(7)
 string_copying(7)
-suffixes(7)
+SUFFIXES(7)
 symlink(7)
 system_data_types(7)
 sysvipc(7)
 tcp(7)
 termio(7)
 thread-keyring(7)
-time_namespaces(7)
 time(7)
-udplite(7)
+time_namespaces(7)
 udp(7)
+udplite(7)
 unicode(7)
 units(7)
-unix(7)
+UNIX(7)
 uri(7)
 user-keyring(7)
 user_namespaces(7)
 user-session-keyring(7)
-utf-8(7)
+UTF-8(7)
 uts_namespaces(7)
-vdso(7)
+vDSO(7)
 vsock(7)
 x25(7)
 xattr(7)
 intro(8)
 iconvconfig(8)
-ldconfig(8)
 ld.so(8)
+ldconfig(8)
 nscd(8)
 sln(8)
 tzselect(8)

groff features for hyperlinked man pages (was: No 6.05/.01 pdf book available)

[G. Branden Robinson]

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

[looping in groff@gnu because I'm talking about GNU troff internals and
development plans I have]

At 2023-08-14T22:22:16+0100, Deri wrote:
> On Monday, 14 August 2023 21:01:46 BST Alejandro Colomar wrote:
> > On 2023-08-14 19:37, Alejandro Colomar wrote:
> > >> Another change which would need to be accepted is to allow a
> > >> fourth parameter to .MR which is the destination name.  Normally
> > >> the name of the destination is derived from the first two
> > >> parameters concatenated with "_", but if the name part of the .MR
> > >> call to the man page includes non- ascii characters (such as ".MR
> > >> my\-lovely\-page 7 ,") then it needs to provide a "clean"
> > >> destination name.

(linux-man readers might want to check out here, except for one
clarification about `MR` below.  The presentation below is mostly about
macro package and formatter internals.)

Yes.  This sort of thing has been undertaken a couple of times in macro
packages for groff.  Keith Marshall's pdfmark and your "an:cln" in the
"deri-gropdf-ng" branch are two examples.  I also had a couple of cracks
at it in my new feature in 1.23 for abbreviating pieces of man page
headers/footers if they would overrun other parts of it.[1]

These things are painful and fragile to implement.  We need a Better
Way(tm).  So I've proposed one and have roughed most of it out in my Git
stash.  I've mentioned it before on the groff list.  What we need is a
*roff string iterator.[2]  I think it's likely that implementing one
will also help us with other problems.[3][4]

Because strings, macros, and diversions can be interchanged, or at least
punned,[5] I think we'll also need a new conditional expression operator
to identify iterands that aren't ordinary or special characters.  The
only application of this that I envision, at least in early days, is so
that a macro iterating over them could skip them, ignore them, or throw
an error.  Already we have problems when people apply the cruder tools
GNU troff has for string manipulation to things that aren't
representable as individual characters within a string.[6]

With a general string/macro/diversion iterator, we can retire a lot of
the existing GNU troff requests that deal with strings, replacing them
with macros using the iterator request, which I intend to call `for`.  A
reverse iterator, `rfor`, may also be necessary.

Using the iterator request, in a file called "string.tmac" maybe,
`length`, `chop`, `substring`, `stringup`, and `stringdown` could all
become macros.  It would be easy to add `index` and `rindex` (after the
old BSD string library functions, now superseded by strchr() strrchr()),
which macro programmers have requested repeatedly over the years.

Often, just searching through a string for a character is all a macro
wants to do.  It's always been absurdly baroque to do that in GNU troff.
In AT&T troff, it was nigh impossible.  (If I don't say "nigh", Tadziu
Hoffman will appear in a puff of brimstone, arrayed in mask and cloak,
to show us some obfuscated but brilliant hack to get it done.  Okay,
forget I said "nigh".  ;-) )

> > I just re-read this, and am confused.  '\-' is an ASCII character,
> > isn't it?  In fact, all of the Linux man-pages pathnames are
> > composed exclusively of ASCII characters, aren't they?

You're thinking about this at the wrong level, Alex.  `\-` is a *roff
special character.  Unless converted to something else by character
translation or character definition,[7] it goes to the
device-independent page description language as a special character too.

Here's a quick glimpse of device-independent troff output, albeit
without helpful italics.

    c c  Typeset the glyph of the ordinary character c.  The drawing
         position is not advanced.

    C id⟨whitespace⟩
         Typeset the glyph of the special character id.  Trailing
         syntactical space is necessary to allow special character names
         of arbitrary length.  The drawing position is not advanced.

Consider a three-character *roff input document.

printf -- '-\\-\n' | groff -Tascii -Z

The part where the glyphs are written out looks like this.[8]

c-
C\-

It is up to the output device to decide what to do with that.  groff's
"ascii" and "latin1" output devices put out a U+002D character; its
"utf8" device puts out a minus sign, U+2212.  Now, before anyone
defecates a brick about the U+2212 not being easily greppable, nor
useful for copying and pasting to a shell prompt, the man(7) and mdoc(7)
macro packages override that.

  In man pages (only), groff maps the minus sign special character '\-'
  to the Basic Latin hyphen-minus (U+002D) because man pages require
  this glyph and there is no historically established *roff input
  character, ordinary or special, for obtaining it when a hyphen and
  minus sign are both separately available.  To obtain a true minus
  sign, use the special character escape sequences '\(mi' or '\[mi]'.[9]

> ... If you look at the keyrings(7) man page you see examples such as:-
> 
> .BR persistent\-keyring (7) ,
[...]
> Which when converted to .MR calls looks like:-
[...]
> .MR "persistent\-keyring" "7" "," "persistent-keyring"

Urp.  No, it doesn't.  Not unless you changed `MR` in deri-gropdf-ng.

.BR persistent\-keyring (7) ,

when converted to an `MR` call, looks like this.

.MR persistent\-keyring 7 ,

I expect man page authors would violently protest if they were told they
had to type all those quotes and, worse, repeat the name of the page.

One of the selling points of `MR` is less typing (no parentheses).  It
is hard enough to sell that macro on the linux-man list without
inaccurate claims entering the fray.

Now, if I understand correctly, is quite possible that something you're
doing in your branch is having `MR` call another macro internally to
prepare a hyperlink with some "anchor"--I won't say "node" because
collides with GNU troff internal jargon--information.  (This is
suggested by the heavy quoting you showed, since when macros call each
other with arbitrary numbers of arguments, and those arguments need to
be kept separate in the callee, the caller should use the `\$@` escape
sequence, which is analogous to the POSIX shell's `$@`.)

In your example above we see the "\-" special character getting
converted to an ordinary one, "-".  That's totally fine and is the sort
of thing I want to make easy--fundamentally with the `for` string
iterator request and practically with an `index` (or `strchr`, or
`bikeshed`) macro.

> On the keyrings(7) page in the pdf you should be able to see the
> difference between HYPHEN (U+2010), which is what \- becomes, and
> HYPHEN-MINUS (U+002D) which is the ascii character. The problem is
> that the MR request is a bit naughty in that it uses the first two
> parameters for two purposes, first it is used as a destination, but it
> is also output as text.

I don't think it's naughty; I think that by and large, man page authors
don't care to give "anchor names" to elements of their document.  They
want the macro package to figure it out.  I think one reason--maybe the
only reason--people are getting a glimpse inside the sausage factory of
GNU troff internals is because we haven't had a defined mechanism for
getting character data to an output device that is neither (1) intended
for formatting (writing visible glyphs) nor (2) in the printable ASCII
(Unicode Basic Latin) character set.  That's the aforementioned Savannah
#63074.[3]

Looking farther ahead, I think a further step is required if we're going
to have intra-page links; we're going to have to have a way to
disambiguate duplicates.  In practice there's not much risk from having
duplicate section titles in man pages, but I reckon a big, complex page
could duplicate subsection titles.  And if we automatically generate
hyperlink tags for paragraph tags, those would likely need it as well.
Maybe representing such internal anchors hierarchically will be enough:
"section_subsection_tag" or something like that.  I'm confident this
problem has been robustly solved elsewhere, and that all we need to do
is identify, adopt, and adapt a known good solution.

> So as text it may contain escapes to enhance the typography, for
> example using \- for a better looking hyphen. It is not my job to
> impose artificial restrictions on how a man page author wants his
> creation to look, better to separate the two purposes, so there is no
> restriction.

Agreed.

> > > Is this really needed?  Can't gropdf just translate them
> > > internally?  Say, do unconditionally the equivalent of `| tr - _
> > > |` or something like that.
> > > 
> > > [...]
> 
> This is all happening in groff macros way before it gets to gropdf.

I hope I have shed some light on this proces.

At 2023-08-14T22:40:31+0100, Deri wrote:
> I'm really hoping Branden's going to help me with that, I think he
> intimated that he might when he suggested I start a branch for the
> work. I have one more push to the branch to do, but I need to contact
> Peter since there is a minor tweak to om.tmac to make expandos work in
> mom.

Yes, I plan to help.  Some of the things you are having to do are ugly,
and making the existing GNU troff limitations described above really
hurt for a Do The Right Thing kind of programmer.  I want to fix these
problems so that the macro stuff we do in man(7) is as simple and easy
to understand as possible.  Complexity creates hiding places for bugs.

Regards,
Branden

[1] "[man] abbreviate titles when too wide, instead of overlapping them"
    https://savannah.gnu.org/bugs/?43532

[2] "[troff] string iteration handles escape sequences inconsistently
    (want `for` request)
    https://savannah.gnu.org/bugs/?62264

[3] "[troff] need a way to embed non-Basic Latin glyphs in device
    control commands"
    https://savannah.gnu.org/bugs/?63074

[4] "[troff] standard error output should be sanitized"
    https://savannah.gnu.org/bugs/?62787

[5] https://www.gnu.org/software/groff/manual/groff.html.node/Punning-Names.html#Punning-Names

[6] "[troff] .chop cannot surmount the barrier of a .char definition"
    https://savannah.gnu.org/bugs/?64439

[7] https://www.gnu.org/software/groff/manual/groff.html.node/Using-Symbols.html

[8] It actually doesn't.  In GNU troff, the GNU extension command 't' is
    used for sequences of non-overstruck ordinary characters when
    supported by output drivers, and in AT&T device-independent troff,
    the unnamed move-and-print command--a performance and storage
    optimization tuned to the needs of machines in 1980 and explained in
    CSTR #97--was used.  But 'c' is simple, supported by all device-
    independent troffs, and works.

[9] https://git.savannah.gnu.org/cgit/groff.git/tree/PROBLEMS?h=1.23.0#n112

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

Re: groff features for hyperlinked man pages (was: No 6.05/.01 pdf book available)

[G. Branden Robinson]

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

[self-follow-up]

Here's a quick note of self-correction to a point that is deep in the
grit.  linux-man readers can skip this unless they're concerned about
full disclosure, or (against all odds) interested.

At 2023-08-14T19:50:22-0500, G. Branden Robinson wrote:
> Consider a three-character *roff input document.
> 
> printf -- '-\\-\n' | groff -Tascii -Z
> 
> The part where the glyphs are written out looks like this.[8]
> 
> c-
> C\-

> [8] It actually doesn't.  In GNU troff, the GNU extension command 't'
>     is used for sequences of non-overstruck ordinary characters when
>     supported by output drivers, and in AT&T device-independent troff,
>     the unnamed move-and-print command--a performance and storage
>     optimization tuned to the needs of machines in 1980 and explained
>     in CSTR #97--was used.  But 'c' is simple, supported by all
>     device- independent troffs, and works.

A sharp-eyed reader may detect the fact I hand-simplified the
device-independent output, manually replacing the `t` command with a
`c`.

...because I forgot to add in the horizontal motion for the glyph
spacing.

So I commented out the `tcommand` directive in the font/devascii/DESC
file and solicited honest output.  Here it is.

$ printf -- '-\\-\n' | tg -Tascii -Z
x T ascii
x res 240 24 40
x init
p1
x font 1 R
f1
s10
V40
H0
md
DFd
c-H24
C\-
h24
n40 0
x trailer
V2640
x stop

The foregoing page description language is documented in groff_out(5)
and groff's Texinfo manual.

https://www.gnu.org/software/groff/manual/groff.html.node/gtroff-Output.html#gtroff-Output

Regards,
Branden

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

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Deri,

On 2023-08-14 23:40, Deri wrote:
[...]

>> Do you have an estimate of how long your branch could take to merge?
>> As in, more than a month or less than a month?
> 
> I'm really hoping Branden's going to help me with that, I think he intimated 
> that he might when he suggested I start a branch for the work. I have one more 
> push to the branch to do, but I need to contact Peter since there is a minor 
> tweak to om.tmac to make expandos work in mom.

Nice; then I'll wait for that to test groff from git HEAD, so I have less
moving parts.  :)

> 
>>> Makefile
>>>
>>> The simplest option would be to add a new rule to the Makefile which is
>>> dependent on all the man pages have been built, and cd's into the scripts/
>>> LinuxManBook directory and calls the program with the location where the
>>> man pages exist. However, I suspect Alex fancies something more
>>> complicated by replacing the perl with a hybrid of shell command and make
>>> magic.
>>
>> You suspect well.  :)
> 
> Just like my wife, she often tells me I'm "No longer required on the 
> journey!". :-)

:-)

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: groff features for hyperlinked man pages (was: No 6.05/.01 pdf book available)

[Alejandro Colomar]

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

Hi Branden, Deri,

On 2023-08-15 02:50, G. Branden Robinson wrote:
[...]

> 
>>> I just re-read this, and am confused.  '\-' is an ASCII character,
>>> isn't it?  In fact, all of the Linux man-pages pathnames are
>>> composed exclusively of ASCII characters, aren't they?
> 
> You're thinking about this at the wrong level, Alex.  `\-` is a *roff
> special character.  Unless converted to something else by character
> translation or character definition,[7] it goes to the
> device-independent page description language as a special character too.

[...]

> It is up to the output device to decide what to do with that.  groff's
> "ascii" and "latin1" output devices put out a U+002D character; its
> "utf8" device puts out a minus sign, U+2212.  Now, before anyone
> defecates a brick about the U+2212 not being easily greppable, nor
> useful for copying and pasting to a shell prompt, the man(7) and mdoc(7)
> macro packages override that.

So, \- is kept as a special character, even in man(7), until output
drivers translate it to ASCII -?  Or which program does the translation?
If it's gropdf(1) that makes the translation, I guess it will also be
able to perform the same translation for MR.  If the translation has
already been made by troff(1), then gropdf(1) shouldn't care.  In any
case, I still don't see the problem.

[...]

>> .BR persistent\-keyring (7) ,
> [...]
>> Which when converted to .MR calls looks like:-
> [...]
>> .MR "persistent\-keyring" "7" "," "persistent-keyring"
> 
> Urp.  No, it doesn't.  Not unless you changed `MR` in deri-gropdf-ng.
> 
> .BR persistent\-keyring (7) ,
> 
> when converted to an `MR` call, looks like this.
> 
> .MR persistent\-keyring 7 ,
> 
> I expect man page authors would violently protest if they were told they
> had to type all those quotes and, worse, repeat the name of the page.

Indeed.  I won't violently protest to Deri's experiments, as I do worse
aberrations while experimenting, but I would if this went into groff(1).  :)

> 
> One of the selling points of `MR` is less typing (no parentheses).

I woudn't really buy it just for that.  ;)
In fact, not having a RM variant, it's more typing when (foo(1)).
But yep, not being DRY would be a trigger for burning the streets of Paris.

>  It
> is hard enough to sell that macro on the linux-man list without
> inaccurate claims entering the fray.
> 
> Now, if I understand correctly, is quite possible that something you're
> doing in your branch is having `MR` call another macro internally to
> prepare a hyperlink with some "anchor"--I won't say "node" because
> collides with GNU troff internal jargon--information.  (This is
> suggested by the heavy quoting you showed, since when macros call each
> other with arbitrary numbers of arguments, and those arguments need to
> be kept separate in the callee, the caller should use the `\$@` escape
> sequence, which is analogous to the POSIX shell's `$@`.)

I'd expect that the hyperlinking ability should be modifyable with
groff(1) --I don't care at what level of the pipeline--, similar to how
it was modifiable with man2html(1).  But the source code shouldn't know
about it.

[...]

> I don't think it's naughty; I think that by and large, man page authors
> don't care to give "anchor names" to elements of their document.  They
> want the macro package to figure it out.

Indeed.  I'd like groff(1) to figure out some name that resembles the
text used as man page reference, or as section heading; I don't want to
specify it.

>  I think one reason--maybe the
> only reason--people are getting a glimpse inside the sausage factory of
> GNU troff internals is because we haven't had a defined mechanism for
> getting character data to an output device that is neither (1) intended
> for formatting (writing visible glyphs) nor (2) in the printable ASCII
> (Unicode Basic Latin) character set.  That's the aforementioned Savannah
> #63074.[3]
> 
> Looking farther ahead, I think a further step is required if we're going
> to have intra-page links; we're going to have to have a way to
> disambiguate duplicates.  In practice there's not much risk from having
> duplicate section titles in man pages, but I reckon a big, complex page
> could duplicate subsection titles.  And if we automatically generate
> hyperlink tags for paragraph tags, those would likely need it as well.
> Maybe representing such internal anchors hierarchically will be enough:
> "section_subsection_tag" or something like that.

Yep.  I'd expect something like that.  You could also include the page
name in a book, which would involve the changes suggested by Deri of not
having the page title hardcoded as the first level, right?


Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: groff features for hyperlinked man pages (was: No 6.05/.01 pdf book available)

[G. Branden Robinson]

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

Hi Alex,

At 2023-08-18T15:50:21+0200, Alejandro Colomar wrote:
> On 2023-08-15 02:50, G. Branden Robinson wrote:
> >>> I just re-read this, and am confused.  '\-' is an ASCII character,
> >>> isn't it?  In fact, all of the Linux man-pages pathnames are
> >>> composed exclusively of ASCII characters, aren't they?
[...]
> > You're thinking about this at the wrong level, Alex.  `\-` is a
> > *roff special character.  Unless converted to something else by
> > character translation or character definition,[7] it goes to the
> > device-independent page description language as a special character
> > too.
[...]
> > It is up to the output device to decide what to do with that.
> > groff's "ascii" and "latin1" output devices put out a U+002D
> > character; its "utf8" device puts out a minus sign, U+2212.  Now,
> > before anyone defecates a brick about the U+2212 not being easily
> > greppable, nor useful for copying and pasting to a shell prompt, the
> > man(7) and mdoc(7) macro packages override that.
> 
> So, \- is kept as a special character, even in man(7), until output
> drivers translate it to ASCII -?

In *roff, any character, ordinary or special, can be "translated" to any
other with the `tr` request.

.tr AB \" translate "A" to "B"
.tr -\- \" translate ordinary char '-' to special char '-'
.tr \[aq]' \" translate special char 'aq' to ordinary char "'"

The resemblance to Unix tr(1) is not coincidental.

In GNU troff, context-dependent translations are available (for fairly
specialized purposes--`trin` and `trnt`).  Beneath that,[1] you can
_redefine_ any ordinary or special character.

The formatter applies character translations (and, in GNU troff,
definitions) before producing output.

> Or which program does the translation?

Output devices can perform translations too.  In the above example, "'"
doesn't "remain" "'"; if the output device has directional single
quotes, groff's font descriptions will assign it to the glyph for U+2019
or similar.

Some time perusing the 1.23.0 groff_char(7) and groff_font(5) man pages
will be rewarded.  I hope one day soon to revise groff_out(5) and the
"Using Symbols" section of groff's Texinfo manual to my
satisfaction--the latter will likely drive updates to groff(7)--and by
then the path from input characters to visible output glyphs should be
completely illuminated.  If you were to call this stuff frustratingly
complex, I'd agree.  Most of the complexity exists for good reasons,
though some of those are historical.  The responsible update of
technical documentation entails unearthing and presenting those reasons.

> If it's gropdf(1) that makes the translation, I guess it will also be
> able to perform the same translation for MR.

The translation of `\-` to `-` specifically for the purpose of writing
PDF metadata (bookmarks) via troff device control commands is _extremely
specialized_.  No man page author should ever have to deal with it.

> If the translation has already been made by troff(1), then gropdf(1)
> shouldn't care.  In any case, I still don't see the problem.

If Deri and I do our jobs right, you won't need to care, nor see any
problems.  We're workin' on it.  (Mostly Deri has been, to date.  My
"contribution" has mainly been to look at an.tmac on one hand and the
"pdfhref" macro on the other and stare slack-jawed, wondering how the
hell I'll ever get the impedances to match.  Don't be surprised if
something gets refactored.)

> Indeed.  I won't violently protest to Deri's experiments, as I do
> worse aberrations while experimenting, but I would if this went into
> groff(1).  :)

I don't know what the current state of play with respect to a
four-argument `MR` in Deri's branch is.  I'll let him speak to it.  I'd
prefer not to undertake a code review half-cocked (and ill-prepared,
besides).

> > One of the selling points of `MR` is less typing (no parentheses).
> 
> I woudn't really buy it just for that.  ;)

No indeed, which is why it has much bigger reasons to recommend it,
namely those cited in groff's NEWS file.

  Inclusion of the `MR` macro was prompted by its introduction to
  Plan 9 from User Space's troff in August 2020.  Its purpose is to
  ameliorate several long-standing problems with man page cross
  references: (1) the package's lack of inherent hyperlink support for
  them; (2) false-positive identification of strings resembling man page
  cross references (as can happen with "exit(1)", "while(1)",
  "sleep(5)", "time(0)" and others) by terminal emulators and other
  programs; (3) the unwanted intrusion of hyphens into man page topics,
  which frustrates copy-and-paste operations (this problem has always
  been avoidable through use of the \% escape sequence, but cross
  references are frequent in man pages and some page authors are
  inexpert *roff users); and (4) deep divisions in man page maintenance
  communities over which typeface should be used to set the man page
  topic (italics, roman, or bold).

> In fact, not having a RM variant, it's more typing when (foo(1)).

It's exactly the same.  Check these with `wc -c`.

All your questions are answered elsewhere
.RB ( foo (1) ).

All your questions are answered elsewhere (\c
.MR foo 1 ).

I admit that the mysterious and frightening `\c` escape sequence punches
well above its weight in key strokes, however.  I'm trying to fix that.

groff_man_style(7):

     \c   End a text line without inserting space or attempting a break.
          Normally, if filling is enabled, the end of a text line is
          treated like a space; an output line may be broken there (if
          not, an adjustable space is inserted); if filling is disabled,
          the line will be broken there, as in .EX/.EE examples.  The
          next line is interpreted as usual and can include a macro call
          (contrast with \newline).  \c is useful when three font styles
          are needed in a single word, as in a command synopsis.

               .RB [ \-\-stylesheet=\c
               .IR name ]

          It also helps when changing font styles in .EX/.EE examples,
          since they are not filled.

               .EX
               $ \c
               .B groff \-T utf8 \-Z \c
               .I file \c
               .B | grotty \-i
               .EE

          Alternatively, and perhaps with better portability, the \f
          font selection escape sequence can be used; see below.  Using
          \c to continue a .TP paragraph tag across multiple input lines
          will render incorrectly with groff 1.22.3, mandoc 1.14.1,
          older versions of these programs, and perhaps with some other
          formatters.

I know that's a lot of words, but I want man page writers to use `\c`
without fear (and only) where it is necessary.  Six years ago when I
raised the question on the groff list, no one could explain it to my
satisfaction.  (That may be a "me" problem, not an "everyone else" one.
But other people have expressed unease with `\c` too.)

Incidentally:

A gear finally turned for me just in the past day or two when I realized
that the only reason the man(7) package has font style alternation
macros in the first place was because the *roff `it` request ignores
`\c`.  This was one of the first tricky groff issues I tried to grapple
with.  Years later, I understand that it was a painful botch for `it` to
ignore `\c`, particularly when `ce` did not.[2]

I felt like a fool for not realizing this sooner, but I've never seen
anyone else explicate this point, so maybe I'm not the dunce I think.
(Or I am, but for some other reason. :P )

If Doc Brown loaned me his DeLorean, I'd go back and plead with Joe
Ossanna to fix this in the early days.  If I could drive 88mph only back
to 1979, I'd ask Doug McIlroy to not use input traps in the man(7)
macros at all.

> I'd expect that the hyperlinking ability should be modifyable with
> groff(1) --I don't care at what level of the pipeline--, similar to
> how it was modifiable with man2html(1).  But the source code shouldn't
> know about it.

Please point me to which man2html(1) implementation you mean.[3]  I can
have a look and evaluate.

> I'd like groff(1) to figure out some name that resembles the text used
> as man page reference, or as section heading; I don't want to specify
> it.
[...]
> > Looking farther ahead, I think a further step is required if we're
> > going to have intra-page links; we're going to have to have a way to
> > disambiguate duplicates.  In practice there's not much risk from
> > having duplicate section titles in man pages, but I reckon a big,
> > complex page could duplicate subsection titles.  And if we
> > automatically generate hyperlink tags for paragraph tags, those
> > would likely need it as well.  Maybe representing such internal
> > anchors hierarchically will be enough: "section_subsection_tag" or
> > something like that.
> 
> Yep.  I'd expect something like that.  You could also include the page
> name in a book, which would involve the changes suggested by Deri of
> not having the page title hardcoded as the first level, right?

Yeah, we could put a page identifier (constructed from the first two
arguments to `TH`) as the first component of the anchor.  Would this
even need to be conditional?  Should we simply always do it?

Regards,
Branden

[1] Or, possibly, on top of it.  https://savannah.gnu.org/bugs/?62691

[2]

$ cat /tmp/it-vs-ce.tr
.de AA
BOOM!
..
.
.ie \n(.g .itc 1 AA
.el       .it 1 AA
Tick.  \c
Tick.
.ce 1
Clean up \c
debris.
$ nroff --version | sed 1q
GNU nroff (groff) version 1.23.0
$ nroff /tmp/it-vs-ce.tr | sed 3q
Tick.  Tick.  BOOM!
                        Clean up debris.

$ pdp11
PDP-11 simulator V3.8-1
sim> set cpu 11/45
Disabling XQ
sim> set tto 7b
sim> att rl unix_v7_rl.dsk
sim> boot rl
@boot
New Boot, known devices are hp ht rk rl rp tm vt
: rl(0,0)rl2unix
mem = 177856
# Restricted rights: Use, duplication, or disclosure
is subject to restrictions stated in your contract with
Western Electric Company, Inc.
Thu Sep 22 22:00:20 EDT 1988

login: dmr
$ nroff /tmp/it-vs-ce.tr | sed 3q
Tick.  BOOM!  Tick.
                        Clean up debris.


[3] https://invisible-island.net/scripts/man2html.html#same-name

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

Re: No 6.05/.01 pdf book available

[Deri]

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

On Tuesday, 15 August 2023 01:34:16 BST Brian Inglis wrote:
> On 2023-08-14 10:06, Deri wrote:
> > I'm afraid the dangling page hyphens are all my fault. :-(
> > 
> > Line missing in the bespoke an.tmac I provided, new version attached. I
> > know Alex wants to run against a stock version of groff, with minimal
> > customisation, and, once my branch is merged, there will be further
> > pruning, but unless you add to Branden's wish list to include an ability
> > to control the hierarchy of the bookmark panel, you will need a
> > customised an.tmac. The reason is because the stock an.tmac has a hard
> > coded hierarchy where the .TH line is given level 1 but as you want to
> > have separate sections these need to be level one and everything else is
> > moved up a level. Of course this just means making the starting level
> > configurable on the command line, i.e. -r startbkmk=2 or some such.
> > Another change which would need to be accepted is to allow a fourth
> > parameter to .MR which is the destination name. Normally the name of the
> > destination is derived from the first two parameters concatenated with
> > "_", but if the name part of the .MR call to the man page includes non-
> > ascii characters (such as ".MR my\-lovely\-page 7 ,") then it needs to
> > provide a "clean" destination name.
> > 
> > Sorting
> > 
> > I decided to use Sort::Versions (rather than RPM::VersionSort) because it
> > is available as a package on my system. Seems to do the job.
> > 
> > Paper
> > 
> > You can now specify the paper size for the book on the command line as
> > "-paper size".
> > 
> > Fonts
> > 
> > There are 2 reasons I included fonts in the build environment:-
> > 
> > A) The man pages which define the various iso-8859 pages contain many
> > glyphs which are not defined in the standard groff fonts, so I used the
> > Tinos font from google which improves the coverage. If you want to get
> > rid of the fonts, and rely on just the fonts in groff, you can change
> > line 4 of anmark.tmac to:-
> > 
> > .special S U-TR
> > 
> > Which is an improvement on the standard fonts, and should be available as
> > standard if the URW fonts were found when groff was built. You will see
> > differences in iso-8859-7 and iso-8859-8 for example.
> > 
> > B) If you build the LinuxManBook using the 1.23.0+ flavour (with the newer
> > gropdf that produces a substantially smaller pdf) it requires a slightly
> > different font format so needs the embedded font directory. If you have
> > installed groff from the deri-gropdf-ng the new format fonts will have
> > been
> > installed, so the embedded font directory can be removed.
> > 
> > Makefile
> > 
> > The simplest option would be to add a new rule to the Makefile which is
> > dependent on all the man pages have been built, and cd's into the scripts/
> > LinuxManBook directory and calls the program with the location where the
> > man pages exist. However, I suspect Alex fancies something more
> > complicated by replacing the perl with a hybrid of shell command and make
> > magic.
> > 
> > I attach a new copy of BuildLinuxMan.pl which is an amalgam of mine and
> > Brian's code. This has the new -paper flag.
> > 
> > Alex's MR branch
> > 
> > The new program now recognises existing .MR's in the document and provides
> > the "clean" destination name, so it should run against the new branch.> 
> >> 	nodemask ... on-
> >> 	...
> >> 	line, ...
> 
> Looking forward to trying out the new spiffy macros and scripts.
> 
> >> There appear to be 24 single word instances of online and 12 outdated
> >> hyphenated compound word instances of on-line across all man pages.
> >> 
> >> UI: I also noticed, while looking for tables to compare, that pages are
> >> ordered by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g
> >> ISO_8859-2 is after ISO_8859-16 which may not be as expected.
> >> Used rpmvercmp in last line of perl sub sortman and works as expected.
> > 
> > I have used Sort::Versions (see above), thanks for the suggestion.
> > 
> >> Tech nitpick: .Z is still recognized by GUIs as compress output
> >> (UNIX-compressed file) - is there no other file type suffix used for
> >> 
> >> ditroff intermediate output? Aha - Alex says .set:
> >> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
> > 
> > Well, that's settled.
> > 
> >> Added variables and changed those also in BLM-letter.pl: copy attached.
> >> 
> >>> Thanks for your help.
> >> 
> >> Happy to help in any way.
> > 
> > Hope you're happy with this version.
> 
> Unlikely as versioncmp treats underscores as special rather than ignoring
> them as in rpmvercmp and sortman: see attached diffs for comparisons. ;^>
> 
> Had to drop more details as got bounced with too many attachments - retrying
> with only diffs: official-order is 6.05.01.

Hi Brian,

Please can you check if this sort order is acceptable.

Cheers 

Deri


[-- Attachment #2: BuildLinuxMan.pl --]
[-- Type: application/x-perl, Size: 7075 bytes --]

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Deri,

On 2023-08-20 18:48, Deri wrote:
> 
> Hi Brian,
> 
> Please can you check if this sort order is acceptable.
> 
> Cheers 
> 
> Deri

Maybe you could call <.../repo-root/scripts/sortman>.  The root of
the repo is known, since it's the first argument to the script.
Is calling a shell script easy from within perl to sort text?

Cheers,
Alex

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Brian Inglis]

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

On 2023-08-20 10:48, Deri wrote:
> On Tuesday, 15 August 2023 01:34:16 BST Brian Inglis wrote:
>> On 2023-08-14 10:06, Deri wrote:
>>> I'm afraid the dangling page hyphens are all my fault. :-(
>>>
>>> Line missing in the bespoke an.tmac I provided, new version attached. I
>>> know Alex wants to run against a stock version of groff, with minimal
>>> customisation, and, once my branch is merged, there will be further
>>> pruning, but unless you add to Branden's wish list to include an ability
>>> to control the hierarchy of the bookmark panel, you will need a
>>> customised an.tmac. The reason is because the stock an.tmac has a hard
>>> coded hierarchy where the .TH line is given level 1 but as you want to
>>> have separate sections these need to be level one and everything else is
>>> moved up a level. Of course this just means making the starting level
>>> configurable on the command line, i.e. -r startbkmk=2 or some such.
>>> Another change which would need to be accepted is to allow a fourth
>>> parameter to .MR which is the destination name. Normally the name of the
>>> destination is derived from the first two parameters concatenated with
>>> "_", but if the name part of the .MR call to the man page includes non-
>>> ascii characters (such as ".MR my\-lovely\-page 7 ,") then it needs to
>>> provide a "clean" destination name.
>>>
>>> Sorting
>>>
>>> I decided to use Sort::Versions (rather than RPM::VersionSort) because it
>>> is available as a package on my system. Seems to do the job.
>>>
>>> Paper
>>>
>>> You can now specify the paper size for the book on the command line as
>>> "-paper size".
>>>
>>> Fonts
>>>
>>> There are 2 reasons I included fonts in the build environment:-
>>>
>>> A) The man pages which define the various iso-8859 pages contain many
>>> glyphs which are not defined in the standard groff fonts, so I used the
>>> Tinos font from google which improves the coverage. If you want to get
>>> rid of the fonts, and rely on just the fonts in groff, you can change
>>> line 4 of anmark.tmac to:-
>>>
>>> .special S U-TR
>>>
>>> Which is an improvement on the standard fonts, and should be available as
>>> standard if the URW fonts were found when groff was built. You will see
>>> differences in iso-8859-7 and iso-8859-8 for example.
>>>
>>> B) If you build the LinuxManBook using the 1.23.0+ flavour (with the newer
>>> gropdf that produces a substantially smaller pdf) it requires a slightly
>>> different font format so needs the embedded font directory. If you have
>>> installed groff from the deri-gropdf-ng the new format fonts will have
>>> been
>>> installed, so the embedded font directory can be removed.
>>>
>>> Makefile
>>>
>>> The simplest option would be to add a new rule to the Makefile which is
>>> dependent on all the man pages have been built, and cd's into the scripts/
>>> LinuxManBook directory and calls the program with the location where the
>>> man pages exist. However, I suspect Alex fancies something more
>>> complicated by replacing the perl with a hybrid of shell command and make
>>> magic.
>>>
>>> I attach a new copy of BuildLinuxMan.pl which is an amalgam of mine and
>>> Brian's code. This has the new -paper flag.
>>>
>>> Alex's MR branch
>>>
>>> The new program now recognises existing .MR's in the document and provides
>>> the "clean" destination name, so it should run against the new branch.>
>>>> 	nodemask ... on-
>>>> 	...
>>>> 	line, ...
>>
>> Looking forward to trying out the new spiffy macros and scripts.
>>
>>>> There appear to be 24 single word instances of online and 12 outdated
>>>> hyphenated compound word instances of on-line across all man pages.
>>>>
>>>> UI: I also noticed, while looking for tables to compare, that pages are
>>>> ordered by filename not like rpmvercmp/ls -v/RPM::VersionSort e.g
>>>> ISO_8859-2 is after ISO_8859-16 which may not be as expected.
>>>> Used rpmvercmp in last line of perl sub sortman and works as expected.
>>>
>>> I have used Sort::Versions (see above), thanks for the suggestion.
>>>
>>>> Tech nitpick: .Z is still recognized by GUIs as compress output
>>>> (UNIX-compressed file) - is there no other file type suffix used for
>>>>
>>>> ditroff intermediate output? Aha - Alex says .set:
>>>> 	https://lists.gnu.org/archive/html/groff/2023-04/msg00213.html
>>>
>>> Well, that's settled.
>>>
>>>> Added variables and changed those also in BLM-letter.pl: copy attached.

>> Unlikely as versioncmp treats underscores as special rather than ignoring
>> them as in rpmvercmp and sortman: see attached diffs for comparisons. ;^>
>>
>> Had to drop more details as got bounced with too many attachments - retrying
>> with only diffs: official-order is 6.05.01.

> Please can you check if this sort order is acceptable.

Hi Deri,

Please see attached comparisons to official and sortman orders:
main difference I see is iso-8859-n suffixes still not ordered numerically which 
is part of version comparisons.

Also did not see smaller header margin on page intro(1) fix in macro updates:
did you send the wrong macro file(s) or outdated version(s)?
I overwrote them in another copy of the previous LinuxManBook/;
that also contains utp.mac not utp.tmac?

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

[-- Attachment #2: sortman-blm4-perl-order.diff --]
[-- Type: text/plain, Size: 12879 bytes --]

--- sortman-noaliases-order.log	2023-08-14 18:06:36.097243800 -0600
+++ blm4-perl-order.log	2023-08-20 12:42:49.384053200 -0600
@@ -2,10 +2,10 @@ intro(1)
 getent(1)
 iconv(1)
 ldd(1)
-localedef(1)
 locale(1)
-memusagestat(1)
+localedef(1)
 memusage(1)
+memusagestat(1)
 mtrace(1)
 pldd(1)
 sprof(1)
@@ -32,8 +32,8 @@ chroot(2)
 clock_getres(2)
 clock_nanosleep(2)
 clone(2)
-close_range(2)
 close(2)
+close_range(2)
 connect(2)
 copy_file_range(2)
 create_module(2)
@@ -43,10 +43,10 @@ epoll_create(2)
 epoll_ctl(2)
 epoll_wait(2)
 eventfd(2)
-execveat(2)
 execve(2)
-exit_group(2)
+execveat(2)
 _exit(2)
+exit_group(2)
 fallocate(2)
 fanotify_init(2)
 fanotify_mark(2)
@@ -56,6 +56,9 @@ fork(2)
 fsync(2)
 futex(2)
 futimesat(2)
+get_kernel_syms(2)
+get_mempolicy(2)
+get_robust_list(2)
 getcpu(2)
 getdents(2)
 getdomainname(2)
@@ -63,8 +66,6 @@ getgid(2)
 getgroups(2)
 gethostname(2)
 getitimer(2)
-get_kernel_syms(2)
-get_mempolicy(2)
 getpagesize(2)
 getpeername(2)
 getpid(2)
@@ -72,7 +73,6 @@ getpriority(2)
 getrandom(2)
 getresuid(2)
 getrlimit(2)
-get_robust_list(2)
 getrusage(2)
 getsid(2)
 getsockname(2)
@@ -88,6 +88,11 @@ inotify_add_watch(2)
 inotify_init(2)
 inotify_rm_watch(2)
 io_cancel(2)
+io_destroy(2)
+io_getevents(2)
+io_setup(2)
+io_submit(2)
+ioctl(2)
 ioctl_console(2)
 ioctl_fat(2)
 ioctl_ficlonerange(2)
@@ -99,14 +104,9 @@ ioctl_ns(2)
 ioctl_pipe(2)
 ioctl_tty(2)
 ioctl_userfaultfd(2)
-ioctl(2)
-io_destroy(2)
-io_getevents(2)
 ioperm(2)
 iopl(2)
 ioprio_set(2)
-io_setup(2)
-io_submit(2)
 ipc(2)
 kcmp(2)
 kexec_load(2)
@@ -118,7 +118,7 @@ landlock_restrict_self(2)
 link(2)
 listen(2)
 listxattr(2)
-llseek(2)
+_llseek(2)
 lookup_dcookie(2)
 lseek(2)
 madvise(2)
@@ -131,25 +131,25 @@ mincore(2)
 mkdir(2)
 mknod(2)
 mlock(2)
-mmap2(2)
 mmap(2)
+mmap2(2)
 modify_ldt(2)
-mount_setattr(2)
 mount(2)
+mount_setattr(2)
 move_pages(2)
 mprotect(2)
 mq_getsetattr(2)
 mremap(2)
 msgctl(2)
 msgget(2)
-msgop(2)
+MSGOP(2)
 msync(2)
 nanosleep(2)
 nfsservctl(2)
 nice(2)
-openat2(2)
-open_by_handle_at(2)
 open(2)
+open_by_handle_at(2)
+openat2(2)
 outb(2)
 pause(2)
 pciconfig_read(2)
@@ -171,14 +171,14 @@ process_vm_readv(2)
 ptrace(2)
 query_module(2)
 quotactl(2)
+read(2)
 readahead(2)
 readdir(2)
 readlink(2)
 readv(2)
-read(2)
 reboot(2)
-recvmmsg(2)
 recv(2)
+recvmmsg(2)
 remap_file_pages(2)
 removexattr(2)
 rename(2)
@@ -197,102 +197,102 @@ sched_setattr(2)
 sched_setparam(2)
 sched_setscheduler(2)
 sched_yield(2)
-seccomp_unotify(2)
 seccomp(2)
-select_tut(2)
+seccomp_unotify(2)
 select(2)
+SELECT_TUT(2)
 semctl(2)
 semget(2)
 semop(2)
+send(2)
 sendfile(2)
 sendmmsg(2)
-send(2)
+set_mempolicy(2)
+set_thread_area(2)
+set_tid_address(2)
 seteuid(2)
 setfsgid(2)
 setfsuid(2)
 setgid(2)
-set_mempolicy(2)
 setns(2)
 setpgid(2)
 setresuid(2)
 setreuid(2)
 setsid(2)
-set_thread_area(2)
-set_tid_address(2)
 setuid(2)
 setup(2)
 setxattr(2)
 sgetmask(2)
 shmctl(2)
 shmget(2)
-shmop(2)
+SHMOP(2)
 shutdown(2)
 sigaction(2)
 sigaltstack(2)
-signalfd(2)
 signal(2)
+signalfd(2)
 sigpending(2)
 sigprocmask(2)
 sigreturn(2)
 sigsuspend(2)
 sigwaitinfo(2)
+socket(2)
 socketcall(2)
 socketpair(2)
-socket(2)
 splice(2)
 spu_create(2)
 spu_run(2)
+stat(2)
 statfs(2)
 statx(2)
-stat(2)
 stime(2)
 subpage_prot(2)
 swapon(2)
 symlink(2)
-sync_file_range(2)
 sync(2)
-syscalls(2)
-syscall(2)
+sync_file_range(2)
 _syscall(2)
+syscall(2)
+syscalls(2)
 sysctl(2)
 sysfs(2)
 sysinfo(2)
 syslog(2)
 tee(2)
+time(2)
 timer_create(2)
 timer_delete(2)
-timerfd_create(2)
 timer_getoverrun(2)
 timer_settime(2)
+timerfd_create(2)
 times(2)
-time(2)
 tkill(2)
 truncate(2)
 umask(2)
 umount(2)
 uname(2)
-unimplemented(2)
+UNIMPLEMENTED(2)
 unlink(2)
 unshare(2)
 uselib(2)
 userfaultfd(2)
 ustat(2)
-utimensat(2)
 utime(2)
+utimensat(2)
 vfork(2)
 vhangup(2)
 vm86(2)
 vmsplice(2)
-wait4(2)
 wait(2)
+wait4(2)
 write(2)
 open_how(2type)
 intro(3)
 a64l(3)
 abort(3)
 abs(3)
-acosh(3)
 acos(3)
+acosh(3)
 addseverity(3)
 adjtime(3)
 aio_cancel(3)
@@ -306,14 +306,14 @@ aio_write(3)
 alloca(3)
 arc4random(3)
 argz_add(3)
-asinh(3)
 asin(3)
+asinh(3)
 asprintf(3)
-assert_perror(3)
 assert(3)
+assert_perror(3)
+atan(3)
 atan2(3)
 atanh(3)
-atan(3)
 atexit(3)
 atof(3)
 atoi(3)
@@ -328,51 +328,51 @@ bstring(3)
 bswap(3)
 btowc(3)
 btree(3)
-byteorder(3)
+BYTEORDER(3)
 bzero(3)
 cabs(3)
-cacosh(3)
 cacos(3)
+cacosh(3)
 canonicalize_file_name(3)
 carg(3)
-casinh(3)
 casin(3)
-catanh(3)
+casinh(3)
 catan(3)
+catanh(3)
 catgets(3)
 catopen(3)
 cbrt(3)
-ccosh(3)
 ccos(3)
+ccosh(3)
 ceil(3)
-cexp2(3)
 cexp(3)
+cexp2(3)
 cfree(3)
 cimag(3)
-circleq(3)
+CIRCLEQ(3)
 clearenv(3)
-clock_getcpuclockid(3)
 clock(3)
-clog2(3)
-clog10(3)
+clock_getcpuclockid(3)
 clog(3)
+clog10(3)
+clog2(3)
 closedir(3)
-cmsg(3)
+CMSG(3)
 confstr(3)
 conj(3)
 copysign(3)
-cosh(3)
 cos(3)
+cosh(3)
 cpow(3)
 cproj(3)
 CPU_SET(3)
 creal(3)
 crypt(3)
-csinh(3)
 csin(3)
+csinh(3)
 csqrt(3)
-ctanh(3)
 ctan(3)
+ctanh(3)
 ctermid(3)
 ctime(3)
 daemon(3)
@@ -381,38 +381,38 @@ des_crypt(3)
 difftime(3)
 dirfd(3)
 div(3)
+dl_iterate_phdr(3)
 dladdr(3)
 dlerror(3)
 dlinfo(3)
-dl_iterate_phdr(3)
 dlopen(3)
 dlsym(3)
 drand48(3)
 drand48_r(3)
 duplocale(3)
 dysize(3)
-ecvt_r(3)
 ecvt(3)
+ecvt_r(3)
 encrypt(3)
-endian(3)
 end(3)
+endian(3)
 envz_add(3)
-erfc(3)
 erf(3)
+erfc(3)
+err(3)
 errno(3)
 error(3)
-err(3)
 ether_aton(3)
 euidaccess(3)
 exec(3)
 exit(3)
-exp2(3)
+exp(3)
 exp10(3)
+exp2(3)
 expm1(3)
-exp(3)
 fabs(3)
-fcloseall(3)
 fclose(3)
+fcloseall(3)
 fdim(3)
 fenv(3)
 ferror(3)
@@ -428,15 +428,15 @@ fileno(3)
 finite(3)
 flockfile(3)
 floor(3)
-fmax(3)
 fma(3)
+fmax(3)
 fmemopen(3)
 fmin(3)
 fmod(3)
 fmtmsg(3)
 fnmatch(3)
-fopencookie(3)
 fopen(3)
+fopencookie(3)
 fpathconf(3)
 fpclassify(3)
 fpurge(3)
@@ -444,8 +444,8 @@ fputwc(3)
 fputws(3)
 fread(3)
 frexp(3)
-fseeko(3)
 fseek(3)
+fseeko(3)
 ftime(3)
 ftok(3)
 fts(3)
@@ -455,8 +455,10 @@ fwide(3)
 gamma(3)
 gcvt(3)
 _Generic(3)
-getaddrinfo_a(3)
+get_nprocs(3)
+get_phys_pages(3)
 getaddrinfo(3)
+getaddrinfo_a(3)
 getauxval(3)
 getcontext(3)
 getcwd(3)
@@ -466,8 +468,8 @@ getdtablesize(3)
 getentropy(3)
 getenv(3)
 getfsent(3)
-getgrent_r(3)
 getgrent(3)
+getgrent_r(3)
 getgrnam(3)
 getgrouplist(3)
 gethostbyname(3)
@@ -479,33 +481,31 @@ getloadavg(3)
 getlogin(3)
 getmntent(3)
 getnameinfo(3)
-getnetent_r(3)
 getnetent(3)
-get_nprocs(3)
+getnetent_r(3)
 getopt(3)
 getpass(3)
-get_phys_pages(3)
-getprotoent_r(3)
 getprotoent(3)
+getprotoent_r(3)
 getpt(3)
-getpwent_r(3)
+getpw(3)
 getpwent(3)
+getpwent_r(3)
 getpwnam(3)
-getpw(3)
-getrpcent_r(3)
 getrpcent(3)
+getrpcent_r(3)
 getrpcport(3)
-getservent_r(3)
+gets(3)
 getservent(3)
+getservent_r(3)
 getspnam(3)
 getsubopt(3)
-gets(3)
 getttyent(3)
 getusershell(3)
 getutent(3)
 getutmp(3)
-getwchar(3)
 getw(3)
+getwchar(3)
 glob(3)
 gnu_get_libc_version(3)
 grantpt(3)
@@ -514,17 +514,17 @@ gsignal(3)
 hash(3)
 hsearch(3)
 hypot(3)
+iconv(3)
 iconv_close(3)
 iconv_open(3)
-iconv(3)
 if_nameindex(3)
 if_nametoindex(3)
 ilogb(3)
 index(3)
+inet(3)
 inet_net_pton(3)
 inet_ntop(3)
 inet_pton(3)
-inet(3)
 INFINITY(3)
 initgroups(3)
 insque(3)
@@ -551,15 +551,15 @@ killpg(3)
 ldexp(3)
 lgamma(3)
 lio_listio(3)
-list(3)
+LIST(3)
 localeconv(3)
 lockf(3)
+log(3)
+log10(3)
 log1p(3)
 log2(3)
-log10(3)
 logb(3)
 login(3)
-log(3)
 lrint(3)
 lround(3)
 lsearch(3)
@@ -567,13 +567,13 @@ lseek64(3)
 makecontext(3)
 makedev(3)
 mallinfo(3)
+malloc(3)
 malloc_get_state(3)
-malloc_hook(3)
+__malloc_hook(3)
 malloc_info(3)
 malloc_stats(3)
 malloc_trim(3)
 malloc_usable_size(3)
-malloc(3)
 mallopt(3)
 matherr(3)
 MAX(3)
@@ -620,8 +620,8 @@ nl_langinfo(3)
 ntp_gettime(3)
 offsetof(3)
 on_exit(3)
-opendir(3)
 open_memstream(3)
+opendir(3)
 openpty(3)
 perror(3)
 popen(3)
@@ -630,9 +630,12 @@ posix_madvise(3)
 posix_memalign(3)
 posix_openpt(3)
 posix_spawn(3)
+pow(3)
 pow10(3)
 powerof2(3)
-pow(3)
+__ppc_get_timebase(3)
+__ppc_set_ppr_med(3)
+__ppc_yield(3)
 printf(3)
 profil(3)
 program_invocation_name(3)
@@ -647,12 +650,12 @@ pthread_attr_setschedparam(3)
 pthread_attr_setschedpolicy(3)
 pthread_attr_setscope(3)
 pthread_attr_setsigmask_np(3)
+pthread_attr_setstack(3)
 pthread_attr_setstackaddr(3)
 pthread_attr_setstacksize(3)
-pthread_attr_setstack(3)
 pthread_cancel(3)
-pthread_cleanup_push_defer_np(3)
 pthread_cleanup_push(3)
+pthread_cleanup_push_defer_np(3)
 pthread_create(3)
 pthread_detach(3)
 pthread_equal(3)
@@ -661,12 +664,12 @@ pthread_getattr_default_np(3)
 pthread_getattr_np(3)
 pthread_getcpuclockid(3)
 pthread_join(3)
-pthread_kill_other_threads_np(3)
 pthread_kill(3)
+pthread_kill_other_threads_np(3)
+pthread_mutex_consistent(3)
 pthread_mutexattr_getpshared(3)
 pthread_mutexattr_init(3)
 pthread_mutexattr_setrobust(3)
-pthread_mutex_consistent(3)
 pthread_rwlockattr_setkind_np(3)
 pthread_self(3)
 pthread_setaffinity_np(3)
@@ -691,15 +694,15 @@ putwchar(3)
 qecvt(3)
 qsort(3)
 raise(3)
-random_r(3)
-random(3)
 rand(3)
+random(3)
+random_r(3)
 rcmd(3)
-readdir_r(3)
+re_comp(3)
 readdir(3)
+readdir_r(3)
 realpath(3)
 recno(3)
-re_comp(3)
 regex(3)
 remainder(3)
 remove(3)
@@ -708,14 +711,14 @@ resolver(3)
 rewinddir(3)
 rexec(3)
 rint(3)
-roundup(3)
 round(3)
+roundup(3)
 rpc(3)
 rpmatch(3)
 rtime(3)
 rtnetlink(3)
-scalbln(3)
 scalb(3)
+scalbln(3)
 scandir(3)
 scanf(3)
 sched_getcpu(3)
@@ -731,6 +734,7 @@ sem_wait(3)
 setaliasent(3)
 setbuf(3)
 setenv(3)
+__setfpucw(3)
 setjmp(3)
 setlocale(3)
 setlogmask(3)
@@ -741,25 +745,25 @@ signbit(3)
 significand(3)
 sigpause(3)
 sigqueue(3)
-sigsetops(3)
 sigset(3)
+SIGSETOPS(3)
 sigvec(3)
 sigwait(3)
+sin(3)
 sincos(3)
 sinh(3)
-sin(3)
 sleep(3)
-slist(3)
+SLIST(3)
 sockatmark(3)
 sqrt(3)
 sscanf(3)
-stailq(3)
+STAILQ(3)
 static_assert(3)
 statvfs(3)
 stdarg(3)
 stdin(3)
-stdio_ext(3)
 stdio(3)
+stdio_ext(3)
 stpncpy(3)
 strcasecmp(3)
 strchr(3)
@@ -794,9 +798,9 @@ sysconf(3)
 syslog(3)
 system(3)
 sysv_signal(3)
-tailq(3)
-tanh(3)
+TAILQ(3)
 tan(3)
+tanh(3)
 tcgetpgrp(3)
 tcgetsid(3)
 telldir(3)
@@ -864,13 +868,9 @@ wmemmove(3)
 wmemset(3)
 wordexp(3)
 wprintf(3)
-xcrypt(3)
+XCRYPT(3)
 xdr(3)
 y0(3)
-__ppc_get_timebase(3)
-__ppc_set_ppr_med(3)
-__ppc_yield(3)
-__setfpucw(3)
 EOF(3const)
 EXIT_SUCCESS(3const)
 NULL(3const)
@@ -880,8 +880,8 @@ aiocb(3type)
 blkcnt_t(3type)
 blksize_t(3type)
 cc_t(3type)
-clockid_t(3type)
 clock_t(3type)
+clockid_t(3type)
 dev_t(3type)
 div_t(3type)
 double_t(3type)
@@ -901,9 +901,9 @@ ptrdiff_t(3type)
 size_t(3type)
 sockaddr(3type)
 stat(3type)
+time_t(3type)
 timer_t(3type)
 timespec(3type)
-time_t(3type)
 timeval(3type)
 tm(3type)
 va_list(3type)
@@ -934,8 +934,8 @@ sd(4)
 sk98lin(4)
 smartpqi(4)
 st(4)
-ttyS(4)
 tty(4)
+ttyS(4)
 vcs(4)
 veth(4)
 wavelan(4)
@@ -944,23 +944,23 @@ acct(5)
 charmap(5)
 core(5)
 dir_colors(5)
-elf(5)
+ELF(5)
 erofs(5)
 filesystems(5)
 ftpusers(5)
 gai.conf(5)
 group(5)
+host.conf(5)
 hosts(5)
 hosts.equiv(5)
-host.conf(5)
 issue(5)
 locale(5)
 motd(5)
 networks(5)
 nologin(5)
 nscd.conf(5)
-nsswitch.conf(5)
 nss(5)
+nsswitch.conf(5)
 passwd(5)
 proc(5)
 protocols(5)
@@ -980,15 +980,15 @@ utmp(5)
 intro(6)
 intro(7)
 address_families(7)
-aio(7)
-armscii-8(7)
+AIO(7)
+ARMSCII-8(7)
 arp(7)
 ascii(7)
 attributes(7)
-bootparam(7)
 boot(7)
-bpf-helpers(7)
-capabilities(7)
+bootparam(7)
+BPF-HELPERS(7)
+Capabilities(7)
 cgroup_namespaces(7)
 cgroups(7)
 charsets(7)
@@ -1010,34 +1010,34 @@ hostname(7)
 icmp(7)
 inode(7)
 inotify(7)
+ip(7)
 ipc_namespaces(7)
 ipv6(7)
-ip(7)
-iso_8859-1(7)
-iso_8859-2(7)
-iso_8859-3(7)
-iso_8859-4(7)
-iso_8859-5(7)
-iso_8859-6(7)
-iso_8859-7(7)
-iso_8859-8(7)
-iso_8859-9(7)
-iso_8859-10(7)
-iso_8859-11(7)
-iso_8859-13(7)
-iso_8859-14(7)
-iso_8859-15(7)
-iso_8859-16(7)
+ISO_8859-1(7)
+ISO_8859-10(7)
+ISO_8859-11(7)
+ISO_8859-13(7)
+ISO_8859-14(7)
+ISO_8859-15(7)
+ISO_8859-16(7)
+ISO_8859-2(7)
+ISO_8859-3(7)
+ISO_8859-4(7)
+ISO_8859-5(7)
+ISO_8859-6(7)
+ISO_8859-7(7)
+ISO_8859-8(7)
+ISO_8859-9(7)
 kernel_lockdown(7)
 keyrings(7)
-koi8-r(7)
-koi8-u(7)
-landlock(7)
+KOI8-R(7)
+KOI8-U(7)
+Landlock(7)
 libc(7)
 locale(7)
 mailaddr(7)
-man-pages(7)
 man(7)
+man-pages(7)
 math_error(7)
 mount_namespaces(7)
 mq_overview(7)
@@ -1062,48 +1062,48 @@ queue(7)
 random(7)
 raw(7)
 regex(7)
-rtld-audit(7)
+RTLD-AUDIT(7)
 rtnetlink(7)
 sched(7)
 sem_overview(7)
 session-keyring(7)
 shm_overview(7)
 sigevent(7)
-signal-safety(7)
 signal(7)
+signal-safety(7)
 sock_diag(7)
 socket(7)
 spufs(7)
 standards(7)
 string_copying(7)
-suffixes(7)
+SUFFIXES(7)
 symlink(7)
 system_data_types(7)
 sysvipc(7)
 tcp(7)
 termio(7)
 thread-keyring(7)
-time_namespaces(7)
 time(7)
-udplite(7)
+time_namespaces(7)
 udp(7)
+udplite(7)
 unicode(7)
 units(7)
-unix(7)
+UNIX(7)
 uri(7)
-user-keyring(7)
 user_namespaces(7)
+user-keyring(7)
 user-session-keyring(7)
-utf-8(7)
+UTF-8(7)
 uts_namespaces(7)
-vdso(7)
+vDSO(7)
 vsock(7)
 x25(7)
 xattr(7)
 intro(8)
 iconvconfig(8)
-ldconfig(8)
 ld.so(8)
+ldconfig(8)
 nscd(8)
 sln(8)
 tzselect(8)

[-- Attachment #3: blm4-perl-order.log --]
[-- Type: text/plain, Size: 13683 bytes --]

intro(1)
getent(1)
iconv(1)
ldd(1)
locale(1)
localedef(1)
memusage(1)
memusagestat(1)
mtrace(1)
pldd(1)
sprof(1)
time(1)
intro(2)
accept(2)
access(2)
acct(2)
add_key(2)
adjtimex(2)
alarm(2)
alloc_hugepages(2)
arch_prctl(2)
bdflush(2)
bind(2)
bpf(2)
brk(2)
cacheflush(2)
capget(2)
chdir(2)
chmod(2)
chown(2)
chroot(2)
clock_getres(2)
clock_nanosleep(2)
clone(2)
close(2)
close_range(2)
connect(2)
copy_file_range(2)
create_module(2)
delete_module(2)
dup(2)
epoll_create(2)
epoll_ctl(2)
epoll_wait(2)
eventfd(2)
execve(2)
execveat(2)
_exit(2)
exit_group(2)
fallocate(2)
fanotify_init(2)
fanotify_mark(2)
fcntl(2)
flock(2)
fork(2)
fsync(2)
futex(2)
futimesat(2)
get_kernel_syms(2)
get_mempolicy(2)
get_robust_list(2)
getcpu(2)
getdents(2)
getdomainname(2)
getgid(2)
getgroups(2)
gethostname(2)
getitimer(2)
getpagesize(2)
getpeername(2)
getpid(2)
getpriority(2)
getrandom(2)
getresuid(2)
getrlimit(2)
getrusage(2)
getsid(2)
getsockname(2)
getsockopt(2)
gettid(2)
gettimeofday(2)
getuid(2)
getunwind(2)
getxattr(2)
idle(2)
init_module(2)
inotify_add_watch(2)
inotify_init(2)
inotify_rm_watch(2)
io_cancel(2)
io_destroy(2)
io_getevents(2)
io_setup(2)
io_submit(2)
ioctl(2)
ioctl_console(2)
ioctl_fat(2)
ioctl_ficlonerange(2)
ioctl_fideduperange(2)
ioctl_fslabel(2)
ioctl_getfsmap(2)
ioctl_iflags(2)
ioctl_ns(2)
ioctl_pipe(2)
ioctl_tty(2)
ioctl_userfaultfd(2)
ioperm(2)
iopl(2)
ioprio_set(2)
ipc(2)
kcmp(2)
kexec_load(2)
keyctl(2)
kill(2)
landlock_add_rule(2)
landlock_create_ruleset(2)
landlock_restrict_self(2)
link(2)
listen(2)
listxattr(2)
_llseek(2)
lookup_dcookie(2)
lseek(2)
madvise(2)
mbind(2)
membarrier(2)
memfd_create(2)
memfd_secret(2)
migrate_pages(2)
mincore(2)
mkdir(2)
mknod(2)
mlock(2)
mmap(2)
mmap2(2)
modify_ldt(2)
mount(2)
mount_setattr(2)
move_pages(2)
mprotect(2)
mq_getsetattr(2)
mremap(2)
msgctl(2)
msgget(2)
MSGOP(2)
msync(2)
nanosleep(2)
nfsservctl(2)
nice(2)
open(2)
open_by_handle_at(2)
openat2(2)
outb(2)
pause(2)
pciconfig_read(2)
perf_event_open(2)
perfmonctl(2)
personality(2)
pidfd_getfd(2)
pidfd_open(2)
pidfd_send_signal(2)
pipe(2)
pivot_root(2)
pkey_alloc(2)
poll(2)
posix_fadvise(2)
prctl(2)
pread(2)
process_madvise(2)
process_vm_readv(2)
ptrace(2)
query_module(2)
quotactl(2)
read(2)
readahead(2)
readdir(2)
readlink(2)
readv(2)
reboot(2)
recv(2)
recvmmsg(2)
remap_file_pages(2)
removexattr(2)
rename(2)
request_key(2)
restart_syscall(2)
rmdir(2)
rt_sigqueueinfo(2)
s390_guarded_storage(2)
s390_pci_mmio_write(2)
s390_runtime_instr(2)
s390_sthyi(2)
sched_get_priority_max(2)
sched_rr_get_interval(2)
sched_setaffinity(2)
sched_setattr(2)
sched_setparam(2)
sched_setscheduler(2)
sched_yield(2)
seccomp(2)
seccomp_unotify(2)
select(2)
SELECT_TUT(2)
semctl(2)
semget(2)
semop(2)
send(2)
sendfile(2)
sendmmsg(2)
set_mempolicy(2)
set_thread_area(2)
set_tid_address(2)
seteuid(2)
setfsgid(2)
setfsuid(2)
setgid(2)
setns(2)
setpgid(2)
setresuid(2)
setreuid(2)
setsid(2)
setuid(2)
setup(2)
setxattr(2)
sgetmask(2)
shmctl(2)
shmget(2)
SHMOP(2)
shutdown(2)
sigaction(2)
sigaltstack(2)
signal(2)
signalfd(2)
sigpending(2)
sigprocmask(2)
sigreturn(2)
sigsuspend(2)
sigwaitinfo(2)
socket(2)
socketcall(2)
socketpair(2)
splice(2)
spu_create(2)
spu_run(2)
stat(2)
statfs(2)
statx(2)
stime(2)
subpage_prot(2)
swapon(2)
symlink(2)
sync(2)
sync_file_range(2)
_syscall(2)
syscall(2)
syscalls(2)
sysctl(2)
sysfs(2)
sysinfo(2)
syslog(2)
tee(2)
time(2)
timer_create(2)
timer_delete(2)
timer_getoverrun(2)
timer_settime(2)
timerfd_create(2)
times(2)
tkill(2)
truncate(2)
umask(2)
umount(2)
uname(2)
UNIMPLEMENTED(2)
unlink(2)
unshare(2)
uselib(2)
userfaultfd(2)
ustat(2)
utime(2)
utimensat(2)
vfork(2)
vhangup(2)
vm86(2)
vmsplice(2)
wait(2)
wait4(2)
write(2)
open_how(2type)
intro(3)
a64l(3)
abort(3)
abs(3)
acos(3)
acosh(3)
addseverity(3)
adjtime(3)
aio_cancel(3)
aio_error(3)
aio_fsync(3)
aio_init(3)
aio_read(3)
aio_return(3)
aio_suspend(3)
aio_write(3)
alloca(3)
arc4random(3)
argz_add(3)
asin(3)
asinh(3)
asprintf(3)
assert(3)
assert_perror(3)
atan(3)
atan2(3)
atanh(3)
atexit(3)
atof(3)
atoi(3)
backtrace(3)
basename(3)
bcmp(3)
bcopy(3)
bindresvport(3)
bsd_signal(3)
bsearch(3)
bstring(3)
bswap(3)
btowc(3)
btree(3)
BYTEORDER(3)
bzero(3)
cabs(3)
cacos(3)
cacosh(3)
canonicalize_file_name(3)
carg(3)
casin(3)
casinh(3)
catan(3)
catanh(3)
catgets(3)
catopen(3)
cbrt(3)
ccos(3)
ccosh(3)
ceil(3)
cexp(3)
cexp2(3)
cfree(3)
cimag(3)
CIRCLEQ(3)
clearenv(3)
clock(3)
clock_getcpuclockid(3)
clog(3)
clog10(3)
clog2(3)
closedir(3)
CMSG(3)
confstr(3)
conj(3)
copysign(3)
cos(3)
cosh(3)
cpow(3)
cproj(3)
CPU_SET(3)
creal(3)
crypt(3)
csin(3)
csinh(3)
csqrt(3)
ctan(3)
ctanh(3)
ctermid(3)
ctime(3)
daemon(3)
dbopen(3)
des_crypt(3)
difftime(3)
dirfd(3)
div(3)
dl_iterate_phdr(3)
dladdr(3)
dlerror(3)
dlinfo(3)
dlopen(3)
dlsym(3)
drand48(3)
drand48_r(3)
duplocale(3)
dysize(3)
ecvt(3)
ecvt_r(3)
encrypt(3)
end(3)
endian(3)
envz_add(3)
erf(3)
erfc(3)
err(3)
errno(3)
error(3)
ether_aton(3)
euidaccess(3)
exec(3)
exit(3)
exp(3)
exp10(3)
exp2(3)
expm1(3)
fabs(3)
fclose(3)
fcloseall(3)
fdim(3)
fenv(3)
ferror(3)
fexecve(3)
fflush(3)
ffs(3)
fgetc(3)
fgetgrent(3)
fgetpwent(3)
fgetwc(3)
fgetws(3)
fileno(3)
finite(3)
flockfile(3)
floor(3)
fma(3)
fmax(3)
fmemopen(3)
fmin(3)
fmod(3)
fmtmsg(3)
fnmatch(3)
fopen(3)
fopencookie(3)
fpathconf(3)
fpclassify(3)
fpurge(3)
fputwc(3)
fputws(3)
fread(3)
frexp(3)
fseek(3)
fseeko(3)
ftime(3)
ftok(3)
fts(3)
ftw(3)
futimes(3)
fwide(3)
gamma(3)
gcvt(3)
_Generic(3)
get_nprocs(3)
get_phys_pages(3)
getaddrinfo(3)
getaddrinfo_a(3)
getauxval(3)
getcontext(3)
getcwd(3)
getdate(3)
getdirentries(3)
getdtablesize(3)
getentropy(3)
getenv(3)
getfsent(3)
getgrent(3)
getgrent_r(3)
getgrnam(3)
getgrouplist(3)
gethostbyname(3)
gethostid(3)
getifaddrs(3)
getipnodebyname(3)
getline(3)
getloadavg(3)
getlogin(3)
getmntent(3)
getnameinfo(3)
getnetent(3)
getnetent_r(3)
getopt(3)
getpass(3)
getprotoent(3)
getprotoent_r(3)
getpt(3)
getpw(3)
getpwent(3)
getpwent_r(3)
getpwnam(3)
getrpcent(3)
getrpcent_r(3)
getrpcport(3)
gets(3)
getservent(3)
getservent_r(3)
getspnam(3)
getsubopt(3)
getttyent(3)
getusershell(3)
getutent(3)
getutmp(3)
getw(3)
getwchar(3)
glob(3)
gnu_get_libc_version(3)
grantpt(3)
group_member(3)
gsignal(3)
hash(3)
hsearch(3)
hypot(3)
iconv(3)
iconv_close(3)
iconv_open(3)
if_nameindex(3)
if_nametoindex(3)
ilogb(3)
index(3)
inet(3)
inet_net_pton(3)
inet_ntop(3)
inet_pton(3)
INFINITY(3)
initgroups(3)
insque(3)
isalpha(3)
isatty(3)
isfdtype(3)
isgreater(3)
iswalnum(3)
iswalpha(3)
iswblank(3)
iswcntrl(3)
iswctype(3)
iswdigit(3)
iswgraph(3)
iswlower(3)
iswprint(3)
iswpunct(3)
iswspace(3)
iswupper(3)
iswxdigit(3)
j0(3)
key_setsecret(3)
killpg(3)
ldexp(3)
lgamma(3)
lio_listio(3)
LIST(3)
localeconv(3)
lockf(3)
log(3)
log10(3)
log1p(3)
log2(3)
logb(3)
login(3)
lrint(3)
lround(3)
lsearch(3)
lseek64(3)
makecontext(3)
makedev(3)
mallinfo(3)
malloc(3)
malloc_get_state(3)
__malloc_hook(3)
malloc_info(3)
malloc_stats(3)
malloc_trim(3)
malloc_usable_size(3)
mallopt(3)
matherr(3)
MAX(3)
MB_CUR_MAX(3)
MB_LEN_MAX(3)
mblen(3)
mbrlen(3)
mbrtowc(3)
mbsinit(3)
mbsnrtowcs(3)
mbsrtowcs(3)
mbstowcs(3)
mbtowc(3)
mcheck(3)
memccpy(3)
memchr(3)
memcmp(3)
memcpy(3)
memfrob(3)
memmem(3)
memmove(3)
mempcpy(3)
memset(3)
mkdtemp(3)
mkfifo(3)
mkstemp(3)
mktemp(3)
modf(3)
mpool(3)
mq_close(3)
mq_getattr(3)
mq_notify(3)
mq_open(3)
mq_receive(3)
mq_send(3)
mq_unlink(3)
mtrace(3)
nan(3)
netlink(3)
newlocale(3)
nextafter(3)
nextup(3)
nl_langinfo(3)
ntp_gettime(3)
offsetof(3)
on_exit(3)
open_memstream(3)
opendir(3)
openpty(3)
perror(3)
popen(3)
posix_fallocate(3)
posix_madvise(3)
posix_memalign(3)
posix_openpt(3)
posix_spawn(3)
pow(3)
pow10(3)
powerof2(3)
__ppc_get_timebase(3)
__ppc_set_ppr_med(3)
__ppc_yield(3)
printf(3)
profil(3)
program_invocation_name(3)
psignal(3)
pthread_atfork(3)
pthread_attr_init(3)
pthread_attr_setaffinity_np(3)
pthread_attr_setdetachstate(3)
pthread_attr_setguardsize(3)
pthread_attr_setinheritsched(3)
pthread_attr_setschedparam(3)
pthread_attr_setschedpolicy(3)
pthread_attr_setscope(3)
pthread_attr_setsigmask_np(3)
pthread_attr_setstack(3)
pthread_attr_setstackaddr(3)
pthread_attr_setstacksize(3)
pthread_cancel(3)
pthread_cleanup_push(3)
pthread_cleanup_push_defer_np(3)
pthread_create(3)
pthread_detach(3)
pthread_equal(3)
pthread_exit(3)
pthread_getattr_default_np(3)
pthread_getattr_np(3)
pthread_getcpuclockid(3)
pthread_join(3)
pthread_kill(3)
pthread_kill_other_threads_np(3)
pthread_mutex_consistent(3)
pthread_mutexattr_getpshared(3)
pthread_mutexattr_init(3)
pthread_mutexattr_setrobust(3)
pthread_rwlockattr_setkind_np(3)
pthread_self(3)
pthread_setaffinity_np(3)
pthread_setcancelstate(3)
pthread_setconcurrency(3)
pthread_setname_np(3)
pthread_setschedparam(3)
pthread_setschedprio(3)
pthread_sigmask(3)
pthread_sigqueue(3)
pthread_spin_init(3)
pthread_spin_lock(3)
pthread_testcancel(3)
pthread_tryjoin_np(3)
pthread_yield(3)
ptsname(3)
putenv(3)
putgrent(3)
putpwent(3)
puts(3)
putwchar(3)
qecvt(3)
qsort(3)
raise(3)
rand(3)
random(3)
random_r(3)
rcmd(3)
re_comp(3)
readdir(3)
readdir_r(3)
realpath(3)
recno(3)
regex(3)
remainder(3)
remove(3)
remquo(3)
resolver(3)
rewinddir(3)
rexec(3)
rint(3)
round(3)
roundup(3)
rpc(3)
rpmatch(3)
rtime(3)
rtnetlink(3)
scalb(3)
scalbln(3)
scandir(3)
scanf(3)
sched_getcpu(3)
seekdir(3)
sem_close(3)
sem_destroy(3)
sem_getvalue(3)
sem_init(3)
sem_open(3)
sem_post(3)
sem_unlink(3)
sem_wait(3)
setaliasent(3)
setbuf(3)
setenv(3)
__setfpucw(3)
setjmp(3)
setlocale(3)
setlogmask(3)
setnetgrent(3)
shm_open(3)
siginterrupt(3)
signbit(3)
significand(3)
sigpause(3)
sigqueue(3)
sigset(3)
SIGSETOPS(3)
sigvec(3)
sigwait(3)
sin(3)
sincos(3)
sinh(3)
sleep(3)
SLIST(3)
sockatmark(3)
sqrt(3)
sscanf(3)
STAILQ(3)
static_assert(3)
statvfs(3)
stdarg(3)
stdin(3)
stdio(3)
stdio_ext(3)
stpncpy(3)
strcasecmp(3)
strchr(3)
strcmp(3)
strcoll(3)
strcpy(3)
strdup(3)
strerror(3)
strfmon(3)
strfromd(3)
strfry(3)
strftime(3)
string(3)
strlen(3)
strncat(3)
strnlen(3)
strpbrk(3)
strptime(3)
strsep(3)
strsignal(3)
strspn(3)
strstr(3)
strtod(3)
strtoimax(3)
strtok(3)
strtol(3)
strtoul(3)
strverscmp(3)
strxfrm(3)
swab(3)
sysconf(3)
syslog(3)
system(3)
sysv_signal(3)
TAILQ(3)
tan(3)
tanh(3)
tcgetpgrp(3)
tcgetsid(3)
telldir(3)
tempnam(3)
termios(3)
tgamma(3)
timegm(3)
timeradd(3)
tmpfile(3)
tmpnam(3)
toascii(3)
toupper(3)
towctrans(3)
towlower(3)
towupper(3)
trunc(3)
tsearch(3)
ttyname(3)
ttyslot(3)
tzset(3)
ualarm(3)
ulimit(3)
undocumented(3)
ungetwc(3)
unlocked_stdio(3)
unlockpt(3)
updwtmp(3)
uselocale(3)
usleep(3)
wcpcpy(3)
wcpncpy(3)
wcrtomb(3)
wcscasecmp(3)
wcscat(3)
wcschr(3)
wcscmp(3)
wcscpy(3)
wcscspn(3)
wcsdup(3)
wcslen(3)
wcsncasecmp(3)
wcsncat(3)
wcsncmp(3)
wcsncpy(3)
wcsnlen(3)
wcsnrtombs(3)
wcspbrk(3)
wcsrchr(3)
wcsrtombs(3)
wcsspn(3)
wcsstr(3)
wcstoimax(3)
wcstok(3)
wcstombs(3)
wcswidth(3)
wctob(3)
wctomb(3)
wctrans(3)
wctype(3)
wcwidth(3)
wmemchr(3)
wmemcmp(3)
wmemcpy(3)
wmemmove(3)
wmemset(3)
wordexp(3)
wprintf(3)
XCRYPT(3)
xdr(3)
y0(3)
EOF(3const)
EXIT_SUCCESS(3const)
NULL(3const)
printf.h(3head)
sysexits.h(3head)
aiocb(3type)
blkcnt_t(3type)
blksize_t(3type)
cc_t(3type)
clock_t(3type)
clockid_t(3type)
dev_t(3type)
div_t(3type)
double_t(3type)
epoll_event(3type)
fenv_t(3type)
FILE(3type)
id_t(3type)
intmax_t(3type)
intN_t(3type)
intptr_t(3type)
iovec(3type)
itimerspec(3type)
lconv(3type)
mode_t(3type)
off_t(3type)
ptrdiff_t(3type)
size_t(3type)
sockaddr(3type)
stat(3type)
time_t(3type)
timer_t(3type)
timespec(3type)
timeval(3type)
tm(3type)
va_list(3type)
void(3type)
intro(4)
cciss(4)
console_codes(4)
cpuid(4)
dsp56k(4)
fd(4)
full(4)
fuse(4)
hd(4)
hpsa(4)
initrd(4)
lirc(4)
loop(4)
lp(4)
mem(4)
mouse(4)
msr(4)
null(4)
pts(4)
ram(4)
random(4)
rtc(4)
sd(4)
sk98lin(4)
smartpqi(4)
st(4)
tty(4)
ttyS(4)
vcs(4)
veth(4)
wavelan(4)
intro(5)
acct(5)
charmap(5)
core(5)
dir_colors(5)
ELF(5)
erofs(5)
filesystems(5)
ftpusers(5)
gai.conf(5)
group(5)
host.conf(5)
hosts(5)
hosts.equiv(5)
issue(5)
locale(5)
motd(5)
networks(5)
nologin(5)
nscd.conf(5)
nss(5)
nsswitch.conf(5)
passwd(5)
proc(5)
protocols(5)
repertoiremap(5)
resolv.conf(5)
rpc(5)
securetty(5)
services(5)
shells(5)
slabinfo(5)
sysfs(5)
termcap(5)
tmpfs(5)
ttytype(5)
tzfile(5)
utmp(5)
intro(6)
intro(7)
address_families(7)
AIO(7)
ARMSCII-8(7)
arp(7)
ascii(7)
attributes(7)
boot(7)
bootparam(7)
BPF-HELPERS(7)
Capabilities(7)
cgroup_namespaces(7)
cgroups(7)
charsets(7)
complex(7)
cp1251(7)
cp1252(7)
cpuset(7)
credentials(7)
ddp(7)
environ(7)
epoll(7)
fanotify(7)
feature_test_macros(7)
fifo(7)
futex(7)
glob(7)
hier(7)
hostname(7)
icmp(7)
inode(7)
inotify(7)
ip(7)
ipc_namespaces(7)
ipv6(7)
ISO_8859-1(7)
ISO_8859-10(7)
ISO_8859-11(7)
ISO_8859-13(7)
ISO_8859-14(7)
ISO_8859-15(7)
ISO_8859-16(7)
ISO_8859-2(7)
ISO_8859-3(7)
ISO_8859-4(7)
ISO_8859-5(7)
ISO_8859-6(7)
ISO_8859-7(7)
ISO_8859-8(7)
ISO_8859-9(7)
kernel_lockdown(7)
keyrings(7)
KOI8-R(7)
KOI8-U(7)
Landlock(7)
libc(7)
locale(7)
mailaddr(7)
man(7)
man-pages(7)
math_error(7)
mount_namespaces(7)
mq_overview(7)
namespaces(7)
netdevice(7)
netlink(7)
network_namespaces(7)
nptl(7)
numa(7)
operator(7)
packet(7)
path_resolution(7)
persistent-keyring(7)
pid_namespaces(7)
pipe(7)
pkeys(7)
posixoptions(7)
process-keyring(7)
pthreads(7)
pty(7)
queue(7)
random(7)
raw(7)
regex(7)
RTLD-AUDIT(7)
rtnetlink(7)
sched(7)
sem_overview(7)
session-keyring(7)
shm_overview(7)
sigevent(7)
signal(7)
signal-safety(7)
sock_diag(7)
socket(7)
spufs(7)
standards(7)
string_copying(7)
SUFFIXES(7)
symlink(7)
system_data_types(7)
sysvipc(7)
tcp(7)
termio(7)
thread-keyring(7)
time(7)
time_namespaces(7)
udp(7)
udplite(7)
unicode(7)
units(7)
UNIX(7)
uri(7)
user_namespaces(7)
user-keyring(7)
user-session-keyring(7)
UTF-8(7)
uts_namespaces(7)
vDSO(7)
vsock(7)
x25(7)
xattr(7)
intro(8)
iconvconfig(8)
ld.so(8)
ldconfig(8)
nscd(8)
sln(8)
tzselect(8)
zdump(8)
zic(8)

[-- Attachment #4: official-blm4-perl-order.diff --]
[-- Type: text/plain, Size: 624 bytes --]

--- official-order.log	2023-08-14 17:42:32.058669100 -0600
+++ blm4-perl-order.log	2023-08-20 12:42:49.384053200 -0600
@@ -1036,8 +1036,8 @@ Landlock(7)
 libc(7)
 locale(7)
 mailaddr(7)
-man-pages(7)
 man(7)
+man-pages(7)
 math_error(7)
 mount_namespaces(7)
 mq_overview(7)
@@ -1069,8 +1069,8 @@ sem_overview(7)
 session-keyring(7)
 shm_overview(7)
 sigevent(7)
-signal-safety(7)
 signal(7)
+signal-safety(7)
 sock_diag(7)
 socket(7)
 spufs(7)
@@ -1091,9 +1091,9 @@ unicode(7)
 units(7)
 UNIX(7)
 uri(7)
+user_namespaces(7)
 user-keyring(7)
 user-session-keyring(7)
-user_namespaces(7)
 UTF-8(7)
 uts_namespaces(7)
 vDSO(7)

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Deri,

On 2023-08-21 01:39, Deri wrote:
> Hi Brian,
> 
> I have created the tar files again with the latest sort.
> 
> Both are intended to be used with groff 1.23.0, but the plus version includes 
> the latest gropdf, so produces more compact output. It also has the narrower 
> gap between the heading on the intro(1) page, I have not investigated the 
> reason yet!
> 
> Also I have a small bone to pick with your "official" sort order - it's not 
> consistent. Most people expect a short word like "cat" to appear before a word 
> like "catatonic", and we see "hosts" does appear before "hosts.equiv", so why 
> does "man" come after "man-pages"! I've also strayed from the official sort 
> order in the 6.05.01 pdf by arranging the latin and iso character code pages 
> in proper numerical order so "latin10" comes after "latin9" rather than 
> following "latin1". I hope this makes sense.

Is "official" the Book for 6.5.1?  Or is it the scripts/sortman in git HEAD?

I've found that scripts/sortman had this problem that you report, and fixed it:

commit a04e93998bebba77ac799dd89c11042c25f2e2d2 (HEAD -> master, korg/master, alx/main, main)
Author: Alejandro Colomar <alx@kernel.org>
Date:   Mon Aug 21 23:55:18 2023 +0200

    scripts/sortman: Sort 'cat' before 'catatonic'
    
    Reported-by: Deri James <deri@chuzzlewit.myzen.co.uk>
    Cc: Brian Inglis <Brian.Inglis@Shaw.ca>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>

diff --git a/scripts/sortman b/scripts/sortman
index 546a7943d..a8f70bab5 100755
--- a/scripts/sortman
+++ b/scripts/sortman
@@ -7,8 +7,9 @@ sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
 | sed -E '/\/intro./! s/.*\.([[:digit:]])\>/\11\t&/' \
 | sed -E '/\/intro./! s/.*\.([[:digit:]])([[:alpha:]][[:alnum:]]*\>)/\12.\2\t&/' \
 | sed -E '            s/\t(.*)/&\n\1/' \
+| sed -E '/\t/        s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//' \
 | sed -E '/\t/        s/\/[_-]*/\//g' \
 | sed -E '/\t/        s/[_-]/_/g' \
 | sed -E '/\t/        {N;s/\n/\t/;}' \
-| sort -fV \
+| sort -fV -k1,2 \
 | cut -f3;


$ ./scripts/sortman << __EOF__
man7/cat.7
man7/catatonic.7
man7/cat_or_dog.7
man7/cat_alike.7
man7/hosts.7
man7/hosts.equiv.7
man7/intro.7
__EOF__
man7/intro.7
man7/cat.7
man7/catatonic.7
man7/cat_alike.7
man7/cat_or_dog.7
man7/hosts.7
man7/hosts.equiv.7

Is this order a good one?  Should maybe cat_alike go right after cat?

Cheers,
Alex

[Hopefully, this email should already be signed; I've recovered my keys.]

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Deri]

On Monday, 21 August 2023 23:02:35 BST Alejandro Colomar wrote:
> Hi Deri,
> 
> On 2023-08-21 01:39, Deri wrote:
> > Hi Brian,
> > 
> > I have created the tar files again with the latest sort.
> > 
> > Both are intended to be used with groff 1.23.0, but the plus version
> > includes the latest gropdf, so produces more compact output. It also has
> > the narrower gap between the heading on the intro(1) page, I have not
> > investigated the reason yet!
> > 
> > Also I have a small bone to pick with your "official" sort order - it's
> > not
> > consistent. Most people expect a short word like "cat" to appear before a
> > word like "catatonic", and we see "hosts" does appear before
> > "hosts.equiv", so why does "man" come after "man-pages"! I've also
> > strayed from the official sort order in the 6.05.01 pdf by arranging the
> > latin and iso character code pages in proper numerical order so "latin10"
> > comes after "latin9" rather than following "latin1". I hope this makes
> > sense.
> 
> Is "official" the Book for 6.5.1?  Or is it the scripts/sortman in git HEAD?

Hi Alex,

I have not a clue, at different times it seems to change! I've had various 
diffs from Brian. I think he wanted me to use rpmvercmp for sorting, seemed a 
bit overkill. You've got a script called sortman, which I don't use, but I 
suppose is part of your work when you retire my script and replace it with 
your own.

So I don't think I'm the person to ask.

Cheers 

Deri

> I've found that scripts/sortman had this problem that you report, and fixed
> it:

> 
> Is this order a good one?  Should maybe cat_alike go right after cat?
> 
> Cheers,
> Alex
> 
> [Hopefully, this email should already be signed; I've recovered my keys.]

Re: No 6.05/.01 pdf book available

[Brian Inglis]

On 2023-08-21 16:02, Alejandro Colomar wrote:
> Hi Deri,
> 
> On 2023-08-21 01:39, Deri wrote:
>> Hi Brian,
>>
>> I have created the tar files again with the latest sort.
>>
>> Both are intended to be used with groff 1.23.0, but the plus version includes
>> the latest gropdf, so produces more compact output. It also has the narrower
>> gap between the heading on the intro(1) page, I have not investigated the
>> reason yet!
>>
>> Also I have a small bone to pick with your "official" sort order - it's not
>> consistent. Most people expect a short word like "cat" to appear before a word
>> like "catatonic", and we see "hosts" does appear before "hosts.equiv", so why
>> does "man" come after "man-pages"! I've also strayed from the official sort
>> order in the 6.05.01 pdf by arranging the latin and iso character code pages
>> in proper numerical order so "latin10" comes after "latin9" rather than
>> following "latin1". I hope this makes sense.
> 
> Is "official" the Book for 6.5.1?  Or is it the scripts/sortman in git HEAD?

Yes - the latest official distributed version uniq page heads;
sortman-no-aliases is your uniq page heads excluding pages aliases;
rpmvercmp and versioncmp are the perl modules providing those functions;
check out the attched diffs in the last couple of emails to see the differnces 
in the orders, and which one you think matches your expectations.

> I've found that scripts/sortman had this problem that you report, and fixed it:

> $ ./scripts/sortman << __EOF__
> man7/cat.7
> man7/catatonic.7
> man7/cat_or_dog.7
> man7/cat_alike.7
> man7/hosts.7
> man7/hosts.equiv.7
> man7/intro.7
> __EOF__
> man7/intro.7
> man7/cat.7
> man7/catatonic.7
> man7/cat_alike.7
> man7/cat_or_dog.7
> man7/hosts.7
> man7/hosts.equiv.7
> 
> Is this order a good one?  Should maybe cat_alike go right after cat?

I am in favour of all punctuation being treated as word spaces and sorting
"cat ..." before "cat..." but find the real orders more evocative and easier to 
decide about than examples.

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Brian,

On 2023-08-22 01:45, Brian Inglis wrote:
> I am in favour of all punctuation being treated as word spaces and sorting
> "cat ..." before "cat..." but find the real orders more evocative and easier to 
> decide about than examples.

Here's an excerpt of how treating - and _ as spaces looks like.  I think
it's a reasonable order.  Should I apply that diff?

Cheers,
Alex

$ git diff
diff --git a/scripts/sortman b/scripts/sortman
index a8f70bab5..6d1d92f09 100755
--- a/scripts/sortman
+++ b/scripts/sortman
@@ -9,7 +9,7 @@ sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
 | sed -E '            s/\t(.*)/&\n\1/' \
 | sed -E '/\t/        s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//' \
 | sed -E '/\t/        s/\/[_-]*/\//g' \
-| sed -E '/\t/        s/[_-]/_/g' \
+| sed -E '/\t/        s/[_-]/ /g' \
 | sed -E '/\t/        {N;s/\n/\t/;}' \
 | sort -fV -k1,2 \
 | cut -f3;
$ touch man8/ld-z.8
$ touch man8/ld.8
$ find man8 | ./scripts/sortman 
man8/intro.8
man8/iconvconfig.8
man8/ld.8
man8/ld-linux.8
man8/ld-linux.so.8
man8/ld-z.8
man8/ld.so.8
man8/ldconfig.8
man8/nscd.8
man8/sln.8
man8/tzselect.8
man8/zdump.8
man8/zic.8
man8


> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: No 6.05/.01 pdf book available

[Brian Inglis]

On 2023-08-28 06:17, Alejandro Colomar wrote:
> Hi Brian,
> 
> On 2023-08-22 01:45, Brian Inglis wrote:
>> I am in favour of all punctuation being treated as word spaces and sorting
>> "cat ..." before "cat..." but find the real orders more evocative and easier to
>> decide about than examples.
> 
> Here's an excerpt of how treating - and _ as spaces looks like.  I think
> it's a reasonable order.  Should I apply that diff?
> 
> Cheers,
> Alex
> 
> $ git diff
> diff --git a/scripts/sortman b/scripts/sortman
> index a8f70bab5..6d1d92f09 100755
> --- a/scripts/sortman
> +++ b/scripts/sortman
> @@ -9,7 +9,7 @@ sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
>   | sed -E '            s/\t(.*)/&\n\1/' \
>   | sed -E '/\t/        s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//' \
>   | sed -E '/\t/        s/\/[_-]*/\//g' \
> -| sed -E '/\t/        s/[_-]/_/g' \
> +| sed -E '/\t/        s/[_-]/ /g' \
>   | sed -E '/\t/        {N;s/\n/\t/;}' \
>   | sort -fV -k1,2 \
>   | cut -f3;
> $ touch man8/ld-z.8
> $ touch man8/ld.8
> $ find man8 | ./scripts/sortman
> man8/intro.8
> man8/iconvconfig.8
> man8/ld.8
> man8/ld-linux.8
> man8/ld-linux.so.8
> man8/ld-z.8
> man8/ld.so.8
> man8/ldconfig.8
> man8/nscd.8
> man8/sln.8
> man8/tzselect.8
> man8/zdump.8
> man8/zic.8
> man8

Looks better, but should your sort *key* field instance also drop the section 
suffix (already in prefix) and also treat "." as space?
Where would you expect to see ld.so?

Also, in `sed`, instead of cloning the line, at the start of a series of 
executions, make them all into a single inline command script, start with `h` to 
*hold* the input line, and end with `G` instead of `N` to append '\n' then the 
held line, convert to `\t`, drop the braces, and you can skip the then redundant 
tests, something like the following should get you close (tried it earlier, now 
sadly already gone from history):

| sed -E '
	h
	/\/intro./  s/.*\.([[:digit:]])/\10\t&/
	s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//
	s/\/[_-]*/\//g
	s/[_-]/_/g
	s/[_-]/ /g
	G
	s/\n/\t/
	' \
| ...

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: No 6.05/.01 pdf book available

[Alejandro Colomar]

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

Hi Brian,

On 2023-08-28 20:24, Brian Inglis wrote:
> On 2023-08-28 06:17, Alejandro Colomar wrote:
>> Hi Brian,
>>
>> On 2023-08-22 01:45, Brian Inglis wrote:
>>> I am in favour of all punctuation being treated as word spaces and sorting
>>> "cat ..." before "cat..." but find the real orders more evocative and easier to
>>> decide about than examples.
>>
>> Here's an excerpt of how treating - and _ as spaces looks like.  I think
>> it's a reasonable order.  Should I apply that diff?
>>
>> Cheers,
>> Alex
>>
>> $ git diff
>> diff --git a/scripts/sortman b/scripts/sortman
>> index a8f70bab5..6d1d92f09 100755
>> --- a/scripts/sortman
>> +++ b/scripts/sortman
>> @@ -9,7 +9,7 @@ sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
>>   | sed -E '            s/\t(.*)/&\n\1/' \
>>   | sed -E '/\t/        s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//' \
>>   | sed -E '/\t/        s/\/[_-]*/\//g' \
>> -| sed -E '/\t/        s/[_-]/_/g' \
>> +| sed -E '/\t/        s/[_-]/ /g' \
>>   | sed -E '/\t/        {N;s/\n/\t/;}' \
>>   | sort -fV -k1,2 \
>>   | cut -f3;
>> $ touch man8/ld-z.8
>> $ touch man8/ld.8
>> $ find man8 | ./scripts/sortman
>> man8/intro.8
>> man8/iconvconfig.8
>> man8/ld.8
>> man8/ld-linux.8
>> man8/ld-linux.so.8
>> man8/ld-z.8
>> man8/ld.so.8
>> man8/ldconfig.8
>> man8/nscd.8
>> man8/sln.8
>> man8/tzselect.8
>> man8/zdump.8
>> man8/zic.8
>> man8
> 
> Looks better,

Thanks, I've applied and pushed the patch.

> but should your sort *key* field instance also drop the section 
> suffix (already in prefix)

It is already dropped.  Am I understanding it correctly?
Here's a debug patch to view the sort key field:

diff --git a/scripts/sortman b/scripts/sortman
index 6d1d92f09..e690f23ea 100755
--- a/scripts/sortman
+++ b/scripts/sortman
@@ -12,4 +12,5 @@ sed   -E '/\/intro./  s/.*\.([[:digit:]])/\10\t&/' \
 | sed -E '/\t/        s/[_-]/ /g' \
 | sed -E '/\t/        {N;s/\n/\t/;}' \
 | sort -fV -k1,2 \
+| tee /dev/tty \
 | cut -f3;


And here's how it looks with man8 (plus the dummy files):


$ find man8 -type f | ./scripts/sortman
80	man8/intro	man8/intro.8
81	man8/iconvconfig	man8/iconvconfig.8
81	man8/ld	man8/ld.8
81	man8/ld linux	man8/ld-linux.8
81	man8/ld linux.so	man8/ld-linux.so.8
81	man8/ld z	man8/ld-z.8
81	man8/ld.so	man8/ld.so.8
81	man8/ldconfig	man8/ldconfig.8
81	man8/nscd	man8/nscd.8
81	man8/sln	man8/sln.8
81	man8/tzselect	man8/tzselect.8
81	man8/zdump	man8/zdump.8
81	man8/zic	man8/zic.8
man8/intro.8
man8/iconvconfig.8
man8/ld.8
man8/ld-linux.8
man8/ld-linux.so.8
man8/ld-z.8
man8/ld.so.8
man8/ldconfig.8
man8/nscd.8
man8/sln.8
man8/tzselect.8
man8/zdump.8
man8/zic.8


There are no suffixes in the second field.

> and also treat "." as space?

I'had been thinking about it, but didn't make an opinion.
Since they are rare, I think making them stand out a little bit
by having a special order rather than just being mixed with the
underscores would make sense.  But I'm open to change that.

> Where would you expect to see ld.so?

Not sure.

> 
> Also, in `sed`, instead of cloning the line, at the start of a series of 
> executions, make them all into a single inline command script, start with `h` to 
> *hold* the input line, and end with `G` instead of `N` to append '\n' then the 
> held line, convert to `\t`, drop the braces, and you can skip the then redundant 
> tests, something like the following should get you close (tried it earlier, now 
> sadly already gone from history):
> 
> | sed -E '
> 	h
> 	/\/intro./  s/.*\.([[:digit:]])/\10\t&/
> 	s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//
> 	s/\/[_-]*/\//g
> 	s/[_-]/_/g
> 	s/[_-]/ /g
> 	G
> 	s/\n/\t/
> 	' \
> | ...

I prefer having many one-liners for a few reasons:

-  Not everybody knows what h and G do.  I did't.  And I will
   soon forget.  In contrast, my implementation has nothing
   rare in it.

-  I can inspect the contents at each of the steps easily by
   adding a line with `| tee /dev/tty \`, for debug purposes.

In general, I avoid having large scripts in other languages.
I prefer piping many one-liners, even if it might be less
efficient (but it uses more cores, so it might end up being
faster; I've seen such things happen already many times).

Cheers,
Alex 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: groff features for hyperlinked man pages (was: No 6.05/.01 pdf book available)

[Alejandro Colomar]

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

Hi Branden,

Sorry for the delay.  I've been learning neomutt(1) and mbsync(1)
recently, which took a lot of time from me.  Now it all stabilized.
Finally, I'm able to grep(1) my mail.  :)

On Fri, Aug 18, 2023 at 11:37:32PM -0500, G. Branden Robinson wrote:
> > I'd expect that the hyperlinking ability should be modifyable with
> > groff(1) --I don't care at what level of the pipeline--, similar to
> > how it was modifiable with man2html(1).  But the source code shouldn't
> > know about it.
> 
> Please point me to which man2html(1) implementation you mean.[3]  I can
> have a look and evaluate.

The only one I've used is Debian's, which probably was aeb's.

Cheers,
Alex

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