klammertext/sks/target/target.k

#[
The targets in the SKS use the LaTeX convention for converting ASCII
characters into standard typographical characters.  This is done
by LaTeX by default; other targets must use the transforms parameter
of Parameter_set, as defined for the m_parameters variable of the
Target_registry class.  (See file target_registry.cpp.)

The LaTeX transformations supported by the SKS are:

  --   ->  en-dash
  ---  ->  em-dash
  `    ->  open single quote
  '    ->  close single quote
  ``   ->  open double quote
  ''   ->  close double quote
  ~    ->  non-breaking space

"^" before any punctuation character quotes it (an engine rule, not an SKS
one): the character reaches the output literally, taking no part in the
transforms above -- ^-^- writes two plain hyphens (a --flag in prose), ^~ a
plain tilde.  The one exception is the apostrophe: "^" before it opens a
literal span instead (a literal apostrophe is ^0027^), and writing that
pair even in THIS comment would open one -- the span sentinels are placed
before text removal.  A target where the raw character would
still be re-interpreted declares its rendering with :resolve -- the tex
target maps a quoted hyphen to {-} (a bare -- in .tex re-forms TeX's dash
ligature) and a quoted tilde to \textasciitilde{} (a raw ~ is TeX's
non-breaking space).  Verbatim text (@c, @code, ^'...'^) never needs any
of this: neither the transforms nor the quoting reach it.

]#


@@@state Target_txt_width
  :desc Width of the text in the plain text target (txt)
  :value 72
@@@

@@@state Target_txt_indent
  :desc Width of indentation in the plain text target (txt)
  :value 2
@@@

# The txt target is not fully implemented in the SKS yet.
#
# A writer's "~" is a non-breaking space (the LaTeX convention), and it
# becomes the nbsp MARKER here rather than a space directly, for two
# reasons.  A transform whose replacement is whitespace is silently
# DISCARDED -- parse_transforms takes the pair with word_split, and a
# space is not a word -- so "~ ^0020^" never did anything, and the
# substitution that made a tilde look like a space lived in the
# justification phase and caught EVERY tilde, so a literal one could not
# be written at all.  The marker survives to the phase and becomes a space
# there; a quoted "^~" is a KTESC marker by then, so it is not matched
# here and reaches the reader as a tilde.
# SYNC: phases.txt_nbsp_marker() in sks/target/phases.py.
@@@target txt | Plain text with formatting |  
  --  -  |
  --- -- |
  ``  "  |
  ''  "  |
  `   '  |
  '   '  |
  ~   __KTEXTNBSP__
  :after_apply
    phases.txt_insert_section_numbers ;
    phases.txt_format_footnotes ;
    phases.txt_insert_captions ;
    phases.txt_justify_blocks ;
    phases.txt_strip_styles
@@@

# Plain text for a TERMINAL: the txt target's output with the type styles
# a terminal can show (@b, @i, @u) as SGR escape sequences.  Named for its
# FORMAT, not its destination -- a file of it is what "less -R" shows, and
# "ktext -t txt -d | less" is a stream that must stay plain -- so the
# writer picks it with -t, as they pick pdf over tex; kdesc picks it for
# its own output when stdout is a terminal.  It includes txt and defines no
# klammers: @b.txt and its siblings emit style markers, which the txt
# target's last phase strips and this target's last phase resolves.  So
# the two renders are equal once the escape sequences are removed
# (sks/tst/ansi_test.sh), and only the last phase differs.  Phases are
# not inherited through :includes (see pdf), hence the restated list.
@@@target ansi | Plain text with ANSI escape sequences for type styles
  :includes txt
  :after_apply
    phases.txt_insert_section_numbers ;
    phases.txt_format_footnotes ;
    phases.txt_insert_captions ;
    phases.txt_justify_blocks ;
    phases.ansi_resolve_styles
@@@

@@@target html | HTML page
#  :escape < &lt; & &amp; |
|
  --- &^#x2014; |
  -- &^#x2013;  |
  `` “        |
  '' ”        |
  ` ‘         |
  ' ’         |
  ~ &^#160;
  :after_apply
    phases.html_format_footnotes ;
    phases.check_section_links
@@@

# No transforms: LaTeX applies the input conventions itself.  The :resolve
# entries say how a QUOTED character renders where the raw character would
# still be re-interpreted by TeX: ^- resolves to {-}, not a bare -, or the
# hyphens re-form a run and the dash ligature turns ^-^- into an en-dash;
# ^~ resolves to \textasciitilde{}, since a raw ~ is TeX's non-breaking
# space.  Other quoted punctuation either has an :escape entry (its marker
# takes the escape replacement: ^$ renders as \$) or decodes to the raw
# character.
@@@target tex | LaTeX
  :escape \ \textbackslash{} & \& { \{ } \} $ \$ % \% _ \_ ^# \^# ^^ \textasciicircum{}
  :resolve - {-} ~ \textasciitilde{}
  :after_apply phases.tex_resolve_markers ; phases.check_section_links
@@@

@@@target pdf | PDF from LaTeX
  :includes tex
  # Phases are NOT inherited through :includes -- escapes, transforms and
  # resolves are (target_registry.cpp) -- and tex_to_pdf compiles the
  # document, so the marker resolution is named here too, and first.
  :after_apply
     phases.tex_resolve_markers ;
     ^:cpp *KLAMMERTEXT_HOME*/sks/document/document tex_to_pdf
@@@