Add default stylesheet and attribute support

[benevans]

This should fix #19, providing default stylesheets that render Asciidoctor output more nicely than the default.

• There are two new stylesheets, based on Java 8 and Java 6 javadoc stylesheets, with additions from Asciidoctor's default stylesheet. These also work fine on Java 7 and 1.5 javadoc output. The doclet detects the Java version and copies the appropriate stylesheet to the output directory, if no user stylesheet was specified.
• Added the -attributes option, so that users can pass document attributes to Asciidoctor.
• Added some documentation to the README on the new options and also an Ant example.

[benevans]

Note there's a potential issue with the -attributes option I added. It uses semicolon to separate the attributes, e.g. -attributes "version=1.0; foo=bar". I tried using comma (like Asciidoctor) but unfortunately the Maven javadoc plugin automatically splits its <additionalparam> value on comma, before passing it to the doclet, so this breaks any arguments that contain commas.

It works fine with semicolon, but then I realized this will break if an attribute value contains entity refs like &. So we probably want another separator, or even make it configurable.

[benevans]

Also it would be nice to read attributes from a file, which avoids the above problems parsing attributes on the command line. I've got a change pending that will read a regular Asciidoc file and just extract its attributes (via Asciidoctor.readDocumentStructure().getHeader()), will update this PR soon.

[johncarl81]

@mojavelinux @LightGuard, could you look at this PR and make sure we're representing the Asciidoc look and feel css properly?

[benevans]

Note that the look & feel is currently biased towards the default (Java 8 or 6) javadoc L&F in terms of fonts, colours and heading styles etc. The Java 6 default L&F in particular is awful ;) and doesn't use CSS much, so I haven't tried to fix it, just adapt it enough so the Asciidoc elements look OK. Java 8's is a big improvement and makes better use of CSS, so is more amenable to styling.

You could really go to town and use more of Asciidoctor's L&F like the red headings and so on, but as it stands it will not be a big change for users already familiar with the default javadoc output.

[mojavelinux]

I have a look. And thanks for your work on this @benevans! I'm so happy to see Asciidoclet getting some more attention!

[johncarl81]

@mojavelinux: ping @benevans, can you provide a jsfiddle link for easy review?

FYI, we're looking to release 1.5.0 very soon and I'd like this PR to be included.

[mojavelinux]

I'll be sure to look today!

[mojavelinux]

(That was enthusiasm, not yelling btw :))

[johncarl81]

lol... @benevans has shared this link before if you want to take a quick look: http://jsfiddle.net/benevans/wed9w/9/embedded/result/. Of course digging into the code and trying it out on a demo project would be preferable.

[benevans]

Note the jsfiddle link above is a bit out of date, I'll update soon with current CSS. For now it's probably simplest to build the javadoc of asciidoclet itself, and view the index.html in your browser. Also the Asciidoclet class javadoc has examples of various elements like lists and tables etc.

On Mon, Aug 18, 2014 at 10:40 PM, John Ericksen notifications@github.com wrote:

lol... @benevans https://github.com/benevans has shared this link before if you want to take a quick look: http://jsfiddle.net/benevans/wed9w/9/embedded/result/. Of course digging into the code and trying it out on a demo project would be preferable.

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/asciidoclet/pull/26#issuecomment-52559351 .

[mojavelinux]

Overall, I think this is a drastic improvement. There are always more things you can do with the stylesheet, as I have painstakingly learned working with the default Asciidoctor stylesheet. We're off to a great start here and we'll take the improvements as they come.

I proposed some changes in a pull request to the opencloud branch. With those changes reviewed and merged, I'd say it looks solid for 1.5.0!

[benevans]

Thanks @mojavelinux, just saw your PR after pushing some of my own fixes for 1.5.0. Will try to merge soon.

[johncarl81]

I can't wait to apply this to my projects. Excelent work @benevans and thanks for taking a look @mojavelinux.

[mojavelinux]

:+1: