From owner-freebsd-doc  Mon Jul  3 11:25:28 1995
Return-Path: doc-owner
Received: (from majordom@localhost)
          by freefall.cdrom.com (8.6.10/8.6.6) id LAA19491
          for doc-outgoing; Mon, 3 Jul 1995 11:25:28 -0700
Received: from grendel.csc.smith.edu (grendel.csc.smith.edu [131.229.222.23])
          by freefall.cdrom.com (8.6.10/8.6.6) with ESMTP id LAA19483
          for <doc@freebsd.org>; Mon, 3 Jul 1995 11:25:27 -0700
Received: from localhost (jfieber@localhost) by grendel.csc.smith.edu (8.6.5/8.6.5) id OAA09148; Mon, 3 Jul 1995 14:27:08 -0400
From: jfieber@grendel.csc.smith.edu (John Fieber)
Message-Id: <199507031827.OAA09148@grendel.csc.smith.edu>
Subject: Re: What's the story with the FAQ?
To: gclarkii@freefall.cdrom.com (Gary Clark II)
Date: Mon, 3 Jul 1995 14:27:07 -0400 (EDT)
Cc: doc@freebsd.org
In-Reply-To: <199507011125.EAA16261@freefall.cdrom.com> from "Gary Clark II" at Jul 1, 95 04:25:54 am
Content-Type: text
Content-Length: 1521      
Sender: doc-owner@freebsd.org
Precedence: bulk

[CCd to doc@freebsd.org because this brings up document
architecture issues of general interest.]

Gary Clark II writes:
> I need "TEXT" versions of the stuff in the handbook before I can
> point ftp users at them.  Thats what I thought /FAQ/Text was!

If we have a hypertext FAQ, and a hypertext handbook that is to
be referenced from the FAQ, pointing at a plain text version
is a pretty big step backward.  

In the FAQ use a relative url of "../handbook/whatever.html".  As
for "whatever", grep the sgml files in the handbook directory for
'<label id'.  Every .sgml file in the handbook directory (except
authors.sgml and handbook.sgml) has a label matching the filename
sans .sgml.  For example, ctm.sgml has a <label id="ctm"> and
could be referenced from the faq with a url of
"../handbook/ctm.html".  My latest commit to sgmlfmt(1) provides
for making symbolic links for every <label id="..."> that point
to the appropriate page since section numbers or html file
numbers are moving targets.

This method of linking between documents does leave some elegance
to be desired, particularly because it breaks if either the FAQ
or the handbook are not in the same position relative to each
other.  Using an absolute link to www.freebsd.org would break for
people who have the HTML files local and no net.conection.  It
would be nifty if the HTML standard supported the specification
of primary and alternate URL's in the anchor tag....

-john

=== jfieber@cs.smith.edu ========== Come up and be a kite!  --K. Bush ===