Dual- versus single-volume mode, and how to write instructions files.

§1. Model. Conceptually, an Indoc project has either one or two volumes. The source for each volume is a single UTF-8 encoded plain text file. In the core Inform repository, there are two volumes, with the files being 

    Documentation/Writing with Inform.txt
    Documentation/The Recipe Book.txt

These are independent books, with individual titles. It would seem simpler just to make them two different Indoc projects, but in dual-volume mode, Indoc can generate joint contents pages, and provide crosswise HTML links between the two volumes.

The project can also include a number of "Examples", each being a single text file such as: 

    Documentation/Examples/Prague.txt

which is the source for an Inform example called "The Prague Job". (These same text files are also used by Intest to test that all of the code samples included in the Inform documentation actually work as claimed.) There can be any number of examples, including none; Inform currently has 468.

Each volume is divided into a series of chapters, and each chapter into a series of sections. Examples are always placed at the ends of sections; note that in dual-volume mode, examples are (mostly) present in both volumes, giving them two different locations. Thus, "The Prague Job" appears in section "More general linkages" of chapter "Scenes" of volume "Writing with Inform", and also in section "Scripted Scenes" of chapter "Time and Plot" of volume "The Recipe Book".

§2. Project instructions. The main instructions file for an Indoc project is, as noted earlier, at: 

    Documentation/indoc-instructions.txt

An instruction file is a UTF-8 encoded plain text file. Single instructions occupy single lines (i.e., line breaks are significant). A white-space line, or a line whose first non-white-space character is a #, are ignored.

The file should begin by specifying one or two volumes, and then, if they will contain Examples in the above sense, by giving the special examples instruction. Inform opens thus: 

    volume: Writing with Inform
    volume: The Inform Recipe Book (RB) = The Recipe Book.txt
    examples

But a simpler, single-volume project might have just: 

    volume: Pandemonium 2.0 for Fun and Profit

Each volume has a title, and Indoc automatically generates an abbreviation for it: by default, it takes the capital letters from the title, so that it abbreviates "Writing with Inform" to WI. That same method would have made turned "The Inform Recipe Book" into TIRB, but because we didn't want that, we supplied our own abbreviation RB instead.

The third, also optional, part of a volume instruction specifies the leafname of the documentation source file for it. By default, this will be the title plus .txt: for example, Writing with Inform.txt. But we can use = X to specify that it should be X instead.

Two other project instructions exist:

If the project will contain images, then they will be looked for in a list of places. Top of the list is a directory internal to Indoc which includes some navigation icons such as arrow-up.png. The instruction images: X adds the directory X to this source list.

Lastly, the cover image for the project can be specified with an instruction such as: 

    cover: combined_cover.png

This specifies a leafname which must exist in one of the image sources mentioned above.

§3. Dublin Core metadata. If the project needs to generate Epub books, then these will need to have some basic DC ("Dublin Core") metadata supplied. For example: 

    dc:title: Inform - A Design System for Interactive Fiction
    dc:creator: Graham Nelson and Emily Short
    dc:subject: Interactive Fiction
    dc:identifier: wwi-rb-combined

The instruction dc:KEY: VALUE supplies a DC key-value pair.

§4. Targets. The instructions file typically begins as above, but then goes into a block of general settings or instructions (for which see below); and eventually gets around to describing one or more targets. A target looks like so: 

    IDENTIFIER {
        ...
    }

where IDENTIFIER is its name. Targets, as noted in the introduction, are different forms of the documentation we might need to produce: Inform, for example, has targets called plain, website, linux_app and so on. What's important here is not that these are written to different locations on disc (though they are) but that they have finicky little differences in settings. The ... stretch of lines can specify these. For example: 

    ebook {
        granularity = 2
        examples_mode = open
        follow: epub-css-tweaks.txt
    }

makes two specific settings and one instruction, all applying only for the target ebook.

§5. Symbols. The instruction declare: SYMBOL creates the symbol SYMBOL. These exist so that we can mark certain paragraphs of documentation as being present in only some of the targets.

For example, we might want Linux installation instructions to appear only in the Linux version of a manual. To do that, we'll need the symbol: 

    linux_app {
        ...
        declare: Linux
        ...
    }

In the documentation, we could then mark up a paragraph like so: 

    {Linux:}To install, first...

The symbol indoc is always declared, but by default no other symbols are. Lastly, undeclare: SYMBOL removes a symbol.

§6. Other instructions. follow: I tells Indoc to follow the instructions file I. This works rather like #include in C, or similar languages. If the follow: is included inside a target block, then it affects only that target. On other targets, the file I won't even be opened, and need never exist.

css: specifies additional CSS (Cascading Style Sheet) styling. This will be needed only if, for example, unusual indexing features are used, in which different categories of index entry need different visual styling. For example, 

    css: span.indextitle ++ {
        font-style: italic;
    }

Here the material between the braces is pure CSS, not Indoc syntax. The notation ++ here tells Indoc that an entirely new CSS style is being created; + would supply new lines to an existing style.

index: NOTATION = CATEGORY OPTION defines a new indexing markup notation; for example, 

    index: ^{@headword} = name (invert)

says that markup notations like ^{@Andrew Plotkin} put a name into the index, which should be an index entry of category name, and should be inverted, in that it will be alphabetised under "Plotkin, Andrew". The text headword in the prototype is where the entry text should appear in the notation.

§7. Miscellaneous settings. There are a great many of these, but most are set to sensible defaults, and it is not compulsory to set any of them. Lines such as 

    SETTING = VALUE

change the default settings if need be. Here is an A-Z list; they're really too miscellaneous to be grouped usefully by subject matter.

alphabetization sets the index sorting algorithm. The default is letter-by-letter; the alternative is word-by-word. The difference is that letter-by-letter would ignore word divisions and sort in the order "peach", "peachpit", "peach tree"; whereas word-by-word would go for "peach", "peach tree", "peachpit".

assume_Public_Library can be yes or no. The default is no. This specifies whether special HTML links to the Public Library will be valid; outside of Inform UI apps, the answer is definitely no.

change_logs_directory is the path to a directory holding Inform release change log files. By default, this will be Documentation/Change Logs.

contents_leafname is the (unextended) leafname to give the HTML contents page. The default is index.

contents_expandable can be yes or no. The default is no. This sets whether Javascript-powered "expand" buttons are to be used in the contents page, and has effect only on the Midnight navigation design.

css_source_file is the filename of the CSS style sheet to use. The default is the base.css file included in the Indoc distribution.

definitions_filename is the filename to use if you would like Indoc to output a special file of Inform phrase definitions, for use by Inform itself when it generates indexes. The default for this is definitions.html. This has nothing to do with the definitions_index_filename.

definitions_index_filename is the leafname to use for the General Index in the documentation. The default is general_index.html. This has nothing to do with the definitions_filename.

destination is the directory into which output is generated. The default is Documentation/Output. Note that specifying -to X at the command line overrides this setting: if -to is used, destination is ignored.

examples_directory is the directory holding the Example files. The default is Documentation/Examples.

examples_alphabetical_leafname is the leafname to use for the alphabetical index of examples in the documentation. The default is examples_alphabetical.html.

examples_granularity is 1, 2, or 3. It can never be less than granularity, and by default is equal to it. It specifies where examples should appear: at the end of the relevant volume (1), chapter (2), or section (3).

examples_mode is open or openable, and is by default open. Open means that an example has its full contents visible by default; openable means that the contents are hidden behind a Javascript-powered button which causes them to be revealed.

examples_numerical_leafname is the leafname to use for the numerical index of examples in the documentation. The default is examples_numerical.html.

examples_thematic_leafname is the leafname to use for the thematic index of examples in the documentation. The default is examples_thematic.html.

format is the most important of all the settings, and is HTML or text, but by default HTML unless the target name is plain, in which case text.

granularity is 1, 2, or 3. The default is 3 unless the target is called webpage or plain, in which case it is 1. This specifies how much the documentation is broken down into pieces. 1 means "each volume in a single HTML file"; 2 means "each chapter", 3 means "each section". Low granularity means fewer but larger files, high granularity more but smaller files.

html_for_Inform_application can be yes or no. The default is no. This specifies whether the HTML is for use inside the Inform UI application, and can therefore use links with the special HTTP transports only available there.

images_copy can be yes or no. The default is yes. In this mode, any needed image files are copied into place into the images_path. (The alternative assumes they are already there, and should be used if images_path is some URL external to the HTML being generated.)

images_path is where the generated HTML expects to find its image files. The default is ~~/Images/, where ~~ means the destination directory: that is, the default is a subdirectory called Images of the destination.

inform_definitions_mode can be yes or no. The default is no. This is cosmetic, and provides extra styling on lines of documentation giving the syntax for Inform phrases.

javascript can be yes or no. The default is yes. This indicates whether Indoc is allowed to compile Javascript, or has to stick to inactive HTML.

link_to_extensions_index is meaningful only if html_for_Inform_application is set, and specifies the URL of the Extensions index inside the app.

manifest_leafname is meaningful only if html_for_Inform_application is set, and is by default manifest.txt. This provides a cross-reference list of files generated by Indoc.

navigation is the design used for navigation links in the HTML produced. There are currently six designs, called architect, lacuna, midnight, roadsign, twilight, and unsigned; the default is roadsign, though inside the Inform applications, the design chosen is usually architect. If the format is text not HTML, then the design is always lacuna.

retina_images can be yes or no. The default is no. This indicates whether MacOS/iOS "retina" versions of the paste and create icons are available: paste@2x.png and create@2x.png respectively.

support_creation can be yes or no. The default is no. This indicates whether the Examples have a "create" button which creates a new Inform project demonstrating them in action; this can only be done in the UI apps, so it should always be no unless html_for_Inform_application is yes.

suppress_fonts can be yes or no. The default is no. If yes, this strips out lists of fonts to use in CSS, leaving only whether they are monospace or not.

toc_granularity is 1, 2, or 3. It can never be less than granularity, and by default is 3. It shows the level of detail in the table of contents: 1 means volumes, 2 means volumes and chapters, 3 goes down to sections.

top_and_tail specifies a prototype HTML file to follow for the more important HTML pages generated by Indoc. The default is not to. If this exists, it can provide a surround for the HTML we generate — for example, it can contain website-specific navigation, or a banner across the top. The prototype should somewhere include the text [TEXT], and this will be replaced with whatever Indoc generates.

top_and_tail_sections is the same as top_and_tail, but for individual section files.

treat_code_as_verbatim can be yes or no. The default is yes. This affects the styling of marked-up code material in documentation. Without it, code markup is largely unavailable.

wrapper can be EPUB, zip or none. The default is none. The wrapper is put around the whole mass of generated HTML; EPUB makes the result an Epub-format ebook.

XHTML can be yes or no. The default is no. This forces the HTML we produce to conform to XHTML 1.1 Strict. If the wrapper is EPUB, then this is automatically set to yes.