Re: Bogus index in man-pages book from other projects

Deri
2024-03-12T13:08:57Z

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

On Saturday, 9 March 2024 16:21:40 GMT Alejandro Colomar wrote:
> Hi Deri!
>
> I've tried to build a man-pages book of the shadow project, using the
> Linux man-pages build system (which calls your script). The text
> contents look good, but the index seems to be bogus, and man-page
> references don't work (it results in just text).

Hi Alex,

This is due to the .TH line not being recognised because its parameters were quoted, regex
adjusted to recognise with or without quotes.

The missing intra-page references (i.e. in See Also) were not recognised because they did
not use .MR or .BR, instead they used "\fBcommand\fR(n)", experimentally I have added
this pattern to recognise as a potential link.

> I only see in the index the names of the pages that are aliases. None
> of the actual pages (their in-page sections are top-level entries in the
> index).
>
> To reproduce it,
>
> ```sh
> git clone -b shadow
> http://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/ git
> clone https://github.com/shadow-maint/shadow
> mkdir build
> cd build
> sudo apt-get build-dep shadow
> ../shadow/autogen.sh
> make -j4
> cd ../man-pages
> make build-book MANDIR=../build/man
> open .tmp/man/man-pages.pdf
> ```

This only works on debian type systems (apt-get), so I had to use my raspberrypi5 instead
of my desktop.

I tested it using MANDIR=../man-pages/ru as well, some of it is cyrillic!

Another reason .TH was not being recognised is the incorrect usage of \& before a full stop
in the command, i.e. login\&.defs. This is not necessary because it will not be recognised as
an end of sentence, so I removed it.

Cheers

Deri

> The `make build-book` step results in the following warning, which may
> be relevant:
>
> $ make build-book MANDIR=../build/man
> MKDIR .tmp/man/
> Build .tmp/man/man-pages.pdf
> for my (...) is experimental at ./scripts/LinuxManBook/prepare.pl line 62.
> pdf.tmac:chage.1:29: warning: adjusted level 3 bookmark; should be <= 1
> pdf.tmac:chage.1:31: warning: adjusted level 3 bookmark; should be <= 2
>
>
> Would you mind having a look at this?
>
> Have a lovely day!
> Alex

[-- Attachment #1.2: Type: text/html, Size: 6160 bytes --]

[-- Attachment #2: shadow.patch --]
[-- Type: text/x-patch, Size: 1925 bytes --]

diff --git a/scripts/LinuxManBook/prepare.pl b/scripts/LinuxManBook/prepare.pl
index bb8667dd8..bfacb3648 100755
--- a/scripts/LinuxManBook/prepare.pl
+++ b/scripts/LinuxManBook/prepare.pl
@@ -59,7 +59,7 @@ foreach my $al (`grep -E '^\\.so' $dir/man*/*`)
$aliases{$1}=$2;
}

-foreach my ($k,$v) (%aliases)
+while (my ($k,$v)=each %aliases)
{
while (exists($aliases{$v})) {
$v=$aliases{$v};
@@ -98,6 +98,15 @@ sub BuildPage

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

+ # if new section add top level bookmark
+
+ if ($sec ne $Section) {
+ print ".nr PDFOUTLINE.FOLDLEVEL 1\n";
+ print ".pdfbookmark 1 $Sections{$sec}\n";
+ print ".nr PDFOUTLINE.FOLDLEVEL 2\n";
+ $Section=$sec;
+ }
+
if (exists($aliases{$bkmark})) {
print ".eo\n.device ps:exec [/Dest /$aliases{$bkmark} /Title ($title) /Level 2 /OUT pdfmark\n.ec\n.fl\n";
return;
@@ -123,7 +132,7 @@ sub BuildPage

s/\\-/-/g if /^\.[BM]R\s+/;

- if (m/^\.BR\s+([-\w\\.]+)\s+\((.+?)\)(.*)/ or m/^\.MR\s+([-\w\\.]+)\s+(\w+)\s+(.*)/) {
+ if (m/^\.BR\s+([-\w\\.]+)\s+\((.+?)\)(.*)/ or m/^\.MR\s+([-\w\\.]+)\s+(\w+)\s+(.*)/ or m/^\\fB([-\w\\.]+)\\fR\((.+?)\)(.*)$/) {
my $bkmark="$1";
my $sec=$2;
my $after=$3;
@@ -135,7 +144,7 @@ sub BuildPage
my $dest=$files{"${bkmark}.$sec"}->[1];
$_=".pdfhref L -D \"$dest\" -A \"$after\" -- \\fI$bkmark\\fP($sec)";
} else {
- $_=".IR ".substr($_,4);
+ $_=".IR $bkmark ($sec)\\c\n$after";
}
}

@@ -161,16 +170,9 @@ sub BuildPage
s/\n\n/\n/g;
}

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

- # if new section add top level bookmark
-
- if ($sec ne $Section) {
- print ".nr PDFOUTLINE.FOLDLEVEL 1\n";
- print ".pdfbookmark 1 $Sections{$sec}\n";
- print ".nr PDFOUTLINE.FOLDLEVEL 2\n";
- $Section=$sec;
- }
+ if (m/^\.TH\s+"?([-\w\\.]+)"?\s+"?(\w+)"?/) {

print "$_\n";

[-- Attachment #3: man-pages.pdf --]
[-- Type: application/pdf, Size: 212913 bytes --]