[html2xdoc] new plugin for including HTML documentation in the site

[James Strachan <ja...@yahoo.co.uk>]

Alot of documentation that ships with Java projects is based on fairly
simple markup using the most basic parts of HTML: Headings, bold, italic,
bullets, the odd table, images and links.

I find editing 'xdoc' format XML files quite painful for anything other than
fairly basic documentation. I far prefer to just edit some simple HTML
document in some WYSIWYG editing tool like Mozilla or MS FrontPage - its
just so much easier to do and less risky that a typo will break the build
etc.

So for WYSIWYG fans like me, there's a new little plugin called html2xdoc.
Basically this takes normal HTML and turns it into the xdoc format that the
xdoc plugin uses to generate the website. This means that you can now mix
and match normal HTML and XML xdoc format files together to generate the
website - users can't really tell them apart.

By default the goal 'html2xdoc' will take all HTMl documents in the xdocs
directory and turn them into xdoc files in the target/generated-xdocs
directory. A nice thing about this is that the HTML documents can link to
relative images in the xdocs/images directory while editing & when the build
is done. Also all the HTML and XML documentation is in the same directory.

To allow HTML to be turned into xdoc format add the following to your
maven.xml

  <preGoal name="xdoc:jelly-transform">
    <attainGoal name="html2xdoc"/>
  </preGoal>


A quick note about the implementation. The HTML is parsed via the Jelly HTML
parsing library (and NekoHTML that does the hard work). I did try implement
this plugin via JSL or XSLT but the logic seemed way to complex to get right
so I just used good old Java to implement the complex processing.

James
-------
http://radio.weblogs.com/0112098/

__________________________________________________
Do You Yahoo!?
Everything you'll ever need on one web page
from News and Sport to Email and Music Charts
http://uk.my.yahoo.com

Re: [html2xdoc] new plugin for including HTML documentation in the site

[Rafal Krzewski <Ra...@caltha.pl>]

Pete Kazmier wrote:

> How do you feel if we make the default src/html instead of the xdocs
> directory?  Or perhaps disable this processing by default?  I only
> suggest this due to the previous behavior Maven exhibited.  HTML files
> located in the xdocs directory were copied over unaltered to the docs
> directory enabling users to put unaltered content on their site.  I
> also recently expanded this such that any non-xdoc file is copied over
> directly.  This lets users included arbitrary types of files on their
> sites, including straight html, pdfs, microcrap stuff, etc.

As far as I know ${basedir}/xdoc location for documentation is in fact
a legacy from other Jakarta projects, and not a conscious design choice.

In my opinion, the documentation plugins should process files in the
respective directories under ${basedir}/src (/xdoc, /apt, /html)
and there should be documentationResources concept similar to build
resources and testResources, that would faciliate copying images, and
downloadable files into the target directory.

It would be nice to have a <documentation> tag in the POM where you
would *declare* what goes into your project documentation.

Some freehand typing:

<documentation>
 <reports>
  <default-reports/>
  <enable-report>customplugin</enable-report>
  <disable-report>junit</disable-report>
 </reports>
 <javadocs>
  <title>${pom.artifactId} API</title>
  <access>public</access>
  <packages>
   <includes>
    <include>**</include>
   </include>
   <excludes>
    <exclude>**.internal</exclude>
   </excludes>
  </packages>
 </javadocs>
 <javadocs>
  <title>${pom.artifactId} developers documention</title>
  <access>private</access>
  <packages>
   <includes>
    <include>**</include>
   </include>
  </includes>
 </javadocs>
 <documentationResources>
  <documentationResource>
   <directory>${basedir}/src/documentation-resources</directory>
   <includes>
    <include>**/*.png</include>
    <include>**/*.svg</include>
  </documenationResource>
 </documentaitonResources>
</documentation>

Paths processed by plugins could be overriden with project.properites,
so backward compatibility with projects' existing structure would be
easy to keep. New locations would become the recommendations for newly
created projects.

R.

Re: [html2xdoc] new plugin for including HTML documentation in the site

[James Strachan <ja...@yahoo.co.uk>]

From: "Pete Kazmier" <pe...@kazmier.com>
> >>>>> On Fri, 7 Mar 2003 07:37:32 -0000, "James Strachan" said:
> 
> James> This goal is not included in the xdoc goal or executed by
> James> default - so its completely optional. Its up to users who want
> James> to use this plugin to explicitly enable it. (Rather like Clover
> James> reports etc)
> 
> Ahh .. I should have looked a little closer before opening my big
> mouth.  Sorry for the confusion.

No problem :).  I should have been more clear.

James
-------
http://radio.weblogs.com/0112098/
__________________________________________________
Do You Yahoo!?
Everything you'll ever need on one web page
from News and Sport to Email and Music Charts
http://uk.my.yahoo.com

Re: [html2xdoc] new plugin for including HTML documentation in the site

[Pete Kazmier <pe...@kazmier.com>]

>>>>> On Fri, 7 Mar 2003 07:37:32 -0000, "James Strachan" said:

James> This goal is not included in the xdoc goal or executed by
James> default - so its completely optional. Its up to users who want
James> to use this plugin to explicitly enable it. (Rather like Clover
James> reports etc)

Ahh .. I should have looked a little closer before opening my big
mouth.  Sorry for the confusion.

Re: [html2xdoc] new plugin for including HTML documentation in the site

[James Strachan <ja...@yahoo.co.uk>]

 From: "Pete Kazmier" <pe...@kazmier.com>
> James> By default the goal 'html2xdoc' will take all HTMl documents in
> James> the xdocs directory and turn them into xdoc files in the
> James> target/generated-xdocs directory.
>
> How do you feel if we make the default src/html instead of the xdocs
> directory?  Or perhaps disable this processing by default?

This goal is not included in the xdoc goal or executed by default - so its
completely optional. Its up to users who want to use this plugin to
explicitly enable it. (Rather like Clover reports etc)


> I only
> suggest this due to the previous behavior Maven exhibited.  HTML files
> located in the xdocs directory were copied over unaltered to the docs
> directory enabling users to put unaltered content on their site.  I
> also recently expanded this such that any non-xdoc file is copied over
> directly.  This lets users included arbitrary types of files on their
> sites, including straight html, pdfs, microcrap stuff, etc.

The html2xdoc plugin can be customized to specify any source directory for
the HTML. It defaults to xdocs as this makes it easy to share images in the
HTML - though it'd be easy to use another directory if need be by setting a
property.

In many ways I see users as wanting either to copy HTML as-is to their site,
or formatting the HTML to include the nav bar, header and such like. Either
way, putting the HTML in the xdocs directory with a child images directory
seems the best approach. So its just up to the user to decide, do they leave
the default behaviour (copy files as is) or enable the html2xdoc plugin
which will format the HTML as if it were an xdoc file.

James
-------
http://radio.weblogs.com/0112098/

__________________________________________________
Do You Yahoo!?
Everything you'll ever need on one web page
from News and Sport to Email and Music Charts
http://uk.my.yahoo.com

Re: [html2xdoc] new plugin for including HTML documentation in the site

[Pete Kazmier <pe...@kazmier.com>]

>>>>> On Thu, 6 Mar 2003 19:14:28 -0000, "James Strachan" <ja...@yahoo.co.uk> said:

James> So for WYSIWYG fans like me, there's a new little plugin called
James> html2xdoc.  Basically this takes normal HTML and turns it into
James> the xdoc format that the xdoc plugin uses to generate the
James> website.

Cool.

James> By default the goal 'html2xdoc' will take all HTMl documents in
James> the xdocs directory and turn them into xdoc files in the
James> target/generated-xdocs directory.

How do you feel if we make the default src/html instead of the xdocs
directory?  Or perhaps disable this processing by default?  I only
suggest this due to the previous behavior Maven exhibited.  HTML files
located in the xdocs directory were copied over unaltered to the docs
directory enabling users to put unaltered content on their site.  I
also recently expanded this such that any non-xdoc file is copied over
directly.  This lets users included arbitrary types of files on their
sites, including straight html, pdfs, microcrap stuff, etc.