[armedbear-devel] Pdfdoclet - Javadoc for ABCL in PDF format

[Mark Evenson]

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…

-- 
"A screaming comes across the sky.  It has happened before, but there
is nothing to compare to it now."