Option sets: a .o target for shared parameters
A named group of optional parameters, declared once and used by several
klammers, so a writer learns one vocabulary instead of a spelling per
klammer. The "o" target is a pseudo-target beside "k": "k" declares a
klammer's interface and documents it, "o" declares an option interface and
documents it, and neither produces output for any target.
@@caption_args.o :caption :number.bool true :caption_side.side
: Arguments that define a caption for a block element @@
@@code.k :filename @hpos_args :hpos left @ @caption_args :caption_side top @
| text.literal : A source file displayed verbatim @@
A set is used only in the parameter list of a ".k" declaration -- the one
place a klammer's interface is declared once for all of its targets -- and
is resolved as that list is read. Names and types come from the set; a
default may be overridden where it is used. A klammer application in a
parameter list is now a definition-time error.
The SKS gains the sets caption_args and hpos_args (:hpos and :offset), and
@table, @image, @image_grid, @reference and @show gain .k declarations. A
distance is no longer written as a position: :hpos 4em is rejected, and the
same layout is :hpos left :offset 4em. Code listings are numbered by
default, like tables and figures.
New engine sources mac/option_set{,_registry}.{h,cpp}; tst/ ships two more
suites, option_set_test.sh and signature_test.sh (twelve in all).
(from dev 34e536cb0329)
This commit is contained in:
@@ -1,22 +1,6 @@
|
||||
@@show s : @eval :cpp show show @ @@
|
||||
# General definitions for the Standard Klammer Set
|
||||
|
||||
@@@argtype caption_side |
|
||||
the side of its element on which a caption is placed
|
||||
:pattern top^|right^|bottom^|left
|
||||
:default bottom
|
||||
@@@
|
||||
|
||||
@@caption_arguments :
|
||||
:caption
|
||||
:number.bool true
|
||||
:caption_side.caption_side
|
||||
:caption_font.font i
|
||||
:caption_font_size.float .9
|
||||
@@
|
||||
|
||||
@@reference spec | name :
|
||||
__REF__*spec*__*name*__
|
||||
@@
|
||||
# Argtypes
|
||||
|
||||
@@@argtype number | a number
|
||||
:pattern 'float'^|'int'
|
||||
@@ -24,9 +8,9 @@
|
||||
@@@
|
||||
|
||||
@@@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
|
||||
#: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))
|
||||
@@@
|
||||
|
||||
@@ -35,16 +19,49 @@
|
||||
#:python_cast (lambda s : [__import__("kutil").parse_length("tex", e) for e in s.split()])
|
||||
@@@
|
||||
|
||||
@@@argtype element_hpos |
|
||||
the horizontal position of a block element (a table or an image) 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.
|
||||
:pattern center^|left^|right^|'length'
|
||||
@@@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.
|
||||
|
||||
@@ -89,8 +106,75 @@ An <id> is the value of the ^:id argument for an image.
|
||||
:pattern [a-z][a-z]
|
||||
@@@
|
||||
|
||||
# The document-wide language for generated text. A klammer's own :lang
|
||||
# argument overrides it; see the language argtype above. Consumers today:
|
||||
# @date and @datetime (month names and date form). Set it for a whole
|
||||
# document with @@@state Language :value de @@@
|
||||
@@@state Language :desc Language (ISO 639-1) for generated text :value en @@@
|
||||
|
||||
# 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 :: @eval :cpp show show @ @@
|
||||
|
||||
Reference in New Issue
Block a user