You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Wendy Smoak <ja...@wendysmoak.com> on 2005/08/09 09:28:51 UTC
Struts website
In keeping with the Maven-or-Ant thread, it's time to think about switching
to the Maven-generated multi-project website. James has had the "basic"
Maven-generated site available for a while now with the nightly builds.
I made a start on integrating the existing site with Maven's, and posted the
first draft here (also beside the nightly builds):
http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
For now all the menus are expanded so you can see what's there. The menu
structure and navigation are still under construction. :)
This involved copying the existing xml files from
/current/core/doc/ into /current/build/xdocs/, renaming the project.xml
files to navigation.xml, and doing some cleanup. So, other than it being in
a different location in the repository, nothing changes about the way you
modify the documentation, and none of the links from other sites to ours
will be broken.
The main motivation for this was the realization that even if I update the
existing site, I have no idea what to do about the half-dozen sets of
JavaDoc. Maintaining an index page and copying the JavaDoc out of each
sub-project isn't appealing, especially not when Maven will take care of it
for you.
The 'multiproject' part of the site is towards the bottom of the menu, under
'Projects'. For example, here is the Project Reports section for Struts
Core:
http://svn.apache.org/builds/struts/maven/trunk/site-test/multiproject/struts-core/maven-reports.html
(And yes, I realize there's currently no way to get back to the main site
from here.)
What do you think? Should this eventually become the "official" Struts
site?
--
Wendy Smoak
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "Martin Cooper" <mf...@gmail.com>
> Another thing I was trying to tackle - which, in retrospect, was much
> too big to do in one chunk, let alone with everything else too - was
> creating a completely generic "main site" that hands off to the
> sub-project sites, where the main site doesn't get into the details of
> 'classic' or 'core' or anything like that.
What I see happening is to first get the existing site integrated with the
Maven-generated site, (which I'm working on,) then start pushing content out
of /build/xdocs/ into the xdocs directory of whatever sub-project it belongs
to.
One of my concerns is to _not_ break links into the site. I've posted
http://struts.apache.org/mail.html in a great many places, and I'd like for
the links in all those archived Usenet and mailing list posts to still work.
Like you, I thought that trying to reorganize everything all at once was too
much to tackle, and that things would probably get missed.
--
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Craig McClanahan <cr...@gmail.com>.
On 8/9/05, Joe Germuska <Jo...@germuska.com> wrote:
> >I do have the same question as James, though: Can we still generate
> >the TLDs from the same XML as the taglib docs? This is one place that
> >I got bogged down, since it seemed that Maven wouldn't take the extra
> >XML elements, and I would absolutely hate to lose the guaranteed
> >synchronisation we get from using the same source. The best I could
> >come up with was keeping the XML format we have, and using XSLT in a a
> >pre-goal to morph it into what Maven likes. However, if what you've
> >got works already, that would be excellent!
>
> We could consider using taglibdoc instead of our homegrown process.
> With taglibdoc, the TLD files themselves become the primary source,
> and the doc is generated, instead of vice-versa. There is a Maven
> plugin for this.
>
> Given how many attributes have accreted around our different HTML
> tags, I kind of prefer the frameset/javadoc style of taglibdoc. I
> played around with generating the doc from our own generated TLDs a
> while back, and I was reasonably satisfied. Looks like I still have
> the (possibly out of date) doc here:
>
> http://people.apache.org/~germuska/struts-taglib/docs/tlddoc/index.html
>
This style is certainly easier to navigate ... but we might want to
lobby the taglibrarydoc folks (if they're still around -- it's on
java.net) to support a way to mark tags and attributes as deprecated,
as we manufactured in our own approach.
The other thing to note is that taglibrarydoc also supports embedded
HTML in descriptions (as long as it's well formed and included in a
CDATA section, so you can make that part even more readable.
Craig
> If we plugged this in, it would appear under the project reports, as
> you can see here:
> http://people.apache.org/~germuska/struts-taglib/docs/maven-reports.html
>
> I just noticed that in Wendy's generated docs at svn.apache.org, all
> the "projects" come far below the "subprojects" in the navigation;
> that might not be the clearest...
>
> Joe
>
>
> --
> Joe Germuska
> Joe@Germuska.com
> http://blog.germuska.com
> "Narrow minds are weapons made for mass destruction" -The Ex
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Joe Germuska <Jo...@Germuska.com>.
>I do have the same question as James, though: Can we still generate
>the TLDs from the same XML as the taglib docs? This is one place that
>I got bogged down, since it seemed that Maven wouldn't take the extra
>XML elements, and I would absolutely hate to lose the guaranteed
>synchronisation we get from using the same source. The best I could
>come up with was keeping the XML format we have, and using XSLT in a a
>pre-goal to morph it into what Maven likes. However, if what you've
>got works already, that would be excellent!
We could consider using taglibdoc instead of our homegrown process.
With taglibdoc, the TLD files themselves become the primary source,
and the doc is generated, instead of vice-versa. There is a Maven
plugin for this.
Given how many attributes have accreted around our different HTML
tags, I kind of prefer the frameset/javadoc style of taglibdoc. I
played around with generating the doc from our own generated TLDs a
while back, and I was reasonably satisfied. Looks like I still have
the (possibly out of date) doc here:
http://people.apache.org/~germuska/struts-taglib/docs/tlddoc/index.html
If we plugged this in, it would appear under the project reports, as
you can see here:
http://people.apache.org/~germuska/struts-taglib/docs/maven-reports.html
I just noticed that in Wendy's generated docs at svn.apache.org, all
the "projects" come far below the "subprojects" in the navigation;
that might not be the clearest...
Joe
--
Joe Germuska
Joe@Germuska.com
http://blog.germuska.com
"Narrow minds are weapons made for mass destruction" -The Ex
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Martin Cooper <mf...@gmail.com>.
Good stuff! I was fiddling around with trying to generate the site
with Maven a while ago, but I think I was trying to kill too many
birds with the same stone, so to speak. Tackling it as you have seems
like a more expedient approach.
I do have the same question as James, though: Can we still generate
the TLDs from the same XML as the taglib docs? This is one place that
I got bogged down, since it seemed that Maven wouldn't take the extra
XML elements, and I would absolutely hate to lose the guaranteed
synchronisation we get from using the same source. The best I could
come up with was keeping the XML format we have, and using XSLT in a a
pre-goal to morph it into what Maven likes. However, if what you've
got works already, that would be excellent!
Another thing I was trying to tackle - which, in retrospect, was much
too big to do in one chunk, let alone with everything else too - was
creating a completely generic "main site" that hands off to the
sub-project sites, where the main site doesn't get into the details of
'classic' or 'core' or anything like that.
Finally, I'd like to see us make a conscious separation between
documentation and web site, and have the documentation be separate
downloads (_not_ as a war file) available in a number of formats -
minimally HTML and PDF.
Lots of lofty goals, I know, but that's what I'd ultimately like to
see. That's not to lessen at all the great start you've got us off to,
Wendy. Thanks!
--
Martin Cooper
On 8/9/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> In keeping with the Maven-or-Ant thread, it's time to think about switching
> to the Maven-generated multi-project website. James has had the "basic"
> Maven-generated site available for a while now with the nightly builds.
>
> I made a start on integrating the existing site with Maven's, and posted the
> first draft here (also beside the nightly builds):
>
> http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
>
> For now all the menus are expanded so you can see what's there. The menu
> structure and navigation are still under construction. :)
>
> This involved copying the existing xml files from
> /current/core/doc/ into /current/build/xdocs/, renaming the project.xml
> files to navigation.xml, and doing some cleanup. So, other than it being in
> a different location in the repository, nothing changes about the way you
> modify the documentation, and none of the links from other sites to ours
> will be broken.
>
> The main motivation for this was the realization that even if I update the
> existing site, I have no idea what to do about the half-dozen sets of
> JavaDoc. Maintaining an index page and copying the JavaDoc out of each
> sub-project isn't appealing, especially not when Maven will take care of it
> for you.
>
> The 'multiproject' part of the site is towards the bottom of the menu, under
> 'Projects'. For example, here is the Project Reports section for Struts
> Core:
> http://svn.apache.org/builds/struts/maven/trunk/site-test/multiproject/struts-core/maven-reports.html
> (And yes, I realize there's currently no way to get back to the main site
> from here.)
>
> What do you think? Should this eventually become the "official" Struts
> site?
>
> --
> Wendy Smoak
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Craig McClanahan <cr...@gmail.com>.
On 8/9/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> In keeping with the Maven-or-Ant thread, it's time to think about switching
> to the Maven-generated multi-project website. James has had the "basic"
> Maven-generated site available for a while now with the nightly builds.
>
> I made a start on integrating the existing site with Maven's, and posted the
> first draft here (also beside the nightly builds):
>
> http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
>
> For now all the menus are expanded so you can see what's there. The menu
> structure and navigation are still under construction. :)
Looks nice. I hope the multiproject stuff will allow subprojects to
independently update their own chunks of the overall site
independently, right?
Regarding navigation, what needs to change to get the
subproject-specific navigation bars included?
Craig
>
> This involved copying the existing xml files from
> /current/core/doc/ into /current/build/xdocs/, renaming the project.xml
> files to navigation.xml, and doing some cleanup. So, other than it being in
> a different location in the repository, nothing changes about the way you
> modify the documentation, and none of the links from other sites to ours
> will be broken.
>
> The main motivation for this was the realization that even if I update the
> existing site, I have no idea what to do about the half-dozen sets of
> JavaDoc. Maintaining an index page and copying the JavaDoc out of each
> sub-project isn't appealing, especially not when Maven will take care of it
> for you.
>
> The 'multiproject' part of the site is towards the bottom of the menu, under
> 'Projects'. For example, here is the Project Reports section for Struts
> Core:
> http://svn.apache.org/builds/struts/maven/trunk/site-test/multiproject/struts-core/maven-reports.html
> (And yes, I realize there's currently no way to get back to the main site
> from here.)
>
> What do you think? Should this eventually become the "official" Struts
> site?
>
> --
> Wendy Smoak
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Don Brown <mr...@twdata.org>.
Very nice! The only thing I noticed is could the author, see also, etc.
metadata for a document be placed at the bottom instead of the top? Now
that we are rendering that, I'll need to go clean it up :)
Thanks again!
Don
Wendy Smoak wrote:
> Thanks for all the feedback and suggestions for the new site. Here's a
> second draft, incorporating as many of the suggestions as I could get to:
>
> http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
>
> - Navigation to subprojects is now consolidated near the top of the menu.
> - If a subproject has a directory on the existing site, (bsf, flow, shale,)
> the link goes to that documentation.
> - If there is no existing documentation (sandbox, etc.) then the link goes
> to the Maven-generated page.
> - The 'Overview' at the top of the Projects menu lists all of the
> Maven-generated pages, so they are all accessible.
> - The subprojects are directly under the root of the website (not under a
> directory called 'multiproject' any longer.)
>
> I have not yet had time to look at the taglib documentation so that's still
> missing.
>
> I'll do something to get the JavaDoc back into the 'Documentation' menu--
> probably just a page that links to the Javadoc for each subproject. (Maven
> puts
> the links under Project Reports -> JavaDoc for each subproject.)
>
> Ted wrote:
>
>> * The Download links could point to anchors on the Acquiring page, to
>> provide a single gateway.
>
>
> I changed the download links to point to the Acquiring page. The anchors,
> however, are a problem.
>
> Maven links to http://jakarta.apache.org/site/jakarta-site2.html as the
> accepted structure for the xml docs. And that includes neither the 'href'
> attribute that we're using to render anchors, nor the <chapter> tag that
> appears in the userGuide docs.
>
> The XSLT is using the 'name' attribute as both the text for the section
> headers _and_ the anchor name, and is ignoring the 'href' attribute
> entirely.
>
> The <chapter> tags are also ignored. I changed them to empty <section>
> tags
> to get the text to appear. Unless <chapter> is important for some reason
> I'm not aware of, (docbook?) those can probably be changed to
> section/subsection tags.
>
> Getting the anchors to work like they used to is probably going to require
> modifying the XSL stylesheet
> (.maven\cache\maven-xdoc-plugin-1.9.1\plugin-resources\site.jsl) and
> setting
> a property to tell Maven to use our stylesheet.
>
> I'm keeping notes on the site conversion here for now:
> http://wiki.wsmoak.net/cgi-bin/wiki.pl?MavenMultiProjectSite
>
> I will post a site conversion plan on the Struts Wiki tonight. I'm
> planning
> to do the initial copy from core/docs to build/xdocs in the repository no
> earlier than Friday night.
>
> Thanks,
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Martin Cooper <mf...@gmail.com>.
On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> From: "Martin Cooper" <mf...@gmail.com>
>
> >> Are there any objections to having 'site' or 'website' as a new
> >> sub-project?
>
> > None at all. As Ted mentioned, that was the original plan. :-)
>
> NOW you tell me. ;) As you probably saw, James set up the new directory in
> the repository.
>
> I'm not sure how to do to the copy and make sure the revision history stays
> with the files. Will just copying it locally and checking it in work (with
> the Tortoise svn client)? Everything in /current/core/doc needs to go in
> /current/site/xdocs.
I would recommend using 'svn move <url1> <url2>', which will do
everything on the server, very quickly and retaining the history. See:
http://svnbook.red-bean.com/en/1.1/svn-book.html#svn-ch-9-sect-1.2-re-move
--
Martin Cooper
> > One thing I especially like about the Maven format is the <source>
> > element, which makes chunks of source code look much nicer than we
> > have them now.
>
> The Maven format is actually the Jakarta format:
> http://jakarta.apache.org/site/jakarta-site2.html (Which I actually thought
> Struts was following, just with additions. In any case, that's what the
> User Guide documentation is going to be converted to.)
>
> Thanks,
> Wendy
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
On the topic of anchors, I changed my mind. Again. I had originally
planned to preserve as many URLs as possible, including the anchor names.
But then I decided to just go with whatever Maven came up with, which is the
text of the section name with spaces and special characters replaced by
underscores.
And the anchors kept getting longer, and longer... until I got to the
'helping' and 'kickstart' pages, at which point I just couldn't deal with
having an anchor that looks like this:
kickstart.html#What_s_the_difference_between_Struts_and_Turbine__What_s_the_difference_between_Struts_and_Expresso_
So I'm switching back to the first idea and adding <a name="anchor-name"/>
above the <section> and <subsection> tags that used to have 'href'
attributes. It's mixed at the moment, but I'll go back through and clean it
up eventually.
--
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Ted Husted <te...@gmail.com>.
On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> From: "Martin Cooper" <mf...@gmail.com>
>
> >> Are there any objections to having 'site' or 'website' as a new
> >> sub-project?
>
> > None at all. As Ted mentioned, that was the original plan. :-)
>
> NOW you tell me. ;)
Sorry about that. The bit about "site" was on display in the bottom of
a locked filing cabinet stuck in a disused lavatory with a sign on the
door saying 'Beware of the Leopard.' "
* http://struts.apache.org/milestones.html#struts_1_3_x
:)
-Ted.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "Martin Cooper" <mf...@gmail.com>
>> Are there any objections to having 'site' or 'website' as a new
>> sub-project?
> None at all. As Ted mentioned, that was the original plan. :-)
NOW you tell me. ;) As you probably saw, James set up the new directory in
the repository.
I'm not sure how to do to the copy and make sure the revision history stays
with the files. Will just copying it locally and checking it in work (with
the Tortoise svn client)? Everything in /current/core/doc needs to go in
/current/site/xdocs.
> One thing I especially like about the Maven format is the <source>
> element, which makes chunks of source code look much nicer than we
> have them now.
The Maven format is actually the Jakarta format:
http://jakarta.apache.org/site/jakarta-site2.html (Which I actually thought
Struts was following, just with additions. In any case, that's what the
User Guide documentation is going to be converted to.)
Thanks,
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Martin Cooper <mf...@gmail.com>.
On 8/11/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> From: "Wendy Smoak" <ja...@wendysmoak.com>
> > One remaining concern about the website conversion: If I copy the files
> > into build/xdocs, what happens when someone checks out struts/current and
> > gets the 'build' directory within every subproject? I have a feeling it's
> > going to retrieve all that documentation a dozen times, once for each
> > subproject, but maybe Subversion clients are smarter than that.
> > Otherwise, can subversion be configured to exclude the 'xdocs' directory?
>
> (I'm really not talking to myself-- James IM'd right after I posted the
> message above to confirm that this is a legitimate issue.)
>
> When I asked a question recently on maven-user, they suggested having a
> separate sub-project for the website. That didn't initially work for me
> because if you run 'maven multiproject:site' from /struts/current/build, it
> sees the 'website' directory as just another sub-project and puts the
> documentation under struts.apache.org/website-- breaking every link into the
> Struts site.
>
> However, having a separate sub-project for the website and building the site
> _from there_ works. I now have struts/current/site containing the 'xdocs'
> directory with all of the xml (and other) files from the existing site, and
> executing 'maven multiproject:site' from struts/current/site does the right
> thing.
>
> Having a separate sub-project for the site also helps with the goal of
> clearly separating the website from the project documentation.
>
> Are there any objections to having 'site' or 'website' as a new sub-project?
None at all. As Ted mentioned, that was the original plan. :-)
--
Martin Cooper
> Thanks,
> Wendy
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Martin Cooper <mf...@gmail.com>.
On 8/12/05, Sean Schofield <se...@gmail.com> wrote:
> Quick related question about the website. Are the xdocs used by
> forrest compatible with the xdocs used by Maven? If not, do you know
> what portion of them can be salvaged if any?
I have no idea how the two xdocs formats relate to each other, but
just wanted to point out that the existing Struts site uses neither.
;-)
--
Martin Cooper
> TIA,
>
> sean
>
> ps. I'm not trying to reopen the maven discussion here, just looking
> for some info on how the website is generated ;-)
>
>
> On 8/12/05, Ted Husted <te...@gmail.com> wrote:
> > On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> > > Are there any objections to having 'site' or 'website' as a new sub-project?
> >
> > I believe we may have contemplated that from the beginning. Site was
> > to be our "seventh dwarf", along with Apps, Core, EL, Plugins,
> > Taglibs, and Tiles. :)
> >
> > We left the top-level site docs in with Core as a stepping stone,
> > until we could get to where you are now (thanks ever so much!)
> >
> > -Ted.
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> > For additional commands, e-mail: dev-help@struts.apache.org
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Craig McClanahan <cr...@gmail.com>.
On 8/12/05, Martin Cooper <mf...@gmail.com> wrote:
>
> I would say just remove the <chapter> tags. When I was messing around
> with this a few months ago, that's what I did, and everything else
> seemed to work out just fine. I have no concerns about any limitations
> of the Maven format if we're going to use a different means to
> generate the taglib docs.
>
+1 ... IIRC we originally modelled our stylesheets after what Anakia
was doing, but there's no reason not to conform to the tags that go
with whatever generation technology we end up with.
Craig
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Martin Cooper <mf...@gmail.com>.
On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> From: "Ted Husted" <te...@gmail.com>
>
> > I've done some work in DocBook, and it's not so bad, expecially since
> > there are some editors out there, like XML Mind.
> >
> > I don't suppose just plain-old XHTML is an option?
>
> You want to maintain the actual HTML with the <h1> <h2> and <div
> class="indent"> tags rather than running XML with <section> and <subsection>
> through XSLT?
Ew, no thanks. That would be a big backwards step, IMO.
> I have to do something with the userGuide-- either remove the <chapter> tags
> or else use something other than 'maven site' to transform it to HTML.
I would say just remove the <chapter> tags. When I was messing around
with this a few months ago, that's what I did, and everything else
seemed to work out just fine. I have no concerns about any limitations
of the Maven format if we're going to use a different means to
generate the taglib docs.
One thing I especially like about the Maven format is the <source>
element, which makes chunks of source code look much nicer than we
have them now.
--
Martin Cooper
> Using some other format and some other transformation is also an option,
> though probably not by Monday. :)
>
> > My own personal favorite for technical writing is Textile, which
> > Confluence uses.
> > * http://textism.com/tools/textile/
> > (I *so* love writing technical documentation in Confluence/Textile.)
> > But, I don't expect that Textile is an option right now :(
>
> I don't see a download link on that page, only on
> http://www.textpattern.com/. Is there more information somewhere? If I
> have a text file in that format... how do I convert it to XHTML?
>
> --
> Wendy
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "Ted Husted" <te...@gmail.com>
> I've done some work in DocBook, and it's not so bad, expecially since
> there are some editors out there, like XML Mind.
>
> I don't suppose just plain-old XHTML is an option?
You want to maintain the actual HTML with the <h1> <h2> and <div
class="indent"> tags rather than running XML with <section> and <subsection>
through XSLT?
I have to do something with the userGuide-- either remove the <chapter> tags
or else use something other than 'maven site' to transform it to HTML.
Using some other format and some other transformation is also an option,
though probably not by Monday. :)
> My own personal favorite for technical writing is Textile, which
> Confluence uses.
> * http://textism.com/tools/textile/
> (I *so* love writing technical documentation in Confluence/Textile.)
> But, I don't expect that Textile is an option right now :(
I don't see a download link on that page, only on
http://www.textpattern.com/. Is there more information somewhere? If I
have a text file in that format... how do I convert it to XHTML?
--
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Ted Husted <te...@gmail.com>.
On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> From: "Sean Schofield" <se...@gmail.com>
>I'm trying to avoid having
> to maintain a custom stylesheet, and looking at options such as DocBook to
> generate some of the docs. (The User Guide in particular already has
> <chapter> tags in it-- I think it might have been intended for DocBook from
> the beginning.)
I think we may have pickedup the chapters style from someone else, who
may or may not adopted the idea from DocBook, but that was so long ago
now, it wouldn't matter.
I've done some work in DocBook, and it's not so bad, expecially since
there are some editors out there, like XML Mind.
I don't suppose just plain-old XHTML is an option?
My own personal favorite for technical writing is Textile, which
Confluence uses.
* http://textism.com/tools/textile/
(I *so* love writing technical documentation in Confluence/Textile.)
But, I don't expect that Textile is an option right now :(
-Ted.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "Sean Schofield" <se...@gmail.com>
> Quick related question about the website. Are the xdocs used by
> forrest compatible with the xdocs used by Maven? If not, do you know
> what portion of them can be salvaged if any?
Maven's 'multiproject:site' goal uses the Jakarta xdocs format:
http://jakarta.apache.org/site/jakarta-site2.html. The set of tags is very
limited, and Struts had already gone beyond it and added extra attributes
and tags to the custom stylesheet we were using. I'm trying to avoid having
to maintain a custom stylesheet, and looking at options such as DocBook to
generate some of the docs. (The User Guide in particular already has
<chapter> tags in it-- I think it might have been intended for DocBook from
the beginning.)
Google turned up the Forrest version 0.7 release announcement, which led to
this page about running Forrest from Maven:
http://forrest.apache.org/docs_0_70/howto/howto-forrest-from-maven.html
I'm sure there will eventually be a "Maven Forrest Plugin" if there isn't
already. :)
HTH,
--
Wendy Smoak
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Sean Schofield <se...@gmail.com>.
Quick related question about the website. Are the xdocs used by
forrest compatible with the xdocs used by Maven? If not, do you know
what portion of them can be salvaged if any?
TIA,
sean
ps. I'm not trying to reopen the maven discussion here, just looking
for some info on how the website is generated ;-)
On 8/12/05, Ted Husted <te...@gmail.com> wrote:
> On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> > Are there any objections to having 'site' or 'website' as a new sub-project?
>
> I believe we may have contemplated that from the beginning. Site was
> to be our "seventh dwarf", along with Apps, Core, EL, Plugins,
> Taglibs, and Tiles. :)
>
> We left the top-level site docs in with Core as a stepping stone,
> until we could get to where you are now (thanks ever so much!)
>
> -Ted.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Ted Husted <te...@gmail.com>.
On 8/12/05, Wendy Smoak <ja...@wendysmoak.com> wrote:
> Are there any objections to having 'site' or 'website' as a new sub-project?
I believe we may have contemplated that from the beginning. Site was
to be our "seventh dwarf", along with Apps, Core, EL, Plugins,
Taglibs, and Tiles. :)
We left the top-level site docs in with Core as a stepping stone,
until we could get to where you are now (thanks ever so much!)
-Ted.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "Wendy Smoak" <ja...@wendysmoak.com>
> One remaining concern about the website conversion: If I copy the files
> into build/xdocs, what happens when someone checks out struts/current and
> gets the 'build' directory within every subproject? I have a feeling it's
> going to retrieve all that documentation a dozen times, once for each
> subproject, but maybe Subversion clients are smarter than that.
> Otherwise, can subversion be configured to exclude the 'xdocs' directory?
(I'm really not talking to myself-- James IM'd right after I posted the
message above to confirm that this is a legitimate issue.)
When I asked a question recently on maven-user, they suggested having a
separate sub-project for the website. That didn't initially work for me
because if you run 'maven multiproject:site' from /struts/current/build, it
sees the 'website' directory as just another sub-project and puts the
documentation under struts.apache.org/website-- breaking every link into the
Struts site.
However, having a separate sub-project for the website and building the site
_from there_ works. I now have struts/current/site containing the 'xdocs'
directory with all of the xml (and other) files from the existing site, and
executing 'maven multiproject:site' from struts/current/site does the right
thing.
Having a separate sub-project for the site also helps with the goal of
clearly separating the website from the project documentation.
Are there any objections to having 'site' or 'website' as a new sub-project?
Thanks,
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
One remaining concern about the website conversion: If I copy the files
into build/xdocs, what happens when someone checks out struts/current and
gets the 'build' directory within every subproject? I have a feeling it's
going to retrieve all that documentation a dozen times, once for each
subproject, but maybe Subversion clients are smarter than that. Otherwise,
can subversion be configured to exclude the 'xdocs' directory?
Thanks,
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by David Geary <sa...@earthlink.net>.
Excellent work, Wendy. I know you've done a great deal of work
on this and we all appreciate it. Even if you are using Maven.
david
Le 05-08-11 à 07:25, Wendy Smoak a écrit :
> Thanks for all the feedback and suggestions for the new site.
> Here's a
> second draft, incorporating as many of the suggestions as I could
> get to:
>
> http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
>
> - Navigation to subprojects is now consolidated near the top of the
> menu.
> - If a subproject has a directory on the existing site, (bsf, flow,
> shale,)
> the link goes to that documentation.
> - If there is no existing documentation (sandbox, etc.) then the
> link goes
> to the Maven-generated page.
> - The 'Overview' at the top of the Projects menu lists all of the
> Maven-generated pages, so they are all accessible.
> - The subprojects are directly under the root of the website (not
> under a
> directory called 'multiproject' any longer.)
>
> I have not yet had time to look at the taglib documentation so
> that's still
> missing.
>
> I'll do something to get the JavaDoc back into the 'Documentation'
> menu--
> probably just a page that links to the Javadoc for each
> subproject. (Maven
> puts
> the links under Project Reports -> JavaDoc for each subproject.)
>
> Ted wrote:
>
>> * The Download links could point to anchors on the Acquiring page, to
>> provide a single gateway.
>>
>
> I changed the download links to point to the Acquiring page. The
> anchors,
> however, are a problem.
>
> Maven links to http://jakarta.apache.org/site/jakarta-site2.html as
> the
> accepted structure for the xml docs. And that includes neither the
> 'href'
> attribute that we're using to render anchors, nor the <chapter> tag
> that
> appears in the userGuide docs.
>
> The XSLT is using the 'name' attribute as both the text for the
> section
> headers _and_ the anchor name, and is ignoring the 'href' attribute
> entirely.
>
> The <chapter> tags are also ignored. I changed them to empty
> <section> tags
> to get the text to appear. Unless <chapter> is important for some
> reason
> I'm not aware of, (docbook?) those can probably be changed to
> section/subsection tags.
>
> Getting the anchors to work like they used to is probably going to
> require
> modifying the XSL stylesheet
> (.maven\cache\maven-xdoc-plugin-1.9.1\plugin-resources\site.jsl)
> and setting
> a property to tell Maven to use our stylesheet.
>
> I'm keeping notes on the site conversion here for now:
> http://wiki.wsmoak.net/cgi-bin/wiki.pl?MavenMultiProjectSite
>
> I will post a site conversion plan on the Struts Wiki tonight. I'm
> planning
> to do the initial copy from core/docs to build/xdocs in the
> repository no
> earlier than Friday night.
>
> Thanks,
> --
> Wendy
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
Thanks for all the feedback and suggestions for the new site. Here's a
second draft, incorporating as many of the suggestions as I could get to:
http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
- Navigation to subprojects is now consolidated near the top of the menu.
- If a subproject has a directory on the existing site, (bsf, flow, shale,)
the link goes to that documentation.
- If there is no existing documentation (sandbox, etc.) then the link goes
to the Maven-generated page.
- The 'Overview' at the top of the Projects menu lists all of the
Maven-generated pages, so they are all accessible.
- The subprojects are directly under the root of the website (not under a
directory called 'multiproject' any longer.)
I have not yet had time to look at the taglib documentation so that's still
missing.
I'll do something to get the JavaDoc back into the 'Documentation' menu--
probably just a page that links to the Javadoc for each subproject. (Maven
puts
the links under Project Reports -> JavaDoc for each subproject.)
Ted wrote:
> * The Download links could point to anchors on the Acquiring page, to
> provide a single gateway.
I changed the download links to point to the Acquiring page. The anchors,
however, are a problem.
Maven links to http://jakarta.apache.org/site/jakarta-site2.html as the
accepted structure for the xml docs. And that includes neither the 'href'
attribute that we're using to render anchors, nor the <chapter> tag that
appears in the userGuide docs.
The XSLT is using the 'name' attribute as both the text for the section
headers _and_ the anchor name, and is ignoring the 'href' attribute
entirely.
The <chapter> tags are also ignored. I changed them to empty <section> tags
to get the text to appear. Unless <chapter> is important for some reason
I'm not aware of, (docbook?) those can probably be changed to
section/subsection tags.
Getting the anchors to work like they used to is probably going to require
modifying the XSL stylesheet
(.maven\cache\maven-xdoc-plugin-1.9.1\plugin-resources\site.jsl) and setting
a property to tell Maven to use our stylesheet.
I'm keeping notes on the site conversion here for now:
http://wiki.wsmoak.net/cgi-bin/wiki.pl?MavenMultiProjectSite
I will post a site conversion plan on the Struts Wiki tonight. I'm planning
to do the initial copy from core/docs to build/xdocs in the repository no
earlier than Friday night.
Thanks,
--
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Ted Husted <te...@gmail.com>.
+1 for me to.
A few notes might be:
* The Download links could point to anchors on the Acquiring page, to
provide a single gateway.
* In the end, I expect we would have a single Subprojects or Projects
section, instead of two. For subproject labels, I would suggest
dropping "Struts" as understood:
+ Applications
+ BSF Scripting
+ Core
+ EL
+ Flow
+ JavaServer Faces
+ JSF Integration
+ Plugins
+ Sandbox
+ Shale Framework
+ Taglibs
+ Tiles
* At some point, we should move all the documentation under the
subprojects. Taglibs would get the Developer Guides, and most of the
rest would go under Core, the notable exception being the SSL Howto.
As Craig mentioned, ultimately each subproject should build and
maintain its own website.
* As Martin indicated, we should start to revamp the site generally
so that there is a clear separation between Struts the project and the
products of the project. The current Acquiring and Learning pages
could go under Core and replaced with generic versions that included
the other subprojects.
But, if we can at least do the first two things, and sorted out the
TLD business (as Joe mentioned, it's time we moved away from our
homegrown approach), I think we should be able to go with this for
Struts 1.3.0.
-Ted.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Hubert Rabago <hr...@gmail.com>.
Agreed, this looks great! Not knowing much about Maven, I wasn't sure
what would happen to the user guide and other such docs. Now I see I
don't need to worry about those. Good work!
Hubert
On 8/9/05, James Mitchell <jm...@apache.org> wrote:
> Thanks for all the hard work Wendy. This looks great!
>
> Do you know how that affects the generation of the tld files? Or is it a
> non-issue (meaning that hasn't changed)
>
> I am +1 for moving over to this approach. My +1 also means that I am
> willing to help (which I guess I sort of already have ;)
>
>
> --
> James Mitchell
> Software Engineer / Open Source Evangelist
> Consulting / Mentoring / Freelance
> EdgeTech, Inc.
> http://www.edgetechservices.net/
> 678.910.8017
> AIM: jmitchtx
> MSN: jmitchell@apache.org
> Skype: jmitchtx
>
> ----- Original Message -----
> From: "Wendy Smoak" <ja...@wendysmoak.com>
> To: "Struts Developers List" <de...@struts.apache.org>
> Sent: Tuesday, August 09, 2005 3:28 AM
> Subject: Struts website
>
>
> > In keeping with the Maven-or-Ant thread, it's time to think about
> > switching
> > to the Maven-generated multi-project website. James has had the "basic"
> > Maven-generated site available for a while now with the nightly builds.
> >
> > I made a start on integrating the existing site with Maven's, and posted
> > the
> > first draft here (also beside the nightly builds):
> >
> > http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
> >
> > For now all the menus are expanded so you can see what's there. The menu
> > structure and navigation are still under construction. :)
> >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "James Mitchell" <jm...@apache.org>
> Do you know how that affects the generation of the tld files? Or is it a
> non-issue (meaning that hasn't changed)
I don't know yet. I noticed that the html taglib docs are missing from the
test site, and it's on the list to check out. (The tlds have to be getting
generated... they're in struts-taglib-1.3.0-dev.jar. Then it should just be
a matter of generating the HTML from the same source and linking to it.)
> I am +1 for moving over to this approach. My +1 also means that I am
> willing to help (which I guess I sort of already have ;)
Yes, and THANK YOU for all the time you've spent on email and IM helping me
figure out how Maven does what it does. I doubt I could have gotten up to
speed this quickly without your help.
--
Wendy
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Struts website
Posted by James Mitchell <jm...@apache.org>.
Thanks for all the hard work Wendy. This looks great!
Do you know how that affects the generation of the tld files? Or is it a
non-issue (meaning that hasn't changed)
I am +1 for moving over to this approach. My +1 also means that I am
willing to help (which I guess I sort of already have ;)
--
James Mitchell
Software Engineer / Open Source Evangelist
Consulting / Mentoring / Freelance
EdgeTech, Inc.
http://www.edgetechservices.net/
678.910.8017
AIM: jmitchtx
MSN: jmitchell@apache.org
Skype: jmitchtx
----- Original Message -----
From: "Wendy Smoak" <ja...@wendysmoak.com>
To: "Struts Developers List" <de...@struts.apache.org>
Sent: Tuesday, August 09, 2005 3:28 AM
Subject: Struts website
> In keeping with the Maven-or-Ant thread, it's time to think about
> switching
> to the Maven-generated multi-project website. James has had the "basic"
> Maven-generated site available for a while now with the nightly builds.
>
> I made a start on integrating the existing site with Maven's, and posted
> the
> first draft here (also beside the nightly builds):
>
> http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html
>
> For now all the menus are expanded so you can see what's there. The menu
> structure and navigation are still under construction. :)
>
> This involved copying the existing xml files from
> /current/core/doc/ into /current/build/xdocs/, renaming the project.xml
> files to navigation.xml, and doing some cleanup. So, other than it being
> in
> a different location in the repository, nothing changes about the way you
> modify the documentation, and none of the links from other sites to ours
> will be broken.
>
> The main motivation for this was the realization that even if I update the
> existing site, I have no idea what to do about the half-dozen sets of
> JavaDoc. Maintaining an index page and copying the JavaDoc out of each
> sub-project isn't appealing, especially not when Maven will take care of
> it
> for you.
>
> The 'multiproject' part of the site is towards the bottom of the menu,
> under
> 'Projects'. For example, here is the Project Reports section for Struts
> Core:
>
> http://svn.apache.org/builds/struts/maven/trunk/site-test/multiproject/struts-core/maven-reports.html
> (And yes, I realize there's currently no way to get back to the main site
> from here.)
>
> What do you think? Should this eventually become the "official" Struts
> site?
>
> --
> Wendy Smoak
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org