On Fri, 28 Apr 2017 01:15:05 -0400 "G. Branden Robinson" <g.branden.robin...@gmail.com> wrote:
> 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. At the time I used nedit. Today I would use emacs. There's no package for docbook-mode that closes tags for you. The xml modes I've used are lame and wouldn't perform well on a large manual. DocBook is a complex beast. It would be great if the editor could do tab-completion for valid tags for the current parent and valid parents for a selected region, and jump from beginning to end of a tag. If such a tool exists, that would be news to me. Meanwhile, what could be simpler than having the editor supply "tool tip" text to explain .Sx or an "mdoc apropos" feature derived from keywords in the manual? The only reason there isn't better editor facilitation for man and mdoc is ... lack of interest. The problem is technically much simpler. > We have ludicrously more processor horsepower and memory Yes, and my contention is that we nevertheless have not developed a system that is easier to use or learn. troff macro packages are simpler and impose less on the author than any alternative of similar capacity. The facilitation promised 2 decades ago to deal with the verbosity and complexity of more recent designs never materialized, leaving authors with a variety of lousy options. > They're programmers. Some of them are difficult to coerce into > writing documentation _at all_. There is no evidence that programmers disinclined to write documentation do a better job of it if it's made easier to do. Good documentation takes effort, and that effort is different from the programming effort. The impetus for Markdown and Doxygen and the like is that good documentation will emerge by lowering the bar. It's simply not true. The problem of writing documentation isn't in opening another file (Doxygen) or understanding the markup system (Markdown). It's in capturing the syntax and semantics from the point of view of the user. And, as you say, some people have the additional burden of caring enough to bother. I have yet to see good documentation produced by those systems unless great care was taken. Having used Doxygen for C library with a 100 functions, I wouldn't use it again. For equivalent time invested, I get better results from mdoc, albeit without the pretty diagrams. >> when transferring them from the manpage I was afraid that might not be clear. What I meant is that as I'm writing documentation, I'm refering to the mdoc manpage (say). I've never done that kind of work for a living. I'm just another occasional mdoc hacker, so I quite often have to relearn parts of it. By "transfer", I meant putting to use what I'm reading in my writing. Two letters aren't hard to remember, and most of the pairs carry some mnemonic weight. (That said, better editor facilitation would make the work less tedious.) > C adopted designated initializers, a sop to those who can't recall > what order a struct's fields come in. I guess you're implying that designated initializers, while verbose, are easier to use, even for aficionados of a terse language like C. As it happens, my current work is in C, and I adopted C11 as a baseline, partly so I could use them. With today's machines, the compiler can do more than was feasible in 1978. I'd argue we have bigger structures now, too. Designated initializers aren't so much a sop to the lazy as they are a gift of clarity, because otherwise the programmer has to count structure elements and supply any zeros preceding the elements to be initialized. Designated initializers also support re-initialization of existing structures, something that otherwise required error-prone member-by-member assignment. All to say that at least one fan of short macro names finds explicit structure initialization useful. --jkl