inform7/indoc/Manual/Volumes and Instructions.w

Volumes and Instructions.

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

@h 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
= (text)
	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:
= (text)
	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".

@h Project instructions.
The main instructions file for an Indoc project is, as noted earlier, at:
= (text)
	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:
= (text)
	volume: Writing with Inform
	volume: The Inform Recipe Book (RB) = The Recipe Book.txt
	examples
=
But a simpler, single-volume project might have just:
= (text)
	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:
= (text)
	cover: combined_cover.png
=
This specifies a leafname which must exist in one of the image sources
mentioned above.

@h 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:
= (text)
	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.

@h 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:
= (text)
	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:
= (text)
	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|.

@h 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:
= (text)
	linux_app {
		...
		declare: Linux
		...
	}
=
In the documentation, we could then mark up a paragraph like so:
= (text as Indoc)
	{Linux:}To install, first...
=
The symbol |indoc| is always declared, but by default no other symbols are.
Lastly, |undeclare: SYMBOL| removes a symbol.

@h 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,
= (text)
	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,
= (text)
	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.

@h 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
= (text)
	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|.