Problem in prepare.pl (PDF book script) when handling Unix V10 manual pages

Problem in prepare.pl (PDF book script) when handling Unix V10 manual pages

[Alejandro Colomar]

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

Hi Deri,

I tried generating a PDF book from the Unix v10 manual pages, and found
some issues with the Perl script.  I don't understand Perl, as you know,
so I don't know what to do.

I've attached a tarball with the manual pages that I'm trying to handle.
They're slightly modified V10 files, in order to make them slightly more
conventional (e.g., the =.1 page is now called eq.1, and the manx/ dir
and other dirs than didn't have a digit in their names are now divided
into dirs that have one digit after the name (e.g., man1x/, ...)).

The command I'm trying to run is:

	$ make -R build-pdf-book MANDIR=~/Downloads/unix/man/

(Of course, replace that path with wherever you untar the tarball.)

The error I see is a forever loop (or so it seems) with the following
error line:

	Use of uninitialized value $v in exists at /srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/pdf/book/prepare.pl line 67.

Would you mind having a look at it?
In case it matters:

	alx@devuan:~$ groff --version
	GNU groff version 1.23.0.2695-49927
	Copyright (C) 1989-2023 Free Software Foundation, Inc.
	This is free software, distributed under the terms of the GNU General Public
	License, version 3, or any later version, at your option.  There is NO warranty;
	not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

	programs in constructed pipeline:

	GNU grops (groff) version 1.23.0.2695-49927
	GNU troff (groff) version 1.23.0.2695-49927


Have a lovely day!
Alex

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

[-- Attachment #1.2: unix-v10-man.tar.gz --]
[-- Type: application/x-tar-gz, Size: 858926 bytes --]

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

Re: Problem in prepare.pl (PDF book script) when handling Unix V10 manual pages

[Deri]

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

On Thursday, 13 February 2025 16:08:39 GMT Alejandro Colomar wrote:
> Hi Deri,
> 
> I tried generating a PDF book from the Unix v10 manual pages, and found
> some issues with the Perl script.  I don't understand Perl, as you know,
> so I don't know what to do.
> 
> I've attached a tarball with the manual pages that I'm trying to handle.
> They're slightly modified V10 files, in order to make them slightly more
> conventional (e.g., the =.1 page is now called eq.1, and the manx/ dir
> and other dirs than didn't have a digit in their names are now divided
> into dirs that have one digit after the name (e.g., man1x/, ...)).
> 
> The command I'm trying to run is:
> 
> 	$ make -R build-pdf-book MANDIR=~/Downloads/unix/man/
> 
> (Of course, replace that path with wherever you untar the tarball.)
> 
> The error I see is a forever loop (or so it seems) with the following
> error line:
> 
> 	Use of uninitialized value $v in exists at
> /srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/pdf/book/prep
> are.pl line 67.
> 
> Would you mind having a look at it?
> In case it matters:
> 
> 	alx@devuan:~$ groff --version
> 	GNU groff version 1.23.0.2695-49927
> 	Copyright (C) 1989-2023 Free Software Foundation, Inc.
> 	This is free software, distributed under the terms of the GNU General
> Public License, version 3, or any later version, at your option.  There is
> NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
> PURPOSE.
> 
> 	programs in constructed pipeline:
> 
> 	GNU grops (groff) version 1.23.0.2695-49927
> 	GNU troff (groff) version 1.23.0.2695-49927
> 
> 
> Have a lovely day!
> Alex

Hi Alex,

This was caused by nonsense "aliases", see man1w/splitrules.1, and man1b/pins.
1g, which looks like an alias, but is not. This has now been fixed by being 
more tolerant of weird entries which look like aliases.

There are a lot of pages which should have aliases added.

I found some other issues which I have fixed:-

When an alias points to another alias the code was meant to keep looking until 
the real page is found. This affects the recent 6.11 (an example is 
fchown32(2) which has no associated page number in the overview panel, it now 
works properly.

Since the v10 pages are intended to run on a version of troff with a two 
character name limit (I think). Code such as ".ne4" cause a problem for groff, 
which needs ".ne 4" to work (otherwise groff looks for a macro called "ne4" 
and fails. Many of these issues are now corrected.

A strange issue is that if a page contained a "$" character it sent eqn into 
the stratosphere (thinking was dealing with an inline equation), I killed it 
when eqn chewed up over 24gb of memory. I have no idea why, and it is not 
triggered by a single page containing a "$", so it must be triggered by 
something in an earlier man page which triggers it, but changing some "$" to 
"\[Do]" fixed the problem.

One page redefined the ".P" man macro, which then affects all following man 
pages.

One page introduced a string register called "mc" which then masks the groff 
command ".mc" with very strange results .

Font L is used in many entries, no clue what font this is, but I convert to 
font CB. Please change to taste (see lines 130 onwards).

Several pages use lower case macro names, i.e. ".th" rather than ".TH".

I have "fixed" a lot of the problems but there are still many warnings when 
running groff. I have attached two parthes, one for the V10 man pages, and one 
for prepare.pl. You should be able to produce a "useful" book after applying 
these.

If you wish to see the fruits of my labour as a pdf, it is here:-

http://chuzzlewit.co.uk/UnixV10.pdf

Cheers 

Deri


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

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

diff -ru alex-v10b/man/man1b/as80.1 alex-v10/man/man1b/as80.1
--- alex-v10b/man/man1b/as80.1	1982-01-13 01:40:00.000000000 +0000
+++ alex-v10/man/man1b/as80.1	2025-02-17 13:27:09.225671117 +0000
@@ -1,27 +1,27 @@
 .h 1 1 2/3/78
-.th as80
-.sh NAME
+.TH as80
+.SH NAME
 as80 \*- assembler for the 8080 and Z80 microprocessors
-.sh SYNOPSIS
-.bd as80
+.SH SYNOPSIS
+.B as80
 [
-.bd \*-lhzi
+.B \*-lhzi
 ] name ...
-.sh DESCRIPTION
-.it as80
+.SH DESCRIPTION
+.I as80
 assembles the concatenation of the named files.
 The output of the assembly is left on the file
-.bd "80.out".
+.B "80.out".
 It is executable if no errors occurred
 during the assembly,
 and if there were no unresolved external references.
-.s1
+.LP
 The -l option causes as80 to produce a listing
 on the standard output.
-.s1
+.LP
 The -h option causes as80 to produce the output listing
 in hex. Octal is default.
-.s1
+.LP
 Register names:		a,b,c,d,e,h,l,af,bc,de,hl,ix,iy,sp
 .br
 Condition codes:		nz,z,nc,c,po,pe,p,m
@@ -30,15 +30,15 @@
 .br
 			.bss,.bssorg,.byte,.word,.list,
 .br
-.s1
-.s3
-.sh FILES
+.LP
+.LP
+.SH FILES
 as80	the assembler
 .br
 "80.out"
 .br
 OPCODES	the external instruction set
-.sh DIAGNOSTICS
+.SH DIAGNOSTICS
 When
 an input file cannot be read, its name and
 a "can't open" diagnostic is produced and assembly
@@ -47,7 +47,7 @@
 encountered,
 a single-character diagnostic is produced.
 The possible diagnostics are:
-.s3
+.LP
 .ta 3
 \. moving dot backwards
 .br
@@ -73,8 +73,8 @@
 .br
 X	Syntax error
 .br
-.sh BUGS
-.s1
+.SH BUGS
+.LP
 If  .list 1  is ever encountered,
 a listing will start to come out
 whether or not  -l  was selected.
diff -ru alex-v10b/man/man1b/ksh.1 alex-v10/man/man1b/ksh.1
--- alex-v10b/man/man1b/ksh.1	1989-06-05 20:16:39.000000000 +0100
+++ alex-v10/man/man1b/ksh.1	2025-02-13 22:37:11.994677266 +0000
@@ -2,9 +2,9 @@
 .ds CK \|]
 .ds ' \s+4\v@.3m@\'\v@-.3m@\s-4
 .ds ` \s+4\v@.3m@\`\v@-.3m@\s-4
-.de P
-.br
-..
+.\" .de P
+.\" .br
+.\" ..
 .TH KSH 1
 .SH NAME
 ksh \- Korn shell, the not standard command programming language
diff -ru alex-v10b/man/man1b/ld80.1 alex-v10/man/man1b/ld80.1
--- alex-v10b/man/man1b/ld80.1	1982-01-13 01:40:01.000000000 +0000
+++ alex-v10/man/man1b/ld80.1	2025-02-17 13:32:33.675178737 +0000
@@ -1,35 +1,35 @@
-.th "ld80" 1 1/2/78
-.sh NAME
+.TH "ld80" 1 1/2/78
+.SH NAME
 "ld80"  \*-  link editor for the 8080/Z80 load moduals.
-.sh SYNOPSIS
-.bd "ld80"
+.SH SYNOPSIS
+.B "ld80"
 [
-.bd \*-ultdb
+.B \*-ultdb
 ] name ...
-.sh DESCRIPTION
-.it "ld80"
+.SH DESCRIPTION
+.I "ld80"
 combines several
 object programs into one; resolves external
 references; and searches libraries.
 In the simplest case the names of several object
 programs are given, and
-.it "ld80"
+.I "ld80"
 combines them, producing
 an object module which can be either executed or
 become the input for a further
-.it "ld80"
+.I "ld80"
 run.
 The output of
-.it "ld80"
+.I "ld80"
 is left on
-.bd "80.out".
+.B "80.out".
 This file is made executable
 only if no errors occurred during the load.
-.s3
+.LP
 The argument routines are concatenated in the order
 specified.  The entry point of the output is the
 beginning of the first routine.
-.s3
+.LP
 If any argument is a library, it is searched exactly once
 at the point it is encountered in the argument list.
 Only those routines defining an unresolved external
@@ -40,14 +40,14 @@
 referencing routine in the library.
 Thus the order of programs within libraries
 is important.
-.s3
-.it "ld80"
+.LP
+.I "ld80"
 understands several flag arguments which are written
 preceded by a `\*-'.
 Except for \fB\*-l\fR,
 they should appear before the file names.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\*-b\fR	This
 option is used to provide an absolute origin for the bss segment
 of the resultant "80.out".
@@ -58,8 +58,8 @@
 segment.
 Use of this option will cause the relocation information to
 be suppressed from the output.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\*-d\fR	This
 option is used to provide an absolute origin for the data segment
 of the resultant "80.out".
@@ -70,15 +70,15 @@
 after the text.
 Use of this option will cause the relocation information to
 be suppressed from the output.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\*-u\fR	take the following argument as a symbol and enter
 it as undefined in the symbol table.  This is useful
 for loading wholly from a library, since initially the symbol
 table is empty and an unresolved reference is needed
 to force the loading of the first routine.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\*-t\fR	This
 option is used to provide an absolute origin for the text segment
 of the resultant "80.out".
@@ -88,8 +88,8 @@
 The default origin is 0.
 Use of this option will cause the relocation information to
 be suppressed from the output.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\*-l\fR	This
 option is an abbreviation for a library name.
 \fB\*-l\fR
@@ -103,18 +103,18 @@
 is significant.
 .i0
 .dt
-.sh FILES
+.SH FILES
 /usr/z8080/lib/z80	libraries
 .br
 "80.out"		 output file
-.sh "SEE ALSO"
+.SH "SEE ALSO"
 "as80" (I), ar (I)
-.sh BUGS
+.SH BUGS
 Most diagnostics are self explanatory.
 The strangest is 'origin - conflict' and
 occurs whenever an origin supplied by the user via
 the -t -d or -b options causes segments to overlap.
 The numbers printed out correspond
 origins and sizes(both in octal) of each resultant segment.
-.bd "80.out"
+.B "80.out"
 is produced.
diff -ru alex-v10b/man/man1b/nm80.1 alex-v10/man/man1b/nm80.1
--- alex-v10b/man/man1b/nm80.1	1982-01-13 01:40:01.000000000 +0000
+++ alex-v10/man/man1b/nm80.1	2025-02-17 13:36:36.879877170 +0000
@@ -1,19 +1,19 @@
-.th NM80 1 03/01/77
-.sh NAME
+.TH NM80 1 03/01/77
+.SH NAME
 nm80  \*-  print name list
-.sh SYNOPSIS
-.bd nm80
+.SH SYNOPSIS
+.B nm80
 [
-.bd \-cnrupgfabdth
+.B \-cnrupgfabdth
 ]
 [ name ]
-.sh DESCRIPTION
+.SH DESCRIPTION
 .it Nm80
 prints the symbol table from the output file of an
 assembler or loader run.
 Each symbol name is preceded by its value (blanks if undefined)
 and one of the letters:
-.s1
+.LP
 \fBU\fR (undefined)
 .br
 \fBA\fR (absolute)
@@ -27,59 +27,59 @@
 \fBF\fR (file name)
 .br
 \fBC\fR (common symbol)
-.s3
+.LP
 If the symbol is local (non-external)
 the type letter is in lower case.
 The output is sorted alphabetically.
-.s3
+.LP
 If no file is given, the symbols in
-.bd 80.out
+.B 80.out
 are listed.
 Absolute symbols have their values printed in octal.
 Non-absolute symbols are assumed to be addresses
 and are printed in a "low byte:high byte" format.
-.s3
+.LP
 Options are:
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-a\fR	list only absolute symbols
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-b\fR	list only bss symbols
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-c\fR	list only C-style external symbols, that is
 those beginning with underscore `\*_'.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-d\fR	list only data symbols
 those beginning with underscore `\*_'.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-f\fR	print only the file names.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-g\fR	print only global (external) symbols
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-n\fR	sort by value instead of by name
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-p\fR	don't sort; print in symbol-table order
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-r\fR	sort in reverse order
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-t\fR	list only text symbols
 those beginning with underscore `\*_'.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-u\fR	print only undefined symbols.
-.s3
-.lp +4 4
+.LP
+.LP +4 4
 \fB\-h\fR	print output in hex.
 .i0
-.sh FILES
+.SH FILES
 80.out
-.sh BUGS
+.SH BUGS
diff -ru alex-v10b/man/man1b/size80.1 alex-v10/man/man1b/size80.1
--- alex-v10b/man/man1b/size80.1	1982-01-13 01:40:02.000000000 +0000
+++ alex-v10/man/man1b/size80.1	2025-02-17 13:39:14.607646591 +0000
@@ -1,17 +1,17 @@
-.th SIZE80 1 "2/23/77"
-.sh NAME
+.TH SIZE80 1 "2/23/77"
+.SH NAME
 size80 \*- size of an object file for the 8008/8080 or Z80
-.sh SYNOPSIS
-.bd size80
+.SH SYNOPSIS
+.B size80
 [ object ... ]
-.sh DESCRIPTION
-.it Size80
+.SH DESCRIPTION
+.I Size80
 prints the decimal and octal number of bytes
 required by the
 text, data, and bss
 portions
 of each object-file argument.
 If no file is specified,
-.bd 80.out
+.B 80.out
 is used.
-.sh BUGS
+.SH BUGS
diff -ru alex-v10b/man/man1x/mailx.1 alex-v10/man/man1x/mailx.1
--- alex-v10b/man/man1x/mailx.1	1989-12-13 20:56:52.000000000 +0000
+++ alex-v10/man/man1x/mailx.1	2025-02-13 21:58:36.104243216 +0000
@@ -38,7 +38,7 @@
 .ds nu \\f2number\\f1
 .ds ms \\f2message\f1
 .ds sh \\f2shell-command\\f1
-.ds mc \\f2mail-command\\f1
+.ds mC \\f2mail-command\\f1
 .ds dl \\fBdead.letter\\f1
 .ds mr \\f2.mailrc\\f1
 .ds mb \\f2mbox\\f1
@@ -419,20 +419,20 @@
 .Cm ho ld \*(om
 Holds the specified messages in the \*(mx.
 .Cm i f \fBs\f1 | \fBr\f1
-.C "" \*(mcs
+.C "" \*(mCs
 .C el se
-.C "" \*(mcs
+.C "" \*(mCs
 .C en dif
 Conditional execution, where
 .B s
-will execute following \*(mcs, up to an
+will execute following \*(mCs, up to an
 .BR el se
 or
 .BR en dif,
 if the program is in
 send mode, and
 .B r
-causes the \*(mcs to be executed only in
+causes the \*(mCs to be executed only in
 receive mode.
 Useful in the \*(mr file.
 .Cm l ist
@@ -569,7 +569,7 @@
 .PD 0
 .Ti ! \*(sh
 Escape to the shell.
-.Ti : \*(mc
+.Ti : \*(mC
 Perform the command-level request.
 .Ti ?
 Print a summary of tilde escapes.
diff -ru alex-v10b/man/man5b/80.out.5 alex-v10/man/man5b/80.out.5
--- alex-v10b/man/man5b/80.out.5	1982-01-13 01:41:59.000000000 +0000
+++ alex-v10/man/man5b/80.out.5	2025-02-17 13:20:47.393796842 +0000
@@ -1,149 +1,149 @@
-.th "80.out" 5 "March 1,1977"
-.sh NAME
+.TH "80.out" 5 "March 1,1977"
+.SH NAME
 80.out \*- assembler and link editor output
-.sh DESCRIPTION
-.it "80.out"
+.SH DESCRIPTION
+.I "80.out"
 is the output file of the assembler
-.it "as80"
+.I "as80"
 and the link editor
-.it "ld80".
+.I "ld80".
 Both programs make
-.it "80.out"
+.I "80.out"
 executable if there were no
 errors and no unresolved external references.
-.s3
-.it 80.out
+.LP
+.I 80.out
 has five sections:
 header, text, data, relocation information and a symbol table (in that order).
 The last two sections may be empty if the program was loaded with
 the ``\*-b'', ``\*-d'' or ``\*-t'' option of
-.it ld80.
-.s1
+.I ld80.
+.LP
 (Constants beginning with `0' are octal values.)
-.s3
-.it HEADER
-.s3
+.LP
+.I HEADER
+.LP
 The header always contains 040 bytes:
-.lp +10 8
+.LP +10 8
 Address	Contents
-.lp +10 8
+.LP +10 8
 (octal)
-.s1
-.lp +10 8
+.LP
+.LP +10 8
 0-1	Magic number (0413)
-.lp +10 8
+.LP +10 8
 2-3	Size of text segment
-.lp +10 8
+.LP +10 8
 4-5	Size of data segment
-.lp +10 8
+.LP +10 8
 6-7	Size of bss segment
-.lp +10 8
+.LP +10 8
 10-11	Size of symbol table
-.lp +10 8
+.LP +10 8
 12-13	Load origin of text segment
-.lp +10 8
+.LP +10 8
 14-15	Load origin of data segment
-.lp +10 8
+.LP +10 8
 16-20	Load origin of bss segment
-.lp +10 8
+.LP +10 8
 20-21	Size of relocation table
-.lp +10 8
+.LP +10 8
 22-23	A word of flags
-.lp +10 8
+.LP +10 8
 24-37	Padding
-.s3
+.LP
 .i0
 The size of each segment is in bytes.
 The size of the header is not included in any of the other sizes.
-.s3
+.LP
 The flag values are:
-.lp +20 7
+.LP +20 7
 Bit	Meaning
-.lp +20 7
+.LP +20 7
 0	If set, no relocation information is present.
 .i0
-.s3
+.LP
 The start of the text segment in the file is 040,
 the start of the data is (040 + text size),
 the start of the relocation is (040 + text + data size),
 and the start of the symbol table is (040 + text size + data size + relocation size).
-.s3
-.it "RELOCATION INFORMATION"
-.s3
+.LP
+.IP "RELOCATION INFORMATION"
+.LP
 The relocation information (if present)
 occupies one or two bytes for each byte or word of text or data.
 The bits of the relocation word (or byte) are:
-.s3
-.lp +10 8
+.LP
+.LP +10 8
 Bit	Meaning
-.s3
-.lp +10 8
+.LP
+.LP +10 8
 6-15	Symbol number in symbol table for external references.
 The firat symbol is numbered 0.
-.lp +10 8
+.LP +10 8
 5	High-byte flag: If set, the next byte of text or data is to be treated as the high
 order byte of a 16-bit quantity for relocation purposes.
-.lp +10 8
+.LP +10 8
 4	Two-byte flag: If set, the next two bytes of text or data are to be
 treated as a 16-bit quantity for relocation purposes.
-.lp +10 8
+.LP +10 8
 3	External flag: If set, bits 15-6 contain a symbol number, otherwise, only one byte
 of relocation information is present.
-.lp +10 8
+.LP +10 8
 0-2	Segment information:
-.lp +20 5
+.LP +20 5
 0	absolute
-.lp +20 5
+.LP +20 5
 1	text
-.lp +20 5
+.LP +20 5
 2	data
-.lp +20 5
+.LP +20 5
 3	bss
 .i0
-.s3
-.sh "SEE ALSO"
+.LP
+.SH "SEE ALSO"
 "as80" (I), "ld80" (I), "nm80" (I)
-.s3
-.it "SYMBOL TABLE"
-.s1
+.LP
+.SH "SYMBOL TABLE"
+.LP
 The symbol table entries consist of six words:
-.s3
-.lp +10 8
+.LP
+.LP +10 8
 Word 	Meaning
-.s1
-.lp 1-4	The first four words contain the left justified, null-padded ASCII symbol name.
-.lp +10 8
+.LP
+.LP 1-4	The first four words contain the left justified, null-padded ASCII symbol name.
+.LP +10 8
 The fifth word is a flag indicating the type of the symbol.
 The following values are possible:
-.lp +20 5
+.LP +20 5
 00	undefined
-.lp +20 5
+.LP +20 5
 01	absolute
-.lp +20 5
+.LP +20 5
 02	text
-.lp +20 5
+.LP +20 5
 03	data
-.lp +20 5
+.LP +20 5
 04	bss
-.lp +20 5
+.LP +20 5
 05	file name symbol (produced by ld80)
-.lp +20 5
+.LP +20 5
 010	undefined external
-.lp +20 5
+.LP +20 5
 011	absolute external
-.lp +20 5
+.LP +20 5
 012	text segment external
-.lp +20 5
+.LP +20 5
 013	data segment external
-.lp +20 5
+.LP +20 5
 014	bss segment external
-.lp +10 8
+.LP +10 8
 6	The sixth word is the value of the symbol.
 .i0
-.s3
+.LP
 The sixth word of a symbol table entry contains the value of the symbol.
-.s3
-.s3
+.LP
+.LP
 The value of a word in the text or data portions which is not
 a reference to an undefined external symbol
 is exactly that value which will appear in core
@@ -158,4 +158,4 @@
 link editor and the external symbol becomes
 defined, the value of the symbol will
 be added into the word in the file.
-.s3
+.LP
diff -ru alex-v10b/man/man5b/prtx.5g alex-v10/man/man5b/prtx.5g
--- alex-v10b/man/man5b/prtx.5g	1982-01-28 20:36:25.000000000 +0000
+++ alex-v10/man/man5b/prtx.5g	2025-02-13 22:16:11.998799451 +0000
@@ -135,7 +135,7 @@
 is required if "m" is present. Otherwise they must be omitted.
 If "m" is omitted then text must be present.
 .TP 10
-$X [ point ]
+\[Do]X [ point ]
 Macro Command: Invoke macro 
 .I X. 
 The the body of macro
diff -ru alex-v10b/man/man6/ascii.6 alex-v10/man/man6/ascii.6
--- alex-v10b/man/man6/ascii.6	1991-03-19 22:48:38.000000000 +0000
+++ alex-v10/man/man6/ascii.6	2025-02-14 15:39:57.666577228 +0000
@@ -14,7 +14,7 @@
 |010 bs |011 ht |012 nl |013 vt |014 np |015 cr |016 so |017 si |
 |020 dle|021 dc1|022 dc2|023 dc3|024 dc4|025 nak|026 syn|027 etb|
 |030 can|031 em |032 sub|033 esc|034 fs |035 gs |036 rs |037 us |
-|040 sp |041  ! |042  " |043  # |044  $ |045  % |046  & |047  \' |
+|040 sp |041  ! |042  " |043  # |044  \[Do] |045  % |046  & |047  \' |
 |050  ( |051  ) |052  * |053  + |054  , |055  - |056  . |057  / |
 |060  0 |061  1 |062  2 |063  3 |064  4 |065  5 |066  6 |067  7 |
 |070  8 |071  9 |072  : |073  ; |074  < |075  = |076  > |077  ? |
diff -ru alex-v10b/man/man6a/atc.6 alex-v10/man/man6a/atc.6
--- alex-v10b/man/man6a/atc.6	1986-08-18 21:06:06.000000000 +0100
+++ alex-v10/man/man6a/atc.6	2025-02-15 00:35:29.366966259 +0000
@@ -138,7 +138,7 @@
 Commands are terminated by newline.
 Backspace may be used to correct errors.
 The following kinds of commands can be issued.
-.IP $ \n()Mu
+.IP \[Do] \n()Mu
 End the game (game normally ends after 26 planes)
 .PD0
 .TP "\w'ALNW 'u"
@@ -153,7 +153,7 @@
 QA0
 .B Q
 will land (go to 0 feet altitude)
-.Tp
+.TP
 .B HRE
 .B H
 will turn right until it is heading east
diff -ru alex-v10b/man/man8/ship.8 alex-v10/man/man8/ship.8
--- alex-v10b/man/man8/ship.8	1989-09-21 19:40:23.000000000 +0100
+++ alex-v10/man/man8/ship.8	2025-02-17 17:37:30.965310889 +0000
@@ -54,11 +54,11 @@
 Other options are the same as those of
 .IR mkpkg :
 .PP
-.TP \w'\-X file 'u
+.TP 10n
 .B -v
 Emit running commentary on the standard error file.
 .TP
-.BI -D path1 = path2
+.BI -D "path1 = path2"
 Pretend that any
 .I file
 name that begins with

[-- Attachment #3: V10prepare.patch --]
[-- Type: text/x-patch, Size: 4038 bytes --]

diff --git a/share/mk/build/pdf/book/prepare.pl b/share/mk/build/pdf/book/prepare.pl
index 4620072ca..a41a877c5 100755
--- a/share/mk/build/pdf/book/prepare.pl
+++ b/share/mk/build/pdf/book/prepare.pl
@@ -1,4 +1,4 @@
-#!/usr/bin/perl -w
+#!/usr/bin/perl -wd
 #
 #	BuildLinuxMan.pl		: Build Linux manpages book
 #	Deri James (& Brian Inglis)	: 15 Dec 2022
@@ -50,6 +50,7 @@ my $dir2=$dir;
 $dir2=~tr[.][_];
 my %files;
 my %aliases;
+my $secQ=qr/\.\d+[\w.]*/;
 
 foreach my $al (`find "$dir"/man*/ -type f \\
 		| grep "\\.[[:digit:]]\\([[:alpha:]][[:alnum:]]*\\)\\?\\>\$" \\
@@ -58,14 +59,16 @@ foreach my $al (`find "$dir"/man*/ -type f \\
 	#$al=~tr[.][_];
 	$al=~m/^$dir\/man\d[a-z]*\/(.*):\.\s*so\s*man\d[a-z]*\/(.*)/o;
 
-	$aliases{$1}=$2;
+	$aliases{$1}=$2 if defined($1) and defined($2);
 }
 
 while (my ($k,$v)=each %aliases)
 {
 	while (exists($aliases{$v})) {
-		$v=$aliases{$v};
+	    $v=$aliases{$v};
 	}
+
+	$aliases{$k}=$v;
 }
 
 foreach my $fn (`find "$dir"/man*/ -type f \\
@@ -73,7 +76,7 @@ foreach my $fn (`find "$dir"/man*/ -type f \\
 {
 	$fn=~s/\n//;
 
-	my ($nm,$sec)=GetNmSec($fn,qr/\.\d[a-z]*/);
+	my ($nm,$sec)=GetNmSec($fn,$secQ);
 	$files{"${nm}.$sec"}=[$fn,(exists($aliases{"${nm}.$sec"}))?$aliases{"${nm}.$sec"}:"${nm}.$sec"];
 }
 
@@ -95,7 +98,7 @@ sub BuildPage
 	my $bkmark=shift;
 
 	my $fn=$files{$bkmark}->[0];
-	my ($nm,$sec,$srt)=GetNmSec($bkmark,qr/\.[\da-z]+/);
+	my ($nm,$sec,$srt)=GetNmSec($bkmark,$secQ);
 
 	my $title= "$nm\\($sec\\)";
 
@@ -106,8 +109,9 @@ sub BuildPage
 	# if new section add top level bookmark
 
 	if ($sec ne $Section) {
+		my $SecHd=(exists($Sections{$sec}))?$Sections{$sec}:"Section $sec";
 		print ".nr PDFOUTLINE.FOLDLEVEL 1\n";
-		print ".pdfbookmark 1 $Sections{$sec}\n";
+		print ".pdfbookmark 1 $SecHd\n";
 		print ".nr PDFOUTLINE.FOLDLEVEL 2\n";
 		$Section=$sec;
 	}
@@ -126,6 +130,19 @@ sub BuildPage
 
 			chomp;
 
+			# typo fixes for v10!!
+			s/^\.PD0/.PD 0/;
+			s/^\.ta1i/.ta 1i/;
+			s/\\fL/\f[CB]/g;
+			s/^\.ft\s*L/.ft CB/;
+			s/^\.ne(\d+)/.ne $1/;
+			s/^\.ft(\S)/.ft $1/;
+			s/^\.ps(\S)/.ps $1/;
+			s/^\.vs(\S)/.vs $1/;
+			s/^\.ti(\S)/.ti $1/;
+			s/\.if([tn])/.if $1/;
+			next if m/\.SH\s*$/;
+
 			# 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.
 
@@ -135,12 +152,13 @@ sub BuildPage
 			next if !$_;
 #			s/^\s+//;
 
-			s/\\-/-/g if /^\.[BM]R\s+/;
+			s/\\-/-/g if /^\.[BMI]R\s+/;
 
-			if (m/^\.BR\s+([-\w\\.]+)\s+\((.+?)\)(.*)/ or m/^\.MR\s+([-\w\\.]+)\s+(\w+)\s+(.*)/ or m/^\\fB([-\w\\.]+)\\fR\((.+?)\)(.*)$/) {
+			if (m/^\.[BI]R\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;
+				$sec=~s/\.\d//;
+				my $after=$3 || '';
 				$after=~s/\s\\".*//;
 				my $dest=$bkmark;
 				$dest=~s/\\-/-/g;
@@ -206,16 +224,25 @@ sub doMR
 	}
 }
 
+sub ns
+{
+    my $sec=shift;
+    $sec=~m/^(\d+)/;
+    $sec="0$1" if $1 < 10;
+    return $sec;
+}
+
 sub GetNmSec
 {
 	my ($nm,$pth,$sec)=fileparse($_[0],$_[1]);
 	$sec=substr($sec,1);
+	$sec=int($sec) if $sec=~m/^\d+\.\d+$/;
 	my $srt=$nm;
 	$srt=~s/\..+?$//;
 	$srt=~s/^_+//;
 	$srt=$1.sprintf("%04d",$2) if $srt=~m/^(.+)(\d+)$/;
 	#$srt="$sec/$srt";
-	return($nm,$sec,$srt);
+	return($nm,$sec,$srt,ns($sec));
 }
 
 # add rpmvercmp
@@ -226,16 +253,18 @@ sub sortman
 {
 # Sort - ignore case but frig it so that intro is the first entry.
 
-	my (undef,$s1,$c)=GetNmSec($a,qr/\.\d[a-z]*/);
-	my (undef,$s2,$d)=GetNmSec($b,qr/\.\d[a-z]*/);
+	my (undef,$s1,$c,$ns1)=GetNmSec($a,$secQ);
+	my (undef,$s2,$d,$ns2)=GetNmSec($b,$secQ);
 
-	my $cmp=$s1 cmp $s2;
+	my $cmp=$ns1 cmp $ns2;
 
 	return $cmp if $cmp;
 	return -1 if ($c=~m/^intro/ and $d!~m/^intro/);
 	return  1 if ($d=~m/^intro/ and $c!~m/^intro/);
 	$c=~tr[-_(][!" ];
 	$d=~tr[-_(][!" ];
+	$cmp=$s1 cmp $s2;
+	return($cmp) if $cmp;
 	$cmp=lc($c) cmp lc($d);
 	return($c cmp $d) if $cmp == 0;
 	return($cmp);

Re: Problem in prepare.pl (PDF book script) when handling Unix V10 manual pages

[Alejandro Colomar]

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

Hi Deri!

On Mon, Feb 17, 2025 at 06:52:46PM +0000, Deri wrote:
> On Thursday, 13 February 2025 16:08:39 GMT Alejandro Colomar wrote:
> > Hi Deri,
> > 
> > I tried generating a PDF book from the Unix v10 manual pages, and found
> > some issues with the Perl script.  I don't understand Perl, as you know,
> > so I don't know what to do.
> > 
> > I've attached a tarball with the manual pages that I'm trying to handle.
> > They're slightly modified V10 files, in order to make them slightly more
> > conventional (e.g., the =.1 page is now called eq.1, and the manx/ dir
> > and other dirs than didn't have a digit in their names are now divided
> > into dirs that have one digit after the name (e.g., man1x/, ...)).
> > 
> > The command I'm trying to run is:
> > 
> > 	$ make -R build-pdf-book MANDIR=~/Downloads/unix/man/
> > 
> > (Of course, replace that path with wherever you untar the tarball.)
> > 
> > The error I see is a forever loop (or so it seems) with the following
> > error line:
> > 
> > 	Use of uninitialized value $v in exists at
> > /srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/pdf/book/prep
> > are.pl line 67.
> > 
> > Would you mind having a look at it?
> > In case it matters:
> > 
> > 	alx@devuan:~$ groff --version
> > 	GNU groff version 1.23.0.2695-49927
> > 	Copyright (C) 1989-2023 Free Software Foundation, Inc.
> > 	This is free software, distributed under the terms of the GNU General
> > Public License, version 3, or any later version, at your option.  There is
> > NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
> > PURPOSE.
> > 
> > 	programs in constructed pipeline:
> > 
> > 	GNU grops (groff) version 1.23.0.2695-49927
> > 	GNU troff (groff) version 1.23.0.2695-49927
> > 
> > 
> > Have a lovely day!
> > Alex
> 
> Hi Alex,
> 
> This was caused by nonsense "aliases", see man1w/splitrules.1, and man1b/pins.
> 1g, which looks like an alias, but is not. This has now been fixed by being 
> more tolerant of weird entries which look like aliases.
> 
> There are a lot of pages which should have aliases added.
> 
> I found some other issues which I have fixed:-
> 
> When an alias points to another alias the code was meant to keep looking until 
> the real page is found. This affects the recent 6.11 (an example is 
> fchown32(2) which has no associated page number in the overview panel, it now 
> works properly.
> 
> Since the v10 pages are intended to run on a version of troff with a two 
> character name limit (I think). Code such as ".ne4" cause a problem for groff, 
> which needs ".ne 4" to work (otherwise groff looks for a macro called "ne4" 
> and fails. Many of these issues are now corrected.
> 
> A strange issue is that if a page contained a "$" character it sent eqn into 
> the stratosphere (thinking was dealing with an inline equation), I killed it 
> when eqn chewed up over 24gb of memory. I have no idea why, and it is not 
> triggered by a single page containing a "$", so it must be triggered by 
> something in an earlier man page which triggers it, but changing some "$" to 
> "\[Do]" fixed the problem.
> 
> One page redefined the ".P" man macro, which then affects all following man 
> pages.
> 
> One page introduced a string register called "mc" which then masks the groff 
> command ".mc" with very strange results .
> 
> Font L is used in many entries, no clue what font this is, but I convert to 
> font CB. Please change to taste (see lines 130 onwards).
> 
> Several pages use lower case macro names, i.e. ".th" rather than ".TH".
> 
> I have "fixed" a lot of the problems but there are still many warnings when 
> running groff. I have attached two parthes, one for the V10 man pages, and one 
> for prepare.pl. You should be able to produce a "useful" book after applying 
> these.

Thanks for all of that work!!

> 
> If you wish to see the fruits of my labour as a pdf, it is here:-
> 
> http://chuzzlewit.co.uk/UnixV10.pdf

It looks quite good!  I need to update the front page, and it's done, I
guess.  :-)


Have a lovely night!
Alex

> Cheers 
> 
> Deri

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

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

Re: Problem in prepare.pl (PDF book script) when handling Unix V10 manual pages

[G. Branden Robinson]

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

[CCing groff@gnu list because some problems arise here that merit being
 findable by search of its list archives]

Hi Deri,

At 2025-02-17T18:52:46+0000, Deri wrote:
> > 	programs in constructed pipeline:
> > 
> > 	GNU grops (groff) version 1.23.0.2695-49927
> > 	GNU troff (groff) version 1.23.0.2695-49927
[...]
> Since the v10 pages are intended to run on a version of troff with a
> two character name limit (I think). Code such as ".ne4" cause a
> problem for groff, which needs ".ne 4" to work (otherwise groff looks
> for a macro called "ne4" and fails. Many of these issues are now
> corrected.

We do have compatibility mode to support old-style AT&T troff input.

troff(1):
     -C       Enable AT&T troff compatibility mode; implies -c.  See
              groff_diff(7).

However...

[skipping ahead]
> but changing some "$" to "\[Do]" fixed the problem.

...if you're doing that, you foreclose use of `\[Do]` for 2 reasons.

1.  That syntax is a groff extension (the AT&T troff form would be
    `\(Do`)...but worse...
2.  `Do` is not a special character identifier generally recognized by
    AT&T-family troffs.  And there's no way within the AT&T *roff
    language to define new ones.  Fortunately, in Kernighan troff, it's
    not hard to add them to font description files.  As long as you have
    superuser privileges.

> A strange issue is that if a page contained a "$" character it sent
> eqn into the stratosphere (thinking was dealing with an inline
> equation), I killed it when eqn chewed up over 24gb of memory. I have
> no idea why, and it is not triggered by a single page containing a
> "$", so it must be triggered by something in an earlier man page which
> triggers it, but changing some "$" to "\[Do]" fixed the problem.

I surmise that this book building system either runs groff with the `-e`
option, or pipes the pages through eqn(1) explicitly, so that every page
gets preprocessed by eqn.  That's not wrong--in fact it's probably the
sanest thing to do--but it does expose you to scenarios like this.

I'd bet a U.S. 50-cent piece that some page had this in it:

.EQ
...
delim $$
...
.EN

and then never did this later:

.EQ
...
delim off
...
.EN

...because who ever formats more than one man page at a time?

So upon encountering a `$` in an eqnless man page later, the eqn
preprocessor would indeed then start gobbling up the entire remainder of
the input for attempted conversion to troff input.

GNU eqn added an option that strongly mitigates this and another
problem:

eqn(1):
     -N      Prohibit newlines within delimiters, allowing eqn to
             recover better from missing closing delimiters.

...and the groff(1) front-end exposes it too, for convenience:

groff(1):
     -N       Prohibit newlines between eqn delimiters: pass -N to
              eqn(1).

...however before reaching for this solution, the corpus of pages being
formatted needs to be audited to ensure that no multiline, inline use of
eqn is attempted.  If it is, the pages must be altered to either:

1.  stop doing that--maybe by joining lines--enabling use of `-N`;
2.  migrate the "inline" math to EQ/EN bracketing (groff man(7) doesn't
    define `EQ` and `EN` to set the math as a display, so this _should_
    work okay), also enabling use of `-N`; or
3.  find the spot where `delim off` should have been and add it.

> One page redefined the ".P" man macro, which then affects all
> following man pages.

Naughty, naughty!  I've wondered in the past about adding support for
"burning it all down and redefining all interface macros" in groff's
"an.tmac" (specifically when hitting a new `TH`).[1]  But I decided that
people wouldn't believe me that this was a practical hazard.  Thanks for
pointing me to a real-world case!  :D

> One page introduced a string register called "mc" which then masks the
> groff command ".mc" with very strange results .

That's not just a groff request name, but an AT&T one.  Hard to imagine
how that isn't a bug, or at least a deeply unwise practice.  People
might want to use {g,}diffmk(1) on man pages, and trashing the mechanism
for setting up the margin character defeats such usage.

Unfortunately man page authorship culture did not evolve in a direction
such that people making changes to the formatter's environment (in the
broad sense, not the *roff concept) put things back the way they found
them.  Approximately every man page is written in the expectation that
the formatter will exit once the last line of _this_ man page document
is read.

Just like how you don't need to bother to free heap-allocated memory in
your programs unless you think _you'll_ need it.  It's the free store!
Grab as much as you want and forget about it!  When your process dies
the OS will reclaim it all anyway, no harm, no foul.

It's no wonder Unix culture produced so many code cowboys.

> Font L is used in many entries, no clue what font this is, but I
> convert to font CB. Please change to taste (see lines 130 onwards).

Good call.  `L` (presumably abbreviating "literal") was a latter-day
Research Unix convention for font and macro names that I have not seen
in materials originating outside the 1980s CSRC.  AT&T Documenter's
Workbench (~1984-~1994), for example, did not appear to embrace it.

> Several pages use lower case macro names, i.e. ".th" rather than
> ".TH".

Wow.  Those could be hangovers from pre-Seventh Edition Unix "man".
But I thought Doug McIlroy got all of those ported/rewritten for Seventh
Edition.

Nevertheless, at least System III,[2] v8, and v10 retained support for
Sixth Edition style man pages.  For example:

$ head -n 5 v8/usr/lib/macros/an
'''\"   PWB Manual Entry Macros - 1.36 of 11/11/80
'''\"   Nroff/Troff Version     @(#)1.36
.deth
.tmwrong version of man entry macros - use -man6
.ab

So be careful out there if you don't want Dave Mustaine to snarl at you!

> I have "fixed" a lot of the problems but there are still many warnings
> when running groff. I have attached two parthes, one for the V10 man
> pages, and one for prepare.pl. You should be able to produce a
> "useful" book after applying these.
> 
> If you wish to see the fruits of my labour as a pdf, it is here:-
> 
> http://chuzzlewit.co.uk/UnixV10.pdf

This looks really good!  It's wonderful to see a working, useful
navigation pane, and at least some internal hyperlinks are working.
Some aren't, and at a glance it's not obvious to me why.  (It's not the
first argument to `TH` being in shouting capitals that hoses things, and
that's not practiced with 100% reliability anyway--see as80(1) and
ld80(1), for example.)

In fact those two pages are a weird in a few respects.  Obvious spelling
errors on the one hand ("moduals"?), and the latter uses a really old
Unix manual convention, identifying the section numbers with roman
numerals.

Where modernization for PDF rendering purposes stops and the Research
Tenth Edition Programmer's Manual, Volume 1 editorial effort begins anew
may prove a difficult boundary to draw.

Regards,
Branden

[1] One bad approach, IMO, would be to define all interface macros
    except `TH` _inside_ its own definition.  Apart from being
    super-disruptive for change tracking purposes, since it would touch
    nearly every line in the macro file, I would expect this to be
    harder to understand and maintain.  Nested macro definitions are
    fully countenanced by the *roff language but not, I think, a widely
    mastered technique.

    Better, I think, would be to define all interface macros using "long
    names", like `an*SH`, and then have `TH` redeclare the public names
    as aliases, as in `.als SH an*SH`.

    Care and testing would be required, as "andoc.tmac" uses the same
    technique to permit switching between man(7) and mdoc(7) input.  I
    am therefore not in a hurry to pick up this task, even though we do
    already have automated tests to detect failure of such switching.

[2] But not, interestingly, System V.
    https://github.com/ryanwoodsmall/oldsysv/

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

Re: Problem in prepare.pl (PDF book script) when handling Unix V10 manual pages

[Deri]

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

On Monday, 17 February 2025 22:22:46 GMT G. Branden Robinson wrote:
> [CCing groff@gnu list because some problems arise here that merit being
>  findable by search of its list archives]
> 
> Hi Deri,
> 
> At 2025-02-17T18:52:46+0000, Deri wrote:
> > > 	programs in constructed pipeline:
> > > 	
> > > 	GNU grops (groff) version 1.23.0.2695-49927
> > > 	GNU troff (groff) version 1.23.0.2695-49927
> 
> [...]
> 
> > Since the v10 pages are intended to run on a version of troff with a
> > two character name limit (I think). Code such as ".ne4" cause a
> > problem for groff, which needs ".ne 4" to work (otherwise groff looks
> > for a macro called "ne4" and fails. Many of these issues are now
> > corrected.
> 
> We do have compatibility mode to support old-style AT&T troff input.
> 
> troff(1):
>      -C       Enable AT&T troff compatibility mode; implies -c.  See
>               groff_diff(7).
> 
> However...
> 
> [skipping ahead]
> 
> > but changing some "$" to "\[Do]" fixed the problem.
> 
> ...if you're doing that, you foreclose use of `\[Do]` for 2 reasons.
> 
> 1.  That syntax is a groff extension (the AT&T troff form would be
>     `\(Do`)...but worse...
> 2.  `Do` is not a special character identifier generally recognized by
>     AT&T-family troffs.  And there's no way within the AT&T *roff
>     language to define new ones.  Fortunately, in Kernighan troff, it's
>     not hard to add them to font description files.  As long as you have
>     superuser privileges.

Hi Branden,

My prepare.pl is only supported for our groff, so I have no interest in making 
it compatible to AT&T troffs.

> > A strange issue is that if a page contained a "$" character it sent
> > eqn into the stratosphere (thinking was dealing with an inline
> > equation), I killed it when eqn chewed up over 24gb of memory. I have
> > no idea why, and it is not triggered by a single page containing a
> > "$", so it must be triggered by something in an earlier man page which
> > triggers it, but changing some "$" to "\[Do]" fixed the problem.
> 
> I surmise that this book building system either runs groff with the `-e`
> option, or pipes the pages through eqn(1) explicitly, so that every page
> gets preprocessed by eqn.  That's not wrong--in fact it's probably the
> sanest thing to do--but it does expose you to scenarios like this.
> 
> I'd bet a U.S. 50-cent piece that some page had this in it:
> 
> .EQ
> ...
> delim $$
> ...
> .EN
> 
> and then never did this later:
> 
> .EQ
> ...
> delim off
> ...
> .EN
> 
> ...because who ever formats more than one man page at a time?
> 
> So upon encountering a `$` in an eqnless man page later, the eqn
> preprocessor would indeed then start gobbling up the entire remainder of
> the input for attempted conversion to troff input.
> 
> GNU eqn added an option that strongly mitigates this and another
> problem:
> 
> eqn(1):
>      -N      Prohibit newlines within delimiters, allowing eqn to
>              recover better from missing closing delimiters.
> 
> ...and the groff(1) front-end exposes it too, for convenience:
> 
> groff(1):
>      -N       Prohibit newlines between eqn delimiters: pass -N to
>               eqn(1).
> 
> ...however before reaching for this solution, the corpus of pages being
> formatted needs to be audited to ensure that no multiline, inline use of
> eqn is attempted.  If it is, the pages must be altered to either:
> 
> 1.  stop doing that--maybe by joining lines--enabling use of `-N`;
> 2.  migrate the "inline" math to EQ/EN bracketing (groff man(7) doesn't
>     define `EQ` and `EN` to set the math as a display, so this _should_
>     work okay), also enabling use of `-N`; or
> 3.  find the spot where `delim off` should have been and add it.

Alex is in charge of the workflow pipeline, prepare.pl runs first and produces 
a [con]catenation (I remembered your preference :-) ) of all the man pages 
which is then run through all the pre-processors and groff -Z and finally 
gropdf. I'm tempted by your 3rd idea, since I am doing other "fixes" this is 
trivial to add, although adding -N is the simplest it does require what may be 
a difficult audit.

> > One page redefined the ".P" man macro, which then affects all
> > following man pages.
> 
> Naughty, naughty!  I've wondered in the past about adding support for
> "burning it all down and redefining all interface macros" in groff's
> "an.tmac" (specifically when hitting a new `TH`).[1]  But I decided that
> people wouldn't believe me that this was a practical hazard.  Thanks for
> pointing me to a real-world case!  :D
> 
> > One page introduced a string register called "mc" which then masks the
> > groff command ".mc" with very strange results .
> 
> That's not just a groff request name, but an AT&T one.  Hard to imagine
> how that isn't a bug, or at least a deeply unwise practice.  People
> might want to use {g,}diffmk(1) on man pages, and trashing the mechanism
> for setting up the margin character defeats such usage.
> 
> Unfortunately man page authorship culture did not evolve in a direction
> such that people making changes to the formatter's environment (in the
> broad sense, not the *roff concept) put things back the way they found
> them.  Approximately every man page is written in the expectation that
> the formatter will exit once the last line of _this_ man page document
> is read.
> 
> Just like how you don't need to bother to free heap-allocated memory in
> your programs unless you think _you'll_ need it.  It's the free store!
> Grab as much as you want and forget about it!  When your process dies
> the OS will reclaim it all anyway, no harm, no foul.
> 
> It's no wonder Unix culture produced so many code cowboys.
> 
> > Font L is used in many entries, no clue what font this is, but I
> > convert to font CB. Please change to taste (see lines 130 onwards).
> 
> Good call.  `L` (presumably abbreviating "literal") was a latter-day
> Research Unix convention for font and macro names that I have not seen
> in materials originating outside the 1980s CSRC.  AT&T Documenter's
> Workbench (~1984-~1994), for example, did not appear to embrace it.
> 
> > Several pages use lower case macro names, i.e. ".th" rather than
> > ".TH".
> 
> Wow.  Those could be hangovers from pre-Seventh Edition Unix "man".
> But I thought Doug McIlroy got all of those ported/rewritten for Seventh
> Edition.
> 
> Nevertheless, at least System III,[2] v8, and v10 retained support for
> Sixth Edition style man pages.  For example:
> 
> $ head -n 5 v8/usr/lib/macros/an
> '''\"   PWB Manual Entry Macros - 1.36 of 11/11/80
> '''\"   Nroff/Troff Version     @(#)1.36
> .deth
> .tmwrong version of man entry macros - use -man6
> .ab
> 
> So be careful out there if you don't want Dave Mustaine to snarl at you!
> 
> > I have "fixed" a lot of the problems but there are still many warnings
> > when running groff. I have attached two parthes, one for the V10 man
> > pages, and one for prepare.pl. You should be able to produce a
> > "useful" book after applying these.
> > 
> > If you wish to see the fruits of my labour as a pdf, it is here:-
> > 
> > http://chuzzlewit.co.uk/UnixV10.pdf
> 
> This looks really good!  It's wonderful to see a working, useful
> navigation pane, and at least some internal hyperlinks are working.
> Some aren't, and at a glance it's not obvious to me why.  (It's not the
> first argument to `TH` being in shouting capitals that hoses things, and
> that's not practiced with 100% reliability anyway--see as80(1) and
> ld80(1), for example.)

I think these are outliers, written in 1977, and using macro calls I have 
never heard of (.s1, .s3, .i0, ...). If you look at the V10 patch for the man 
pages you will see heavy editing of these pages, mainly changing anything I 
did not understand to .LP, since, whatever they are, they definitely expected 
a line break!

The majority of hyperlinks are fine, but remember that AT&T did not have a 
nice .MR macro to identify hyperlinks. The LinuxManBook is fairly consistent 
in using:-

.BR name (section)

Where fortunately this corresponds to the filename.section, rather than what 
is in the .TH line. The V10 corpus mainly uses:-

.IR name (section)

Again ignoring the actual .TH entry, but unfortunately it is not as consistent 
and there are anomalies. The 80.out.5 page codes it this way:-

.SH "SEE ALSO"
"as80" (I), "ld80" (I), "nm80" (I)

It's not really giving me much chance!

> In fact those two pages are a weird in a few respects.  Obvious spelling
> errors on the one hand ("moduals"?), and the latter uses a really old
> Unix manual convention, identifying the section numbers with roman
> numerals.
> 
> Where modernization for PDF rendering purposes stops and the Research
> Tenth Edition Programmer's Manual, Volume 1 editorial effort begins anew
> may prove a difficult boundary to draw.

I have done my best with "difficult" source, I gave myself a pretty low target 
"produce something at least readable", rather than fidelity to how it would 
have looked printed in 1980. Manually working through the groff errors would 
certainly improve the finished product. I have attached my log.

Cheers 

Deri

> Regards,
> Branden
> 
> [1] One bad approach, IMO, would be to define all interface macros
>     except `TH` _inside_ its own definition.  Apart from being
>     super-disruptive for change tracking purposes, since it would touch
>     nearly every line in the macro file, I would expect this to be
>     harder to understand and maintain.  Nested macro definitions are
>     fully countenanced by the *roff language but not, I think, a widely
>     mastered technique.
> 
>     Better, I think, would be to define all interface macros using "long
>     names", like `an*SH`, and then have `TH` redeclare the public names
>     as aliases, as in `.als SH an*SH`.
> 
>     Care and testing would be required, as "andoc.tmac" uses the same
>     technique to permit switching between man(7) and mdoc(7) input.  I
>     am therefore not in a hurry to pick up this task, even though we do
>     already have automated tests to detect failure of such switching.
> 
> [2] But not, interestingly, System V.
>     https://github.com/ryanwoodsmall/oldsysv/


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

[-- Attachment #2: t.log --]
[-- Type: text/x-log, Size: 11877 bytes --]

troff:<standard input>:38: error: cannot load font 'TinosR' to mark it as special
an.tmac:apsend.1:47: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:at.1:92: warning: cannot nest .TP or .TQ inside .TP; supply a tag
troff:awk.1:77: warning: font name 'CW' is deprecated
troff:bcp.1:51: warning: character with input code 12 not defined
an.tmac:calendar.1:100: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:calendar.1:102: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:calendar.1:104: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:cbt.1:137: warning: cannot nest .TP or .TQ inside .TP; supply a tag
an.tmac:cbt.1:139: warning: cannot nest .TP or .TQ inside .TP; supply a tag
troff:cu.1:131: warning: expected numeric expression, got character '`'
troff:dag.1:100: warning: name 'BIwidth' not defined (possibly missing space after 'BI')
an.tmac:dag.1:101: warning: cannot nest .TP or .TQ inside .TP; supply a tag
troff:ftp.1:458: warning: cannot select font '\'
troff:gcc.1:500: error: a space character is not allowed in an escape sequence argument
troff:ideal.1:350: warning: name '..width' not defined (possibly missing space after '..')
troff:ideal.1:351: warning: name '..libfile' not defined (possibly missing space after '..')
troff:ideal.1:352: warning: name '..minx' not defined (possibly missing space after '..')
troff:ld80.1:105: error: cannot clear diversion trap when not diverting output
troff:memo.1:22: error: unterminated transparent embedding escape sequence
troff:mkstr.1:86: warning: name '..SH' not defined (possibly missing space after '..')
troff:mkstr.1:87: warning: name '..All' not defined (possibly missing space after '..')
troff:nm80.1:11: warning: expected numeric expression, got character 'N'
troff:sml.1:44: warning: expected numeric expression, got character 'e'
troff:snocone.1:218: warning: expected numeric expression, got character 'P'
troff:snocone.1:237: warning: expected numeric expression, got character 'I'
troff:splitrules.1:2: error: cannot open '/usr/man/man1/splitinf.1': No such file or directory
troff:tbl.1:271: warning: name 'sp3' not defined (possibly missing space after 'sp')
troff:gplot.1g:3: error: cannot load font 'G' for mounting
troff:pins.1g:0: error: cannot open 'CDL': No such file or directory
troff:pins.1g:24: warning: name 'sp.5' not defined (possibly missing space after 'sp')
troff:vtimes.2v:26: warning: expected numeric expression, got character 't'
troff:erf.3:39: warning: character with input code 4 not defined
troff:manip.3:112: warning: expected numeric expression, got character 'o'
troff:sbuf.prot.3:193: warning: expected numeric expression, got character 'e'
troff:strstream.3:64: warning: expected numeric expression, got character 't'
troff:plot.5:373: warning: expected numeric expression, got character 'd'
troff:ipa.6:0: error: cannot load font 'P1' from file 'IPA1' for mounting
troff:ipa.6:1: error: cannot load font 'P2' from file 'IPA2' for mounting
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:54: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:39: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:40: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:41: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:42: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:43: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:44: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:45: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:46: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:47: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:48: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:49: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:50: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:51: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:52: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:53: warning: cannot select font 'L'
troff:ipa.6:54: warning: cannot select font 'L'
troff:mbits.6:0: error: cannot open '/usr/lib/tmac/tmac.bits': No such file or directory
troff:mbits.6:68: error: system command execution request is not allowed in safer mode
troff:mbits.6:72: error: system command execution request is not allowed in safer mode
troff:mbits.6:76: error: system command execution request is not allowed in safer mode
troff:mbits.6:80: error: system command execution request is not allowed in safer mode
troff:mbits.6:84: error: system command execution request is not allowed in safer mode
troff:mbits.6:88: error: system command execution request is not allowed in safer mode
troff:mbits.6:95: error: system command execution request is not allowed in safer mode
troff:av.7:102: warning: expected numeric expression, got character 'u'
troff:scat.7:21: warning: name 'RB(' not defined (possibly missing space after 'RB')
troff:fstat.8:37: error: cannot clear diversion trap when not diverting output
troff:mkfs.8:118: warning: name 'sp5' not defined (possibly missing space after 'sp')
troff:svcmgr.8:316: warning: name '..SH' not defined (possibly missing space after '..')
troff:svcmgr.8:317: warning: name '..to' not defined (possibly missing space after '..')
troff:upas.8:208: warning: name 'EX#' not defined (possibly missing space after 'EX')
an.tmac:blitblt.9:27: warning: cannot nest .TP or .TQ inside .TP; supply a tag
troff:faced.9:26: warning: font name 'H' is deprecated
troff:jioctl.9:61: warning: expected numeric expression, got character '"'
troff:mds.10:62: warning: expected numeric expression, got character ','