Web version of v10's Writing with Inform / Recipe Book, featuring playable examples

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)
  • improved contrast / no more teeny font sizes
  • scales better to larger and smaller screens
  • improved formatting of tables; see: Pine 4
  • 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).

Thanks also to @AmandaB, @otistdog, @DeusIrae, and @Dannii for providing feedback on previous drafts.

22 Likes

Congrats, Zed !! what one really needs !

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 :wink:

Kudos, and best regards !

2 Likes

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.

The indoc documentation begins:

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.

4 Likes

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).

3 Likes

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).

1 Like

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

Best regards from Italy,
dott. Piergiorgio.

2 Likes

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.

1 Like

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.

Best regards from Italy,
dott. Piergiorgio.

1 Like

I pushed the new version that includes dark mode support and has much nicer formatting in general.

4 Likes