forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Charles Palmer" <>
Subject Re: Understanding linking
Date Mon, 09 Aug 2004 10:50:17 GMT
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" />

to this:

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

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" />

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.

View raw message