230 lines
9.4 KiB
OpenEdge ABL
230 lines
9.4 KiB
OpenEdge ABL
Advanced Weaving with Patterns.
|
|
|
|
Customise the booklets woven from a web.
|
|
|
|
@h Weave patterns.
|
|
As noted, the two most useful weave patterns are |-weave-as HTML| and
|
|
|-weave-as TeX|, and these are both supplied built in to Inweb. When you
|
|
weave something with |-weave-as P|, for some pattern name |P|, Inweb first
|
|
looks to see if the web in question defines a custom pattern of that name.
|
|
For example,
|
|
|
|
|$ inweb/Tangled/inweb inweb/Examples/goldbach -weave-as Tapestry|
|
|
|
|
would look for a directory called:
|
|
|
|
|inweb/Examples/goldbach/Patterns/Tapestry|
|
|
|
|
If that is found, Inweb expects it to define |Tapestry|. If not, Inweb next
|
|
tries:
|
|
|
|
|inweb/Patterns/Tapestry|
|
|
|
|
since |inweb/Patterns| is where the built-in patterns are kept. If it can't
|
|
find either, Inweb issues an error.
|
|
|
|
@ Patterns are a relatively new feature of Inweb, but allow for considerable
|
|
customisation of the woven output. In brief, a pattern directory is expected
|
|
to contain a configuration file called |pattern.txt|. This consists of a
|
|
series of simple one-line commands.
|
|
|
|
Most custom patterns open with the command:
|
|
|
|
|from Whatever|
|
|
|
|
which tells Inweb that this new pattern inherits from an existing one named
|
|
|Whatever|. (Do not get these into loops, with A inheriting from B and B
|
|
also inheriting from A.) The rule is then that if Inweb needs a file to do
|
|
with weaving, it looks first in the new custom pattern, and then, failing
|
|
that, in the pattern inherited from. As a result, the custom pattern need
|
|
only contain actual differences.
|
|
|
|
There should then always be a command reading:
|
|
|
|
|format = HTML|
|
|
|
|
or whatever other file format is required (for the TeX pattern, for example,
|
|
this reads |format = PDF|). A few other settings can also be made with |=|.
|
|
|
|
(a) |numbered = yes| causes the weaver to apply numbers to section headings:
|
|
the first included will be number 1, and so on. Default is |no|.
|
|
|
|
(b) |abbrevs = no| causes the weaver to suppress all mention of abbreviated
|
|
sections ranges, such as |2/tpc|, which aren't useful for documentation (for
|
|
example). Default is |yes|.
|
|
|
|
(c) |tex-command = C| tells the weaver that the TeX typesetting system should
|
|
be invoked with the shell command |C|. Default is |tex|.
|
|
|
|
(d) |pdftex-command = C| tells the weaver that the TeX typesetting system should
|
|
be invoked with the shell command |C| when what we want is a PDF, not a DVI
|
|
file. Default is |pdftex|.
|
|
|
|
(e) |open-command = C| tells the weaver to use the shell command |C| if it
|
|
wants to open the woven file (i.e., on the user's computer) after it finishes.
|
|
Default is |open|, which works nicely for MacOS.
|
|
|
|
(f) |default-range = R| tells the weaver to assume the range |R|, if the user
|
|
tries to weave a multi-section web with this pattern. (For example, the standard
|
|
HTML pattern sets |default-range = sections|.)
|
|
|
|
(g) The equals sign can also be used to override values of the bibliographic data
|
|
for the web. These changes are only temporary for the period in which the weave
|
|
is going on; they enable us to give custom titles to different weaves from the
|
|
same web. For example:
|
|
|
|
|Title = Grammar|
|
|
|Booklet Title = A formal grammar for Inform 7|
|
|
|Author = The Inform Project|
|
|
|
|
@ The command:
|
|
|
|
|use X|
|
|
|
|
tells Inweb that the file X, also stored in the pattern directory, should
|
|
be copied into any website being woven. For example, the HTML pattern says
|
|
|
|
|use crumbs.gif|
|
|
|
|
to instruct Inweb that an image used by the pages generated needs to be
|
|
copied over.
|
|
|
|
Finally, the command
|
|
|
|
|embed css|
|
|
|
|
tells Inweb that in any HTML file produced, the CSS necessary should be
|
|
embedded into the HTML, not linked as an external file. This is tidier for
|
|
patterns like TeX, where there will only be at most one HTML file produced,
|
|
and there's no need for an external CSS file.
|
|
|
|
@h Cover sheets.
|
|
If a weave has a range bigger than a single section -- for example, if it's
|
|
a weave of a chapter, or of the complete web -- then it will include a
|
|
"cover sheet". In the case of a PDF being made via TeX, this will actually
|
|
be an extra page at the front of the PDF; for HTML, of course, it will just
|
|
be additional material at the top of the web page.
|
|
|
|
The template for the cover sheet should be given in a file in the pattern
|
|
folder called |cover-sheet.tex|, |cover-sheet.html| or similar. Within it,
|
|
double-square brackets can be used to represent values from the bibliographic
|
|
data at the top of the web's Contents section. For example:
|
|
|
|
|\noindent{{\stitlefont [[Author]]}}|
|
|
|
|
In addition:
|
|
(a) |[[Cover Sheet]]| expands to the parent pattern's cover sheet -- this is
|
|
convenient if all you want to do is to add a note at the bottom of the
|
|
standard look.
|
|
(b) |[[Booklet Title]]| expands to text such as "Chapter 3", appropriate
|
|
to the weave being made.
|
|
(c) |[[Capitalized Title]]| is a form of the title in block capital letters.
|
|
|
|
@h Indexing.
|
|
Some weaves are accompanied by indexes. For example, a standard weave into
|
|
sections (for the HTML pattern) generates an |index.html| contents page,
|
|
linking to the weaves for the individual sections. How is this done?
|
|
|
|
Inweb looks in the pattern for a template file called either
|
|
|chaptered-index.html| or |unchaptered-index.html|, according to whether the
|
|
web's sections are in chapters or simply in a single directory of |Sections|.
|
|
If it doesn't find this, it looks for a template simply called |index.html|,
|
|
using that template in either case.
|
|
|
|
An index is then made by taking this template file and running it through
|
|
the "template interpreter". This is basically a filter: that is, it
|
|
works through one line at a time, and most of the time it simply copies
|
|
the input to the output. The filtering consists of making the following
|
|
replacements. Any text in the form |[[...]]| is substituted with the
|
|
value |...|, which can be any of:
|
|
|
|
(a) A bibliographic variable, set at the top of the |Contents.w| section.
|
|
|
|
(b) One of the following details about the entire-web PDF (see below):
|
|
|
|
|[[Complete Leafname]] [[Complete Extent]] [[Complete PDF Size]]|
|
|
|
|
(b) One of the following details about the "current chapter" (again, see below):
|
|
|
|
|[[Chapter Title]] [[Chapter Purpose]] [[Chapter Leafname]]|
|
|
|[[Chapter Extent]] [[Chapter PDF Size]] [[Chapter Errors]]|
|
|
|
|
(...) The leafname is that of the typeset PDF; the extent is a page count;
|
|
the errors result is a usually blank report.
|
|
|
|
(c) One of the following details about the "current section" (again, see below):
|
|
|
|
|[[Section Title]] [[Section Purpose]] [[Section Leafname]]|
|
|
|[[Section Extent]] [[Section PDF Size]] [[Section Errors]]|
|
|
|[[Section Lines]] [[Section Paragraphs]] [[Section Mean]]|
|
|
|[[Section Source]]|
|
|
|
|
(...) Lines and Paragraphs are counts of the number of each; the Source
|
|
substitution is the leafname of the original |.w| file. The Mean is the
|
|
average number of lines per paragraph: where this is large, the section
|
|
is rather raw and literate programming is not being used to the full.
|
|
|
|
@ But the template interpreter isn't merely "editing the stream", because
|
|
it can also handle repetitions. The following commands must occupy entire
|
|
lines:
|
|
|
|
|[[Repeat Chapter]]| and |[[Repeat Section]]| begin blocks of lines which
|
|
are repeated for each chapter or section: the material to be repeated
|
|
continues to the matching |[[End Repeat]| line. The ``current chapter or
|
|
section'' mentioned above is the one selected in the current innermost
|
|
loop of that description.
|
|
|
|
|[[Select ...]]| and |[[End Select]| form a block which behaves like
|
|
a repetition, but happens just once, for the named chapter or section.
|
|
|
|
For example, the following pattern:
|
|
|
|
|To take chapter 3 as an example, for instance, we find:|
|
|
|[[Select 3]]|
|
|
|[[Repeat Section]]|
|
|
| Section [[Section Title]]: [[Section Code]]: [[Section Lines]] lines.|
|
|
|[[End Repeat]]|
|
|
|[[End Select]]|
|
|
|
|
weaves a report somewhat like this:
|
|
|
|
|To take chapter 3 as an example, for instance, we find:|
|
|
| Section Lexer: 3/lex: 1011 lines.|
|
|
| Section Read Source Text: 3/read: 394 lines.|
|
|
| Section Lexical Writing Back: 3/lwb: 376 lines.|
|
|
| Section Lexical Services: 3/lexs: 606 lines.|
|
|
| Section Vocabulary: 3/vocab: 338 lines.|
|
|
| Section Built-In Words: 3/words: 1207 lines.|
|
|
|
|
@h Navigation and breadcrumbs.
|
|
When assembling large numbers of woven websites together, as is needed for
|
|
example by the main Inform repository's GitHub pages, we need to navigate
|
|
externally as well as internally: that is, the page for one tool will need
|
|
a way to link to pages for other tools.
|
|
|
|
To that end, the special expansion |[[Navigation]]| in a pattern template
|
|
will expand by looking for a file which contains a fragment of HTML, usually
|
|
consisting only of an un-numbered list of links.
|
|
|
|
By default, Inweb looks for a file called |nav.html| in two directories: the
|
|
one above the destination, and the destination. If both exist, they are both
|
|
used. If neither exists, the expansion is empty, but no error is produced.
|
|
|
|
However, this can be overridden at the command line, with |-navigation N|,
|
|
where |N| is the filename for a suitable fragment of navigation HTML.
|
|
|
|
@ The row of breadcrumbs at the top of a woven website can also be
|
|
customised from the command line, in that the prefatory breadcrumbs can
|
|
be explicitly chosen. (If they are not chosen, there's just a star, which
|
|
links to the relevant GitHub repository home page.) Any number can be
|
|
supplied. For example:
|
|
|
|
|-breadcrumb 'Groceries:groc.html' -breadcrumb Produce|
|
|
|
|
produces the trail
|
|
|
|
|Groceries > Produce > ...|
|
|
|
|
with the links being to |groc.html| and |Produce.html| respectively. (The
|
|
colon is optional, and needed only if the link is not to the text with |.html|
|
|
appended.)
|