Return-Path: 
 <user-return-360-apmail-forrest-user-archive=forrest.apache.org@forrest.apache.org>
Delivered-To: apmail-forrest-user-archive@www.apache.org
Received: (qmail 18428 invoked from network); 9 Aug 2004 10:50:31 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur-2.apache.org with SMTP; 9 Aug 2004 10:50:31 -0000
Received: (qmail 17207 invoked by uid 500); 9 Aug 2004 10:50:31 -0000
Delivered-To: apmail-forrest-user-archive@forrest.apache.org
Received: (qmail 17171 invoked by uid 500); 9 Aug 2004 10:50:30 -0000
Mailing-List: contact user-help@forrest.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:user-help@forrest.apache.org>
list-unsubscribe: <mailto:user-unsubscribe@forrest.apache.org>
list-post: <mailto:user@forrest.apache.org>
Reply-To: user@forrest.apache.org
Delivered-To: mailing list user@forrest.apache.org
Received: (qmail 17160 invoked by uid 99); 9 Aug 2004 10:50:30 -0000
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=
X-Spam-Check-By: apache.org
Received: from [195.200.0.96] (HELO relay1.ftech.net) (195.200.0.96)
  by apache.org (qpsmtpd/0.27.1) with ESMTP; Mon, 09 Aug 2004 03:50:27 -0700
Received: from opal.ftech.net ([212.32.16.127] helo=mailgate.ftech.net)
	by relay1.ftech.net with esmtp (Exim 3.36-ftechp12 #2)
	id 1Bu7jV-0005AW-00
	for user@forrest.apache.org; Mon, 09 Aug 2004 11:50:25 +0100
Received: from pc2.dspadsl.ftech.co.uk ([212.32.45.99] helo=dsp.ftech.co.uk)
	by mailgate.ftech.net with esmtp (Exim 3.36-ftechp12 #1)
	id 1Bu7jV-0002Rn-00
	for user@forrest.apache.org; Mon, 09 Aug 2004 11:50:25 +0100
Received: from CHARLESS (charless.dsp.local [192.168.1.151])
	by dsp.ftech.co.uk (dsp.ftech.co.uk [127.0.0.1])
	(MDaemon.PRO.v7.1.2.R)
	with ESMTP id md50000054056.msg
	for <user@forrest.apache.org>; Mon, 09 Aug 2004 11:50:21 +0100
Message-ID: <006b01c47dfe$a93da090$9701a8c0@dsp.local>
From: "Charles Palmer" <charles@dspdesign.com>
To: <user@forrest.apache.org>
References: <001c01c47d44$e78cd0b0$2401a8c0@dsp.local>
 <1092034737.24717.17468.camel@ighp>
Subject: Re: Understanding linking
Date: Mon, 9 Aug 2004 11:50:17 +0100
Organization: DSP Design
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook Express 6.00.2600.0000
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2600.0000
X-Spam-Processed: dsp.ftech.co.uk, Mon, 09 Aug 2004 11:50:21 +0100
	(not processed: message from valid local sender)
X-MDRemoteIP: 192.168.1.151
X-Return-Path: charles@dspdesign.com
X-MDaemon-Deliver-To: user@forrest.apache.org
X-MDAV-Processed: dsp.ftech.co.uk, Mon, 09 Aug 2004 11:50:22 +0100
X-Virus-Checked: Checked
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

Re: documenting links, and the new sample2.xml I submitted:

I have done some more experimenting and my understanding improves yet again
(wonderful!). The forrest errors that I reported previously are fixed by
changing this code in site.xml:

<files href="../site/">
    <hello_file href="hello.pdf" />
    <test1_file href="test1.html" />
    <test2_file href="test2.html" />
</files>

to this:

<files href="">
    <hello_file href="hello.pdf" />
    <test1_file href="test1.html" />
    <test2_file href="test2.html" />
</files>

I introduced the error while hacking about trying to extend the simple
example to one where the linked-to files were located somewhere other than
in src/documentation/content. I have now sorted that out as well. Could I
suggest that you include the slightly less trivial example:

An extract from the xdocs source file:

<p>Read the <link href="site:dp83816">the Ethernet datasheet</link> </p>

and the site.xml contents:

<files href="files/">
  <pdfs href="pdfs/">
    <dp83816 href="National/DP83816.pdf" />
  </pdfs>
</files>

explaining that the linked-to file is at
src/documentation/files/pdfs/National/DP83816.pdf and that it gets copied
unmodified to build/site/files/pdfs/National/DP83816.pdf

I'll rework my sample2.xml if you like, but it sounds like you are already
cutting and pasting this to other places.

Could I clarify my earlier point about the use of examples and the location
of documentation:

In my experience learning and understanding a new concept is much easier if
the documentation describes a working example that I have at hand, and can
modify to extend the example to fit my actual needs. That is why (IMHO) it
is very useful to have the documentation (wherever it is located) refer to
examples provided within the material generated by the forrest seed process.
That way I can take real source files on my computer and learn by changing
them. If the documentation refers to examples within the main forrest site
then I can't (easily) learn by making changes to them.

It is less important whether the forrest seed material is self documenting,
or whether I have to go elsewhere for the documentation. What is really
valuable is if the documentation refers to source files that I have readily
at hand.

Note that this might mean making the structure of the forrest seed site
slightly more complex, so more general examples can be given as well as the
most trivial case.