[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
URIs for GNU documentation
From: |
Ivan Shmakov |
Subject: |
URIs for GNU documentation |
Date: |
Tue, 16 Dec 2014 19:17:36 +0000 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) |
>>>>> 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
- Re: On being web-friendly and why info must die, (continued)
- Re: On being web-friendly and why info must die, Richard Stallman, 2014/12/16
- Re: On being web-friendly and why info must die, Richard Stallman, 2014/12/16
- Re: On being web-friendly and why info must die, Ludovic Courtès, 2014/12/16
- Re: On being web-friendly and why info must die, Thien-Thi Nguyen, 2014/12/17
- Re: On being web-friendly and why info must die, Richard Stallman, 2014/12/17
- Re: On being web-friendly and why info must die, Thien-Thi Nguyen, 2014/12/17
- Re: On being web-friendly and why info must die, Richard Stallman, 2014/12/21
- URIs for GNU documentation,
Ivan Shmakov <=
- Re: URIs for GNU documentation, Richard Stallman, 2014/12/21
- Re: On being web-friendly and why info must die, Stefan Monnier, 2014/12/15
- Re: On being web-friendly and why info must die, Richard Stallman, 2014/12/16
- Re: On being web-friendly and why info must die, Steinar Bang, 2014/12/17
- Re: On being web-friendly and why info must die, Richard Stallman, 2014/12/17
- Re: On being web-friendly and why info must die, Stefan Monnier, 2014/12/17
- Re: On being web-friendly and why info must die, Phillip Lord, 2014/12/17
Re: On being web-friendly and why info must die, Lennart Borgman, 2014/12/11