skins to wrong directory in transition from 0.5 to 0.7

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

I'm having a great deal of difficulty transitioning from 0.5.1 to 0.7. 
I've searched the archives, but I can't find some very specific answers.

I'm behind a firewall that I control. While I can easily "wget" the file 
http://forrest.apache.org/skins/skins.xml, my attempt at running forrest 
  fails, with the following error in my log:

> fetch-skins-descriptors:
> fetching descriptor: http://forrest.apache.org/skins/skins.xml
> Getting: http://forrest.apache.org/skins/skins.xml
> Error getting http://forrest.apache.org/skins/skins.xml to /usr/local/share/forrest-current/main/webapp/skins/skins-1.xml


Now, I admit that I don't understand this, for two reasons.

(1) The first is whether the "Getting" failed, or whether writing to the 
skins.xml to /usr/local/share/forrest-current failed.

(2) The second is more important: why would the skins end up in 
/usr/local/share/forrest-current, as implied by the log? I have 
project.skins-dir set to ${project.content-dir}/skins, which puts it in 
a sub-directory in user space and is specific to a particular project. 
The error implies that only super-user can run forrest, or that any 
change to the skin would require super-user approval. This is very 
different than in 0.5, and not covered in the FAQ.

I suspect that I'm supposed to "install" the skins as super-user the 
first time through, but again that's not reasonable. I want to use the 
skins that I have in my user space.

I also have other issues:

* I have set forrest.skins.descriptors to 
file://./src/documentation/skins/skins.xml, but the system still 
attempts to fetch http://forrest.apache.org/skins/skins.xml.

* The FAQ states that if I fail because I'm behind a firewall, I should 
use the proxy and host settings. That's not a reasonable suggestion! I 
don't need to proxy anything else, and clearly there's a different 
problem at work.

* The new skins.xml file isn't documented, as far as I can tell. It's 
not all that difficult to understand by reading it, but it'd be nice to 
understand :
  - what it does
  - whether I can use URLs of the type "file"
  - whether I can use relative path names (and where they start out 
relative to) in "file://" style skin path names
  - whether any custom skin I create needs to be put into the skins.xml file
   - and other matters that will no doubt come to mind when I finally 
get 0.7 to work.
   - Or, for that matter, where the "best practices" location is for 
"skins.xml" if I use a local copy.

Does someone have this information?

Re: skins to wrong directory in transition from 0.5 to 0.7

[Ross Gardler <rg...@apache.org>]

Moshe Yudkowsky wrote:
> I'm having a great deal of difficulty transitioning from 0.5.1 to 0.7. 
> I've searched the archives, but I can't find some very specific answers.

Did you follow the instructions for upgrading from 0.6 before attampting 
the upgrade to 0.7?

> I'm behind a firewall that I control. While I can easily "wget" the file 
> http://forrest.apache.org/skins/skins.xml, my attempt at running forrest 
>  fails, with the following error in my log:
> 
>> fetch-skins-descriptors:
>> fetching descriptor: http://forrest.apache.org/skins/skins.xml
>> Getting: http://forrest.apache.org/skins/skins.xml
>> Error getting http://forrest.apache.org/skins/skins.xml to 
>> /usr/local/share/forrest-current/main/webapp/skins/skins-1.xml
> 
> 
> 
> Now, I admit that I don't understand this, for two reasons.
> 
> (1) The first is whether the "Getting" failed, or whether writing to the 
> skins.xml to /usr/local/share/forrest-current failed.

Do forrest -verbose and you'll get more info about the failure.

> (2) The second is more important: why would the skins end up in 
> /usr/local/share/forrest-current, as implied by the log? I have 
> project.skins-dir set to ${project.content-dir}/skins, which puts it in 
> a sub-directory in user space and is specific to a particular project. 
> The error implies that only super-user can run forrest, or that any 
> change to the skin would require super-user approval. This is very 
> different than in 0.5, and not covered in the FAQ.

The skin descriptor file (skins.xml) is only retrieved if Forest cannot 
find the skin it is being told to use. Please ensure that you are using 
a skin that is present (set in forrest.properties)

> I suspect that I'm supposed to "install" the skins as super-user the 
> first time through, but again that's not reasonable. I want to use the 
> skins that I have in my user space.

No, all Forrest supplied skins are provided as part of the initial 
install. The dowload of the skins descriptor file is only necessary if 
you are using a third party skin that we cannot distribute.

Which skin are you trying to use (set in forrest.properties)

> I also have other issues:
> 
> * I have set forrest.skins.descriptors to 
> file://./src/documentation/skins/skins.xml, but the system still 
> attempts to fetch http://forrest.apache.org/skins/skins.xml.

That should not happen. It sounds like it is using the default setting 
provided by forrest in default-forrest.properties. Can you please 
veryify if this is the case.

> * The FAQ states that if I fail because I'm behind a firewall, I should 
> use the proxy and host settings. That's not a reasonable suggestion! I 
> don't need to proxy anything else, and clearly there's a different 
> problem at work.

The proxy and host settings are what are used to pass through many 
firewalls. It isn't necessarily a proxy, but it tends to be called that 
by convention. If you are able to retrieve the file as you describe via 
http then you need not worry about this.

> * The new skins.xml file isn't documented, as far as I can tell. 

It's part of a system allowing skins to be downloaded on demand.

The skin packaging system has never been utilised a great deal, quite 
possibly because it was never documented. All we have is the woeful page 
at http://forrest.apache.org/docs_0_70/skin-package.html

It's never become an issue because people have not donated their skins 
and so has never been used. If your config files are set up correctly 
you need not worry about this since, as I said earlier, if Forrest can 
find your skin then it just gets on with it and doesn't try and download 
anything. Since default skins are provided in the download it's not 
usually an issue.

> It's 
> not all that difficult to understand by reading it, but it'd be nice to 
> understand :
>  - what it does

Identifies skin packages that can be downloaded on demand. This allows 
third parties to distribute skins.

>  - whether I can use URLs of the type "file"

Yes, and you can have multiple URLS

>  - whether I can use relative path names (and where they start out 
> relative to) in "file://" style skin path names

not sure

>  - whether any custom skin I create needs to be put into the skins.xml file

Only if you want to redistribute it

>   - and other matters that will no doubt come to mind when I finally get 
> 0.7 to work.

If you have your configs set up correctly and don't wnat to distribute 
your skin then you can ignore skins.xml

>   - Or, for that matter, where the "best practices" location is for 
> "skins.xml" if I use a local copy.

That's up to you, but is only relevant if you want to redistribute (I'm 
repeating myself aren't I ;-)

> Does someone have this information?

Forget skins.xml and focus on why it seems that you forrest.properties 
are not set correctly. You problem is that when Forrest looks for your 
skin it cannot find it.

Ross