From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Robert J. Chassell" Newsgroups: gmane.emacs.devel Subject: Re: Gtk patch version 3, part 1 Date: Fri, 3 Jan 2003 22:42:00 +0000 (UTC) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <200301011944.h01Jim0U011400@stubby.bodenonline.com> Reply-To: bob@rattlesnake.com NNTP-Posting-Host: main.gmane.org X-Trace: main.gmane.org 1041633771 31730 80.91.224.249 (3 Jan 2003 22:42:51 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Fri, 3 Jan 2003 22:42:51 +0000 (UTC) Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 18UaWe-0008FM-00 for ; Fri, 03 Jan 2003 23:42:48 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18UaZS-0005nf-00 for ; Fri, 03 Jan 2003 23:45:42 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18UaWN-0005WV-02 for emacs-devel@quimby.gnus.org; Fri, 03 Jan 2003 17:42:31 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18UaW3-0005Uv-00 for emacs-devel@gnu.org; Fri, 03 Jan 2003 17:42:11 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18UaW0-0005Ue-00 for emacs-devel@gnu.org; Fri, 03 Jan 2003 17:42:10 -0500 Original-Received: from megalith.rattlesnake.com ([140.186.114.245] helo=localhost) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18UaVz-0005UK-00 for emacs-devel@gnu.org; Fri, 03 Jan 2003 17:42:07 -0500 Original-Received: by rattlesnake.com via sendmail from stdin id (Debian Smail3.2.0.114) Fri, 3 Jan 2003 22:42:00 +0000 (UTC) Original-To: emacs-devel@gnu.org In-reply-to: (message from Richard Stallman on Thu, 02 Jan 2003 22:30:59 -0500) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:10444 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:10444 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