[TUHS] v6 Unix Documents

[TUHS] v6 Unix Documents

[Dan Plassche]

Hi,

A scan of the printed UNIX Version 6 documents set is now online
at the link below since last week.  The set consists of documents
accompanying the manual pages in the programmer's manual (similar
to volume 2 in v7).

https://www.computerhistory.org/collections/catalog/102659317

The [nt]roff user manual, tmg compiler-compiler, and m6 macro
processor memos were previously missing from the distributions
in TUHS and later efforts to re-create the documentation.

I have been working on finding this documentation as part of
researching roff history.  Still interested in earlier copies of
the internal memoranda from Ossanna that served as the NROFF
User's Manual since v3, the TROFF User's Manual after v5, and
TROFF Made Trivial starting around v4. Based on the manpage
histories, the documentation was revised for v4, 5, and 6.


Best,

Dan Plassche

[TUHS] Re: v6 Unix Documents

[G. Branden Robinson]

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

Hi Dan,

At 2024-10-17T21:19:38-0500, Dan Plassche wrote:
> A scan of the printed UNIX Version 6 documents set is now online
> at the link below since last week.  The set consists of documents
> accompanying the manual pages in the programmer's manual (similar
> to volume 2 in v7).

And Volume 2 in Research version 10!  Bell Labs Unix published a Volume
2 for only three releases (per McIlroy), and it appears that all have
now been recovered.  This is a milestone--thank you!

> https://www.computerhistory.org/collections/catalog/102659317

I do observe that this web page credits the publisher of the document as
"Western Digital Corporation".  Shouldn't that be "Western Electric
Company"?

(Apparently back in 1975, WD was making chips for calculators.)

> The [nt]roff user manual,

Noteworthy but frustrating here is that at this point, the forerunner of
CSTR #54 was still titled simply "NROFF Users' Manual" (PDF pp. 173ff.).
References to troff are present, but the typesetting program is not
fully documented.  Frustrating!

Also we have here the (unnumbered) first edition of the eqn User's
Guide (PDF pp. 269ff.).

I haven't enumerated the language changes in nroff and eqn going from v6
to v7 yet, but for the formatter there seem to be at least a dozen,
including numerous deletions.  (If I tried to move groff that fast, I'd
be dragged before a firing squad by the faculty of a German university!)

The biggest nroff change that leaps out at me right now is that in V6
_special character escape sequences did not yet exist_.  Given that the
C/A/T typesetter had already been in use for years by 1975 (with eqn
giving it strenuous exercise from early on), I find this fascinating.
Evidence of the close relationship with the Teletype Model 37 is
present, with the `\x` and `\y` escape sequences mapping to "ASCII
Shift-out" and "ASCII Shift-in", respectively (PDF p. 177).

Check out some of these other relics:

.xh		Extra half-line mode on.
.ch -N -M	Move trap by _position_, not name.

.nc		Number character.

(From an interpreter writer's perspective, that one's _really_
interesting.  I won't spoil its shocking semantics here.)

.ar		Arabic numbers.
.ro		Lower case roman numbers.
.RO		Upper case roman numbers.

(The `af` request hadn't been developed yet.  The me(7) package at
Berkeley, which commenced development in 1978--_before_ Seventh
Edition--helped people over the hump in the case of the first two.)

.li		Accept input lines literally.

(That one survived, undocumented, into Seventh Edition.)

.np		Number parameters set or reset.

\?		Raw transmission indicator
\:		Generates ASCII ETX (003) for post processor use
\l		ASCII Delete

I see that the `ad` request did not accept arguments "l" or "b", just
"c" and "n".  Since "b" and "l" were redundant, my imaginations conjures
office arguments over the meaning of the word "adjustment".  With the
design in such flux, too bad I wasn't there to lobby for the separation
of "alignment" and "adjustment".  ;-)

No worries, I'll be there soon!  <https://savannah.gnu.org/bugs/?65954>
(Fifty years late but moving fast, as Douglas Adams might have said.)

You could turn automatic hyphenation on or off, but there was only one
hyphenation mode.  Any color you want, so long as it's black!  :)

> tmg compiler-compiler, and m6 macro processor memos were previously
> missing from the distributions in TUHS and later efforts to re-create
> the documentation.

I'm intensely interested in both of these from a personal perspective.

I observe that the TMG and  m6 documents appear may have been prepared
by vintage 1972 and 1971 nroff, making them worthwhile exhibits on that
basis alone (PDF pp. 211ff., 239ff., respectively).  I wonder why they
were never typeset.  Would the document sources have required too much
"porting" to troff?

One more thing I noticed: in a first glance, it appears Room 127 got
their hands on a sans-serif (Helvetica?) roman plate for the C/A/T prior
to V5.  We see it used in Ritchie's "C Reference Manual" (PDF pp. 31ff.)
and Kernighan's "Programming in C — A Tutorial" (PDF pp. 61ff.).  But
Courier is nowhere in sight.

In summary, there is a boatload of information here that is useful to me
in understanding Why Things Look The Way They Do.

> I have been working on finding this documentation as part of
> researching roff history.  Still interested in earlier copies of
> the internal memoranda from Ossanna that served as the NROFF
> User's Manual since v3, the TROFF User's Manual after v5, and
> TROFF Made Trivial starting around v4. Based on the manpage
> histories, the documentation was revised for v4, 5, and 6.

Please keep the groff list apprised of further findings.  Fascinating
stuff.

Good work!

Regards,
Branden

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

[TUHS] Re: v6 Unix Documents

[Al Kossow]

On 10/18/24 6:58 AM, G. Branden Robinson wrote:

>> https://www.computerhistory.org/collections/catalog/102659317
> 
> I do observe that this web page credits the publisher of the document as
> "Western Digital Corporation".  Shouldn't that be "Western Electric
> Company"?
> 
> (Apparently back in 1975, WD was making chips for calculators.)
>

typos happen
email research@computerhistory.org and let them know you found an error

[TUHS] Re: v6 Unix Documents

[Jonathan Gray]

On Fri, Oct 18, 2024 at 08:58:06AM -0500, G. Branden Robinson wrote:
> 
> Noteworthy but frustrating here is that at this point, the forerunner of
> CSTR #54 was still titled simply "NROFF Users' Manual" (PDF pp. 173ff.).
> References to troff are present, but the typesetting program is not
> fully documented.  Frustrating!

PWB was an early external distribution with troff.

Documents for the PWB/UNIX Time-Sharing System
https://datamuseum.dk/wiki/Bits:30007124
https://bitsavers.org/pdf/att/unix/PWB_UNIX/

NROFF/TROFF User's Manual
October 11, 1976
datamuseum.dk, pp 325-357
bitsavers, pp 217-249

Addendum to the NROFF/TROFF User's Manual
May 1977
datamuseum.dk, p 358
bitsavers, p 250

fonts described in:
Administrative Advice for PWB/UNIX
23. PHOTOTYPESETTING EQUIPMENT AND SUPPLIES
datamuseum.dk, p 647

[TUHS] Re: v6 Unix Documents

[Jonathan Gray]

On Sun, Oct 20, 2024 at 01:23:23AM -0400, Dan Plassche wrote:
> 
> On Sat, 19 Oct 2024, Jonathan Gray wrote:
> 
> > PWB was an early external distribution with troff.
> > 
> > Documents for the PWB/UNIX Time-Sharing System
> > https://datamuseum.dk/wiki/Bits:30007124
> > https://bitsavers.org/pdf/att/unix/PWB_UNIX/
> > 
> > NROFF/TROFF User's Manual
> > October 11, 1976
> > datamuseum.dk, pp 325-357
> > bitsavers, pp 217-249
> > 
> > Addendum to the NROFF/TROFF User's Manual
> > May 1977
> > datamuseum.dk, p 358
> > bitsavers, p 250
> > 
> > fonts described in:
> > Administrative Advice for PWB/UNIX
> > 23. PHOTOTYPESETTING EQUIPMENT AND SUPPLIES
> > datamuseum.dk, p 647
> 
> Thank you Jonathan.  I was previously not sure where to place the 
> PWB documentation in the timeline but a clearer picture is 
> emerging.
> 
> Based on the v6 "NROFF User's Manual" revised in 1974 and 
> published in 1975, I can now see that the PWB documentation with 
> the "NROFF/TROFF User's Manual" from 1976-77 has most of the 
> content that later appears in v7.  The major change immediately 
> beforehand was the rewrite of troff into C.[1] Some clear 
> differences are the combination of nroff and troff manpages and 
> the addition of troff specific features like the special fonts 
> into the user's manual.
> 
> [1]. Apparently in 1976: 
> https://www.tuhs.org/Archive/Distributions/USDL/unix_program_description-troffsrc.tar.gz

"It was rewritten in C around 1975"
Kernighan in CSTR 97, A Typesetter-independent TROFF

I've seen references to
"Documents for Use with the Phototypesetter (Version 7)"
which was likely distributed with the licensed phototypesetter tape in 1977.

What may have been the manual distributed with that tape is also close to v7.

https://www.tuhs.org/cgi-bin/utree.pl?file=Interdata732/usr/source/troff/doc
https://www.tuhs.org/Archive/Distributions/Other/Interdata/

tuhs Applications/Spencer_Tapes/unsw3.tar.gz
usr/source/formatters/troff/doc/

[TUHS] Typesetter C Compiler and Troff (Re: Re: v6 Unix Documents)

[Dan Plassche]

On Sun, 20 Oct 2024, Jonathan Gray wrote:

> I've seen references to
> "Documents for Use with the Phototypesetter (Version 7)"
> which was likely distributed with the licensed phototypesetter tape in 1977.
> 
> What may have been the manual distributed with that tape is also close to v7.
> 
> https://www.tuhs.org/cgi-bin/utree.pl?file=Interdata732/usr/source/troff/doc
> https://www.tuhs.org/Archive/Distributions/Other/Interdata/
> 
> tuhs Applications/Spencer_Tapes/unsw3.tar.gz
> usr/source/formatters/troff/doc/

Looks we have the files from 1977!

There are 3 distributions on TUHS that have the same general name 
and number of source files for the "typesetter c" compiler and 
the "new" troff in C:

https://www.tuhs.org/Archive/Applications/Spencer_Tapes/unsw3.tar.gz
	./usr/source/c_compiler
	./usr/source/formatters/

https://www.tuhs.org/Archive/Distributions/USDL/spencer_pwb.tar.gz
	./sys/c/c
	./type/croff
	./sys/source/s7/croff

https://www.tuhs.org/Archive/Distributions/Other/Interdata/interdata_v6.tar.gz
	./usr/source/c
	./usr/source/troff

The Spencer PWB tape appears to be 1.0.  Dates on files from 
sccsid comments on nroff/troff and throughout the system are from 
early to mid-1977 making this the earliest set.[1]  The files 
under the ./type/croff directory and ./sys/source/s7/croff are 
the same.

The UNSW AUSAM tape has the same files as PWB.  An initial check 
shows some feature flags and structs from PWB are missing for 
[nt]roff here.  However, there are extra notes on the c changes 
and the October 1976 NROFF/TROFF manual source for content 
published in the PWB documentation.  The latest dates on other 
files are from early to mid-1978.[2]

The Interdata files have lots of added comments and changes with 
a late 1978 date listed in some files[3].  It does have extra 
READ_ME files confirming that this was pre-release v7 c compiler 
for v6, which helps validate the PWB and UNSW content.

I'll work from the PWB and UNSW files with the plan to send troff 
details to the groff list and rebuild the compiler in the 
process.  Glad to confirm if the build succeeds and I find out 
any further details about the compiler if relevant for TUHS.

 1. Examples: ./usr/man/man0/introduction: May 1977 and 
    ./usr/man/man0/documents: August 1977

 2. As printed in the copy available at: 

 http://www.bitsavers.org/pdf/att/unix/PWB_UNIX/Documents_for_the_PWB_UNIX_Time-Sharing_System_Edition_1.0_197710.pdf

    Updates like the January 1978 changes to the dz serial code 
    provided by Dennis at ./usr/sys/dmr/dz.c.

 3. Such as ./usr/doc/cman/cman1: June 1978.


Best,

Dan

[TUHS] Re: Typesetter C Compiler and Troff (Re: Re: v6 Unix Documents)

[Jonathan Gray]

On Sun, Oct 20, 2024 at 08:30:47PM -0400, Dan Plassche wrote:
> 
> On Sun, 20 Oct 2024, Jonathan Gray wrote:
> 
> > I've seen references to
> > "Documents for Use with the Phototypesetter (Version 7)"
> > which was likely distributed with the licensed phototypesetter tape in 1977.
> > 
> > What may have been the manual distributed with that tape is also close to v7.
> > 
> > https://www.tuhs.org/cgi-bin/utree.pl?file=Interdata732/usr/source/troff/doc
> > https://www.tuhs.org/Archive/Distributions/Other/Interdata/
> > 
> > tuhs Applications/Spencer_Tapes/unsw3.tar.gz
> > usr/source/formatters/troff/doc/
> 
> Looks we have the files from 1977!
> 
> There are 3 distributions on TUHS that have the same general name 
> and number of source files for the "typesetter c" compiler and 
> the "new" troff in C:
> 
> https://www.tuhs.org/Archive/Applications/Spencer_Tapes/unsw3.tar.gz
> 	./usr/source/c_compiler
> 	./usr/source/formatters/

same contents in
Distributions/UNSW/7/record0.tar.gz
source/formatters/

> 
> https://www.tuhs.org/Archive/Distributions/USDL/spencer_pwb.tar.gz
> 	./sys/c/c
> 	./type/croff
> 	./sys/source/s7/croff
> 
> https://www.tuhs.org/Archive/Distributions/Other/Interdata/interdata_v6.tar.gz
> 	./usr/source/c
> 	./usr/source/troff

Applications/Usenix_77/ug091377.tar.gz
3/ken/nroff_manual/ 'NROFF/TROFF User's Manual'
same as interdata troff doc, without some files

> 
> The Spencer PWB tape appears to be 1.0.  Dates on files from 
> sccsid comments on nroff/troff and throughout the system are from 
> early to mid-1977 making this the earliest set.[1]  The files 
> under the ./type/croff directory and ./sys/source/s7/croff are 
> the same.
> 
> The UNSW AUSAM tape has the same files as PWB.  An initial check 
> shows some feature flags and structs from PWB are missing for 
> [nt]roff here.  However, there are extra notes on the c changes 
> and the October 1976 NROFF/TROFF manual source for content 
> published in the PWB documentation.  The latest dates on other 
> files are from early to mid-1978.[2]
> 
> The Interdata files have lots of added comments and changes with 
> a late 1978 date listed in some files[3].  It does have extra 
> READ_ME files confirming that this was pre-release v7 c compiler 
> for v6, which helps validate the PWB and UNSW content.
> 
> I'll work from the PWB and UNSW files with the plan to send troff 
> details to the groff list and rebuild the compiler in the 
> process.  Glad to confirm if the build succeeds and I find out 
> any further details about the compiler if relevant for TUHS.

I adapted Tim Newsham's v6 install scripts for PWB if you'd
like to run it on simh.

https://github.com/jonathangray/pwb/

Base system from the Bostic tapes, troff installed from
the Spencer tape.

> 
>  1. Examples: ./usr/man/man0/introduction: May 1977 and 
>     ./usr/man/man0/documents: August 1977
> 
>  2. As printed in the copy available at: 
> 
>  http://www.bitsavers.org/pdf/att/unix/PWB_UNIX/Documents_for_the_PWB_UNIX_Time-Sharing_System_Edition_1.0_197710.pdf
> 
>     Updates like the January 1978 changes to the dz serial code 
>     provided by Dennis at ./usr/sys/dmr/dz.c.
> 
>  3. Such as ./usr/doc/cman/cman1: June 1978.
> 
> 
> Best,
> 
> Dan
> 

[TUHS] Re: Typesetter C Compiler and Troff (Re: Re: v6 Unix Documents)

[Dan Plassche]

> Date: Sun, 20 Oct 2024 22:47:43
> From: Jonathan Gray <jsg@jsg.id.au>
> 
> 
> I adapted Tim Newsham's v6 install scripts for PWB if you'd
> like to run it on simh.
> 
> https://github.com/jonathangray/pwb/

Thanks, very helpful and worked well.  Since I was able to 
follow the setup script and rebuild the c versions of nroff/troff 
on PWB 1.0, I took a look at the new c compiler for differences 
with the UNSW copy.

It turns out that the UNSW copy of the c compiler was definitely 
a earlier version than in PWB.  The most noticeable difference in 
the UNSW stdio library was calloc.c not using malloc.  The most 
major omission in the c compiler was casts and there were also 
some local changes to cc.c.  Based on those differences, I'm 
thinking that the UNSW copy appears to be from late 1976 to early 
1977.

I was able to rebuild both the UNSW and the native PWB compiler 
on PWB 1.0, but not to backport either to vanilla v6.


Best,

Dan

[TUHS] Re: v6 Unix Documents

[Dan Plassche]

Thanks Jonathan for the pointer.

On Sat, 19 Oct 2024, Jonathan Gray wrote:

> PWB was an early external distribution with troff.
> 
> Documents for the PWB/UNIX Time-Sharing System
> https://datamuseum.dk/wiki/Bits:30007124
> https://bitsavers.org/pdf/att/unix/PWB_UNIX/
> 
> NROFF/TROFF User's Manual
> October 11, 1976
> datamuseum.dk, pp 325-357
> bitsavers, pp 217-249
> 
> Addendum to the NROFF/TROFF User's Manual
> May 1977
> datamuseum.dk, p 358
> bitsavers, p 250
> 
> fonts described in:
> Administrative Advice for PWB/UNIX
> 23. PHOTOTYPESETTING EQUIPMENT AND SUPPLIES
> datamuseum.dk, p 647

I was not previously certain where the PWB release fit into the 
troff timeline.  

Based on comparison to the v6 manual last updated in September 
1974 and published in 1975, this manual revised in October 1976 
and published in 1977 now integrates troff-specific content like 
the special fonts you mentioned under new title of "NROFF/TROFF 
User's Manual."  The major change in the meantime was the rewrite 
of troff into C.[1]

1. Apparently from 1975-76 as noted in the 1992 revision of the 
manual and shown in the PWB 1.0 croff source code below:

https://www.tuhs.org/Archive/Distributions/USDL/spencer_pwb.tar.gz


Best,

Dan

[TUHS] Re: v6 Unix Documents

[Dan Plassche]

Hey Branden,

Apologies for the duplicate message.  I had a mailer issue this 
evening where the message did not reach TUHS.

On Fri, 18 Oct 2024, G. Branden Robinson wrote:

> I do observe that this web page credits the publisher of the document as
> "Western Digital Corporation".  Shouldn't that be "Western Electric
> Company"?

Yeah, Western Electric issued licenses and official printed 
documentation externally for Research Unix in the 1970s.

I completely looked past that typo in the catalog amidst the 
thrill of obtaining the document!

I've let an archivist at the CHM know of the correction.  I found 
in the course of researching that most other catalogs list the 
documentation as a single serial item from 1971 onwards with 
Thompson and/or Ritchie as authors, so finding any specific item 
can be difficult.

> > The [nt]roff user manual,
> 
> Noteworthy but frustrating here is that at this point, the forerunner of
> CSTR #54 was still titled simply "NROFF Users' Manual" (PDF pp. 173ff.).
> References to troff are present, but the typesetting program is not
> fully documented.  Frustrating!

We can trace the evolution using nroff as a starting point.

Nroff appeared in v2 Unix in 1972 and the preceeding roff 
formatter did not change afterwards.

The v3 manpage for nroff includes the first reference to the 
"NROFF User's Manual" (MM-73-1271-2) and a summary of all 
commands.  The summary is available with each dated and revised 
manpage for nroff through v5.

The v6 manual from 1975 is identified as the second edition of 
the "NROFF User's Manual" as revised in Sept. 1974.

If the documentation and changes to the extant source code from 
v4 to v6 are in alignment, we should have a baseline history with 
a clear indication of differences across versions.  I will send a 
summary with further details to the groff mailing list in the 
coming weeks.

The development of troff before the rewrite to C between v6 and 
v7 is a lot less clear.  Troff appears in v4 with a mention of a 
preliminary user's manual, but I suspect the manual is a summary 
of unique troff features that were not documented elsewhere until 
v7.  The manpages only cover troff invocation.

> Also we have here the (unnumbered) first edition of the eqn User's
> Guide (PDF pp. 269ff.).
... 
> The biggest nroff change that leaps out at me right now is that in V6
> _special character escape sequences did not yet exist_.  Given that the
> C/A/T typesetter had already been in use for years by 1975 (with eqn
> giving it strenuous exercise from early on), I find this fascinating.

Perhaps special characters did exist for troff but were not 
documented in this v6 manual.  It's not clear without seeing an 
earlier troff manual, but I'm staring to think that the v6 manual 
may be a continuation of the nroff manual alone.  In that case, 
general users would have fallen back on overstrikes for most 
special characters.  The greek characters in eqn and the various 
copyright symbols on earlier programmer's manuals seem to support 
the assumption that special characters were in use with troff.  
The documents and programmer's manuals were all printed with 
troff from v4 onwards.


> Evidence of the close relationship with the Teletype Model 37 is
> present, with the `\x` and `\y` escape sequences mapping to "ASCII
> Shift-out" and "ASCII Shift-in", respectively (PDF p. 177).

I was surprised to see the ribbon shift-in/out feature existed 
and then got removed, since it would seem that the command could 
have been reused for changing the typing element on Selectric 
consoles and daisywheel printers that were fairly widespread.

> .xh		Extra half-line mode on.

Half line motions are surprisingly common on older documents and 
probably a major reason for using troff output that's setup to 
look like an nroff device.

> I see that the `ad` request did not accept arguments "l" or "b", just
> "c" and "n".  Since "b" and "l" were redundant, my imaginations conjures
> office arguments over the meaning of the word "adjustment".  With the
> design in such flux, too bad I wasn't there to lobby for the separation
> of "alignment" and "adjustment".  ;-)
> 
> No worries, I'll be there soon!  <https://savannah.gnu.org/bugs/?65954>
> (Fifty years late but moving fast, as Douglas Adams might have said.)

The v6 design certainly seems clearer and in support of your 
cleanup.

> > tmg compiler-compiler, and m6 macro processor memos were previously
> > missing from the distributions in TUHS and later efforts to re-create
> > the documentation.
> 
> I'm intensely interested in both of these from a personal perspective.
> 
> I observe that the TMG and  m6 documents appear may have been prepared
> by vintage 1972 and 1971 nroff, making them worthwhile exhibits on that
> basis alone (PDF pp. 211ff., 239ff., respectively).  I wonder why they
> were never typeset.  Would the document sources have required too much
> "porting" to troff?

I was very interested to find the papers as well.  The output 
seems to be roff formatted like the v1 manual on TUHS and frozen 
from around 1972.

> In summary, there is a boatload of information here that is useful to me
> in understanding Why Things Look The Way They Do.
> 
> Please keep the groff list apprised of further findings.  Fascinating
> stuff.
> 
> Good work!
> 
> Regards,
> Branden

Thank you for your feedback and the credit in re-creating the 
Unix porting paper, which I have been following with interest.

I really appreciate all of the extra work you put in as 
maintainer to understand the history of roff design and output in 
order to better document, validate, and develop groff.


Sincerely,

Dan