2026-07-18 18:48:23 +02:00
|
|
|
|
2026-08-16 16:58:50 +02:00
|
|
|
@@code.k
|
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)
2026-08-06 13:11:37 +02:00
|
|
|
@hpos_args :hpos left @
|
|
|
|
|
@caption_args :caption_side top @
|
|
|
|
|
| text.literal :
|
2026-08-16 16:58:50 +02:00
|
|
|
A block of code, given here and displayed uninterpreted. Code that lives in a
|
|
|
|
|
file is ^@source_listing instead; ^@code is only for a block written inline.
|
|
|
|
|
|
|
|
|
|
It carried ":filename" and ":pattern" until 2026-08-16. Neither was ever
|
|
|
|
|
implemented -- "filename" is read only by ^@source_listing and "pattern" by
|
|
|
|
|
nothing at all -- and because a literal parameter's content begins at the first
|
|
|
|
|
katom when no bar is written, "^@code :filename f :pattern p" DISPLAYED THOSE
|
|
|
|
|
WORDS as the listing rather than acting on them.
|
2026-07-18 18:48:23 +02:00
|
|
|
@@
|
|
|
|
|
|
Target coverage: a klammer states the targets it serves
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)
2026-08-12 17:20:23 +02:00
|
|
|
@@code.html,tex :: @eval code_block.Code(K) @ @@
|
2026-07-18 18:48:23 +02:00
|
|
|
|
2026-08-16 16:58:50 +02:00
|
|
|
@@c.k code_text.literal :
|
|
|
|
|
A word or phrase displayed verbatim in a line. Like ^@code, its content is
|
|
|
|
|
LITERAL -- nothing in it is interpreted as Klammertext -- so it must be closed
|
|
|
|
|
with the named delimiter "c^@". ^@c is the in-line form and ^@code the block
|
|
|
|
|
form of the same thing; before 2026-08-16 this parameter was an ordinary
|
|
|
|
|
string, so a "^#" or a bare "^@" inside it was read as Klammertext and usually
|
|
|
|
|
failed the file, which is not what "verbatim" can mean.
|
2026-07-18 18:48:23 +02:00
|
|
|
@@
|
|
|
|
|
|
Target coverage: a klammer states the targets it serves
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)
2026-08-12 17:20:23 +02:00
|
|
|
@@c.html,tex :: @eval code_block.Code_fragment(K) eval@
|
2026-07-18 18:48:23 +02:00
|
|
|
@@
|
|
|
|
|
|
2026-07-27 20:25:49 +02:00
|
|
|
# :cwd makes the filename resolve against the DOCUMENT's directory, not
|
|
|
|
|
# the directory ktext happens to run in.
|
2026-08-16 16:58:50 +02:00
|
|
|
@@source_listing.k filename :marker
|
|
|
|
|
@hpos_args :hpos left @
|
|
|
|
|
@caption_args :caption_side top @
|
|
|
|
|
: Code read from a file and displayed uninterpreted. *filename* is the file;
|
|
|
|
|
without ":marker" the whole file is listed.
|
|
|
|
|
|
|
|
|
|
":marker P" lists only the region BETWEEN two lines that consist solely of
|
|
|
|
|
"//P" and begin in the first column. The source file therefore declares its
|
|
|
|
|
own extractable regions and the document asks for one by name, so the two
|
|
|
|
|
cannot drift apart silently: renaming or reformatting the code does not change
|
|
|
|
|
what is extracted, and a region that disappears is an error rather than a
|
|
|
|
|
quietly different listing.
|
|
|
|
|
|
|
|
|
|
Named "^@source_file" until 2026-08-16. # retired-ok
|
|
|
|
|
@@
|
|
|
|
|
@@source_listing.html,tex :: @eval :cwd *K_input_dir* code_block.Source(K) @ @@
|