inform designer's manual problems


Thu, 28 Dec 1995 20:05:49 UTC

1. "Exercise" #1 is completely unfair, because the reader
presumably at that point has no idea of the concept of the
"general" attribute.

2. The reader is told to 'insert' code without being told
anything at all up to that point as to the general structure
of object definitions; so how does s/he know where/how to
insert?

3. "Exercise" #4 unfair! Reader has seen no examples of
Fake_action, and only the briefest of mentions has been made
of it, yet this example expects the reader to now create
code using it.

The "Exercise" seems like it should be an example instead.
And it is not even adequate as an example, as it is not very
well explained. The reader is told in the "Exercise" to
"declare a fake action", but nowhere has the reader ever
been told how to make such declarations. The execution of
the "OpenUp" mentioned at the end is given no example
either, leaving the novice at this point completely gasping
for air (having forgotten to breath while trying to
understand this new concept that has not been at all
explained and yet seems it is expected to be self evident).

4. Not only is there no overview of the Object definition
structure and the reader is told to insert code, without
being told where or how to insert it, but there is no
overview of the story file structure, and suddenly the
reader is told to insert various "includes", but not told
where.

5. Example of the Dart Board (pg 27) suddenly uses an "ELSE"
structure. Conditional branches have not up to this point
been explained at all.

6. "Exercise" #5 INCOMPREHENSIBLE explanation.

7. "Exercise" #7, the Mayan compass is a lesson, yet it's
called an Exercise, as if the student is to complete it on
their own.

8. "Exercise" #8 UNFAIR -- the reader knows nothing of the
"swapdirs" function and is told to devise a way to swap
directions.

9. "Exercise" #9. After reading it over and over and over it is
just not understandable (at least at this point). I don't
get it. No comments. Unfair.

10. Chapter 6 (i will call it chapter six although the manual is
divided by some other bizarre structure labeling chapters
into large groups and yet the sections i'd call chapters
progress sequentially though them) says directions have
"number" property which is "useful for mazes" and then
absolutely no hint is given as to how this is the case? Is
it self evident? Not to me. Give a clue!

11. One page 36 and noticing the very strange "(the)" construct
(function??) in an example. It has been used before several
times as well and no explanation as to the nature of method
of doing things, or how it works, has been given. It is
somewhat obvious that it's somehow sticking the definite
article for the object, however one (a beginner especially)
even intuiting this is left completely puzzled as to the
nature of this device, and is left hanging with no official
explanations, only their own best guesses.

12. I might mention some of the quotations at the beginning of
chapters up to this point. The second quote at the beginning
of chapter four which begins "...a language obsessed with
action". The quote is chopped so the reader has no idea what
the original context was. A pilfered description, but feels
about right-- something half explained. But then on chapter
eight the quote mentions a lock being wrapped in a dozen six
inch thick chains, and i'm wondering if that quote isn't put
there to demonstrate how illogical and frustratingly
unprogressive and unbelievable (in how it foists "Exercises"
on the student which the student then must look up the
answer to find that they have been hoodwinked for they
didn't have the knowledge or tools to complete the
assignment in the first place and are lucky if they can even
understand the "answer" at all when showed to them-- usually
without explanation) the manual has been in places up to
this point. A dozen six inch thick chains when added up
equals six feet thick worth of chains! that's one big lock
they are wrapped around i'd say!

13. Chapter 11: an example utilizes some sort of variable called
"wn" which was never explained or mentioned and the novice
has no idea whatsoever what it signifies. The whole example
is utterly confusing, exceedingly complicated, and not
explained. The "jump" command is not explained.

14. "Exercise" #21 might make a good example, but not an
EXERCISE. One has no idea what the explanation of a "grammar"
routine is until one tries to decipher the "answer" given to
the question posed them.

15. "Exercise" #22 uses something called "scope_stage". What the
bloody hell is that!! It's not yet been mentioned in the
entire manual up to this point, and now it's tossed in
casually with no explanation.

16. Growing weary of writing out these instances of INJUSTICE in
the manual i have lazily slipped over some parts I would
have liked to complain about if i had the energy and wasn't
so depressed from reading "answers" to "exercises" and often
only being able to understand enough to know that they
utilize concepts not yet presented to the reader. I thought
I would give up altogether on this indictment as it seemed
so overwhelming. The details of the "Exersise" regarding
switching the player's persona completely stumped me...
completely... (the "orders" routine... what is an "orders"
routine?! No one ever mentioned an "orders" routine yet!)...
and other things... using 'untypable' dictionary words... i
think i get it.. i think so... but not really... and all
this above utter confusion in my mind is like clear crystal
beside the absolutely impenetrable (to me, at least)
"Exercise" of "list_together" of coins and the I Ching. But
i shoulder the discouraging burden of conscious ignorance
and move on feeling it's hopeless... and i make it to the
"how nouns are parsed" chapter and lo and behold, a
miracle!! Finally a few things are being explained to me.
Finally i'm given a few clues that make some of the previous
incomprehensible gobbledy-gook at least semi-comprehensible.
For example, i finally now learn what the "parse_name"
property is for the first time, in spite of it having been
used (to the effect of utter bewilderment) without
explanation in many examples up to this point. I had NO CLUE
what parse_name was for wile trying to desperately
understand what going on in the EXTENSIVE use of parse_name
in "Exercises" 55 and 56. Now, at this late date, i am
finally treated with an explanation as to why those words
were unparsable in the "unparsable" words mentioned
previously. **NOW** FINALLY it is said explicitly that the
'wn' variable is "word number". Thank you! Couldn't it have
been mentioned before many chapters ago when it was USED? It
is TOO LATE!! I had to figure out that "wn" meant word
number all on my own by guess work and thousands of
re-readings of the code to agonizingly intuit it's purpose
with no explanation or mention. With sweat and strain i had
to figure the mystery of "wn" out on my own dozens of pages
ago! ANd now here, when it is totally redundant information,
and my head is splitting from figuring things out that
haven't been explained, i'm informed that it simply means
"word number". Too late! The frustration of this is almost
boundless.

With my new found knowledge of parse_name, i actually decide
to go back and take a look at some of the previously
completely enigmatic "exercises" to see if they now can be
deciphered. I go back to the coin example and yet again am
repulsed by stabbing ignorance. No clue whatsoever as to the
meaning of "##TheSame". Baffled by functions returning
negative values... no comments. No hints. Helpless still...

17. I have to laugh bitterly at the Shakespearean quotation at
the start of chapter 15; life being a tale told by an idiot,
signifying nothing... sigh. Thanks for the encouragement, as
if i'm not having a hard enough time and am not depressed
enough i have to be confronted with that. I'm an idiot! And
I can't understand this manual! And besides, thanks for
reminding me Shakespeare, anything i do will signify nothing
anyhow so why am i torturing myself with this stuff?!

18. Trying to decipher "Exercise" #63 and notice it sets
parser_action. What in god's name is parser_action, i ask. I
realize now that i've seen it used previously in the manual,
but i have no clue what it is. Did i miss something? I look
it up in the index to see where it was mentioned before and
thanks to the index i find that parser_action WILL be
explained on the NEXT page AFTER the page that i'm on. Is
this not backwards?? Shouldn't these things be explained
BEFORE sending the hapless reader into the exercise?? So i
abandon my mortal struggle with "Exercise" #63 and move on
hoping things will make more sense at some later date.
Perhaps AFTEr things have been explained.

19. Wow. "Exercise" #64. I find myself completely
disproportionately impressed by this fact: the exercise
actually takes the time to WARN the reader that to
understand it might require knowledge of the NEXT two
chapters. Why bother with this warning now? It's never been
given before and i've now recounted so many instances where
the so-called "exercises" contain things not yet explained.
But lets not dwell on the past, i'm still very very happy to
have at least been warned. I think i'll skip this example
and save myself the pain-- come back to it after i've read
the next couple of chapters. And thank my lucky stars that
in schools i went to they didn't have the final exams at the
beginning of semesters and then teach you what was on the
exam after...

20. !!!!FINALLY!!!! Finally some light is shed!!!!! I'm
completely over reacting because it's such a shock to
understand something! My joy is so intense i can barely
articulate. I already announced my thrill in the last
chapter of finally having the enigmatic parse_name
explained, but in this chapter (21) there is a GOOD
explanation, and not only that i finally find out what that
damned ##TheSame notation was all about! it's about time! I
finally think i have the bare essentials to POSSIBLY
understand that long gone by, twice already looked at,
"Exercise"! I'm finally being treated to the truth of the
matter! I cry, indeed, "the truth shall set you free"! (and
i don't feel bad about taking this quote of jesus out of
context because i've had a lot of examples of completely out
of context quotes so far in the manual).

21. And here is the truth! It's so obvious now. The author of
the manual is a Tralfalmadorian! Incapable of linear
thought! Progression, as we humble, backwards eartlings know
it, means nothing to a Tralfalmadorian. This explains
everything! (-;

22. Page 84 says it's going to extend "press" but then extends
"push"... synonyms, but an inaccuracy.

23. "Exercise" 68.... NextWordStopped()??? STOPPED??? Have not
seen that one before. wn*2-3???? what on earth is that for!
Not explained. -1:Return?? is this a typo??! I'm confused.

24. page 89. __[routine]__ returns 1 twice in the chart? Typo?
is the top value supposed to be -1?

25. Three pages AFTER the fact I'm not informed what
"NextWordStopped()" means, but at this point i'm too
mentally exhausted to backtrack and try and decipher a little
more of that already mentioned "Exercise" 68 again.

26. There is no 26.

27. "Exercise" #70. ... look at that! The much used "switch"
function (which has nowhere been explained) has a "default:"
usage.... how nice to know these things. (just looked up
"switch" in the index and can take cold comfort from knowing
that in just 36 more pages it will be officially explained
to me... i can hardly wait. No matter how redundant the
explanation will be by then.

28. I find my brain uncontrollably screaming: For God's sake put
some comments, or explanations in the "exercise"
"answers"!!! It's the least that could be done!! And for
God's sake move the scope chapter to somewhere before the
completely mind numbing parser detail in the "tokens of
grammar" chapter lest poor folks collapse under its weight
and don't make it out the other side! Help! i'm being
crushed!

29. Lighter note: "Exercise" #74. It's a "slider", but you can't
"slide" it. (-: Does that make sense? I only thank god I
haven't seen an I-F yet with 500 sliders in it as this
"exercise" suggests might be a good use for the technique
being shown... and i hope i never will!

30. "Exercise" 76. Imagine trying to learn a programming
language and being told for an Exercise to go and design and
program your own compiler out of the language you are trying
to learn.... uh...

31. "Ex" #80. "++scope_count"?!?! what on earth??

32. "Ex" #83. Reader is told what INP1 and INP2 do only after the
"Exercise" that just used them and while still in the
exercise "answer". Is that fair?

33. page 98 typo. "relatively simply" should be "relatively
simple".

34. Page 105. typo "ofthese" (no space between words)

35. page 107. typo? "This turns on (flag=1) or off (flag=1)
word-breaking" (i assume the "off" value should be 0?)

36. Once again i'm with good old Shakespeare again at the
beginning of chapter 24 when he says "Wherefore are these
things hid?" Exactly my feelings, shakespeare, old buddy!! I
couldn't have said it better... WHEREFORE ARE THESE THINGS
HID!
--****ATTENTION****--****ATTENTION****--****ATTENTION****--***ATTENTION***
Your e-mail reply to this message WILL be *automatically* ANONYMIZED.
Please, report inappropriate use to abuse@anon.penet.fi
For information (incl. non-anon reply) write to help@anon.penet.fi
If you have any problems, address them to admin@anon.penet.fi