I just published a reformatted copy of the I7 v10 docs. The most interesting things:
the examples have links to play or modify them in Borogove or play them in Quixe, and for examples with test me defined, the test me output is provided; see: A Day for Fresh Sushi
the “search” page has the whole of the docs and examples on one page, providing an easier way to do a whole text search (just by searching within the page in your browser) than otherwise exists outside the IDEs
pages per chapter instead of per section makes prolonged reading easier
lots of internal links make it easier to browse, too (I hope)
the docs’ and examples’ copy-to-clipboard buttons work (they don’t in the current web copy of the official docs)
all internal links are relative; if you clone the i7doc github repo you could, e.g., firefox docs/index.html and everything would just work. (And if you’re offline, this is when you’d appreciate the Quixe versions, which otherwise don’t add anything to what Borogove provides.)
Big thanks to @Juhana for creating the Borogove snippets for the examples (and for creating and maintaining Borogove, of course).
I’m impressed of this proven ruby script, automating ~450 I7 compilations is really something, so I strongly disagree about the comment at the top of the script
Automating the compilations was truly not bad. The intricacies of parsing the data to build the general index, the example metadata and (Recipes).txt, indoc-instructions.txt, and RawText, the markup language of Writing with Inform, The Recipe Book, and the documentation examples after the first three lines of metadata per file… that had its moments. And seeing how to reproduce the example numbers was trickier than it sounds: it took spotting the underlying basis for the “essentially random order” mentioned below.
At this point, then, we know which section every example belongs to. But we still have to put them in order within those sections: we want 1-star examples first, then 2-star, and so on. The following does that. In the first volume, examples of equal star rating are in essentially random order, but in subsequent volumes, they appear in that same order, since this means their example numbers as shown in the documentation are increasing; which looks tidy.
As a program, Indoc began as a rat’s nest of Perl in 2002, and you can still see where the rats used to live. Like all too many quick-fix Perl scripts, it was still in use ten years later. In 2012, I spent some time tidying it up to generate better HTML, and made it a web (that is, a literate program). […]
Just as I was finishing up, John Siracusa described a not dissimilar task on his then podcast (Hypercritical 85): “I was trying to think of a good analogy for what happens when you’re a programmer and you have this sort of task in front of you. Is it, the cobbler’s children have no shoes? … You would expect someone who is a programmer to make some awesome system which would generate these three things. But when you’re a programmer, you have the ability to do whatever you want really, really quickly in the crappiest possible way… And that’s what I did. I wrote a series of incredibly disgusting Perl scripts.”
It’s Ruby, not Perl, but I have built new domiciles for those homeless rats.
There’s now test-me output for a few examples that had been missing it. I’ve also made a lot of cosmetic improvements (I hope) and even (gasp) fixed some errors (shakes fist at tables whose columns’ values include quoted strings with embedded newlines).
It’s a big fraught change that’ll take a lot more testing and fiddling to let it out the door and I really should do some other things this weekend, but I will tease that dark mode support now basically works (in my development version).
the testme output is really improving the understanding of the docs (whose, after ch. 9-12, (it’s a YMMV case) the examples can be best understand thru the cause-and-effect between the source and the responses of the resulting source file.
But, some source file, esp. where the source is separated by explanation (e.g. 174, numberless) gives a very imperfect output, and also where the example is related to the status line (e.g. 183, the hang of Thursday) the output simply can’t show what the example demonstrates.
The first can be repaired in your perl script, but the latter can’t be solved, I think, and I suggest that you give screenshots of the raw output, as done for the map-drawing examples (on the latter I suggest adding the raw output of the examples, without the later retouching, allowing to see what the map generation has actually built
I see what you mean about 174, thanks. I hadn’t spotted that my efforts to strip the top boilerplate was swallowing up “when play begins” text too, and that’s obviously bad. I had just yesterday noticed that the output for anything whose point was showing status line changes is not helpful and The World of Charles S. Roberts’ output is all messed up, as would be anything that depended on monospace type.
It’s more effort, but the same improvement could help with all of these: instead of simple-mindedly piping commands to a Git process built with CheapGlk and reading STDOUT the script could have a real conversation with Git built with RemGlk. The status lines couldn’t be displayed without busting out of the width I’m using for everything else, but maybe I could offer a switch that expanded the box width and included the status lines.
Now that you point to me, ex.171, Proposal 's transcript rely heavily on the when play begins (and this specific when play begins is the main demo of the “if player consent” condition) and said if player consent demo, being in the when play begins, predates the prompt, hence also the test me metacommand…
Said demo’s placement actually makes sense, because the y/n question is often used in asking if the played want to restore a save, or acknowledge this or that disclaimer, things whose natural place is indeed inside the when play begins, so isn’t a misfeature, at least IMVHO.
for the rest, having firefox in the virtual desktop left (or right) of I7 IDE is a quantum leap in coding enviro comparable with the documentation side-by side of said IDE in coding with I7.
Minor, but useful revision: in any of the chapter pages, e.g., WI 17 if you hover over a section title, a link icon appears that links directly to that section, so you can copy it and easily provide a link directly to that section. (This is the same as how headings work here, but we hardly ever use them so it’s easy not to know!)
Heading
I already made an announcement post for Web version of Ron Newcomb’s Inform 7 Programmer’s Manual available, but I should note it here, too, for people who might turn this up searching the forum or something: the I7 Programmer’s Manual (for 8.5/6G60) is now featured alongside Writing with Inform and the Recipe Book.
I have now added a reformatted 10.1 Project Index for a minimal “Lab is a room” project. Its documentation links point to the appropriate places in the online docs. It has some known issues… the dropdown more-info boxes in tables don’t work; the 12 directions and 25 command parser errors dropdown boxes on the Kinds page are missing their content… but most things are right and I thought it was good enough to be worth sharing.
I’m working on a revision to the docs web remix that will, among other things, fix the above shortcomings and better integrate the Project Index pages.
Aside the different layout is nearly exactly the type of offline library reference from the core index I tried to extract from the IDE to html !! Congratulations !!!
It’s still months away, but I’ve been working on a new version. (I’m doing the thing programmers always mean to get do but rarely do: replacing the ugly code with not-ugly code.)
new dark-mode-sensitive CSS for the Quixe examples
web-playable versions of the Z-machine-only examples (via ZVM from Parchment)
a link to the raw text of the examples
in some places, my own annotations
a markdown version of the docs (I opted to use markdown as an intermediate representation, which turned out better than I expected, so I get this as a free side-effect)
Can anyone think of anything else they’d like? Some new way to usefully present or cross-reference the information?
I introduced an embarassing bug a mortifying length of time ago that made most of the text italic. That’s finally fixed. And the title page will look much better on small screens. And I’m now bundling the design’s variable fonts within its CSS so unless you go out of your way it shouldn’t fall back to other fonts on your system. (I use a variable font for fine control of text weight while offering both light and dark modes to ensure there’s good contrast and readability throughout. Most local fonts on your system it would fall back to wouldn’t be variable-weight fonts and would likely look bad.)
