Re: [RT] Writing generated page to disk in "forrest run"

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> David Crossley wrote:
> 
> >I do have one concern. First some background.
> >
> >See the new FAQ:
> >http://forrest.apache.org/docs/faq.html#crawler
> >
> >The user (not knowing exactly how Forrest works)
> >had changed the only link, to point to an offsite
> >page instead. Therefore the local document stopped
> >being processed by the 'forrest site' command, yet
> >looked fine in 'forrest run' mode. Calamity.
> 
> In this case the page would be saved in the build/site directory when 
> the user viewed it to check their edits. So when they did svn up, all 
> would be well (yes, I skipped the step of getting from build/site to the 
> svn checkout, we'll come back to that when initial experiments are in 
> place).

No need. The normal workflow proceeeds.

For example in our Forrest project, a committer
manually copies the file from 
/svn/asf/forrest-trunk/site-author/build/site
to /svn/asf/forrest-site

If people don't like those manual steps then they
can use a local forrestbot.

Some other projects that use Forrest, e.g. Incubator
have switched the forrest.properties so that documents
are generated directly into their publish directory
so no need for the manual copy step. At Incubator
the build directory is called "site-publish" rather
than the normal "build/site".

> >So my concern is that users will forget to link
> >the new document into the system. Perhaps we can
> >automatically add a default link (perhaps to a
> >supplementary site.xml) and issue a warning to
> >the console.
> 
> This is a slightly different case. If I understand the case here the 
> user has created a new page using their chosen editor and gone to it 
> directly by typing http://localhost:8888/myNewPage.html, but has not 
> added a link to it from a page or a menu.

That is correct. And they will probably blame forrest :-(

> In this case the page will still end up in the final local build (the 
> previewed and saved it), it will therefore end up on the live server (as 
>  in the previous use case).
> 
> The lack of a link is a very clear user error and could not be claimed 
> to be unexpected behaviour. I don't think we need to worry ourselves 
> about it.

Okay, there is already an FAQ.

-David

> Having said that, we could provide a tool to search the known document 
> tree and tell us what pages link to the current page. Not sure how 
> useful this would be (sounds more like a CMS feature than a publisher 
> feature to me).
> 
> Ross

Re: [RT] Writing generated page to disk in "forrest run"

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> David Crossley wrote:
> >Ross Gardler wrote:
> >>David Crossley wrote:
> 
> >>>So my concern is that users will forget to link
> >>>the new document into the system. Perhaps we can
> >>>automatically add a default link (perhaps to a
> >>>supplementary site.xml) and issue a warning to
> >>>the console.
> >>
> >>This is a slightly different case. If I understand the case here the 
> >>user has created a new page using their chosen editor and gone to it 
> >>directly by typing http://localhost:8888/myNewPage.html, but has not 
> >>added a link to it from a page or a menu.
> >
> >That is correct. And they will probably blame forrest :-(
> >
> >>In this case the page will still end up in the final local build (the 
> >>previewed and saved it), it will therefore end up on the live server (as 
> >>in the previous use case).
> >>
> >>The lack of a link is a very clear user error and could not be claimed 
> >>to be unexpected behaviour. I don't think we need to worry ourselves 
> >>about it.
> >
> >Okay, there is already an FAQ.
> 
> Surely not (I'm new on the Incubator list ;-). I mean the page is 
> generated when they view it locally, it is uploaded to the server when 
> they do "svn ci", but it can't be linked to, do they really expect 
> Forrest to write their docs for them?

People who don't understand Forrest are expecting it
to process every document on the filesystem.

The new FAQ explains it:
http://forrest.apache.org/docs/faq.html#crawler

-David
> Or are you saying they will want to see it automatically appear i the 
> site navigation? If so then it is a FAQ with an example of how we do 
> that in the Resume plugin.
> 
> Ross

Re: [RT] Writing generated page to disk in "forrest run"

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

David Crossley wrote:
> Ross Gardler wrote:
> 
>>David Crossley wrote:

...

>>>So my concern is that users will forget to link
>>>the new document into the system. Perhaps we can
>>>automatically add a default link (perhaps to a
>>>supplementary site.xml) and issue a warning to
>>>the console.
>>
>>This is a slightly different case. If I understand the case here the 
>>user has created a new page using their chosen editor and gone to it 
>>directly by typing http://localhost:8888/myNewPage.html, but has not 
>>added a link to it from a page or a menu.
> 
> 
> That is correct. And they will probably blame forrest :-(
> 
> 
>>In this case the page will still end up in the final local build (the 
>>previewed and saved it), it will therefore end up on the live server (as 
>> in the previous use case).
>>
>>The lack of a link is a very clear user error and could not be claimed 
>>to be unexpected behaviour. I don't think we need to worry ourselves 
>>about it.
> 
> 
> Okay, there is already an FAQ.

Surely not (I'm new on the Incubator list ;-). I mean the page is 
generated when they view it locally, it is uploaded to the server when 
they do "svn ci", but it can't be linked to, do they really expect 
Forrest to write their docs for them?

Or are you saying they will want to see it automatically appear i the 
site navigation? If so then it is a FAQ with an example of how we do 
that in the Resume plugin.

Ross