Re: Gtk patch version 3, part 1

[storm@cua.dk (Kim F. Storm)]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>        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:

Well if it is not on your machine -- you definitely cannot access it 
without accessing the Internet.

I don't argue that if there is a document on your -- and everyone
else's -- local machines that can be referenced, we should do that.

But I really don't see how we can assume that a specific file is
always available.  Some systems even come without man-pages ...

If we cannot rely on having a local file, we have two options:

- include the necessary documentation in the emacs distribution [meaning
  that we may have to (re)write that documentation ourselves], or

- reference an existing document (in whatever format it is available in)
  with the appropriate URL.

The first option still costs you something (when downloading and
storing emacs on your local machine), and it may be time-consuming to
write the necessary documentation.

The second option has the potential risks of non-availability that you
mention, and it *may* also costs a few cents to access the URL (although
flat-rate Internet access is getting pretty common in many places).

IMHO, referencing a URL is at least as good as referencing a local
file which we cannot be sure is available (or don't know where it's
located even if it exists)...

Having said that, I agree that Texinfo is a superior format for
online docs!

> 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.  

If it is a link which they can click on with mouse-2 and have it
opened in an emacs buffer, in a browser or in some other viewer, I
think most users will be happy with that.

>                                (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.)

I disagree!  Regarding a user's inability to access the Internet as a
documentation failure seems quite far-fetched to me.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk