Hi Brett,
On 1/9/06, Brett Porter <[EMAIL PROTECTED]> wrote:
>
> Hi John,
>
> I think the answer is not to change the APT parsing, but allow mapping
> level 1 to h3, level 2 to h4, etc (I think that's what you wanted?) It
> still may be worth looking into.
Yeah, I considered that, but don't think it is quite right. This issue of
headings is specific to /index.html in the generated site, and does not
affect any other page. If Java.Net was not prepending anything special for
the /index.html content (in addition to the regular Java.Net chrome), then
my src/site/apt/index.apt file would be of the form:
Project Name
some general project text goes here
* Description
the description text goes here
* Mission
the mission statement goes here
As it is, Java.Net takes ownership of everything up to and including the "*
Description". That's why I thought it would be useful to be able to provide
context for APT parsing in this case.
Suppose I would like to add another Section heading after the "Mission"
Sub-section, such as a "Testimonials" Section, then there would be no way to
represent that in the index.apt file if a change in heading mapping is used,
whereas providing context would work fine.
It might be useful to have some way to specify the structure without it
being included in the generated documentation. For example:
Project Name~!~
* Description~!~
the description text goes here
* Mission
the mission statement goes here
Just an idea. :-)
In all the other site documentation, I would definitely want Section to map
to <h2> so that it matches the <h2>Project Name<h2> created automatically by
Java.Net for /index.html. So, if we did go for a Section mapping to <h3>,
it would need to be restricted to src/site/apt/index.apt only, although that
would mean giving up on having additional Sections in /index.html, but that
would be easy enough to live with. :-)
Either way, these are core changes that would need to be investigated
> (please JIRA). In the interim, can you achieve the look you want using
> CSS to adjust the bigger headings?
At the moment, my Maven-generated html site docs don't need any specific
CSS, but they do reference the Java.Net "app" class as part of the
java.net.vm Velocity template. This causes other contextual style selectors
in the Java.Net CSS stylesheet to be picked up automatically, such as ".app
h2" and ".app h3". At the moment, I'm just manually changing the
<h2>Mission</h2> to <h3>Mission</h3> for /index.html when updating the site.
I think it would be a good idea to release the CSS and site.vm as a
> skin (either on java.net, or we'd accept it at Apache) so that other
> java.net projects could use it out of the box.
Yep, that's my plan.
Btw, is there any support in site skinning to supply an additional Velocity
Macro template for special files that have fixed names and should only be
generated once for the whole project, rather than running the macro on every
file in the site?
For Java.Net a special file, called /project_tools.html is included at
runtime inside the Java.Net navigation bar on the left side of the website
for all pages. I'm using the following handwritten file on Java.Net - have
to make sure Maven gets some credit for the generated site. :-)
</div>
<div id="projecttools" class="toolgroup">
<div class="label"><strong>Project Reports</strong></div>
<div class="body">
<div><a href="dependencies.html">Dependencies</a></div>
<hr></hr>
<div>
<a href="http://maven.apache.org/"; title="Built by Maven" >
<img alt="Built by Maven" src="images/logos/maven-feather.png">
</a>
</div>
</div>
I would like to be able to dynamically generate the contents of this file,
so that all the Maven-generated reports can be linked automatically.
Many of the standard Maven reports are duplicates of the Java.Net ones added
in the chrome at runtime, so we'd need to be able to exclude the well-known
duplicates and capture the rest automatically.
It would be really great if all of this could actually be captured in a
single site skin.
Kind Regards,
John Fallows.
On 1/10/06, John Fallows <[EMAIL PROTECTED] > wrote:
> > Summary:
> >
> > I'm using the maven-site-plugin for Maven2 to generate the site
> > documentation for a Java.Net project and the APT parser is choking on
> the
> > syntax needed to get the desired look for the index page.
> >
> > org.codehaus.doxia.module.apt.AptParseException: expected SECTION1,
> found
> > SECTION2 at line 20
> >
> > Is there a workaround to let the parser continue?
> >
> >
> > Background:
> >
> > Java.Net sites and Maven-generated sites both want to own the chrome
> around
> > the content defined in the site documentation. Initially, I tried
> playing
> > around with some tricks to automatically redirect the standard
> > Java.Netindex page to the Maven generated index page, but then the
> > Java.Net styles were lost and the other Java.Net chrome, such as
> > breadcrumbs, tabs, and especially login, were also lost. Btw, before
> > figuring out how to turn off the Java.Net chrome (via /nonav in the URL)
> > there was chrome from both Java.Net and Maven in the site docs, which
> > definitely didn't look right. ;-)
> >
> > I finally settled on using a custom Velocity Macro template (see below)
> to
> > generate the Maven2 site in a much more plain way, such that upon
> inclusion
> > by Java.Net at runtime, all the styles would be picked up automatically,
> and
> > the Java.Net chrome could remain. Some of the menus in this chrome can
> be
> > customized by having a specially named file present in the web root, so
> I
> > plan to leverage that to include links for Maven-generated reports, and
> a
> > "Powered By" logo. Of course, it would be nice if that could be
> automated
> > during Maven2 site generation, but I haven't got that far yet, due to
> the
> > above APT parse error. :-)
> >
> > <html>
> > <head>
> > <title>$title</title>
> > <meta http-equiv="Content-Type" content="text/html;
> > charset=${outputEncoding}" />
> > </head>
> > <body>
> > <div class="app" >
> > $bodyContent
> > </div>
> > </body>
> > </html>
> >
> > -- java.net.vm
> >
> > In addition to controlling the chrome for all pages on the site,
> > Java.Netalso does something special with the index page. There is a
> > pre-defined
> > section at the top of the index page that includes the project name at
> <h2>,
> > and a "Description" title at <h3>.
> >
> > Therefore, my Maven2 index.apt file starts with indented text, to
> indicate
> > paragraph text for the description, which works just fine. However,
> when I
> > try to add a second "h3" title for the index page, say "Mission", using
> the
> > APT syntax for a sub-section, site generation breaks with an APT parsing
> > error, because the APT parser has no awareness of the project name
> "section"
> > title being managed by Java.Net at runtime. Therefore, it thinks I made
> a
> > mistake to have my first title be a subsection instead of a section, but
> I
> > really do need a subsection here.
> >
> > I realize that if the syntax for APT is relaxed too much, then many
> unwanted
> > errors would leak into site documentation. However, I wonder if there
> is
> > some value in keeping that strict default, but still being able to tell
> the
> > APT parser that a particular file has a different initial state (such as
>
> > after-subsection, instead of before-section) and then let the strict
> rules
> > continue in that specific context?
> >
> > Kind Regards,
> > John Fallows
> >
> > --
> > Author Pro JSF and Ajax: Building Rich Internet Components
> > http://www.apress.com/book/bookDisplay.html?bID=10044
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
>
--
Author Pro JSF and Ajax: Building Rich Internet Components
http://www.apress.com/book/bookDisplay.html?bID=10044
