Re: Emacs minimised

[Lee Sau Dan]

>>>>> "Jesper" == Jesper Harder <harder@myrealbox.com> writes:

    Jesper> Keith O'Connell <kroc@blueyonder.co.uk> writes:
    >> Yes its there, now I know to look. The problem is I did "man
    >> emacs" and it wasn't there. I figured if it wasn't in the man
    >> file it was worth asking.

    Jesper> '-iconic' is documented in the "Icons X" node in the Emacs
    Jesper> manual.  For GNU programs it's usually always best to look
    Jesper> in Info first:

That's true.  But this is also a problem.  Even though I've been using
Info to  look up  many things, I  still have  the unix habit  of using
'man'  when want  to  find something  in  a hurry,  and assuming  that
everything is  there.  Failing  to find something  in the man  page is
already frustrating!  So, I will forget about Info at that point!  :(

Info is good, if  I want to study the program for  15 minutes or more.
But for quick lookups, man  pages are still much better.  (Many people
are simply not interested in learning yet another program.)


The other problem  is that there are too many places  to look for such
information.  "--help"  is usually the most up-to-date,  but too brief
to  be useful  for studying.   Only helpful  in recalling  options and
their  names.  man pages  have the  tradition (on  unix, at  least) of
being "complete", but  the Gnu programs do not  follow this tradition.
This is  the problem.  The man  page of many Gnu  programs are already
very detailed,  and hence give people  a feeling that it  is, like the
other unix man pages, very complete.   But the truth is: the man pages
are not  complete and  sometimes even out-of-date.   One often  has no
clues  about  this by  just  studying the  man  page,  they miss  much
information.  

I  think a  reference to  the appropriate  Info page  in the  SEE ALSO
section would  be very  helpful.  This  is what a2ps  does in  its man
page:
SEE ALSO
       a2ps(1),   card(1),    fixps(1),    pdiff(1),    psset(1),
       texi2dvi4a2ps(1).

       The full documentation for a2ps is maintained as a Texinfo
       manual.  If  the  info  and  a2ps  programs  are  properly
       installed at your site, the command

              info a2ps

       should give you access to the complete manual.

Emacs's  man page  has  something similar,  but  NOT in  the SEE  ALSO
section.  It is in the  DESCRIPTION section.  It is thus easily missed
by the impatient who are looking for command line options.


BTW, I like the man page of 'xv'.  At least, I'm not confused.  Here's
an excerpt:

       The  documentation  for  XV  is  now distributed only as a
       PostScript file, as it has  gotten  enormous,  and  is  no
       longer very well suited to the 'man' page format.  Print a
       copy of the (100-ish page) manual found in docs/xvdocs.ps.
       If  you  are  unable  to  get  the manual to print on your
       printer, you may purchase a printed copy of the XV manual.
       Click on 'About XV' in the program to get further informa­
       tion.



-- 
Lee Sau Dan                     李守敦(Big5)                    ~{@nJX6X~}(HZ) 

E-mail: danlee@informatik.uni-freiburg.de
Home page: http://www.informatik.uni-freiburg.de/~danlee