Re: Editors

From: Beth (BethStone21_at_hotmail.NOSPICEDHAM.com)
Date: 02/29/04 

Date: Sun, 29 Feb 2004 03:18:56 -0000

Randy Hyde wrote:
> Beth wrote:
> > I just spent the day doing it too from the big long HTML version
Randy
> > has on Webster (nothing more than splitting it up into one HTML
file
> > for each chapter...dealing with the "index", though, is going to
be a
> > much more complicated task...but it would be nice to have that
catered
> > for and automated ;)...and it's come out at only 454KB with me
> > here...were you working directly from the PDF file or doing like I
did
> > and simply split up the big HTML version Randy's already got?
>
> I wish you had emailed me first.

Hey, me and Roy and others would wish that you'd release these things
in something easier to browse than PDF files...to the point that both
of us can't be bothered to wait for you to get the message on the
constant "PDF files are crap!!!" comments that people make all the
time (what was that you were telling Rene about listening to your
users? ;) and would take on the necessary work involved...but, there
we are...you don't always get what you want...

> I could have given you RTF files that would have made the job
> a *whole* lot easier.

Ummm, RTF files wouldn't have made it easier at all because _HTML
Help_ uses HTML files...it's _WinHelp_ (the _OLD_ Windows help system
;) that you're thinking of which uses RTF files...since Windows 95 -
which about a decade ago now - Microsoft switched to these CHM files,
which is actually kind of like a ZIP file for HTML pages (it stores
them all together with its own internal file system and compresses
them :) and which has support for an extra "pane" to the left with
"table of contents" and "index" and "search" stuff built-in...the
other useful thing about this method is that, being HTML files, you
can also put the same files onto Webster for on-line browsing or GZIP
them for Linux and so on, to make it useable for non-Windows people
too...

> The HLA documentation (indeed, almost all of my documentation)
> is maintained in Adobe Framemaker. Framemaker automatically
> emits HTML and PDF formats (among others, such as RTF).
> Indeed, for the "splitting it up into separate chapters" issue,
Framemaker
> can automatically do that, too.

Then why ain't you done this for the reference stuff already?

AoA is different; It's a _book_...it's linear...it's cover to
cover...but _reference material_ is a pain in the arse to try to jump
straight to the answers you're looking for with these big, long HTML
or PDF files you make available...this stuff is _naturally non-linear_
and, thus, we've got the good old "square peg in a circular hole"
problem...Intel's PDFs are similarly a right royal pain in the ***
for the same reason...some people don't have printers, some people
don't like print-outs, some people can't afford to waste the paper and
ink...hence, the PDF "advantage" entirely dies for such people and it
becomes a _disadvantage_ instead to scroll around in Acrobat, which
likes to take ages accurately rendering the letter "p" with infinite
accuracy than, ooh, getting the thing up on the screen for you to read
it...all programmers need to quickly look up the syntax of something
or the parameters of a certain library functions as they are
programming (it's temporarily slipped their mind...they just want to
look at the syntax or parameters of options and that's it...dragging
up and down searching for it is not particularly useful :)...big, long
HTML or PDF files are _crap_ for this...they are a bit "sucky"...

Since the invention of the hyperlink, this sort of material has to be
authored with both linear and non-linear access in mind...yes, write
it as a linear book if necessary but make sure that it can be accessed
something like: "Crap! How does that label section thing work again?",
double-click, click, click and there we are, the chapter about "label
sections" is there...also, of course, to support this kind of access,
then things should be written so that you can directly read that
chapter without looking at any other one to find your information (or,
if you need to refer to something else, then there's a _hyperlink_
taking you there and a "back" button to return after reading the
"background information" on another page :)...you've got writing
things non-linearly right...it can read like this...no problems
there...

But _accessing_ the reference information is not particularly
"friendly" enough...too much "white noise" on the line with a big
"table of contents" to scroll through...have a little look at the CHM
file I've sent to you...just think to yourself some random question
like: "What are the procedure options again?" or "I need to know the
syntax of a particular MMX instruction"...and then open up the CHM
file and try to go directly to it...note that the "table of contents"
is automatically in a hierachy "tree" thingy...so, you don't have to
scroll through the whole thing, you just look for "HLA language
elements", open that up, look for "procedures", open that up and there
it is! Looking up an instruction? Well, you can see that chapter 14 is
"the 80x86 instruction set in HLA" and just open that and look for
"MMX instructions"...

Now, after trying this out and feeling the speed, simplicity and
focus, do the following...right-click on the "table of contents" pane
to the left...there's a "open all" option...then, leaving all the
branches open and the full hierarchy exposed, try to locate that same
information again...oh dear, we're scrolling up and down, reading all
these entries that have nothing to do with what we want because the
"contents" is so large there's no way to see it all at once...there's
an awful lot of "white noise" drowning out a simple task that has
nothing to do with locating the stuff we want...

Now, one step further back again, open up the PDF file and try the
same "enquiries" once more...this time, you've got to scroll up and
down the "table of contents" at the start and it changes the whole
screen to that thing when you click on it so you can't see the
"contents" anymore...hence, you've got to hit the "back" button and do
it again...due to the size of these PDFs, the scroll bar is somewhat
useless...that is, if you grab the scroll thumb and move it up or down
even slightly because the file is so big and the scroll bar is in
proportion to that then even a small movement jumps 6 chapters in
either direction...so, you've got to either manually drag the text up
and down with the hand cursor or click on the actual scrolling arrows
(which are all the way at the top-right and bottom-right, widely
spaced from each other so that if you go too far in one direction,
you've got to travel the vertical length of the screen almost just to
tap it back up one or two times :)...

This, by the way, is a problem with _all_ PDF files in Acrobat of a
reasonable size...the scrolling problem is ten times worse with
Intel's volume 2 instruction set because the file is massive...also,
the "table of contents" is laid out completely flat rather than in an
expandable / collapsable tree so you're getting all this extra "white
noise" distracting you (you can't see the whole contents on one screen
so you're forced to scroll up and down - with all those scrolling
issues in Acrobat with large PDFs - reading off loads of entries
searching for the one you're looking for :)...when you jump to a
chapter, the whole display changes to that and you can't look at the
"contents" anymore...one really useful thing - cuts down on the "white
noise" distractions once more - is the ability to only change pages to
the actual entries you want...if you trying "browsing" (random
wandering) with the PDF files and then with the CHM file and it's
always visible "table of contents", then the difference should be
really apparent...the CHM file wins for ease and lack of confusion
(you can get similar "bookmark" functionality in Acrobat with PDF
files - I've seen a couple of files like this - but you don't seem to
make use of that)...

Perhaps there's bias for you here in that you know this information
already and you wrote the references, so you can't appreciate all the
distracting "white noise" that annoys everyone else...in which case,
grab something like the DirectX CHM files and the Intel PDF file for
the instruction set and compare those to get an appreciation of the
issues here...

Think this is trivial? Guess again...I'm happily a supporter of HLA
but I find this stuff so annoying that, yeah, I'm prepared to spend a
whole day trying to fix it and wade through tons of horrible
auto-generated HTML to do so...it really is that bad that the torture
of doing this seems _preferable_ to the torture of yet another bloody
PDF file and Acrobat's annoying badly design "browsing" and scrolling
stuff which means you're actually often having to _FIGHT_ with your
documentation...which is, of course, an absolutely stupidly ludicrous
situation...this stuff should be "handy", NOT a "declaration of war"
with your PDF viewer(!!!)...

Just me? Nope, Roy Jones here talks about how he's also been prepared
to take on the same large effort to do it - "fix" things - with AoA
(I'm not so interested in AoA and there's an argument that it's not so
"non-linear" that this stuff isn't so important because, most times,
you are just moving from cover to cover as you follow the
"course"...the reference material, though, should NOT be treated that
way because the information is inherently "non-linear" and, without
doubt, people will want to access it that way :)...

Just us two? Nah, far from it...why did I have to do that "RTFM" stuff
to Frank? Because, of course, Frank _knows_ that the information is in
those PDFs and he knows all about "RTFM" as the solution to so many
problems...he also has, I'm sure, no doubts about the
comprehensiveness of your documentation...the real reason? Yeah,
despite nagging at Frank about this, I _DO_ know why he wasn't
"RTFMing"...it's that bloody PDF file format again!!! It's a pain in
the arse to "browse" and, correspondingly, I'm guessing Frank has that
same "PDF dread" that many, many people suffer: "Oh, crap! It's a PDF
file! Ah, forget it!! I'd rather stay ignorant!! I'd rather stick pins
in my eyes repeatedly than fight with that Acrobat reader ever
again!!"...

Then, there's good money that would suggest - listening to his
comments - that Wannabee saw those PDFs...he also got a face full of
"white noise" distraction...he's thinking: "okay, so how do we use
these instructions?", only to get a faceful of a massive "table of
contents" full of words he has absolutely no appreciation for at all:
"iterators", "context-free macro invocation", "object-orientation
under HLA", etc....and, _REASONABLY_, being forced to browse over all
this what-looks-like-voodoo-black-magic-spells stuff, full of words he
can't yet appreciate as a beginner (heck, these words throw long-time
ASM coders sideways because many are concepts loaned from the HLL
world)...he decides "sod this for a game of darts!!" and finds
"B_U_ASM" much more entertaining to use..._even with_ the political
rants, bad English and so forth in it...why? Because it's _non-linear_
from the ground up...and that's how _REFERENCES_ should be...yes, you
can still write it in a "book" fashion that it _could_ be read "cover
to cover" but if you compell people to do this from your structure
then Rene's "fascist" taunts take on a degree of truth in that forcing
people to read things like a book when that's NOT the most useful form
for them is comparable to Rene's "thought police" restrictions on
using libraries...you're getting the _author's opinions_ about
libraries or how great PDF files are and you're NOT getting what you
want directly and easily with no fuss and, importantly, no "white
noise" distractions...

And we ain't finished because what is Rene's _chief attack_ on you?
Calling you "Master PDF"...because he _KNOWS_ he's onto a winner
there...I like the actual documentation...the actual text is
great...understand that there's no complaint about the _content_ at
all...that's what I was trying to recommend Frank to look at because,
indeed, you're comprehensive and all Frank's questions are suitably
answered in the documentation...but when it comes to "what do you
think of PDF files?"...well, sorry, Rene's corner is looking much more
tempting than your own on this score...

Straight down the line, the _MAIN COMPLAINT_ here is the bloody PDF
files!! Now, much of that is to do with Adobe's Acrobat viewer have
horrible controls that means you're fighting with the thing all the
time...but regardless of who's "at fault", the HLA documentation _IS_
suffering big-time because it's in PDF format...the _only_ advantage
is that the stuff prints out nicely...but then with the size of these
things, even if someone does have a printer, do they have the entire
morning and a rainforest of paper to print it out...and some people
prefer the treeware in their hand, it's true...but some others aren't
particularly impressed with the "weight lifting" and "animated
flipbook" exercises that take a while, just to look up _one_ set of
parameters for _one_ standard library function...AoA is arguably
different but for the _references_, you really want to be able to jump
in and jump out in a matter of _seconds_...or to be able to browse the
standard library...

Because there's another reason beyond "advanced programming" why I
never use the standard library...finding out what's in it is actually
a whole lot easier by browsing the directories in Explorer (because at
least that's hierarchical so you can look at "sections" at a time :)
than it is looking through that PDF (and the "table of contents"
automatically generated for the standard library reference is a bit,
well, _horrible_...what people really want here is, of course,
something like a big "I/O functions" heading and, under that, a
"standard input" heading, "standard output" heading and a "file I/O"
heading...then, under those, the respective functions...

I mean, you know the arguments already...that's why those standard
library functions are split off into "namespaces", right? Why you
format the directories into "groups" and the MAKE files are
"hierarchical" to create the library...why large-scale programs
benefit from the "hierarchy" of thing like OOP...why we have "scope"
and "nested" this and "nested" that...

Well, simply, there's NO DIFFERENCE when it comes to the
documentation...it should be _similarly structured_ or it turns out to
be a _HINDERANCE_ rather than a help...that "table of contents" on the
standard library reference is like a whole bunch of "global variables"
that it seems we're expected to all comprehend in totality like the
"hacker" who hands us code full of global variables and then declares
"hey, it's easy to understand when you've been immersed in the
variables for the last six months!!"...you're documenting something
that's split into groups and hierarchies and stuff but then if you
want to access the information quickly, you're presented with an
"index" that's got it all laid out flat and isn't even properly
alphabetical(!!!) so you've got to look through the whole thing just
in case there's a "c" entry _after_ the predominantly "s"
entries...that "index" on that reference is so awkward, in fact,
you've got to ask yourself if it would even end up better NOT to have
one at all...it's that complicated to use when it's really a somewhat
random list of functions...worse, the actual library _IS_ correctly
split up into convenient "groups" so it's kind of working
backwards...you're presented with a "randomly ordered global
variables" index to something that's actually well structured...

I 100% stand by what I was saying that _IF_ you can get passed these
_superficial_ issues with HLA - e.g. that it's a compiler on top of an
assembler rather than an assembler itself...that the "HLL syntax" is
deceptive, making you think things are "higher level" than they
actually are...that once you find the page in the PDF you want, the
documentation _IS_ comprehensive, well-written and answers all your
questions...etc., etc. - then _HLA itself_ is brilliant...

But, enough is enough...the _INJUSTICE_ you do to HLA by using those
bloody PDF files is offensive...I mean, that is one _valid_ criticism
that Rene rides all the time, knowing he's onto a winner...it's
probably a very large part of the reason you've lost a few "newbies"
like Wannabee...it's why Frank was openly asking questions which
_should_ be easily answered by "RTFM" (I said that to Frank BUT, on
the other hand, I _DO_ perfectly understand _why_ he hadn't done the
obvious when it's in a PDF file ;)...it has driven Roy Jones and
myself at the very least to contemplate taking on volumes of work and
giving up a day or two just to get the documentation into a _useable_
state...I support HLA on here more than anyone else except yourself,
probably, but I _can't_ bring myself to defend PDF files for even a
second...it's just one notch lower than defending Microsoft, so to
speak...

And why you think that everyone was nagging you over and over: "When's
the tree-ware version of AoA turning up?"...hey, they'd rather _PAY_
than use those bloody PDF files _for free_!!!

Am I getting the message across? Because I sure Hope I am...as I'm
quite serious that half the problems of acceptance you're getting with
HLA is in no small part thanks to those PDF files...except for Adobe,
you might be about the only person in existence who actually _likes_
them...when Rene says "Master PDF", he's totally wrong about the
_quality of the content_ but the actual use of "PDF" as an insult is
maintained by Rene exactly because it's one of those things that Rene
actually gets right from time to time...he literally tells his users:
"if you use HLA, you need to read PDF files...if you use RosAsm, I
have a custom-built help file that's easy to browse" and actually
_wins_ many people over _on that argument alone_...

There are some who are "indifferent" to PDF files, of course...but
there's an awful lot who _DESPISE_ them with a passion...HTML is not
just "neutral" with regards to being viewable on practically all
platforms (including mobile phones, for Pete's sake ;)...it's also
"neutral" with regard to people's opinions on the format...it's "text
files with tags" so who's going to worry about that? But PDFs are
another thing...Adobe's viewer is _slow_ and _awkward_...the "linear"
format that the HLA documentation is biased towards at the moment is
_horrible to use_ (the content, I stress, is _GREAT_...it's getting
access to that content which is horrible ;)...that standard library
index is distinctly _amateur_ that it's really surprising to see you
produce something like that because you're normally the first to
expect to do a far, far better job than, well, scattering your "global
variables" into a "flat" list that's _NOT EVEN ALPHABETICAL_, for
Pete's sake!!

_HLA itself_ is of very, very good quality...that's why I support it
and it does make other tools look a touch silly in comparison...the
_presentation_ of HLA in places, though, is not particularly
good...and if you look to VHS vs. Betamax, Microsoft vs. people who
actually know how to program, etc., etc. then the lesson is
clear...you could have "World Peace" in quality terms but when your
presentation sucks, it'll go nowhere...what you're getting is down to
the _quality_ alone...but, in a sense, that quality is having to
_fight_ against its presentation...this, to my mind, is an INJUSTICE
you're forcing on yourself...

Hopefully, as you know I'm supportive in all other regards, you'll
realise this isn't a "Rene post" just criticising for the sake of
it...in fact, I've been "polite" thus far on the issue because it can
be "tolerated" to a degree and you are "prototyping" and stuff so it's
always possible that what we're seeing is "temporary" (but doesn't
appear to be so after waiting around for something _useful_ other than
PDF to appear ;)...

It is a load of crap but it's fact: Success is 99% presentation
_regardless_ of the actual quality...I mean, one only needs to look at
the immense amount of cheap, tacky plastic goods out there that fall
apart in five minutes and never did what they were supposed to do,
anyway...but their makers are successful because they had a cool ad
for it...it's exactly that crap and superficial, indeed...but it's the
truth of it in a nutshell...

> > There's also room for improving this because the big HTML file is
full
> > of automatically generated "<A></A>" tags everywhere for the
"index"
> > stuff...but this stuff would need to be changed and fixed now that
> > I've split up the file into multiple smaller files (the URLs would
be
> > all wrong :)...
>
> Framemaker's HTML generation is notoriously bloated.

I actually just waded through it to do this...hence, I know first-hand
how horrible it is...it's not just the bloat, it's the fact that it
just dumps it all as one incredibly long line with no spacing at
all...it's next to impossible to read...

> Of course,
> Adobe's GoLive is even worse. Fortunately, as a ZIP file most of
> that bloat goes away (and on a local machine, it's not that much of
> a concern).

CHM files automatically compress the stuff in addition to the vastly
superior navigation stuff...hint, hint ;)

> I've always thought that a cool program to have would be an
> "HTML optimizer". A program that cleans up an HTML file
> and removes unnecessary tags from the file (without altering
> how it displays). Anyone know of such a program?
> If not, anyone game for writing it?

Don't know of such a program and it would be cool and it is tempting
to consider writing it but thinking more over what's involved, I think
I'll happily "defer" this utility to someone else to code ;)...

> > so, in creating the "index" - a tricky task because the
> > PDF works with "page numbers", which is awkward to convert...the
other
> > stuff is pretty "automatic" to do (which is why something as big
as
> > the HLA reference could be done reasonably well in just a day :)
but
> > changing the "index" into an appropriate form for the CHM file
(now
> > that all the URLs are basically "broken" because it's in multiple
> > files, not just one big one :) looks like it would have to simply
be a
> > long, hard slog through each "index" entry and the page numbers,
> > putting in link targets and that sort of stuff _manually_ - this
stuff
> > will have to be "corrected" on a case by case basis...not looking
> > forward to that...
>
> This is where using an RTF file would come in real handy.

Not for CHM files, it wouldn't...they contain _HTML_ files and RTF
ain't supported...RTF would only fractionally be more useful than the
PDF files...it would need conversion...

Again, it's _WinHelp_ that uses RTF...the new (I say "new" but it's
since Win95, which is now coming up to a decade old ;) Windows help
system uses _HTML_ pages...a CHM file, basically, is like a ZIP file
specifically for storing HTML files (and other related files like
images, .CSS files, etc. :) into one file that automatically has
"table of contents" and "index" stuff built-in, which is provided
automatically by the CHM "viewer" application (which everyone who has
Windows should automatically have already because Windows' own help
files are in CHM format...it's the default help format and comes
"built-in" to all 32-bit Windows :)...

Microsoft even provide a little ActiveX thingy that can be used on a
website to get the "table of contents" and "index" stuff working
without CHM support (still Windows specific, mind you, but then this
is Microsoft, of course ;)...and the files can always be "ejected" out
of the CHM and just used as ordinary HTML files a la any website...

RTF files don't come into this and would prove more horrible than what
I've already done...

Perhaps you ain't looked this stuff up in a while or something...in
which case, look for "HTML Help" (NOT "WinHelp", which was the old
stuff that used RTF files :) and "HTML Help Workshop" (which puts them
together...it's a terribly buggy utility full of "this isn't quite
finished" functionality but once used to its "quirks", you can
navigate through them to get something working, anyway :)...

> > But I've got the stuff as a whole bunch of HTML files, one for
each
> > "chapter" and it's good enough to simply browse around and
read...the
> > "index" doesn't work - although this is one of the better features
> > available that it should be fixed - but it's still a whole lot
nicer
> > to navigate than the PDF files...
>
> This is also where an RTF file would come in real handy.

Not for CHM files, it wouldn't be...handy for the older WinHelp stuff,
perhaps, though...and that _is_ still supported by Windows...just it's
not as "handy" as the newer "HTML Help" with the built-in secondary
panes for "contents", "index" and "search" that means you can browse
around at any time...

Again, I sent you the CHM file of what I've done so far...actually
launch it and give it a go to see the help system I mean and look at
the automatic "tab" stuff which makes navigation a lot, lot easier
than most other systems (although, "Xman" had the "two screens" help
system idea first...because, of course, Microsoft innovate _nothing_
and just pretend they do ;)...

> > I was about to send an Email to Randy to see if he'd be interested
in
> > this...450KB isn't too bad considering the size of the text...it
was
> > only because I was thinking about the Linux people too - ".CHM"
files
> > only work with Windows' help viewer thingy - that I was going to
add
> > some "navigation" onto the HTML files themselves (you know, a
bunch of
> > "previous", "next", "up" links at the top of each HTML page so
that
> > they are all linked together and can be browsed _without_ the
"table
> > of contents" widget thingy that CHM files have :)
>
> I don't know if Framemaker has any type of support for CHM files,
> but as long as I can output RTF, Word can easily generate the
> CHM files.

Really? Word does that? Are you sure you're not confusing the HTML
Help ".CHM" files for the older ".HLP" WinHelp files? Those _did_ use
RTF files...this new "HTML Help" doesn't and, as the name suggests, is
HTML-based (because even Microsoft realise that more people are
willing to use such a system when the content can be re-used for
"on-line viewing" on a website as well as being packed into a CHM file
for convenient "local off-line" viewing :)...

> As for breaking up the HTML file into a bunch of smaller
> files, Framemaker *can* do this automatically (well, you have to
> create a "template" first, but it's automatic after that).

So press the buttons and do it!!! This is what so many people out
there have been waiting for instead of the bloody PDF files!!!
Something that's split up into nice, small convenient "sections" with
a nice "tree" index to jump around the place and so forth...

Again, _look_ at the CHM file I've provided to see the
difference...each "chapter" (well, "section" but let's not get this
confused with things like the "label section" or it becomes the "label
section section" ;) has its own page and the scroll bar is actually
reasonably used (being smaller, the proportions mean that moving the
scroll thumb a small amount doesn't suddenly jump half-way across the
file! ;)...you can look things up in convenient "chunks" and jump to
where you want easily...blah-blah-blah...

This is what your users are crying out for!! It's the _chief
complaint_ people are giving you...Rene: "Master PDF"...Wannabee: "Too
much information! Overload! Overload! Aaah, RosAsm is so much easier
on the brain!"...Frank: "Is that a machine instruction? Is that a
macro? RTFM?? What those PDF files? Nah, thank you but I'd rather
not!"...Roy: "I've spent all my time also converting things into a
better format, Beth...yes, it's a lot of work but it's a lesser
torture than using PDF files!!"...me: "Randy!! Sort it
out!!!"...blah-blah-blah...it's all got a common ancestory and it's
name is "PDF"!!! ;)

> > so that Linux users
> > can also have it but just as a bunch of loose, separate HTML
> > files...just stuff them into a ZIP file or whatever...this is one
of
> > the better things in Microsoft's decision to go with HTML for
their
> > newer "help" stuff than the WinHelp things they had before...as a
CHM
> > file, then that's much better because of the "contents", "index"
and
> > "search" tabs that are always available and the compression stuff
> > keeping the files all together compressed, much like a ZIP
file...BUT
> > you can also re-use the same HTML pages on a web site or as a
download
> > for non-Windows machines where the "CHM" files aren't
supported...that
> > was the "delay" in letting Randy know I'd done this, really...I
wanted
> > to "fine tune" it - double-check links, add "in-page" navigation
for
> > Linux or putting it up on Webster directly - before handing it to
him,
> > if he's interested...
>
> Hard to say. Though downloading the entire HTML file at once is
> a bit of a drag for those without broadband, being able to search
through
> the entire reference manual or stdlib documentation is nice, too.

Nope, sorry...but having it split up into individual sections with a
convenient index and things are "grouped" and so on, is a 100 times
better to search than one long file...where the smallest movement of
the scroll thumb jumps twenty chapters in either direction due to the
"proportionality" of the scroll bar (e.g. big file = harder to move
around with scroll bar reasonably because you're actions are
exaggerated by the "proportions" of such a massive file :)...you know
I didn't even consider the "bandwidth" thing but, in fact, that's just
the straw that breaks the camel's back...for those people, it must be
absolute murder because it's bad enough when the things download
quickly...if you also had to wait forever before you could "enjoy" the
torture of fighting with some massive PDF file, then I wouldn't be
surprised to hear if you have NO 56K modem users whatsoever...

> > But a 450KB download off Webster doesn't seem too bad, does it? In
> > fact, it's 1.29MB(!!) as just one long HTML file that it's
actually
> > much smaller as a CHM file, due to the compression that these
files
> > use automatically for the HTML pages...
>
> :-)

See? It's _smaller_ even! The PDFs might be great for printing but
that's about it...and people - if they _do_ print it out at all - only
have to do that _once_...on the other hand, they'll want to quickly
look up a particular chapter or library function directly in a matter
of seconds whilst programming to remind themselves of what is
what...and, on this score, your current long, long, long HTML and PDF
files are not very good at that...there's the "white noise
distraction" of looking through all those other entries to find the
one you want (compare to the collapsable hierarchical tree in the CHM
file I gave you to see how much nicer on the brain it is to be able to
avoid this "white noise" by searching for things hierarchically by
"grouping" :)...there's the scroll bar problem that happens to
anything that scrolls over a massive range: You only lightly touch the
scroll thumb and suddenly you're on the other side of the known
universe(!!)...there's that horrible, horrible "index" on the standard
library reference which is not only "flat" but not even properly
alphabetical with hundreds of entries, meaning it's kind of "pot luck"
looking up the function you want or you have to look through the
entire list...Adobe's Acrobat reader is badly designed and renders
things far too slowly for browsing because its obsession is with
"accurate rendering"...you use the hand cursor to move the text up and
down and, oops, oh dear, you happen to go over a link and when you
meant to scroll, you've actually "teleported" over to the other side
of the document (and then the tiny unlabelled "back" button looks
almost the same as the "go to the start" button so you accidentally
click the wrong one and end up in totally the wrong place)...there's
the fact that it's not particularly searchable for keywords..."page
numbers" are only useful when you've printed it out...the "plug-in"
for PDF takes forever to load into a browser...the PDF files aren't as
small or bandwidth friendly...neither is having it as one long
file...and I _AIN'T_ got anywhere near the end of the list of
complaints here...

Hopefully, the message is getting across...you're the only one in the
known universe who _likes_ PDF files...okay, that's an exaggeration
but putting it that bluntly might kind of help get the message
across...this isn't the format your users actually want...it gets in
the way and is akward, in fact...what's been missing and everyone is
crying out for is exactly the thing you keep NOT doing...and it's
strange because when it comes to _code_, you're putting things into
neat groups...advocating _MODULAR PROGRAMMING_ where each "groups" is
split off into lots of small files...

Don't you get it, Randy? You're telling Rene how bad "monofile
programming" is...but then you go off and use "monofile
documentation"!!! Worse, "monofile documentation" for something that's
actually _modular_ in design and how it's written...even worse still,
the "standard library" is _very modular_ - which is good - but then
actually ends up with the most useless _flat_, random,
non-alphabetical "scattered global variable" index that I've ever had
the displeasure of looking at...surely you can appreciate the concept
that if the library is modular then the documentation should be
equally so...

Note, the _content_ here is perfectly fine...it's just proving awkward
and impossible for many of your users to access properly due to the
total lack of "navigation"...on the contrary, I find it a total
nightmare to "browse" in comparison...put it this way, the verb
"browse" in its computer context didn't exist _until_ the invention
and adoption of the _HYPERLINK_ in the world wide web...that is NOT by
coincidence...

Beth :)