I guess this isn’t so much an Inform-specific question, but I’m wondering what is a good way to search the manuals just in the browser. Ideally you could run a search query like “http://inform7.com/learn/man/?search=” and get a list of results back linked into the manual. Doing a site: search in Google sort of works but it’s not great.
Would anyone be interested in an online searchable version of the manuals, and perhaps other documentation like the Programmer’s guide?
Have you seen the recently-stickied list of I7 documentation?
https://intfiction.org/t/the-list-of-inform-7-documentation-as-of-19-dec-2011/3311/1
It includes Andrew Plotkin’s index to the manual.
I don’t use the IDE (I just compile on the command line in LINUX) so when I made that switch, this was foremost in my mind. On inform7.com there is a text file version of Writing With Inform, so I searched on that at first. Lately, I’ve more often been searching on the actual Standard Rules library, which is also a text file, and which is also downloadable from inform7.com (there is even a version that includes commentary). I don’t recall if these options are on the documentation sticky, but they probably should be.
Paul.
One thing about Inform being a “natural” programming language is that well-written code is reasonably self-documenting. I use the Standard Library as my main documentation as well…
@Laroquod, so do you do an incremental find/search for the terms you’re looking for while the Standard Rules are open in your editor? Or are you using some other search utility?
@capmikee, I wrote the stickied I7 docs post 
. Writing that post made me think of this topic.
I tend to keep a copy of Standard Rules.i7x open in a text editor at all times, just in case I need it. People ask questions…
Yup I just bang it into a text file in the same editor I am coding in and do a search. It’s hard to improve on having a single, very lightweight software program handle both coding and documentation. On the Mac, I use TextWrangler. On LINUX, so far I have been using gedit but that might change.
blinks
That sure wasn’t my experience in writing New Cat. I had to torture the English language severely and ended up with malformed quasi-sentences galore – and I still had tons of documentation. The source code for other games (like Weischaupt Scholars, and Rover’s Day Out) is even worse.
Fraise is another good editor. I used its previous incarnation Smultron. TextWrangler is good, but it sure makes me want to get BBEdit, you know?
I’m not interested in it now; the lack of a decent doc search was one of the things that inspired me to kick I7 to the curb, but it is one of those bare minimum kind of things that dead-tree publishers had figured out some 200+ years ago. I think people who want to use I7 will REALLY benefit from a full-text doc search.
Depends on your definition of “natural language”. Languages such as PHP and Pascal are considered “human readable”, whereas languages such as C and Assembly are considered “machine readable”. Put I7 next to I6 and I7 certainly seems like natural language. I think it’s not perfect because it’s “English”, which is one of the most complicated and butchered languages spoken today. That which is considered “proper English” is spoken pretty rarely and those who actually speak it receive some pretty odd glances from listeners.
Because it sounds stupid.
I7 has to be peppered with I6 to do anything advanced with any semblence of efficiency. There are just some things that haven’t been translated to “natural language” or to the layman’s definition of “natural language”. Maybe it isn’t possible, I don’t know. (I personally think it is.) Maybe I7 is billed improperly. Maybe it should be called a “pseudo-natural language” or a “quasi-natural language”.
While not perfect, I7 is certainly closer to natural language than anything else out there. Some concessions have to be made, sure, and maybe you have to learn some I6 to do what you need to do. But I guess if there’s no way to say…
Take that one row that has an acorn in one of the columns and mix it up between the row with the plankton and box cutter.… then I’ll have to settle for learning someone else’s idea of English.
But that’s probably the redneck talking.
(Official Statement: While I7 does have both a programmatic and an linguistically syntactic learning curve, if certain concessions can be made, it is a successful niche approach to a niche market. While I both hope and believe that steps forward will be taken to make it more easily accessibly to the interested public, it is certainly a step above the other offerings in it’s current market.)
Out of idle curiosity, are you knocking the language, the documentation or the language because of the documentation?
I ask because this is one of the pet projects I’ve been working on that’s kept me from finishing my WIP, completing promised beta testing and rectifying various faux pas that I’ve been meaning to atone for.
Thanks. I usually have a copy of BBEdit, too, but I really don’t need any of its extra features. When I switched to TextWrangler I found that not a single function that I actually used in BBEdit had been removed.
I will try to refrain from taking any of this as a judgment on the quality of the code in any of those examples. Of course it’s possible to write unreadable code in any language, including plain English (read any instruction manuals lately?).
I was referring to the Standard Rules and a number of extensions, including some by Ron Newcomb, Eric Eve and Emily Short - all of which I consider to be well-written to varying degrees. I like the way Ron takes special care to name objects and phrases so they can be used naturally in a sentence. Sometimes this involves a compromise in readability at the low level which provides much better readability at higher levels. That doesn’t bother me - if the name of a low-level phrase explains what it does, I don’t care if the way it’s done looks a little odd.
In my own coding, I often find myself writing a comment to document a rule (for example), and then realizing I could just make the comment the name of the rule.
Fortunately, efficiency is not the primary concern of most code. If you don’t work this way already, I recommend coding for readability first. Then if it’s not efficient enough, profile it and optimize only what you need to, encapsulating the optimized code in a readable wrapper.
Also, when adding I6 code, it is most natural (and convenient) to wrap up the I6 functionality in modular I7 phrases. So you’re not so much “peppering” as adding a small side dish.