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

Alejandro Colomar
2024-03-12T14:12:56Z

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

On Tue, Mar 12, 2024 at 12:47:48PM +0000, Deri wrote:
> Hi Alex,

Hi Deri,

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

Sorry, I didn't know how to do the equivalent of `apt-get build-dep` in
other systems. :)

There seems to be some equivalent for dnf(1)-based systems:
<https://unix.stackexchange.com/questions/326047/does-dnf-have-an-equivalent-to-apts-build-dep>

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

Hmm, interesting thing to try! I've tried it too, and the bookmarks for
the in-page sections (e.g., DESCRIPTION, or rather ОПИСАНИЕ) appear with
no name (or maybe it's a locale problem in my system?). See attached
PDF.

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

> diff --git a/scripts/LinuxManBook/prepare.pl b/scripts/LinuxManBook/prepare.pl

Thanks! I've applied it, with the following commit:

Author: Deri <deri@chuzzlewit.myzen.co.uk>
AuthorDate: Tue Mar 12 14:46:24 2024 +0100
Commit: Alejandro Colomar <alx@kernel.org>
CommitDate: Tue Mar 12 15:09:59 2024 +0100

scripts/LinuxManBook/prepare.pl: Support some autogenerated pages from other projects

And remove a warning about an experimental perl feature, by using a
while instead of a for loop.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

Have a lovely day!
Alex

> 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";
>

--
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #1.2: ru.pdf --]
[-- Type: application/pdf, Size: 217865 bytes --]