Received: (at submit) by bugs.debian.org; 16 Nov 1997 15:57:58 +0000 Received: (qmail 8534 invoked from network); 16 Nov 1997 15:57:55 -0000 Received: from nymphe.m.ISAR.de (Umonet@nymphe.m.ISAR.de@193.141.69.3) by 205.229.104.5 with SMTP; 16 Nov 1997 15:57:55 -0000 Received: (from Umonet@localhost) by nymphe.m.ISAR.de (8.8.7/8.8.7/nymphe-2.1) with UUCP id RAA13265 for submit@bugs.debian.org; Sun, 16 Nov 1997 17:01:39 +0100 (CET) X-Authentication-Warning: nymphe.m.ISAR.de: Umonet set sender to schwarz@monet.m.isar.de using -f Received: from localhost (schwarz@localhost) by monet.painters.schwarz-online.com (8.8.5/8.8.5) with SMTP id QAA23384 for ; Sun, 16 Nov 1997 16:53:59 +0100 Date: Sun, 16 Nov 1997 16:53:59 +0100 (CET) From: Christian Schwarz X-Sender: schwarz@monet To: Debian Bugs Subject: new tag for cross references Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII 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 tag which can be used for any cross references (pointing to docs, packages, URL's, etc.) using an URN syntax Proposal: 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: 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 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. - , , , ..., 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 cgi script could be written to check for these comment statements and replace the local 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): 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