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
