This touches on something I experienced recently. I wanted to write a JavaScript module that would help developers generate manual-pages for their projects (because there's a searing lack of manpages in the Node community...).
I ended up ditching that idea when I realised developers would still be asking for the possibility of converting Markdown into Roff commands... and I realised I'd be going through endless effort to spoon-feed close-minded devs who can't be bothered making an attempt to learn even basic manpage authoring. I laughed at how complex a JavaScript-based documentation generator would become when compared to the simplicity and power of a simple, plain, correctly-written manpage. As Branden said: you can lead a horse to its troff, but you can't make them drink. (I know it's pronounced "tee-roff", not "trough", but c'mon, that pun was unavoidable...) On 28 April 2017 at 15:15, G. Branden Robinson <g.branden.robin...@gmail.com > wrote: > 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 >