At 2017-04-27T23:38:23-0400, James K. Lowden wrote: > On Wed, 26 Apr 2017 09:46:43 -0400 > "G. Branden Robinson" <g.branden.robin...@gmail.com> wrote: > > > 1. The slavish devotion to two-letter names for things, which like the > > man macro package and the oldest parts of *roff itself, make it > > self-anti-documenting. > > Having written one user guide in DocBook, I have to disagree. > > The troff system was designed to be typed at a keyboard. The > dot-on-the-left rule might be ugly, and the requests/macros terse, > but the benefit to the user is relatively few keystrokes above those > needed for the text.
Did you write your DocBook-based user guide in ed? Nothing has come close to saving me more keystrokes than <TAB> at the shell prompt and CTRL-N in Vim. We have powerful, robust, and programmable text-completion systems these days. I have second-hand nostalgia for the early Bell Labs Unix days (too?), but we don't live in those times. We have ludicrously more processor horsepower and memory, and we've even, occasionally, found some good applications for the surfeit. > Most SGML derivatives, on the other hand, presupposed Interleaf-like > tools that would shield users from the markup syntax. That "assume a can > opener" design theory freed them to be verbose. When the tools never > materialized, users started looking for a way to avoid their verbosity > tax. Markdown is only the latest product of that search. > > Short names are actually *easier* to use than long ones! Why? > > Brevity rewards experience. Well, that's part of the problem. Few people are full-time *roff or macro package users. They're programmers. Some of them are difficult to coerce into writing documentation _at all_. A lot of people hate Fortran, but I don't. In the 20+ years since I first saw it I've come to recognize a huge virtue in its insistence on unabbreviated English words for its keywords; they're more ergonomic for the scientists and (non-software) engineers who have been off doing science or engineering for several months and only occasionally have to do code maintenance or development. That's the analogy I recommend for macro packages targeting documentation of software systems. You can even lead the horses to literate programming, as Knuth tried to do decades ago, and most of them will stubbornly spend the great bulk of their time in the part that gets tangled rather then the part that gets woven. It doesn't matter for our discussion why that is--it's a fact and the state of our discipline. Maybe they're snooty elitists or code cowboys or rock stars or maybe they simply spend their time where the problems are. The competing models of "recognition" vs. "recall" have occupied a lot of writing on user experience. I submit to you that for most of its users, the man macro package needs to work the "recognition" side of the street. > If .SH or .Sx is hard to read, they're also easy to write, and easy to > remember when transferring them from the manpage to the document at > hand. I don't understand this claim. Section headings would be pretty obvious most of the time even if they weren't marked up at all. You're not transferring the macros, surely, but rather their parameters, right? Do you remember off the top of your head in what order the 6 arguments to .TH get placed at header-left, header-middle, header-right, footer-left, footer-middle, and footer-right? Even the ne plus ultra of terseness among successful languages, C, adopted designated initializers, a sop to those who can't recall what order a struct's fields come in. (Though I wouldn't bet on whether Ritchie would have thought it was a good idea.) > In today's world, to most programmers troff is 100% novel, and they find > its terseness inscrutable and off-putting. Too hard to understand! > > Ah. But so easy to use. ...and yet again so hard to use correctly. Regards, Branden
signature.asc
Description: PGP signature
