Re: A Formal Review Request

From: Daryle Walker (darylew_at_[hidden])
Date: 2000-10-10 12:05:13

on 10/9/00 8:55 AM, David Abrahams at abrahams_at_[hidden] wrote:

> Looking at the .html documentation, it appears to have been a bit scrambled.

Comparing my version and the old version, it looks more like a hand-tailored
rewrite.  I'll give justifications below.

> Just for example, the "Arithmetic Operators" heading is out-of-place at the
> top of the page. In fact, many places I had an internal name reference have
> been incorrectly turned into a heading.

This is a HTML 4 feature.  HTML 4 allows tags to have IDs.  Furthermore,
these IDs can be targeted like the <a name> elements.  So I compacted the
destination elements into the header tags.

Why HTML 4?  Your version was basically HTML 3.2, except for the <TBODY>
tags used in your tables.  Those may have been the result of a brain-dead
automatic HTML editor, but instead of removing it to make the file HTML 3.2
compliant, I went the other way and maximized the file for HTML 4.  (I
downloaded the HTML 4 spec. just for this.)  This is partially responsible
for the massive changes.

Note to HTML writers: please make your code matches some official
specification.  Some automatic HTML editors can produce gnarly code, so some
hand-fixing may be required.  You can add a DOCTYPE tag (HTML 3.2, HTML 4
[several types], or XHTML 1 [several types]) after checking it.  The HTML
files I make for this and other projects were hand-edited with a bare-bones
HTML editor (PageSpinner), a HTML-Tidy plug-in, and a validating web browser
(iCab).

> Also, try not to make arbitrary
> changes to formatting and spacing of source code or documentation. The many
> "cosmetic changes", especially to the documentation (e.g. changing <h2> to
> <h3> everywhere) makes evaluating the changes with even the best automated
> diff tools nearly impossible. My diff tools are actually capable of ignoring
> whitespace differences (even line wrapping changes), but they are having too
> hard a time with your submission.

Maybe you could drop using the "diff" tool and accept the HTML file as an
original work not-so-loosely based on the current version.  Except for the
new operator tables, the two versions look similar in a web browser.  I
think my version may be easier to maintain.

Changes (that I remember):
- Removed some automation tags.  Not appropriate since I was hand-editing.
+ Changed some character constructs with advanced HTML entities (&equiv;).
+ Changed the format of the contributor section.  It was becoming unwieldy
in straight prose.  Added my name.  Also added a header to it.  (Actually,
it should come as a separate section before "Arithmetic Operators."  Maybe
we need a "Contents" section too.)
- Simple style changes.  The main title should be the only <H1> tag, so most
of the other header tags went down one level.  Used the <CITE> tag for file
names.  Rewrapped lines and adjusted spacing.
+ Re-did the operator template tables.  Moved explanations to table footers.
Made the column headers official headers.  Renamed some headers.  Added
captions, summaries, and column specifiers.  The arithmetic table was
originally split up because it was getting ridiculously large.  Later I
realized that it was inappropriate to mix the base operator templates with
combined operator templates, since the former needs three columns (name,
operations, and requirements) and the latter only needs two columns (name
and the templates it's based on).  Also, since I added new categories of
templates, the table split made it easier to add explanations of the new
stuff.
+ Fixed some links (from absolute [to the Boost web site] to relative).

> So, the first order of business, if you want these changes to be accepted,
> is to repair the documentation, and to try to keep it an incremental move
> away from what's currently in the release library so that the changes can be
> easily vetted.

After 20+ hours of hand-tailored art, I'm currently too burnt out to
re-re-implement the HTML file.  (That's partially why I moved to new
projects.)  It is complete to itself, and would totally replace the current
version if approved, so it's only an issue for your maintenance, and not for
the users.  Any new version would get a lot of changes from the current
version, from HTML clean-up and documenting new stuff in the header file
(nearly 44% increase by size).  Could you reconsider?

--