How to use "site:" in subdirs and with binaries, and using img (was "site:" fails in subdir with "No pipeline")

[Moshe Yudkowsky <ms...@bl.com>]

I've resolved the problem with "site:" in my subdir, and I've also figured out 
how to reference binaries (*.gz files) using "site:". And how to use <img 
src="foo">.

Since there's no Wiki page for FAQs, I'm going to post the answer here in the 
hope of helping out some other clueless newbie.

(1) Set up the subdirectories correctly; many "BROKEN: No pipeline matched 
request" errors can be resolved by examining site.xml. To set up a tech 
subdirectory, in site.xml you must the following subdir structure:

<technology label="Technology" href="tech/" tab="tech">
	<about label="Index" href="index.html" />
	<downloads label="Downloads" href="index-downloads.html"/>
	<demos label="Demos" href="index-demos.html" />
	<presentations label="Presentations" href="index-talks.html"/>
</technology>

Now files in the tech subdirectory can use <link href="site:foo"> to reference 
any file defined in site.xml.

(2) Using "site:" to link to non-forrest-generated files

To use site to link to non-forrest-generated files -- e.g., a binary packed as 
a "gz" file -- is a two-step process.

(a) in a file structure that starts at the same level as xdocs, your files. I 
wanted my files in files/binaries, so I created src/documuments/files/binaries; 
  files is in the same directory as xdocs.

(b) define files/binaries in site.xml:

<binaries href="files/binaries/">
	<vxml_bio_0_1 href="vxml_bio_0.1.tar.gz" />
	<Voice2IM.20020604.tar.gz href="Voice2IM.20020604.tar.gz" />
</binaries>

You can now use "site:vxml_bio_0_1" to reference the binary. Note that 
"site:binaries/vxml_bio_0.1.tar.gz" will fail.

(3) Images. There's a directory called src/resources/images, and your images 
can go there; but you need to know the trick to reference them. Put foo.png 
there, for example. You can then use <img src="images/foo.png"> from any 
directory or subdirectory to reference foo.png. If you don't use the "images/" 
construct, but just "foo.png", forrest will attempt to find the image whatever 
directory you're currently in.

-- 
  Moshe Yudkowsky
  Disaggregate
  2952 W Fargo
  Chicago, IL 60645 USA

  <http://www.Disaggregate.com>

Re: How to use "site:" in subdirs and with binaries, and using img (was "site:" fails in subdir with "No pipeline")

[Moshe Yudkowsky <ms...@bl.com>]

Nicola Ken Barozzi wrote:

> That construct is deprecated (I know, it's not well documented)

Ah, thanks. With all due respect, I have yet to see an open-source project that 
was well documented; forrest has a little less documentation than some. Not 
that I'm not finding forrest to be very useful at the moment, but the learning 
curve -- the gotcha's and the mysteries -- were more than I expected.

Spamassassin has wiki documentation; see http://wiki.spamassassin.org. The 
documenation there continues to improve.

> and will 
> go away in a future forrest version, as we are moving to a double 
> directory space: one for all the usual docs and images (content), 
> another for artifacts that must be served without any other intervention 
> of forrest (raw).

I cheated. Given the coming deprecation, and followign your advice, I've just 
moved the image to src/documentation/files/images, gave it an entry in 
site.xml, and used src="site:foo" to reference it in the subdirectory.

That's in test. In production I may find myself having to move it elsewhere, 
e.g., to the parallel "raw" structure you noted.

The coming "raw" parallel structure is documented, but only in passing in the 
"samples" directory, and I was a little hesitant to fool around with it.

Thank you very much for your comment, which was extremely helpful.

-- 
  Moshe Yudkowsky
  Disaggregate
  2952 W Fargo
  Chicago, IL 60645 USA

  <http://www.Disaggregate.com>

Re: How to use "site:" in subdirs and with binaries, and using img (was "site:" fails in subdir with "No pipeline")

[Nicola Ken Barozzi <ni...@apache.org>]

Moshe Yudkowsky wrote:
...
> (3) Images. There's a directory called src/resources/images, and your 
> images can go there; but you need to know the trick to reference them. 
> Put foo.png there, for example. You can then use <img 
> src="images/foo.png"> from any directory or subdirectory to reference 
> foo.png. If you don't use the "images/" construct, but just "foo.png", 
> forrest will attempt to find the image whatever directory you're 
> currently in.

That construct is deprecated (I know, it's not well documented) and will 
go away in a future forrest version, as we are moving to a double 
directory space: one for all the usual docs and images (content), 
another for artifacts that must be served without any other intervention 
of forrest (raw).

In the above case, the images should be placed as
   src/documentation/content/xdocs/anywhere/myimage.png

and referenced as
    <img src="anywhere/myimage.png"/>

Keep in mind that in

   src/documentation/content/xdocs/anywhere/subanywhere/

to reference the above image one would do

    <img src="../anywhere/myimage.png"/>

as for other xdocs (in this case it's better to put it in site.xml, as 
IMHO relative links like this usually denote a more generic resource)

Because of this, we will have instead of

    src/documentation/content/xdocs/
    src/documentation/content/

something like

    src/site/
    src/site/raw

that is much easier to use.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------