But I'm ok with a terse man page with a SEE ALSO that points to a user guide.

Docs should be helpful.

Complexity is entropy. It occurs naturally in all human endeavor. It takes work to keep things small, orderly, and rational. But there is also a point where although a tool may be perfect in its conception and execution, from its own perspective, it is not as useful as a slightly more disorderly version that does what people want it to do. "Well they shouldn't want that !" is a common response. Then people write scripts to do for themselves what the tool doesn't do. Which might be right, but it might lead to a whole bunch of similar scripts to do the same thing, just a little differently And that's when we discover that it would have been better to have it in the one tool in the first place. So it's a back and forth, trial and error process. Eventually new balances get struck, and people of like minds and tastes find a new center, like Plan 9, or other things. Myself, I do tend to like tools that are smaller and more single-minded in their function (and that makes it possible to have documentation that is clearer and more concise), but as an example, sometimes I want the "-u" switch on diff, to make a patch, sometimes I don't, the default display is better for a quick review (but I think or expect that the essential diff engine is being shared). It's all a matter of judgment, but you can't apply good judgment until you have the experience gained from trying several alternatives. So things will get bloated up, and then they will need to be pruned and re-engineered, but hopefully we don't throw out the most helpful exceptions to the rule just because they don't fit with some sort of consistency aesthetic. On 05/18/2024 11:52 AM, Clem Cole wrote: > > > On Sat, May 18, 2024 at 2:18 PM Larry McVoy &lt;lm(a)mcvoy.com&gt; wrote: > > > But I'm ok with a terse man page with a SEE ALSO that points to a user guide. > > Only if the SEE ALSO has more complete and relevant information - otherwise, it degrades to VMS's famous "see figure 1" SPR. > > > > > Docs should be helpful. > > And easy to extract information. > > > The issue to be comes back to the type of information each document is designed to give. I believe there at least three types of docs: > > 1. Full manuals explain how something is built and it it used. It helps to have theory/principles of operations behind it and enough detail when done, you can understand why and how to use it. > 2. Tutorials are excellent for someone trying to learn a new tool. Less theory - and more -- examples, showing off the features and how to do something. > 3. References pages - need to be quick look-ups to remind someone how to use something - particularly for tools you don't use every day/generally don't memorize. > > > > There are at least two more: an academic paper which might be looked at as a start of #1 and full books which take #1 to even more details. Some academic papers indeed are fine manuals, and I can also argue the "manual" for some tools like awk/sed or, for that matter, yacc(1) are full books. But the idea is the >>complete<< review here. > > > Tutorials and reference pages are supposed to easy helpful things -- but often miss the mark for the audience. To me, the problem is the wrong type of information is put in each one and, more importantly, people's expectations from the document. I love properly built manual pages - I detest things like the VMS/TOPS help command or gnu info pages. What I really hate is when there is no manual, but they tell you see the HELP command -- but which command or "subtopic" -- Yikes. The traditional man system is simple quick reminders, basic reference and I can move on. For instance, I needed to remember which C library has the definition these days for some set of functions and what are its error return codes -- man 3 functions, I'm done. > > > Tutorials are funny. For some people, what they want to learn the ideas behind a tool. Typically, I don't need that as much as how this toll does some function. For instance, Apple is forcing me the learn lldb because the traditional debuggers derived from UCB's DBX are not there. It's similar to different. The man page is useful only for the command lines switches. It turns out the commands are all really long, but they have abbreviations and can be aliases. I found references to this in an lldb tutorial - but the tutorial is written to teach people more how to use a debugger to debug there code, and less how this debugger maps into the traditional functions. Hey I would like to find an cheat sheet or a set of aliases that map DBX/GDB into it -- but so far I've found nothing. > > > So Larry -- I agree with you ... "Docs should be helpful," but I fear saying like that is a bit like the Faber College Motto/Founder's Quote: "Knowledge is good." > > > > > ᐧ

Douglas McIlroy wrote in &lt;CAKH6PiXaYGEUmVFRX99eM6s3+nTJrbVvkuBRa-Awhhd69xzJrg(a)mail.gmail.com&gt;: |I just revisited this ironic echo of Mies van der Rohe's aphorism, "Less is |more". | % less --help | wc | 298 |Last time I looked, the line count was about 220. Bloat is self-catalyzing. I do not buy that. You are working on Windows and in the meantime have switched to one of those graphical browser monsters (i think) where each instance has more code active than the entire Unix history altogether. less(1) can now Unicode, and that is not as easy with ISO/POSIX as it was on Plan9 for example which simply goes UTF-8 and has some (smart) lookup tables (now in go, more or less, last i looked), but that is not the whole picture of it. It can those ANSI / ISO 6429 color sequences that everybody wants, as you have them everywhere, even GNU's yacc, bison. The OpenBSD people took a port done by an OpenSolaris (i think, that scene, anyhow) guy, and together they stripped it down massively. But i do not use it, because after almost exactly a decade i got upstreamed to Nudelman's less(1) the necessary patches to have active hyperlinks on the terminal, in a normal Unix (roff mdoc) manual. (These work via OSC-8 escape sequences; it was a "15 files changed, 601 insertions(+), 9 deletions(-)" patch, which included careful quoting of file paths etc. for man(1) openings (ie, such code gets lengthy), but he did it differently a bit, and left off some things i wanted, included others (good), but if you use --mouse with his one then you have a real browser feeling. I have problems with --mouse, unfortunately, because when used you can no longer copy+paste -- he would need to add clipboard control in addition i'd say.., adding even more code.) You know, it may be viable for some tools, but for others, .. not. You say it yourself in your "A Research UNIX Reader": "Electronic mail was there from the start. Never satisfied with its exact behavior, everybody touched it at one time or another". In the meantime the IETF went grazy and produced masses of standards, and unfortunately each one adds a little bit that needs to be addressed differently, and all that needs documentation. Now mail is an extreme example. And almost a quarter of a century ago i wrote a small pager that even had a clock, and it required less CPU on a day with some scrolling than less/ncurses for a one time scroll through the document. But that pager is history, and less is still there, running everywhere, and being used by me dozens to hundreds time a day. Also with colours, with searching, and now also with ^O^N ^On * Search forward for (N-th) OSC8 hyperlink. ^O^P ^Op * Search backward for (N-th) OSC8 hyperlink. ^O^L ^Ol Jump to the currently selected OSC8 hyperlink. And prepared mdoc manuals can now display on a normal Unix terminal in a normal (actively OSC-8 supporting $PAGER) a TOC (at will, with links), and have external (man:, but also http: etc; man is built into less(1) -- yay!) links, too. For example here ∞ is an external, and † are internal links: The OpenSSL program ciphers(1)∞ should be referred to when creating a custom cipher list. Variables of interest for TLS in general are tls-ca-dir†, tls-ca-file†, tls-ca-flags†, tls-ca-no-defaults†, tls-config-file†, tls-config-module†, tls-config-pairs So ^O^L on that ciphers(1) opens a new man(1)ual instance. For all this functionality a program with 221K bytes is small: 221360 May 18 22:13 ...less* Also it starts up into interactive mode with --help. So you could have "full interactivity" and colours and mouse, and configurability to a large extend, which somehow has to be documented, in just 221 K bytes. I give in in that i try to have --help/-h and --long-help/-H, but sometimes that -h is only minimal, because a screenful of data is simply not enough to allow users to have a notion. So less could split the manual into a less.1 and a less-book.7. The same is true for bash, for sure. (And for my little mailer.) But things tend to divert, and it is hard enough to keep one manual in sync with the codebase, especially if you develop focused and expert-idiotized in a one man show. |What prompted me to look was another disheartening discovery. The "small |special tool" Gnu diff has a 95-page manual! And it doesn't cover the |option I was looking up (-h). To be fair, the manual includes related |programs like diff3(1), sdiff(1) and patch(1), but the original manual for |each fit on one page. --End of &lt;CAKH6PiXaYGEUmVFRX99eM6s3+nTJrbVvkuBRa-Awhhd69xzJrg(a)mail.gmail\ .com> --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)

I can't tell you--although some of you will know--what a delight it is to be working on a project with an actual documentation engineer. That person (Jonathan Sick, if any of you want to hire him) has engineered things such that it is easy to write good documentation for the projects we write, and not very onerous. Design for documentability, testability, and ease of maintenance are what

Sometimes in the process of doing that youd stop and think, "wait a minute--we don't really want it doing that".  Or you'd find that you bhad difficulty articulating exactly how a particular feature behaves.  That's a red flag that you've designed the feature to be too obscure and complex, or that there's something flat-out wrong with it.