I’m polishing an extension, and have recently become aware of its presentation in the Index.
I use alternate phrasings a lot, and not just in the obvious places like is/are/am, all/each/every, and plurals, but also related grammars when I can help it. For example, I would allow long constructions like “do/does/-- not/doesn’t include/includes all/each/every/-- of/-- the/an/a/-- future/scheduled/pending/-- event/events”. If that’s pathologically forgiving, well, I remember well first learning Inform and how frustrating it is to miss the exact wording all the time. Plus, I’ve spent so much time flipping through C++ library manuals for OS APIs looking for yet another name, defined value, etc. that “it should be guess-able” became my philosophy. That philosophy works much better in Inform’s syntax than C++.
But if someone could not guess the syntax and is already looking something up in the index, surely just one phrasing would suffice? I worry that by making the exact wording more guessable I may actually scare away authors with the mere look of the thing in the phrasebook.
Perhaps a, what do you call it, a pop-up hint, a tooltip, that shows all the possibilities? Or only show it in the details box via clicking the plus icon?
Section headings from my extensions appear as section headings in the phrasebook. I’m torn on this. Obviously I like defining headings for use in there. But, I usually put in many, many section headings in my extensions to facilitate per-heading replacement, and also to narrow down an author’s search for bugs should a clash between her code and my extension happens. The latter I feel is quite important as the extension’s code will be unfamiliar to her, and much harder to track down bugs.
Perhaps do this with chapter headings instead of section headings? Generally, in the index one does not need the finest-grained heading to find the phrase, as there’s a hyperlink that goes straight to it anyway. The finest-grained headings are most useful in the (blessedly improved!) Problem messages, which bracket where the problems lie. Hence I would have only chapter headings appear in the phrasebook, not the headings larger or smaller than that. (Or, the heading next larger than chapter, as it is probably used less enough that it is free to be put in, or left out, according to little else besides documentation concerns.)
Clicking the plus icon beside my new phrases brings up… not much. Is it possible to define specification text to go in there? Just a thought. Seems silly to have the icons there but they not really do much, for non-built-in phrases.
(I just learned that the “unindexed” word only works for sections, not chapters or anything larger. I was surprised. And filed a documentation clarification on Mantis.)
Sometimes I feel a newly defined phrase should be slipped under an existing heading. For example, if I define a new “repeat” loop, I might like it to appear with the others, or the say phrase “time as a time period” with its brethren. (Possibly while also including it in the extension-specific section of the phrasebook, so the author could still tell what all possibilities were added.) Just a thought.
All in all, I like the new phrasebook and hope it renders the separate syntax document obsolete. With the improving search capabilities on the documentation (plus my having at least a vague idea of the word or words to search for), I haven’t used the syntax document for about a year. As for the above points, 1 and 2 are really the only ones I would defend if called to do so. But #2 I feel very strongly about. A mere “section” is too small, at least for extensions written with a mind toward flexibility.
Sorry I don’t have anything to say about your main point, but I have a tangential comment on this:
I see your point: I’ve struggled with things like “When the play begins” vs “When play begins” which just should be smoother, but personally I’m for the one function, one name philosophy. It’s all nice and handy to be able to guess syntax when you’re learning the language or a new library, but in the long run it starts to become a burden because if you read other people’s code, you have to learn every available wording to be able to understand the code. For example, your construction could be written as “does not include every future event” or “doesn’t include all of the scheduled events”. Is it the same function? Or a different one with a similar name? Are future events the same as scheduled events? The ease of writing comes with a cost of harder reading. If C++ had synonyms to everything it would be a nightmare to work with in a team of programmers (even more than it is right now.)
Inform 7 is possibly an exception in some ways with its natural-language-like syntax, but I’m still happy that I don’t have to flip through the syntax document every time someone uses a feature I know but with a different wording than how I’ve learned it.
Ah, another thing on that point. I sometimes have two different versions of the same phrase, one that requires a particular extension and one that doesn’t. When I use the heading phrases (for use with Plurality by Emily Short) and (for use without Plurality by Emily Short), this allows me to give a single phrase to the author regardless whether he’s including the other extension or not. However, phrases done this way are always listed in little subsections by themselves in the phrasebook rather than being grouped with the rest of its herd.
So again, please don’t show the Section headers in the phrasebook, just the Chapter headings and/or larger.
I agree that it would be nice to for the phrasebook to show a single, simple version, and give us the complex version only on mouseover (provided that is properly accessible to screenreaders). But I agree because I tend to write phrases like this:
To draw a line (hue - a number) in (win - a g-window) from (x1 - a number) by (y1 - a number) measuring/of (distance - a number) pixel/pixels/-- long/-- at (angle - a number) deg/degree/degrees/-- angle/-- with (wgt - a number) pixel/pixels/px/-- line-weight/stroke:
I also want to take this opportunity to say that removing “change ____ to ______” from the language, as will happen in an upcoming release, is annoying. The phrase that should be gotten rid of is “now the _____ is _____”. The former is a strong, verb-centered assertion that says exactly what it does, while the latter is weak and just…silly sounding. In my own work, I’ll definitely have to add “change…” back in, but I’m really not looking forward to clearing it out of my extensions…
The issue with change is that it does exactly a subset of what “now” does. Now is more generally powerful because it is a compact way of asserting most things that could be declared as a game-starting assertion, short of object creation; it doesn’t make sense to say “change the sticker to part of the noun”, whereas “now the sticker is part of the noun” does make sense (and circumlocutions with change would be ugly: “change the sticker to be a part of the noun”? Ugh.)
Our impression is that having change as a slightly-less-able form of “now” may sound good some of the time – and I admit I’m going to have to retrain myself as well, because I habitually do use it for some things – but is in general confusing. But, as always, feedback is welcome.
The direction of my work with Inform so far hasn’t taken me toward needing to do anything with parts, and I haven’t run into that situation. I guess it makes sense, then, to see “now…” as the superset. (On the other hand, “change the sticker to be part of the noun” sounds OK–not great, but better I think than “now the car is blue”.)
I suspect that there will be an extension (in fact, I may write it) to reintroduce “change…” to the language when it goes away. I’d like to see the decision to retire it reconsidered, but I guess it’s not really that big a deal. There are lots of other things I consider more important.
“now” covers more than parts; it covers all relations. “now all coins are in the bag”, “now the phone booth is off-stage”, “now Steve loves pie” (with the appropriate loving relation), etc.
Yes, looking over some old code I notice that I certainly use “now” for those kinds of things, and I also use it once in a great while for simple variable assignments (“now the sky is blue”), where it hits better on the ear.
This doesn’t really change my preference though–“now” may be more comprehensive in its uses, but “change” is not a mere cosmetic variation: from the standpoint of clear and direct natural-language syntax, “now” is really the variation, used because there are lots of things that don’t sound good with “change.” That is, “change” + “now” makes sense idiomatically, whereas the other phrases that are being eliminated are being eliminated because they truly are duplicative: “award 5 points”, for example, duplicates the far more general “increase the score by 5”.
One might even argue that more idioms should be introduced that translate into “now”, e.g.:
make the sticker part of the noun.
change the sticker to be part of the noun.
move all the coins into the bag.
place all the coins in the bag.
move the phone booth off-stage.
make Steve love pie. [this one is maybe a bit silly…]
This kind of thing definitely doesn’t fit into the dev team’s plans, but I think at least a few users would appreciate the flexibility.