[TUHS] Project Idea: The UNIX Programmer's Manual: Heritage Edition

[TUHS] Project Idea: The UNIX Programmer's Manual: Heritage Edition

[segaloco via TUHS]

I haven't known when or how to bring up this project idea, but figure I might as well start putting feelers out since my Dragon Quest project is starting to slow down and I might focus back on UNIX manual stuff.

So something painfully missing from my and I'm sure plenty of other folks' libraries is a nice, modern paper UNIX manual that takes the past few decades into consideration.  The GNU project, BSDs, etc. ship manpages of course, and there's the POSIX manpages, but I'm a sucker for a good print manual.  Something I'm thinking of producing as a "deliverable" of sorts from my documentation research is a new-age UNIX manual, derived as closely as possible from the formal UNIX documentation lineages (so Research, SysV, and BSD pages), but:

    1. Including subsequent POSIX requirements
    2. Including an informational section in each page with a little history and some notes about current implementations, if applicable.  This would include notes about "dead on the vine" stuff like things plucked from the CB-UNIX, MERT/PG, and PWB lines.  The history part could even be a separate book, that way the manual itself could stay tight and focused.  This would also be a good place for luminaries to provide reflections on their involvement in given pieces.

One of the main questions that I have in mind is what the legal landscape of producing such a thing would entail.  At the very least, to actually call it a UNIX Programmer's Manual, it would probably need to pass some sort of compliance with the materials The Open Group publishes.  That said, the ownership of the IP as opposed to the trademarks is a little less certain, so I would be a bit curious who all would be involved in specifically getting copyright approval to publish anything that happened the commercial line after the early 80s, so like new text produced after 1982.  I presume anything covered by the Caldera license at least could be published at-cost, but not for a profit (which I'm not looking for anyway.)

Additionally, if possible, I'd love to run down some authorship information and make sure folks who wrote stuff up over time are properly credited, if not on each page ala OWNER at least in a Acknowledgements section in the front.

As far as production, I personally would want to do a run with a couple of different cover styles, comb bound, maybe one echoing the original Bell Laboratories UNIX User's Manual-style cover complete with Bell logo, another using the original USENIX Beastie cover, etc. but that also then calls into question more copyrights to coordinate, especially with the way the Bell logo is currently owned, that could get complicated.

Anywho, anyone know of any such efforts like this?  If I actually got such a project going in earnest, would folks find themselves interested in such a publication?  In any case I do intend to start on a typesetter sources version of this project sometime in the next year or so, but ideally I would want it to blossom into something that could result in some physical media.  This idea isn't even half-baked yet by the way, so just know I don't have a roadmap in place, it's just something I see being a cool potential project over the coming years.

- Matt G.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Larry McVoy]

One of the projects I thought I'd do in my retirement, but haven't done, 
was to provide man page / paper as in "a paper", not tree paper, versions
of all the GNU info stuff.  I could not be less thrilled with info, yeah
there are ways to deal, but it just isn't as good (to me) as how Unix did
docs.  It's like they want to force emacs on us to read docs.

I'd start with groff.

So I'm a little off topic but if people wanted to work on that, I'd be
up for that project.  It's not as big as what you are saying but it's 
pretty big, I think we just start with something, see if we can get 
debian/ubuntu to pick it up, lather, rinse repeat.  In fact if we 
just get the groff project to pick up our stuff, all the distros will
get that eventually.

The one drawback I see is people might want to provide info and man 
docs.  My personal preference is that the info stuff goes away but I
have learned I don't get what I want.  So there may be a period of 
time where both need to be maintained.

On Tue, Sep 19, 2023 at 08:32:15PM +0000, segaloco via TUHS wrote:
> I haven't known when or how to bring up this project idea, but figure I might as well start putting feelers out since my Dragon Quest project is starting to slow down and I might focus back on UNIX manual stuff.
> 
> So something painfully missing from my and I'm sure plenty of other folks' libraries is a nice, modern paper UNIX manual that takes the past few decades into consideration.  The GNU project, BSDs, etc. ship manpages of course, and there's the POSIX manpages, but I'm a sucker for a good print manual.  Something I'm thinking of producing as a "deliverable" of sorts from my documentation research is a new-age UNIX manual, derived as closely as possible from the formal UNIX documentation lineages (so Research, SysV, and BSD pages), but:
> 
>     1. Including subsequent POSIX requirements
>     2. Including an informational section in each page with a little history and some notes about current implementations, if applicable.  This would include notes about "dead on the vine" stuff like things plucked from the CB-UNIX, MERT/PG, and PWB lines.  The history part could even be a separate book, that way the manual itself could stay tight and focused.  This would also be a good place for luminaries to provide reflections on their involvement in given pieces.
> 
> One of the main questions that I have in mind is what the legal landscape of producing such a thing would entail.  At the very least, to actually call it a UNIX Programmer's Manual, it would probably need to pass some sort of compliance with the materials The Open Group publishes.  That said, the ownership of the IP as opposed to the trademarks is a little less certain, so I would be a bit curious who all would be involved in specifically getting copyright approval to publish anything that happened the commercial line after the early 80s, so like new text produced after 1982.  I presume anything covered by the Caldera license at least could be published at-cost, but not for a profit (which I'm not looking for anyway.)
> 
> Additionally, if possible, I'd love to run down some authorship information and make sure folks who wrote stuff up over time are properly credited, if not on each page ala OWNER at least in a Acknowledgements section in the front.
> 
> As far as production, I personally would want to do a run with a couple of different cover styles, comb bound, maybe one echoing the original Bell Laboratories UNIX User's Manual-style cover complete with Bell logo, another using the original USENIX Beastie cover, etc. but that also then calls into question more copyrights to coordinate, especially with the way the Bell logo is currently owned, that could get complicated.
> 
> Anywho, anyone know of any such efforts like this?  If I actually got such a project going in earnest, would folks find themselves interested in such a publication?  In any case I do intend to start on a typesetter sources version of this project sometime in the next year or so, but ideally I would want it to blossom into something that could result in some physical media.  This idea isn't even half-baked yet by the way, so just know I don't have a roadmap in place, it's just something I see being a cool potential project over the coming years.
> 
> - Matt G.

-- 
---
Larry McVoy           Retired to fishing          http://www.mcvoy.com/lm/boat

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Adam Thornton]

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

I would be very interested in this and haven't heard of anyone trying it.

I actually just came to post a question-which-is-really-a-gripe about man
pages, because this seems like the group that might be able to answer it,
and given the existence of this topic, it seems like the sort of thing that
should end up in the Definitive Unix Programmer's Manual.

Why (and when) did GNU drop the HISTORY section from its man pages?

It actually was really useful to me today to find out that sed appears in
v7, but cut didn't come along until AT&T System III.

I had to use a Mac's man pages, because the ones on my Linux systems don't
have HISTORY sections.

(this is in the context of: is there a better way to get the org/reponame
information from a git repository than

git ls-remote --get-url origin | sed -e "s|^origin$|$(git config --get
user.name)/$(basename $(pwd))" -e 's/\.git$//' | rev | cut -d / -f 1-2 |
cut -d : -f 1 | rev

The more elegant and complicated regex sed expressions that my
better-at-regex-than-I coworkers suggested to do away with rev-cut-rev do
not manage to work on both (currentish) Mac and Linux, which are my target
audience, Rubin Observatory development being split about 75/25; stripping
the possible trailing .git is about all I can count on working in both
environments' sed, but I can count on having *some* sed and coreutils.  If
anyone here has a better answer for getting that info out I'd appreciate it)

Adam

On Tue, Sep 19, 2023 at 1:32 PM segaloco via TUHS <tuhs@tuhs.org> wrote:

> I haven't known when or how to bring up this project idea, but figure I
> might as well start putting feelers out since my Dragon Quest project is
> starting to slow down and I might focus back on UNIX manual stuff.
>
> So something painfully missing from my and I'm sure plenty of other folks'
> libraries is a nice, modern paper UNIX manual that takes the past few
> decades into consideration.  The GNU project, BSDs, etc. ship manpages of
> course, and there's the POSIX manpages, but I'm a sucker for a good print
> manual.  Something I'm thinking of producing as a "deliverable" of sorts
> from my documentation research is a new-age UNIX manual, derived as closely
> as possible from the formal UNIX documentation lineages (so Research, SysV,
> and BSD pages), but:
>
>     1. Including subsequent POSIX requirements
>     2. Including an informational section in each page with a little
> history and some notes about current implementations, if applicable.  This
> would include notes about "dead on the vine" stuff like things plucked from
> the CB-UNIX, MERT/PG, and PWB lines.  The history part could even be a
> separate book, that way the manual itself could stay tight and focused.
> This would also be a good place for luminaries to provide reflections on
> their involvement in given pieces.
>
> One of the main questions that I have in mind is what the legal landscape
> of producing such a thing would entail.  At the very least, to actually
> call it a UNIX Programmer's Manual, it would probably need to pass some
> sort of compliance with the materials The Open Group publishes.  That said,
> the ownership of the IP as opposed to the trademarks is a little less
> certain, so I would be a bit curious who all would be involved in
> specifically getting copyright approval to publish anything that happened
> the commercial line after the early 80s, so like new text produced after
> 1982.  I presume anything covered by the Caldera license at least could be
> published at-cost, but not for a profit (which I'm not looking for anyway.)
>
> Additionally, if possible, I'd love to run down some authorship
> information and make sure folks who wrote stuff up over time are properly
> credited, if not on each page ala OWNER at least in a Acknowledgements
> section in the front.
>
> As far as production, I personally would want to do a run with a couple of
> different cover styles, comb bound, maybe one echoing the original Bell
> Laboratories UNIX User's Manual-style cover complete with Bell logo,
> another using the original USENIX Beastie cover, etc. but that also then
> calls into question more copyrights to coordinate, especially with the way
> the Bell logo is currently owned, that could get complicated.
>
> Anywho, anyone know of any such efforts like this?  If I actually got such
> a project going in earnest, would folks find themselves interested in such
> a publication?  In any case I do intend to start on a typesetter sources
> version of this project sometime in the next year or so, but ideally I
> would want it to blossom into something that could result in some physical
> media.  This idea isn't even half-baked yet by the way, so just know I
> don't have a roadmap in place, it's just something I see being a cool
> potential project over the coming years.
>
> - Matt G.
>

[-- Attachment #2: Type: text/html, Size: 6376 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[KenUnix]

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

Matt,

There was a book printed by Newnes titled UNIX pocket book. It covers
System-V Xenix, BSD 4.3, C-shell, plus the usual commands.

Also has sections dedicated to system administration, vi, rebuilding the
kernel, Bourne Shell, C-Shell, Korn Shell, etc...

It was written by Steve Heath 1998 "ISBN 0 7506 410 88" 340 pages. A good
read. Only problem, for my eyes it is physically too small.

-Ken


On Tue, Sep 19, 2023 at 4:32 PM segaloco via TUHS <tuhs@tuhs.org> wrote:

> I haven't known when or how to bring up this project idea, but figure I
> might as well start putting feelers out since my Dragon Quest project is
> starting to slow down and I might focus back on UNIX manual stuff.
>
> So something painfully missing from my and I'm sure plenty of other folks'
> libraries is a nice, modern paper UNIX manual that takes the past few
> decades into consideration.  The GNU project, BSDs, etc. ship manpages of
> course, and there's the POSIX manpages, but I'm a sucker for a good print
> manual.  Something I'm thinking of producing as a "deliverable" of sorts
> from my documentation research is a new-age UNIX manual, derived as closely
> as possible from the formal UNIX documentation lineages (so Research, SysV,
> and BSD pages), but:
>
>     1. Including subsequent POSIX requirements
>     2. Including an informational section in each page with a little
> history and some notes about current implementations, if applicable.  This
> would include notes about "dead on the vine" stuff like things plucked from
> the CB-UNIX, MERT/PG, and PWB lines.  The history part could even be a
> separate book, that way the manual itself could stay tight and focused.
> This would also be a good place for luminaries to provide reflections on
> their involvement in given pieces.
>
> One of the main questions that I have in mind is what the legal landscape
> of producing such a thing would entail.  At the very least, to actually
> call it a UNIX Programmer's Manual, it would probably need to pass some
> sort of compliance with the materials The Open Group publishes.  That said,
> the ownership of the IP as opposed to the trademarks is a little less
> certain, so I would be a bit curious who all would be involved in
> specifically getting copyright approval to publish anything that happened
> the commercial line after the early 80s, so like new text produced after
> 1982.  I presume anything covered by the Caldera license at least could be
> published at-cost, but not for a profit (which I'm not looking for anyway.)
>
> Additionally, if possible, I'd love to run down some authorship
> information and make sure folks who wrote stuff up over time are properly
> credited, if not on each page ala OWNER at least in a Acknowledgements
> section in the front.
>
> As far as production, I personally would want to do a run with a couple of
> different cover styles, comb bound, maybe one echoing the original Bell
> Laboratories UNIX User's Manual-style cover complete with Bell logo,
> another using the original USENIX Beastie cover, etc. but that also then
> calls into question more copyrights to coordinate, especially with the way
> the Bell logo is currently owned, that could get complicated.
>
> Anywho, anyone know of any such efforts like this?  If I actually got such
> a project going in earnest, would folks find themselves interested in such
> a publication?  In any case I do intend to start on a typesetter sources
> version of this project sometime in the next year or so, but ideally I
> would want it to blossom into something that could result in some physical
> media.  This idea isn't even half-baked yet by the way, so just know I
> don't have a roadmap in place, it's just something I see being a cool
> potential project over the coming years.
>
> - Matt G.
>


-- 
End of line
JOB TERMINATED

[-- Attachment #2: Type: text/html, Size: 4502 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[segaloco via TUHS]

> I'd start with groff.
> 
> So I'm a little off topic but if people wanted to work on that, I'd be
> up for that project. It's not as big as what you are saying but it's
> pretty big, I think we just start with something, see if we can get
> debian/ubuntu to pick it up, lather, rinse repeat. In fact if we
> just get the groff project to pick up our stuff, all the distros will
> get that eventually.
> 
> --
> ---
> Larry McVoy Retired to fishing http://www.mcvoy.com/lm/boat

That's an excellent point, the beauty of UNIX being a granular system is that such an effort wouldn't need to be a "start at page 1 and finish at page whatever", but could be done piecemeal.  Groff would also be a great candidate due to the preponderance of supporting secondary papers, like the NROFF/TROFF manual, different macro definitions, etc.  That does then get into the prospect of the secondary papers too, likewise excellent references to this day on a number of subjects that I personally would love to have modernized versions of.

Well if anyone catches wind of such a project kicking off in some way elsewhere, know that I'm certainly interested in what I can contribute.  What my work towards this eventual goal will probably continue to look like for now though is just doing my diff analysis of manual versions, as one of my principle goals there was to identify the apparent last common ancestor of Research, PWB, and BSD lineages, at least as far as documentation is concerned.  Common sense would just say research V7 but there are little tidbits here and there between V6 and V7 that don't show up in other places, just tiny little nuanced things for the most part.  I haven't done this part of the analysis at all but a causal glance at a 32V manual diffed with a V7 manual reveals some changes that don't appear to be related to the portability work.  But I'm not going to comment on that further without analysis to back it up, just some anecdotal observations at present.

> Why (and when) did GNU drop the HISTORY section from its man pages?
>
> Adam

Did GNU ever have a HISTORY section?  I just plucked a couple books off the shelf, I don't see HISTORY in the V10, 4.4BSD, or SVR4 books, so probably a later invention in the BSD line that didn't get picked up by other UNIX-likes?  Looking at a few illumos manpages, they also don't appear to have a HISTORY section.  They appear to be there on macOS, probably as a result of the FreeBSD origins of macOS user space.  That said, I also appreciate the HISTORY section, it's tipped me off to things to study that I didn't know on a few occasions.

- Matt G.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[segaloco via TUHS]

> > I'd start with groff.
> > 
> > So I'm a little off topic but if people wanted to work on that, I'd be
> > up for that project. It's not as big as what you are saying but it's
> > pretty big, I think we just start with something, see if we can get
> > debian/ubuntu to pick it up, lather, rinse repeat. In fact if we
> > just get the groff project to pick up our stuff, all the distros will
> > get that eventually.
> > 
> > --
> > ---
> > Larry McVoy Retired to fishing http://www.mcvoy.com/lm/boat
> 
> 
> That's an excellent point, the beauty of UNIX being a granular system is that such an effort wouldn't need to be a "start at page 1 and finish at page whatever", but could be done piecemeal. Groff would also be a great candidate due to the preponderance of supporting secondary papers, like the NROFF/TROFF manual, different macro definitions, etc. That does then get into the prospect of the secondary papers too, likewise excellent references to this day on a number of subjects that I personally would love to have modernized versions of.
> 
> Well if anyone catches wind of such a project kicking off in some way elsewhere, know that I'm certainly interested in what I can contribute. What my work towards this eventual goal will probably continue to look like for now though is just doing my diff analysis of manual versions, as one of my principle goals there was to identify the apparent last common ancestor of Research, PWB, and BSD lineages, at least as far as documentation is concerned. Common sense would just say research V7 but there are little tidbits here and there between V6 and V7 that don't show up in other places, just tiny little nuanced things for the most part. I haven't done this part of the analysis at all but a causal glance at a 32V manual diffed with a V7 manual reveals some changes that don't appear to be related to the portability work. But I'm not going to comment on that further without analysis to back it up, just some anecdotal observations at present.
> 
> > Why (and when) did GNU drop the HISTORY section from its man pages?
> > 
> > Adam
> 
> 
> Did GNU ever have a HISTORY section? I just plucked a couple books off the shelf, I don't see HISTORY in the V10, 4.4BSD, or SVR4 books, so probably a later invention in the BSD line that didn't get picked up by other UNIX-likes? Looking at a few illumos manpages, they also don't appear to have a HISTORY section. They appear to be there on macOS, probably as a result of the FreeBSD origins of macOS user space. That said, I also appreciate the HISTORY section, it's tipped me off to things to study that I didn't know on a few occasions.
> 
> - Matt G.

Sorry for the double bump, don't want to lie, just found a few pages in the 4.4BSD manual with a HISTORY section.  Checked the same pages in V10, SVR4, and 4.3BSD, no dice, so maybe 4.4BSD at the earliest?  Of course I could just grep this but where's the fun in that (and I'm not at a computer I have a UNIX tree on right now...)

- Matt G.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Clem Cole]

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

+1
ᐧ

On Tue, Sep 19, 2023 at 6:39 PM Larry McVoy <lm@mcvoy.com> wrote:

> One of the projects I thought I'd do in my retirement, but haven't done,
> was to provide man page / paper as in "a paper", not tree paper, versions
> of all the GNU info stuff.  I could not be less thrilled with info, yeah
> there are ways to deal, but it just isn't as good (to me) as how Unix did
> docs.  It's like they want to force emacs on us to read docs.
>
> I'd start with groff.
>
> So I'm a little off topic but if people wanted to work on that, I'd be
> up for that project.  It's not as big as what you are saying but it's
> pretty big, I think we just start with something, see if we can get
> debian/ubuntu to pick it up, lather, rinse repeat.  In fact if we
> just get the groff project to pick up our stuff, all the distros will
> get that eventually.
>
> The one drawback I see is people might want to provide info and man
> docs.  My personal preference is that the info stuff goes away but I
> have learned I don't get what I want.  So there may be a period of
> time where both need to be maintained.
>
> On Tue, Sep 19, 2023 at 08:32:15PM +0000, segaloco via TUHS wrote:
> > I haven't known when or how to bring up this project idea, but figure I
> might as well start putting feelers out since my Dragon Quest project is
> starting to slow down and I might focus back on UNIX manual stuff.
> >
> > So something painfully missing from my and I'm sure plenty of other
> folks' libraries is a nice, modern paper UNIX manual that takes the past
> few decades into consideration.  The GNU project, BSDs, etc. ship manpages
> of course, and there's the POSIX manpages, but I'm a sucker for a good
> print manual.  Something I'm thinking of producing as a "deliverable" of
> sorts from my documentation research is a new-age UNIX manual, derived as
> closely as possible from the formal UNIX documentation lineages (so
> Research, SysV, and BSD pages), but:
> >
> >     1. Including subsequent POSIX requirements
> >     2. Including an informational section in each page with a little
> history and some notes about current implementations, if applicable.  This
> would include notes about "dead on the vine" stuff like things plucked from
> the CB-UNIX, MERT/PG, and PWB lines.  The history part could even be a
> separate book, that way the manual itself could stay tight and focused.
> This would also be a good place for luminaries to provide reflections on
> their involvement in given pieces.
> >
> > One of the main questions that I have in mind is what the legal
> landscape of producing such a thing would entail.  At the very least, to
> actually call it a UNIX Programmer's Manual, it would probably need to pass
> some sort of compliance with the materials The Open Group publishes.  That
> said, the ownership of the IP as opposed to the trademarks is a little less
> certain, so I would be a bit curious who all would be involved in
> specifically getting copyright approval to publish anything that happened
> the commercial line after the early 80s, so like new text produced after
> 1982.  I presume anything covered by the Caldera license at least could be
> published at-cost, but not for a profit (which I'm not looking for anyway.)
> >
> > Additionally, if possible, I'd love to run down some authorship
> information and make sure folks who wrote stuff up over time are properly
> credited, if not on each page ala OWNER at least in a Acknowledgements
> section in the front.
> >
> > As far as production, I personally would want to do a run with a couple
> of different cover styles, comb bound, maybe one echoing the original Bell
> Laboratories UNIX User's Manual-style cover complete with Bell logo,
> another using the original USENIX Beastie cover, etc. but that also then
> calls into question more copyrights to coordinate, especially with the way
> the Bell logo is currently owned, that could get complicated.
> >
> > Anywho, anyone know of any such efforts like this?  If I actually got
> such a project going in earnest, would folks find themselves interested in
> such a publication?  In any case I do intend to start on a typesetter
> sources version of this project sometime in the next year or so, but
> ideally I would want it to blossom into something that could result in some
> physical media.  This idea isn't even half-baked yet by the way, so just
> know I don't have a roadmap in place, it's just something I see being a
> cool potential project over the coming years.
> >
> > - Matt G.
>
> --
> ---
> Larry McVoy           Retired to fishing
> http://www.mcvoy.com/lm/boat
>

[-- Attachment #2: Type: text/html, Size: 5620 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Adam Thornton]

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

Yeah, I'm less angry at GNU now--I didn't search as hard, but when I found
out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still
actively-ish maintained) then I figured it wasn't something classical that
GNU dropped, just never imported.  I feel like it existed on SunOS and
Solaris but I might be wrong about that?  Was it really FreeBSD that
introduced it?

Adam

[-- Attachment #2: Type: text/html, Size: 488 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[segaloco via TUHS]

> Yeah, I'm less angry at GNU now--I didn't search as hard, but when I found out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still actively-ish maintained) then I figured it wasn't something classical that GNU dropped, just never imported. I feel like it existed on SunOS and Solaris but I might be wrong about that? Was it really FreeBSD that introduced it?
> 
> Adam

As per my silly bump (really I hate double messages, I'm probably being harder on myself than any of you would be :P) it seems there are some HISTORY sections in the print 4.4BSD set I have on my shelf.  The pages I did spot the section in do not have it in the corresponding 4.3BSD volumes, although I'm basing this on a casual flip through paper books at present, not looking down in /usr/man on any given distro.  None of the Bell-adjacent stuff I've flipped through has any HISTORY sections though.

- Matt G.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Jeremy C. Reed]

> Additionally, if possible, I'd love to run down some authorship 
> information and make sure folks who wrote stuff up over time are 
> properly credited, if not on each page ala OWNER at least in a 
> Acknowledgements section in the front.

My NetBSD section 8 was two long printed book volumes.

68 printed pages 1461 through 1529 had 109 different licences (no 
duplicate verbiage) and corresponding copyrights and required 
acknowledgement statements.

The permuted index was also 68 pages long.

The books will be several volumes long and likely ten thousand of 
pages.

(Not very many sold, it was large learning project.)

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[markus schnalke]

Hoi.

[2023-09-20 06:16] "Jeremy C. Reed" <reed@reedmedia.net>
> > Additionally, if possible, I'd love to run down some authorship 
> > information and make sure folks who wrote stuff up over time are 
> > properly credited, if not on each page ala OWNER at least in a 
> > Acknowledgements section in the front.
> 
> My NetBSD section 8 was two long printed book volumes.
> 
> 68 printed pages 1461 through 1529 had 109 different licences (no 
> duplicate verbiage) and corresponding copyrights and required 
> acknowledgement statements.
> 
> The permuted index was also 68 pages long.
> 
> The books will be several volumes long and likely ten thousand of 
> pages.
> 
> (Not very many sold, it was large learning project.)

Good point.

Original manpages reprinted and collected would not interest me
much. That stuff is available online and to me more a reference
than something I take to bed reading in the evening. This kind of
content also leads to the copyright annoyance described above.

Much more am I interested in something like Doug's Unix Reader,
i.e. commented history and folklore around the tools, collected and
arranged. Of course, this is much more work, but it's more original
work and to me of greater uniqueness and value.

Thus, let's make the manpages *only* contain the History section!
... plus Changes, Bugs, Quirks, Versions, Differences, ...

Of course, that would be the Unix Historian's Manual then. ;-)


meillo


P.S.
Adding good manpages to info-only or manpage-stub programs would be
a relief, too.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Chet Ramey]

On 9/19/23 7:43 PM, Adam Thornton wrote:

> Why (and when) did GNU drop the HISTORY section from its man pages?

We never had it. It originated with 4.4 BSD, and none of us picked it up.

-- 
``The lyf so short, the craft so long to lerne.'' - Chaucer
		 ``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Alejandro Colomar (man-pages)]

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

On Wed, Sep 20, 2023, 15:23 Chet Ramey <chet.ramey@case.edu> wrote:

> On 9/19/23 7:43 PM, Adam Thornton wrote:
>
> > Why (and when) did GNU drop the HISTORY section from its man pages?
>
> We never had it. It originated with 4.4 BSD, and none of us picked it up.
>

I recently added a HISTORY section to the Linux man-pages (chapters 2 and
3), and we moved there info that was scattered across various sections.  If
your plan includes man2 and man3, you could maybe just contribute some
extra details to those pages' HISTORY section and you're done with that
part.  We also produce a PDF book (this was done by Deri James from
gropdf): <https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/>.

Cheers,


> --
> ``The lyf so short, the craft so long to lerne.'' - Chaucer
>                  ``Ars longa, vita brevis'' - Hippocrates
> Chet Ramey, UTech, CWRU    chet@case.edu    http://tiswww.cwru.edu/~chet/
>
>

[-- Attachment #2: Type: text/html, Size: 1822 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Warner Losh]

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

On Wed, Sep 20, 2023, 2:30 AM segaloco via TUHS <tuhs@tuhs.org> wrote:

> > > I'd start with groff.
> > >
> > > So I'm a little off topic but if people wanted to work on that, I'd be
> > > up for that project. It's not as big as what you are saying but it's
> > > pretty big, I think we just start with something, see if we can get
> > > debian/ubuntu to pick it up, lather, rinse repeat. In fact if we
> > > just get the groff project to pick up our stuff, all the distros will
> > > get that eventually.
> > >
> > > --
> > > ---
> > > Larry McVoy Retired to fishing http://www.mcvoy.com/lm/boat
> >
> >
> > That's an excellent point, the beauty of UNIX being a granular system is
> that such an effort wouldn't need to be a "start at page 1 and finish at
> page whatever", but could be done piecemeal. Groff would also be a great
> candidate due to the preponderance of supporting secondary papers, like the
> NROFF/TROFF manual, different macro definitions, etc. That does then get
> into the prospect of the secondary papers too, likewise excellent
> references to this day on a number of subjects that I personally would love
> to have modernized versions of.
> >
> > Well if anyone catches wind of such a project kicking off in some way
> elsewhere, know that I'm certainly interested in what I can contribute.
> What my work towards this eventual goal will probably continue to look like
> for now though is just doing my diff analysis of manual versions, as one of
> my principle goals there was to identify the apparent last common ancestor
> of Research, PWB, and BSD lineages, at least as far as documentation is
> concerned. Common sense would just say research V7 but there are little
> tidbits here and there between V6 and V7 that don't show up in other
> places, just tiny little nuanced things for the most part. I haven't done
> this part of the analysis at all but a causal glance at a 32V manual diffed
> with a V7 manual reveals some changes that don't appear to be related to
> the portability work. But I'm not going to comment on that further without
> analysis to back it up, just some anecdotal observations at present.
> >
> > > Why (and when) did GNU drop the HISTORY section from its man pages?
> > >
> > > Adam
> >
> >
> > Did GNU ever have a HISTORY section? I just plucked a couple books off
> the shelf, I don't see HISTORY in the V10, 4.4BSD, or SVR4 books, so
> probably a later invention in the BSD line that didn't get picked up by
> other UNIX-likes? Looking at a few illumos manpages, they also don't appear
> to have a HISTORY section. They appear to be there on macOS, probably as a
> result of the FreeBSD origins of macOS user space. That said, I also
> appreciate the HISTORY section, it's tipped me off to things to study that
> I didn't know on a few occasions.
> >
> > - Matt G.
>
> Sorry for the double bump, don't want to lie, just found a few pages in
> the 4.4BSD manual with a HISTORY section.  Checked the same pages in V10,
> SVR4, and 4.3BSD, no dice, so maybe 4.4BSD at the earliest?  Of course I
> could just grep this but where's the fun in that (and I'm not at a computer
> I have a UNIX tree on right now...)
>

4.4BSD almost certainly had some history. All the current BSDs have a
HISTORY section for many of their pages. And we are busy borrowing each
other's primary research for them... though it a man page, not a treatis on
the evolution of signals since V7. Nor do the vast majority of command line
flags have mention. Those that do are either 4BSD vs System V or XXXBSD vs
Linux (and maybe a few FooBSD vs BarBSD, but those are rare).

Warner

>

[-- Attachment #2: Type: text/html, Size: 4482 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Dan Cross]

On Wed, Sep 20, 2023 at 10:57 AM Warner Losh <imp@bsdimp.com> wrote:
> [snip]
> 4.4BSD almost certainly had some history. All the current BSDs have a HISTORY section for many of their pages. And we are busy borrowing each other's primary research for them... though it a man page, not a treatis on the evolution of signals since V7. Nor do the vast majority of command line flags have mention. Those that do are either 4BSD vs System V or XXXBSD vs Linux (and maybe a few FooBSD vs BarBSD, but those are rare).

My recollection is that the HISTORY stuff started showing up in BSD
man pages around the time of Net/2?

        - Dan C.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Larry McVoy]

On Tue, Sep 19, 2023 at 07:25:13PM -0700, Adam Thornton wrote:
> Yeah, I'm less angry at GNU now--I didn't search as hard, but when I found
> out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still
> actively-ish maintained) then I figured it wasn't something classical that
> GNU dropped, just never imported.  I feel like it existed on SunOS and
> Solaris but I might be wrong about that?  Was it really FreeBSD that
> introduced it?

I don't think SunOS had it.  The SunOS man pages were pretty terse, the
powers that be wanted just the facts.  I remember get beat up for putting
examples in some of the man pages I wrote, they got taken out "because
examples are for user guides, man pages are not user guides, they are a
reference guide" or something like that.

I like examples in man pages, I think it jump starts you into using the
program more easily but maybe that's just me.
-- 
---
Larry McVoy           Retired to fishing          http://www.mcvoy.com/lm/boat

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[segaloco via TUHS]

> > Yeah, I'm less angry at GNU now--I didn't search as hard, but when I found
> > out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still
> > actively-ish maintained) then I figured it wasn't something classical that
> > GNU dropped, just never imported. I feel like it existed on SunOS and
> > Solaris but I might be wrong about that? Was it really FreeBSD that
> > introduced it?
> 
> 
> I don't think SunOS had it. The SunOS man pages were pretty terse, the
> powers that be wanted just the facts. I remember get beat up for putting
> examples in some of the man pages I wrote, they got taken out "because
> examples are for user guides, man pages are not user guides, they are a
> reference guide" or something like that.
> 
> I like examples in man pages, I think it jump starts you into using the
> program more easily but maybe that's just me.
> --
> ---
> Larry McVoy Retired to fishing http://www.mcvoy.com/lm/boat

I'm glad I'm not the only one, do I find the dearth of examples on many reference manuals to be quite annoying.  The only compelling (to me) reason I've ever heard for flat out avoiding examples is to not imply best practices.  For instance, in my own work, there are times I purposefully have to not provide use-case examples of some generic bit I put together because then I find it gets used very narrowly, as if the example given is "how it should be used" rather than "a way it can be used".  Granted, that is a product of perception, not intention, so outright avoiding guidance altogether or not, you're always going to have people who read something and accept that as lore rather than just a helpful suggestion or narrow demonstration.  It's kinda like providing a reference implementation of some general interface or service.  If it works well and is general, folks are just going to use that reference implementation rather than customizing their own logic to drive the interface, defeating the purpose of trying to standardize an interface instead of just providing a distinct product.  Kinda like X these days, how many *new* X servers or clients have popped up lately?  Is everything X.org now?  I don't know enough to speculate on that but might serve as a good example.

Another way I think about that caveat is, say one is providing an example of fseek.  A narrow example of seeking to the end of a file would be an effective example, a perfect use-case for fseek.  However, presenting instead a bulkier example that demonstrates determining filesize *using* the fact you can fseek to the end and then ftell the position, while also demonstrating use of fseek perfectly well, might embed itself in someone's mind as suggesting *the* way to do this sort of thing in C.  Granted, again, that's up to user perception, but those are the kinds of scenarios that do give me pause when drafting examples for documentation: The concern that someone will take an example as an absolute in every angle that it touches.

I think in a full UNIX manual, constituting both volumes (or whatever other permutations of manpages and doc papers), it does make a bit more sense to keep examples terse because for many materials needing detail, one could simply cite the paper that is also considered a part of that standard documentation package.  Sadly with the fragmentary nature of documentation these days, that sort of packaged manual doesn't really exist anymore, and all of what would have gone into that arrangement of documents is out leading multiple lives as info, HTML pages, PDFs, etc probably from TeX sources.  /usr(/share)/doc is a thing of the past in its old way of being.  I guess these days what with the internet and all, it's less important for each and every scrap of information being succinctly accessible by a common mechanism on the system itself...but hoo boy would it be nice...I guess that's what they wanted info to be but...yeah that needs no further comment from me.

- Matt G.

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Alan Coopersmith]

On 9/19/23 19:25, Adam Thornton wrote:
> Yeah, I'm less angry at GNU now--I didn't search as hard, but when I found out 
> 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still 
> actively-ish maintained) then I figured it wasn't something classical that GNU 
> dropped, just never imported.  I feel like it existed on SunOS and Solaris but I 
> might be wrong about that?  Was it really FreeBSD that introduced it?

I just checked the nroff sources for the man pages from SunOS 3.0, 4.0, 4.1.4, 
and 5.0 (aka Solaris 2.0), and none of them had a "HISTORY" section, except
that the SunOS 4 man page for sail(6) has a "THE HISTORY OF SAIL" section.

I have been adding HISTORY sections to the Solaris 11.4 man pages over time,
but don't remember seeing any existing sections in our man pages that predate
this effort.  (And I'm only documenting the history in Solaris, leaving it to
others to document history in other OS'es.)

-- 
         -Alan Coopersmith-                 alan.coopersmith@oracle.com
          Oracle Solaris Engineering - https://blogs.oracle.com/solaris

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Dave Horsfall]

On Wed, 20 Sep 2023, Larry McVoy wrote:

[...]

> I like examples in man pages, I think it jump starts you into using the 
> program more easily but maybe that's just me.

No, it's not just you :-)

-- Dave

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Marc Donner]

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

Maybe it’s just you, but it’s just me too.

On Wed, Sep 20, 2023 at 3:57 PM Larry McVoy <lm@mcvoy.com> wrote:

> On Tue, Sep 19, 2023 at 07:25:13PM -0700, Adam Thornton wrote:
> > Yeah, I'm less angry at GNU now--I didn't search as hard, but when I
> found
> > out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still
> > actively-ish maintained) then I figured it wasn't something classical
> that
> > GNU dropped, just never imported.  I feel like it existed on SunOS and
> > Solaris but I might be wrong about that?  Was it really FreeBSD that
> > introduced it?
>
> I don't think SunOS had it.  The SunOS man pages were pretty terse, the
> powers that be wanted just the facts.  I remember get beat up for putting
> examples in some of the man pages I wrote, they got taken out "because
> examples are for user guides, man pages are not user guides, they are a
> reference guide" or something like that.
>
> I like examples in man pages, I think it jump starts you into using the
> program more easily but maybe that's just me.
> --
> ---
> Larry McVoy           Retired to fishing
> http://www.mcvoy.com/lm/boat
>

[-- Attachment #2: Type: text/html, Size: 1669 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Adam Thornton]

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

That's it, isn't it? Man pages are great if you a) already know the name of
the program you want (c'mon, apropos/man -k have never really worked that
well), and b) have at least a vague idea of how to use it.  If you want to
look up what a flag does, or whether there's a flag that does what you
need, they can't be beat.

But they aren't great for either exploration or discoverability.

Now, this is less of a problem when a command takes its input on stdin,
writes its output to stdout, any errors to stderr, and it has, like, five
or fewer different options.  For the use case of
programs-which-are-really-filter-stages designed to be connected via pipes,
and when there aren't all that many of them, it works fine.  Once something
else is on the table, yeah, the man page is at best incomplete and at worst
basically useless.

Say what you will about VMS, its HELP functionality makes it much easier to
go from "I want to do X" to "And here's a sequence of commands that will do
X" when you don't already have a good mental model of what's on the system.

Adam

[-- Attachment #2: Type: text/html, Size: 1266 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[G. Branden Robinson]

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

At 2023-09-20T20:06:27-0700, Adam Thornton wrote:
> That's it, isn't it? Man pages are great if you a) already know the
> name of the program you want (c'mon, apropos/man -k have never really
> worked that well),

I think that's less a technology problem than a human problem.  People
need to write the summary descriptions of a man page--that would be

.SH Name
this part \- right here

in a way that helps people find it.

Sure, you could use AI <cough> to scan the full texts of pages to try to
infer keywords, but I don't see that putting natural intelligence out of
business quite yet.

Man page authors labor under all kinds of crazy delusions about what can
go into the "Name" section.  Some people seem to think there's a length
limit.  Some seem to think that the summary description has to fit on
one _input line_, as if filling is disabled when it's read.

> But they aren't great for either exploration or discoverability.

I got positive feedback on the groff development list regarding
precisely these points when (1) revising its ~60 man pages to give them
more helpful summary descriptions and (2) compiling them into a
navigable PDF.

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

> Say what you will about VMS, its HELP functionality makes it much
> easier to go from "I want to do X" to "And here's a sequence of
> commands that will do X" when you don't already have a good mental
> model of what's on the system.

My experience with VMS is far too limited (and 30 years out of date) to
offer any comparison here, but I do agree that man pages are frequently
unhelpful when it comes to synthesis of the components they document.

Taking the "Examples" section more seriously might help with this.

At the same time I get that it's really tempting to punt.  "If it's not
documenting this discrete element of the system," people want to say,
"it doesn't belong in the man page".  I sympathize with that perspective
only insofar as the people who say this then proceed to offer some
alternative form of documentation that does.  If they don't, then I
suspect this professed piety about modular design to be a mask for
unwillingness to do work that needs doing.

Regards,
Branden

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

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Phil Budne]

Adam Thornton:
> Say what you will about VMS, its HELP functionality makes it much easier to
> go from "I want to do X" to "And here's a sequence of commands that will do
> X" when you don't already have a good mental model of what's on the system.

I'm reminded of two fourty-odd year old diatribes(*) against Unix
documentation, yet somehow the Unix model has persisted, while other
systems have long since been taken out with yesterdays ashbin of history.

My beef, coming from TOPS-20 with VMS "HELP" was that (in the days on
having a single dumb terminal on your desk) was if you couldn't
remember a switch midway through typing a command you had to erase it,
wade through multiple levels of HELP screens, cancel out of that, and
then type the switch, until you realized you needed another switch.
On TOPS-20 you just typed ?

Yes, I suppose Unix-like systems could have section of pages with
overviews of functional areas (tho to be fair, v6/v7 era Unix didn't
have any facilities complex enough to warrant such things).

And it depends on which Unix-like system: "man 4 inet" on FreeBSD is a
more useful intro to TCP/IP socket programming than anything I can
find on my Ubuntu 22.04 system.  However, the FreeBSD man page
(unhelpfully) references two 4.3 BSD Interprocess Communication
Tutorials with no obvious information on how to find them.

(*) For diatribe #1 search for: "Last night I dreamed that the Real
World had adopted the Unix Philosophy".  For #2 search for "it's
literally a five-foot shelf of documentation"

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[G. Branden Robinson]

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

Hi Larry,

At 2023-09-19T16:39:25-0700, Larry McVoy wrote:
> One of the projects I thought I'd do in my retirement, but haven't
> done, was to provide man page / paper as in "a paper", not tree paper,
> versions of all the GNU info stuff.  I could not be less thrilled with
> info, yeah there are ways to deal, but it just isn't as good (to me)
> as how Unix did docs.  It's like they want to force emacs on us to
> read docs.
> 
> I'd start with groff.
> 
> So I'm a little off topic but if people wanted to work on that, I'd be
> up for that project.  It's not as big as what you are saying but it's
> pretty big, I think we just start with something, see if we can get
> debian/ubuntu to pick it up, lather, rinse repeat.

You have raised this issue before (multiple times) so I will remind you
that I'm working on this.

$ COLUMNS=72 git diff --stat 1.22.4 1.23.0 man/{roff,groff{,_font,_out}}.*.man
 man/groff.7.man      | 9853 ++++++++++++++++++++++++++++--------------
 man/groff_font.5.man | 1269 ++++--
 man/groff_out.5.man  | 1035 +++--
 man/roff.7.man       | 2973 +++++++++----
 4 files changed, 9991 insertions(+), 5139 deletions(-)

Check out the compiled groff man pages PDF.  I'm open to your critiques
but I'd prefer you made then when I could be confident that had recently
familiarized yourself with the problem.

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

> The one drawback I see is people might want to provide info and man
> docs.  My personal preference is that the info stuff goes away but I
> have learned I don't get what I want.  So there may be a period of
> time where both need to be maintained.

I have no particular love for Texinfo, but it really is trying to do a
somewhat different thing than a man page does.  As Trent Fisher and
Werner Lemberg left it, groff's Texinfo manual felt (to me) influenced
by the O'Reilly Nutshell book approach.  And that's not a bad thing.  It
converses with and guides the reader in a way that classically laconic
Unix man pages don't.

Since Bertrand released groff 1.23.0 in July, I've further whacked on
the early chapters of the groff Texinfo manual (among other things).
You can find a bleeding edge version here.

https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0

But if someone simply refuses to read the Texinfo manual, I've tried to
make roff(7) an introduction to the formatting language and further
developed groff(1) as a general introduction from the command-line
perspective.

I think we're deep into the "maintain both" period:

$ grep -n '@c.*parallel' doc/groff.texi
584:@c BEGIN Keep parallel with groff(1), section "Description" (after the
602:@c END Keep parallel with groff(1), section "Description" (after the
605:@c BEGIN Keep parallel with groff(1), section "Usage" (introduction).
616:@c END Keep parallel with groff(1), section "Usage" (introduction).
1591:@c BEGIN Keep parallel with groff(1), subsection "Paper format".
1626:@c END Keep parallel with groff(1), subsection "Paper format".
1631:@c BEGIN Keep parallel with groff(1), section "Examples".
1696:@c END Keep parallel with groff(1), section "Examples".
5036:@c BEGIN Keep roughly parallel with roff(7) section "Concepts".
5342:@c END Keep roughly parallel with roff(7) section "Concepts".
5561:@c TODO: Consider parallelizing with groff_tmac(5) "Description".
5934:@c BEGIN Keep (roughly) parallel with section "Measurements" of
6052:@c END Keep (roughly) parallel with section "Measurements" of groff(7).
...
16963:@c BEGIN Keep parallel with section "Warnings" of troff(1).
17138:@c END Keep parallel with section "Warnings" of troff(1).
17568:@c BEGIN TODO: Make parallel with groff_out(5).
18448:@c END TODO: Make parallel with groff_out(5).
18453:@c BEGIN Keep parallel with groff_font(5).
18940:@c END Keep parallel with groff_font(5).

Yes, these are screeching examples of DRY violation.  But such
violations are warranted if doing so means that users have a fighting
chance to obtain competence with the system being documented.

Regards,
Branden

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

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Wesley Parish]

On 21/09/23 10:31, Dave Horsfall wrote:
> On Wed, 20 Sep 2023, Larry McVoy wrote:
>
> [...]
>
>> I like examples in man pages, I think it jump starts you into using the
>> program more easily but maybe that's just me.
> No, it's not just you :-)
>
> -- Dave

Seconded. IDK when I was learning Linux, how many times I would've been 
unable to follow the reference in the Linux man pages without a 
reference example or more to show me how I could do it myself.

Wesley Parish

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[John P. Linderman]

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

One of the things I liked about Mark Rochkind's original "Advanced UNIX
Programming" book was that he not only provided examples of what to do, but
also examples of what NOT to do, like failing to close the write end of a
pipe in a child that expects to read input. I'm not sure manual pages are
the right place for this sort of thing, but it certainly is valuable.

On Thu, Sep 21, 2023 at 12:10 AM Wesley Parish <wobblygong@gmail.com> wrote:

> On 21/09/23 10:31, Dave Horsfall wrote:
> > On Wed, 20 Sep 2023, Larry McVoy wrote:
> >
> > [...]
> >
> >> I like examples in man pages, I think it jump starts you into using the
> >> program more easily but maybe that's just me.
> > No, it's not just you :-)
> >
> > -- Dave
>
> Seconded. IDK when I was learning Linux, how many times I would've been
> unable to follow the reference in the Linux man pages without a
> reference example or more to show me how I could do it myself.
>
> Wesley Parish
>
>

[-- Attachment #2: Type: text/html, Size: 1411 bytes --]

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Theodore Ts'o]

On Wed, Sep 20, 2023 at 12:56:35PM -0700, Larry McVoy wrote:
> On Tue, Sep 19, 2023 at 07:25:13PM -0700, Adam Thornton wrote:
> > Yeah, I'm less angry at GNU now--I didn't search as hard, but when I found
> > out 4.3BSD didn't have HISTORY (and neither does 2.11BSD, which is still
> > actively-ish maintained) then I figured it wasn't something classical that
> > GNU dropped, just never imported.  I feel like it existed on SunOS and
> > Solaris but I might be wrong about that?  Was it really FreeBSD that
> > introduced it?
> 
> I don't think SunOS had it.  The SunOS man pages were pretty terse, the
> powers that be wanted just the facts.  I remember get beat up for putting
> examples in some of the man pages I wrote, they got taken out "because
> examples are for user guides, man pages are not user guides, they are a
> reference guide" or something like that.

These days, I find the much more useful sections are VERSIONS and
STANDARDS, e.g.:

VERSIONS
	openat() was added in Linux 2.6.16; library support was added
       in glibc 2.4.

STANDARDS
       open(), creat() SVr4, 4.3BSD, POSIX.1‐2001, POSIX.1‐2008.

       openat(): POSIX.1‐2008.

       openat2(2) is Linux‐specific.

       The O_DIRECT, O_NOATIME, O_PATH, and O_TMPFILE flags are
       Linux‐specific.  One must define _GNU_SOURCE to obtain their
       definitions.

       The O_CLOEXEC, O_DIRECTORY, and O_NOFOLLOW flags are not
       specified in POSIX.1‐2001, but are specified in POSIX.1‐2008.
       Since glibc 2.12, one can obtain their definitions by defining
       either _POSIX_C_SOURCE with a value greater than or equal to
       200809L or _XOPEN_SOURCE with a value greater than or equal to
       700.  In glibc 2.11 and earlier, one obtains the definitions by
       defining _GNU_SOURCE.

       As noted in feature_test_macros(7), feature test macros such as
       _POSIX_C_SOURCE, _XOPEN_SOURCE, and _GNU_SOURCE must be defined
       before including any header files.

						- Ted

[TUHS] Re: Project Idea: The UNIX Programmer's Manual: Heritage Edition

[Kenneth Goodwin]

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

On the copyright issue

My humble opinion is you would have less trouble with getting authorization
if you do the following

1. Maintain all the original authorship/copyright information for the
documents.

2. Charge no more than cost plus shipping so it is nonprofit

3. Optionally add an uptick charge to the costs for charitable
contributions and send those donations to a charity of your/group choice.
I would recommend picking one or more of the computer museums to use as the
charity.
The donations therefore going to support the preservation of the history of
computing worldwide. This should be something of collective interest that
most people and authors/copyright holders could support and endorse.

On Tue, Sep 19, 2023, 4:32 PM segaloco via TUHS <tuhs@tuhs.org> wrote:

> I haven't known when or how to bring up this project idea, but figure I
> might as well start putting feelers out since my Dragon Quest project is
> starting to slow down and I might focus back on UNIX manual stuff.
>
> So something painfully missing from my and I'm sure plenty of other folks'
> libraries is a nice, modern paper UNIX manual that takes the past few
> decades into consideration.  The GNU project, BSDs, etc. ship manpages of
> course, and there's the POSIX manpages, but I'm a sucker for a good print
> manual.  Something I'm thinking of producing as a "deliverable" of sorts
> from my documentation research is a new-age UNIX manual, derived as closely
> as possible from the formal UNIX documentation lineages (so Research, SysV,
> and BSD pages), but:
>
>     1. Including subsequent POSIX requirements
>     2. Including an informational section in each page with a little
> history and some notes about current implementations, if applicable.  This
> would include notes about "dead on the vine" stuff like things plucked from
> the CB-UNIX, MERT/PG, and PWB lines.  The history part could even be a
> separate book, that way the manual itself could stay tight and focused.
> This would also be a good place for luminaries to provide reflections on
> their involvement in given pieces.
>
> One of the main questions that I have in mind is what the legal landscape
> of producing such a thing would entail.  At the very least, to actually
> call it a UNIX Programmer's Manual, it would probably need to pass some
> sort of compliance with the materials The Open Group publishes.  That said,
> the ownership of the IP as opposed to the trademarks is a little less
> certain, so I would be a bit curious who all would be involved in
> specifically getting copyright approval to publish anything that happened
> the commercial line after the early 80s, so like new text produced after
> 1982.  I presume anything covered by the Caldera license at least could be
> published at-cost, but not for a profit (which I'm not looking for anyway.)
>
> Additionally, if possible, I'd love to run down some authorship
> information and make sure folks who wrote stuff up over time are properly
> credited, if not on each page ala OWNER at least in a Acknowledgements
> section in the front.
>
> As far as production, I personally would want to do a run with a couple of
> different cover styles, comb bound, maybe one echoing the original Bell
> Laboratories UNIX User's Manual-style cover complete with Bell logo,
> another using the original USENIX Beastie cover, etc. but that also then
> calls into question more copyrights to coordinate, especially with the way
> the Bell logo is currently owned, that could get complicated.
>
> Anywho, anyone know of any such efforts like this?  If I actually got such
> a project going in earnest, would folks find themselves interested in such
> a publication?  In any case I do intend to start on a typesetter sources
> version of this project sometime in the next year or so, but ideally I
> would want it to blossom into something that could result in some physical
> media.  This idea isn't even half-baked yet by the way, so just know I
> don't have a roadmap in place, it's just something I see being a cool
> potential project over the coming years.
>
> - Matt G.
>

[-- Attachment #2: Type: text/html, Size: 4656 bytes --]