URIs for GNU documentation

[Ivan Shmakov <ivan@siamics.net>]

>>>>> Richard Stallman <rms@gnu.org> writes:

 >>> We want to write something short such as `info:emacs' to refer to
 >>> the Emacs manual.

[…]

 >> 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 “Web-friendly,” which I tend to interpret to
	mean “works with any browser” (among other things.)  The use of
	a specialized, Emacs-only URI scheme would be against that goal.

	Below, I’ve 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’re a plenty of existing URI schemes that’d fit the role.
	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, – especially if it’s 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 “specialization overhead”, 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, – 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 Manual}

   /usr/share/info/emacs-25.0.50.1/elisp/Abbrevs.html:
   <a href="../emacs/Expanding-Abbrevs.html" >…</a>

   doc/lispref/building.texi:
   @xref{Top,, Make, make, GNU Make Manual}.

   /usr/share/info/emacs-25.0.50.1/elisp/Compilation.html:
   <a href="../../latest/make/index.html" >…</a>

	In the latter case, ‘latest’ could be a directory populated 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), ‘latest’
	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)

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A