Bug 15949

Is the FAQ no clearer?

If so, please close this bug.

"no" should have been "now", sorry.

Hhmm, have your changes already been deployed - I don't really see much change
yet...?
Also, the page is broader than my Mozilla1.3/MSIE window and doesn't adapt on
re-sizing - is that intentional??

Yes, they have been deployed.

Two changes:

* it now says "docs.xml at the top level of the jakarta-ant CVS module"

* and "jakarta-site2 CVS module" instead of just "jakarta-site2 module"

hmm, that's kind of minimalisitc   ;)

Or 1) do you anyway advocate to rather use forrest/cocoon?

Also, 2) what do you say about the window size/horizontal scroll-bar/resizing issue?

minimalistic?  Well, yes, certainly, patches welcome 8-)

forrest/cocoon?  We (as in "the Ant developers") have not yet decided what we want
to do with our doc building system in the future.  We are watching Forrest.
IM (as in "Stefan's") HO Forrest is not yet up to the task completely.

layout?  Well, it's always been that way ;-)  See ant.apache.org for an idea of
what we may be up to in the future (this looks like Forrest but uses Anakia).

If I were able to reproduce the faq.html, I would be happy to provide the
patches you are asking for...  (see my comment to
http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15948)!
The new ant.apache.org looks nice! congrats! 
Would it be possible to produce also w3c validating xhtml11 instead of html4/loose ?

The easiest way to reproduce the FAQ is to check out the complete jakarta-ant and
the complete jakarta-site2 CVS module so that the directories are siblings.

After that, run Ant on the docs.xml file inside the jakarta-ant directory.

The minimal amount of stuff you need from the Ant module is docs.xml, xdocs/faq.xml
and the complete xdocs/stylesheets directory.  You also need all the jars that
Anakia requires, which means you need the complete lib directory of jakarta-site2.

Created attachment 4460 [details]
free docs.xml from jakarta-site2 subtree dependency

It appears that all the jars needed for docs.xml/anakia to be able to properly
create faq.html from faq.xml can be found in the jakarta-velocity tree as well.
And this one is really needed to perform the translation. site2 appears to be
somewhat unneccessary overhead to a location-independent way to build a faq.
The last <echo> statement mentioning the velocity.log file addresses the issues
raised in http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15948

One remaining issue: While the faq gets translated perfectly, it fails to
translate the following macros: header, footer, source, table.
First, in velocity.log, I got the error message:
[error] ResourceManager : unable to find resource 'VM_global_library.vm' in any
resource loader.
Found the missing file in jakarta-velocity\test\templates and placed in the
stylesheets directory.
No change in the faq.html, but a new error message in .log:
[error] VM #recurse: error : too few arguments to macro. Wanted 1 got 0

Created attachment 4461 [details]
The patch you were asking for.

O.k. figured that the VM_global_library.vm was the wrong direction, getting
velocity.properties into xdocs solved it.

Therefore, the second attachment/patch now is what I propose to have the next
person trying to do what I tried doing it in minutes, not hours (assuming you
update docs.xml with the first patch).

OK, just did a clean ant build, have jakarta-site checked out and did 
ant -f docs.xml

It all works, so I don't think we need to change that. Thanks

Conor,

Sure, it works as is. But wouldn't a little bit more user-friendliness be useful
for two reasons:
1) more people using this velocity-based approach to generate html might
increase the prevalence of velocity in general
2) as per my patches - checking out jakarta-site isn't necessary, since all you
need is in velocity/build/lib already

Also, did you have a chance to look at the patches I provided?
It would be strange if an apache.org-person asks me for a patch in the first
place and now my contribution gets dumped apparently even without being looked
at at all...   :(

r.

If you feel the bug has not been addressed, please feel free to reopen.

Of course I have looked at the patches. I don't see that replacing a dependency
on jakarta-site2 with a dependency on jakarta-velocity is a great change.

<     <property name="velocity.dir"     location="../jakarta-velocity" />

It is not really my mission to promote velocity usage. I like velocity in
general but all I want is a system which can build the Ant website. The
underlying technology is not that relevant.

As for the second patch, I didn't see the benefit of putting links into CVS from
the documentation since it is likely that the user will already have everything
checked out. 

What issue is it that you are trying to solve?

the issue to solve is: get a generic way to manage a website more effectively
than just plain html in a cvs.
In order to use the great mechanism you have developed for the ant website, I
only need the velocity engine, but not the entire jakarta-site tree and I am up
and running. The benefits are that your approach is a lot simpler than what
forrest/cocoon does and as Stefan wrote above: you are watching forrest/cocoon,
but even with your new ant.jakarta.org website you do use their layout ideas,
but not their underlying technology.

OK, I'm going to reopen as an enhancement - we can revisit.