Menu ▾ ▴

User Guide

todo (1)
Yetu Yachim
Attachments
jahm-ss-main_gui.png (21936 bytes)

Installation

Binary

Download the binary package, jahm-x.x.x-bin.zip, and extract the executable into the directory from which you wish to run it. You may want to include this directory in your system's PATH environment variable.

Source

An executable can be created from the source package, jahm-x.x.x-src.zip, using Apache Ant. Version 7 of the Java Development Kit (JDK) is required to compile the source files and can be obtained from the Oracle website. After installing Ant and the JDK, and assuming that the directory to 'ant' is included in the PATH environment variable, type the following commands on the command line.

:::bash
$ unzip jahm-x.x.x-src.zip
$ cd jahm-x.x.x-src
$ ant dist

This will create jahm.jar in directory: jahm-x.x.x-src/dist

Command-line Usage

The Java Runtime Environment (JRE) version 7 or greater is required to run JAHM. This can be obtained from the Oracle website.

You will also need access to the command line (i.e. cmd.exe in Microsoft Windows, Terminal.app in Macintosh OS X, or sh on Linux).

Ensure that the JRE is installed and open the command line.

Preview Content

You can view your content as it will appear when archived by using the "preview" option. The first argument is a path to your HTML files.

:::bash
$ java -jar jahm.jar /path/to/content --preview


Create Archive

Use the "assemble" option to create an archive. The first argument is a path to your HTML files. The "output" argument can optionally be passed to specify the path and name of the created archive.

:::bash
$ java -jar jahm.jar /path/to/content --assemble --output=/path/to/new/doc.jar


Launch Archive

An archive created by the JAHM tool can be launched from the command line:

:::bash
$ java -jar doc.jar

In some environments, it may also be possible to launch the archive by double-clicking its icon in a file manager (e.g. Explorer in Microsoft Windows or Finder in Macintosh OS X).

GUI Usage

In release 0.2.0, a graphical window became available as an alternative to the command line. This window appears when jahm.jar is run with the "--assemble" and "--preview" options excluded. (Double-clicking jahm.jar may also produce this window.)

[[img src="jahm-ss-main_gui.png" alt="JAHM Launch GUI"]]
todo: explain textfields and buttons


Data Files

Two categories of files are understood by the JAHM viewer. The first includes those that have fixed names and formats; these are generally used to provide details about the appearance of the viewer and what to place in the navigational panes. All other files are treated as information typically rendered by a web-browser.

Configuration (cfg.xml)

Settings are specified in this file to control the viewer's appearance and behavior. The following example locates the navigation panel to the right of the display panel and sets 'index.htm' as the page to load when the archive is launched (or content is previewed).

:::xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
    <comment>JAHM Configuration</comment>
    <entry key="nav.pos">right</entry>
    <entry key="dsp.start">index.htm</entry>
</properties>


key value effect
nav.pos hidden navigation panel does not appear
left navigation panel appears to the left of display panel
right navigation panel appears to the right of display panel
nav.toc.visible false table-of-contents tab does not appear in navigation panel
true table-of-contents tab appears in navigation panel
nav.index.visible false index tab does not appear in navigation panel
true index tab appears in navigation panel
nav.search.visible false search tab does not appear in navigation panel
true search appears in navigation panel
dsp.start <page> <page> is loaded into display when browser opens


Table of Contents (toc.xml)

A hierarchical description of available content is defined here and displayed in the "Content" tab of the navigation panel.

:::xml
<toc label="Title to Display in the Browser Heading">
    <topic label="First Link" href="pagex.htm" />
    <topic label="Parent without Link">
        <topic label="Nested Parent with Link" href="parent.htm">
            <topic label="Child of Nested Parent" href="parent.htm#child1" />
            <topic label="Second of Nested Parent" href="parent.htm#child2" />
        </topic>
        <topic label="Child of Parent without Link" href="child.htm" />
    </topic>
</toc>


Index (idx.xml)

This file contains groupings of links to content. Groups are specified with the entry tag which defines a label and encloses topic tags that contain links and (optional) labels. For topics that do not have labels, the table-of-contents is queried for a label that corresponds to the linked content. If no corresponding topic label is found in the table-of-contents, then the file-name is used.

:::xml
<index>
    <entry keyword="Group One">
        <topic href="parent.htm#child2">
    </entry>
    <entry keyword="Group Two">
        <entry keyword="SubGroup">
            <topic href="pagex.htm" />
            <topic label="Something Relevant to SubGroup" href="parent.htm#child1" />
        </entry>
    </entry>
</index>


Content

This is the textual and graphical information to be shown in the main display area. At the moment, the following file formats are known to be supported.

text version note
HTML 3.2
CSS 1
image note
JPEG
PNG


todo: add to list of supported formats


MongoDB Logo MongoDB