klammertext/sks/kutil/kutil.k

# 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))
@@@

# Lengths on an axis (2026-09-16).  A width and a height are different
# types so that a value can only name a unit of its own axis: "w" and "pw"
# belong to widths, "h" and "ph" to heights, and a mistake is an argument
# error rather than a silent misreading.  A BARE NUMBER is the natural
# unit of the axis in every target -- characters for a width (a column in
# txt, "ch" in html, the width of a digit in tex), lines for a height (a
# newline in txt, "lh" in html, \baselineskip in tex) -- which is what lets
# a klammer written for the page keep its meaning in a terminal.  "length"
# stays for the quantities with no axis (a rule thickness).
@@@argtype width |
  a horizontal length.  A bare number is that many characters (one column
  of plain text; in a proportional typeface, the width of a digit, so an
  indent or a column lines up across lines even where the letters do not).
  Otherwise a number with a unit: ^:width 2em, 12pt, 100px, .5w (that
  fraction of the text width), .5pw (of the page width); f or none for an
  element's natural width; a quoted string, whose set width is used where
  the target can measure it.
  :pattern 'float'^|'float'em^|'int'pt^|'int'px^|'float'w^|'float'pw^|f^|none^|"[^^"]+"
@@@

@@@argtype height |
  a vertical length.  A bare number is that many lines (blank lines in
  plain text; the line height of the surrounding text otherwise).
  Otherwise a number with a unit: ^:height 2em, 12pt, 100px, .5h (that
  fraction of the text height), .5ph (of the page height).
  :pattern 'float'^|'float'em^|'int'pt^|'int'px^|'float'h^|'float'ph
@@@

@@@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 "width", 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
  # width type must not declare :alone -- a bare option name has to read the
  # same way wherever it appears, and "4" is meaningless for :width.
  # Both values are BARE numbers -- characters -- so that they mean the same
  # thing under txt as on the page (2026-09-16): four characters is about
  # the 2em the alone value used to be, and 0 is flush everywhere.
  :pattern 'width'
  :default 0
  :alone 4
@@@


#[
@@@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_style.style_code i
  :caption_size.float 1
: 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 @ @@