The files in the windows/ dir can have any legal HTML they want,
because they do not get converted to man pages.

The files in the solaris/, linux/, and share/ directories, however,
are RESTRICTED TO A MANPAGE-COMPATIBLE SUBSET OF HTML, explained
below. (For a basic template, use pubs/make/basic_tool_page.html.)

BEFORE YOU PUTBACK YOUR CHANGES
-------------------------------

 1. Generate man pages

      % cd pubs/make
      % ./pubsmake man

 2. View the results, and make sure the
    conversion produces the expected results

    For files in share/ or solaris/ dirs:
      % ./solaris_man <tool>

    For files in the linux/ dir:
      % ./linux_man <tool>

    Example:
      % ./solaris_man jar

HTML RESTRICTIONS
-----------------
These are things that do not work, and cause the conversion to
fail or, worse, appear to succeed but generate horrendous results.

  * Nested tables do not work. There is no equivalent in nroff.

  * Table cells with extraneous colspan indicators display fine
    in HTML, but cause problems for the conversion.

    **Symptom:**
       Table lines are drawn after the table, instead of
       around it. (NOTE: That symptom can also occur when
       a table comes right down to the end of a page. To
       fix the problem, adjust the text to move the table up.)

  * <FORM> and <SCRIPT> tags are not allowed.
    (surprisingly, some imported pages included them)

  * <IMG> TAGS ARE NOT ALLOWED -- there is no nroff equivalent
    Alternatives:
      * Create a text-diagram in <pre>-format text
      * Put the diagram in a guides page and create a relative link
        (Relative links are converted to absolute during the
         conversion process.)

  * Ordered lists that use roman numerals are not allowed.
    (Other kinds of lists are fine.)

STYLE NOTES
-----------
These are things that lead to better HTML pages and/or better
conversions into man pages:

  * ALL LINKS SHOULD BE RELATIVE
    That way, they keep working properly in a new release.
    They're converted to absolute links when man pages are
    generated (now), and when creating the downloadable doc bundle (soon).
    See notes below for more information on links.

  * A TOC list, if one is present, must be one of:

     o An unordered list <ul> in which the first entry is a
       link to "Synopsis" or "SYNOPSIS".

     o An <h2> tag with the value Contents or CONTENTS.
       (Everything down to the next <h2> is removed, including
        intervening <h1> tags, if any.

  * Tools pages should be attached to the tools stylesheet. From
    any tools/ subdirectory, the path is ../../css/tools.css

    Note:
       Feel free to modify the stylesheet in any way that makes
       sense. To be sure that your modifications *do* make sense,
       create a test page and test the conversion:
            % pubsmake man                # do the conversion
            % solaris_man <testfilename>  # see the results

  * Anchor-name tags should end with </a>. If they don't have any
    ending, or end with an XML-style "... />", they cause the
    css style for link-rollover to be applied to all text that comes
    after the anchor name.

  * Links should occupy an entire phrase, preferably at the
    end of a line, ideally at the end of the paragraph.

    Reason: The link is added as text. Since links tend to be
    long, they break up the flow of the text. So use this:

      o On windows, use _xyz_

    If you have this:

      o Use _xyz_ on windows

    It becomes

      o Use xyz @ http://java.sun.com/javase/6/docs/technotes/tools/share/xyz.html
        on windows.

    For links to tools pages, see the note below.

  * Links to Tools Pages
    --------------------
    Here's how to code links so they work online and when converted.

    Synopsis
    ~~~~~~~~
    When linking to a tool in the solaris/ directory,
    route the user through the index page, since there is
    always a corresponding page in the windows/ directory.
    So instead of this:

      <a href="../solaris/java.html">solaris/linux java
      <a href="../windows/java.html">windows java

    code this:

      <a href="../index.html#java>java</a>

    When linking to a tool in the share/ directory, on the
    other hand, you can code the link normally, since the
    same page is displayed for all operating systems:

      <a href="../share/xjc.html>xjc</a>

    (Of course, you can also go through the index page.
     You might want to do so for consistency, but it's
     not absolutely necessary.)

    EXPLANATION
    ~~~~~~~~~~~
    When a tool is referenced in a man page, it uses a
    format like this: java(1). That is the expected form
    for such references in a man page. Some editors like
    xemacs even recognize that form and convert them into
    a clickable reference to the local man page.

    Web pages, on the other hand, need links. And the link
    text wants to read as "java", not "java(1)". The problem
    for the conversion process, then, is to recognize links
    to tool pages and, rather than displaying the URLs,
    substitute the appropriate man page reference, instead.

    So where _Tutorial_ becomes "Tutorial @ http://some_URL",
    a link to _jmap_ needs to become "jmap(1)".

    To do that, the following link formats are recognized
    and converted to the standard man page form:

      o <a href="../share/jmap.html">...  -- from solaris/
      o <a href="jmap.html">...             -- from share/
      o <a href="../index.html#classpath">... --all other

    The last form is particularly important. In a web page,
    the user's system is unknown, so it is desirable to put
    in multiple links:

      o java [_solaris and linux_] [_windows_]
      o See the _classpath doc_ for solaris and linux, or see
        the _classpath doc_ for windows.

    But a man page displays on a single system. So a link
    to the windows version of the classpath, for example,
    is pointless in a linux man page.

    The solution is to route the HTML reader through an
    additional link:
      See Also:
        * <a href="../index.html#java">java</a>

    That link takes the user to an anchor on the index page.
    There, the reader will find a summary of the tool and
    links to the different operating system pages:

       java [_solaris and linux_] [_windows_]
    or
       java [_solaris_] [_linux_] [_windows_]