You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by Charles Palmer <ch...@dspdesign.com> on 2004/08/08 14:40:11 UTC
Understanding linking
Team
I've been spending a bunch of time trying to understand how to link between files. I certainly have a better idea now than I did yesterday morning. Not being critical, but some of the documentation wasn't too clear, so I've tried to write my own, and would like to pass it back to be checked, corrected, enhanced, and if thought worthwhile, used to replace the existing sample2.xml file that comes out of the forrest seed operation.
A few things:
1 I don't know whether user@forrest.apache.org accepts file attachments - I'll find out soon enough!
2 You will need to make the small alteration to site.xml that the file talks about.
3 The process does give error messages like:
../site/test1.html BROKEN: C:\Forrest\projects\Improved_Original\build\tmp\context\content\site\test1.xml (The system cannot find the path specified)
No doubt there is a way of fixing this, that could be added to my work.
4 In terms of future documentation work, IMHO it would be good if the documentation uses the site that forrest seed creates for examples of useage. After all, that is what users will have on their local machine, and they can easily examine the code and make their own changes. In contrast the menus and linking document at http://forrest.apache.org/docs/linking.html uses extracts from the main forrest site, which is more difficult for users to examine, or even theoretical examples that users can't examine.
Charles
Re: Understanding linking
Posted by Clay Leeds <cl...@medata.com>.
On Aug 9, 2004, at 5:04 AM, David Crossley wrote:
> Charles Palmer wrote:
>> 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.
>
> Your ideas are good. We can build on the infrastructure
> that we have. Perhaps we can can different seeds to suit
> various circumstances.
>
> --
> David Crossley
Perhaps one could have a couple of seed 'targets':
- /forrest seed/ (simple docs similar to current output)
- /forrest seed-docs/ (builds more complete Docs)
- /forrest seed-core-docs/ (builds complete CORE Docs)
I'm not certain of the difference between the seed-docs &
seed-core-docs, but perhaps there's such a need to differentiate.
Web Maestro Clay
Re: Understanding linking
Posted by David Crossley <cr...@apache.org>.
Charles Palmer wrote:
<snip/>
>
> I'll rework my sample2.xml if you like, but it sounds like you are already
> cutting and pasting this to other places.
No wait. Once you submit something you would need to give
us a chance to rework it and incorporate it. Then you can
get the new source and build upon it. Just save your ideas
in a text file for now, then add them later.
> 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.
I agree entirely, and i work this way too.
We have established the shell of an example site.
The next stage is to flesh it out with worked examples.
There is a trade-off with how much actual documentation
and explanation to put in there. It would be better to be
concise, and have the lengthy explanations in the core docs.
The core docs are what compose our final website. It is good
to have the documentation in the open and so not need to
duplicate.
Now here is an idea. We could generate the seed site docs
and put them online as part of the website. That way we
only need to document in one place ... a self-describing
example site.
> 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.
Well you can do that too. You have a local copy of the
core docs. You can tweak it and send patches to us.
> 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.
Your ideas are good. We can build on the infrastructure
that we have. Perhaps we can can different seeds to suit
various circumstances.
--
David Crossley
Re: Understanding linking
Posted by Charles Palmer <ch...@dspdesign.com>.
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.
Re: Understanding linking
Posted by David Crossley <cr...@apache.org>.
Charles Palmer wrote:
> I've been spending a bunch of time trying to understand how to link
> between files. I certainly have a better idea now than I did yesterday
> morning. Not being critical, but some of the documentation wasn't too
> clear, so I've tried to write my own, and would like to pass it back
> to be checked, corrected, enhanced, and if thought worthwhile, used
> to replace the existing sample2.xml file that comes out of the forrest
> seed operation.
Thanks. I have started to incorporate your document.
It is going to be added to the core Forrest documentation
to support the main "Menus and linking" document. This new
document will be more "explanation and demonstration"
whereas the other one has the full details.
Over in the "forrest seed" demo site i will add a more
concise demonstration.
--
David Crossley
Re: Understanding linking
Posted by David Crossley <cr...@apache.org>.
Charles Palmer wrote:
> I've been spending a bunch of time trying to understand how to link
> between files. I certainly have a better idea now than I did yesterday
> morning. Not being critical, but some of the documentation wasn't too
> clear, so I've tried to write my own, and would like to pass it back
> to be checked, corrected, enhanced, and if thought worthwhile, used
> to replace the existing sample2.xml file that comes out of the forrest
> seed operation.
Thanks. This is one way that documentation will be improved,
by people making contributions.
> A few things:
>
> 1 I don't know whether user@forrest.apache.org accepts file
> attachments - I'll find out soon enough!
We would far prefer that people use the Issue tracker.
Some reasons:
* Easy to overlook it in a busy mail archive.
* With the Issue tracker, one of us can assign the task
and work on adding it. With mail attachment we could
needlessly duplicate our work.
* Now every one of us has a copy in our local email
archives.
* Needless copy is sitting in every remote email archive.
* Issue tracker provides a better audit trail.
> 2 You will need to make the small alteration to site.xml that the
> file talks about.
> 3 The process does give error messages like:
>
> ../site/test1.html BROKEN:
> C:\Forrest\projects\Improved_Original\build\tmp\context\content\site\test1.xml (The system cannot find the path specified)
>
> No doubt there is a way of fixing this, that could be added to my
> work.
>
> 4 In terms of future documentation work, IMHO it would be good if
> the documentation uses the site that forrest seed creates for examples
> of useage.
That is a good idea for examples of usage. Yesterday i improved
the ihtml sample.
However i think that comprehensive documentation like your
contribution should be in the core documentation.
> After all, that is what users will have on their local machine, and
> they can easily examine the code and make their own changes.
However you have the full documentation for the forrest website
in your local forrest too. Do 'forrest run' in the top-level
forrest directory.
> In contrast the menus and linking document at
> http://forrest.apache.org/docs/linking.html uses extracts from the
> main forrest site, which is more difficult for users to examine, or
> even theoretical examples that users can't examine.
The main documentation will still be the core forrest docs.
We definitely should enhance the 'forrest seed' too.
Thanks again for your contribution. We will investigate.
--
David Crossley
Re: Understanding linking
Posted by David Crossley <cr...@apache.org>.
Charles Palmer wrote:
> I've been spending a bunch of time trying to understand how to link
> between files. I certainly have a better idea now than I did yesterday
> morning. Not being critical, but some of the documentation wasn't too
> clear, so I've tried to write my own, and would like to pass it back
> to be checked, corrected, enhanced, and if thought worthwhile, used
> to replace the existing sample2.xml file that comes out of the forrest
> seed operation.
I have taken the approach of a comprehensive example
in the seed site which demonstrates all types of linking
to generated files and to raw files.
Your explanations seemed a bit confusing. I surmised that
we are not being clear about how the resource space maps
across to the final produced website space. I hope that
the examples and diagram explains that better.
--
David Crossley