Geertjan's Blog

  • June 30, 2007

Visual Editor (Part 3)

Geertjan Wielenga
Product Manager
I got slightly carried away while preparing for the third part of this series—as a result, I seem to have created a mostly complete JavaHelp Editor. Below, you see four buttons in the top of the visual view, one is for the XML source of the JavaHelp TOC file, while the other three are the names of the highest elements in the TOC hierarchy. When you click one of the buttons, you get a list of topics, but only those that relate (i.e., are below in the hierarchy) to the name in the button. In other words, the buttons are dynamically created, so maybe not a good idea (if you have 20 top level topics, you might end up having a problem because of buttons and spacing).

Within the body of the visual view, you see the outline of the help content. If a topic does not have a 'target' attribute set, the text field is outlined in red, because that means it is a 'bucket', containing help topics. If it is a help topic, the text field is outlined in blue. In that case, you can right-click, click a menu item, and then the topic itself opens in the IDE, so you can edit it right away. (This is made possible by parsing the Map file, via JAXB, and then comparing the target attribute in the Map file with the target attribute in the TOC file. By the way, I assume that the Map file is in the same folder as the TOC file, and that there is only one Map file in that folder, which I think are fair assumptions.) And what if the background is yellow? That signifies a broken link! In one glance, without needing to do anything at all, I can see all the broken links! That's about as useful as a JavaHelp Editor can be.

I learned quite a lot while making this JavaHelp Editor and I hope to continue with this series tomorrow, building on from yesterday, with the screenshot above as the target. In the meantime, I'll be sure to continue developing this tool. For example, a progress bar is needed, because the JAXB parsing sometimes take a little bit of time, especially the first time round. (Thus far, not more than 5 seconds. That time could be decreased if I focus on handling the JAXB parsing more efficiently. It definitely isn't a JAXB problem, just a coding issue.) Also, currently the link check is done for a tab whenever a tab is opened; maybe that should be deferred so that the user can choose when the link check should be done. And, as before, the synchronization hasn't been done yet, so that changes to the TOC source view do change the visual view, but not the other way round. Something else is that the visual view should be organized better—for example, the "Servers" text in the screenshot above should be in the top orange-backgrounded header, while what is there currently is superfluous, since it simply repeats the text in the button. Are there other things that could be added? I'd be glad to take suggestions.

Join the discussion

Comments ( 3 )
  • Szabó Árpád Zoltán Monday, July 2, 2007
    You have blogged earlier about DocBook (http://blogs.sun.com/geertjan/entry/docbeans). So merging that project and this one could result in a complete JavaHelp authoring tool, couldn't it?

    It's a pity IMHO, that JavaHelp sticks to html files, and not a "proprietary" xml documentation format, for what DocBook would be a good candidate (maybe the only good one?).

    But they obviously wanted to achieve a chm like format, and it's true, HTML can be the displayed format backed by XML (and admitting that separation of formatting and content can be maintained, and novadays (with CSS) it can be).
    The question is how effectively can be aided the actual authoring (writing and formatting) itself (maybe the generated toc-map should be aware of its xml source, and could be edited/set in multiple places, wysiwyg xml editing and other dreamy like features).
  • 绿植租摆 Saturday, July 7, 2007
    thank you webmaster for a good blog and good post. i am reading all
  • Geertjan Saturday, July 7, 2007
    Thanks both for the comments. Szabó, I agree, would be excellent if JavaDoc were to be XML-based.
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.