From fd8f547191457928785b8bc38570b05205f369ac Mon Sep 17 00:00:00 2001 From: Glenn Hutchings Date: Thu, 28 Apr 2016 20:56:15 +0100 Subject: [PATCH] Add links to online DM4 at appropriate places. --- about.rst | 18 +++++++++--------- appendices/e.rst | 3 +-- chapters/02.rst | 28 +++++++++++++-------------- chapters/09.rst | 2 +- chapters/10.rst | 26 ++++++++++++------------- chapters/11.rst | 12 ++++++------ chapters/14.rst | 8 ++++---- chapters/17.rst | 49 ++++++++++++++++++++++++------------------------ conf.py | 11 +++++++++++ 9 files changed, 83 insertions(+), 74 deletions(-) diff --git a/about.rst b/about.rst index ae816b9..ed87193 100644 --- a/about.rst +++ b/about.rst @@ -58,13 +58,13 @@ Scope and approach Because this is only an introduction to Inform, many features are treated rather superficially, or ignored altogether. The definitive text is Graham -Nelson's Inform *Designer's Manual* (Fourth Edition, July 2001), commonly -known as the DM4; you cannot hope to use Inform successfully without having -this splendid book by your side. Our guide should be seen merely as a -supplement to the DM4, offering step-by-step descriptions of those aspects -of Inform which are most important on first acquaintance. In any matter -where we seem at odds with what Graham has written, you should assume that -he is right and that we are, well, confused. +Nelson's |DM4| (Fourth Edition, July 2001), commonly known as the DM4; you +cannot hope to use Inform successfully without having this splendid book by +your side. Our guide should be seen merely as a supplement to the DM4, +offering step-by-step descriptions of those aspects of Inform which are +most important on first acquaintance. In any matter where we seem at odds +with what Graham has written, you should assume that he is right and that +we are, well, confused. As a tutorial, this guide is intended to be printed out and then read sequentially; it isn't meant for online usage or designed as a reference @@ -141,8 +141,8 @@ locations: * http://www.inform-fiction.org/ The Inform home page, maintained by Graham Nelson and a small team of - helpers. Most important, this is where you can find the *Inform - Designer's Manual* in PDF format. + helpers. Most important, this is where you can find the |DM4| in PDF + format. * http://mirror.ifarchive.org/ diff --git a/appendices/e.rst b/appendices/e.rst index 8e0ab52..8bbe068 100644 --- a/appendices/e.rst +++ b/appendices/e.rst @@ -667,8 +667,7 @@ To declare a new property common to all objects: Uncommon and deprecated directives ================================== -You're unlikely to need these; look them up in the *Designer's Manual* if -necessary. +You're unlikely to need these; look them up in the |DM4| if necessary. | `Abbreviate "{string}"... "{string}";` | `End;` diff --git a/chapters/02.rst b/chapters/02.rst index d95eee6..a5fa8e9 100644 --- a/chapters/02.rst +++ b/chapters/02.rst @@ -171,12 +171,12 @@ Follow these steps: In order to make the download small and fast, these folders include just enough to get you started as an Inform designer -- the compiler and interpreter programs, the library files, the ``Ruins.inf`` example file - from the *Inform Designer's Manual*, and a template for your own first - game. A few other folders are included as placeholders where you could - later download additional components, if you wanted them. As soon as - possible, you should download the *Inform Designer's Manual* into the - ``Inform\Doc`` folder -- it's an essential document to have, and has - been omitted from this download only because of its 3MB size. + from the |DM4|, and a template for your own first game. A few other + folders are included as placeholders where you could later download + additional components, if you wanted them. As soon as possible, you + should download the |DM4| into the ``Inform\Doc`` folder -- it's an + essential document to have, and has been omitted from this download only + because of its 3MB size. 3. To verify that the downloaded files work properly, use Windows Explorer to display the contents of the ``Inform\Games\MyGame1`` folder: you will @@ -235,7 +235,7 @@ Follow these steps: 9. Using the same techniques, you can compile and play ``Ruins.inf``, which is held in the ``Inform\Games\Download`` folder. RUINS is the game used - as an example throughout the *Inform Designer's Manual*. + as an example throughout the |DM4|. .. rubric:: Setting file associations @@ -423,13 +423,13 @@ Follow these steps: In order to make the download small and fast, these folders include just enough to get you started as an Inform designer -- the compiler and interpreter programs, the library files, the ``Ruins.inf`` example from - the *Inform Designer's Manual*, and a template for your own first game, - which you may copy and rename each time you begin a new Inform project. - A few other folders are included as placeholders where you could later - download additional components, if you wanted them. As soon as - possible, you should download the *Inform Designer's Manual* into the - ``Inform/Doc`` folder -- it's an essential document to have, and has - been omitted from this download only because of its 3MB size. + the |DM4|, and a template for your own first game, which you may copy + and rename each time you begin a new Inform project. A few other + folders are included as placeholders where you could later download + additional components, if you wanted them. As soon as possible, you + should download the |DM4| into the ``Inform/Doc`` folder -- it's an + essential document to have, and has been omitted from this download only + because of its 3MB size. 3. To verify that the downloaded files work properly, use the Finder to display the contents of the ``Inform/Games/MyGame1`` folder: you will see diff --git a/chapters/09.rst b/chapters/09.rst index 797b343..f6a50a1 100644 --- a/chapters/09.rst +++ b/chapters/09.rst @@ -234,7 +234,7 @@ Return value is important Return value doesn't matter For full details on which library property values can be embedded routines, and which return values are significant, see :ref:`object-props` and -Appendix §A2 of the *Inform Designer's Manual*. +:dm4:`Appendix §A2 ` of the |DM4|. Return to the marketplace ========================= diff --git a/chapters/10.rst b/chapters/10.rst index 3274de9..cc4543e 100644 --- a/chapters/10.rst +++ b/chapters/10.rst @@ -443,13 +443,13 @@ something else to describe it: .. note:: - Although the text of our guide calls Benny's establishment a "café" - -- note the acute "e" -- the game itself simplifies this to "cafe". - We do this for clarity, not because Inform doesn't support accented - characters. The *Inform Designer's Manual* explains in detail how to - display these characters in "§1.11 *How text is printed*" and - provides the whole Z-machine character set in Table 2. In our case, - we could have displayed this:: + Although the text of our guide calls Benny's establishment a "café" -- + note the acute "e" -- the game itself simplifies this to "cafe". We do + this for clarity, not because Inform doesn't support accented + characters. The |DM4| explains in detail how to display these characters + in :dm4:`§1.11 ` "*How text is printed*" and provides the + whole Z-machine character set in Table 2. In our case, we could have + displayed this:: The town's favourite for a quick snack, Benny's café has a 50's ROCKETSHIP look. @@ -524,12 +524,12 @@ rip with a snatch of Wagner, you may intercept the ``Sing`` action in a ``before`` property and alter its default, pretty useless behaviour. If not, it's "Your singing is abominable" for you. -All actions, useful or not, have a stock of messages associated with -them (the messages are held in the ``english.h`` library file and listed -in Appendix 4 of the *Inform Designer's Manual*). We have already seen -one way of altering the player character's description -- "As good -looking as ever" -- in "William Tell", but the other defaults may also -be redefined to suit your tastes and circumstantial needs. +All actions, useful or not, have a stock of messages associated with them +(the messages are held in the ``english.h`` library file and listed in +:dm4:`Appendix 4 ` of the |DM4|). We have already seen one way of +altering the player character's description -- "As good looking as ever" -- +in "William Tell", but the other defaults may also be redefined to suit +your tastes and circumstantial needs. John Covarth, aka Captain Fate, could happily settle for most of these default messages, but we deem it worthwhile to give him some customised diff --git a/chapters/11.rst b/chapters/11.rst index ffbc9ae..80acc51 100644 --- a/chapters/11.rst +++ b/chapters/11.rst @@ -651,12 +651,12 @@ which restores the value originally stored in ``ks`` to ``keep_silent``. The effect is that we manage to leave it as it was before we tampered with it. -Well, that's about everything about doors. Everything? Well, no, not -really; any object can grow as complex as your imagination allows, but -we’ll drop the subject here. If you care to see more sophisticated -doors, check Exercises 3 and 4 in the *Inform Designer's Manual*, where -an obliging door opens and unlocks by itself if the player simply walks -in its direction. +Well, that's about everything about doors. Everything? Well, no, not +really; any object can grow as complex as your imagination allows, but +we’ll drop the subject here. If you care to see more sophisticated doors, +check Exercises :dm4:`3 and 4 ` in the |DM4|, where an +obliging door opens and unlocks by itself if the player simply walks in its +direction. So far, we have the player in front of a locked door leading to the toilet. A dead end? No, the description mentions a scribbled note on its diff --git a/chapters/14.rst b/chapters/14.rst index b8e12b7..0b99b44 100644 --- a/chapters/14.rst +++ b/chapters/14.rst @@ -28,10 +28,10 @@ We'll also talk, in :ref:`reading-other-code`, about a few ways of doing things that we've chosen not to tell you about, but which you're quite likely to encounter if you look at Inform code written by other designers. -The tone here is perhaps a little dry, but trust us: in walking this -dusty ground we touch on just about everything that is fundamental in -your overall understanding of Inform. And as always, the *Inform -Designer's Manual* provides rounder and more comprehensive coverage. +The tone here is perhaps a little dry, but trust us: in walking this dusty +ground we touch on just about everything that is fundamental in your +overall understanding of Inform. And as always, the |DM4| provides rounder +and more comprehensive coverage. Expressions =========== diff --git a/chapters/17.rst b/chapters/17.rst index c4a69d1..12be396 100644 --- a/chapters/17.rst +++ b/chapters/17.rst @@ -45,21 +45,20 @@ organised in a prettier way." Go right ahead. "I want to have a better social life thanks to Inform." No problem, but you'll have to be one damn charming designer. Oh, well. -Inform has been designed to let you do simple things intuitively and -quickly. Left to its own devices, it offers a wide range of default -functionality, and we’ve seen that it’s also easy to alter some of its -standard behaviour. The desirable goal is for you to reach a state of -such familiarity with the system that you can concentrate on designing -your games. By "such familiarity" we are not implying that you should -know the innards of the library inside out; such people exist, but -they're few and far between. However, once you become reasonably -proficient at typing in code, with a knowledge level similar to the one -provided by this guide, a careful look at the appropriate section of the -*Inform Designer's Manual* should help you through most difficulties. -Admittedly, there are problems and *problems*, from the slap-on-the-head -trifle to the teeth-gnashing nightmare. We advise you to put the -nightmares on hold for the time being. It may be that one day you -discover that their fangs were not as sharp as they seemed. +Inform has been designed to let you do simple things intuitively and +quickly. Left to its own devices, it offers a wide range of default +functionality, and we’ve seen that it’s also easy to alter some of its +standard behaviour. The desirable goal is for you to reach a state of such +familiarity with the system that you can concentrate on designing your +games. By "such familiarity" we are not implying that you should know the +innards of the library inside out; such people exist, but they're few and +far between. However, once you become reasonably proficient at typing in +code, with a knowledge level similar to the one provided by this guide, a +careful look at the appropriate section of the |DM4| should help you +through most difficulties. Admittedly, there are problems and *problems*, +from the slap-on-the-head trifle to the teeth-gnashing nightmare. We advise +you to put the nightmares on hold for the time being. It may be that one +day you discover that their fangs were not as sharp as they seemed. There are many interesting topics that you could pursue next. Here are a few: @@ -136,16 +135,16 @@ players, so their advice beyond the call of bug-hunting is as priceless counsel as you are likely to get. Encourage them to comment on your achievements in both programming *and* design. -Now: where to go, what to do? Allow us to insist one last time on the -importance of reading the *Inform Designer's Manual*, an excellent book -in all respects. While you are at it, write small games, training -exercises; we don't advise you to try an epic saga for your first -scenario, but if nothing else will work for you -- the Think Big -approach -- don't let us deter you. It's a good idea to play other -people's games, because you'll know the average level that players may -expect; check the newsgroups for comments on good titles. Be sure around -September to keep an eye open for the Interactive Fiction Competition -(http://www.ifcomp.org/), an annual showcase for short(ish) works. +Now: where to go, what to do? Allow us to insist one last time on the +importance of reading the |DM4|, an excellent book in all respects. While +you are at it, write small games, training exercises; we don't advise you +to try an epic saga for your first scenario, but if nothing else will work +for you -- the Think Big approach -- don't let us deter you. It's a good +idea to play other people's games, because you'll know the average level +that players may expect; check the newsgroups for comments on good +titles. Be sure around September to keep an eye open for the Interactive +Fiction Competition (http://www.ifcomp.org/), an annual showcase for +short(ish) works. And, who knows? It might be that next year we’ll all be smashed by *your* entry. diff --git a/conf.py b/conf.py index 956d4bc..540662e 100644 --- a/conf.py +++ b/conf.py @@ -42,6 +42,7 @@ def setup(app): # ones. extensions = [ 'sphinx.ext.todo', + 'sphinx.ext.extlinks', 'tools.blockdiag', ] @@ -109,6 +110,16 @@ default_role = "any" # output. They are ignored by default. #show_authors = False +# Global substitutions. +rst_epilog = """ +.. |DM4| replace:: *Inform Designer's Manual* +""" + +# External links. +extlinks = { + 'dm4': ("http://inform-fiction.org/manual/html/%s", ""), +} + # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'friendly' -- 2.31.1