Debian Bug report logs - #14923
debian doc URN scheme

Package: doc-base; Maintainer for doc-base is Robert Luberda <robert@debian.org>; Source for doc-base is src:doc-base.

Reported by: Christian Schwarz <schwarz@monet.m.isar.de>

Date: Sun, 16 Nov 1997 16:03:00 UTC

Severity: wishlist

Reply or subscribe to this bug.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Christian Schwarz <schwarz@debian.org>:
Bug#14923; Package debiandoc-sgml. Full text and rfc822 format available.

Acknowledgement sent to Christian Schwarz <schwarz@monet.m.isar.de>:
New bug report received and forwarded. Copy sent to Christian Schwarz <schwarz@debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Christian Schwarz <schwarz@monet.m.isar.de>
To: Debian Bugs <submit@bugs.debian.org>
Subject: new <ref> tag for cross references
Date: Sun, 16 Nov 1997 16:53:59 +0100 (CET)
Package: debiandoc-sgml
Severity: wishlist
Version: 1.0.11

The following text has been developed and discussed on the debian-doc
mailing list in May 97. I've just incorporated a few new ideas. 

If you have any questions, feel free to contact me.


Thanks,

Chris

------------------------------------------------------------------------

Cross references
----------------

Goals:
  - we want to have links _between_ documents
  - the links should be as easy to use as current links within a document
  - the specification of the "target" for the link should be independent
    of filenames, www locations, etc.
  - html output: the link should point to either to a local file if present,
    or to an Internet location of the document
  - it would be nice to have a <ref> tag which can be used for any
    cross references (pointing to docs, packages, URL's, etc.) using an URN
    syntax

Proposal:

  <ref id="urn:<namespace> identifier:<path>" text="...">

  namespace is one of the following:

    debiandoc  - debiandoc sgml files
               - these would get resolved to the appropriate generated
                 HTML file residing in a directory below the SGML file
               - path format is "DOCID#id"
                 ie. "debian-policy#binarypkg"

    package    - Debian package
               - should display the name of the package 
                 in HTML output: link to an Internet WWW page describing
                 the package, maintainer, location to download, etc.

    man        - man pages 
               - path format is "name/section" 
                 i.e. "bogomips/1"

    info       - info pages 
               - path format is "(info file name)node name" 
                 i.e. "(gcc)Copying" 

    dir        - directory listing
               - path format is "filename"
                 ie. /usr/doc

    file       - other local files (typically under /usr/doc)
               - path format is "filename"

    html       - html pages (typically under /usr/doc)
               - path format is "filename#anchor"
                 i.e. "/usr/doc/libtiff3/index.html" 

    text       - text file (typically under /usr/doc)
               - path format is "filename"         

    www        - Internet URL
               - path is an URL, e.g. "ftp://ftp.debian.org/"

    dwww       - reference to a dwww menu entry (implementation isn't
                 finalized yet)

    dwwwsearch - reference to a dwww search string (implementation isn't
                 finalized yet)

Examples:

    <ref id="urn:package identifier:bash">
    <ref id="urn:www identifier:http://www.debian.org/" text="Debian's Home Page">


Implementation:

  - Every document gets a unique "document id" (called DOCID below).
    This id is used for file names, to reference the document, and so on.
    Since the name is presented to the user in URLs and directory/file
    names, the name should not by a cryptic abbreviated. Good examples
    are "policy-manual", "users-guide", "developers-reference", etc.

  - The <book> tag gets an "id" attribute. This "id" specifies the
    DOCID.

    This attribute is used to identify the document when using cross
    references, so it is optional, but has to be set if this document
    is referenced by another document.

  - <book>, <chapt>, <sect>, ..., <sect4> objects can be referenced, if
    they provide an "id".

  - debiandoc creates a file called "foo.anchors" (is this name good?)
    if DOCID is set to "foo". This file lists all objects that can be
    referenced by other documents. The syntax used in this file is:

       LABEL=xxx  HTML=yyy  TITLE=zzz  TYPE=ttt  NUM=nnn

    The arguments (xxx, ...) must not include spaces, or they
    have to be surrounded by quotes ("). Quotes within the argument
    have to be escaped (\").

    The LABEL is put together from the DOCID, followed by a colon (:),
    optional followed by a chapter/section id. The HTML value specifies
    the URL of the referenced object. The TITEL arguments contains the
    "title" of the object. TYPE can be one of the following: "DOCUMENT",
    "CHAPTER", "SECTION", dependend on the type of the referenced object.
    The NUM argument gives the TOC number of the object for chapters
    or sections.

    Here is an example (document "Foos and Bars" with DOCID="foo"):

       -----cut-here--------------------
       LABEL=foo: HTML=foo/index.html TITLE="Foos and Bars" \
            TYPE=DOCUMENT
       LABEL=foo:intro HTML=foo/ch-intro.html TITLE="Introduction" \
            TYPE=CHAPTER NUM=1
       LABEL=foo:about HTML=foo/ch-intro.html#about \
            TITLE="About Foos" TYPE=SECTION NUM=1.1
       -----cut-here--------------------

  - The "foo.anchors" files are stored in a common location in the
    filesystem.

  - When debiandoc2html processes an "urn:debiandoc identifier:foo" tag,
    it checks for the "foo.anchors" file. If this file exists, it
    resolves the cross reference. Otherwise, it produces a warning message.

  - The HTML output contains a local reference for "debiandoc" references.
    In addition, a HTML comment statement is included before the <a href>.
    A cgi script could be written to check for these comment statements
    and replace the local <a href> reference with an Internet reference
    if the file does not exist locally.

  - All Debian manuals are installed in the same directory structure, 
    on the local system, on the WWW, and on the FTP servers:

 Filesystem:
  /usr/doc/manuals/debian-policy/index.html
  /usr/doc/manuals/debian-policy.ps.gz (optional)

 WWW server:
  http://www.debian.org/doc/manuals/debian-policy/index.html

 FTP server:
  ftp://ftp.debian.org/debian/doc/manuals/debian-policy.html.tar.gz
  ftp://ftp.debian.org/debian/doc/manuals/debian-policy.text.gz
  ftp://ftp.debian.org/debian/doc/manuals/debian-policy.dvi.gz
  ftp://ftp.debian.org/debian/doc/manuals/debian-policy.ps.gz
  ftp://ftp.debian.org/debian/doc/manuals/debian-policy.sgml.tar.gz


An Example:

   Here is the .sgml file (a few required tags have been dropped):

      <book id="foo">

      <title>Foos and Bars
      <author>Christian Schwarz <email/schwarz@debian.org/
      <toc sect>

      <chapt id="intro">Introduction
      <p>

      <sect id="about">About Foos
      <p>

      ....

   And here is an extract from another document referencing the first:

      ... Please check the <ref id="urn:debiandoc identifier:foo"> manual for details ...

      ... (cf. <ref id="urn:debiandoc identifier:foo#about">) ...

   The lout/text output would look like this:

      ... Please check the Foos and Bars manual for details ...

      ... (cf. Foos and Bars, About Foos) ...

   The HTML output would look like this:

      ... Please check the <!-- DEBIANDOC REFERENCE --><a
      href="../foo/index.html">Foos
      and Bars</a> manual for details ...

      ... (cf. <!-- DEBIANDOC REFERENCE --><a
      href="../foo/intro.html#about">Foos
      and Bars, About Foos</a>) ...

   In the first step, the links will point to the Internet location
   of the manual. However, we can easily implement a cgi script
   that pre-processes all manuals, checks if the "local link" exists,
   and adapts the "href" before the web client gets the document.

Consequences:

  - Only "labeled" objects of a document can be referenced. Thus, the
    authors should provide an id at least for all chapters.

  - One needs the "anchors" file of the other documents at compilation
    time. This produces the "chicken-egg-problem". However, debiandoc
    will just insert "???" and issue a warning message if the anchors
    file is not available instead of aborting. This way, one could
    compile the own document to produce the anchors file, provide this
    for the other authors, and wait for them to provide the anchors
    file of their documents.

  - The links will break if an "id" is renamed. We'll have to use the
    Debian package dependencies to avoid this.

    However, if the manual installed on the Internet site is changed,
    a few old documents installed on some workstation will still point
    to the wrong URL. (I think we can live with this small disadvantage.)

--                  Christian Schwarz
                   schwarz@monet.m.isar.de, schwarz@schwarz-online.com
                  schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
                       
                PGP-fp: 8F 61 EB 6D CF 23 CA D7  34 05 14 5C C8 DC 22 BA
              
 CS Software goes online! Visit our new home page at
 	                                     http://www.schwarz-online.com



Information forwarded to debian-bugs-dist@lists.debian.org, Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>:
Bug#14923; Package debiandoc-sgml. Full text and rfc822 format available.

Acknowledgement sent to "Adam P. Harris" <apharris@burrito.onshore.com>:
Extra info received and forwarded to list. Copy sent to Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>. Full text and rfc822 format available.

Message #10 received at 14923@bugs.debian.org (full text, mbox):

From: "Adam P. Harris" <apharris@burrito.onshore.com>
To: 14923@bugs.debian.org
Subject: thoughts on this wishlist
Date: Sun, 28 Jun 1998 13:29:02 -0400
I think this needs to be re-thought in the light of the emerging
debian metadata standard.  Personally, I would be happy if there
was URL support, a la the linuxdoc package, i.e., a tag like:

  <URL id="http://foo.bar/" name="optional name, defaults to id">

Then, when the metadata format is supported, simply allow one
to refer to metadata elements in some way.  This might be quite
complex, since metadata describes things of arbitrary MIME types.
And a particular document may or may not be installed locally.

Which is to say I'd like to shelf this wishlist and just get URL
support in ASAP.

.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>


Information forwarded to debian-bugs-dist@lists.debian.org:
Bug#14923; Package debiandoc-sgml. Full text and rfc822 format available.

Acknowledgement sent to Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>:
Extra info received and forwarded to list. Full text and rfc822 format available.

Message #15 received at 14923@bugs.debian.org (full text, mbox):

From: Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>
To: "Adam P. Harris" <apharris@burrito.onshore.com>, 14923@bugs.debian.org
Subject: Re: Bug#14923: thoughts on this wishlist
Date: 29 Jun 1998 22:23:12 +0200
Hi,

I was already planning to having this re-thought, especially where to
put things, how to introduce it, how to handle non-local documents,
etc.  But maybe we should re-think the whole approach, although I'm
still in favour of the URN notation which is very intuitive. 

W.r.t. the URL support: this is on my TODO list for version 1.1.0 and
I just implemented an ftpsite/ftppath-like tag pair for this, used
e.g. as <httpsite "www.debian.org"> and <httppath "support.html">.  In
the .html file you then get respectively

  <code>www.debian.org</code>

and

  <A href="http://www.debian.org/support.html"><code>support.html</code></A>

Since this is not be best way to provide URL support (although it can
have its applications), I'll also implement the <url> tag as you 
suggest as a more general reference.  Note that all these reference
tags will be succeeded by the new <ref>. 

I was planning to add some more features before releasing this
version, but I might just as well as release it in a day or two (after 
some more thorough testing and after documenting the SUBDOC feature not
being supported :-).  

Thanks,

Ardo

"Adam P. Harris" <apharris@burrito.onshore.com> writes:

> I think this needs to be re-thought in the light of the emerging
> debian metadata standard.  Personally, I would be happy if there
> was URL support, a la the linuxdoc package, i.e., a tag like:
> 
>   <URL id="http://foo.bar/" name="optional name, defaults to id">
> 
> Then, when the metadata format is supported, simply allow one
> to refer to metadata elements in some way.  This might be quite
> complex, since metadata describes things of arbitrary MIME types.
> And a particular document may or may not be installed locally.
> 
> Which is to say I'd like to shelf this wishlist and just get URL
> support in ASAP.
> 
> .....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
> 
> 

-- 
Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl, ardo@debian.org
home page:  http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp:     3B 1F 21 72 00 5C 3A 73  7F 72 DF D9 90 78 47 F9


Information forwarded to debian-bugs-dist@lists.debian.org, Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>:
Bug#14923; Package debiandoc-sgml. Full text and rfc822 format available.

Acknowledgement sent to "Adam P. Harris" <apharris@burrito.onshore.com>:
Extra info received and forwarded to list. Copy sent to Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>. Full text and rfc822 format available.

Message #20 received at 14923@bugs.debian.org (full text, mbox):

From: "Adam P. Harris" <apharris@burrito.onshore.com>
To: Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>
Cc: 14923@bugs.debian.org
Subject: Re: Bug#14923: thoughts on this wishlist
Date: Mon, 29 Jun 1998 17:39:41 -0400
In message <877m20c5zj.fsf@rivendell.middle-earth.earth> you wrote:
>I was already planning to having this re-thought, especially where to
>put things, how to introduce it, how to handle non-local documents,
>etc.  But maybe we should re-think the whole approach, although I'm
>still in favour of the URN notation which is very intuitive. 

Yes, it *is* nice.  To be honest, I don't really grok URL vs URN, though
I understand that URN are supposed to be more stable, rather like a 
"well known service".  Maybe we should implement (eventually) debian
metadata references as URN, with our own scheme?  
(I.e., "debian://jade/jade.htm" being a reference to the resource and
metadata jade.htm, installed from the package jade, which also happens
to be translatable into a file URL, "file://localhost/usr/doc/jade/jade.htm".
Nice, eh?)

>W.r.t. the URL support: this is on my TODO list for version 1.1.0 and
>I just implemented an ftpsite/ftppath-like tag pair for this, used
>e.g. as <httpsite "www.debian.org"> and <httppath "support.html">.
[...]
>Since this is not be best way to provide URL support (although it can
>have its applications), I'll also implement the <url> tag as you 
>suggest as a more general reference. 

Excellent.  

>Note that all these reference
>tags will be succeeded by the new <ref>. 

Right; this would be the URN-enabled <ref> with a design similar, though
not exactly the same in details, to Christian's design.

Ardo, please count on me if you need any help documenting, DTD writing,
testing, or doing design work!

>I was planning to add some more features before releasing this
>version, but I might just as well as release it in a day or two (after 
>some more thorough testing and after documenting the SUBDOC feature not
>being supported :-).  

Yes, early and often release is good, not that I'm one to talk.

.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>


Information forwarded to debian-bugs-dist@lists.debian.org:
Bug#14923; Package debiandoc-sgml. Full text and rfc822 format available.

Acknowledgement sent to Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>:
Extra info received and forwarded to list. Full text and rfc822 format available.

Message #25 received at 14923@bugs.debian.org (full text, mbox):

From: Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl>
To: "Adam P. Harris" <apharris@burrito.onshore.com>, 14923@bugs.debian.org
Subject: Re: Bug#14923: thoughts on this wishlist
Date: 30 Jun 1998 21:40:30 +0200
"Adam P. Harris" <apharris@burrito.onshore.com> writes:

> In message <877m20c5zj.fsf@rivendell.middle-earth.earth> you wrote:
> >I was already planning to having this re-thought, especially where to
> >put things, how to introduce it, how to handle non-local documents,
> >etc.  But maybe we should re-think the whole approach, although I'm
> >still in favour of the URN notation which is very intuitive. 
> 
> Yes, it *is* nice.  To be honest, I don't really grok URL vs URN, though
> I understand that URN are supposed to be more stable, rather like a 
> "well known service".  Maybe we should implement (eventually) debian
> metadata references as URN, with our own scheme?  
> (I.e., "debian://jade/jade.htm" being a reference to the resource and
> metadata jade.htm, installed from the package jade, which also happens
> to be translatable into a file URL, "file://localhost/usr/doc/jade/jade.htm".
> Nice, eh?)

Yes!  Please hold this thought until we have the <ref> discussion. 

[snip]
> Ardo, please count on me if you need any help documenting, DTD writing,
> testing, or doing design work!

Thanks!  I will certainly keep this in mind.

[snip]
> .....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>

Thanks,

Ardo
-- 
Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl, ardo@debian.org
home page:  http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp:     3B 1F 21 72 00 5C 3A 73  7F 72 DF D9 90 78 47 F9


Changed Bug title. Request was from Ardo van Rangelrooij <ardo@debian.org> to control@bugs.debian.org. Full text and rfc822 format available.

Bug reassigned from package `debiandoc-sgml' to `doc-base'. Request was from Ardo van Rangelrooij <ardo@debian.org> to control@bugs.debian.org. Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Fri Apr 18 06:33:44 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.