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_]