Why no cd(1) man page in Ubuntu? (was: man-intro)
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 so
Re: man-intro
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? Clarke On 5/22/21 3:42 PM, Ulrich Lauther wrote: On Sat, May 22, 2021 at 08:18:41PM +0200, Oliver Corff wrote: "man cd", on the other hand, opens the bash built-in command *man page*, which, at least on my system is a plethora of text to read (and digest). on my sytem (ubunto mate) "man cd" results in "No manual entry for cd". Just my 2cents, ulrich -- Clarke Echols B2B Commercial Writer and Marketing Communications Specialist "Freedom comes from seeing the ignorance of your critics and discovering the emptiness of their virtue" - Ayn Rand - (as quoted by Robert Ringer)
Re: getting more out of man pages with less(1)
Hello.
|> Good idea. I've further changed the Subject: to reflect the flow of the
|> discussion.
...
|> I also wonder if the pager wars are basically over and less(1) won them.
|
|That's certainly what I thought...
..
Ever since less(1) started supporting OSC 8 "Hyperlinks in
Terminal Emulators" as of version 566 i wanted to rewrite my
mdocmx(7) extension to be based upon the OSC 8 sequences that now
become more and more common.
So the last two days i finally made the great and implemented
OSC 8 for my mdoxmx macro package extension, as well as for grotty
v1.22.3 and less v586. Yay.
grotty was a bit hard because i wanted to implement all sorts of
OSC 8 things, even those they did not invent there in that github
repo, like document-local anchors and document-local "URI"s (i
used the usual "#REF" syntax used by eg HTML).
+// Place a document-local anchor; arg(s): 1=ID
+// (An OSC8 sequence without URI and INNER-TEXT.)
+{"anchor", sizeof("anchor") -1, a_ANCHOR, 1},
+// Link with inner text; arg(s): 1=URI, 2=INNER-TEXT
+{"link", sizeof("link") -1, a_LINK, 2},
+// Reference a document-local anchor; arg(s): 1=ID [2=INNER-TEXT]
+// If INNER-TEXT is missing ID is reused for that.
+{"link-anchor", sizeof("link-anchor") -1, a_LINK_ANCHOR, 2},
+// Reference a manual page; arg(s): 1=NAME 2=SECTION-NR [3=ID]
+// ID is optional, SECTION is manual section (eg "idle 2 55", "vi 1p").
+// This ends up as "man://NAME.SECTION", the inner text will be ID if ID
+// was given, otherwise "NAME(ID)".
+{"link-manual\0", sizeof("link-manual") -1, a_LINK_MANUAL, 3},
+// Link with externally controlled inner text; arg(s): 1=URI
+{"link-start", sizeof("link-start") -1, a_LINK_START, 1},
+// No arguments
+{"link-end", sizeof("link-end") -1, a_LINK_END, 0}
Eg \X'tty osc8 link-anchor 50' or \X'tty osc8 link-manual awk 79'.
The latter ends up like (here in blue as my mdocmx does it):
awk(1)^[[34m[^[]8;id=79;man://awk.1^[\79^[]8;;^[\]^[[0m
So for example (here formatted by my mdocmx macro extension):
SEE ALSO
awk(1)[79], ...
then in less(1) with the OSC 8 anchor-search patch, typing ^A:
[OSC 8 anchor]:
then typing 79 and return and one sees
Read external manual: !man 1 awk
and if you return return again that comes up.
One could think about dropping link-manual and simply offering
a $LESS_BROWSER or so hook, but like this some security checks can
be applied more easily. (Only fewest yet.)
I pushed the git mail-patch boxes to the git repo of my roff clone
that is still awaiting any actions. On Monday i will apply some
more content checking on the link-manual content in less(1) (in
grotty we already check cisprint before we create the OSC
8 sequence).
The nice thing with OSC 8 is that generators like docbook or so
could simply enwrap things like
.BR cat (1)
with \X'tty: osc8 link-start cat 1' and \X'tty: osc8 link-end'.
For my search patch for less(1) however this would not work out.
For now the less(1) OSC 8 search patch requires an id= though.
A nice sunday i wish from Germany.
--steffen
|
|Der Kragenbaer,The moon bear,
|der holt sich munter he cheerfully and one by one
|einen nach dem anderen runter wa.ks himself off
|(By Robert Gernhardt)
Re: man-intro
Ulrich Lauther wrote in <20210522214249.GA20730@starlite>: |On Sat, May 22, 2021 at 08:18:41PM +0200, Oliver Corff wrote: |> |> "man cd", on the other hand, opens the bash built-in command *man page*, |> which, at least on my system is a plethora of text to read (and digest). |> |on my sytem (ubunto mate) "man cd" results in "No manual entry for cd". Dunno Ubuntu but POSIX manuals (aka 1p, 3p ..) could be a separate package. They are definitely separate balls here: #?0|kent:$ ll /x/balls/man-pages/ total 2636K -rw-r--r-- 1 ports ports 1758092 Mar 28 00:57 man-pages-5.11.tar.xz -rw-r--r-- 1 ports ports 935196 Mar 28 00:57 man-pages-posix-2017-a.tar.xz drwsrwx--T 1 ports ports 100 Mar 28 01:55 ./ drwsrws--T+ 1 ports ports5616 May 22 17:51 ../ --steffen | |Der Kragenbaer,The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)
Re: man-intro
On Sat, May 22, 2021 at 08:18:41PM +0200, Oliver Corff wrote: > > "man cd", on the other hand, opens the bash built-in command *man page*, > which, at least on my system is a plethora of text to read (and digest). > on my sytem (ubunto mate) "man cd" results in "No manual entry for cd". > Just my 2cents, > ulrich
Re: Adding macro for code listings title to the mm macros.
On 5/18/21, Oliver Corff wrote: > Wouldn't it be a good idea to collect macros of this kind (and previous > contributions to this list) in a contrib directory? Since Mike Bianchi proposed a similar idea a couple years ago (http://lists.gnu.org/archive/html/groff/2018-11/msg00028.html), I've been thinking there ought to be a web repository or wiki to collect useful roff snippets that don't merit their own macro package or inclusion in the official distro. But someone would have to maintain and curate this archive, and while that's not a huge amount of work, it's not a job I'm willing to volunteer for, so I've kept my mouth shut. At present the two-decade archive of this list remains the best source of such material. Its search capabilities leave something to be desired, but with a little prodding I've usually been able to find what I've been looking for.
Re: man-intro
Hi James, this is a very nice intro indeed. I have a few suggestions: I agree with Dave that the passus on numbered sections of man pages should be moved further down. The majority of novice users will likely search for commands, not necessarily for functions etc. A dedicated section "On Sections" could begin with: The library of man pages provides much more documentation than "just" the commands you may want to use. System calls, library functions, kernel interfaces and many other topics are treated in separate sections. These sections are accessed by a number. Try, for instance, man groff, which gives a synopsis of the details necessary for running groff. In contrast, man 7 groff gives a "short reference" (not so short after all) of the GNU roff language. Near the beginning, I humbly suggest inserting a paragraph which introduces the interaction of man page, formatter and pager, like: All man pages your system offers are formatted uniformly. Calling a given man page sends that man page through a formatter and prepares it for display. You can read man pages on screen, but they will look equally readable when formatted for print. Finally, I'd encourage the user to verify for him/herself the difference between a shell (e. g. bash) built-in and a man page call. In the case of "cd", the difference is striking! "help cd" offers just a bit more than a screenful of information, exactly the amount one is willing to digest in the beginning. "man cd", on the other hand, opens the bash built-in command *man page*, which, at least on my system is a plethora of text to read (and digest). Just my 2cents, Oliver. On 5/17/21 10:05 PM, James K. Lowden wrote: On Mon, 17 May 2021 16:24:34 +1200 "Michael Kerrisk (man-pages)" wrote: Maybe Michael or Alejandro can advise regarding where they think a good place for a man page utilization tutorial would be. If any place, I think intro(1) would be most appropriate, or, failing that, an initial sentence that points the reader at another page (that could be added in man-pages). My guiding principle would be that the guidance given should be simple (introductory and not comprehensive), finishing with pointers to man(1) and/or less(1) for further details. The current intro(1) is an odd page though. Andries Brouwer made some steps to turning into a general "intro to Linux" page, but that was, to my mind, always going to be an impossibly huge scope. I'm not a huge fan of what is there. Attached is a straw man 1st draft of what an introduction to the man system might look like. If it clears the threshold of raspberries, perhaps we can mold it into something useful. I think the page should be called man-intro, or intro-man. (Need help? Never fear, Intro Man is here!) I included what I wish someone had told me back when VAXes were in production. This is my work. I'm happy to consign it to the groff project or FSF, or to the public domain. --jkl -- Dr. Oliver Corff -- China Consultant -- Wittelsbacherstr. 5A D-10707 Berlin Tel.: +49-30-8572726-0 Fax : +49-30-8572726-2 mailto:oliver.co...@email.de
Re: man-intro (was: getting more out of man pages with less(1) )
On 5/17/21, James K. Lowden wrote: > Attached is a straw man 1st draft of what an introduction to the man > system might look like. If it clears the threshold of raspberries, > perhaps we can mold it into something useful. I think it looks great! I'm admittedly not its target audience, as I haven't been a novice man-page user in decades, so it's hard for me to say whether it's missing anything important. But even if there end up being details to be filled in later, this is a great starting point. The thing I might change structurally is moving the stuff about the user interface nearer the top where it's more prominent, and the stuff about the section numbers down. The novice user is way more likely to care about how to scroll through the page than how to look up something in section 5. It's certainly a valid topic to cover on an intro page, but maybe at the bottom rather than the top. (And since the majority of man pages only have one entry, making the section number unnecessary a lot of the time, maybe include an example of a page where the section does make a difference, like printf or groff?)
Re: parallel make problem with our Texinfo manual
Hi, Bertrand and Ingo! Thanks to you both for your help. At 2021-05-21T18:23:56+0200, Ingo Schwarze wrote: > Not very surprisingly, i didn't instantly manage to reproduce your > problem on a different machine and operating system. That's typical > for races, they depend on a lot of details. [...] > In my tests, i'm using "make -j 4 all check" because without > specifying the maximum number of parallel jobs an an argument "4" to > the "-j" option, i get nothing but > >$ make -j all check > make: illegal argument to -j option -- all -- invalid I reckon what's happening here is that you're not using GNU Make. [...] > Parallel builds can be useful, not only for wasting less time waiting > for builds to finish but also for finding bugs in dependency > specifications in Makefiles. More often than not, build failures > that only happen with -j indicate Makefile bugs, for example bugs > in dependency specifications, and sometimes other bugs, too. Yup. I was prepared to put these very arguments forward in case you discouraged -j usage. :D Incidentally, for those suspicious of parallel make, I have bad news--POSIX is standardizing it for the next "Issue" of the standard. The committee has been working constructively with Paul Smith (GNU Make maintainer), and as usual Jörg Schilling is trying to ensure that POSIX standardizes whatever is in Solaris and excludes everything that isn't. https://austingroupbugs.net/view.php?id=1436 https://austingroupbugs.net/view.php?id=1437 [much snippage] At 2021-05-22T02:00:07+0200, Bertrand Garrigues wrote: > The generated Makefile use recursive make for both 'all' and 'check' > targets: > >all: $(BUILT_SOURCES) > $(MAKE) $(AM_MAKEFLAGS) all-am >[...] >check: $(BUILT_SOURCES) > $(MAKE) $(AM_MAKEFLAGS) check-am > > That's why there is no dependency tracking (the jobs generated by the > 'all' target are not aware of the jobs from the 'check' target). Also > 'make check' implies 'make all' as we have: > > check-am: all-am > > So it's a bit like if you've done 'make all & make all'. You don't > need to do (and should not do) 'make -j all check' just do 'make -j > check'. Yup. A classic PEBKAC: "Problem Exists Between Keyboard and Chair". :P At some point the other day I blearily decided I didn't trust the "check" target to depend on everything being built, the bad formulation got into my shell history, and I just kept using it. Everything was fine until I went back to making modifications to the Texinfo manual... Thanks again! :) Regards, Branden signature.asc Description: PGP signature
