Re: Gtk patch version 3, part 1

["Robert J. Chassell" <bob@rattlesnake.com>]

       Do you mean "that the user can include into his machine" or "something
       that might be on the users machine already"?

   I mean something that ought to be on the user's machine
   (though any given user may or may not have installed it, of course).

Yes.  If it is not on your machine, you may not be able to access it:

 * The site may be down, as I find happens with the places I reference.

 * Your Internet service provider may have suffered a hardware
   failure, as mine did on 31 Dec 2002.

 * Getting something on the net may be inconvenient or expensive.  I
   was just talking to one of my my brothers-in-law: for him to get
   an update is expensive.  It takes time to download an update.
   

       If the second, can I refer to /usr/share/gtk-doc, where the GTK
       documentation is usually installed?

The /usr/share/doc/ documents are so much less convenient than Texinfo
documents.  For one, the Texinfo documents go into Info, which is
still, after 15 years, the single most efficient of the online
documentation formats (since you can navigate using regexps).  For
two, Texinfo documents go into HTML.  For three, Texinfo documents can
be typeset and printed, from DVI, PS, or PDF formatted files.

/usr/share/doc/ documents tend to be either text or HTML, both of
which have been superceded by better formats.  (HTML was superceded by
a format developed before CERN started using it.  Of course, the
people at CERN never thought that their format would be used for more
than the equivalent of 1980s Apple Hypertext Cards, which is why they
did not insist on an efficient language.  It never occurred to the
managers at CERN that anyone would want to reference another page of
the same document; all documents would be one page long!)

   A brief explicit concrete list would be much better than a
   cross-reference.  When something is directly relevant for the
   user's understanding, using a cross reference is considerably less
   convenient for the user.

Yes: please remember, when people look up a reference, you have to
think of them as being in `encyclopedia mode'.  They want the
information.  A link to another document on their machine is likely to
be perceived as a hinderance.  (A link to a document that they cannot
get to, because it is on another machine and they are off the
Internet, is likely to be perceived as a failure of the
documentation.)

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com