From: Glenn Hutchings Date: Tue, 29 Mar 2016 06:54:27 +0000 (+0100) Subject: Initial content. X-Git-Url: https://jxself.org/git/?a=commitdiff_plain;h=056d415c5a40209963cb26f45458ca8c73d02f5e;p=ibg.git Initial content. --- 056d415c5a40209963cb26f45458ca8c73d02f5e diff --git a/.hgignore b/.hgignore new file mode 100644 index 0000000..aea98ed --- /dev/null +++ b/.hgignore @@ -0,0 +1,3 @@ +syntax: glob + +output/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ec0dbde --- /dev/null +++ b/LICENSE @@ -0,0 +1,14 @@ +This book and its associated example games are copyright © Roger Firth and +Sonja Kesserich 2004. Copying and distribution, with or without +modification, are permitted in any medium without royalty provided the +copyright notice and this notice are preserved. Exceptions to these +conditions must be negotiated directly with the authors +(roger@firthworks.com and polilla@idecnet.com). + +This book is offered as-is, without any warranty. The authors assume no +liability for errors and omissions in this book, or for damages or loss of +revenue resulting from the use of the information contained herein, or the +use of any of the software described herein. + +Inform, the program and its source code, its example games and +documentation, are copyright © Graham Nelson 1993—2004. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..14b5f52 --- /dev/null +++ b/Makefile @@ -0,0 +1,192 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = output + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/InformBeginnersGuide.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/InformBeginnersGuide.qhc" + +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/InformBeginnersGuide" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/InformBeginnersGuide" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/README.md b/README.md new file mode 100644 index 0000000..e3f5773 --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +Inform Beginner's Guide, 4th Edition +==================================== + +Introduction +------------ + +This repository contains the sources for the 4th edition of the +[Inform Beginner's Guide](http://www.firthworks.com/roger/IBG.html), +henceforth known as the IBG. The new edition will be in a new source +format that's more contributor-friendly (see below). It's a +work-in-progress; see the [issue tracker](https://github.com/i6/ibg/issues) +for how it's going. + +The rationale for this 4th edition is: + +* There have been quite a few updates to Inform and its support libraries + in the time since 2004, when the 3rd edition was published. + +* The nitty-gritty information about how to install and run programs goes + stale pretty fast. + +* Some old web links have gone away, to be replaced by new and better + ones. + +Building from source +-------------------- + +The new source format is [Sphinx](http://sphinx-doc.org), a documentation +build tool written in [Python](http://python.org), which you will need to +install if you want to build the document. You can find the complete +installation instructions +[here](http://www.sphinx-doc.org/en/stable/install.html). + +After you have Sphinx installed, you can build the HTML version of the +guide from a command prompt, like this: + + make html + +Other formats are available; just type `make` for more details. + +Conversion strategy +------------------- + +The first three editions of the IBG were created with +[Adobe FrameMaker](http://www.adobe.com/products/framemaker.html). And the +FrameMaker source files have kindly been supplied by Roger Firth to make +this update, which opened up the possibility of creating an auto-converter. + +But unfortunately, what with FrameMaker being proprietary, there isn't much +out there apart from FrameMaker itself that can read them. I was hoping +that conversion using [Mif2Go](http://mif2go.com) might be a possibility, +but it turns out that that's just a plugin for FrameMaker. I guess I could +get a trial FrameMaker license, try to set up the plugin and get it to +autoconvert to some usable format, but it all looks far too messy. But on +the plus side, the supplied GIF images are totally usable. + +So, it's back to my original plan: use the PDF file. Here's the first +(major) part of the work: + +* Dump the text out of the PDF file +* Convert all the text to Sphinx format +* Get the online version to look good + +After that comes the 4th edition changes, hopefully in collaboration with +others. Also, in parallel with that, other niceties: + +* Add a glossary +* Add an index +* Add Inform syntax highlighting +* Prepare a new PDF version, via the Sphinx LaTeX converter diff --git a/about.rst b/about.rst new file mode 100644 index 0000000..13b4b0b --- /dev/null +++ b/about.rst @@ -0,0 +1,225 @@ +================== + About this guide +================== + +.. epigraph:: + + | *If they asked me, I could write a book;* + | *About the way you TALK, and LISTEN; And LOOK.* + + -- with apologies to Richard Rodgers and Lorenz Hart. + +Text adventures, otherwise known collectively as interactive fiction (IF), +were highly popular computer games during the 1980s. As technology evolved +they faded from the market, unable to compete with increasingly +sophisticated graphical games; however, IF was far from dead. The Internet +grew, and Usenet discussion forums offered a focal point for fans of the +genre. By developing IF programming tools and systems, organising contests +and writing tutorials and reviews, these enthusiasts have led a revival +responsible for many notable works, including some whose quality arguably +surpasses that of the best commercial titles of the 1980s. + +Nowadays, IF is a hobby; almost everything that you need to begin writing +your own text adventures is available, for free, on the Internet. While +expert programmers may relish the considerable challenge of creating +interactive fiction using a generalised language such as BASIC or C, +specialist IF tools have largely solved the fundamental world-building +issues. The most common systems are Graham Nelson's Inform -- our subject +matter -- and Mike Roberts' TADS (Text Adventure Development System). New +hopefuls arrive each year, but few achieve widespread acceptance; the +majority of today's IF (and virtually all the works generally regarded as +interesting, innovative, sophisticated, etc.) have been created with +either one or the other. In our view, only TADS bears comparison with +Inform in popularity, in being able to handle simple and complex stories, +and in availability on PCs, Macs, hand-held devices and a wide variety of +other computers. But, since you're reading our guide, we'll assume that +you've already made a choice, and decided to give Inform a try. + +We aim to provide a grounding in Inform basics. When you have learnt a +little about it, you'll be able to design simple games for your friends to +play and, as you become more accomplished, which you can share via the +Internet with enthusiasts worldwide. However, if you simply want to play +[#play]_ games written by others -- rather than write them yourself -- then +you don't need to learn Inform, and this guide isn't for you. + +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. + +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 +manual, though it does provide brief summaries of Inform's language and +library. Our approach is to teach you about Inform through the creation of +three games: all short, all playable to completion. "Heidi" is just about +as simple as an IF game can be, but still manages to introduce a range of +important concepts. "William Tell", a retelling of the famous folk tale, +is nearly as brief but roams more widely in its use of Inform's +capabilities. Finally "Captain Fate" presents a comic-book hero in urgent +need of a change. By the end of the guide, we'll have touched on less than +half of Inform's capabilities, but we hope we'll have mentioned most of the +things that matter when you're starting out to design your first Inform +game. + +One final point: Inform is a powerful system, often offering several +different ways of tackling a particular design requirement. We've tried to +present things as simply and consistently as possible, but you shouldn't be +surprised to discover other approaches, maybe shorter, maybe more +efficient, than those shown here. + +Presentation and style +====================== + +Most of the guide's text appears in this typeface, except where we're using +words which are part of the Inform system (like ``print``, ``Include``, +``VerbLib``) or are extracted from one of our games (like ``bird``, +``nest``, ``top_of_tree``). Terms in **bold type** are included in the +glossary -- Appendix G on page 273. We switch to italic type for a +placeholder: for example you should read the Inform statement: + +.. parsed-literal:: + + print "*string*"; + +as meaning "display on the player's screen the arbitrary character or +characters which are represented here by the placeholder *string*". +Examples might include:: + + print "Hello world!"; + print "Fourscore and seven years ago our fathers brought forth on + this continent a new nation, [...] and that government of + the people, by the people, for the people shall not perish + from the earth."; + +We place the "TYPE" symbol alongside game fragments which you can type in +as a part of our working examples. This differentiates them from other +code snippets whose only purpose is to illustrate some particular feature. + +.. todo:: + + The "TYPE" symbol doesn't really work here. Think of a better way to + indicate typed-in fragments. + +Useful Internet resources +========================= + +One of our basic assumptions -- along with your burning desire to learn +Inform and your ability to work comfortably with the files and folders on +your computer -- is that you have access to the Internet. This is pretty +well essential, since almost everything you need is available only via this +medium. In particular, you'll find much helpful material at these +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. + +* http://mirror.ifarchive.org/ + + The IF Archive (or actually a high-speed mirror copy of it), from which + you can download almost anything that's free and in the public domain. + For a clickable map of Inform-related parts of the Archive, see + http://www.firthworks.com/roger/informfaq/hh.html. + + .. note:: + + Prior to August 2001, the IF Archive was located elsewhere, at + ftp://ftp.gmd.de/if-archive/, and references to that location can + still occasionally be found. *Do not use* the old location: any + information still available from there is likely to be out-of-date. + +* http://www.firthworks.com/roger/ + + Roger Firth's Inform pages, including the Informary (what's new in + Inform?), and the Inform Frequently Asked Questions (FAQ) pages. + +* http://www.plover.net/~textfire/raiffaq/ + + A more general list of FAQs about IF authorship, covering both Inform + and the other main systems. + +* news:rec.arts.int-fiction + + The Usenet newsgroup for authors of IF, commonly known by the + abbreviation RAIF. Here you'll find discussion on IF technology, + criticism and game design issues, and fast, friendly and knowledgeable + assistance with your own "how do I..." questions (but please, look in + the manual first). + +* news:rec.games.int-fiction + + The complementary newsgroup for IF *players*, often known as RGIF. + +.. todo:: + + Update these links appropriately. The newsgroups in particular are + mostly unused these days. + +Acknowledgements +================ + +Becoming sufficiently conversant with Inform to be able to share it with +others is not something done quickly or in isolation. In getting to where +we are today, we have been assisted at many times and in many ways by the +notably supportive and good-natured people, far too numerous to list by +name, who make ``rec.arts.int-fiction`` such an invaluable IF resource. We +are grateful to you all. + +In creating this guide, we have received specific help from a number of +people. First and foremost we must mention Graham Nelson, who kindly wrote +the Foreword, and delighted us with long and detailed lists of helpful +comments and suggestions on two of our drafts; also Dennis G. Jerz, who +patiently and skilfully edited the text, making innumerable improvements to +our often wayward and inconsistent prose. David Cornelson supervised the +Second Edition's transformation into professionally printed respectability. +Further assistance came from Barney Firth, Christine Firth, Harry Firth, +Megan Firth, Jim Fisher, Rosemary Frezza, Phil Graham, Graham Holden, Paul +Johnson, Yoon Ha Lee, Brian Pylant, Jo Quinn, Milos Radovanovic, Muffy +St. Bernard, Gunther Schmidl, Emily Short, Curt Siffert, A. Sloe, Pavel +Soukenik, Elise Stone, Brent VanFossen and R. Cliff Young. Thank you: it +is impossible to overstate the value of this freely given support and +assistance. + +The drop capitals, and their associated poem, are from "A Picture +Alphabet", digitised from a collection of public domain woodcuts, circa +1834, by Steven J. Lundeen of emerald city fontwerks. + +.. todo:: + + Reference to the drop-caps should only apply to those places they're + used (just the PDF?). + +All credit to the generosity of http://briefcase.yahoo.com/ for making +international file-sharing such a breeze. + +Finally, of course, we owe an enormous debt of gratitude to Graham Nelson +for devising it all, thereby giving us the opportunity -- first +independently and later in enjoyable collaboration -- of using, and +eventually of presenting, the Inform text adventure development system. + +| *Roger Firth* +| *Wallingford, England* + +| *Sonja Kesserich* +| *Madrid, Spain* + +| *August 2004* + +.. rubric:: Footnotes + +.. [#play] + If you feel confused about IF in general or about this distinction + between writing and playing in particular, try glancing ahead at "Just + what is interactive fiction?" on page 13 and at "How to play an IF game" + on page 209; also, you may find the Ifaq at + http://www.plover.net/~textfire/raiffaq/ifaq/ helpful. diff --git a/chapters/01.rst b/chapters/01.rst new file mode 100644 index 0000000..ece83a9 --- /dev/null +++ b/chapters/01.rst @@ -0,0 +1,229 @@ +====================================== + 1: Just what is interactive fiction? +====================================== + +.. epigraph:: + + | *A was an archer, who shot at a frog;* + | *B was a butcher, who had a great dog.* + +Before we start learning to use the Inform system, it's probably sensible +to consider briefly how IF, which has many narrative elements, differs from +regular storytelling. Before we do *that*, though, let's look at an example +of a familiar folk tale. + + "There was once a man called Wilhelm Tell, from high in the he lived by + his skills Swiss Alps near the town Altdorf. A hunter and a guide, + proud mountaineer, in tracking and archery. It happened one day that + Wilhelm visited the town to buy provisions, and he took his son Walter + with him. + + The region was at the time governed by Hermann Gessler (a vain and + petty man appointed as vogt by the Austrian emperor), who attempted a + show of power over his subjects by placing his hat on a pole in the + town square, for everyone to salute. Reluctant citizens were + "encouraged" by a troop of the vogt's soldiers, who made sure that + their bows were sufficiently respectful. + + Wilhelm knew of the hat, and of the humiliating exercise in obeisance. + So far he had managed to avoid the town's square, sure that -- given + his open dislike for the vogt -- his refusal to bend the knee would + cause trouble. Today, however, he needed to pass near the pole to + reach Johansson's tannery. + + If Wilhelm had hoped for a lucky break, we'll never know. The square + was filled with market-day crowds; the soldiers were especially keen in + their salute- enforcing duties, challenging everyone with loud shouts + and the occasional coarse expletive. Wilhelm threw a protective arm + over his son's shoulder and walked determinedly without looking at the + pole or the guards. + + A soldier called to him; Wilhelm took no notice. Other guards focused + their attention on the archer. "Salute the vogt's hat," he was told. + A tense silence followed. Wilhelm tried to keep going, but by now he + was surrounded. The men knew of him; one counselled Wilhelm to give a + cursory nod towards the hat and be done. Everybody in the vicinity was + watching, so the disrespect could not be ignored. There was a long + pause. Wilhelm refused. + + Word was sent to Gessler, who rushed to the square with reinforcements. + The little man was delighted at the chance of making an example of the + trouble-maker. He mockingly recounted the many skills of Herr Tell, + speculating that such mastery maybe accounted for the pride that + prevented acknowledgement of the Emperor's authority. The vogt + understood all that, and would give him a fair chance. If Wilhelm were + able to shoot true at an apple from fifty paces, Gessler would be + inclined to show mercy; however, to make things interesting, the apple + was to be balanced on Walter's head. + + Everything was set up. Wilhelm selected and mounted an arrow and + slowly raised the bow, conscious of the motionless and brave stance + that Walter was displaying. He pulled, feeling the tension mount on + the string and his fingers, through his hands, into his arms. He'd + made much more difficult shots in the past, at fleeting deer, at + soaring birds; but this was the life of his son... he could not fail, + would not fail. + + Wilhelm let loose. The arrow flew straight and true, violently pinning + the apple to the tree behind the boy. The crowd exploded in a roar of + relief and admiration, and Gessler, disappointed, had no option but to + let them go. + + Years later, Wilhelm led an uprising against the vogt... but that's + another story." + +And now an extract from the same tale, this time in the form of a tiny text +adventure game. If you're new to interaction with text adventures you'll +find some general instructions in "How to play an IF game" on page 209, and +you can see a complete transcript of the game in the "William Tell" story +on page 219:: + + A street in Altdorf + The narrow street runs north towards the town square. Local folk are + pouring into the town through the gate to the south, shouting + greetings, offering produce for sale, exchanging news, enquiring with + exaggerated disbelief about the prices of the goods displayed by + merchants whose stalls make progress even more difficult. + + "Stay close to me, son," you say, "or you'll get lost among all these + people." + + >GO NORTH + + Further along the street + People are still pushing and shoving their way from the southern gate + towards the town square, just a little further north. You recognise + the owner of a fruit and vegetable stall. + + Helga pauses from sorting potatoes to give you a cheery wave. + + "Hello, Wilhelm, it's a fine day for trade! Is this young Walter? + My, how he's grown. Here's an apple for him -- tell him to mind that + scabby part, but the rest's good enough. How's Frau Tell? Give her + my best wishes." + + >INVENTORY + You are carrying: + an apple + a quiver (being worn) + three arrows + a bow + + >TALK TO HELGA + You warmly thank Helga for the apple. + + >GIVE THE APPLE TO WALTER + "Thank you, Papa." + + >NORTH + + South side of the square + The narrow street to the south has opened onto the town square, and + resumes at the far side of this cobbled meeting place. To continue + along the street towards your destination -- Johansson's tannery -- + you must walk north across the square, in the middle of which you see + Gessler's hat set on that loathsome pole. If you go on, there's no + way you can avoid passing it. Imperial soldiers jostle rudely through + the throng, pushing, kicking and swearing loudly. + + ... + +Some of the more obvious differences are highlighted by these questions: + +* Who is the protagonist? + + Our example of narrative prose is written in the third person; it + refers to the hero as "Wilhelm" and "he" and "him", watching and + reporting on his activities from afar. In this sample IF game, you are + the hero, seeing everything through Wilhelm's eyes. + +* What happens next? + + The regular narrative is intended to be read once, straight through + from beginning to end. Unless you didn't pay attention the first time, + or you're planning to critique the story, there's generally no need to + go back and read a sentence twice; if you do, you'll find exactly the + same text. The author leads the way and sets the pace; you, as the + reader, just go along for the ride. In IF, that's usually much less + true. The author has created a landscape and populated it with + characters, but you choose how and when to explore it. The game + evolves, at least superficially, under your control; perhaps you + explore the street first and then the square, perhaps the other way + round. There usually are multiple paths to be found and followed -- + and you can be pretty certain that you won't discover them all, at + least on first acquaintance. + +* How does it all turn out? + + You can tell when you've come to the end of a regular narrative -- you + read the last sentence, and you know there's no more. In IF, it's + clear enough when you reach an end; what's much less apparent is + whether that's the only conclusion. In the transcript from the example + game, you win by shooting the apple from Walter's head. But what if + you miss? What if you hit him by mistake? Or fire instead at the + hated vogt? Or even stand the tale on its head by bowing obsequiously + to the governor's hat and then going about your business? All of these + are possible ways in which the game could come to an end. The phrase + "what if" is the key to writing successfully, and should always be in + the forefront of an IF designer's mind. + +* Where did Helga come from? + + You'll notice that Helga and her stall don't appear in the regular + narrative; she's a distraction from the tale's momentum. But in the IF + game, she fulfils a number of useful functions: mentioning the names + "Wilhelm", "Walter" and "Frau Tell" (so that you know who the tale's + about), introducing the all-important apple in a natural manner and, + above all, providing an opportunity for the "I" in IF -- some + interactivity. Without that -- the chance to interact with the tale's + environment -- the game is little different from a conventional piece + of fiction. + +* That item looks interesting; can you tell me more about it? + + In the regular narrative, what you see is what you get; if you want to + know more about alpine life in the fourteenth century, you'll need to + consult another source. IF, on the other hand, offers at least the + possibility of delving deeper, of investigating in greater detail an + item which has been casually mentioned. For example, you could have + explored Helga's stall:: + + " ... How's Frau Tell? Give her my best wishes." + + >EXAMINE THE STALL + It's really only a small table, with a big heap of potatoes, + some carrots and turnips, and a few apples. + + >EXAMINE THE CARROTS + Fine locally grown produce. + + You see those descriptions only if you seek them; nothing you find + there is unexpected, and if you don't examine the stall, you've not + missed anything important. Nevertheless, you've enhanced the illusion + that you're visiting a real place. Such details would rapidly grow + tedious if the stall and its contents were described in full each time + that you pass them. + +* How do I work this thing? + + Whereas the presence of Helga is an elaboration of the folk tale, the + shooting of the arrow (it's in the transcript in "William Tell" story + on page 219, not in the extract above) illustrates the opposite + principle: simplification. The tale builds dramatic tension by + describing each step as Wilhelm prepares to shoot the apple. That's + OK; he's been an archer all his life, and knows how to do it. You, on + the other hand, probably know little about archery, and shouldn't be + expected to guess at the process and vocabulary. Let's hope you know + that you need to shoot at the apple -- and that's all it takes. The + game explains what was involved, but doesn't force you through each + mundane step. + +Of course, all of these are generalisations, not universal truths; you +could find fine works of IF which contradict each observation. However, +for our purposes as beginners in the craft of IF design, they represent +useful distinctions between IF and conventional fiction. + +We'll come back to the "William Tell" tale in a later chapter, but before +then we'll work through an even simpler example. And before either of +those, we need to download the necessary files which will enable us to +write Inform games. diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..5f579c0 --- /dev/null +++ b/conf.py @@ -0,0 +1,289 @@ +# -*- coding: utf-8 -*- +# +# Inform Beginner's Guide documentation build configuration file, created by +# sphinx-quickstart on Tue Mar 29 07:50:39 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.todo', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['templates'] + +# The suffix(es) of source filenames. +source_suffix = ['.rst'] + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Inform Beginner\'s Guide' +author = u'Roger Firth and Sonja Kesserich' +copyright = u'2016, ' + author + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '4.0' +# The full version, including alpha/beta/rc tags. +release = '4.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['output'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +default_role = "any" + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# The default Pygments highlight language. +highlight_language = 'none' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + 'font_family': 'Georgia', + 'head_font_family': 'Georgia', +} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = project + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'IBG' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', + + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + #'preamble': '', + + # Latex figure (float) alignment + #'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'IBG.tex', project, author, 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'informbeginnersguide', u'Inform Beginner\'s Guide', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'ibg', u'Inform Beginner\'s Guide', + author, 'Inform Beginners Guide', 'Beginner\'s guide to Inform.', + 'Games'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/copyright.rst b/copyright.rst new file mode 100644 index 0000000..a604024 --- /dev/null +++ b/copyright.rst @@ -0,0 +1,5 @@ +=========== + Copyright +=========== + +.. include:: LICENSE diff --git a/endnotes.rst b/endnotes.rst new file mode 100644 index 0000000..fcc9b09 --- /dev/null +++ b/endnotes.rst @@ -0,0 +1,9 @@ +========================== + About the Fourth edition +========================== + +This latest (fourth) edition of this guide is currently being created. +It's a work-in-progress. Here's a partial list of stuff still to do, with +references to their places in the text: + +.. todolist:: diff --git a/foreword.rst b/foreword.rst new file mode 100644 index 0000000..047ea98 --- /dev/null +++ b/foreword.rst @@ -0,0 +1,68 @@ +=========================== + Foreword by Graham Nelson +=========================== + +It would, I think, be immodest to compare myself to Charles Bourbaki +(1816--97), French hero of the Crimean War and renowned strategist, a man +offered nothing less as a reward than the throne of Greece (he declined). +It may be in order, though, to say a few words about his fictitious +relative Nicholas, the most dogged, lugubrious, interminably thorough and +clotted writer of textbooks ever to state a theorem. Rather the way +Hollywood credits movies for which nobody wants the blame to the director +"Alan Smithee" (who by now has quite a solid filmography and even gets the +occasional cinema festival), so in mathematics many small results are +claimed to be the work of Nicholas Bourbaki. Various stories are told of +the birth of Bourbaki, under whose name young Parisian mathematicians have +clubbed together since 1935 to write surveys of whole fields of algebra. +His initials, it may be noted, are NB. Some say "Bourbaki" was an in-joke +at the Ecole Normale Supérieure (much as "zork" and "foobar" were at MIT), +going right back to a practical joke in 1880 when a pupil successfully +impersonated a visiting "General Claude Bourbaki". Folklore also has it +that the real general was notorious when on manoeuvres for being able to +eat *anything* if need be -- stale biscuit, raw turnips, his horse, his +horse's hay, his horse's leather nosebag that the hay used to be in -- just +as Nicholas Bourbaki would have to eat everything there was to eat in the +theory of algebra, no matter how tooth-grinding or chewy. To give credit +where it's due, Bourbaki's forty volumes are quite useful. Or, actually, +they aren't, but it's nice to know they're there. + +It was on reading this present book that I realised the melancholy truth: +that my own volume on Inform, the *Designer's Manual*, is a Bourbaki. It +has to cover every last thing, from Icelandic accents to assembly language +to fake actions, not to mention fake fake actions, to grouping together +almost-but-not-quite-identical objects such as Scrabble tiles -- matters +which a dedicated Inform designer might need to look up once in a lifetime, +or then again might not. To be sure, the basics do turn up every so often, +especially in Chapters II and III, but despite my best intention it is a +gentle introduction only if you pick your way through as if on stepping +stones. This book, on the other hand, is a follow-as-you-go tutorial, +covering the basics thoroughly and a little at a time. Where the +*Designer's Manual* tries never to retrace its steps, so for instance there +is just one section on locations, the *Beginner's Guide* works its way +through three whole games, giving it three chances to visit every subject, +reinforcing and showing a little more each time. + +I should like to say that my first reaction, when out of the blue the +authors sent me advance proofs, was to exclaim with delight at the lucid, +uncluttered, sensible approach. Truthfully, however, that was my third +reaction, the first being jealousy (it's all right for *you*, you don't +have to document how the parser calculates GNA sets for noun clauses) and +the second pique (you've cast the *gizbru spell: turn dangerous object into +a harmless one* at my book). When it comes down to it, though, there is no +greater compliment any writer can be paid than to have someone else choose +to write a book about his work, so I thank Roger and Sonja for their +gesture, as well as the fine job they have done. + +That is quite enough talking about myself, as Inform belongs to all its +users, to the hundreds of serious writers of interactive fiction who find +it helpful, and for almost a decade it has been a collective enterprise. +Today nobody remembers who suggested what. Its world-modelling rules now +resemble a New England patchwork quilt, to which each house in the village +contributes one woven square. As you read this book, you might want to +bear in mind that such a quilt is never finished, and always has room for +one more square from a newly arrived neighbour. + +| *St Anne's College* +| *University of Oxford* +| *April 2002* + diff --git a/history.rst b/history.rst new file mode 100644 index 0000000..a8ab1fb --- /dev/null +++ b/history.rst @@ -0,0 +1,22 @@ + +Release history +=============== + +.. list-table:: + :widths: 1 1 2 + + * - First Edition + - April 2002 + - + + * - Second Edition + - August 2002 + - Minor revisions + + * - Third Edition + - August 2004 + - Alignment with Inform 6.30, further minor revisions + + * - Fourth Edition + - March--May 2016 + - Reformatting and more minor revisions diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..b89b129 --- /dev/null +++ b/index.rst @@ -0,0 +1,27 @@ +============================= + The Inform Beginner's Guide +============================= + +Contents: + +.. toctree:: + :maxdepth: 2 + :glob: + + copyright + history + foreword + about + chapters/* + +Indices: + +* :ref:`genindex` +* :ref:`search` + +End notes: + +.. toctree:: + :maxdepth: 2 + + endnotes diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..11f83d1 --- /dev/null +++ b/make.bat @@ -0,0 +1,272 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=output +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. epub3 to make an epub3 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\IBG.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\IBG.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "epub3" ( + %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end