Andy Kopra
59c1599bc9
kdesc gains --coverage, which reports for every klammer the set of targets it can render to, and — the point of it — which klammers' coverage cannot be derived and must therefore be declared. Three rules: coverage is DERIVED where the definitions determine it (a general body of klammer calls covers the intersection of what those klammers cover, by a greatest fixpoint after loading), DECLARED where the engine cannot interpret what decides it (an @eval body, whose targets are undecidable), and UNKNOWN where nothing is written — which never means "deliberately unavailable". Two new spellings in a definition's name. A comma-separated target list, "@@table.html,tex :: ...", gives one body several targets; it is surface syntax, expanded at registration, and each member goes through the redefinition rules on its own. And "@@date.* :: ..." writes the general target out, asserting that the klammer works for EVERY target including ones not yet defined — a stronger claim than a list of the targets defined today, and the one target declaration that could be mechanically falsified. The Standard Klammer Set was swept accordingly: it now has no general definitions at all, every klammer names the targets it serves, six use ".*", and tex and pdf are at zero undecided. kdesc's flags are reorganised on two rules: a flag reached for often gets a single letter (-k klammers, -t targets, -c characters, -i input), a more specialised topic a multi-letter name (--argtypes, --katoms, --rewrite, --optionsets, --coverage, --klammerset, --font); and -v says how much to show about PROCESSING, never what the RESULT contains — so the katom regex column is "--katoms full" and the coverage detail "--coverage all". NOTE: "-k" now lists klammers (optionally filtered by a name/description search); the katom table moved to "--katoms". Fixes carried along: an option written with no value crashed the command with SIGSEGV instead of reporting the mistake; two required positional arguments never parsed; kdesc and kdiag printed an error and exited 0; and definition diagnostics counted registrations rather than what was written, so one line could be reported as two definitions and then printed twice. Four new test suites: target_list, coverage, command_option, kdesc. (from dev 46f54080bd9a)
179 lines
6.1 KiB
Plaintext
179 lines
6.1 KiB
Plaintext
# General definitions for the Standard Klammer Set
|
|
|
|
# Argtypes
|
|
|
|
@@@argtype number | a number
|
|
:pattern 'float'^|'int'
|
|
:python_cast (lambda s: float(s))
|
|
@@@
|
|
|
|
@@@argtype length | a length specifier
|
|
#:pattern f^|none^|'float'w^|'float'h^|'int'px^|'float'em^|'int'pt
|
|
# The last pattern is a string, used where possible to determine its length
|
|
:pattern f^|none^|'float'w^|'float'h^|'int'px^|'float'em^|'int'pt^|"[^^"]+"^|'float'pw^|'float'ph
|
|
# :python_cast (lambda s : __import__("kutil").parse_length("tex", s))
|
|
@@@
|
|
|
|
@@@argtype lengths | a list of lengths
|
|
:pattern ('length'^|\s+)*
|
|
#:python_cast (lambda s : [__import__("kutil").parse_length("tex", e) for e in s.split()])
|
|
@@@
|
|
|
|
@@@argtype side |
|
|
the side of its element on which a caption is placed: top, right, bottom, left
|
|
:pattern top^|right^|bottom^|left
|
|
:default bottom
|
|
@@@
|
|
|
|
@@@argtype hpos |
|
|
a horizontal position: left, center, right, none
|
|
:pattern left^|center^|right^|none
|
|
:default center
|
|
@@@
|
|
|
|
@@@argtype offset_length |
|
|
how far a block element is inset from the margin that ^:hpos names: from
|
|
the left margin for ^:hpos left, from the right margin for ^:hpos right.
|
|
An offset has no meaning for a centered element and is ignored there.
|
|
Written alone, ^:offset is the standard indentation (e.g. ^:hpos left
|
|
^:offset), and a value overrides it (^:hpos right ^:offset 4em).
|
|
# A single-purpose type, not a use of "length", because the two values
|
|
# below are what the writer relies on and only a type can carry them: an
|
|
# element is flush unless an offset is asked for (:default), and asking
|
|
# without saying how much is the standard indentation (:alone). A general
|
|
# length type must not declare :alone -- a bare option name has to read the
|
|
# same way wherever it appears, and "2em" is meaningless for :width.
|
|
:pattern 'length'
|
|
:default 0pt
|
|
:alone 2em
|
|
@@@
|
|
|
|
|
|
#[
|
|
@@@argtype element_hpos |
|
|
the horizontal position of a block element (a table, an image, a code
|
|
listing) within the text column: center, left, right, or a length, which
|
|
places the element's left edge that far from the left margin (e.g. ^:hpos
|
|
4em, ^:hpos .25w). When the element is as wide as the text column, the
|
|
positions are indistinguishable. The value none puts the element in no
|
|
positioning container at all, so that it flows with the text around it.
|
|
:pattern center^|left^|right^|none^|'length'
|
|
:default center
|
|
@@@
|
|
]#
|
|
|
|
@@@argtype figure_id |
|
|
an identifier for a figure.
|
|
|
|
The identifier can be in one of six forms:
|
|
|
|
before
|
|
before <offset-to-figure>
|
|
after
|
|
after <offset-to-figure>
|
|
<image-basename>
|
|
<id>
|
|
|
|
The "before" value means the figure before this place in the text;
|
|
the number indicates the number of figures behind that place in the
|
|
text. This means that "before" is equivalent to "before 1". The
|
|
"after" value uses an offset in the same way but counting forewards.
|
|
|
|
For images, the <image-basename> argument is the basename argument to
|
|
the ^@image klammer and can be used as an identifier.
|
|
|
|
An <id> is the value of the ^:id argument for an image.
|
|
|
|
^:pattern before(?^:\s+\d+)?^|after(?^:\s+\d+)?^|[-\w]+
|
|
@@@
|
|
|
|
@@@argtype filename_list |
|
|
one or more filenames. Filenames may contain spaces: a list is separated
|
|
by a standalone "/" (whitespace on both sides), e.g.
|
|
"chapter 1.kt / chapter 2.kt". Without the separator, the names are
|
|
separated by whitespace, and names that do not exist are rejoined with
|
|
their neighbors into names that do. A leading ~ expands to the home
|
|
directory.
|
|
:pattern [\s\S]*
|
|
:python_cast (lambda s: __import__("kutil").filename_list(s))
|
|
@@@
|
|
|
|
@@@argtype language |
|
|
an ISO 639-1 language code (two lowercase letters) selecting the language
|
|
of text a klammer generates, e.g. en (English) or de (German). The
|
|
languages actually available are listed by the klammer that uses the
|
|
argument (^@date and ^@datetime); an unknown code reports them.
|
|
:pattern [a-z][a-z]
|
|
@@@
|
|
|
|
|
|
# State variables
|
|
|
|
@@@state Language :desc Language (ISO 639-1) for generated text.
|
|
The document-wide language for generated text. A klammer's own ^:lang
|
|
argument overrides it; see the language argtype above. Currently used by
|
|
^@date and ^@datetime (month names and date form). Set it for a whole
|
|
document with ^@^@^@state Language ^:value de ^@^@^@
|
|
:value en
|
|
@@@
|
|
|
|
|
|
# Option sets
|
|
|
|
#[
|
|
The horizontal placement of a block element is two parameters: where it sits
|
|
(hpos_arg) and how far it is inset from that side (offset_arg). They are two
|
|
sets rather than one because a klammer may need the second without the first
|
|
-- and because a set is a vocabulary a reader learns whole, so a small one is
|
|
easier to learn than a large one.
|
|
|
|
An option set is a claim about behavior, not just a saving of keystrokes: a
|
|
klammer whose declaration uses these must also POSITION itself with them,
|
|
through latex_util.caption_wrapper (tex) and html_util.hpos_container
|
|
(html), or the parameter is accepted and silently ignored. Asserted by
|
|
outcome in sks/tst/placement_test.sh, so a new block klammer that takes the
|
|
parameters and ignores them is caught.
|
|
|
|
A klammer that wants a different DEFAULT position says so where it uses the
|
|
set (@hpos_arg :hpos left @ in the code klammer): a set owns the names and
|
|
the types, and the klammer owns what silence means for it.
|
|
]#
|
|
|
|
#[
|
|
@@offset_arg.o
|
|
:offset.offset_length
|
|
: How far a block element is inset from the margin its position names @@
|
|
|
|
@@hpos_arg.o
|
|
:hpos.element_hpos
|
|
: Where a block element sits in the text column @@
|
|
]#
|
|
|
|
@@hpos_args.o
|
|
:hpos.hpos
|
|
:offset.offset_length
|
|
:
|
|
The horizontal position of a block element. If the ^:hpos value is "none", no
|
|
outer structure is added to the element so that it can be used inline or in
|
|
other structures. The ^:offset is used only if the ^:hpos value is "left" or
|
|
"right".
|
|
@@
|
|
|
|
@@caption_args.o
|
|
:caption
|
|
:number.bool true
|
|
:caption_side.side
|
|
:caption_font.font i
|
|
:caption_font_size.float .9
|
|
: Arguments that define a caption for a block element.
|
|
@@
|
|
|
|
|
|
# Klammers
|
|
|
|
@@reference.k spec | name : Reference marker for captioned elements @@
|
|
@@reference.* :: __REF__*spec*__*name*__ @@
|
|
|
|
@@show.k s : Show the raw Klammertext and the result @@
|
|
@@show.html,tex,txt :: @eval :cpp show show @ @@
|