Re: [boost] Re: A Formal Review Request

From: David Abrahams (abrahams_at_[hidden])
Date: 2000-10-10 14:02:14

----- Original Message -----
From: "Daryle Walker" <darylew_at_[hidden]>

> 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.

I don't mean to devalue your hard work, but there really is a mistake here.
For example, follow the "Arithmetic operators" link near the top of the
page... aha, now I see that the mistake was present in the previous release,
too. Sorry about that. The link should refer to the Arithmetic Operators
Table. I'm not sure what else I was seeing, but I could have sworn there
were other places where a reference to a .

> Why HTML 4?  Your version was basically HTML 3.2, except for the <TBODY>
> tags used in your tables.

OK, so was the last version valid HTML 4?

>  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.

If the previous version was valid under HTML 4 this was strictly
unneccessary. If not, I am sympathetic, but wonder if the massive changes
were practically neccessary.

> 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).

Whew! Becoming an HTML expert at that level may not be a responsibility I'm
willing to accept in order to maintain a boost library. I think this may
apply to other participants, too. I realize it's a GOOD THING and all, but
practically speaking, is it neccessary? Our pages have worked fine so far...

> > 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.

Maybe, but it makes the job of evaluating your changes much harder. You have
to appreciate that I may not have the time to do this.

> Except for the
> new operator tables, the two versions look similar in a web browser.  I
> think my version may be easier to maintain.

Certainly it would be easier for you. Since you used HTML constructs I'm not
familiar with, it would be harder for me.

> Changes (that I remember):
> - Removed some automation tags.  Not appropriate since I was hand-editing.

An HTML idiot doesn't know what this means. I assume these relate to the
original version which Beman produced with FrontPage.

> + Changed some character constructs with advanced HTML entities (&equiv;).

Again, "duh?"

> + 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.)

Maybe this seems like a reasonable change.

> - Simple style changes.  The main title should be the only <H1> tag, so
most
> of the other header tags went down one level.

I guess that makes sense. The "Arithmetic Operators" heading is simply
out-of-place near the top of the file (don't know how that snuck in), so if
you take it out a whole bunch of <H3>s could become <H2> again, right?

> Used the <CITE> tag for file names.

Neccessary, or just a cute HTML4-ism?

> Rewrapped lines and adjusted spacing.

Seems reasonable, except maybe for the last one. It would have been much
easier for me if you'd left the line breaks alone.

> + Re-did the operator template tables.  Moved explanations to table
footers.

This one I really disagree with. Reading from top to bottom, the explanation
may not even be visible when you see the top part of the table. The standard
establishes a different precedent. And notice that it's not consistent in
operators.html, since the Dereference Operators has an equivalent Notation
section at the beginning.

> Made the column headers official headers.  Renamed some headers.  Added
> captions, summaries, and column specifiers.

The HTML-idiot says "huh?"

> 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.

OK

> + 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?

As the maintainer I'm responsible for seeing that the documentation
accurately describes everything it used to. I'm open to suggestions for how
I can do this.

Regards,
Dave