[nSLUG] pet peeves

Jeff Warnica jeff at coherentnetworksolutions.com
Tue Jun 27 19:36:28 ADT 2006

Consider the opening paragraphs of what the respective tools have to say
about themselves:

$ man man

       man - an interface to the on-line reference manuals

       man  [-c|-w|-tZHT  device]  [-adhu7V]  [-i|-I]  [-m system[,...]]
[-L locale] [-p string] [-M path] [-P pager] [-r prompt] [-S list] [-e
       [[section] page ...] ...
       man -l [-7] [-tZHT device] [-p string] [-P pager] [-r prompt]
file ...
       man -k [apropos options] regexp ...
       man -f [whatis options] page ...

       man is the system's manual pager. Each page argument given to man
is normally the name of a program, utility or function.  The manual page
       ated  with each of these arguments is then found and displayed. A
section, if provided, will direct man to look only in that section of
the manual.
       The default action is to search in all of the available sections,
following a pre-defined order and to show only the first page found,
even if page
       exists in several sections.


$ info info

e: info.info,  Node: Top,  Next: Getting Started,  Up: (dir)

Info: An Introduction

The GNU Project distributes most of its on-line manuals in the "Info
format", which you read using an "Info reader".  You are probably using
an Info reader to read this now.

   There are two primary Info readers: `info', a stand-alone program
designed just to read Info files, and the `info' package in GNU Emacs,
a general-purpose editor.  At present, only the Emacs reader supports
using a mouse.

   If you are new to the Info reader and want to learn how to use it,
type the command `h' now.  It brings you to a programmed instruction

   To read about expert-level Info commands, type `n' twice.  This
brings you to `Info for Experts', skipping over the `Getting Started'


If I were an English teacher, I would fail the person who wrote the
"Introduction" to Info, as it doesn't cover what Info is in a nice
succinct fashion... "Info: a tool for reading documentation written in
the info format." Their introduction is paticularly unhelpful if, for
example, you use konqueror to view info pages (admittedly, outside this
contrived example, I can think of no overlap in people who would
consider using konqueror to view info pages). It attempts to be friendly
to users, but this short fragment is itself internally incosistant in
that friendlyness... "You are probably using an Info reader to read this
now.": so its possible the user doesnt know what they are doing, or even
what tool the;

Arguing info as a high-level markup format is simply wrong. docbook is
the high level markup format to use. yelp, the Gnome help tool reads
docbook stuff by design, and the docbook tool chain can convert it to
just about anything, including man and info.


More information about the nSLUG mailing list