This is the mail archive of the cygwin@cygwin.com mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

"RTFM'ing": readily accessible user documentation?


Hello,

When I try to use `info blah' on my Cygwin system I get the error
info: dir: No such file or directory

Yes, this in in the FAQ (however, alternatively, not findable by any of 5 
permutations of searches I ran on the List archives, just as an aside):
--------------------------------------------------------------------------  
 info error "dir: No such file or directory"
   Cygwin packages install their info documentation in the /usr/info 
   directory. But you need to create a dir file there before the standalone 
   info program (probably /usr/bin/info) can be used to read those info files. 
   This is how you do it: 

   	bash$ cd /usr/info
   	bash$ for f in *.info ; do install-info $f dir ; done

   This may generate warnings: 

   	install-info: warning: no info dir entry in `gzip.info'
   	install-info: warning: no info dir entry in `time.info'

   The install-info command cannot parse these files, so you will have to add 
   their entries to /usr/info/dir by hand. 
--------------------------------------------------------------------------

It is apparently the feeling on this cygwin List that one of the first 
things a new user should do is check the documentation ("RTFM") that comes 
with the Cygwin installation ('should do' long before they consider posting 
a question to the List). Documentation that is installed on the local 
machine the user is using (especially if they are a dial-up user) is 
preferable to on-line documention for reasons of speed of access (or not 
having to use a phone line, or not having one available). Seem reasonable? 
No? Well I am sure anyone can argue about anything.

IMHO, "info" *should get set up automatically when Cygwin is installed.* 
Placing a bunch of files into a directory then just leaving them inert and 
useless seems half-assed to me, to be candid, given the recently over-
discussed noise level issue here (myself being the one who is doggedly 
flogging it to death). Anyhow, that arcane invocation given in the FAQ 
(arcane to someone just learning `bash' or shell scripting in general, 
probably), represents setting the bar TOO HIGH on new user ease-of-access 
to that important information in the preferred Gnu format ("info" as 
opposed to "man").

This is all stated *given willingness to acknowledge _human_ _nature_* of 
course. Only from that perspective do I consider these my observations to 
be obviously salient. From the perspective of expert users and those who 
have known Gnu software for years (and probably created some of it), 
looking at the matter without being able to "get into the head" of the 
novice user impatient to begin using Cygwin, it will sound like silly 
purile carping. Such a person can say so -- fine -- but will get no 
sympathy from me next time they complain that "the same questions keep 
getting asked over and over again...".

The FSF info source code package for "texinfo" contains a README file which 
contains this small notice:

   * The Info tree uses a file `dir' as its root node; the `dir-example'
     file in this distribution is included as a possible starting point.
     Use it, modify it, or ignore it just as you like.
(ftp://tug.ctan.org/tex-archive/macros/texinfo/texinfo/README)

That source package also contains this script file (as it turns out, once 
one opens it and reads it, it's a shell script -- but how would a newbie 
automatically know this???):
ftp://tug.ctan.org/tex-archive/macros/texinfo/texinfo/util/gen-dir-node

Couldn't this script, or something like it, be made a part of Cygwin and 
run each time a setup installation procedure is completed? Couldn't the 
user AT LEAST be prompted to choose whether to run it, or advised that he 
should?

That's my suggested addition (for today) to whatever it is that `setup' 
does. I am not currently involved in hacking on `setup' so I won't be 
contributing any patches on this issue; it will have to fall to someone 
else to (maybe) implement this, for the time being (other priorities are 
just unrefusable for me at present). Thanks for your attention.

       Soren Andersen


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]