[next] [prev] [prev-tail] [tail] [up]

2.2 The JavaHelp Files

  2.2.1 The HTML Documentation (*.html)
  2.2.2 The JavaHelp Root File (HelpSet File: jobname.hs)
  2.2.3 The JavaHelp Search Directory (jobname-jhs)
  2.2.4 The JavaHelp Keys to URLs Mapping (jobname.jhm)
  2.2.5 The JavaHelp TOC (jobname-jht.xml)
  2.2.6 The JavaHelp Index (jobname-jhi.xml)
  2.2.7 Configuring Link Targets
  2.2.8 Version Information
  2.2.9 Incorporate JavaHelp into a program
  2.2.10 Compiling
  2.2.11 Running
  2.2.12 Compressing (with JAR)
  2.2.13 Getting the JavaHelp Software

<..javahelp..>
 % javahelp.4ht (2014-05-24-11:52), generated from tex4ht-javahelp.tex
 % Copyright (C) 2009-2010 TeX Users Group
 % Copyright (C) 2003-2009 Eitan M. Gurari
 <.TeX4ht copywrite.>
-_-_-

<..double acute iso-8859-2..>
 <.double acute code.>%
-_-_-

2.2.1 The HTML Documentation (*.html)

Prepare a LATEX file and compile it for HTML 3.2. For instance, with the command htlatex jobname "html,3.2,3,javahelp".

<..configure javahelp Preamble..>
 <.instructions for log.>
 % \newif\ifimmediate
 % \immediatefalse
-_-_-

<..jh defs..>
 \def\Write:File#1#2{%
   \special{t4ht>#1}%
   \special{t4ht=#2}%
   \special{t4ht*>#1}%
   \special{t4ht*>}%
 }
-_-_-

<..configure javahelp Preamble..>+
 \NewConfigure{jhxml}[1]{\concat:config\a:jhxml{#1}}
 \let\a:jhxml\relax
-_-_-

<..javahelp-a.4ht..>
 % javahelp-a.4ht (2014-05-24-11:52), generated from tex4ht-javahelp.tex
 % Copyright (C) 2009-2010 TeX Users Group
 % Copyright (C) 2003-2009 Eitan M. Gurari
 <.TeX4ht copywrite.>
 \NextFile{\jobname.tmp}
 \HPage{}
 \bgroup
    \catcode‘\:=11
    \catcode‘\@=11
    \catcode‘\"=12
    \Configure{PROLOG}{}
    \Configure{HtmlPar}{}{}{}{}
    \Configure{tableofcontents}{}{}{}{}{}
    \Configure{htf}{0}{+}{}{}{}{}{}{}{}
    \ScriptEnv{dito}{\IgnorePar}{}
    \a:jhxml
    <.jh util.>
    <.jh root.>
    <.jh toc.>
    <.jh index.>
    <.jh at end.>
 \egroup
 \EndHPage{}
-_-_-

The HPage above is to ensure the all the references in the javahelp files will be to locations at other files, and so they will explicitly include the names of the files being referenced. The page is empty and not referenced by other pages.

<..instructions for log..>
 \immediate\write-1{--------------- JavaHelp -----------------}
 \immediate\write-1{The entry (HelpSet) file for the java program
                                          is at ‘\jobname.hs’}
 \immediate\write-1{Generate a search database
                              with, for instance, the command}
   \immediate\write-1{ java -jar
     ...../jh1.1.3/javahelp/bin/jhindexer.jar
     -db \jobname-jhs \jobname*.html}
 \immediate\write-1{Compile the java program with a command similar to}
   \immediate\write-1{ javac -classpath
     ...../jh1.1.3/javahelp/lib/jh.jar  program.java}
 \immediate\write-1{Run the java program with a command similar to}
   \immediate\write-1{ java -classpath
     ...../jh1.1.3/javahelp/lib/jh.jar;. program}
 \immediate\write-1{JavaHelp might require a compilation for HTML 3.2,
      for instance,}
 \immediate\write-1{ htlatex \jobname\space "html,javahelp,3.2,3"}
 \immediate\write-1{------------------------------------------}
-_-_-

<..jh defs..>+
 \def\jhNote{%
      Created for JavaHelp
      (http://java.sun.com/products/javahelp/)\Hnewline
      by TeX4ht (http://www.cse.ohio-state.edu/\string
      ~gurari/TeX4ht/)\Hnewline from \jobname.tex at \:today \space
   }
-_-_-

We can’t keep the comment boundaries in the macro because the adjacent hyphens in some cases merge into a n-dash under font encoding T1. For instance,

   \documentclass{report}  
     \usepackage[T1]{fontenc}  
   \begin{document}  
 
   \ScriptEnv{dito}{}{}  
 
   \begin{dito}  
   --[]-[]  
   \end{dito}  
   \end{document}

<..tex4ht note..>
 \jhNote
-_-_-

<..par del..>
 !*?: 
-_-_-

<..jh defs..>+
 \Configure{crosslinks}{}{}{}{}{}{}{}{}{}
-_-_-

2.2.2 The JavaHelp Root File (HelpSet File: jobname.hs)

This file introduces the files in the help distribution.

<..jobname.hs: url of jh root file..>
 \jobname.hs
-_-_-

The etension name must be ‘hs’!

<..dtd lang..>
 \dTdLaNg
-_-_-

<..jh defs..>+
 \def\dTdLaNg{\expandafter
   \ifx \csname a:dtd-lang\endcsname\relax EN\else
     \csname a:dtd-lang\endcsname
   \fi   }
-_-_-

<..jh root..>
 <.jh root config.>
 \IgnorePar\par\leavevmode\special{t4ht><.jobname.hs: url of jh root file.>}%
 \begin{dito}-\
 <?xml version="1.0" encoding="ISO-8859-1" ?>
 \end{dito}
 <.helpset DTD.>
 \begin{dito}-\
 <!-\relax- <.tex4ht note.> -\relax->
 <helpset version="\dotVersion">
   <title><.title label.></title>
   <maps>
     <homeID><.home id.></homeID>
     <mapref location="<.url of jh keys file.>"/>
   </maps>
   <view>
     <name>TOC</name>
     <label><.toc label.></label>
     <type>javax.help.TOCView</type>
     <data><.url of jh toc file.></data>
   </view>
   <view>
     <name>Index</name>
     <label><.index label.></label>
     <type>javax.help.IndexView</type>
     <data><.url of the jh index.></data>
   </view>
   <view>
     <name>Search</name>
     <label><.search dir label.></label>
     <type>javax.help.SearchView</type>
     <data
       engine="com.sun.java.help.search.DefaultSearchEngine"><.url of jh serach dir.></data>
   </view>
 </helpset>
 \end{dito}
 \IgnorePar\par\leavevmode\special{t4ht<<.jobname.hs: url of jh root file.>}
-_-_-

<..toc label..>
 \tocLabel
-_-_-

<..index label..>
 \indexLabel
-_-_-

<..search dir label..>
 Search
-_-_-

<..title label..>
 \titleLabel
-_-_-

<..jh root config..>
 \edef\tocLabel{\ifx\contentsname\:UnDef Table Of Contents\else
                \ifx\contentsname\empty  Table Of Contents\else
                \contentsname\fi\fi}
 \edef\indexLabel{\ifx\indexname\:UnDef Index\else
                  \ifx\indexname\empty  Index\else \indexname\fi\fi}
 \ifTag{TITLE+}
    {\edef\titleLabel{\LikeRef{TITLE+}}}
    {\def\titleLabel{\jobname}}
-_-_-

2.2.3 The JavaHelp Search Directory (jobname-jhs)

<..url of jh serach dir..>
 \jobname-jhs
-_-_-

Use a command similar to ‘java -jar ...../jh2.0/javahelp/bin/jhindexer.jar -db tex4ht-javahelp-jhs tex4ht-javahelp*.html’ to create a search directory JavaHelpSearch for JavaHelp from the HTML pages of the documentation.

2.2.4 The JavaHelp Keys to URLs Mapping (jobname.jhm)

<..url of jh keys file..>
 \jobname.jhm
-_-_-

The homeId tag provides the default entry to present when a HelpSet is first shown.

<..home id..>
 \jobname
-_-_-

The default entry point can be overwritten in:

<..entry point..>
 \jobname
-_-_-

Assigns keys to locations within the HTML document.

<..jh at start..>
 \Write:File
    {<.url of jh keys file.>}
    {<.map preamble.>}
-_-_-

<..map preamble..>
 <?xml version="1.0" encoding="ISO-8859-1" ?>\Hnewline
 <.map DTD.>
 \Hnewline <!-- <.tex4ht note.> -->\Hnewline
 <map version="\dotVersion">\Hnewline
 <mapID target="<.entry point.>" url="\jobname.html"/>\Hnewline
-_-_-

<..jh defs..>+
 \HAssign\mapEntry=0
-_-_-

<..add index entry to map..>
 \gHAdvance\mapEntry by 1
 \Write:File
    {<.url of jh keys file.>}%
    {<mapID target="indexentry-\mapEntry"
              url="\RefFileNumber\FileNumber
        \#\title:chs {dx\last:haddr}{\cur:th\:currentlabel}%
            " />\Hnewline}%
-_-_-

<..jh defs..>+
 \AtBeginDocument{%
   \let\jh:toc=\auto:toc
   \expandafter\append:defI\csname tableofcontents*\endcsname{%
      \global\let\jh:toc=\auto:toc }%
 }
-_-_-

<..load table of contents..>
 \expandafter\ifx \csname jh:toc\endcsname\relax
    \tableofcontents
 \else
    \expandafter\expandafter\expandafter\tableofcontents
    \expandafter\expandafter\expandafter[\csname
                                          jh:toc\endcsname]%
 \fi
-_-_-

<..jh at end..>
 \special{t4ht><.url of jh keys file.>}%
 \bgroup
    <.jh map for toc.>
   \bgroup \catcode‘\:=12 \catcode‘\@=12 \let\contentsname\empty
      <.load table of contents.>%
   \egroup
   \HCode {</map>\Hnewline}
 \egroup
 \special{t4ht*><.url of jh keys file.>}%
 \special{t4ht*>}%
-_-_-

<..jh map for toc..>
 \Configure{Link}{mapID}{target="\a:mapIdTarget" url=}{}{}
 \Configure{TocLink}{\Link{#2}{}\EndLink}
 \let\jh:doTocEntry\:doTocEntry
 \def\:doTocEntry#1#2#3{%
    \edef\sectioningKey{\expandafter\gob:IV\string#1}%
    \edef\:temp{\noexpand\ConfigureToc{\sectioningKey}
                {}{\relax}{}{}}\:temp
    <.config toc target entry.>%
    \jh:doTocEntry#1{#2}{#3}}
 \def\gob:IV#1#2#3#4{}
 \def\sectioningKey{NoToc}
-_-_-

2.2.5 The JavaHelp TOC (jobname-jht.xml)

<..url of jh toc file..>
 \jobname-jht.xml
-_-_-

<..jh toc..>
 \bgroup
 %\immediatetrue
 <.jh TOC config.>
 <.start jh TOC.>
      <.load table of contents.>%
 <.end jh TOC.>
 \egroup
-_-_-

<..start jh TOC..>
 \IgnorePar\par\leavevmode\special{t4ht><.url of jh toc file.>}%
 \begin{dito}-\
 <?xml version="1.0" encoding="ISO-8859-1" ?>
 \end{dito}
 <.toc DTD.>
 \begin{dito}-\
 <!-\relax- <.tex4ht note.> -\relax->
 <toc version="\dotVersion">
   <tocitem target="<.entry point.>" text="<.title label.><.uni sp.>">
 \end{dito}
 \let\end:jhhook=\empty
 \catcode‘\:=12 \catcode‘\@=12  \let\contentsname\empty
 \NoFonts
-_-_-

<..end jh TOC..>
 \EndNoFonts
 \catcode‘\:=11 \catcode‘\@=11
 \end:jhhook
 \begin{dito}
   </tocitem>
 </toc>
 \end{dito}
 \special{t4ht<<.url of jh toc file.>}
-_-_-

<..jh TOC config..>
 \Configure{TocLink}
    {\HCode{<tocitem target="\a:mapIdTarget"\Hnewline
                     text="}\hbox{#4}\HCode{<.uni sp.>">\Hnewline}}
 \let\jh:doTocEntry\:doTocEntry
 \def\:doTocEntry#1#2#3{%
    \edef\sectioningKey{\expandafter\gob:IV\string#1}%
    \edef\:temp{\noexpand\ConfigureToc{\sectioningKey}
        {}{\noexpand\set:endtocitem{\sectioningKey}}{}{}}\:temp
    <.config toc target entry.>%
    \jh:doTocEntry#1{#2}{#3}}
 \def\gob:IV#1#2#3#4{}
 \def\sectioningKey{NoToc}
-_-_-

<..jh util..>
 \def\set:endtocitem#1{%
    \csname catchAt:#1\endcsname
    \expandafter\ifx\csname a:end#1\endcsname\relax
       \HCode{</tocitem>}%
    \else
       \expandafter\ifx \csname jh:#1\endcsname\relax
          <.end tocitem at end of toc.>%
          \def\:tempc##1,{\if ,##1,%
                \expandafter\gob:pardel
             \else
                <.end tocitem at toc entry of diff type.>%
                \expandafter\:tempc
             \fi}%
          \expandafter\expandafter\expandafter
              \:tempc\csname a:end#1\endcsname,,<.par del.>%
       \fi
       <.end tocitem at toc entry of same type.>%
    \fi
 }
 \def\gob:pardel#1<.par del.>{}
-_-_-

<..end tocitem at toc entry of same type..>
 \csname jh:#1\endcsname
 \expandafter\gdef\csname jh:#1\endcsname{%
    \expandafter\global\expandafter\let\csname jh:#1\endcsname=\empty
    \HCode{</tocitem><!--/#1-->}}%
-_-_-

<..end tocitem at toc entry of diff type..>
 \expandafter\ifx \csname catchAt:##1\endcsname \relax
   \expandafter\gdef\csname
     catchAt:##1\endcsname{\csname jh:#1\endcsname}%
 \else
   \expandafter\pend:def\csname
     catchAt:##1\endcsname{\csname jh:#1\endcsname}%
   \expandafter\global\expandafter\let\csname
     catchAt:##1\expandafter\endcsname\csname catchAt:##1\endcsname
 \fi
-_-_-

<..end tocitem at end of toc..>
 \append:def\end:jhhook{%
    \csname jh:#1\endcsname
    \expandafter\global\expandafter
                \let\csname jh:#1\endcsname\:UnDef}%
 \global\let\end:jhhook\end:jhhook
-_-_-

2.2.6 The JavaHelp Index (jobname-jhi.xml)

<..url of the jh index..>
 \jobname-jhi.xml
-_-_-

<..jh index..>
 \bgroup
 <.jh IDX config.>
 <.start jh IDX.>
      <.load index entries.>%
 <.end jh IDX.>
 \egroup
-_-_-

<..start jh IDX..>
 \IgnorePar\par\leavevmode\special{t4ht><.url of the jh index.>}%
 \begin{dito}-\
 <?xml version="1.0" encoding="ISO-8859-1" ?>
 \end{dito}
 <.index DTD.>
 \begin{dito}-\
 <!-\relax- <.tex4ht note.> -\relax->
 <index version="\dotVersion">
 \end{dito}
-_-_-

<..end jh IDX..>
 \begin{dito}
 </index>
 \end{dito}
 \special{t4ht<<.url of the jh index.>}%
-_-_-

<..load index entries..>
 \let\indexname\empty
 \def\gobbleLnk#1, \LNK#2#3#4#5{#1\HCode{" target="indexentry-#5"}}
 \Configure{theindex}
    {}{}
    {\hbox\bgroup\HCode{<\string !--index-item--><indexitem
           text="}\gobbleLnk}
    {\HCode{/>}\egroup\hfill\break}
    {\hbox\bgroup\HCode{<\string !--subex-item--><indexitem
           text="}\gobbleLnk}
    {\HCode{/>}\egroup\hfill\break}
    {\hbox\bgroup\HCode{<\string !--subsubitem--><indexitem
           text="}\gobbleLnk}
    {\HCode{/>}\egroup\hfill\break}
    {}
 \immediate\openin15=\jobname.ind
 \ifeof15
    \immediate\closein15
 \else
    \immediate\closein15
    \input \jobname.ind
 \fi
-_-_-

<..load index entriesNO..>
 \def\beforeindex#1|LNK#2#3{#1}%
 \def\indexentry#1#2{\HCode{<indexitem target="indexentry-#2"
                      text="}\beforeindex#1\HCode{<.uni sp.>" />\Hnewline}}%
 \immediate\openin15=\jobname.4dx
 \ifeof15
    \immediate\closein15
 \else
    \immediate\closein15
    \input \jobname.4dx
 \fi
-_-_-

<..jh defs..>+
 \HAssign\indexEntry=0
 \append:defI\@wrindex{%
    <.add index entry to map.>%
 }
-_-_-

JavaHelp has problems with unicode values at the end of text fields in the toc of within the jht file: it refuses ‘text="Men&#252;"’ (but accepts ‘text="Men&#252; "’). The following adds spaces at the end of the text attribute values.

<..uni sp..>
  
-_-_-

A similar problem occurs when two unicode character codes follow each other. In this case, the second one is not properly rendered.

2.2.7 Configuring Link Targets

<..config toc target entry..>
 \expandafter\target:info#3//%
 \b:mapIdTarget
-_-_-

<..jh defs..>+
 \def\target:info#1#2#3#4#5#6//{%
     \let\sectionType=\sectioningKey
     \let\sectionId\TocCount
     \Advance:\sectionId 1
     \def\sectionName{#5}%
   }
 \NewConfigure{mapIdTarget}{2}
 \Configure{mapIdTarget}
    {\sectionType-\sectionId}
    {}
-_-_-

2.2.8 Version Information

<..helpset DTD..>
 \begin{dito}-\
     <!DOCTYPE helpset PUBLIC
     "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version \dotVersion//<.dtd lang.>"
     "http://java.sun.com/products/javahelp/helpset_\subVersion.dtd">
 \end{dito}
-_-_-

<..toc DTD..>
 \begin{dito}-\
    <!DOCTYPE toc PUBLIC
    "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version \dotVersion//<.dtd lang.>"
    "http://java.sun.com/products/javahelp/toc_\subVersion.dtd">
 \end{dito}
-_-_-

<..index DTD..>
 \begin{dito}-\
    <!DOCTYPE index PUBLIC
    "-//Sun Microsystems Inc.//DTD JavaHelp Index Version \dotVersion//<.dtd lang.>"
    "http://java.sun.com/products/javahelp/index_\subVersion.dtd">
 \end{dito}
-_-_-

<..old index DTD..>
    <!DOCTYPE index PUBLIC
    "-//Sun Microsystems Inc.//DTD JavaHelp Index Version \dotVersion//<.dtd lang.>"
    "http://java.sun.com/products/javahelp/index_\subVersion.dtd">
-_-_-

<..map DTD..>
 <!DOCTYPE map PUBLIC\Hnewline
      "-//Sun Microsystems Inc.//DTD
                     JavaHelp Map Version \dotVersion//<.dtd lang.>"\Hnewline
      "http://java.sun.com/products/javahelp/map_\subVersion.dtd">  
-_-_-

<..jh defs..>+
 \:CheckOption{jh1.0} \if:Option
    \def\dotVersion{1.0}
    \def\subVersion{1\string_0}
 \else
    \def\dotVersion{2.0}
    \def\subVersion{2\string_0}
 \fi
-_-_-

2.2.9 Incorporate JavaHelp into a program

Url of JavaHelp root file (jobname.hs)

http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/javahelp/javahelp.html

<..program..>
 import java.net.URL;
 import javax.help.*;
 import javax.swing.*;
 public class program {
            //^^^^^^^
    public static void main(String args[]) {
       JHelp helpViewer=null;
       try {
          ClassLoader cl = program.class.getClassLoader();
                         //^^^^^^^
          URL url = HelpSet.findHelpSet(cl,
                               "<.jobname.hs: url of jh root file.>");
          HelpSet hs = new HelpSet(cl, url);
          helpViewer = new JHelp( hs );
          /*
             helpViewer.setCurrentID("<.entry point.>");
          */
       } catch (Exception e) {
           System.out.println("error"); System.exit(0);
       }
       JFrame frame = new JFrame();
       frame.getContentPane().add(helpViewer);
       frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
       frame.setSize(500,500);
       frame.setVisible(true);
    }
 }
-_-_-

http://java.sun.com/developer/technicalArticles/J2SE/Desktop/javahelp/

<..HelpMenu..>
 import java.net.*;
 import javax.help.*;
 import javax.swing.*;
 import java.awt.event.*;
 
 public class HelpMenu {
    JFrame f;
    JMenuItem topics;
 
    public HelpMenu() {
      f = new JFrame("Menu Example");
      JMenuBar mbar = new JMenuBar();
 
      // a file menu
      JMenu file = new JMenu("File");
      JMenu help = new JMenu("Help");
 
      // add an item to the help menu
      help.add(topics = new JMenuItem("Help Topics"));
 
      // add the menu items to the menu bar
      mbar.add(file);
      mbar.add(help);
 
      // 1. create HelpSet and HelpBroker objects
      HelpSet hs = getHelpSet(<.jobname.hs: url of jh root file.>);
      HelpBroker hb = hs.createHelpBroker();
 
      // 2. assign help to components
 /*
      CSH.setCurrentID("<.entry point.>");
 */
      // 3. handle events
      topics.addActionListener(new CSH.DisplayHelpFromSource(hb));
 
      // attach menubar to frame, set its size, and make it visible
      f.setJMenuBar(mbar);
      f.setSize(500, 300);
      f.setVisible(true);
    }
 
    /**
     * find the helpset file and create a HelpSet object
     */
    public HelpSet getHelpSet(String helpsetfile) {
       HelpSet hs = null;
       ClassLoader cl = this.getClass().getClassLoader();
       try {
         URL hsURL = HelpSet.findHelpSet(cl, helpsetfile);
         hs = new HelpSet(null, hsURL);
       } catch(Exception ee) {
         System.out.println("HelpSet: "+ee.getMessage());
         System.out.println("HelpSet: "+ helpsetfile + " not found");
       }
       return hs;
    }
 
    public static void main(String argv[]) {
       new HelpMenu();
    }
 }
-_-_-

2.2.10 Compiling

Add JavaHelp to your program, say ‘program.java’, and compile the program with the command ‘javac -classpath ...../jh2.0/javahelp/lib/jh.jar program.java’.

2.2.11 Running

Use the a command similar to ‘java -classpath ...../jh2.0/javahelp/lib/jh.jar;. program’.

2.2.12 Compressing (with JAR)

javac -classpath c:\jh1.1.3\javahelp\lib\jhall.jar  
      -d c:\temp  
      JavaHelpTest.java  
 
jar cvfm JavaHelpTest.jar  manifest JavaHelpTest.class  
 
java -jar jh1.3.1/demos/bin/UserGuide.jar

2.2.13 Getting the JavaHelp Software

Download JavaHelp from http://java.sun.com/products/javahelp/download_binary.html and unzip it into some directory (say ...../).

[next] [prev] [prev-tail] [front] [up]