next gen javadoc (javadoc without frameset)

Sun Aug 25 13:59:08 PDT 2013

## Framesets are simple, useful, familiar ##

Javadoc relies on HTML's <frameset> for it's "FRAMES" view of doc sets.
This feature adds some convenient navigation whilst Javadoc's HTML output
remains as-simple-as-possible. It is familiar and useful and you wouldn't
abandon it unless an alternative was unquestionably better and just as
simple.

## Framesets don't really fit on the web ##

There is however, a weakness of <frameset> based sites - the URL in the
address bar doesn't match the primary content being viewed. As a
consequence:

- navigating a hyperlink or via back and forwards button doesn't update the
URL in the address bar, which is unexpected behavior (although not to those
familiar with javadoc)

- search engines will link to the primary content page, so users will
arrive at the NOFRAMES view and need to manually choose the FRAMES view.

- users can't bookmark pages or email the URL when in the FRAMES view

## With AJAX and pushState, framesets can be emulated / surpassed ##

Fortunately, all up-to-date browsers have the `history.pushState()` API
call which allows javascript to update the URL in address bar without
reloading the page. This - together with the long-supported XMLHttpRequest
- should allow a Javascript-driven **emulation** of framesets that also
keeps the URL in the address bar valid.

(Naturally it is not necessary to strictly emulate the current UI if
something better is possible, e.g. a dynamic search box.)

## A frameset replacement must be (mostly) decoupled from Javadoc ##

For this approach to be a viable replacement for framesets it must be
possible to implement it with minimal change to javadoc's HTML output.
Ideally this change would be a single <script src="boot.js"> in every page
to bootstrap the enhanced UI.

If this can be achieved then the UI can be updated independently of javadoc
being run. This would make UI customization / rebranding / fixes /
enhancement quicker and simpler.

## An implementation ##

The good news is that this approach already has an implementation.

The javadoc-panner project brings pushState-assisted-navigation and a
customizable UI to documentation-sets generated by Javadoc-1.7. There is a
public project page at https://github.com/meekostuff/javadoc-panner

### Proof of concept

These enhancements **are** achieved with a single bootstrap script.
Currently this is the most important feature of javadoc-panner.

### Demonstrations

The generic method of applying javadoc-panner to a doc-set is with a
javascript bookmarklet. This can be most easily installed from
http://devel.meekostuff.net/javadoc-panner/0.1-devel/

There is also an introduction video with a few thoughts, a walk-through on
how to install the bookmarklet, and a short demo of it running on a few
sites. See http://youtu.be/LC45G7zsCFs

### The UI can be easily updated

When you try out javadoc-panner or watch the demo, the most important thing
to remember is that *you don't have to like the UI* because **it can be
updated independently**. Another important thing to note is that the UI is
implemented as a standalone HTML document - another feature that should
make UI evolution quicker and simpler.

### Easily integrated

It is also possible (though undocumented) to integrate javadoc-panner into
an already generated doc-set. You can see this in action at

http://playground.meekostuff.net/javadoc/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html

This doc-set is copied from the one at

http://download.java.net/jdk8/docs/jdk/api/jpda/jdi/overview-summary.html

The only difference between the HTML source files and the files in this
doc-set
is that each file is prepended with the lines:

    <!DOCTYPE html>
    <script src="/javadoc/boot.js"></script>

## Feedback required ##

It would be great to have feedback.

Any questions or comments on the approach outlined here are welcome.

If there are other news groups where it would be appropriate to discuss
this then please notify me.

Issues / bugs / feature-requests for the javadoc-panner project are best
directed to the project issues page
    https://github.com/meekostuff/javadoc-panner/issues

regards,
Sean Hogan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20130826/6fb0ef27/attachment.html 