I have written extensive JavaDoc documentation on my application, and added lots of useful info at overview.html and package.html files (including links on the former to illustrations in doc-files/). Maven's Javadoc plugin nicely uses the standard javadoc tool to generate the classic JavaDoc frameset, but now I need to generate a PDF with the whole documentation.
AurigaDoclet generates very pretty PDFs, and I was able to make DocFlex work also. However, both ignore my overview.html and package.html files (tried both inside and outside Maven - the PDF will be a once-only thing, since I'd rather have the HTMLs on the long run).
Does anyone know how to make AurigaDoclet recoginze my non-Java files? Or, alternatively, another to generate a decent-looking PDF from either the source code or the JavaDoc-generated HTML?
Nailed it. After trying all the possible tools to generate straight from the source, I returned to HTMLDOC. It is not JavaDoc-aware, but it is so well built that a few tweaks are enough to make it generate a pretty usable PDF.
Here goes a step-by-step description of how I did it:
Download the software on the releases page;
Generate your traditional HTML docs in your preferred way (Ant, Maven, command-line javadoc - your choice);
The GUI is nice, but adding all files manually can be cumbersome, so just create a .book file with Document Type set to "Web Page", add one of the HTML files from your generated javadoc's root folder (e.g., overview-summary.html, anyone will do, it's just for reference on step 5). On the Output tab select the PDF format and set a name for it, and add other options to your heart's content (logos, colors, lots of cool stuff here). Save this project (say, myjavadocpdf.book) and close the GUI
Generate a list of all HTML files in your javadoc. I did it with Cygwin's find command (my DOS/cmd shell days are long over), but you can do anything you want, as long as you get a file list. In my case a find . | grep html$ | sort -r > files.txt did the trick;
For Windows users, dir /s/b *.html > files.txt should do the same (but keep in mind you may have to replace \s with /s if they appear like so on the next step).
Open the .book file generated on step 3 in your favorite pure text editor (as a programmer you should have strong opinions on that, so will keep my opinions to myself - NOT ;-) ) and append the list generated on step 4 to this .book file (it keeps the list of files at the end, making life really easy). Don't forget to fix the relative paths, if needed with a global search/replace (that's why you needed at least one file added on step 3 - to see which file path pattern htmldoc expects);
Now you should sort the files in a convenient order. I put my overview first, then package descriptions and each class, then the full index, and everything else at the end. Remember that any file you delete will become an external (hence broken) link, so choose wisely;
Save your .book file and re-open it on HTMLDOC. Voila: all files added and sorted. Click on generate. That's it!
You may want to fiddle with images (hint: use HTML width/height, not style/css). In the end, the resulting file is surprisingly good: nice looking and fully navigable for internal and external links. Impressive when you consider that the tool is not Java(Doc) aware at all...
EDIT: software is now free from original author; updated links, thank you #mohammed
According to the Sun JavaDoc FAQ, there's a couple of options -- mostly free, with one or two commercial offerings as well. Check it out at http://java.sun.com/j2se/javadoc/faq/index.html#print.
AurigaDoclet fails to process package.html.
For a fix see my comment at https://sourceforge.net/projects/aurigadoclet/forums/forum/339169/topic/1572199/index/page/1
If this question was bumped anyways, I can use this to link my ltxdoclet project.
This creates from the source (by being a JavaDoc plugin) documentation in LaTeX format, which you then can pass through PdfLaTeX to produce a PDF.
Optionally it also can include pretty-printed source code.
Related
I got a Java project from another developer and I found several files with these two names strewn around the source folder:
vssver.scc
filesystem.attributes
I know the first one is from Visual SourceSafe but what about the second? Are these files from Visual SourceSafe too?
It's difficult to search this as Google simply ignores the dot character in between, even if I put the whole thing in quotes.
Edit: File contents are binary but mostly have references to classes from Java and libraries:
After some digging, it looks to be a (presumably obsolete) Netbeans thing. The only real reference I could find is this Netbeans mailing list post from August 2000, which says it was used to store various IDE metadata about each file.
It is created automatically when you modify some attributes of a file
using the IDE itself. [...] Every file (including directories) stores its
attributes in a filesystem.attributes located alongside it (in the
same containing directory). FileUtil.extractJar specially recognizes
filesystem.attributes in a JAR, so if you jar up your directory then
when it is extracted the jarred attributes will be applied to the
extraction folder.
The post mentions a "future reimplementation" using an XML-based filesystem, which I think has happened by now. This later post mentions using the name .nbattrs to replace the old filesystem.attributes. I'm not a NetBeans user, but this seems to be what happened; for instance, I found an example in this gist.
I am hosting a Wordpress site and would like to use it to publish an open source project. I'd like one of the main menu items to link to the javadoc for the project. For those, unfamiliar with Java, javadoc is a programmatically generated directory hierarchy with many (too many to convert manually) HTML files. The root level contains the index.html file that you start with and all the references are relative to that directory. How can I hook in this structure to the WP site? Converting each page by hand to a WP page is not an acceptable solution because there are too many of them and they change regularly.
The following worked for me:
Within my WordPress folder I created a folder javadoc - right next to wp-admin and the like - and dumped all the created JavaDoc-html in there. Going to http://my-blog/javadoc nicely displays the docs.
I'm a novice in this area, so this might be inadvisable from a best practice or security point of view. I'm actually very interested in an opinion on that!
I've been using WinMerge, Eclipse's compare tool and Tortoise's to see my changes before committing. The problem is that when I edit a file that hasn't been edited by someone else since we last updated our autoformatter-configuration I'll see many, many changes caused by the autoformatter.
Now I have to copy the code from the previous revision, autoformat it in Eclipse and copy it into WinMerge to only see I really made.
Is there a tool that can automatically autoformat both versions of the file I'm comparing?
Any diff tool that allows you to set up an external conversion before the comparison should handle that. External conversions are primarily intended for things like Word/Excel/PDF to Text conversion, but you can do anything you want as long as you can run it from the command line.
For Beyond Compare we already have an optional add-on rule that will use Jalopy to format Java source and another one that use HTML Tidy for HTML files.
WinMerge doesn't look like it supports a Java reformatter out of the box, but their plugins page does describe how you could add one using a dll or Windows Scripting Host scriptlet.
I work on an open source project that is hosted on google code. I'm using ant to create javadocs and I'd like to have links to the source files. I understand I can use the linksource flag to javadoc to include the source in the resulting html, but this isn't what I really want. What I'd prefer is to provide a link to the source file in google code's svn browser. I suppose I could do a simple filter prior to running javadoc, but it'd be even better if I could figure a way to do this right in javadoc. Ideally, I could have a property in my ant properties file like
base.src.url=http://code.google.com/p/myproject/source/browse/branches/1.2
and the javadoc command would add a line to each class's html file:
see source on google code
Any ideas?
The standard doclet offers no such option, as far as I know. So it looks you either have to
use an alternative doclet,
patch the standard doclet,
preprocess the Java files or
postprocess the produced HTML.
A feature request to include this in the standard doclet might also be a good idea.
I have a Java project in a SVN repository, with a bunch of .java files, each of those files has a licence agreement flower box at the top of the file (I have customers which have licenced the source as well as running the product).
Is there a good way to be able to modify / maintain the licence text in one place rather than having to update all the source files manually if it changes?
Looking at some similar (but not identical) questions it seems like SVN does not have this functionality out of the box - what other approaches would be most suitable?
Edit: Ideally the solution would act like the SVN keywords (Id, Author etc.) rather than being a build-time solution. The customer has access to the SVN repository too, so it would be ideal if the licence text was present in the SVN version of the file. I know SVN has commit triggers - what's a simple way to implement that?
Edit 2: Looking at the SVN hooks it doesn't look like what I'd like to do is possible. I guess build process that can be run when the text changes is ok - since it won't change too often.
Modify the source files that need to contain the text of the license to contain some token instead, and then move the license text to a single file that's kept in subversion. Finally, as part of your build process, add a step that substitutes the text of the license for the token. At my job, I do something along these lines using a combination of sed and make. You could then execute this single step before distributing the source to your customers.
ANT can do the substitution easily. Look into the <copy> target.