On 7/21/13 11:09 AM, Sean Champ wrote:

Hello!

In brief: Attached is a shell script for running pdfdoclet[6], a Javadoc doclet component that generates PDF format documentation, instead of HTML, when used with the javadoc tool. For sake of convenience, I was going to send the PDF format ABCL javadoc generated by pdfdoclet, but the resulting PDF file is 13.3 megs in size. Maybe the little utility shell script, as attached, could be enough.

The PDF javadoc could be useful, i think, in the interest of studying ABCL's Java API - perhaps more intermediately, for modeling ABCL's Java API in UML - for instance, using Modelio[1], Argo[2], or Papyrus[3], on the laptop, and Cubetto Mobile[4] on the tablet.

As an additional plug: As far as the PDF format itself, and PDF's annotation support, typically on mobile, i tend to prefer Goodreader[5]. It offers good support for PDF annotations and so on.

PDFDoclet can also be used from Ant. I'm not very well familiar with Ant, offhand. Of course, I notice that Ant is used in ABCL - will take a look...

Not to discourage you too much, but I am afraid that the javadoc generated from the ABCL sources is not terribly informative. Or at least I don't find it easier understanding the code from reading Javadoc than from opening the code in an IDE like Netbeans. The current developers inherited a codebase with almost no javadoc comments, and have never attempted to systematically improve this situation. Also the really informative comments are not present in javadoc, but in the line-by-line snippets used to explain really hairy code.

That being said--and if you aren't discouraged--I would sponsor moving a future version of the use of pdfdoclet into the ABCL build system if you would undergo a bit of back-and-forth critique from me.

So, my two current problems:

1) your script is that it needs to be easier for the average user to install, as it isn't immediately obvious that one needs to download the pdfdoclet.jar, create the $(directory $JAR) location on the filesystem, placing the binary there. The $JAR location is outside the ABCL source root directory, which is a generally unfriendly assumption vis a vis the system packaging facilities.

2) we need to run under Windows as well (without assuming the presence of cygwin)

Running things from Ant would certainly solve #2 fairly easily, so I would suggest pursue the development of creating an Ant task for this process. From browsing the [pdfdoclet documentation][1], this seems quite straightforward. If you are a Java developer, getting a basic familiarity with wrangling Ant scripts is worth the time invested.

For easing the process of installing the pdfdoclet.jar, I would use the Ant <get> task to download the pdfdoclet.jar automatically [as is done for for using JUnit][abcl.ext]. Implementing this would meet my objections in #1.

As an alternative implementation strategy, one could use [abcl-asdf][2] to reference pdfdoclet.jar, invoking from your choice of Java FFI from within a running ABCL. Here, your code would almost entirely in Lisp, with a tiny snippet of Ant to invoke the ABCL process. This would win points from the "The point of ABCL is to not have to use Java the Language on the JVM" crowd, but would probably be slower to execute as it would involve starting about a sub-JVM from the Ant script. But if you get this working in Lisp, I'll contribute the Ant target for its invocation.

[1]: http://pdfdoclet.sourceforge.net/running.html [abcl.ext]: http://lisp.not.org/trac/armedbear/browser/trunk/abcl/build.xml#L897 [2]: http://abcl.org/svn/trunk/abcl/contrib/abcl-asdf/README.markdown

Thanks for the contribution, and welcome to the Bear…