Re: [boost] Re: A Formal Review Request

From: Ed Brey (brey_at_[hidden])
Date: 2000-10-10 15:02:00

[Discussion of large quantity of changes to operators library
documentation.]

From: "David Abrahams" <abrahams_at_[hidden]>
>
> 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.

You might try browsing each version of the page with lynx.  For each
version, use the print command ("p") and choose to print to a file.  The
print command saves a formatted plain-text version of the file.  This makes
for versions of the files that are both readable and diff-friendly.  I tried
it and it worked pretty well.  Almost all the lines highlighted by the diff
tool were due to substantive improvements in the new version.  There are
quite a few small changes, but a lot of small improvements can be just as
valuable as a few big changes.

Here's my two cents about the HTML changes (there's always a cost for
advice, right? :-). Based on my intermediate-level HTML knowledge, Daryle's
changes look like a move in the right direction, from a technical point of
view.  HTML authors have gotten away with trouble for a while due to the
prevalence of a small number of very popular browsers.  However, this does
eventually break down.  Just a quick example: lynx rendered the section
headings centered and in all caps in the original, because the section
headings were tagged with <H1>.  Such a strong heading was probably not the
intent, but was never caught since on GUI browsers, the difference between
H1 and H2 is more subtle.

To me it seems only fitting that a group committed to writing
standard-conforming C++ would produce standard-conforming HTML.  While HTML
is not the focus, and so a much lower priority, I welcome the work of an
experienced HTML-writer to enhance over what Microsoft's tools may generate.
As for maintenance, I believe that even maintainers unfamiliar with details
of HTML will find that reading valid HTML submissions can be done with
pythonesque ease (as long as there's a way to easily see version
differences), since the language is pretty simple.  Reading the raw HTML
could be made even more painless if we could introduce CSS, but given that
Microsoft's standard CSS conformance is poor and Netscape's is abysmal, the
timing just isn't right (but think of the fun we could have with conformance
flames and laments :-).  (Of course, I've also found a non-conformance
problem in the CSS validator promoted by the W3C that I can't seem to get
the maintainer to fix. :-( )