Why no cd(1) man page in Ubuntu? (was: man-intro)

[G. Branden Robinson]

Hi Clarke,

At 2021-05-22T21:09:56-0600, Clarke Echols wrote:
> I don't know why that would occur...
> 
> (Aside note):
> [In the HP-UX Reference Manual (HP's Unix which was POSIX compliant) I
> produced in late 1992, which contained all manpages, there is a
> manpage included in Volume 1 on page 91 and 92 with the heading at the
> top of each past: "cd(1)".  The manual contains 3000 pages in 3
> volumes.  I was solely responsible for maintaining HP-UX Reference
> manpages, including typesetting, man macros for producing print-ready
> artwork as well as page-layout and design for all HP-UX Reference
> manuals for HP-UX 7.0, 8.x, and 9.0 from June 1989 through the end of
> 1992.
> 
> I had sole control over the master source-code files for troff files
> used to produce it.  Nobody had access permission to alter the files
> for all change requests from HP-UX software engineers from assorted
> software labs.  The HP-UX 9.0 edition was produced from 1453 total
> troff files.
> 
> I also forced the change in HP's HP-UX manuals from 3-ring binders to
> soft-cover bound books.  It cut production costs by millions of
> dollars.  I'm also the original author and creator of the title" "The
> Ultimate Guide to the Vi and Ex Text Editors" along with convincing
> management to get it into bookstores.  I wrote the original in 1987,
> it was still selling on Amazon in 2018, and a recent Google search I
> made for the title as quoted above produced more than approximately10
> million (!!) search results.]   (End note)
> 
> But when I issue command "man cd", I get the same error.
> 
> I'm running Ubuntu 20.04.  Who's minding the store?

The problem is shared by Debian, with which I am affiliated (albeit
minimally active), and upon which Ubuntu bases its distribution, so I
reckon Debian has to wear some responsibility for this.  "cd" is
documented along with all of the other bash built-in commands in
bash-builtins(7), and "man builtins" suffices to bring up that page.
That "man cd" does not is disappointing.

But as a Unix expert of long pedigree (unfurled above), you must surely
already appreciate why "cd" in particular is a tricky case.

Commands get man pages.  So do library functions, system calls, device
interfaces, and file formats.

"cd" is none of these.

cd is internal to the shell, as it has been since the earliest versions
of Unix (albeit under the name "chdir" in First Edition)[1].  You may
recall that the current working directory is a property of a Unix
process.  Programs are run in Unix by creating a duplicate of the
currently running process (fork(2)) and then overlaying certain portions
of that process's image in memory with replacements from an executable
stored on disk (including its machine language instructions, termed
"text" in a strongly non-roffish sense) (exec(2)).

Once a process has been forked, it leads a mostly independent existence
from its parent.  One of the many things that don't remain coupled is
the current working directory.  As a consequence, implementing cd as an
"external command" (like ls(1) or cat(1)) would be pointless.  It could
be launched, called chdir(2) to change its own current working
directory, and then exit, leaving its parent utterly unaltered, like
Marvin Misnky's useless machine that produces a mechanical hand from
within a box to flip a switch turning itself back off.

To return to the instant problem, I am surprised that man-db, the Debian
(and now GNU man(1)) implementation, did not index all of the items in
the apropos line of bash-builtins(7) such that they would be found...

Oh, I see the problem.  The list of programs is in the Synopsis section,
not the Name section, where any apropos(1) implementation expects them.

  BASH‐BUILTINS(7)  Miscellaneous Information Manual  BASH‐BUILTINS(7)

  NAME
         bash‐builtins - bash built‐in commands, see bash(1)

  SYNOPSIS
         bash defines the following built‐in commands: :, ., [, alias,
         bg, bind, break, builtin, case, cd,  command,  compgen,  com‐
         plete,  continue,  declare, dirs, disown, echo, enable, eval,
         exec, exit, export, fc, fg, getopts, hash, help, history, if,
         jobs,  kill,  let,  local,  logout, popd, printf, pushd, pwd,
         read, readonly, return, set, shift, shopt,  source,  suspend,
         test, times, trap, type, typeset, ulimit, umask, unalias, un‐
         set, until, wait, while.

One traditional solution to this sort of problem is to install a man
page that simply sources another man page.

For example...

$ cat > /usr/share/man/man1/cd.1
.so man7/bash-builtins.7

Symbolic links are another possibility.  And because many different
shells exist, and all must implement some subset of those supported by
GNU Bash and either be useless or doomed to unpopularity, Debian's more
elaborate "alternatives" mechanism supported by dpkg(1) may be required
to manage the situation.

Alternatively, anyone not using the system's default login shell could
be assumed to be sophisticated enough to know about shells and the
distinction between built-ins and commands external to the shell
interpreter.

> "Freedom comes from seeing the ignorance
> of your critics and discovering the
> emptiness of their virtue"  - Ayn Rand -
>  (as quoted by Robert Ringer)

Regards,
Branden

[1] see attached image

chdir.1.png
Description: PNG image

signature.asc
Description: PGP signature