URIs for GNU documentation

[Ivan Shmakov]

>>>>> Richard Stallman <address@hidden> 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