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

[Alejandro Colomar <alx@kernel.org>]

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

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