fa4f516349b27ef46cbcc9ac14158157c7ef63bf
[ibg.git] / chapters / 14.rst
1 ========================
2  Some last lousy points
3 ========================
4
5 .. only:: html
6
7   .. image:: /images/picF.png
8      :align: left
9
10 .. raw:: latex
11
12    \dropcap{f}
13
14 inally our three example games are written; we've shown you as much of 
15 the Inform language as we've needed to, and made a lot of observations 
16 about how and why something should be done. Despite all that, there's 
17 much that we've left unsaid, or touched on only lightly. In this chapter 
18 we'll revisit key topics and review some of the more significant 
19 omissions, to give you a better feel for what's important, and what can 
20 be ignored for the time being; when you become an accomplished designer, 
21 you will decide what matters and what can be left on the shelf.
22
23 We'll also talk, in :ref:`reading-other-code`, about a few ways of doing
24 things that we've chosen not to tell you about, but which you're quite
25 likely to encounter if you look at Inform code written by other designers.
26
27 The tone here is perhaps a little dry, but trust us: in walking this 
28 dusty ground we touch on just about everything that is fundamental in 
29 your overall understanding of Inform. And as always, the *Inform 
30 Designer's Manual* provides rounder and more comprehensive coverage.
31
32 Expressions
33 ===========
34
35 In this guide we’ve used the placeholder ``expression`` a few times; 
36 here's roughly what we mean.
37
38 * An ``expression`` is a single ``value``, or several ``values`` 
39   combined using ``operators`` and sometimes parentheses ``(...)``.
40
41 * Possible ``values`` include:
42
43   * a literal number (-32768 to 32767)
44
45   * something that's represented as a number (a character ``'a'`` , a 
46     dictionary word ``'aardvark'`` , a string ``"aardvark's adventure"`` 
47     or an action ``##Look`` )
48
49   * the internal identifier of a constant, an object, a class or a routine
50
51   * (only in a run-time statement, not in a compile-time directive) the
52     contents of a variable, or the return value from a routine.
53
54 * Possible ``operators`` include:
55
56   * an arithmetic operator: ``+ - * / % ++``
57   * a bitwise logical operator: ``& | ~``
58   * a numeric comparison operator: ``== ~= > < >= <=``
59   * an object conditional operator: ``ofclass in notin provides has hasnt``
60   * a boolean combinational operator: ``&& || ~~``
61
62
63 Internal IDs
64 ============
65
66 Many of the items which you define in your source file -- objects, 
67 variables, routines, etc. -- need to be given a name so that other items 
68 can refer to them. We call this name an item's internal identifier 
69 (because it's used only within the source file and isn't visible to the 
70 player), and we use the placeholders ``obj_id``, ``var_id``, 
71 ``routine_id``, etc. to represent where it's used. An internal ID
72
73 * can be up to thirty-two characters long
74
75 * must start with a letter or underscore, and then continue with letters 
76   ``A-Z`` , underscore ``_`` and digits ``0-9`` (where upper-case and 
77   lower-case letters are treated as indistinguishable)
78
79 * should generally be unique across all files: your source file, the 
80   standard library files, and any library contributions which you've 
81   used (except that a routine's local variables are not visible outside 
82   that routine).
83
84 .. _statements:
85
86 Statements
87 ==========
88
89 A :term:`statement` is an instruction intended for the interpreter, telling
90 it what to do at run-time. It *must* be given in lower-case, and always
91 ends with a semicolon.
92
93 Some statements, like ``if``, control one or more other statements. We 
94 use the placeholder ``statement_block`` to represent either a single 
95 ``statement``, or any number of ``statements`` enclosed in braces:
96
97 .. todo::
98
99   We might need some custom syntax highlighting here
100
101 .. code-block:: inform
102
103   statement;
104
105   { statement; statement; ... statement; }
106
107 Statements that we've met
108 -------------------------
109
110 Our games have used these statements, about half of the Inform 
111 possibilities:
112
113 .. code-block:: inform
114
115   give obj_id attribute;
116   give obj_id attribute attribute ... attribute;
117
118   if (expression) statement_block
119   if (expression) statement_block else statement_block
120
121   move obj_id to parent_obj_id;
122
123   objectloop (var_id) statement_block
124
125   print value;
126   print value, value, ... value;
127
128   print_ret value;
129   print_ret value, value, ... value;
130
131   remove obj_id;
132
133   return false;
134   return true;
135
136   style underline; print...; style roman;
137
138   switch (expression) {
139       value: statement; statement; ... statement;
140       ...
141       default: statement; statement; ... statement;
142   }
143
144   "string";
145   "string", value, ... value;
146
147   <action>;
148   <action noun>;
149   <action noun second>;
150
151   <<action>>;
152   <<action noun>>;
153   <<action noun second>>;
154
155 Statements that we've not met
156 -----------------------------
157
158 Although our example games haven't needed to use them, these looping
159 statements are sometimes useful:
160
161 .. code-block:: inform
162
163   break;
164   continue;
165
166   do statement_block until (expression)
167
168   for (set_var : loop_while_expression : update_var) statement_block
169
170   while (expression) statement_block
171
172 On the other hand, we suggest that you put the following statements on 
173 hold for now; they're not immediately relevant to everyday code and have 
174 mostly to do with printing and formatting:
175
176 .. code-block:: inform
177
178   box
179   font
180   jump
181   new_line
182   spaces
183   string
184
185 In particular, avoid using the deprecated jump statement if you possibly can.
186
187 Print rules
188 -----------
189
190 In ``print`` and ``print_ret`` statements, each ``value`` can be:
191
192 * a numeric ``expression``, displayed as a signed decimal number,
193
194 * a ``"string"``, displayed literally, or
195
196 * a print rule. You can create your own, or use a standard one, including:
197
198   .. tabularcolumns:: ll
199
200   +-------------------------+---------------------------------------------------+
201   | ``(a) obj_id``          | the object's name, preceded by "a", "an" or "some"|
202   +-------------------------+---------------------------------------------------+
203   | ``(A) obj_id``          | as ``(a)`` but using "A", "An" or "Some"          |
204   +-------------------------+---------------------------------------------------+
205   | ``(the) obj_id``        | the object's name, preceded by "the"              |
206   +-------------------------+---------------------------------------------------+
207   | ``(The) obj_id``        | as ``(the)`` but using "The"                      |       
208   +-------------------------+---------------------------------------------------+
209   | ``(number) expression`` | the numeric expression's value in words           |
210   +-------------------------+---------------------------------------------------+
211
212
213 Directives
214 ==========
215
216 A :term:`directive` is an instruction intended for the compiler, telling it
217 what to do at compile-time, while the source file is being translated into
218 Z-code. By convention it's given an initial capital letter (though the
219 compiler doesn't enforce this) and always ends with a semicolon.
220
221 Directives that we've met
222 -------------------------
223
224 We've used all of these directives; note that for ``Class``, ``Extend``, 
225 ``Object`` and ``Verb`` the full supported syntax is more sophisticated 
226 than the basic form presented here:
227
228 .. code-block:: inform
229
230   Class   class_id
231     with  property  value,
232           property  value,
233           ...
234           property  value,
235     has   attribute  attribute  ...  attribute;
236
237   Constant  const_id:
238   Constant  const_id = expression;
239   Constant  const_id expression;
240
241   Extend 'verb'
242       * token  token  ...  token -> action
243       * token  token  ...  token -> action
244       ...
245       * token  token  ...  token -> action
246
247   Include "filename";
248
249   Object  obj_id  "external_name"  parent_obj_id
250     with  property  value,
251           property  value,
252           ...
253           property  value,
254     has   attribute  attribute  ... attribute;
255
256   Release  expression;
257
258   Replace  routine_id;
259
260   Serial "yymmdd";
261
262   Verb  'verb'
263       * token  token  ...  token -> action
264       * token  token  ...  token -> action
265       ...
266       * token  token  ...  token -> action;
267
268   ! comment text which the compiler ignores
269
270   [ routine_id;  statement;  statement; ... statement;  ];
271
272   #Ifdef  any_id;  ... #Endif;
273
274 Directives that we've not met
275 -----------------------------
276
277 There's only a handful of useful directives which we haven't needed to 
278 use:
279
280 .. code-block:: inform
281
282   Attribute attribute;
283
284   Global var_id;
285   Global var_id = expression;
286
287   Property property;
288
289   Statusline score;
290   Statusline time;
291
292 but there's a whole load which are of fairly low importance for now:
293
294 .. code-block:: inform
295
296   Abbreviate
297   Array
298   Default
299   End
300   Ifndef
301   Ifnot
302   Iftrue
303   Iffalse
304   Import
305   Link
306   Lowstring
307   Message
308   Switches
309   System_file
310   Zcharacter
311
312 .. _objects:
313
314 Objects
315 =======
316
317 An object is really just a collection of variables which together 
318 represent the capabilities and current status of some specific component 
319 of the model world. Full variables are called properties; simpler 
320 two-state variables are attributes.
321
322 Properties
323 ----------
324
325 The library defines around forty-eight standard property variables (such 
326 as ``before`` or ``name``), but you can readily create further ones just 
327 by using them within an object definition.
328
329 You can create and initialise a property in an object's ``with`` segment:
330
331 .. code-block:: inform
332
333   property,                             ! set to zero / false
334
335   property value,                       ! set to a single value
336
337   property value value ... value,       ! set to a list of values
338
339 In each case, the ``value`` is either a compile-time ``expression``, or 
340 an embedded routine:
341
342 .. code-block:: inform
343
344   property expression,
345
346   property [; statement; statement; ... statement; ],
347
348
349 You can refer to the value of a property:
350
351 .. code-block:: inform
352
353   self.property                         ! only within that same object
354
355   obj_id.property                       ! everywhere
356
357 and you can test whether an object definition includes a given property:
358
359 .. code-block:: inform
360
361   (obj_id provides property)            ! is true or false
362
363 .. _routines:
364
365 Routines
366 ========
367
368 Inform provides standalone routines and embedded routines.
369
370 Standalone routines
371 -------------------
372
373 Standalone routines are defined like this:
374
375 .. code-block:: inform
376
377   [ routine_id; statement; statement; ... statement; ];
378
379 and called like this:
380
381 .. code-block:: inform
382
383   routine_id()
384
385 Embedded routines
386 -----------------
387
388 These are embedded as the value of an object's property:
389
390 .. code-block:: inform
391
392   property [; statement; statement; ... statement; ],
393
394 and are usually called automatically by the library, or manually by:
395
396 .. code-block:: inform
397
398   self.property()                       ! only within that same object
399
400   obj_id.property()                     ! everywhere
401
402 Arguments and local variables
403 -----------------------------
404
405 Both types of routine support up to fifteen local variables -- variables 
406 which can be used only by the statements within the routine, and which 
407 are automatically initialised to zero every time that the routine is 
408 called:
409
410 .. code-block:: inform
411
412   [ routine_id var_id var_id ... var_id; statement; statement; ... statement; ];
413
414   property [ var_id var_id ... var_id; statement; statement; ... statement; ],
415
416 You can pass up to seven arguments to a routine, by listing those 
417 arguments within the parentheses when you call the routine. The effect 
418 is simply to initialise the matching local variables to the argument 
419 values rather than to zero:
420
421 .. code-block:: inform
422
423   routine_id(expression, expression, ... expression)
424
425 Although it works, this technique is rarely used with embedded routines, 
426 because there is no mechanism for the library to supply argument values 
427 when calling the routine.
428
429 Return values
430 -------------
431
432 Every routine returns a single value, which is supplied either 
433 explicitly by some form of return statement:
434
435 .. code-block:: inform
436
437   [ routine_id; statement; statement; ... return expr; ]; ! returns expr
438
439   property [; statement; statement; ... return expr; ], ! returns expr
440
441 or implicitly when the routine runs out of statements. If none of these 
442 ``statements`` is one -- ``return``, ``print_ret``, ``"..."` or 
443 ``<<...>>`` -- that causes an explicit return, then:
444
445 .. code-block:: inform
446
447   [ routine_id; statement; statement; ... statement; ];
448
449 returns ``true`` and
450
451 .. code-block:: inform
452
453   property [; statement; statement; ... statement; ]
454
455 return ``false``.
456
457 This difference is *important*. Remember it by the letter pairs STEF: 
458 left to themselves, Standalone routines return True, Embedded routines 
459 return False.
460
461 Here's an example standalone routine which returns the larger of its two
462 argument values:
463
464 .. code-block:: inform
465
466   [ Max a b; if (a > b) return a; else return b; ];
467
468 and here are some examples of its use (note that the first example, 
469 though legal, does nothing useful whatsoever):
470
471 .. code-block:: inform
472
473   Max(x,y);
474
475   x = Max(2,3);
476
477   if (Max(x,7) == 7) ...
478
479   switch (Max(3,y)) { ...
480
481 Library routines versus entry points
482 ------------------------------------
483
484 A library routine is a standard routine, included within the library 
485 files, which you can optionally call from your source file if you 
486 require the functionality which the routine provides. We've mentioned 
487 these library routines:
488
489 .. code-block:: inform
490
491   IndirectlyContains(parent_obj_id, obj_id)
492
493   PlaceInScope(obj_id)
494
495   PlayerTo(obj_id, flag)
496
497   StartDaemon(obj_id)
498
499   StopDaemon(obj_id)
500
501
502 By contrast, an entry point routine is a routine which you can provide 
503 in your source file, in which case the library calls it at an 
504 appropriate time. We've mentioned these optional entry point routines:
505
506 .. code-block:: inform
507
508   DeathMessage()
509
510   InScope(actor_obj_id)
511
512 And this, the only mandatory one:
513
514 .. code-block:: inform
515
516   Initialise()
517
518 There are full lists in :ref:`library-routines` and :ref:`entry-points`.
519
520 .. _reading-other-code:
521
522 Reading other people's code
523 ===========================
524
525 Right at the start of this guide, we warned you that we weren't setting 
526 out to be comprehensive; we've concentrated on presenting the most 
527 important aspects of Inform, as clearly as we can. However, when you 
528 read the *Inform Designer's* Manual, and more especially when you look 
529 at complete games or library extensions which other designers have 
530 produced, you'll come across other ways of doing things -- and it might 
531 be that you, like other authors, prefer them over our methods. Just try 
532 to find a style that suits you and, this is the important bit, be 
533 *consistent* about its use. In this section, we highlight some of the 
534 more obvious differences which you may encounter.
535
536 Code layout
537 -----------
538
539 Every designer has his or her own style for laying out their source 
540 code, and they're all worse than the one you adopt. Inform's flexibility 
541 makes it easy for designers to choose a style that suits them; 
542 unfortunately, for some designers this choice seems influenced by the 
543 Jackson Pollock school of art. We've advised you to be consistent, to 
544 use plenty of white space and indentation, to choose sensible names, to 
545 add comments at difficult sections, to actively *think*, as you write 
546 your code, about making it as readable as you can.
547
548 This is doubly true if you ever contemplate sharing a library extension 
549 with the rest of the community. This example, with the name changed, is 
550 from a file in the Archive:
551
552 .. code-block:: inform
553
554   [xxxx i j;
555   if (j==0) rtrue;
556   if (i in player) rtrue;
557   if (i has static || (i has scenery)) rtrue;
558   action=##linktake;
559   if (runroutines(j,before) ~= 0 || (j has static || (j has scenery))) {
560   print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
561   rtrue;
562   }
563   else {
564   if (runroutines(i,before)~=0 || (i has static || (i has scenery))) {
565   print "You'll have to disconnect ",(the) i," from ",(the) j," first.^";
566   rtrue;
567   }
568   else
569   if (j hasnt concealed && j hasnt static) move j to player;
570   if (i hasnt static && i hasnt concealed) move i to player;
571   action=##linktake;
572   if (runroutines(j,after) ~= 0) rtrue;
573   print "You take ",(the) i," and ",(the) j," connected to it.^";
574   rtrue;
575   }
576   ];
577
578 Here's the same routine after a few minutes spent purely on making it 
579 more comprehensible; we haven't actually tested that it (still) works, 
580 though that second ``else`` looks suspicious:
581
582 .. code-block:: inform
583
584   [ xxxx i j;
585       if (i in player || i has static or scenery || j == nothing) return true;
586       action = ##LinkTake;
587       if (RunRoutines(j,before) || j has static or scenery)
588           "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
589       else {
590           if (RunRoutines(i,before) || i has static or scenery)
591               "You'll have to disconnect ", (the) i, " from ", (the) j, " first.";
592           else
593               if (j hasnt static or concealed) move j to player;
594           if (i hasnt static or concealed) move i to player;
595           if (RunRoutines(j,after)) return true;
596           "You take ", (the) i, " and ", (the) j, " connected to it.";
597       }
598   ];
599
600 We hope you'll agree that the result was worth the tiny extra effort. 
601 Code gets written once; it gets read dozens and dozens of times.
602
603 Shortcuts
604 ---------
605
606 There are a few statement shortcuts, some more useful than others, which 
607 you'll come across.
608
609 * These five lines all do the same thing:
610
611   .. code-block:: inform
612
613     return true;
614     return 1;
615     return;
616     rtrue;
617     ];          ! at the end of a standalone routine
618
619 * These four lines all do the same thing:
620
621   .. code-block:: inform
622
623     return false;
624     return 0;
625     rfalse;
626     ];          ! at the end of an embedded routine
627
628 * These four lines all do the same thing:
629
630   .. code-block:: inform
631
632     print "string"; new_line; return true;
633     print "string^"; return true;
634     print_ret "string";
635     "string";
636
637 * These lines are the same:
638
639   .. code-block:: inform
640
641     print value1; print value2; print value3;
642     print value1, value2, value3;
643
644 * These lines are the same:
645
646   .. code-block:: inform
647
648     <action noun second>; return true;
649     <<action noun second>>;
650
651 * These lines are also the same:
652
653   .. code-block:: inform
654
655     print "^";
656     new_line;
657
658 * These ``if`` statements are equivalent:
659
660   .. code-block:: inform
661
662     if (MyVar == 1 || MyVar == 3 || MyVar == 7) ...
663
664     if (MyVar == 1 or 3 or 7) ...
665
666 * These ``if`` statements are equivalent as well:
667
668   .. code-block:: inform
669
670     if (MyVar ~= 1 && MyVar ~= 3 && MyVar ~= 7) ...
671     if (MyVar ~= 1 or 3 or 7) ...
672
673 * In an ``if`` statement, the thing in parentheses can be *any* 
674   expression; all that matters is its value: zero (false) or anything 
675   else (true). For example, these statements are equivalent:
676
677   .. code-block:: inform
678
679     if (MyVar ~= false) ...
680     if (~~(MyVar == false)) ...
681     if (MyVar ~= 0) ...
682     if (~~(MyVar == 0)) ...
683     if (MyVar) ...
684
685   Note that the following statement specifically tests whether ``MyVar`` 
686   contains ``true`` (1), *not* whether its value is anything other than 
687   zero.
688
689   .. code-block:: inform
690
691     if (MyVar == true) ...
692
693 * If ``MyVar`` is a variable, the statements ``MyVar++;`` and 
694   ``++MyVar;`` work the same as ``MyVar = MyVar + 1;`` For example, 
695   these lines are equivalent:
696
697   .. code-block:: inform
698
699     MyVar = MyVar + 1; if (MyVar == 3) ...
700     if (++MyVar == 3) ...
701     if (MyVar++ == 2) ...
702
703   What's the same about ``MyVar++`` and ``++MyVar`` is that they both 
704   add one to ``MyVar``. What's different about them is the value to 
705   which the construct itself evaluates: ``MyVar++`` returns the current 
706   value of ``MyVar`` and then performs the increment, whereas 
707   ``++MyVar`` does the "+1" first and then returns the incremented 
708   value. In the example, if ``MyVar`` currently contains 2 then 
709   ``++MyVar`` returns 3 and ``MyVar++`` returns 2, even though in both 
710   cases the value of ``MyVar`` afterwards is 3. As another example, 
711   this code (from Helga in "William Tell"):
712
713   .. code-block:: inform
714
715     Talk: self.times_spoken_to = self.times_spoken_to + 1;
716         switch (self.times_spoken_to) {
717             1: score = score + 1;
718                print_ret "You warmly thank Helga for the apple.";
719             2: print_ret "~See you again soon.~";
720             default: return false;
721         }
722     ],
723
724   could have been written more succinctly like this:
725
726   .. code-block:: inform
727
728     Talk: switch (++self.times_spoken_to) {
729         1: score++;
730            print_ret "You warmly thank Helga for the apple.";
731         2: print_ret "~See you again soon.~";
732         default: return false;
733         }
734     ],
735
736 * Similarly, the statements ``MyVar--;`` and ``--MyVar;`` work the same 
737   as ``MyVar = MyVar - 1;`` Again, these lines are equivalent:
738
739   .. code-block:: inform
740
741     MyVar = MyVar - 1; if (MyVar == 7) ...
742     if (--MyVar == 7) ...
743     if (MyVar-- == 8) ...
744
745 "number" property and "general" attribute
746 -----------------------------------------
747
748 The library defines a standard ``number`` property and a standard 
749 ``general`` attribute, whose roles are undefined: they are 
750 general-purpose variables available within every object to designers as 
751 and when they desire.
752
753 We recommend that you avoid using these two variables, primarily because 
754 their names are, by their very nature, so bland as to be largely 
755 meaningless. Your game will be clearer and easier to debug if you 
756 instead create new property variables -- with appropriate names -- as 
757 part of your ``Object`` and ``Class`` definitions.
758
759 .. _common-props:
760
761 Common properties and attributes
762 --------------------------------
763
764 As an alternative to creating new individual properties which apply only to
765 a single object (or class of objects), it's possible to devise properties
766 and new attributes which, like those defined by the library, are available
767 on *all* objects. The need to do this is actually quite rare, and is mostly
768 confined to library extensions (for example, the ``pname.h`` extension
769 which we encountered in :doc:`12` gives every object a ``pname`` property
770 and a ``phrase_matched`` attribute). To create them, you would use these
771 directives near the start of your source file:
772
773 .. code-block:: inform
774
775   Attribute attribute;
776
777   Property property;
778
779 We recommend that you avoid using these two directives unless you really 
780 do need to affect every object -- or at least the majority of them -- in 
781 your game. There is a limit of forty-eight attributes (of which the 
782 library currently defines around thirty) and sixty-two of these common 
783 properties (of which the library currently defines around forty-eight). 
784 On the other hand, the number of individual properties which you can add 
785 is virtually unlimited.
786
787 .. _setting-up-tree:
788
789 Setting up the object tree
790 --------------------------
791
792 Throughout this guide, we've defined the initial position of each object 
793 within the overall object tree either by explicitly mentioning its 
794 parent's ``obj_id`` (if any) in the first line of the object definition 
795 -- what we've been calling the header information -- or, for a few 
796 objects which crop up in more than one place, by using their 
797 ``found_in`` properties. For example, in "William Tell" we defined 
798 twenty-seven objects; omitting those which used ``found_in`` to define 
799 their placement at the start of the game, we're left with object 
800 definitions starting like this:
801
802 .. code-block:: inform
803
804   Room    street "A street in Altdorf"        
805
806   Room    below_square "Further along the street"
807   Furniture   stall "fruit and vegetable stall" below_square
808   Prop    "potatoes" below_square
809   Prop    "fruit and vegetables" below_square
810   NPC     stallholder "Helga" below_square
811
812   Room    south_square "South side of the square"
813
814   Room    mid_square "Middle of the square"
815   Furniture   pole "hat on a pole" mid_square
816
817   Room    north_square "North side of the square"
818
819   Room    marketplace "Marketplace near the square"
820   Object  tree "lime tree" marketplace
821   NPC     governor "governor" marketplace
822
823   Object  bow "bow"
824
825   Object  quiver "quiver"
826   Arrow   "arrow" quiver
827   Arrow   "arrow" quiver
828   Arrow   "arrow" quiver
829
830   Object  apple "apple"
831
832 You'll see that several of the objects begin the game as parents: 
833 ``below_square``, ``mid_square``, ``marketplace`` and ``quiver`` all 
834 have child objects beneath them; those children mention their parent as 
835 the last item of header information.
836
837 There's an alternative object syntax which is available to achieve the 
838 same object tree, using "arrows". That is, we could have defined those 
839 parent-and-child objects as:
840
841 .. code-block:: inform
842
843   Room    below_square "Further along the street"
844   Furniture -> stall "fruit and vegetable stall"
845   Prop      -> "potatoes"
846   Prop      -> "fruit and vegetables"
847   NPC       -> stallholder "Helga"
848
849   Room      mid_square "Middle of the square"
850   Furniture   -> pole "hat on a pole"
851
852   Room      marketplace "Marketplace near the square"
853   Object    -> tree "lime tree"
854   NPC       -> governor "governor"
855
856   Object    quiver "quiver"
857   Arrow     -> "arrow"
858   Arrow     -> "arrow"
859   Arrow     -> "arrow"
860
861 The idea is that an object's header information *either* starts with an 
862 arrow, or ends with an ``obj_id``, or has neither (having both isn’t 
863 permitted). An object with neither has no parent: in this example, 
864 that's all the ``Rooms``, and also the ``bow`` and the ``quiver`` (which 
865 are moved to the player ``object`` in the ``Initialise`` routine) and 
866 the apple (which remains without a parent until Helga gives it to 
867 William).
868
869 An object which starts with a single arrow ``->`` is defined to be a 
870 child of the nearest previous object without a parent. Thus, for 
871 example, the ``tree`` and ``governor`` objects are both children of the 
872 ``marketplace``. To define a child of a child, you'd use two arrows
873 ``-> ->``, and so on. In "William Tell", that situation doesn't occur; 
874 to illustrate how it works, imagine that at the start of the game the 
875 potatoes and the other fruit and vegetables where actually *on* the 
876 stall. Then we might have used:
877
878 .. code-block:: inform
879
880   Room    below_square "Further along the street"
881   Furniture ->  stall "fruit and vegetable stall"
882   Prop    ->  -> "potatoes"
883   Prop    ->  -> "fruit and vegetables"
884   NPC     -> stallholder "Helga"
885   ...
886
887 That is, the objects with one arrow (the ``stall`` and ``stallholder``) 
888 are children of the nearest object without a parent (the ``Room``), and 
889 the objects with two arrows (the produce) are children of the nearest 
890 object defined with a single arrow (the ``stall``).
891
892 The advantages of using arrows include:
893
894 * You're forced to define your objects in a "sensible" order.
895
896 * Fewer ``obj_ids`` may need to be used (though in this game it would 
897   make no difference).
898
899 The disadvantages include:
900
901 * The fact that objects are related by the physical juxtaposition of 
902   their definitions is not necessarily intuitive to all designers.
903
904 * Especially in a crowded room, it’s harder to be certain exactly how 
905   the various parent–child relationships are initialised, other than by 
906   carefully counting lots of arrows.
907
908 * If you relocate the parent within the initial object hierarchy to a 
909   higher or lower level, you'll need also to change its children by 
910   adding or removing arrows; this isn't necessary when the parent is 
911   named in the child headers.
912
913 We prefer to explicitly name the parent, but you'll encounter both forms 
914 very regularly.
915
916 Quotes in "name" properties
917 ---------------------------
918
919 We went to some lengths, way back in :ref:`things-in-quotes`, to explain
920 the difference between double quotes ``"..."`` (strings to be output) and
921 single quotes ``'...'`` (input tokens -- dictionary words).  Perhaps
922 somewhat unfortunately, Inform allows you to blur this clean distinction:
923 you can use double quotes in name properties and Verb directives:
924
925 .. code-block:: inform
926
927   NPC     stallholder "Helga" below_square
928     with  name "stallholder" "greengrocer" "monger" "shopkeeper" "merchant"
929               "owner" "Helga" "dress" "scarf" "headscarf",
930   ...
931
932   Verb "talk" "t//" "converse" "chat" "gossip"
933       * "to"/"with" creature          -> Talk
934       * creature                      -> Talk;
935
936 *Please* don't do this. You'll just confuse yourself: those are 
937 dictionary words, not strings; it's just as easy -- and far clearer -- 
938 to stick rigidly to the preferred punctuation.
939
940 Obsolete usages
941 ---------------
942
943 Finally, remember that Inform has been evolving since 1993. Over that 
944 time, Graham has taken considerable care to maintain as much 
945 compatibility as possible, so that games written years ago, for earlier 
946 versions of the compiler and the library, will still compile today. 
947 While generally a good thing, this brings the disadvantage that a 
948 certain amount of obsolete baggage is still lying around. You may, for 
949 example, see games using ``Nearby`` directives (denotes parentage, 
950 roughly the same as ``->``) and ``near`` conditions (roughly, having the 
951 same parent), or with ``" \ "`` controlling line breaks in long 
952 ``print`` statements. Try to understand them; try *not* to use them.
953
954