on Fri, Dec 05, 2003 at 12:00:10PM -0500, Bijan Soleymani (email@example.com) wrote: > "Karsten M. Self" <firstname.lastname@example.org> writes: > > > on Fri, Dec 05, 2003 at 11:17:04AM -0500, Bijan Soleymani (email@example.com) wrote: > > RTFL. > > > > It's not just the reader. It's the document structure. > > I read the damn thing! May I suggest toggling reading-with-comprehension mode next time? I wrote that abstract as outcome of a rather involved thread on d-u previously. Curiously there was a participant with gross comprehension problems that time 'round too.... > 2) It's (largely) bound to a specific viewer. > > It requires an info viewer (not true note my comment). To view a manpage: man foo ...which dumps user into $PAGER, or system default, or 'more'. Which the user uses for any other file. I use such pagers.... dozens of times a day. They're relatively simple. They're highly familiar. And I can chose any of several (less, more, most, w3m) which works for me. With zero functionality loss vis-a-vis the others, in terms of gross functionality of man. info foo ...dumps the user into, well, info. Unless you type 'pinfo'. In both cases, you've essentially got a special-purpose hypertext viewer. There is no way generally know to access info documents, from the command line, in a commonly used viewer familiar to the user. Yes, it's possible > 3) It fragments the documentation effort. > > Bah. Whatever. You appear to think this is an insignificant point. It's not. Reading, and I quote: The GNU folks, in general, abhor man pages, and create info documents instead....If you really want to understand tar, then you should run info and read the tar info pages, or use the info mode in emacs. ...in a manpage is simply unacceptable. Kudos to the Debian project for filling in manpages where they are missing. Worse, like other annoyances, the attitude that "we don't do manpages" becomes "we don't do documentation" for some entire projects, such as GNOME. I was involved in an extremely disheartening discussion with a key GNOME developer, and the release manager, earlier this year, in which I was told to "read the manpage" for gconftool documentation. As it turns out, there simply _is none_. Despite a 2+ year old outstanding bug filed against the package. The discussion revolved around, variously: - Why gconf is a horrible kluge. - Why GNOME is geared to end-users, not traditional Unix folks, who aren't its constituency. - Why end-users aren't qualified to comment on technical software issues. - How gconftool is a traditional Unix admin folks tool... - ...and much, much dissembling over why in two years nobody had thought to write a manpage (it's finally starting to happen -- the contents are largely what you'd see when typing "gconftool --help"). Again: there's a major difference between being able to: - Type 'apropos foo' - Type 'man foo' and '/<regexp>' to find a topic. - Type 'man foo -T<format>' and output the manpage in any desired format. ...and fussing through either a very rarely used, single-purpose hypertext browser with unfamiliar features, or hunting and poking through a set of disjoint webpages if you've installed dwww. > 5) It splits a programs docs into multiple pages. > > Again you can convert it to html all on one page. You brilliantly miss the somewhat minor point that the info document *isn't* a single page, readily searchable, and accessible via a single command-line statement, by default, and that the user has to go through several nontrivial steps (particularly for the novice or naive user) to extract another, more useful, format. I certainly went years without knowing of such options. > 6) GNU project manpages frequently deprecate manpages > > Ok is that a problem with the format? or the GNU project? Given the inherent and highly visible faults of the format, it is a fault of the GNU Project. > 7) Info viewers have usability problems > > Again convert to html or pdf. See 5. > 8) Info as extended documentation > > Ok so Docbook is better than Texinfo. You betchya. > 9) The learning curve argument > > Yeah learning to read html or a pdf or a physical book is tough. RTFL. info/pinfo are specialized, single-purpose tools. Vs. _either_ a general-purpose pager (less / more / most / w3m) or a web browser. > 12) Thou shalt render content and presentation asunder. > > I don't get what this means. I'm not surprised. man pages generate slightly formatted text output, which can be dumped straight to terminal or printer, captured to file, or viewed in any standard text pager or viewer. With the '-T' option, additional formats, including postscript, can be generated. With tools such as dwww or man2html, man pages are accessible as webpages. And, I might add, tend to render better than info pages. By contrast, info is a format tied to a specific viewer (by default, and by most convenient access). It's not tied to the system 'apropos' command. And the structure of the documents means that translation to other forms makes for significant loss of utility. The upshot is that I use an info viewer once every few months, don't know its features, curse it, and feel very much that I'm not alone. Info is, in this regard, not entirely unlike MS Word, as a document which is almost wholly associated with a single tool. With the concomitant disadvantages this entails. > 13) Remedy the problem > > Ok whatever. Richard is wrong, sometimes. Ubersoft notwithstanding. He should own up to this one. > 14) And yes, manpages have their problems. Example... > > Ok so man pages aren't perfect. > > > So I missed the whole part where you explained that Texinfo can be > converted into info, html, ps or pdf. I didn't think you were reading with comprehension. Seems I was right: It is searchable from within info, it has several output formats as it is LaTeX? based. And the basic concept seems valid. > And in any case it isn't unreasonable to put the basic documentation > in a section of the extended documentation. Especially for really > complicated programs. You'll find that this is actually a standard practice in Debian packages. Basic command references are in a manpage. Extended documentation is found in /usr/share/doc/<packagename>/, in the form of manuals, references, programmers references, FAQs, or entire HTML documents (say, for r-base, exim, or apache). [Perl and Python discussion elided]: both are presented in man page, and HTML format. No need to use info. Point of contention above being that several packages deprecate manpages entirely in favor of info. _That_ is the specific practice I detest and would prefer corrected. Preparing docs which can be presented in multiple formats, _including_ manpages, and whatever other silly format(s) are desired, is acceptable. Peace. -- Karsten M. Self <firstname.lastname@example.org> http://kmself.home.netcom.com/ What Part of "Gestalt" don't you understand? Bush/Cheney '04: Four More Wars!
Description: PGP signature