From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Ivan Shmakov Newsgroups: gmane.emacs.devel Subject: URIs for GNU documentation Date: Tue, 16 Dec 2014 19:17:36 +0000 Message-ID: <87fvcfieun.fsf_-_@violet.siamics.net> References: <20141205123549.GA29331@thyrsus.com> <87ppbqb6s1.fsf@gnu.org> <87388mme16.fsf@newcastle.ac.uk> <87a92u86wv.fsf@gnu.org> <87d27oliue.fsf@gnu.org> <87r3w2fgux.fsf@uwakimon.sk.tsukuba.ac.jp> <871to1f69o.fsf@uwakimon.sk.tsukuba.ac.jp> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1418757504 9205 80.91.229.3 (16 Dec 2014 19:18:24 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 16 Dec 2014 19:18:24 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Dec 16 20:18:20 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Y0xdQ-0006JO-Na for ged-emacs-devel@m.gmane.org; Tue, 16 Dec 2014 20:18:16 +0100 Original-Received: from localhost ([::1]:46331 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0xdP-0004aM-Vv for ged-emacs-devel@m.gmane.org; Tue, 16 Dec 2014 14:18:15 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38333) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0xdC-0004aE-Fn for emacs-devel@gnu.org; Tue, 16 Dec 2014 14:18:03 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Y0xd8-0007ns-0i for emacs-devel@gnu.org; Tue, 16 Dec 2014 14:18:02 -0500 Original-Received: from fely.am-1.org ([2a01:4f8:d15:1b86::2]:51173) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y0xd7-0007lm-JW for emacs-devel@gnu.org; Tue, 16 Dec 2014 14:17:57 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=siamics.net; s=a2013295; h=Content-Transfer-Encoding:Content-Type:MIME-Version:Message-ID:In-Reply-To:Date:Sender:References:Subject:To:From; bh=FbmNeBM//hrZCZtWg/0b/DQusQEQNJGlUliQr+8iuHM=; b=J9kMyiW9VVXlDvxGArBYtz5H+G/76UTgYShwkN3QTsb5voYrhFr5TZriXfzy1Uw2mIsI1AZNBMfsDs9zOh/auOVq1DNlRKTaE9x/GonpGPcbrMIvGgFCjj8jj5R1+oND773nfzdpbjLabnEoQINAN82Wtj5oTniQYP1XJ3M9aTE=; Original-Received: from [2a02:2560:6d4:26ca::1:1d] (helo=violet.siamics.net) by fely.am-1.org with esmtps (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.80) (envelope-from ) id 1Y0xcv-0006Y4-2O for emacs-devel@gnu.org; Tue, 16 Dec 2014 19:17:45 +0000 Original-Received: from localhost ([::1] helo=violet.siamics.net) by violet.siamics.net with esmtps (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.80) (envelope-from ) id 1Y0xcn-0008D4-Kq for emacs-devel@gnu.org; Wed, 17 Dec 2014 02:17:37 +0700 In-Reply-To: (Richard Stallman's message of "Tue, 16 Dec 2014 00:20:13 -0500") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a01:4f8:d15:1b86::2 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:180201 Archived-At: >>>>> Richard Stallman writes: >>> We want to write something short such as `info:emacs' to refer to >>> the Emacs manual. [=E2=80=A6] >> I don't think either the browser maintainers or the IETF will be >> particularly interested in an info: scheme since it's really a >> document format rather than a transport. > It has nothing to do with the file format. These files will be HTML. > Rather, it refers to a way of searching for a file (usually local, > but maybe not always). > Anyway, we don't depend on their approval. The very premise of this thread was (AIUI) to make the GNU documentation more =E2=80=9CWeb-friendly,=E2=80=9D which I tend to interpr= et to mean =E2=80=9Cworks with any browser=E2=80=9D (among other things.) The u= se of a specialized, Emacs-only URI scheme would be against that goal. Below, I=E2=80=99ve tried to outline several of the available choices, and (hopefully) made an argument for using a standardized Info HTML files naming scheme to facilitate cross-references. URI schemes and URNs There=E2=80=99re a plenty of existing URI schemes that=E2=80=99d fit the r= ole. The core choice to make is whether to use URNs (similar to the info: scheme suggested above) or URLs. The advantages of the former are: the URIs may be made entirely independent of the exact locations of the files comprising the documentation or section; they /could/ be concise; the existing infrastructure (such as XML catalogs [1], for instance) could probably be re-used. The necessity of a separately maintained mapping from names to locations (not unlike the currently used Info directory) is the principal disadvantage, =E2=80=93 especially if it=E2=80=99s desired that a remote copy should be used when no local one is available. The other disadvantage is that the use of a generic scheme either implies some =E2=80=9Cspecialization overhead=E2=80=9D, for instance [2, 3= ]: tag:gnu.org,2014:manual:emacs urn:publicid:%2B:IDN+gnu.org:Manual+GNU+Emacs+25.0.50.1:EN or requires the use of URIs whose intended meaning is not readily discernable [4, 5]: urn:oid:1.3.6.1.4.1.1370787.42 urn:uuid:b36df5bb-cf0c-4e1a-acd6-dc6602e5d6a4 As an alternative, FSF could request a separate URN namespace (urn:fsf:), but the use of the resulting identifiers would imply some kind of approval or endorsement from the Foundation, which seems infeasible for non-GNU projects. Naming scheme for Info HTML files The use of URLs for the purpose has the obvious drawback of them being tied to particular remote service or local filesystem layout. The question is: is that a problem? The filesystem layout for the majority of GNU installations is already standardized; say, we may expect to find the Info documents somewhere under /usr/share/info (also /share/info for GNU/Hurd.) Should we take a step further and require that the HTML Info documentation be installed using a specific scheme, =E2=80=93 and we could readily refer to a specific node or section using plain relative URIs. For instance, assuming the following scheme: PACKAGE-VERSION/MANUAL/NODE.html the following translations would take place: doc/lispref/abbrevs.texi: @pxref{Expanding Abbrevs,, Expanding Abbrevs, emacs, The GNU Emacs Manua= l} /usr/share/info/emacs-25.0.50.1/elisp/Abbrevs.html: =E2=80=A6 doc/lispref/building.texi: @xref{Top,, Make, make, GNU Make Manual}. /usr/share/info/emacs-25.0.50.1/elisp/Compilation.html: =E2=80=A6 In the latter case, =E2=80=98latest=E2=80=99 could be a directory populate= d with either symbolic links pointing to the latest versions of the manuals, /or/ HTML redirect pages (including redirects to non-local copies of the documentation not currently installed.) Alternatively, when the manuals are served via HTTP(S), =E2=80=98latest=E2= =80=99 may refer to a server-side program translating the URIs it receives into (temporary) HTTP redirects to the fully-qualified locations. References [1] https://oasis-open.org/committees/entity/specs/cs-entity-xml-catalogs-1= .0.html [2] https://tools.ietf.org/html/rfc4151 (urn:ietf:rfc:4151) [3] https://tools.ietf.org/html/rfc3151 (urn:ietf:rfc:3151) [4] https://tools.ietf.org/html/rfc3061 (urn:ietf:rfc:3061) [5] https://tools.ietf.org/html/rfc4122 (urn:ietf:rfc:4122) --=20 FSF associate member #7257 http://boycottsystemd.org/ =E2=80=A6 3013 B6A0= 230E 334A