J3/02-299

Date:     22 Oct 2002
To:       J3
From:     Richard Maine
Subject:  Changes in pdf and dvi generation

I'd like to thank Jesper Harder for doing most of the hard parts
of the fixes proposed in this paper.  Van Snyder did most of the
rest. I did little more than test and comment on their various
attempts...and write this paper.

This paper proposes changes to improve the interactive usability
of pdf and dvi files for the draft standard.  None of these are
intended to change a single word of the text of the standard or
its appearance when printed in black and white on paper.  This
makes them even more purely editorial than such things as typo
corrections.

The issues addressed by these changes are:

1. Color abnormalities in the Annexes.

2. Completely black notes when viewed with some versions of xdvi.

3. Lack of "live" interactive links in the table of contents and
   index.

The proposed resolutions of these issues are

1. Turn off the blue coloration of the Annexes.  It was intended
   to indicate non-normative material, but since everything in
   all of the Annexes is non-normative, the color isn't very
   helpful.  It is just distracting to have over a hundred pages
   all in blue (even without the abnormalities that left some
   parts black).

   Nothing in the document even mentioned this color convention
   anyway (which was a good thing, as the printed document
   presumably won't have color).

2. Provide an option to easily turn off the gray backgrounds of
   notes.  This would be defaulted to the same as currently
   used, but would allow the default to be overridden without
   editing the files of the 007.  I'm not sure whether anyone
   other than Van actually uses xdvi for the 007, but this edit
   is trivial enough to do.

   Related to this, the low-level implementation of the note
   environment was abstracted enough to allow note, xnote, and
   jnote to all be trivial special cases of it.  This avoids
   having multiple almost-duplicate copies of the implementation,
   which then are subject to skew.  (Gee - just like one of the
   reasons for subroutines).  In particular, xnote and jnote
   weren't redone when, several revisions back, note was majorly
   reimplemented.  As a result of this skew, the color option was
   going to need diferent implementations for note vs xnote/jnote.

   The xnote environment isn't actually used in the 007, but is
   for meeting papers.

   And I deleted the jnote environment for j3 notes (insomuch as
   we have retired all the j3 notes and I don't expect to add any
   new ones), but it is now trivial to do using the abstracted
   low-level note.

3. Fixing this was substantially harder and is mostly due to
   Jesper and Van as mentioned above.  The fix makes use of
   a package called hyperref, which is included in standard
   Tex distributions.  However, Van and I hadn't formerly been
   able to get it to work for the 007.  The result is that
   all xrefs in the pdf and dvi files are now "live" in that
   clicking on them will follow them.  This includes those
   in the index and table of contents.

   Also, the introduction's references to the Annex were plain
   text instead of xrefs.  Changed them to live xrefs.

The actual edits aren't listed in this paper because it seems pointless.
(The editor already has them and the odds of anyone else even reading
them are negligible).  They are available on request and are generally
described below.

The only edit to the files constituting the body of the standard
is to globally replace the string "\ref{N" with "\nref{N".  This
is because other edits make \ref no longer include the word "Note"
in note xrefs, so we have a new \nref macro to add the word back in.

The j3.cls file has modest revision, much of which is to delete all
of its overriding definitions of the standard LaTeX xref macros.
The hyperindex package takes care of that, and does so more completely.
The edits to make gray note backgrounds optional and to combine the
note/xnote implementations are also in j3.cls.

The 007.tex file has small revisions to activate the hyperindex
package and to remove Annex coloration.

Each annex file has a one-line change to make an xref tag.  That
tag is then referenced at the end of intro.tex.

A current version of the open source hyperindex style file is
included in the tex directory of the 007 because some widely used
TeX distributions have an old version of this file (which doesn't
work for us).

A new small utility program in f90 is included in the util directory.
This program corrects the links in the index of the pdf version, which
otherwise were off by 16 pages (the number of pages prior to the
page numbered as page 1).  Van wrote this.

A revised Makefile to correctly accomodate the use of hyperindex.