[RT] Super Simple Site Generation Tool

[Leo Simons <ma...@leosimons.com>]

Hi gang,

It pains me to say this (Forrest is a cool project and I
consider at least some of its active developers and community
members my friends) but we've muddled around long enough.

I think that, for the incubator website, Apache Forrest

  * is too unstable as a codebase
  * is way too complex
  * has too many features we don't need and solves
    too many problems we don't have
  * has a learning curve that is too big
  * does not work well with the SVN-based publishing
    process we want to use
  * is not well-understood by enough of the current
    Incubator volunteers
  * has caused frustration for too many of the current
    Incubator volunteers

I think this needs solving. I think this needs solving in
general, not just for the Incubator (I have the exact same
problem over at Gump, which also has a horrendously outdated
website which also uses Apache Forrest).

== Use case ==

In particular, the use case we are looking at can be codified
in the following workflow:

  # 1) figure out how to edit docs...
  curl http://svn.../site/README | less

  # 2) get stuff from SVN
  svn co http://.../site
  cd site

  # 3) edit docs
  $EDITOR x/y/z/foo.xml

  # 4) validate edit, generate results
  ./build # must work on windows, linux, os x, solaris, ...

  # 5) check results locally
  svn diff
  mozilla-firefox build/x/y/z/foo.html

  # 6) commit
  svn commit -m "foo.xml: fix typo. Its 'spelling', not 'speling'."

  # 7) validate commit
  mozilla-firefox http://staging.incubator.apache.org/x/y/z/foo.html

  # 8) x hours later...
  mozilla-firefox http://incubator.apache.org/x/y/z/foo.html

== Requirements ==

Now, steps 1-7 should be possible in about 5 minutes (provided you're
on broadband network and a 600mhz/128mb/5400rpm machine. 5 minutes includes
reading the documentation and the like), and about 10 seconds for someone
who already knows how the tool works and has the checkout on his machine
already.

Step 4 should be so quick and natural and trustable that steps 5,7 and 8
are not really neccessary once you've used the tool a few times.

The produced HTML should be simple, clean, valid XHTML 1.1 strict, with
navigational stuff similar to that available on other parts of
www.apache.org. This output should be customizable in a manner that's
similarly simple as the above use case (for eg adding banner logos or
updating a project logo), though its allowed to be a little harder (eg
having to learn some template language is just fine).

The source format should be simple, clean, and simple to grok (within the
basic 5 minute period mentioned above) for anyone who knows how to write
basic HTML (eg <b>, <em>, <h1>). The translation from the source to the
produced HTML should be obvious and without surprises.

There should be a simple file (probably XML) for specifying navigational
elements where again the transformation from source to html is so obvious
that anyone who has ever edited XML doesn't need to RTFM.

== Available tools ==

None of the other generally available tools satisfy all the above
requirements at the moment.

 * forrest
   * requires installing forrest, which takes way more than 5 mins in and
     of itself
   * basically it fails many of the use case basics (too heavyweight,
     takes more than 3 minutes to learn, input->output transforms too
     complex), which is probably because I wrote the use case to contrast
     with the current forrest process
   * the transformation is not predictable enough

 * maven
   * requires installing maven, which takes 5 mins in and of itself
     * maven 1 not easy enough to install into svn self-contained
       * maven 1� will essentially be "dead" as everyone migrates to
         maven 2
     * don't know about maven 2 yet, but it doesn't have a very widely
       installed base yet, since it was just released
   * the source xdoc format is not simple or clean enough
   * the validation step is not complete enough
   * the transformation is not predictable enough
   * changing the stylesheet is not simple enough
     * if maven is upgraded your entire look and feel may change as
       well as other things (eg the xdoc plugin is not stable enough)

 * anakia
   * the source xdoc format is not simple or clean enough
   * the validation step is not complete enough
   * the transformation is not predictable enough
   * managing navigational elements is not simple or clean enough

 * others
   * no doubt there are many that could be used

== Possible steps forward? ==

Given the above, fixing forrest seems like a lot of work. I think its a
fundamentally bad fit, being built on top of many many layers of java code
and several frameworks makes it too heavy by definition. However, since
it is very easy to customize forrest to output the source format for
another tool, and we have ready access to forrest experts, migrating away
from forrest is probably not very painful (I think it involves writing some
XSLT). As long as the source format stays XML, moving back to forrest later
is also not painful. Standards-based. Lack of lock-in. Good.

Moving back to anakia is possible, but satisfying the validation requirement
is always going to be hard because of its use of velocity rather than "real"
XML parsing.

Moving forward to maven 2 is probably possible but I think the same argument
against anakia still applies to its document generation process. One big
advantage with maven is that its easy to also automate many of the other bits
of workflow, eg doing things like the 'svn commit' too.

Step 7 and 8 depend on what the site-dev at apache.org people come up with;
right now this is more like having to do an "svn up" remotely, setting up
a HTTP proxy, etc, or skip 7, and just do 8, with x == 2. But that'll be
fixed. Lots of plans made, apparently. Haven't been able to figure out what
the status is right now (seems there's no code for steps 1-6 at the moment),
but its definitely going to be compatible with any tool satisfying the above
use case. See:

  http://people.apache.org/~rgardler/site-dev/Site-Build.html

The site-dev people have been working on some other kinds of tools, including
one that uses Perl+XSL, which shows just how simple "step 4" at its core really
is:

  #!/usr/local/bin/perl

  use strict;

  my $xdocdir = "xdoc";
  my $htmldir = "html";
  my $xslfn = "xsl/xdoc2html.xsl";

  opendir(XDOC, $xdocdir) || die("Couldn't open directory $rdfdir");
  while (my $r = readdir(XDOC)) {
      next unless $r =~ /^[a-zA-Z].*\.xml$/;
      my $infn = "$xdocdir/$r";
      print "Processing $infn\n";
      my $outfn = "$htmldir/$r";
      $outfn =~ s/\.xml$/\.html/;
      `xsltproc $xslfn $infn > $outfn`;
  }
  closedir(RDF);

Some things to notice...

 * needs xsltproc to be installed
 * error reporting not so intuitive (just the output from xsltproc)
 * no clear abort on error
 * doesn't walk directories (I think perls readdir reads the current
   directory only)
 * specification of navigational elements not easy enough (eg no
   maven-style site.xml)
(* also note some of the use case being addressed depends on the XSLT
   file)

But these kinds of things aren't exactly hard to address. So I think
I'm going to spend a day or maybe two writing a dedicated script that
does the above, and a little more, and then once done I'll spec up
what forrest should be spitting out, and ask for a volunteer to write
the neccessary stylesheets and do the conversion.

The code for this is probably going to end up somewhere inside

  https://svn.apache.org/repos/asf/infrastructure/site-tools/trunk

Unless there's lots of discussion resulting from the above on site-dev
(there seems to be a lot of history to this topic), then it'll end up
somewhere else.

Its probably going to be written in python and will probably use minidom
and the Kid template language. Its probably going to have a source XML
format that is a subset of XHTML 1.1 and specified as a DTD file. I think
I'll do away with a "site.xml" or anything like that and just specify
the menu as an XHTML snippet, since I've never ever seen site.xml files
used for anything but generating websites. I'll try and write the critter
so that its easily thrown away and replaced by something written in Perl
or Java.

I think I'll call it xdok.

I'll send another email once I have something working and ready for a
demo.

>From there, we'll see where it goes.

- LSD

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

David Crossley wrote:
> Geir Magnusson Jr. wrote:
> > 
> > For the next one, I'll do that.  For this one, I'll assume it's in  
> > safe and responsible hands.
> 
> http://forrest.apache.org/docs/faq.html#crawler

I meant to also say i just added that FAQ today.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Ross Gardler wrote:
> Geir Magnusson Jr wrote:
> >>Forrest is much more than the "simple site generation tool" that the 
> >>subject says is wanted here, I recognise that Forrest may not be the 
> >>right tool for this job. I happen to disagree, but I recognise the 
> >>possibility.
> >
> >Well, if you believe Forrest could be, then do it :)  
> 
> I think we *are* doing it. Leo just sent a very useful mail to our user 
> list and to myself (actually it is stuck in moderation since he is not 
> subscribed). I've prepared my response there.
> 
> It seems that around 80% of the issues raised either have been addressed 
> or are in the process of being addressed. The problem is not one of 
> doing it, but accepting that we are doing it, and working with us to 
> understand it.
> 
> Of course that remaining 20% is vital to us and very helpful feedback.
> 
> >Some basic things 
> >that you've heard here -
> >
> >1) Don't make us checkout some fixed branch of source and build it. I 
> >was recently admonished for using the actual release from the project to 
> > build the Incubator site.   I used to want to build everything, 
> >including my Linux Kernels.  I'm too old now.
> 
> I have no idea why you are using the release branch rather than the 
> binary release. There are no bug fixes in that branch that I am aware 
> of. If I am mistaken you could have asked us (via our dev list) to 
> create a binary snapshot for you - I'd have been more than happy to do so.
>
> I only just joined this list because I became aware of issues with 
> Forrest, I don't know the history here.

There are bugfixes. I would not have specified the release branch
if there was no need. Cannot think what at the moment but they
were important. Sure we could try to make an official release,
but our project is small, so that is an added burden.

Snapshot? Hmm maybe, sorry i had not thought of
doing that, just expected that the old hands
would have no trouble with SVN.

Geir you say "admonished". Please remember that your
commit of the generated docs was huge because you
reverted a bugfix by not using the specified version.
You slammed Forrest for the size of the commit.
I explained it and fixed it for you.

> >2) Reduce the surprises.  Consider that many people here have become 
> >accustomed - rightly or wrongly - to the way Anakia tries to render 
> >everything in the doc tree, and see what you can do to fix that and 
> >mimic that workflow and the user expectations that arise from knowing it.
> 
> There are good reasons why we do not render everything in the document 
> tree, and we will never do so by default.
> 
> If this ever becomes my own itch, I'll add a config property to 
> optionally include everything in the doc tree for users like yourself. 
> In the meantime, how to do it is explained in our FAQ, so should you 
> ever use Forrest again and you need this feature we'd welcome a patch.
> 
> As for workflow, I think I covered this in earlier messages, Forrest 
> does support the workflow outlined by Leo and yourself.
> 
> >3) When I touch something via browser in 'forrest run' mode, WRITE THE 
> >CHANGE TO DISK.  I (as the user) think that I'm looking at the site as 
> >rendered, and was really stumped when no such change really happened.

However the trouble was that in a prior commit
you had removed the sole relative link to the document.

> This is a new feature request I've never heard before. It actually makes 
> alot of sense, and like all good ideas is really obvious to anyone but a 
> developer who is too comfortable with the tool.
> 
> It would address a common concern (have to render the whole site even if 
> a single page has changed). I'll look into this one on the Forrest dev list.
> 
> >3) Don't expect that I'm going to go and read Forrest docs to do what I 
> >(as the user) think of as basic things.  I won't.   I did read the 
> >5-step on the Forrest site that fateful saturday when I was trying to 
> >fix that orphan page, and I thought I did all the right things.  I 
> >supposed I did from your POV - it's just that my "right things" and your 
> >"right things" are different, and hence the gap.
> 
> Yes, I can accept that that our "right things" are different. But I'm 
> still disappointed that when your "right thing" didn't work as expected 
> you "banged your head against a wall" for hours rather than spend just 
> five minutes sending a mail to our lists to get the answer that is now 
> in our FAQ.

Also i saw Gier's 'svn commit' message to Incubator site
containing frustrated comments and immediately explained
the problem. Everbody remember that the world is round.
If you have a problem, then ask immediately. Don't stew.

> If you had you would probably be saying "well it confused the hell out 
> of me, but the Forrest guys explained what was going on and showed me 
> how to fix it pretty quickly". Then I wouldn't need to defend what we do 
> in public forums like this.
> 
> >Thanks for sticking with us here on this.  I know what it's like to be 
> >piled on in a public forum, and none of us meant to do that.  It's just 
> >that there is legitimate frustration.

What amazes me is that i had tried to ease that
frustration two months ago by suggesting alternatives
and removing the need to attack Forrest. Unfortunately
people missed it, so the frustration simmered.

-David

> It does seem to have finally boiled down to a few legitimate 
> frutstrations. Thank you for being patient enough to get to the bottom 
> of these concerns.
> 
> (wow I think we reached a mutual consensus here :-))
> 
> Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr wrote:
>> Forrest is much more than the "simple site generation tool" that the 
>> subject says is wanted here, I recognise that Forrest may not be the 
>> right tool for this job. I happen to disagree, but I recognise the 
>> possibility.
> 
> 
> Well, if you believe Forrest could be, then do it :)  

I think we *are* doing it. Leo just sent a very useful mail to our user 
list and to myself (actually it is stuck in moderation since he is not 
subscribed). I've prepared my response there.

It seems that around 80% of the issues raised either have been addressed 
or are in the process of being addressed. The problem is not one of 
doing it, but accepting that we are doing it, and working with us to 
understand it.

Of course that remaining 20% is vital to us and very helpful feedback.

> Some basic things 
> that you've heard here -
> 
> 1) Don't make us checkout some fixed branch of source and build it. I 
> was recently admonished for using the actual release from the project to 
>  build the Incubator site.   I used to want to build everything, 
> including my Linux Kernels.  I'm too old now.

I have no idea why you are using the release branch rather than the 
binary release. There are no bug fixes in that branch that I am aware 
of. If I am mistaken you could have asked us (via our dev list) to 
create a binary snapshot for you - I'd have been more than happy to do so.

I only just joined this list because I became aware of issues with 
Forrest, I don't know the history here.

> 2) Reduce the surprises.  Consider that many people here have become 
> accustomed - rightly or wrongly - to the way Anakia tries to render 
> everything in the doc tree, and see what you can do to fix that and 
> mimic that workflow and the user expectations that arise from knowing it.

There are good reasons why we do not render everything in the document 
tree, and we will never do so by default.

If this ever becomes my own itch, I'll add a config property to 
optionally include everything in the doc tree for users like yourself. 
In the meantime, how to do it is explained in our FAQ, so should you 
ever use Forrest again and you need this feature we'd welcome a patch.

As for workflow, I think I covered this in earlier messages, Forrest 
does support the workflow outlined by Leo and yourself.

> 3) When I touch something via browser in 'forrest run' mode, WRITE THE 
> CHANGE TO DISK.  I (as the user) think that I'm looking at the site as 
> rendered, and was really stumped when no such change really happened.

This is a new feature request I've never heard before. It actually makes 
alot of sense, and like all good ideas is really obvious to anyone but a 
developer who is too comfortable with the tool.

It would address a common concern (have to render the whole site even if 
a single page has changed). I'll look into this one on the Forrest dev list.

> 3) Don't expect that I'm going to go and read Forrest docs to do what I 
> (as the user) think of as basic things.  I won't.   I did read the 
> 5-step on the Forrest site that fateful saturday when I was trying to 
> fix that orphan page, and I thought I did all the right things.  I 
> supposed I did from your POV - it's just that my "right things" and your 
> "right things" are different, and hence the gap.

Yes, I can accept that that our "right things" are different. But I'm 
still disappointed that when your "right thing" didn't work as expected 
you "banged your head against a wall" for hours rather than spend just 
five minutes sending a mail to our lists to get the answer that is now 
in our FAQ.

If you had you would probably be saying "well it confused the hell out 
of me, but the Forrest guys explained what was going on and showed me 
how to fix it pretty quickly". Then I wouldn't need to defend what we do 
in public forums like this.

> Thanks for sticking with us here on this.  I know what it's like to be 
> piled on in a public forum, and none of us meant to do that.  It's just 
> that there is legitimate frustration.

It does seem to have finally boiled down to a few legitimate 
frutstrations. Thank you for being patient enough to get to the bottom 
of these concerns.

(wow I think we reached a mutual consensus here :-))

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

Hopefully my last post. I'd have stopped a while ago, but I thought I 
was being helpful by telling you about a use case that I thought legit 
that had me stumbling and to show I wasn't just whining.

Ross Gardler wrote:

[SNIP]

> 
> Now please let the "dead horse" drop. Simply admit that you don't have 
> the time or inclination to ask questions or read docs and therefore 
> you'd rather see someone build a simpler tool that you have the time to 
> understand.

I wrote a simpler tool.  I was one of the primary authors of Velocity, 
and worked closely with Jon on Anakia.  I also then wrote DVSL which is 
what Jon really wanted Anakia to be - a Velocity-driven alternative to XSLT.

So I think I have some reasonable idea of the kind of tool that can be 
built and is desired for what we need to do here.  Sure, Forrest has 
lots of nice features, but your users are stumbling over stuff for not 
so off-the-wall use cases.

Either Forrest is overkill for what we need, or you need a few 
improvements for newbies based on how newbies or casual site owners do 
things.

[SNIP]

> Forrest is much more than the "simple site generation tool" that the 
> subject says is wanted here, I recognise that Forrest may not be the 
> right tool for this job. I happen to disagree, but I recognise the 
> possibility.

Well, if you believe Forrest could be, then do it :)  Some basic things 
that you've heard here -

1) Don't make us checkout some fixed branch of source and build it. I 
was recently admonished for using the actual release from the project to 
  build the Incubator site.   I used to want to build everything, 
including my Linux Kernels.  I'm too old now.

2) Reduce the surprises.  Consider that many people here have become 
accustomed - rightly or wrongly - to the way Anakia tries to render 
everything in the doc tree, and see what you can do to fix that and 
mimic that workflow and the user expectations that arise from knowing it.

3) When I touch something via browser in 'forrest run' mode, WRITE THE 
CHANGE TO DISK.  I (as the user) think that I'm looking at the site as 
rendered, and was really stumped when no such change really happened.

3) Don't expect that I'm going to go and read Forrest docs to do what I 
(as the user) think of as basic things.  I won't.   I did read the 
5-step on the Forrest site that fateful saturday when I was trying to 
fix that orphan page, and I thought I did all the right things.  I 
supposed I did from your POV - it's just that my "right things" and your 
"right things" are different, and hence the gap.

Thanks for sticking with us here on this.  I know what it's like to be 
piled on in a public forum, and none of us meant to do that.  It's just 
that there is legitimate frustration.

geir

> 

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr wrote:
> I don't mean to beat a dead horse here, but this reminds me of the old 
> joke :
> 
> Patient : "Doctor, my arm hurts when I life it like this..."
> Doctor : "Don't lift it like that..."
> 
> I needed to "lift my arm".
> 
> I had a page that I didn't wish to have as part of the site (i.e. I 
> didn't want the site to have a live link to it) but I wanted to change 
> the content for anyone out there that still had a link (like Google!).
> 
> So I needed to modify and render a page that wasn't part of the formal 
> site tree. The solution? After hours of beating my head against the 
> wall, the solution was to Link something to it, render (go for 
> coffee...), then change the link back, re-render (go for coffee...)

Please stop with this rubbish.

It *is* possible to do exactly what you wanted to do, quickly and 
easily. By asking questions on the user list or reading the archives, 
you will save a great deal of time. Users coming after you can now read 
our (recently added) FAQ:

3.3. How to control the processing of URIs by Cocoon, e.g. exclude 
certain URIs, include other additional ones [2]

It's interesting that this FAQ tells you how to lift your arm *without* 
it hurting, yet you still claim the opposite.

Whilst I'm at it, I may as well point out there is no need to "go for a 
coffee" either as you can instruct Forrest to start at any given page, 
so if you only want to render one page, you can.

Alternatively, you can use the Forrestbot and then you don't have to 
manually build any part of the site (and yes, you still have the 
opportunity to do QA - see earlier messages).

Now please let the "dead horse" drop. Simply admit that you don't have 
the time or inclination to ask questions or read docs and therefore 
you'd rather see someone build a simpler tool that you have the time to 
understand.

Now, finally, in order to keep the balance let me highlight what the 
valid criticisms in this thread regarding Forrest are (in my opinion):

- it is a 0.8-dev rather than a 1.0 product

- if you want to use it locally (*not* required if a ForrestBot is made 
available) then you need to download a large Java binary distribution 
(*not* megabytes of source code as you claimed earlier).

- the default skin is "old fashioned", although this can easily be 
changed with some CSS and maybe a little XSL (just CSS when the 
Dispatcher becomes stable)

Forrest is much more than the "simple site generation tool" that the 
subject says is wanted here, I recognise that Forrest may not be the 
right tool for this job. I happen to disagree, but I recognise the 
possibility.

In the absence of an Incubator volunteer to work with the Forrest 
community it is clear that this simple tool should be built. If it works 
out, I am sure that we will integrate the sources into Forrest via a 
plugin, if it doesn't Forrest will still be there.

Ross

[1]
I'm assuming your "doctor" comments above were tongue in cheek so I 
should get away with that - just in case I'll state that I am using a 
metaphor, not making a personal comment

[2]
http://forrest.apache.org/docs_0_70/faq.html#cli-xconf

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

I don't mean to beat a dead horse here, but this reminds me of the old 
joke :

Patient : "Doctor, my arm hurts when I life it like this..."
Doctor : "Don't lift it like that..."

I needed to "lift my arm".

I had a page that I didn't wish to have as part of the site (i.e. I 
didn't want the site to have a live link to it) but I wanted to change 
the content for anyone out there that still had a link (like Google!).

So I needed to modify and render a page that wasn't part of the formal 
site tree. The solution? After hours of beating my head against the 
wall, the solution was to Link something to it, render (go for 
coffee...), then change the link back, re-render (go for coffee...)

Oh, and since we're on this subject, one more thing - when running 
Forrest in local server mode, it **WILL** render things that aren't 
linked when you browse them.  IOW, letting forrest render everything to 
disk as a batch didn't fix my page because nothing linked to it. Running 
forrest and me hitting it on localhost with a browser *did* render it 
when I put the URL in. (And then it didn't write the rendered output to 
disk... Imagine my bafflement...)  So I think that you should choose one 
mode.  And it would be very useful if I had gotten a message in the 
online mode that said "you are looking at a resource that currently 
isn't linked to by any of the control documents" (or whatever) it would 
have saved *heaps* of time....

geir


David Crossley wrote:
> Geir Magnusson Jr. wrote:
> 
>>Tim Williams wrote:
>>
>>>>geirm@apache.org
>>>
>>>The Forrest project uses a tool called JIRA [1] so that users like you
>>>can add feedback/feature requests like this one.  Your request is much
>>>more likely to get addressed there than on the incubator mailing list.
>>
>>For the next one, I'll do that.  For this one, I'll assume it's in  
>>safe and responsible hands.
> 
> 
> http://forrest.apache.org/docs/faq.html#crawler
> 
> -David
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
> 
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr. wrote:
> Tim Williams wrote:
> >>geirm@apache.org
> >
> >The Forrest project uses a tool called JIRA [1] so that users like you
> >can add feedback/feature requests like this one.  Your request is much
> >more likely to get addressed there than on the incubator mailing list.
> 
> For the next one, I'll do that.  For this one, I'll assume it's in  
> safe and responsible hands.

http://forrest.apache.org/docs/faq.html#crawler

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Geir Magnusson Jr." <ge...@apache.org>]

On Dec 29, 2005, at 8:34 AM, Tim Williams wrote:

> On 12/29/05, Geir Magnusson Jr. <ge...@apache.org> wrote:
>>
>> On Dec 27, 2005, at 10:03 PM, David Crossley wrote:
>>
>>> Davanum Srinivas wrote:
>>>>
>>>> Example: last apachecon, Geir was trying to update  
>>>> geronimo.html, it
>>>> took 30+ mins before asking for help. It took me 15+ minutes to
>>>> figure
>>>> out that geronimo.html was not being linked from any page in the  
>>>> web
>>>> site. So we lost close to an hour of hackathon time trying to do
>>>> something really simple and silly - add a line of text to the
>>>> geronimo.html asking folks to go to the geronimo actual web site.
>>>
>>> Steady on. Just prior to that, someone made a change that
>>> removed geronimo.html from the /projects/ area. The normal process
>>> with such a sudden break, is to investigate the prior changes that
>>> caused it.
>>
>> My problem was that I didn't understand how things worked.  I thought
>> that all content in the tree got rendered, and was just baffled when
>> my changes to the cwiki file didn't get added.  Yes, it was my fault,
>> I suppose, but please, add a feature in Forrest to show a list of
>> files it found that it won't process. I think that really help users.
>>
>> geir
>>
>> --
>> Geir Magnusson Jr                                  +1-203-665-6437
>> geirm@apache.org
>
> The Forrest project uses a tool called JIRA [1] so that users like you
> can add feedback/feature requests like this one.  Your request is much
> more likely to get addressed there than on the incubator mailing list.

For the next one, I'll do that.  For this one, I'll assume it's in  
safe and responsible hands.

geir

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geirm@apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Tim Williams <wi...@gmail.com>]

On 12/29/05, Geir Magnusson Jr. <ge...@apache.org> wrote:
>
> On Dec 27, 2005, at 10:03 PM, David Crossley wrote:
>
> > Davanum Srinivas wrote:
> >>
> >> Example: last apachecon, Geir was trying to update geronimo.html, it
> >> took 30+ mins before asking for help. It took me 15+ minutes to
> >> figure
> >> out that geronimo.html was not being linked from any page in the web
> >> site. So we lost close to an hour of hackathon time trying to do
> >> something really simple and silly - add a line of text to the
> >> geronimo.html asking folks to go to the geronimo actual web site.
> >
> > Steady on. Just prior to that, someone made a change that
> > removed geronimo.html from the /projects/ area. The normal process
> > with such a sudden break, is to investigate the prior changes that
> > caused it.
>
> My problem was that I didn't understand how things worked.  I thought
> that all content in the tree got rendered, and was just baffled when
> my changes to the cwiki file didn't get added.  Yes, it was my fault,
> I suppose, but please, add a feature in Forrest to show a list of
> files it found that it won't process. I think that really help users.
>
> geir
>
> --
> Geir Magnusson Jr                                  +1-203-665-6437
> geirm@apache.org

The Forrest project uses a tool called JIRA [1] so that users like you
can add feedback/feature requests like this one.  Your request is much
more likely to get addressed there than on the incubator mailing list.

--tim

[1] - http://issues.apache.org/jira/browse/FOR

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Geir Magnusson Jr." <ge...@apache.org>]

On Dec 27, 2005, at 10:03 PM, David Crossley wrote:

> Davanum Srinivas wrote:
>>
>> Example: last apachecon, Geir was trying to update geronimo.html, it
>> took 30+ mins before asking for help. It took me 15+ minutes to  
>> figure
>> out that geronimo.html was not being linked from any page in the web
>> site. So we lost close to an hour of hackathon time trying to do
>> something really simple and silly - add a line of text to the
>> geronimo.html asking folks to go to the geronimo actual web site.
>
> Steady on. Just prior to that, someone made a change that
> removed geronimo.html from the /projects/ area. The normal process
> with such a sudden break, is to investigate the prior changes that
> caused it.

My problem was that I didn't understand how things worked.  I thought  
that all content in the tree got rendered, and was just baffled when  
my changes to the cwiki file didn't get added.  Yes, it was my fault,  
I suppose, but please, add a feature in Forrest to show a list of  
files it found that it won't process. I think that really help users.

geir

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geirm@apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Davanum Srinivas wrote:
> 
> Example: last apachecon, Geir was trying to update geronimo.html, it
> took 30+ mins before asking for help. It took me 15+ minutes to figure
> out that geronimo.html was not being linked from any page in the web
> site. So we lost close to an hour of hackathon time trying to do
> something really simple and silly - add a line of text to the
> geronimo.html asking folks to go to the geronimo actual web site.

Steady on. Just prior to that, someone made a change that
removed geronimo.html from the /projects/ area. The normal process
with such a sudden break, is to investigate the prior changes that
caused it.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Thomas Dudziak <to...@gmail.com>]

On 12/27/05, Davanum Srinivas <da...@gmail.com> wrote:

> Example: last apachecon, Geir was trying to update geronimo.html, it
> took 30+ mins before asking for help. It took me 15+ minutes to figure
> out that geronimo.html was not being linked from any page in the web
> site. So we lost close to an hour of hackathon time trying to do
> something really simple and silly - add a line of text to the
> geronimo.html asking folks to go to the geronimo actual web site.
>
> We did get into a debate on pros and cons then and there. We
> definitely knew that if someone proposed such a measure like Leo's all
> the forrest aficionados will come out of the woodwork (like you did!)
> :)

Well, I'm no forrest aficionado at all, just a user. My comments were
rather that we should avoid creating the n'th format and tool to do
something that we already have a lot of tools for.
Btw, I would be surprised if the Geronimo site (of which I don't know
anything about) is a simple site. And this seems a good example where
input to the Forrest project can make it better.

> A simple script that required no setup and that generates the html for
> the web site with no fuss is what we want. IMHO, Forrest to put it
> mildly is a pain in the neck for a total beginner to bootstrap himself
> to do something useful.

For what it's worth, I think Henri's idea is a good one. Just let the
incubated projects write their docs in HTML and Incubator gives them a
CSS (and perhaps a coarse look-and-feel to strive for). And then use
something like Sitemesh or similar to add menus and stuff.

regards,
Tom

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Davanum Srinivas <da...@gmail.com>]

Thomas,

Example: last apachecon, Geir was trying to update geronimo.html, it
took 30+ mins before asking for help. It took me 15+ minutes to figure
out that geronimo.html was not being linked from any page in the web
site. So we lost close to an hour of hackathon time trying to do
something really simple and silly - add a line of text to the
geronimo.html asking folks to go to the geronimo actual web site.

We did get into a debate on pros and cons then and there. We
definitely knew that if someone proposed such a measure like Leo's all
the forrest aficionados will come out of the woodwork (like you did!)
:)

A simple script that required no setup and that generates the html for
the web site with no fuss is what we want. IMHO, Forrest to put it
mildly is a pain in the neck for a total beginner to bootstrap himself
to do something useful.

thanks,
dims

PS: I am an ex-cocoon guy myself

On 12/27/05, Thomas Dudziak <to...@gmail.com> wrote:
> On 12/27/05, Leo Simons <ma...@leosimons.com> wrote:
>
> > It pains me to say this (Forrest is a cool project and I
> > consider at least some of its active developers and community
> > members my friends) but we've muddled around long enough.
> >
> > I think that, for the incubator website, Apache Forrest
> >
> >   * is too unstable as a codebase
> >   * is way too complex
> >   * has too many features we don't need and solves
> >     too many problems we don't have
> >   * has a learning curve that is too big
> >   * does not work well with the SVN-based publishing
> >     process we want to use
> >   * is not well-understood by enough of the current
> >     Incubator volunteers
> >   * has caused frustration for too many of the current
> >     Incubator volunteers
> >
> > I think this needs solving. I think this needs solving in
> > general, not just for the Incubator (I have the exact same
> > problem over at Gump, which also has a horrendously outdated
> > website which also uses Apache Forrest).
>
> Hi Leo,
>
> since I'm rather new to this, I don't have a deep understanding of the
> problems you're trying to solve. However, to my naive understanding
> its two things:
>
> * make the process of documenting incubated projects easier for their community
> * make the process of publishing this documentation easier (and more
> stable) for infra/incubator people
>
> Now I don't really know about the problems that you have with Forrest
> regarding the second point - it works for the projects that I work in,
> but then again we probably have fewer/simpler requirements. It would
> be nice if you could perhaps provide some details, e.g. regarding
> SVN-based publishing ?
>
> Anyway, I think there are several possible things that could be done
> to deal with this (in the line of "eating your own dog food"), aside
> from implementing a new tool:
>
> * Get Cocoon/Forrest developers to help in the Incubator.
>
> If Forrest is too complicated to use, let Forrest/Cocoon people help
> out. This would help them see where complexity has to be removed. And
> the community of the incubated projects would have experts available
> that can help them with their problems.
> And more helpers for Incubator should be a good thing, not ?
>
> * Simplify Forrest for 'admins'.
>
> Same as above. As I said, I don't really know about the problems, but
> I think all projects that use Forrest, can benefit from a
> simpler/faster/more stable site generation.
>
> * Simplify documentation writing for end users.
>
> Actually, I think this is quite an important point. Writing a new tool
> probably means yet another XML (or some other format) to learn, which
> is Not A Good Thing (tm). IMHO it would be better to get away from XML
> completely and pursue simpler solutions.
> One such thing might be the OpenOffice plugin that generates Forrest
> files, which would help new projects a lot in writing/converting
> existing documentation.
> Another thing might be abandoning Forrest altogether for Incubation
> docs in favor of, for instance, a protected Wiki that only the project
> developers (and mentors, PMCs, ...) have write access to. And there's
> is probably a not-too-complicated technical way to convert this later
> on to Maven or Forrest format once the project comes out of
> incubation.
>
> Anyway, I hope you don't mind me making a case for using this as an
> opportunity to make Forrest better instead of abandoning it.
>
> regards,
> Tom
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>


--
Davanum Srinivas : http://wso2.com/blogs/

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr wrote:
> 
> 
> Ross Gardler wrote:
> 
>> Geir Magnusson Jr. wrote:
>>
> 
>>> a) edit
>>> b) render
>>> c) examine.  if not right, GOTO a)
>>> d) commit
>>> e) deploy
>>>
>>> a,c are entirely my choice of tool, so it's easy.
>>>
>>> d,e use one standard common tool.  it's easy.
>>>
>>> b needs to be simple and easy
>>
>>
>>
>> The ForrestBot does b, d and e of your, i.e. the three steps that you 
>> don't list as "entirely my choice of tool".
> 
> 
> True, becuase it's SVN.  I suppose that to be fair, there are tools for 
> SVN now ;)  like integration into editors and nice plugins for windows 
> or something.  But I just use svn on the command line everywhere I go, 
> and I mis-thought, I guess.
> 
>> Although e) can not be done on ASF harware until there is a way such a 
>> tool can push the content to the live servers (same problem for all 
>> tools). Of course, it can do the preparation work, such as put it in a 
>> relevant SVN server for periodic pull deployment to the servers.
> 
> 
> I dunno.  Here's how it works w/ the Harmony site :
> 
> ssh -l geirm minotaur.apache.org
> cd /www/incubator.apache.org/harmony/
> svn update

That's exactly what the Forrestbot enables you to do (it will also 
deploy via SCP if the servers allow it).

> Now, we could probably just put a post-commit hook that does the deploy, 
> and maybe tailor it to a specific file, like DEPLOY.txt in the root or 
> such so that you just touch it, commit, and the site deploys, with the 
> added benefit that SVN will give us a log of who actually did the deploy 
> at a given time.

Sure - such a solution would be a good idea since any tool that puts the 
resulting docs in SVN will work with that solution.

>> The advantage of the forrestbot is that if you have users who edit 
>> docs but do not do b through e, then a cron job will reularly run the 
>> build and report any problems via email. This also means there is a 
>> regularly built staging area for people to independantly do c) without 
>> the need to do b).
> 
> 
> But I get nervous about not being able to do any QA - meaning the bits 
> that get deployed to "production" are never given even an cursory view 
> by the human that did the change.

You can still do do manual QA, the forestbot deploys to a staging site 
where it can be viewed manually. You can optionally have it deploy to 
the live server, or you can do it manually by logging into a webapp and 
clicking a deploy button (not installed on the FOrrest zone yet, but I 
run a version on a private test server at 
http://cms.wkwyw.net:8080/forrestbot-trunk/ (not the staged docs and 
access to the last buiod logs).

For example, the Cocoon docs are staged at 
http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/index.html

These staging docsc are published automatically every three hours by a 
cron job (if it fails a report is sent to the dev list). They are not 
autoatically published, they are still published manually when the QA 
checks have been done.

> I may be a luddite or something, but I don't trust that kind of 
> auto-deployment.

No, I wasn't clear, it's auto-deploy of the *staged* documents for your 
steps b) and c). Hopefully the above makes it clearer.

> I don't seem to be able to grok 
> what actually changes in the doc tree for some arbitrary change. That's 
> not terrible in itself, but w/o having to commit the generated artifacts 
> myself, I can't know if things changed that I didn't expect....

Again, probably a result of my lack of clarity in the original message.

If you put the staged docs in SVN, then you get commit messages. 
However, I am happy with the commit messages from the sources, but that 
might be because of my comfort level with Forrest.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

Ross Gardler wrote:
> Geir Magnusson Jr. wrote:
> 

>> a) edit
>> b) render
>> c) examine.  if not right, GOTO a)
>> d) commit
>> e) deploy
>>
>> a,c are entirely my choice of tool, so it's easy.
>>
>> d,e use one standard common tool.  it's easy.
>>
>> b needs to be simple and easy
> 
> 
> The ForrestBot does b, d and e of your, i.e. the three steps that you 
> don't list as "entirely my choice of tool".

True, becuase it's SVN.  I suppose that to be fair, there are tools for 
SVN now ;)  like integration into editors and nice plugins for windows 
or something.  But I just use svn on the command line everywhere I go, 
and I mis-thought, I guess.

> Although e) can not be done 
> on ASF harware until there is a way such a tool can push the content to 
> the live servers (same problem for all tools). Of course, it can do the 
> preparation work, such as put it in a relevant SVN server for periodic 
> pull deployment to the servers.

I dunno.  Here's how it works w/ the Harmony site :

ssh -l geirm minotaur.apache.org
cd /www/incubator.apache.org/harmony/
svn update

Now, we could probably just put a post-commit hook that does the deploy, 
and maybe tailor it to a specific file, like DEPLOY.txt in the root or 
such so that you just touch it, commit, and the site deploys, with the 
added benefit that SVN will give us a log of who actually did the deploy 
at a given time.

> 
> The advantage of the forrestbot is that if you have users who edit docs 
> but do not do b through e, then a cron job will reularly run the build 
> and report any problems via email. This also means there is a regularly 
> built staging area for people to independantly do c) without the need to 
> do b).

But I get nervous about not being able to do any QA - meaning the bits 
that get deployed to "production" are never given even an cursory view 
by the human that did the change.

It's like letting your app server build and deploy a WAR from source :)

I may be a luddite or something, but I don't trust that kind of 
auto-deployment.

And if you don't buy my argument above, there's always the bit about 
unintended consequences - w/ Forrest, I don't seem to be able to grok 
what actually changes in the doc tree for some arbitrary change. That's 
not terrible in itself, but w/o having to commit the generated artifacts 
myself, I can't know if things changed that I didn't expect....

With checking in the artifacts, I do a svn commit and see the things 
that change, and can find things that surprise me.

> 
> Couple this with other validation tools that can be set to run on the 
> staging area, e.g. link checkers, accessibility checkers erc. and you 
> have a level of automated validation of your site (we have not yet 
> integrated such tools in the ForrestBot).

Sure - and those could be used either way - a safety system always 
running to check our site...

> 
> It's here, it works now and it is in use in production environments. 
> However, it is not a simple lightweight tool for local use, it still 
> suffers from the "Forrest is too much for our simple site needs" issue. 
> As you will see if you are a site-dev subscriber, I'm not objecting to 
> Leo doing this work, my only concen is the misinformation that is in 
> this thread conerning Forrest.

I'm not sure which misinfo....my POV on forrest comes entirely from 
using it.

geir

> 
> Ross
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
> 
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr. wrote:
> 
> On Dec 29, 2005, at 9:58 AM, Ross Gardler wrote:
> 
>> Geir Magnusson Jr. wrote:
>>
>>> On Dec 27, 2005, at 9:14 PM, David Crossley wrote:
>>>
>>>> Leo Simons wrote:
>>>>
>>>>> Thomas Dudziak wrote:
>>>>>
>>>>>> since I'm rather new to this, I don't have a deep  understanding  
>>>>>> of the
>>>>>> problems you're trying to solve.
>>>>>
>>>>>
>>>>>
>>>>> None is needed, the problem is very simple.
>>>>
>>>>
>>>>
>>>> The problems are not simple, or they would have been solved
>>>> years ago. Follow the site-dev discussions from mid-2004.
>>>>
>>>> It seems that the publishing step is the hardest. No matter
>>>> what the tool, that step trips people up. It seems that
>>>> committers just will not do it. It could perhaps be automated,
>>>> however the requirement to check the generated docs into
>>>> svn prevents that (need a committer's svn credentials).\
>>>
>>> I don't understand.  Publshing to me should be "svn commit" after  I  
>>> look at the site with my local browser as a QA step.  And yes,   
>>> committers should be the only ones able to do it.
>>
>>
>> That is exactly what it is, when using ForrestBot (in fact you  don't 
>> even have to type "svn commit" since the tool does it for  you). The 
>> problem is that it requries SVN passwords or user  interaction and so 
>> can't be part of an automated tool.
> 
> 
> What's the "ForrestBot"?  I just want to

The forrestbot is a tool runs Forrest for you it can be run from the 
command line, via a cron job or via a servlet (i.e. no need to install 
locally). It will do useful things like send emails on success/failure 
(useful for periodic staging builds).

> a) edit
> b) render
> c) examine.  if not right, GOTO a)
> d) commit
> e) deploy
> 
> a,c are entirely my choice of tool, so it's easy.
> 
> d,e use one standard common tool.  it's easy.
> 
> b needs to be simple and easy

The ForrestBot does b, d and e of your, i.e. the three steps that you 
don't list as "entirely my choice of tool". Although e) can not be done 
on ASF harware until there is a way such a tool can push the content to 
the live servers (same problem for all tools). Of course, it can do the 
preparation work, such as put it in a relevant SVN server for periodic 
pull deployment to the servers.

The advantage of the forrestbot is that if you have users who edit docs 
but do not do b through e, then a cron job will reularly run the build 
and report any problems via email. This also means there is a regularly 
built staging area for people to independantly do c) without the need to 
do b).

Couple this with other validation tools that can be set to run on the 
staging area, e.g. link checkers, accessibility checkers erc. and you 
have a level of automated validation of your site (we have not yet 
integrated such tools in the ForrestBot).

It's here, it works now and it is in use in production environments. 
However, it is not a simple lightweight tool for local use, it still 
suffers from the "Forrest is too much for our simple site needs" issue. 
As you will see if you are a site-dev subscriber, I'm not objecting to 
Leo doing this work, my only concen is the misinformation that is in 
this thread conerning Forrest.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Geir Magnusson Jr. wrote:

> Ross Gardler wrote:

> > Because the ASF have to support the chosen tool and there are many
> > different site generation tools in use within the ASF (now the
> > Incubator is about to get its own).

> I hope not.  I hope we reuse what is simple and easy and already
> working.

Hard to reconcile that at times with the infra request du jour from some
PMCs.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Geir Magnusson Jr." <ge...@optonline.net>]

On Dec 29, 2005, at 9:58 AM, Ross Gardler wrote:

> Geir Magnusson Jr. wrote:
>> On Dec 27, 2005, at 9:14 PM, David Crossley wrote:
>>> Leo Simons wrote:
>>>
>>>> Thomas Dudziak wrote:
>>>>
>>>>> since I'm rather new to this, I don't have a deep  
>>>>> understanding  of the
>>>>> problems you're trying to solve.
>>>>
>>>>
>>>> None is needed, the problem is very simple.
>>>
>>>
>>> The problems are not simple, or they would have been solved
>>> years ago. Follow the site-dev discussions from mid-2004.
>>>
>>> It seems that the publishing step is the hardest. No matter
>>> what the tool, that step trips people up. It seems that
>>> committers just will not do it. It could perhaps be automated,
>>> however the requirement to check the generated docs into
>>> svn prevents that (need a committer's svn credentials).\
>> I don't understand.  Publshing to me should be "svn commit" after  
>> I  look at the site with my local browser as a QA step.  And yes,   
>> committers should be the only ones able to do it.
>
> That is exactly what it is, when using ForrestBot (in fact you  
> don't even have to type "svn commit" since the tool does it for  
> you). The problem is that it requries SVN passwords or user  
> interaction and so can't be part of an automated tool.

What's the "ForrestBot"?  I just want to

a) edit
b) render
c) examine.  if not right, GOTO a)
d) commit
e) deploy

a,c are entirely my choice of tool, so it's easy.

d,e use one standard common tool.  it's easy.

b needs to be simple and easy

>
>>> Another complex issue is being able to run doc tools on Apache
>>> servers. We have all been asked to not use people.apache.org
>>> for that. Sure we will soon have the zones.apache.org machine
>>> (currently still in testing phase). However, that is not
>>> scalable. For example we don't want to run various forrest
>>> instances there for everybody to use. Our project is too small
>>> to be able to support other projects in that way.
>> Why not run doc tools?  Isn't it really about which doc tool?
>
> Because the ASF have to support the chosen tool and there are many  
> different site generation tools in use within the ASF (now the  
> Incubator is about to get its own).

I hope not.  I hope we reuse what is simple and easy and already  
working.

geir

>
> See http://people.apache.org/~rgardler/site-dev/Site-Build.html
>
> and bring any suggestions/contributions you have to the site-dev list.
>
> Ross
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geir@optonline.net



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr. wrote:
> 
> On Dec 27, 2005, at 9:14 PM, David Crossley wrote:
> 
>> Leo Simons wrote:
>>
>>> Thomas Dudziak wrote:
>>>
>>>> since I'm rather new to this, I don't have a deep understanding  of the
>>>> problems you're trying to solve.
>>>
>>>
>>> None is needed, the problem is very simple.
>>
>>
>> The problems are not simple, or they would have been solved
>> years ago. Follow the site-dev discussions from mid-2004.
>>
>> It seems that the publishing step is the hardest. No matter
>> what the tool, that step trips people up. It seems that
>> committers just will not do it. It could perhaps be automated,
>> however the requirement to check the generated docs into
>> svn prevents that (need a committer's svn credentials).\
> 
> 
> I don't understand.  Publshing to me should be "svn commit" after I  
> look at the site with my local browser as a QA step.  And yes,  
> committers should be the only ones able to do it.

That is exactly what it is, when using ForrestBot (in fact you don't 
even have to type "svn commit" since the tool does it for you). The 
problem is that it requries SVN passwords or user interaction and so 
can't be part of an automated tool.

>> Another complex issue is being able to run doc tools on Apache
>> servers. We have all been asked to not use people.apache.org
>> for that. Sure we will soon have the zones.apache.org machine
>> (currently still in testing phase). However, that is not
>> scalable. For example we don't want to run various forrest
>> instances there for everybody to use. Our project is too small
>> to be able to support other projects in that way.
> 
> 
> Why not run doc tools?  Isn't it really about which doc tool?

Because the ASF have to support the chosen tool and there are many 
different site generation tools in use within the ASF (now the Incubator 
is about to get its own).

See http://people.apache.org/~rgardler/site-dev/Site-Build.html

and bring any suggestions/contributions you have to the site-dev list.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Geir Magnusson Jr." <ge...@apache.org>]

On Dec 27, 2005, at 9:14 PM, David Crossley wrote:

> Leo Simons wrote:
>> Thomas Dudziak wrote:
>>> since I'm rather new to this, I don't have a deep understanding  
>>> of the
>>> problems you're trying to solve.
>>
>> None is needed, the problem is very simple.
>
> The problems are not simple, or they would have been solved
> years ago. Follow the site-dev discussions from mid-2004.
>
> It seems that the publishing step is the hardest. No matter
> what the tool, that step trips people up. It seems that
> committers just will not do it. It could perhaps be automated,
> however the requirement to check the generated docs into
> svn prevents that (need a committer's svn credentials).\

I don't understand.  Publshing to me should be "svn commit" after I  
look at the site with my local browser as a QA step.  And yes,  
committers should be the only ones able to do it.

>
> Another complex issue is being able to run doc tools on Apache
> servers. We have all been asked to not use people.apache.org
> for that. Sure we will soon have the zones.apache.org machine
> (currently still in testing phase). However, that is not
> scalable. For example we don't want to run various forrest
> instances there for everybody to use. Our project is too small
> to be able to support other projects in that way.

Why not run doc tools?  Isn't it really about which doc tool?   
Running the generation for the geronimo site takes under 10 seconds  
wall clock for a full render.  That's seems fairly unintrusive.

geir

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geirm@apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Leo Simons wrote:
> Thomas Dudziak wrote:
> > since I'm rather new to this, I don't have a deep understanding of the
> > problems you're trying to solve.
> 
> None is needed, the problem is very simple.

The problems are not simple, or they would have been solved
years ago. Follow the site-dev discussions from mid-2004.

It seems that the publishing step is the hardest. No matter
what the tool, that step trips people up. It seems that
committers just will not do it. It could perhaps be automated,
however the requirement to check the generated docs into
svn prevents that (need a committer's svn credentials).

Another complex issue is being able to run doc tools on Apache
servers. We have all been asked to not use people.apache.org
for that. Sure we will soon have the zones.apache.org machine
(currently still in testing phase). However, that is not
scalable. For example we don't want to run various forrest
instances there for everybody to use. Our project is too small
to be able to support other projects in that way.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Thomas Dudziak <to...@gmail.com>]

On 12/27/05, Leo Simons <ma...@leosimons.com> wrote:

> Err, I would suggest you please go and read the general@incubator archives.
> That's basically a "FAQ" at this point. You may also wish to go and look for
> some posts by me over the last few years to the forrest mailing lists, or
> to the avalon mailing lists with the added keyword of "forrest".

Thanks! Since I'm trying to get more into the "Apache" ways, I think
I'll do that (though I think there is a bit more there than just a
"FAQ" given that there are probably several thousand mails in the
archives, and site-dev should be similar though I havn't found its
archive yet).

> I will assert OpenOffice is big and bloated and overkill too and not
> simple at all. I like vi and subethaedit. And HTML.

Well, I was under the (wrong) assumption that you were talking about
the docs of the incubated projects. And for them, OpenOffice might be
a good idea. For a lot of people, everything close to Word is a good
thing, for that matter.
But since your problem is about the Incubator docs itself, OpenOffice
is irrelevant anyways.

> > Anyway, I hope you don't mind me making a case for using this as an
> > opportunity to make Forrest better instead of abandoning it.
>
> Well, basically I do. I've spent several years (ever since Avalon became
> the first forrest user outside the xml.a.o group) working with forrest,
> helping it to improve and try and help to turn it into something that
> satisfies our simple use case, but its just not a good idea to keep going
> down that path. I've read through about 9 months of discussion on the
> site-dev list where basically the same discussion took place over and over
> again which was very frustrating (or so it seems) for all the participants.
> Nothing is ever going to get done if we keep having the same discussion
> over and over again.
>
> There is such a thing as "trying too hard" to get "full consensus" on a
> topic that is "too vague". DavidC's site management proposal from so long ago
> and each and every proposal after that has something along the line of
> "Projects can use various documentation tools: Anakia, Forrest, Maven, raw
> html, etc. Each system would have its own ways to report build problems to the
> committer (e.g. xml validation, broken links, content and spelling errors,
> configuration errors)." for a good reason. "There is more than one way to
> do it" and this is going to be Yet Another Way.
>
> I don't want to spend more time helping to improve Forrest or discussing the
> relative merits of a variety of solutions. I have an itch to scratch and I
> want to build a little piece of software to scratch it, in a way that is
> compatible with all the goals and needs of the ASF, the Infrastructure Team,
> the Incubator, the Gump project, and hopefully a few other projects. But I
> don't want to concern myself with the needs of the Forrest community right
> now as part of this effort, that's making it too hard to get anything done.

Thanks, I understand your itch now :-) Though I'm not quite sure yet
what the implications are.

regards,
Tom

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Leo Simons <ma...@leosimons.com>]

On Tue, Dec 27, 2005 at 04:17:37PM +0100, Thomas Dudziak wrote:
> since I'm rather new to this, I don't have a deep understanding of the
> problems you're trying to solve.

None is needed, the problem is very simple.

> However, to my naive understanding its two things:
> 
> * make the process of documenting incubated projects easier for their community
> * make the process of publishing this documentation easier (and more
> stable) for infra/incubator people

Actually its not for the incubated projects, just for the incubator
documentation and website itself. Each and every incubated project decides
what they want to do.

> Now I don't really know about the problems that you have with Forrest
> regarding the second point - it works for the projects that I work in,
> but then again we probably have fewer/simpler requirements. It would
> be nice if you could perhaps provide some details, e.g. regarding
> SVN-based publishing ?

Err, I would suggest you please go and read the general@incubator archives.
That's basically a "FAQ" at this point. You may also wish to go and look for
some posts by me over the last few years to the forrest mailing lists, or
to the avalon mailing lists with the added keyword of "forrest".

> Anyway, I think there are several possible things that could be done
> to deal with this (in the line of "eating your own dog food"), aside
> from implementing a new tool:
> 
> * Get Cocoon/Forrest developers to help in the Incubator.

We have a few actually. David Crossley is our "manual forrestbot" but it
doesn't scale. This is a bad idea. Everybody who knows SVN and how to
type in commands on a console should be able to manage the documentation
process end-to-end.

> * Simplify Forrest for 'admins'.

Yes its possible but it doesn't solve everything (its still going to be
big and complex and bloated and overkill no matter how pretty the user
interface is).

> * Simplify documentation writing for end users.
> 
> Actually, I think this is quite an important point. Writing a new tool
> probably means yet another XML (or some other format) to learn, which
> is Not A Good Thing (tm). IMHO it would be better to get away from XML
> completely and pursue simpler solutions.

+1.

> One such thing might be the OpenOffice plugin that generates Forrest
> files, which would help new projects a lot in writing/converting
> existing documentation.

I will assert OpenOffice is big and bloated and overkill too and not
simple at all. I like vi and subethaedit. And HTML.

> Another thing might be abandoning Forrest altogether for Incubation
> docs in favor of, for instance, a protected Wiki that only the project
> developers (and mentors, PMCs, ...) have write access to. And there's
> is probably a not-too-complicated technical way to convert this later
> on to Maven or Forrest format once the project comes out of
> incubation.

See Alex Karasulu's post to site-dev a while back for an approach where
we could have an admin-protected Confluence to serve as an editing interface
for xdoc.

There's a lot of ways to do things.

> Anyway, I hope you don't mind me making a case for using this as an
> opportunity to make Forrest better instead of abandoning it.

Well, basically I do. I've spent several years (ever since Avalon became
the first forrest user outside the xml.a.o group) working with forrest,
helping it to improve and try and help to turn it into something that
satisfies our simple use case, but its just not a good idea to keep going
down that path. I've read through about 9 months of discussion on the
site-dev list where basically the same discussion took place over and over
again which was very frustrating (or so it seems) for all the participants.
Nothing is ever going to get done if we keep having the same discussion
over and over again.

There is such a thing as "trying too hard" to get "full consensus" on a
topic that is "too vague". DavidC's site management proposal from so long ago
and each and every proposal after that has something along the line of
"Projects can use various documentation tools: Anakia, Forrest, Maven, raw
html, etc. Each system would have its own ways to report build problems to the
committer (e.g. xml validation, broken links, content and spelling errors,
configuration errors)." for a good reason. "There is more than one way to
do it" and this is going to be Yet Another Way.

I don't want to spend more time helping to improve Forrest or discussing the
relative merits of a variety of solutions. I have an itch to scratch and I
want to build a little piece of software to scratch it, in a way that is
compatible with all the goals and needs of the ASF, the Infrastructure Team,
the Incubator, the Gump project, and hopefully a few other projects. But I
don't want to concern myself with the needs of the Forrest community right
now as part of this effort, that's making it too hard to get anything done.


cheers,


LSD

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Thomas Dudziak <to...@gmail.com>]

On 12/27/05, Leo Simons <ma...@leosimons.com> wrote:

> It pains me to say this (Forrest is a cool project and I
> consider at least some of its active developers and community
> members my friends) but we've muddled around long enough.
>
> I think that, for the incubator website, Apache Forrest
>
>   * is too unstable as a codebase
>   * is way too complex
>   * has too many features we don't need and solves
>     too many problems we don't have
>   * has a learning curve that is too big
>   * does not work well with the SVN-based publishing
>     process we want to use
>   * is not well-understood by enough of the current
>     Incubator volunteers
>   * has caused frustration for too many of the current
>     Incubator volunteers
>
> I think this needs solving. I think this needs solving in
> general, not just for the Incubator (I have the exact same
> problem over at Gump, which also has a horrendously outdated
> website which also uses Apache Forrest).

Hi Leo,

since I'm rather new to this, I don't have a deep understanding of the
problems you're trying to solve. However, to my naive understanding
its two things:

* make the process of documenting incubated projects easier for their community
* make the process of publishing this documentation easier (and more
stable) for infra/incubator people

Now I don't really know about the problems that you have with Forrest
regarding the second point - it works for the projects that I work in,
but then again we probably have fewer/simpler requirements. It would
be nice if you could perhaps provide some details, e.g. regarding
SVN-based publishing ?

Anyway, I think there are several possible things that could be done
to deal with this (in the line of "eating your own dog food"), aside
from implementing a new tool:

* Get Cocoon/Forrest developers to help in the Incubator.

If Forrest is too complicated to use, let Forrest/Cocoon people help
out. This would help them see where complexity has to be removed. And
the community of the incubated projects would have experts available
that can help them with their problems.
And more helpers for Incubator should be a good thing, not ?

* Simplify Forrest for 'admins'.

Same as above. As I said, I don't really know about the problems, but
I think all projects that use Forrest, can benefit from a
simpler/faster/more stable site generation.

* Simplify documentation writing for end users.

Actually, I think this is quite an important point. Writing a new tool
probably means yet another XML (or some other format) to learn, which
is Not A Good Thing (tm). IMHO it would be better to get away from XML
completely and pursue simpler solutions.
One such thing might be the OpenOffice plugin that generates Forrest
files, which would help new projects a lot in writing/converting
existing documentation.
Another thing might be abandoning Forrest altogether for Incubation
docs in favor of, for instance, a protected Wiki that only the project
developers (and mentors, PMCs, ...) have write access to. And there's
is probably a not-too-complicated technical way to convert this later
on to Maven or Forrest format once the project comes out of
incubation.

Anyway, I hope you don't mind me making a case for using this as an
opportunity to make Forrest better instead of abandoning it.

regards,
Tom

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Mads Toftum wrote:

> The one thing I never understood is why incubator insists on placing the
> whole forrest burden on new projects - as if they don't have enough
> other things to worry about than learning a system that they're likely
> to ditch as soon as they have the chance?

Huh?  Projects have precisely one file to maintain, in plain HTML.

	--- Noel

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Mads Toftum <ma...@toftum.dk>]

On Thu, Dec 29, 2005 at 08:23:48AM -0500, Geir Magnusson Jr. wrote:
> I am +1 for dumping Forrest.  I never grok why something so simple as  
> our static website needs something so complicated to build it.
> 
I think you've nailed the difference between the forrest crowd and the
rest of us. I totally agree with your wondering about the need for
something that <flame>big and bloated</flame> to do something so simple
that everyone else could do it in a moment with an editor and running a
simple command.

> I'd rather err in having less-than-perfect technology with the  
> benefit of trivial addition/edit/update.  Granted, it requires having  
> Java running, but that's not so onerous in this day and age.
> 
This model has worked just fine for www.a.o and the docs for httpd - it
is simple, easy enough to use that anyone with a reasonable grasp of how
editors work can easily use it and it has proven quite effective over a
long period of time.
The one thing I never understood is why incubator insists on placing the
whole forrest burden on new projects - as if they don't have enough
other things to worry about than learning a system that they're likely
to ditch as soon as they have the chance? 

vh

Mads Toftum
-- 
`Darn it, who spiked my coffee with water?!' - lwall


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr wrote:
> Noel J. Bergman wrote:
> >Geir Magnusson Jr. wrote:
> >
> >>What's wrong with the xdoc/Anakia approach?
> >
> >Nothing, necessarily.  David Crossley tried to put together a constructive
> >discourse regarding site construction almost two months ago, and got almost
> >no feedback.
> 
> I'll go back and try to find that.  We all seemed to miss it, and it 
> sounds like it deserves a read.  I'll grub, but it might help all of us 
> if someone or David reposts.

I already posted the URL for that message earlier in
this current thread. Noel even provided the reference
again yesterday. Here it is again.

http://marc.theaimsgroup.com/?t=113108607500002                                 
Re: simplifying the generation of Incubator website
Date: Fri, 4 Nov 2005 17:31:58 +1100
http://mail-archives.apache.org/mod_mbox/incubator-general/200511.mbox/%3c20051104063158.GA932@igg.indexgeo.com.au%3e

One reason that i sent that message, is that i needed
to go into damage control on behalf of Apache Forrest.
There is so much accusation, misinformation, and now
even deliberate flaming from an ASF member.

Such behaviour is not good for any project, and it
is especially bad to happen on the Incubator list.
I suppose that it does demonstrate a part of the
Apache Way - how to resolve public conflicts.
Perahps we can learn something and enhance our way.

Please consider letting Forrest out of here.
Use Anakia as i already suggested, or get behind
Leo's excellent new invention.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

Noel J. Bergman wrote:
> Geir Magnusson Jr. wrote:
> 
> 
>>I am +1 for dumping Forrest.  I never grok why something so simple as
>>our static website needs something so complicated to build it.
> 
> 
> Forrest does do some things for us, such as generating what I do consider to
> be a somewhat nicer looking site with collapsable menus and tabbed
> navigation than we have for the main site, JAMES, httpd, et al.  YMMV.
> 
> 
>>What's wrong with the xdoc/Anakia approach?
> 
> 
> Nothing, necessarily.  David Crossley tried to put together a constructive
> discourse regarding site construction almost two months ago, and got almost
> no feedback.

I'll go back and try to find that.  We all seemed to miss it, and it 
sounds like it deserves a read.  I'll grub, but it might help all of us 
if someone or David reposts.

> 
> 
>>And honestly, besides poking in the ApacheCon logo at the
>>appropriate times of the year, who ever edits the Anakia doc?
> 
> 
> I do, every time I need to change the side menu, or other global item.

Right- but compared to the general content changes, how often is that?

geir

> 
> 	--- Noel
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
> 
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Geir Magnusson Jr. wrote:

> I am +1 for dumping Forrest.  I never grok why something so simple as
> our static website needs something so complicated to build it.

Forrest does do some things for us, such as generating what I do consider to
be a somewhat nicer looking site with collapsable menus and tabbed
navigation than we have for the main site, JAMES, httpd, et al.  YMMV.

> What's wrong with the xdoc/Anakia approach?

Nothing, necessarily.  David Crossley tried to put together a constructive
discourse regarding site construction almost two months ago, and got almost
no feedback.

> And honestly, besides poking in the ApacheCon logo at the
> appropriate times of the year, who ever edits the Anakia doc?

I do, every time I need to change the side menu, or other global item.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Geir Magnusson Jr." <ge...@apache.org>]

I am +1 for dumping Forrest.  I never grok why something so simple as  
our static website needs something so complicated to build it.

What's wrong with the xdoc/Anakia approach?  If the problem is  
validation, that's trivial - we can easily create an dtd or xsd (if  
you don't want humans to be able to read the schema) to fix that, and  
while I admit that Anakia format doc is a bear to read, you can  
either do it via DVSL (another Vel based approach) or just plain  
XSLT.  And honestly, besides poking in the ApacheCon logo at the  
appropriate times of the year, who ever edits the Anakia doc?

I've put in a xdoc/anakia approach for Geronimo, JDO, Harmony and  
Agila, and it's been simple and mindless for anyone who wants to  
update or add to the site.

The other tools were too de-motivating, and kept people from updating  
the sites.

I'd rather err in having less-than-perfect technology with the  
benefit of trivial addition/edit/update.  Granted, it requires having  
Java running, but that's not so onerous in this day and age.

geir

On Dec 27, 2005, at 9:02 AM, Leo Simons wrote:

> Hi gang,
>
> It pains me to say this (Forrest is a cool project and I
> consider at least some of its active developers and community
> members my friends) but we've muddled around long enough.
>
> I think that, for the incubator website, Apache Forrest
>
>   * is too unstable as a codebase
>   * is way too complex
>   * has too many features we don't need and solves
>     too many problems we don't have
>   * has a learning curve that is too big
>   * does not work well with the SVN-based publishing
>     process we want to use
>   * is not well-understood by enough of the current
>     Incubator volunteers
>   * has caused frustration for too many of the current
>     Incubator volunteers
>
> I think this needs solving. I think this needs solving in
> general, not just for the Incubator (I have the exact same
> problem over at Gump, which also has a horrendously outdated
> website which also uses Apache Forrest).
>
> == Use case ==
>
> In particular, the use case we are looking at can be codified
> in the following workflow:
>
>   # 1) figure out how to edit docs...
>   curl http://svn.../site/README | less
>
>   # 2) get stuff from SVN
>   svn co http://.../site
>   cd site
>
>   # 3) edit docs
>   $EDITOR x/y/z/foo.xml
>
>   # 4) validate edit, generate results
>   ./build # must work on windows, linux, os x, solaris, ...
>
>   # 5) check results locally
>   svn diff
>   mozilla-firefox build/x/y/z/foo.html
>
>   # 6) commit
>   svn commit -m "foo.xml: fix typo. Its 'spelling', not 'speling'."
>
>   # 7) validate commit
>   mozilla-firefox http://staging.incubator.apache.org/x/y/z/foo.html
>
>   # 8) x hours later...
>   mozilla-firefox http://incubator.apache.org/x/y/z/foo.html
>
> == Requirements ==
>
> Now, steps 1-7 should be possible in about 5 minutes (provided you're
> on broadband network and a 600mhz/128mb/5400rpm machine. 5 minutes  
> includes
> reading the documentation and the like), and about 10 seconds for  
> someone
> who already knows how the tool works and has the checkout on his  
> machine
> already.
>
> Step 4 should be so quick and natural and trustable that steps 5,7  
> and 8
> are not really neccessary once you've used the tool a few times.
>
> The produced HTML should be simple, clean, valid XHTML 1.1 strict,  
> with
> navigational stuff similar to that available on other parts of
> www.apache.org. This output should be customizable in a manner that's
> similarly simple as the above use case (for eg adding banner logos or
> updating a project logo), though its allowed to be a little harder (eg
> having to learn some template language is just fine).
>
> The source format should be simple, clean, and simple to grok  
> (within the
> basic 5 minute period mentioned above) for anyone who knows how to  
> write
> basic HTML (eg <b>, <em>, <h1>). The translation from the source to  
> the
> produced HTML should be obvious and without surprises.
>
> There should be a simple file (probably XML) for specifying  
> navigational
> elements where again the transformation from source to html is so  
> obvious
> that anyone who has ever edited XML doesn't need to RTFM.
>
> == Available tools ==
>
> None of the other generally available tools satisfy all the above
> requirements at the moment.
>
>  * forrest
>    * requires installing forrest, which takes way more than 5 mins  
> in and
>      of itself
>    * basically it fails many of the use case basics (too heavyweight,
>      takes more than 3 minutes to learn, input->output transforms too
>      complex), which is probably because I wrote the use case to  
> contrast
>      with the current forrest process
>    * the transformation is not predictable enough
>
>  * maven
>    * requires installing maven, which takes 5 mins in and of itself
>      * maven 1 not easy enough to install into svn self-contained
>        * maven 1Â will essentially be "dead" as everyone migrates to
>          maven 2
>      * don't know about maven 2 yet, but it doesn't have a very widely
>        installed base yet, since it was just released
>    * the source xdoc format is not simple or clean enough
>    * the validation step is not complete enough
>    * the transformation is not predictable enough
>    * changing the stylesheet is not simple enough
>      * if maven is upgraded your entire look and feel may change as
>        well as other things (eg the xdoc plugin is not stable enough)
>
>  * anakia
>    * the source xdoc format is not simple or clean enough
>    * the validation step is not complete enough
>    * the transformation is not predictable enough
>    * managing navigational elements is not simple or clean enough
>
>  * others
>    * no doubt there are many that could be used
>
> == Possible steps forward? ==
>
> Given the above, fixing forrest seems like a lot of work. I think  
> its a
> fundamentally bad fit, being built on top of many many layers of  
> java code
> and several frameworks makes it too heavy by definition. However,  
> since
> it is very easy to customize forrest to output the source format for
> another tool, and we have ready access to forrest experts,  
> migrating away
> from forrest is probably not very painful (I think it involves  
> writing some
> XSLT). As long as the source format stays XML, moving back to  
> forrest later
> is also not painful. Standards-based. Lack of lock-in. Good.
>
> Moving back to anakia is possible, but satisfying the validation  
> requirement
> is always going to be hard because of its use of velocity rather  
> than "real"
> XML parsing.
>
> Moving forward to maven 2 is probably possible but I think the same  
> argument
> against anakia still applies to its document generation process.  
> One big
> advantage with maven is that its easy to also automate many of the  
> other bits
> of workflow, eg doing things like the 'svn commit' too.
>
> Step 7 and 8 depend on what the site-dev at apache.org people come  
> up with;
> right now this is more like having to do an "svn up" remotely,  
> setting up
> a HTTP proxy, etc, or skip 7, and just do 8, with x == 2. But  
> that'll be
> fixed. Lots of plans made, apparently. Haven't been able to figure  
> out what
> the status is right now (seems there's no code for steps 1-6 at the  
> moment),
> but its definitely going to be compatible with any tool satisfying  
> the above
> use case. See:
>
>   http://people.apache.org/~rgardler/site-dev/Site-Build.html
>
> The site-dev people have been working on some other kinds of tools,  
> including
> one that uses Perl+XSL, which shows just how simple "step 4" at its  
> core really
> is:
>
>   #!/usr/local/bin/perl
>
>   use strict;
>
>   my $xdocdir = "xdoc";
>   my $htmldir = "html";
>   my $xslfn = "xsl/xdoc2html.xsl";
>
>   opendir(XDOC, $xdocdir) || die("Couldn't open directory $rdfdir");
>   while (my $r = readdir(XDOC)) {
>       next unless $r =~ /^[a-zA-Z].*\.xml$/;
>       my $infn = "$xdocdir/$r";
>       print "Processing $infn\n";
>       my $outfn = "$htmldir/$r";
>       $outfn =~ s/\.xml$/\.html/;
>       `xsltproc $xslfn $infn > $outfn`;
>   }
>   closedir(RDF);
>
> Some things to notice...
>
>  * needs xsltproc to be installed
>  * error reporting not so intuitive (just the output from xsltproc)
>  * no clear abort on error
>  * doesn't walk directories (I think perls readdir reads the current
>    directory only)
>  * specification of navigational elements not easy enough (eg no
>    maven-style site.xml)
> (* also note some of the use case being addressed depends on the XSLT
>    file)
>
> But these kinds of things aren't exactly hard to address. So I think
> I'm going to spend a day or maybe two writing a dedicated script that
> does the above, and a little more, and then once done I'll spec up
> what forrest should be spitting out, and ask for a volunteer to write
> the neccessary stylesheets and do the conversion.
>
> The code for this is probably going to end up somewhere inside
>
>   https://svn.apache.org/repos/asf/infrastructure/site-tools/trunk
>
> Unless there's lots of discussion resulting from the above on site-dev
> (there seems to be a lot of history to this topic), then it'll end up
> somewhere else.
>
> Its probably going to be written in python and will probably use  
> minidom
> and the Kid template language. Its probably going to have a source XML
> format that is a subset of XHTML 1.1 and specified as a DTD file. I  
> think
> I'll do away with a "site.xml" or anything like that and just specify
> the menu as an XHTML snippet, since I've never ever seen site.xml  
> files
> used for anything but generating websites. I'll try and write the  
> critter
> so that its easily thrown away and replaced by something written in  
> Perl
> or Java.
>
> I think I'll call it xdok.
>
> I'll send another email once I have something working and ready for a
> demo.
>
> From there, we'll see where it goes.
>
> - LSD
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geirm@apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Leo Simons <ma...@leosimons.com>]

/me hits himself on the head for not mentioning this earlier...but..
...could we please move this thread to site-dev at apache dot org? The crossposts
are no doubt annoying some people :-)

On Tue, Dec 27, 2005 at 11:37:15AM -0800, Justin Erenkrantz wrote:
> --On December 27, 2005 6:02:18 AM -0800 Leo Simons <ma...@leosimons.com> 
> wrote:
> 
> > * anakia
> >   * the source xdoc format is not simple or clean enough
> >   * the validation step is not complete enough
> >   * the transformation is not predictable enough
> >   * managing navigational elements is not simple or clean enough
> 
> FWIW, I think these are all solvable with anakia or just not that important.

Noted. What is and what is not important enough is something that takes
potentially a lot of discussing...but I'm guessing having validated X(HT)ML is
worth something...

> For the apache.org sites that still use it (www, httpd, apr), it gets about 
> as close to your stated workflow as anything else we use today.

Yup. Admireable, huh? :-)

Of all our website tools, I still like anakia best. I'm not the only one. Heh.
Geir set up Harmony with an anakia-based thing the other day :-)

> If anything that you create has the same workflow as anakia, fine by me.

That's the baseline. Either its more productive or it gets shot.

> Altering the workflow to require Forrest or Maven-like characteristics is a 
> non-starter for me - this explains why I won't do a darn thing with the 
> Incubator site even though the site is dog-poo (both in site design and 
> content). 

aye.

> I see too many people waste too much time fighting Forrest on 
> the Incubator to justify any investment of time on my part.

I've seen so many people fight various doctools I'm putting some effort into
fixing it.

- LSD

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Justin Erenkrantz <ju...@erenkrantz.com>]

--On December 27, 2005 6:02:18 AM -0800 Leo Simons <ma...@leosimons.com> 
wrote:

>  * anakia
>    * the source xdoc format is not simple or clean enough
>    * the validation step is not complete enough
>    * the transformation is not predictable enough
>    * managing navigational elements is not simple or clean enough

FWIW, I think these are all solvable with anakia or just not that important.

For the apache.org sites that still use it (www, httpd, apr), it gets about 
as close to your stated workflow as anything else we use today.

If anything that you create has the same workflow as anakia, fine by me.

Altering the workflow to require Forrest or Maven-like characteristics is a 
non-starter for me - this explains why I won't do a darn thing with the 
Incubator site even though the site is dog-poo (both in site design and 
content).  I see too many people waste too much time fighting Forrest on 
the Incubator to justify any investment of time on my part.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Greg Stein wrote:
> David Crossley wrote:
> >...
> > If people have issues with Forrest, then please take them
> > to the user@forrest mailing list. It is totally unfair
> > to a new project to just criticise it from afar. We get
> > very few emails to the user mailing list about any issues
> > with Forrest. This seems to be especially the case with
> > committers from Apache projects that decided to use Forrest.
> >...
> > There are zero postings from Leo to user@forrest and
> > one or two relevant ones to dev@forrest.
> 
> This isn't surprising. When Forrest was deployed for the Incubator,
> and we first started having problems with it and talking about
> jettisoning it, then you (David) appeared saying "I'll provide all the
> help you need to use Forrest for the Incubator." So all the questions
> and concerns stayed right here.

Correction:
I came in long after Forrest was being employed, following
one person's plea for help to forrest-dev. I didn't
know of any jettison intentions - perhaps that was on
pmc@incubator. I doubt that i would offer to provide
"all the help" as i recognise that i am an over-committed
volunteer. It requires other people to get involved.
I certainly did help as much as i could, but i have not
pushed for the Incubator to continue to use Forrest.
In fact i have often suggested that it be relieved.

> IMO, I'm also +1 on tossing it.

I am +0, meaning that i doubt that i will be able to
help. Certainly i will try, but i am not committing
to doing the work nor writing any new howto documentation.
Thankfully because the source documents are in plain
html, then it would be easy to retain the content and
just use some other tool. Perhaps we can make forrest
output in whatever format is needed.

> The last time that I had to update the
> incubator site, I had to download a JRE for my box. Then I had to
> *checkout* about dozen *megabytes* of various java projects. I'm
> talking about megabytes of *source* code. That got built into
> something like another 60 megabytes over the next 30 minutes. Then I
> had to get the thing running against my Incubator site checkout. Once
> I got it all working, then I was able to make my 10-line edit.

Please do not exaggerate.

> No thanks. It is really cumbersome to use. I'm not about to go and
> build another Forrest just to edit some Incubator pages.

Grrr, not from you too. Please either read the earlier
comments in this thread and my previous proposal, or
go direct to http://incubator.apache.org/guides/website.html
You *only* need to edit the source. There is no excuse.

-David

> Like Justin,
> I'll just go do one of the other billion things that interests me more
> than fighting with a huge publishing system. And that is kind of sad,
> given that the Incubator should remain updated and fresh, as it is one
> of the first things that many new folks see when they come to Apache.
> 
> I think Forrest can be a great tool, but I don't think it is
> appropriate for the Incubator. We've been fighting against it for a
> LONG time now, and I think that (empirically) says that it just isn't
> suitable for this PMC, its community, and what it is trying to do.
> 
> Cheers,
> -g
> 
> -- 
> Greg Stein, http://www.lyra.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

> > I had to download a JRE for my box.
> C'mon, it's a java-based app after all.

FWIW, so is anakia, which is what we use to build the main ASF site, and
many other ASF sites.  So a JRE is pretty universally required, and
available.

> Same thing will happen with this new Super Simple Tool
> -- you'll have to download a python interpreter.

No, he won't.  HE already has one of those.  :-)  Of course, if you're a
Windows user ...

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Ross,

> Forrest has been moving towards the site-build proposal steadily. Most of
> our devs are on the site-dev list and see what little is discussed there.
> We are actually much closer to it than people not onthe Forrest lists will
> realise. We've not reported to the sie-dev list because we are not there
> yet and have learnt our lessons about speaking publically too early.

There is a balance, though, and I suggest that you really should at least
keep site-dev in the loop, at least to make sure that things mesh nicely.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

[rg...@saafe.org]

> David,
>
>> Some troubles at the ASF are that:
>> a) We cannot run java-based applications on apache
>> hardware (perhaps when the zones.a.o machine is
>> out of testing phase).
>
>> b) There are various projects using Forrest
>> but no ASF-wide installation for them to use
>> server-side.
>
>  - zones is out of testing
>  - we have new hardware that is being donated
>
> If you need a place to run your code, please see infra@ for help getting
> it
> setup.

That is great news.

We'll discusss exactly what the right approach is on the Forrest lists and
get back to infra. We've been doing various tests on our own zone for a
while now.

>
>> c) The results are committed to SVN (which is
>> nice because it enables easy site restoral and
>> other things).
>
> Alternative would be to have source materials in SVN, and generated
> artifacts in the site-build server.  But you know all about that proposal.
> :-)

Forrest has been moving towards the site-build proposal steadily. Most of
our devs are on the site-dev list and see what little is discussed there.
We are actually much closer to it than people not onthe Forrest lists will
realise. We've not reported to the sie-dev list because we are not there
yetand have learnt our lessons about speaking publically too early.

Ross


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

David,

> Some troubles at the ASF are that:
> a) We cannot run java-based applications on apache
> hardware (perhaps when the zones.a.o machine is
> out of testing phase).

> b) There are various projects using Forrest
> but no ASF-wide installation for them to use
> server-side.

 - zones is out of testing
 - we have new hardware that is being donated

If you need a place to run your code, please see infra@ for help getting it
setup.

> c) The results are committed to SVN (which is
> nice because it enables easy site restoral and
> other things).

Alternative would be to have source materials in SVN, and generated
artifacts in the site-build server.  But you know all about that proposal.
:-)

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Torsten Curdt wrote:
> Sorry, don't get it...
> 
> At work we are running continuum watching svn commits and
> then automatically rebuilding our site with forrest.
> Noone has to care about html nor forrest. Just check out
> the xdocs and commit them - done.
> 
> My 2 cents

Fantastic to hear.

Some troubles at the ASF are that:

a) We cannot run java-based applications on apache
hardware (perhaps when the zones.a.o machine is
out of testing phase).

b) There are various projects using Forrest
but no ASF-wide installation for them to use
server-side.

c) The results are committed to SVN (which is
nice because it enables easy site restoral and
other things).

That means that human committers are needed
to generate locally and commit the site, and
that is where things fall down.

Good to hear that you have isolated humans to
content editing :-)

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Torsten Curdt <tc...@apache.org>]

Sorry, don't get it...

At work we are running continuum watching svn commits and
then automatically rebuilding our site with forrest.
Noone has to care about html nor forrest. Just check out
the xdocs and commit them - done.

My 2 cents

cheers
--
Torsten

Re: [RT] Super Simple Site Generation Tool

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

Leo Simons wrote:
> OK ok ok ok. Enough already. Done and done. The incubator has more pressing things
> to worry about right now besides site generation tools. Please drop this thread or
> take it elsewhere (I suggested site-dev@ before).

I too see no need to squash such threads. Sure, take
the techincal detail elsewhere.

For me it was not so much about the site generation tools,
more about how to deal with angry customers.

> Gaah. Apologies to all for opening up a can of worms. My goal with spending time on
> this was to remove some frustration, not add to it.

I do wish that you had just presented your new work
without contrasting with Forrest.

People, let me state it again. The reason that i
have been continuing some points (and i see the
same vein with Tim and Ross, thanks) is that if such
were left to stand then the archives of the Incubator
mailing list would be doing unwarranted damage to the
Apache Forrest project. Also to the Incubator.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Justin Erenkrantz wrote:

> I don't want a staging server at all!  It's *massive* overkill and
> something I don't want to have any part of.

Fine, let's take the build server out of this equation, because it addresses
somewhat different needs.

> The way to solve the 'how do I build this?' for a project is to just do
one
> Subversion checkout and then run build....just like Anakia does.

Well, that is what I've suggested, right?

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Justin Erenkrantz <ju...@erenkrantz.com>]

On Sat, Dec 31, 2005 at 12:47:51PM -0500, Noel J. Bergman wrote:
> Justin Erenkrantz wrote:
> 
> > Noel J. Bergman wrote:
> > > if you look at plans for site-dev, they don't involve people doing
> > > their own builds, they involve a build server.
> 
> > Anakia sites don't need a build server!  I would never feel comfortable
> > about committing a change that I couldn't review myself.
> 
> The site-build server would have to support review.  That's mandatory.  I
> would like to be able to build sites locally, sure, but with dozens of ASF
> sites, and too many different ways to build them ...

Ergh.  I don't want a staging server at all!  It's *massive* overkill and
something I don't want to have any part of.  A server that takes four+
hours for me to see its changes?  Riiight.  We need instant gratification.

The way to solve the 'how do I build this?' for a project is to just do one
Subversion checkout and then run build....just like Anakia does.  I don't
care what is behind the scenes as long as it works.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Justin Erenkrantz wrote:
> Noel J. Bergman wrote:
> > Mads Toftum wrote:
> > > Whoa! so the workflow is tied to David watching for commits?
> > > When someone said that at apachecon, I thought it was a joke - I'm
> > > beginning to understand more and more of why people are annoyed.
> > 
> > Why?  The man has been tremendous about it.  He publishes daily.  And if you
> > look at plans for site-dev, they don't involve people doing their own
> > builds, they involve a build server.  Right now, ours is called David.
> 
> Anakia sites don't need a build server!  I would never feel comfortable
> about committing a change that I couldn't review myself.
> 
> The fact that we have to rely on a human being means to me (and probably
> where Mads is coming from) that the entire workflow is broken.  -- justin

The workflow of Forrest is exactly the same as Anakia.

There can be an additional build server for those who
only want to make a quick content change.

Imagine that only one committer ever manages to
find the time to run the Anakia build command and
then review and commit the changes. There would be
the same holdup. Note that this seems to be the case
for the top-level w.a.o/dev/ docs too. 

The problem seems to be that people don't want
to install Forrest locally. There is me and looking
at the commit archives i see that there have been
some others recently.

Yes agreed, the process is broken.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Ross Gardler wrote:
> Mads Toftum wrote:
> >Justin Erenkrantz wrote:
> >
> >>The fact that we have to rely on a human being means to me (and probably
> >>where Mads is coming from) that the entire workflow is broken.  -- justin
> >>
> >
> >Exactly! Depending on a 3rd party as part of the process is what really
> >blows my mind. I also begin to understand part of the frustration on
> >Davids side for spending so much time keeping an unappreciated workflow
> >up and running.
> 
> There is no need to depend on a third party, any commiter can do it.
> 
> See the instrcutions for publishing the Forrest site (very small set of 
> instructions):
> 
> http://svn.apache.org/repos/asf/forrest/trunk/etc/publishing_our_site.txt
> 
> (NB I'm not sure if David has set it up like this here or not, but it is 
> easy to do so)

What Ross is suggesting is to enable each committer at
Incubator to use a local forrestbot. No i have not yet
enabled that for Incubator. If people think that it will
help, then sure.

However the current procedure is still simple enough:
http://incubator.apache.org/guides/website.html
Esentially the same two steps that a local forrestbot
would do: 'build', allow you to review, then 'deploy'.

> ---
> 
> What's really interesting is that even on the Forrest project we have 
> this same problem. Even though David has worked really hard to make 
> publishing so easy and even though everyone in the Forrest committer 
> list knows Forrest very well, it is still very rare that anyone else 
> actually does this publication - David is tireless for us too.
>
> ======================================================================
> My point (others have made this same point)?
> 
> It is irrelevant how easy you make the process - people just don't do it!
> ======================================================================
> 
> Ross

Yes it is fascinating and puzzling.

-David


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Mads Toftum wrote:
> On Sat, Dec 31, 2005 at 08:41:35AM -0800, Justin Erenkrantz wrote:
> 
>>The fact that we have to rely on a human being means to me (and probably
>>where Mads is coming from) that the entire workflow is broken.  -- justin
>>
> 
> Exactly! Depending on a 3rd party as part of the process is what really
> blows my mind. I also begin to understand part of the frustration on
> Davids side for spending so much time keeping an unappreciated workflow
> up and running.

There is no need to depend on a third party, any commiter can do it.

See the instrcutions for publishing the Forrest site (very small set of 
instructions):

http://svn.apache.org/repos/asf/forrest/trunk/etc/publishing_our_site.txt

(NB I'm not sure if David has set it up like this here or not, but it is 
easy to do so)

---

What's really interesting is that even on the Forrest project we have 
this same problem. Even though David has worked really hard to make 
publishing so easy and even though everyone in the Forrest committer 
list knows Forrest very well, it is still very rare that anyone else 
actually does this publication - David is tireless for us too.

======================================================================
My point (others have made this same point)?

It is irrelevant how easy you make the process - people just don't do it!
======================================================================

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Mads Toftum <ma...@toftum.dk>]

On Sat, Dec 31, 2005 at 08:41:35AM -0800, Justin Erenkrantz wrote:
> The fact that we have to rely on a human being means to me (and probably
> where Mads is coming from) that the entire workflow is broken.  -- justin
> 
Exactly! Depending on a 3rd party as part of the process is what really
blows my mind. I also begin to understand part of the frustration on
Davids side for spending so much time keeping an unappreciated workflow
up and running.

vh

Mads Toftum
-- 
`Darn it, who spiked my coffee with water?!' - lwall


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Justin Erenkrantz wrote:

> Noel J. Bergman wrote:
> > if you look at plans for site-dev, they don't involve people doing
> > their own builds, they involve a build server.

> Anakia sites don't need a build server!  I would never feel comfortable
> about committing a change that I couldn't review myself.

The site-build server would have to support review.  That's mandatory.  I
would like to be able to build sites locally, sure, but with dozens of ASF
sites, and too many different ways to build them ...

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Justin Erenkrantz <ju...@erenkrantz.com>]

On Sat, Dec 31, 2005 at 11:04:18AM -0500, Noel J. Bergman wrote:
> Mads Toftum wrote:
> > Whoa! so the workflow is tied to David watching for commits?
> > When someone said that at apachecon, I thought it was a joke - I'm
> > beginning to understand more and more of why people are annoyed.
> 
> Why?  The man has been tremendous about it.  He publishes daily.  And if you
> look at plans for site-dev, they don't involve people doing their own
> builds, they involve a build server.  Right now, ours is called David.

Anakia sites don't need a build server!  I would never feel comfortable
about committing a change that I couldn't review myself.

The fact that we have to rely on a human being means to me (and probably
where Mads is coming from) that the entire workflow is broken.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Geir,

> [David] has been studly about it, but could he be studly today?
> I updated the main projects page and need that to be published.

Hopefully so.  IIRC, David is in Oz, and so it should be just past 5AM for
him.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

He has been studly about it, but could he be studly today?  I updated 
the main projects page and need that to be published...


Noel J. Bergman wrote:
> Mads Toftum wrote:
> 
>>Whoa! so the workflow is tied to David watching for commits?
>>When someone said that at apachecon, I thought it was a joke - I'm
>>beginning to understand more and more of why people are annoyed.
> 
> 
> Why?  The man has been tremendous about it.  He publishes daily.  And if you
> look at plans for site-dev, they don't involve people doing their own
> builds, they involve a build server.  Right now, ours is called David.
> 
> However, rather than repeat it here, see the tail end of my e-mail to Ross,
> where I mention some proposals for ease-of-use here in the Incubator.
> 
> 	--- Noel
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
> 
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Mads Toftum wrote:
> Whoa! so the workflow is tied to David watching for commits?
> When someone said that at apachecon, I thought it was a joke - I'm
> beginning to understand more and more of why people are annoyed.

Why?  The man has been tremendous about it.  He publishes daily.  And if you
look at plans for site-dev, they don't involve people doing their own
builds, they involve a build server.  Right now, ours is called David.

However, rather than repeat it here, see the tail end of my e-mail to Ross,
where I mention some proposals for ease-of-use here in the Incubator.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Mads Toftum <ma...@toftum.dk>]

On Sat, Dec 31, 2005 at 10:34:04AM -0500, Noel J. Bergman wrote:
> Mads Toftum wrote:
> > the logo for Apachecon that finished more than two weeks ago
> 
> Fixed the next time that David regenerates the site.
> 
Whoa! so the workflow is tied to David watching for commits?
When someone said that at apachecon, I thought it was a joke - I'm
beginning to understand more and more of why people are annoyed.

vh

Mads Toftum
-- 
`Darn it, who spiked my coffee with water?!' - lwall


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Justin Erenkrantz wrote:
> Torsten Curdt wrote:
> > As long as everyone has to have a tool locally to build and commit a
> > site in order to change *content*, people *will* find the tool annoying.
> > A smaller tool maybe less ...but it's *is* an additional step that  
> > should not be required. Period!
> 
> As has been described by numerous folks already, the idea of having to
> locally build and commit the site is not the problem that people are having
> with Forrest.  Leo's described workflow maintains exactly that behavior.
> 
> I have seen very few people argue that the workflow is wrong.  The
> prevalent comment is that Forrest is incapable of supporting that model.
> Forrest's workflow is, well, I'm not really sure; but I know that it's not
> what I want.  A "ForrestBot"?  A "staging server"?

These are additional tools that can be employed. The
base workflow of forrest is the same as others.

>  In my opinion, none of
> those should be involved for what we're trying to accomplish here.

Note that i have not yet proposed that Incubator
use the Forrestbot. It would need the concensus of
this project.

-David

> So, no issue that has been raised means that a wiki is the answer.
> 
> Far from it.  -- justin
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Justin Erenkrantz <ju...@erenkrantz.com>]

On Sat, Dec 31, 2005 at 01:35:38PM +0100, Torsten Curdt wrote:
> As long as everyone has to have a tool locally to build and commit a
> site in order to change *content*, people *will* find the tool annoying.
> A smaller tool maybe less ...but it's *is* an additional step that  
> should
> not be required. Period!

As has been described by numerous folks already, the idea of having to
locally build and commit the site is not the problem that people are having
with Forrest.  Leo's described workflow maintains exactly that behavior.

I have seen very few people argue that the workflow is wrong.  The
prevalent comment is that Forrest is incapable of supporting that model.
Forrest's workflow is, well, I'm not really sure; but I know that it's not
what I want.  A "ForrestBot"?  A "staging server"?  In my opinion, none of
those should be involved for what we're trying to accomplish here.

So, no issue that has been raised means that a wiki is the answer.

Far from it.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Torsten Curdt <tc...@apache.org>]

>> Personally, I'd like to see if the Forrest folks can "redeem" the  
>> product's
>> reputation here, and make people happy in a timely manner.
>>
> Incubator has been using Forrest for how long? So how long do you want
> to go on with something that seems to generate a lot of annoyance with
> anyone but you and the forrest committers (that is based on the  
> comments
> in this thread - I see you liking forrest, and I see David and Ross
> trying very har at "damage control").

Although I am a cocooner I am really not biased here (honestly!)
...but I do think this whole discussion is a bit unfair.

Everyone blames the tool - I would blame the process (and the related
issues David pointed out)

As long as everyone has to have a tool locally to build and commit a
site in order to change *content*, people *will* find the tool annoying.
A smaller tool maybe less ...but it's *is* an additional step that  
should
not be required. Period!

Could we maybe use the energy that comes out of this thread of  
frustration
and concentrate on fixing the process instead?

cheers
--
Torsten

how to make some requested mods to current site (Re: [RT] Super Simple Site Generation Tool)

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

Roy T. Fielding wrote:
> On Dec 31, 2005, at 7:34 AM, Noel J. Bergman wrote:
> 
>> Just the tabbed and menu navigation.  And some other little bits  that 
>> no one
>> probably uses.
> 
> 
> FTR, I hate the tabs, find the layout unreadable,...  And, no, I don't
> want the site to generate a friggin PDF.
> 
> I've known that for years now and have not bothered to fix any of
> them because I also know the entry barrier is too high on the tool.

To remove all tabs
==================

Don't define them in tabs.xml [1]

To Prevent PDF Generation
=========================

Change: <disable-pdf-link>false</disable-pdf-link>

in skinconf.xml [2]

I'm sure most people can guess what to change it to.

 > It is absolutely unacceptable that two different people
 > generating the same site will produce different results.

Impossible, unless one of the users is using different 
sources/configuration files.

Can we please stop with this misinformation. Constructive criticism is 
not a problem, in fact it is encouraged, but many statements in this 
thread are just ridiculous.

Ross

[1] 
http://svn.apache.org/repos/asf/incubator/public/trunk/site-author/tabs.xml

[2] 
http://svn.apache.org/repos/asf/incubator/public/trunk/site-author/skinconf.xml

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

David Crossley wrote:
> Geir Magnusson Jr wrote:
> 
>>Roy T. Fielding wrote:
>>
>>>I don't see any point in having this conversation every year.
>>>Whoever is willing to fix the content on incubator, please feel
>>>free to remove the entire site (except the project status files)
>>>and start over with whatever tool you deem suitable.  I have four
>>>other sites to work on that have higher priority, so chances are good
>>>that I won't be deleting the incubator site any time soon.
>>
>>Out of some sense of insomnia-driven inquisitiveness, I converted a good 
>>bit of the site to xdoc/anakia.  It took about 2.5 hours or so.
>>
>>http://svn.apache.org/viewcvs.cgi/incubator/public/trunk/site/
>>
>>It's not done.  I have to convert all the project stuff - I didn't have 
>>the internal fortitude and wherewithal to face "cwiki" - and there's a 
>>few other odds and ends.
> 
> 
> Yeah the *.cwiki are difficult. Forrest often had trouble
> with them too. As you know, i often tried to encourage
> people not to use it.
> 
> Today i repeated the process that converts the cwiki
> files into html via Forrest's "plain-dev" skin.
> For each project that still uses the cwiki format, see
> the html version in site-author/projects/TEMP_HTML/*.html
> 

Thanks - that helps :)

geir

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr wrote:
> Roy T. Fielding wrote:
> >
> >I don't see any point in having this conversation every year.
> >Whoever is willing to fix the content on incubator, please feel
> >free to remove the entire site (except the project status files)
> >and start over with whatever tool you deem suitable.  I have four
> >other sites to work on that have higher priority, so chances are good
> >that I won't be deleting the incubator site any time soon.
> 
> Out of some sense of insomnia-driven inquisitiveness, I converted a good 
> bit of the site to xdoc/anakia.  It took about 2.5 hours or so.
> 
> http://svn.apache.org/viewcvs.cgi/incubator/public/trunk/site/
> 
> It's not done.  I have to convert all the project stuff - I didn't have 
> the internal fortitude and wherewithal to face "cwiki" - and there's a 
> few other odds and ends.

Yeah the *.cwiki are difficult. Forrest often had trouble
with them too. As you know, i often tried to encourage
people not to use it.

Today i repeated the process that converts the cwiki
files into html via Forrest's "plain-dev" skin.
For each project that still uses the cwiki format, see
the html version in site-author/projects/TEMP_HTML/*.html

> It became clear that we need to rework some of the content.

:-)

> If you want to see it :
> 
> http://people.apache.org/~geirm/incubator/

Great work thanks. It is such a relief.

-David

> Happy New Year
> 
> geir

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

Roy T. Fielding wrote:
> On Dec 31, 2005, at 7:34 AM, Noel J. Bergman wrote:
> 
[SNIP]
> I don't see any point in having this conversation every year.
> Whoever is willing to fix the content on incubator, please feel
> free to remove the entire site (except the project status files)
> and start over with whatever tool you deem suitable.  I have four
> other sites to work on that have higher priority, so chances are good
> that I won't be deleting the incubator site any time soon.

Out of some sense of insomnia-driven inquisitiveness, I converted a good 
bit of the site to xdoc/anakia.  It took about 2.5 hours or so.

http://svn.apache.org/viewcvs.cgi/incubator/public/trunk/site/

It's not done.  I have to convert all the project stuff - I didn't have 
the internal fortitude and wherewithal to face "cwiki" - and there's a 
few other odds and ends.

It became clear that we need to rework some of the content.

If you want to see it :

http://people.apache.org/~geirm/incubator/

Happy New Year

geir

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Roy T. Fielding" <fi...@gbiv.com>]

On Dec 31, 2005, at 7:34 AM, Noel J. Bergman wrote:
> Just the tabbed and menu navigation.  And some other little bits  
> that no one
> probably uses.

FTR, I hate the tabs, find the layout unreadable, and nobody sees that
the important documentation has never been updated.  Half the screen
real estate is occupied by crap I don't need to see.  The renderer eats
spaces after hypertext links.  Even the logo sucks.  And, no, I don't
want the site to generate a friggin PDF.

I've known that for years now and have not bothered to fix any of
them because I also know the entry barrier is too high on the tool.
I don't even bother any more -- the real documentation belongs on
www.apache.org/dev anyway. I installed anakia there because it gave me
complete control over every single bit written to the output and
the result can be reviewed prior to commit.  I set the policy because
I was the one writing almost all the ASF content at the time.

I am not a Forrest user.  I have no time to read its mailing lists.
I don't care whether or not it is the best thing since sliced bread.
What I care about is having complete control over the content that
I write and how it appears (visually and technically) before it is
published.  It is absolutely unacceptable that two different people
generating the same site will produce different results.

I don't see any point in having this conversation every year.
Whoever is willing to fix the content on incubator, please feel
free to remove the entire site (except the project status files)
and start over with whatever tool you deem suitable.  I have four
other sites to work on that have higher priority, so chances are good
that I won't be deleting the incubator site any time soon.

....Roy

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Mads Toftum wrote:

> I don't see much sophistication in the current site

Just the tabbed and menu navigation.  And some other little bits that no one
probably uses.

> the logo for Apachecon that finished more than two weeks ago

Fixed the next time that David regenerates the site.

> > Personally, I'd like to see if the Forrest folks can "redeem" the
> > product's reputation here, and make people happy in a timely manner.

> Incubator has been using Forrest for how long?

Since Nicola Ken first set it up here.  And that was way early for the
product, which was nowhere near mature, nor was the usage pattern.

> So how long do you want to go on with something that seems to
> generate a lot of annoyance with anyone but you and the forrest
> committers

It is comments like that which want me to give it a chance to correct its
image.

Forrest's use here was probably premature, except that it was put into place
by one of its committers.  So there have been issues, certainly.  But David
has tried to put things right, and now we have other Forrest folks here,
since they can't get us onto their lists.  ;-)  And when David tried to
proactively talk about simplifying things, he got essentially NO feedback.
Feedback came later in the form of complaints.  And still, the Forrest folks
appear to be not only doing damage control, but working with Leo to provide
a nicer, simpler, cleaner workflow.  So if they believe that they can make
things simpler, why not?

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Mads Toftum <ma...@toftum.dk>]

On Fri, Dec 30, 2005 at 09:54:44PM -0500, Noel J. Bergman wrote:
> Either see what improvements we can get from Forrest, or convert to anakia
> and have a less sophisticated site.
> 
I don't see much sophistication in the current site - or is it the logo
for Apachecon that finished more than two weeks ago that counts as
sophistication? ;)

> Personally, I'd like to see if the Forrest folks can "redeem" the product's
> reputation here, and make people happy in a timely manner.
> 
Incubator has been using Forrest for how long? So how long do you want
to go on with something that seems to generate a lot of annoyance with
anyone but you and the forrest committers (that is based on the comments
in this thread - I see you liking forrest, and I see David and Ross
trying very har at "damage control"). 

vh

Mads Toftum
-- 
`Darn it, who spiked my coffee with water?!' - lwall


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Justin Erenkrantz wrote:
> Noel J. Bergman wrote:
> > Leo Simons wrote:
> > 
> > > I think what it comes down to is what we want here for the
> > > incubator is a "stable", or preferably "mature" tool, and
> > > forrest really is currently too much of a moving target
> > 
> > That can be addressed, in part, by packaging Forrest in our site build
> > structure, so that when you checkout the Incubator site, you get everything
> > you need to build it.  We do that with JAMES; everything you need comes with
> > the checkout, including the specific versions of ant, phoenix, DBCP, etc.,
> > that we use.  All in that one tree.  And when you're done, if you delete the
> > tree, there are no droppings left elsewhere.
> 
> How would even having a local copy of the JARs prevent the problem that
> Forrest won't actually generate the site?  That was the issue Geir had.

As has been endlessly exlained elsewhere in this thread,
it was a simple issue where the user removed the only
link to the page in question.

> As far as I can tell, Forrest will only work with a "ForrestBot" and a
> "staging server" - it doesn't support a model where a local build is
> sufficient to regenerate the site.

Totally incorrect as has been explained elsewhere.

> (Ross said that he is proposing that
> Forrest be able to do that in the future; but they don't do it now.)
> 
> Don't get me wrong; having everything included in incubator/site *is* a
> requirement.  The only thing a user should bring to the table is a JVM.
> As demonstrated elsewhere, Anakia works exactly like that.
> 
> > > I'm not going to be "happy" until I have a site generation tool I can
> > > basically "forget about".
> > 
> > That's a fair, but potentially orthogonal issue.
> 
> It's central to the whole discussion.  If I have to spend any time thinking
> about Forrest, it means that I'm not thinking about the content.  -- justin

I was not brave enough to package Forrest into Incubator
SVN for fear of complaints about its size.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Noel J. Bergman wrote:
> Justin Erenkrantz wrote:
> 
> 
>>How would even having a local copy of the JARs prevent the problem that
>>Forrest won't actually generate the site?
> 
> 
> I don't believe that to be correct, but we can clarify with David and Ross.

As far as I am aware the site builds fine.

There has been a problem reported in this thread that was a problem of 
user education/user error. See earlier messages in the thread for 
details (if you have the energy).

(other direct questions in this mail were repeated later in the thread 
so I'll address them there).

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Justin Erenkrantz wrote:

> How would even having a local copy of the JARs prevent the problem that
> Forrest won't actually generate the site?

I don't believe that to be correct, but we can clarify with David and Ross.

> Don't get me wrong; having everything included in incubator/site *is* a
> requirement.  The only thing a user should bring to the table is a JVM.
> As demonstrated elsewhere, Anakia works exactly like that.

OK, so we're agreeing on this, so let's see from David and Ross what we
would need to have in our checkout to satisfy the requirement.  Yes?  If
that works, great, and if not, we can move on to something that does.

> > > I'm not going to be "happy" until I have a site generation tool I can
> > > basically "forget about".
> > That's a fair, but potentially orthogonal issue.
> It's central to the whole discussion.  If I have to spend any time
thinking
> about Forrest, it means that I'm not thinking about the content.

I meant that it was orthogonal to his initial point about Forrest changing.
JAMES uses an older version of ant.  The main site uses a newer version of
ant.  I've checked, and the actual tags that we use to access anakia are
different.  Now, I don't know whether or not the new version of ant does or
does not support our older style of use, but that won't matter until JAMES
decides to move to a newer version of Ant.  Same with the Incubator, if we
provide Forrest the same way that we otherwise provide Anakia, then we can
be stable in our frame of reference, even if Forrest is evolving.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Justin Erenkrantz <ju...@erenkrantz.com>]

On Sat, Dec 31, 2005 at 11:10:13AM -0500, Noel J. Bergman wrote:
> Leo Simons wrote:
> 
> > I think what it comes down to is what we want here for the
> > incubator is a "stable", or preferably "mature" tool, and
> > forrest really is currently too much of a moving target
> 
> That can be addressed, in part, by packaging Forrest in our site build
> structure, so that when you checkout the Incubator site, you get everything
> you need to build it.  We do that with JAMES; everything you need comes with
> the checkout, including the specific versions of ant, phoenix, DBCP, etc.,
> that we use.  All in that one tree.  And when you're done, if you delete the
> tree, there are no droppings left elsewhere.

How would even having a local copy of the JARs prevent the problem that
Forrest won't actually generate the site?  That was the issue Geir had.
As far as I can tell, Forrest will only work with a "ForrestBot" and a
"staging server" - it doesn't support a model where a local build is
sufficient to regenerate the site.  (Ross said that he is proposing that
Forrest be able to do that in the future; but they don't do it now.)

Don't get me wrong; having everything included in incubator/site *is* a
requirement.  The only thing a user should bring to the table is a JVM.
As demonstrated elsewhere, Anakia works exactly like that.

> > I'm not going to be "happy" until I have a site generation tool I can
> > basically "forget about".
> 
> That's a fair, but potentially orthogonal issue.

It's central to the whole discussion.  If I have to spend any time thinking
about Forrest, it means that I'm not thinking about the content.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Leo Simons wrote:

> I think what it comes down to is what we want here for the
> incubator is a "stable", or preferably "mature" tool, and
> forrest really is currently too much of a moving target

That can be addressed, in part, by packaging Forrest in our site build
structure, so that when you checkout the Incubator site, you get everything
you need to build it.  We do that with JAMES; everything you need comes with
the checkout, including the specific versions of ant, phoenix, DBCP, etc.,
that we use.  All in that one tree.  And when you're done, if you delete the
tree, there are no droppings left elsewhere.

> I'm not going to be "happy" until I have a site generation tool I can
> basically "forget about".

That's a fair, but potentially orthogonal issue.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Leo Simons <ma...@leosimons.com>]

Hi gang,

On Fri, Dec 30, 2005 at 09:54:44PM -0500, Noel J. Bergman wrote:
> > What shall we do then in incubator?  Any idea for a productive outcome?
> 
> Either see what improvements we can get from Forrest, or convert to anakia
> and have a less sophisticated site.
> 
> Personally, I'd like to see if the Forrest folks can "redeem" the product's
> reputation here, and make people happy in a timely manner.

I've spent some time looking at the forrest project website, mail archives and
svn commit logs. I think what it comes down to is what we want here for the
incubator is a "stable", or preferably "mature" tool, and forrest really is
currently too much of a moving target (more deserving of an "alpha" or "beta"
qualifier). Heck, it says so on the front page of their website. There is
nothing wrong with that and it has little to do with "reputation", just with
expectations which aren't very well-aligned with the "development mode". I'm not
going to be "happy" until I have a site generation tool I can basically "forget
about". The forrest front page says

  "Please realise that Forrest is still pre-1.0 release version. It is certainly
   usable for those who are prepared to move with it."

and I think we don't want a moving target.

I suggest the incubator moves to something else, and then when forrest hits
1.0 (or 1.1) we can re-evaluate.

LSD


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Geir Magnusson Jr wrote:
> I disagree in trying to put the kibosh on the thread.
> 
> It was very healthy to bring out the frustration that had been 
> simmering, and I think that we all learned something.

Agreed

> What shall we do then in incubator?  Any idea for a productive outcome?

Well as I have said a number of times, my position is do what you need 
to. As a Forrest dev I've learnt what are real issues and what are user 
issues (or our management of users).

For what it is worth I just proposed an enhancement to "forrest run" 
that will solve the remaining workflow issues (with the exception of the 
large initial download).

This will provide a way to write generated content to the local build 
directoy as Geir suggested. It will also provide the ability to fully 
deploy the site from within the browser, either with or without a 
complete site rebuild.

In other words, it will integrate the ForrestBot functionality into the 
validation stage of the workflow without the need to actually install 
the ForrestBot application, just do "forrest run" as you normally do.

I'll be working on this during spare time over the next few days, not 
for the incubator, but because it is a good idea generally. Who knows 
when I'll finish it, soon I hope.

I don't expect this to mean you stay with Forrest, but it would be wrong 
of me to not show we are listening and acting upone the feedack in this 
thread.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Justin Erenkrantz wrote:
> Geir Magnusson Jr wrote:
> > What shall we do then in incubator?  Any idea for a productive outcome?
> 
> Switch the incubator to anakia.  =)
> 
> FWIW, Brett claims that Maven 2 gives up all of the goofy workflow problems
> with Maven 1, but I'm not familiar with it.  I'd go with what I know...
> 
> Count me a +1 to anakia, +0 to Maven2.
> 
> If Brett or anyone else who knows m2 can set it up such that it has the
> *exact* same workflow as anakia, I'm fine with it.  I just don't care what
> the technology is - I care that it fits our workflow and isn't a PITA to
> use or set up (svn co incubator/site + a JVM is *all* that is needed; *no*
> downloading anything else - manual or otherwise).  If someone - be it Leo or
> whomever - comes along with something better, so be it.  -- justin

Beware the overworked single vounteer problem.
More people probably know Maven. However the problem
is if one single person "sets it up" then there will be
issues down the track. Hence my proposal long ago about
each project needing a documentation team that takes care:

 http://marc.theaimsgroup.com/?l=incubator-general&m=109444576111598
 "each project needs a documentation team"

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Leo Simons <ma...@leosimons.com>]

On Fri, Dec 30, 2005 at 08:21:32AM -0800, Justin Erenkrantz wrote:
> On Fri, Dec 30, 2005 at 11:12:14AM -0500, Geir Magnusson Jr wrote:
> > What shall we do then in incubator?  Any idea for a productive outcome?
> 
> Switch the incubator to anakia.  =)

Yup.
  
> FWIW, Brett claims that Maven 2 gives up all of the goofy workflow problems
> with Maven 1, but I'm not familiar with it.  I'd go with what I know...
> 
> Count me a +1 to anakia, +0 to Maven2.

Aye. +1 to anakia. I think I'm -0 on maven2 at least for now (see below).

---

> If Brett or anyone else who knows m2 can set it up such that it has the
> *exact* same workflow as anakia, I'm fine with it.  I just don't care what
> the technology is - I care that it fits our workflow and isn't a PITA to
> use or set up (svn co incubator/site + a JVM is *all* that is needed; *no*
> downloading anything else - manual or otherwise).

I think Brett kind-of volunteered himself the other day to help us set that
up. One advantage I see is that the default look maven offers is a little
neater than what we normally get out of Anakia; it has folding menus and
stuff.

I just took a look at maven2 its site generation stuff. There's a lot of it,
and it has all this component-oriented pluggability and frameworkieness. Uses
something called Doxia,

  http://svn.apache.org/repos/asf/maven/doxia/trunk/

which kinda looks like a mini-cocoon specialised for handling xdoc-style
website generation. I dunno. There's a lot of code in there, and most of it
is Really New(tm). Maybe re-evaluating using maven2 something like 6 or 12
months from now is a good idea. Shrug. 95% of the reason for using maven (like,
having to build and maintain software) doesn't really apply to the incubator
website.

> If someone - be it Leo or
> whomever - comes along with something better, so be it.  -- justin

I just finished comparing Anakia with what I came up with:

  https://svn.apache.org/repos/asf/infrastructure/site-tools/trunk/xdok/harmony-sample/README.txt

Conclusion: for us, its probably better to just use Anakia.

ciao!

LSD


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Justin Erenkrantz <ju...@erenkrantz.com>]

On Fri, Dec 30, 2005 at 11:12:14AM -0500, Geir Magnusson Jr wrote:
> What shall we do then in incubator?  Any idea for a productive outcome?

Switch the incubator to anakia.  =)

FWIW, Brett claims that Maven 2 gives up all of the goofy workflow problems
with Maven 1, but I'm not familiar with it.  I'd go with what I know...

Count me a +1 to anakia, +0 to Maven2.

If Brett or anyone else who knows m2 can set it up such that it has the
*exact* same workflow as anakia, I'm fine with it.  I just don't care what
the technology is - I care that it fits our workflow and isn't a PITA to
use or set up (svn co incubator/site + a JVM is *all* that is needed; *no*
downloading anything else - manual or otherwise).  If someone - be it Leo or
whomever - comes along with something better, so be it.  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Noel J. Bergman wrote:
> Ross Gardler wrote:
...

> As I understood your recent comments, you (Forrest) are actively working to
> make the workflow simpler, such than anyone should be able to download a
> binary, grab our site from SVN, build and publish.  Correct?

Yes that is correct. As an example, see the simple instructions for 
building and deploying the Forrest site (very small file):
  http://svn.apache.org/repos/asf/forrest/trunk/etc/publishing_our_site.txt

We are also removing the need to have Forrest installed locally. In this 
instance just get Incubator SVN, make edits, commit, log in to a webapp 
and a click on a button to build the site for QA. OK, this is not a 
great idea for major edits or structural changes but, for very simple 
edits (spelling for example) this is great.

In other words you can get your community much more involved by removing 
the need to install/learn *any* software locally other than SVN and 
their chosen editor. Edit, commit, login, click.

Forrest does not enforce the same workflow on everyone (Cocoon, for 
example, use a CMS, thus removing the need to checkout SVN as well)

I find it strange that this thread claims the workflow is not supported, 
we support *many* workflows, including the one outlined in the very 
first mail of this thread.

>>Will it be timeley? I don't know we are all volunteers. It will take as
>>long as it takes.
> 
> 
> Best guess?

The one line build and commit works now.

The webapp described above works now (not yet working on the Forrest 
Zone, but I use it in a production).

Improve the local edit/build workflow? I intend to have a prototype 
within a week, it is holidays after all. However, no promises, I am a 
volunteer ;-)

What will this do? It will implement a new "forrest run" feature that 
will allow you to save a file to the built site from within the browser, 
as suggested by Geir in this thread.

Of course, the above build and deploy options will also be available 
from within the browser as part of this prototype.

> just run the ant build, optionally with a site target.  How
> hard would that be?  That seems to be the level of ease-of-use that people
> expect, and would welcome.

I don't think this is a problem, the "forrest" command is only a wrapper 
for Ant. We need a specific version of ANT but I don't think there are 
any remaining issues with using a version not supplied with Forrest 
itself. I'd need to confirm that with Forrest devs though.

> what if we were to put the correct
> version of Forrest as a binary in our site build structure, along with a
> build script?  That would ensure that the correct version is being used, and
> support better ease of use, no?

This is certainly possible. The problem is that Forrest is, as has been 
observed, a large download - too large (not 60Mb as someone claimed in 
this thread, more like around 20Mb, but still large).

I would actually recommend using a snapshot of SVN head instead. The 
reason being that we (Forrest) could add the incubator site to our 
integration tests on the Forrest zone. I like the idea of this because 
the Incubator use is not "typical" of Forrest users (for example, you 
use html sources).

Incubator wouldn't be using Forrest SVN head exactly, rather a "last 
known working version" packaged as a binary. We would store this in the 
Forrest SVN, and the incubator could include it in your checkout with an 
svn:external. Thus you would be protected from the occasional breaks in 
our codebase.

Downside? Periodic upgrades of this snapshot, which would be more 
frequent than Forrest releases would result in a large svn update.

NOTE: this would require the agreement of the Forrest community as 
someone would have to build this snapshot. I'm willing to volunteer to 
do that, but nevertheless, I don't represent the whole community and 
there may be objections. I will discuss on the Forrest list and report 
back here if there is interest.

I also volunteer to ensure the incubator site was kept up to date with 
changes in Forrest so that it will always build with the latest binary 
snapshot. Of course, there is always the risk that i disappear. We know 
the dangers of relying on a single person.

This could be avoided by sticking with a specific version of Forrest, 
again we could provide such a snapshot.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Ross Gardler wrote:

> In my opinion sticking with Forrest will be damaging to both parties
unless:
> - people here are willing to actually respond to Davids proposals
>  (not necessarily agree, but at least respond)

I agree that it isn't fair to always file feature requests in the form of
complaints, and not to participate in the process for resolving them ...

> - make feature requests for Forrest via our own lists and/or jira rather
>   than on lists that we don't read
> - use our user lists and docs in order to resolve problems they are
> having with the tool

... and I agree that it is generally appropriate to communicate directly
with the project.  After all, if the Maven folks wanted to know about all of
the complaints and diatribe targeted at it, they'd have to subscribe to just
about every Java-based list we have.  Not practical.

On the other hand, people don't always tend to join lots of lists,
especially when they are already on lots of lists.  They want discussion
centered around their needs, not everyone's.  So, when we had some issues
using Derby with JAMES, we didn't all join derby's lists en masse.  Instead,
we invited a few of them to join us on our list.

We can debate which approach works best, but at least we did make a point of
direct involvement.  And I think that we can agree that direct involvement
is the real key.

> then I would be +1 on sticking with Forrest (yes +1, as in I will be
> active *here* in incubator). However, I am still only one *volunteer*,
> as is David. We need other people to put in a little effort.

As I understood your recent comments, you (Forrest) are actively working to
make the workflow simpler, such than anyone should be able to download a
binary, grab our site from SVN, build and publish.  Correct?

> As I said in an earlier post, we have taken the valid parts of the
> criticism here on board and are working on it

Yes, I've been paying attention.

> Will it be timeley? I don't know we are all volunteers. It will take as
> long as it takes.

Best guess?

FWIW, I just looked over how we do the site builds with Ant for both JAMES
and the main site.  Each is a bit different, but both depend on having an
anakia task registered with Ant.  No one, anymore, needs to know how that
was done.  They just run the ant build, optionally with a site target.  How
hard would that be?  That seems to be the level of ease-of-use that people
expect, and would welcome.

In fact, when you checkout JAMES, except for jars that we cannot provide
from source control, due to licensing (JavaMail), you get everything you
need to do the build, including Ant and other dependencies -- the specific
version that we've tested and use.  So what if we were to put the correct
version of Forrest as a binary in our site build structure, along with a
build script?  That would ensure that the correct version is being used, and
support better ease of use, no?

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Noel J. Bergman wrote:
>>What shall we do then in incubator?  Any idea for a productive outcome?
> 
> 
> Either see what improvements we can get from Forrest, or convert to anakia
> and have a less sophisticated site.
> 
> Personally, I'd like to see if the Forrest folks can "redeem" the product's
> reputation here, and make people happy in a timely manner.

I've been checking the archives.

In my opinion sticking with Forrest will be damaging to both parties unless:

- people here are willing to actually respond to Davids proposals (not 
necessarily agree, but at least respond)

- make feature requests for Forrest via our own lists and/or jira rather 
than on lists that we don't read

- use our user lists and docs in order to resolve problems they are 
having with the tool

If people here are willing to do the above (which is not anything other 
than the normal "Apache Way") then I would be +1 on sticking with 
Forrest (yes +1, as in I will be active *here* in incubator). However, I 
am still only one *volunteer*, as is David. We need other people to put 
in a little effort.

As for "redeeming" the product. As I said in an earlier post, we have 
taken the valid parts of the criticism here on board and are working on 
it (there has already been 2 doc improvements and one bug fix as a 
result of observations here, plus one proposal to make our ForrestBot 
functionality available durning "forrest run").

Will it be timeley? I don't know we are all volunteers. It will take as 
long as it takes.

If any of the above seems unreasonable then I am -1 on sticking with 
Forrest.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

> What shall we do then in incubator?  Any idea for a productive outcome?

Either see what improvements we can get from Forrest, or convert to anakia
and have a less sophisticated site.

Personally, I'd like to see if the Forrest folks can "redeem" the product's
reputation here, and make people happy in a timely manner.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Geir Magnusson Jr <ge...@pobox.com>]

I disagree in trying to put the kibosh on the thread.

It was very healthy to bring out the frustration that had been 
simmering, and I think that we all learned something.

What shall we do then in incubator?  Any idea for a productive outcome?

geir

Leo Simons wrote:
> OK ok ok ok. Enough already. Done and done. The incubator has more pressing things
> to worry about right now besides site generation tools. Please drop this thread or
> take it elsewhere (I suggested site-dev@ before).
> 
> Gaah. Apologies to all for opening up a can of worms. My goal with spending time on
> this was to remove some frustration, not add to it.
> 
> LSD
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
> 
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Leo Simons <ma...@leosimons.com>]

OK ok ok ok. Enough already. Done and done. The incubator has more pressing things
to worry about right now besides site generation tools. Please drop this thread or
take it elsewhere (I suggested site-dev@ before).

Gaah. Apologies to all for opening up a can of worms. My goal with spending time on
this was to remove some frustration, not add to it.

LSD

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Tim Williams <wi...@gmail.com>]

On 12/29/05, Greg Stein <gs...@lyra.org> wrote:
> On Wed, Dec 28, 2005 at 01:12:52PM +1100, David Crossley wrote:
> >...
> > If people have issues with Forrest, then please take them
> > to the user@forrest mailing list. It is totally unfair
> > to a new project to just criticise it from afar. We get
> > very few emails to the user mailing list about any issues
> > with Forrest. This seems to be especially the case with
> > committers from Apache projects that decided to use Forrest.
> >...
> > There are zero postings from Leo to user@forrest and
> > one or two relevant ones to dev@forrest.

Welcome to our community.  We are free from being grounded in any
reality.  We are free from talking in the concrete, preferring instead
to make baseless general statements.  Over the years our egos have
grown so large that we no longer see a need to ask questions even
though we don't know the answers.  Instead, we'll bitch and complain
and blame it on our fellow community member's crappy tool.  Our time
is so valuable that we'd prefer to grossly over-exaggerate how bad the
tool is than actually try to help fellow members of our community make
it better -- that's there problem, after all, and it's tons easier to
just spout nonsense than actually contribute to *someone else's*
problem.  This introduction to community isn't from an Apache novice
like me, it's what I've learned by watching those more experienced
old-timers that I have so much respect for... Dissappointing to say
the least...

Now on to the hyperbole...

> The last time that I had to update the
> incubator site, I had to download a JRE for my box.

C'mon, it's a java-based app after all.  I assume this was your first
time ever running forrest or any other java app?  That you lump
*having* to download a JRE in with Forrest's issues just shows me that
you're not really trying to help at all, just adding a little noise to
make your point a little stronger I suppose.  Same thing will happen
with this new Super Simple Tool -- you'll have to download a python
interpreter.

> Then I had to
> *checkout* about dozen *megabytes* of various java projects. I'm
> talking about megabytes of *source* code.

I really don't know why we ship the little bit of source code with
Forrest to be honest -- doesn't make much since.  To put your flagrant
hyperbole into perspective though, your megabytes==140k.  Yep, Forrest
0.7 has a whopping 140k of source code.  We do have numerous jars that
add considerably to the size being ~29M -- we should really try to
trim that down considerably before our 1.0 release.

> That got built into
> something like another 60 megabytes over the next 30 minutes.

A couple thoughts come to mind here...  If you're a user, why are you
building it anyway -- just use the distribution.  As I said, 0.7 is
~29M built, I don't know how that got doubled on your machine.  As to
the 30 minutes, did you figure out how to get a JRE on that Commodore
64 or something?  It consistently takes ~9 seconds to build forrest on
my box which is not a high-end machine by any stretch.  Bottom line: 
You appear to be doing several things wrong here and you could help
yourself, Forrest, and the ASF community a great deal by simply asking
instead of hyperbolizing.

> Then I
> had to get the thing running against my Incubator site checkout. Once
> I got it all working, then I was able to make my 10-line edit.

I think David said that the Incubator is using HTML as source so all
this was for nothing, you could have simply made your edits.  Again,
no one is too much of an expert to ask questions every now and then.

All in all, I'm incredibly dissappointed with some of the older and
wiser folks' apparent idea of community.  Here, I'm not talking so
much about a tool.  I'm talking about just a total lack of respect and
helpfulness.  I mean, if folks are too lazy to RTFM or learn how to do
things or ask questions.. fine... but why trash the work of fellow
community members because of your own laziness?    I think all of the
folks on Forrest openly admit to its blemishes (and it has plenty),
more so than other projects I think.  But it's unfortunate to hear
fellow community members spout issues that indicate a lack of
understanding rather than real issues and to use gross
exaggeration/hyperbole to make the non-issue a appear a little
stronger.

(non-binding) +0 to dumping Forrest in the incubator...

--tim

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Greg Stein <gs...@lyra.org>]

On Wed, Dec 28, 2005 at 01:12:52PM +1100, David Crossley wrote:
>...
> If people have issues with Forrest, then please take them
> to the user@forrest mailing list. It is totally unfair
> to a new project to just criticise it from afar. We get
> very few emails to the user mailing list about any issues
> with Forrest. This seems to be especially the case with
> committers from Apache projects that decided to use Forrest.
>...
> There are zero postings from Leo to user@forrest and
> one or two relevant ones to dev@forrest.

This isn't surprising. When Forrest was deployed for the Incubator,
and we first started having problems with it and talking about
jettisoning it, then you (David) appeared saying "I'll provide all the
help you need to use Forrest for the Incubator." So all the questions
and concerns stayed right here.

IMO, I'm also +1 on tossing it. The last time that I had to update the
incubator site, I had to download a JRE for my box. Then I had to
*checkout* about dozen *megabytes* of various java projects. I'm
talking about megabytes of *source* code. That got built into
something like another 60 megabytes over the next 30 minutes. Then I
had to get the thing running against my Incubator site checkout. Once
I got it all working, then I was able to make my 10-line edit.

No thanks. It is really cumbersome to use. I'm not about to go and
build another Forrest just to edit some Incubator pages. Like Justin,
I'll just go do one of the other billion things that interests me more
than fighting with a huge publishing system. And that is kind of sad,
given that the Incubator should remain updated and fresh, as it is one
of the first things that many new folks see when they come to Apache.

I think Forrest can be a great tool, but I don't think it is
appropriate for the Incubator. We've been fighting against it for a
LONG time now, and I think that (empirically) says that it just isn't
suitable for this PMC, its community, and what it is trying to do.

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Ross Gardler wrote:

> Noel J. Bergman wrote:
> > Fair drawback, since I doubt that if one edits the HTML in SVN directly,
> > that Confluence would be able to pick up the changes.  OTOH, isn't this
> > how Cocoon is doing their docs now, albeit with Daisy?

> Daisy does not write to SVN so the only way to edit the docs are via the
> web interface. It does provide version control, with diffs etc. but, we
> (Forrest) decided that the lack of off-line editing is a real problem.

Both of those can be issues.  The SVN one was raised by me in late October
regarding Cocoon's use of Daisy.  The thread was "Re: Official source
content in CMS other than CVS/SVN?" on the infrastructure list.  I might
restart it on site-dev, as per David Crossley's suggestion.

And I came across a more detailed response to me regarding how Cocoon uses
Daisy:

  "The daisy install, as far as I understand it, is simply a way for us
  Cocoon developers to work easily on our XML-based doucmentation from
  a browser, rather than having to check-out, edit XML in "vi", check-
  in, and so on... From there, the documents are rendered using Cocoon/
  Forrest and will become our static web-site, so the pattern is quite
  different from Wikis.

> Consequently, Forrest and Lenya intend to work together. The Lenya folk
> say they can make lenya write to SVN on the back end, thus folk will be
> able to choose their tool.

That sounds great.  :-)

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

Noel J. Bergman wrote:
> Geir Magnusson Jr. wrote:
> 
> 
>>Noel J. Bergman wrote:
> 

...

>>Confluence isn't that, and you can't work offline.
> 
> 
> Fair drawback, since I doubt that if one edits the HTML in SVN directly,
> that Confluence would be able to pick up the changes.  OTOH, isn't this how
> Cocoon is doing their docs now, albeit with Daisy?

Not quite.

Daisy does not write to SVN so the only way to edit the docs are via the 
web interface. It does provide version control, with diffs etc. but, we 
(Forrest) decided that the lack of off-line editing is a real problem.

Consequently, Forrest and Lenya intend to work together. The Lenya folk 
say they can make lenya write to SVN on the back end, thus folk will be 
able to choose their tool.

We (Forrest) are an XML Publishing Framework, we don't care where the 
content comes from. The idea is that projects should be able to use 
their preferred tools, as long as they satisfy the ASF requirements for 
for traceability. Forrest will suck that content out and present it in a 
unified form.

So do we care if Infra moves away to a simpler system? No, I don't think 
we do, as long as the content is in an XML format we will be able to 
incorporate it into the site-build tool that infra need.

Ross

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

Geir Magnusson Jr. wrote:

> Noel J. Bergman wrote:

> > In any event, there are a variety of ways forward.  Alex, Ted,
> > Serge and others appear to like the idea of a authentication
> > restricted Confluence to use for generating HTML.

> I think that we should have a neutral open format that our docs

Yes.  HTML or XML/XSLT.  Confluence would be used as an HTML editor, as I
understand their proposal.

> Confluence isn't that, and you can't work offline.

Fair drawback, since I doubt that if one edits the HTML in SVN directly,
that Confluence would be able to pick up the changes.  OTOH, isn't this how
Cocoon is doing their docs now, albeit with Daisy?

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

["Geir Magnusson Jr." <ge...@apache.org>]

On Dec 28, 2005, at 12:52 PM, Noel J. Bergman wrote:

>
>
> In any event, there are a variety of ways forward.  Alex, Ted,  
> Serge and
> others appear to like the idea of a authentication restricted  
> Confluence to
> use for generating HTML.

I think that we should have a neutral open format that our docs and  
sites are in.  Confluence isn't that, and you can't work offline.   
PLease, lets not solve this with a wiki.

geir

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geirm@apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

RE: [RT] Super Simple Site Generation Tool

["Noel J. Bergman" <no...@devtech.com>]

[Sorry for the delayed response ... spent a few days rebuilding my laptop.]

David tried to get people interested in the issue, constructively, back in
November.

 ref:
http://mail-archives.apache.org/mod_mbox/incubator-general/200511.mbox/%3c20
051104063158.GA932@igg.indexgeo.com.au%3e

Please review David's post from almost two months ago, and contribute
constructively to the discussion.

There is no need to waste an hour.  For one thing, we've told people
repeatedly to just publish their HTML changes, and that the site will be
taken care of for them.

All tools have issues.  Anakia remains the one I am most comfortable with,
but I have even had issues with anakia, which we use with JAMES, trying to
manage the occassionally annoying project stylesheet.  And Maven ... well,
no thanks.

In any event, there are a variety of ways forward.  Alex, Ted, Serge and
others appear to like the idea of a authentication restricted Confluence to
use for generating HTML.  Daisy is used by Cocoon for similar purposes.  But
most of the discussion probably belongs on the site-dev@a.o list, where
we're trying to bring some semblance of sanity to the overall ASF site
management process.

	--- Noel


---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

David Crossley wrote:
> If people have issues with Forrest, then please take them
> to the user@forrest mailing list. It is totally unfair
> to a new project to just criticise it from afar. We get
> very few emails to the user mailing list about any issues
> with Forrest. This seems to be especially the case with
> committers from Apache projects that decided to use Forrest.

This is *very* important. In cal my time on the Forrest project I do not 
recall a single question from an Incubator volunteer on our user lists.

In this thread one person encouraged people to visit the archives of the 
Forrest lists because they were fed up of working with Forrest to get it 
to where they want. I checked, last post with that name on the dev list 
was March 2004 and there were no posts to the user list.

How is that working with us? Why is it that I find myself joining yet 
another list because I hear grumbles in a completely unrelated list 
saying that Incubator has some issues with Forrest? Why should I, as a 
Forrest dev, have to join your list?

Even having joined this list, I see almost no contributions to Davids 
repeated attempts to try and understand what incubator need, so I am 
still unaware of the problems.

In my opinion the problem is not the tool, it is the number of 
volunteers wanting to work with whatever tool is in use. This is the 
issue that needs addressing regardless of whether you use 
Forrest/Maven/Anakia or some Python tool created specifically for the 
purpose.

That being said, as people will see from my replies on the site-dev 
list, I have some sympathy with Leo, and I do agree that Forrest is 
large and cumbersome for building a simple site. However, I am annoyed 
at various statements in this thread that claim to represent Forrest as 
it stands today but in fact illustrate a lack of understanding of the 
capabilities of Forrest head which is an increasingly stable platform 
that has been working towards the goals of the site-build project [1] 
(despite claims to the contrary in this thread).

Current SVN head of Forrest, coupled with Davids implementation of the 
ForrestBot means Forrest can do steps one through seven of Leo's 
workflow (with a local install of Forrest being optional). Of course, we 
are a 0.8-dev project, not a 1.0 project. The solution is not perfect, 
it is still a 0.8-dev project, and the claimed support needs to be 
tested and validated in a wider range of projects (currently we only 
have private dev projects, Forrest test sites and Cocoon-docs)

Step 8 (publishing) cannot currently be done by any tool due to the fact 
that infra require that the live server to be updated by a pull rather 
than a push process (for security reasons).

It'd be great to work with the incubator to help validate things, but 
that requries more than David (and now myself) to support the incubator 
site, it requires at least a willingness to provide feedback to the 
Forrest community about what is good and what is bad. I don't see that 
happening so maybe Leo's Python scripts are the solution (at least they 
will allow me to not worry about the incubator site).

Ross

[1] http://people.apache.org/~rgardler/site-dev/Site-Build.html

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

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

I am not trying to defend Forrest. We already acknowledge
that there are some inadequacies for the situation where
people do not want to learn and enhance the tool, and rather
they just want to use it to generate some quick doco.
Forrest is overkill for that. Why are people using it
and then criticising it for being overkill?

There are some misguided comments below, so i attempt
to correct them. We cannot afford to leave public
comments hanging.

Leo Simons wrote:
> Hi gang,
> 
> It pains me to say this (Forrest is a cool project and I
> consider at least some of its active developers and community
> members my friends) but we've muddled around long enough.

Interesting that you don't acknowledge my recent posting
to general@incubator on this topic.
http://marc.theaimsgroup.com/?t=113108607500002
Re: simplifying the generation of Incubator website

We got very little feedback on that. I had put in an incredible
amount of effort and it hurts to have it ignored. (Thanks
to the sole responder.)

If people have issues with Forrest, then please take them
to the user@forrest mailing list. It is totally unfair
to a new project to just criticise it from afar. We get
very few emails to the user mailing list about any issues
with Forrest. This seems to be especially the case with
committers from Apache projects that decided to use Forrest.

> I think that, for the incubator website, Apache Forrest
> 
>   * is too unstable as a codebase
>   * is way too complex
>   * has too many features we don't need and solves
>     too many problems we don't have
>   * has a learning curve that is too big
>   * does not work well with the SVN-based publishing
>     process we want to use

Would you please explain what you mean by that SVN point.

>   * is not well-understood by enough of the current
>     Incubator volunteers
>   * has caused frustration for too many of the current
>     Incubator volunteers
> 
> I think this needs solving. I think this needs solving in
> general, not just for the Incubator (I have the exact same
> problem over at Gump, which also has a horrendously outdated
> website which also uses Apache Forrest).

At Gump i hope that you are using a recent version
of Forrest and have configured it properly. Remember
that it is in a 0.x series of releases. If you tell
us your problems, then we will try to help.

There are zero postings from Leo to user@forrest and
one or two relevant ones to dev@forrest.

[ snip ]
> Given the above, fixing forrest seems like a lot of work. I think its a
> fundamentally bad fit, being built on top of many many layers of java code
> and several frameworks makes it too heavy by definition. However, since
> it is very easy to customize forrest to output the source format for
> another tool, and we have ready access to forrest experts, migrating away
> from forrest is probably not very painful (I think it involves writing some
> XSLT).

There is already one alternative skin called "plain-dev".
Set that in your forrest.properties and you will get
plain html output. The "-dev" on the end means "in development".
Send a patch if you can fix something.

> As long as the source format stays XML, moving back to forrest later
> is also not painful. Standards-based. Lack of lock-in. Good.

The format of the source content is not a concern of Forrest.
Forrest is only about drawing together various source content
and generating consistent output.

Have you looked at the source format for the Incubator site.
Plain html. It seemed that people could not cope with xml,
so the Incubator site was switched a couple of years ago.

It is interesting to note that even though people have the
option at Incubator to just edit the source html content
and leave it for someone else to generate the site, that this
does not really happen.

It always amazes me that when people see a documentation
blockage, then they blame the tools and go off inventing
new ones.

I predict that the problem has nothing to do with the
particular doc generation tools. It is mostly about content
editing and about people having enough urge to even bother
with that task. Consider the top-level apache.org website
(e.g. /dev/). It uses the wonderfully simple Anakia. However,
people still don't do much enhancement of those docs.

> I think I'll call it xdok.
>
> I'll send another email once I have something working and ready for a
> demo.
> 
> From there, we'll see where it goes.

I sure hope that it doesn't turn into a one-person show.

-David

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org

Re: [RT] Super Simple Site Generation Tool

[Henri Yandell <fl...@gmail.com>]

On 12/27/05, Leo Simons <ma...@leosimons.com> wrote:

> == Available tools ==
>
> None of the other generally available tools satisfy all the above
> requirements at the moment.

How about just plain xml and xslt?

Stick a build.xml in there, but people are free to use the xslt engine
of their choice. xmlproc or whatever.

The only problem that seems to occur then is that you have to stick to
standard xslt, and that different engines format things differently,
so a noisy svn.

Or just write the documentation in html. An ant script to do the
search and replace for the nav bar, the header and the footer if
that's what we're talking about. Write a nice css to handle the
formatting.

Hen

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org