On Wed, Dec 05, 2018, James K. Lowden wrote: > On Tue, 4 Dec 2018 15:16:50 -0500 > Peter Schaffter <pe...@schaffter.ca> wrote: > > > When I analyze my initial impression of manpages, I see that it > > was a clash between approaching computing from the humanities, > > as a non-programming user, versus approaching computing from the > > sciences, as a programmer. > > I don't think that's quite right, Peter. I suggest to you that's the > difference between a user guide and a reference manual. We need both, > always have, and the humanities have nothing to do with it, except > insofar as they teach clear exposition.
I used humanities as a collective noun referring to users who come to a Unix system as philosophers, historians, linguists, writers of fiction, essayists... Such users do, generally, approach computing from a different perspective than sysadmins and programmers. They do not *think* like sysadmins and programmers. The filters they bring to bear on documentation are very much related to the issue at hand. Not to acknowledge that leads to BOFH thinking. Manpages target the B.Sc. crowd, not the B.A. crowd, if I may speak very broadly to make the point. I believe the latter tends to have the same reaction to manpages that I did on first exposure. "Manpage" implies "a manual." A common understanding of the term manual, the one brought to bear by my "B.A crowd," is "[A] comprehensive and step-by-step guide to a particular topic for both beginners and practitioners that also serves as a reference book. A manual details what is given and what is required, explains how to put the presented information into practice, and instructs how to solve problems as they occur." [BuinessDictionary.com] Manpages are the antithesis of this, so conceptual clashes of the sort I experienced are likely to occur. I'd hate to be guilty of extrapolating the general from the specific, but I'm certain I am not alone in my initial reaction to manpages. I do hope it's clear I am not attacking manpages or suggesting their content, style, or formatting be altered, except insofar as I'm Ingo's camp when it comes to mandoc. Manpages serve the needs of their target audience, of which I am a card carrying member. How well they do so will likely always be contentious, as, IMO, it should be; that's how we make them better. Nevertheless, they are not and will never be suitable for all documentation. I dispute the notion that if you can't document your work manpage style, your code is sub par. Classic case of "true in most instances, not in all." > You'd have a hard time convincing me that MOM is more complex > than troff itself, or that groff_mom(7) would be longer or > harder to organize than groff(7). Heaven forfend! I'd never suggest mom was more complex than troff. But she is nothing like g/troff. Groff is a typesetting *program*. Mom is, for all intents and purposes, a formatting *language*--as such, akin to html/css. Nowhere is html/css documented in manpage format, for the obvious reason that you can't learn a language from reading the dictionary. You need more than just "this is what the words mean." Organizing html/css into a usable manpage would, I think, prove a complex task indeed. _Ita quoque mom._ A better analogy might be GNU Lilypond, which provides a formatting language for engraving music. The language is not covered in a manpage because, quite simply, it cannot be, not in any meaningful way. Instead, its manpage does what I propose is best for mom: it gives the NAME, a DESCRIPTION, the invocation SYNOPSIS, and command line OPTIONS--the kind of information I want from a manpage, which I am likely to be consulting at the terminal because I intend to perform a command line operation. For actually creating lilypond documents, users are directed to the full manual. (I shudder to think of consulting a manpage for all that guile/scheme.) > The very fact that your HTML documentation is frequently viewed is > proof, actually, that a reference manual is needed. I see it differently. What it tells me is that mom users like consulting the documentation from their web browser. The experience is comfortable and familiar. Users don't have to go on the Web to consult the docs, which ship with groff, yet they persist in doing so. More a question of "familiarity breeds ease of use" than silent pleas for a manpage, I should think. :) -- Peter Schaffter http://www.schaffter.ca
