Images in plain text and the terminal; bounded build parallelism (from dev 16f82cc887af)

- @image under txt and ansi is a picture in characters, in five styles
  (Image_txt_style: halfblock the default, shade, ascii, quadrant,
  braille), sized to the terminal's width less a margin when ktext runs
  in one, every cell in its own colours under ansi; a figure's caption
  is centred under it and no txt caption is ruled off any more.
- The build compiles as many files at once as the machine has cores
  (JOBS; make -C com JOBS=1 for a small machine): the sub-makes' bare -j
  meant unlimited parallelism and exhausted 8 GB machines. The three
  install pages say "make -C com".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

sks/Makefile

@@ -35,15 +35,15 @@ all : support $(SO_DIRS)
 support : $(SUPPORT_DIRS)
 
 kutil :
-	$(MAKE) -j -C $(KS)/kutil
+	$(MAKE) -j$(JOBS) -C $(KS)/kutil
 
 target : kutil
-	$(MAKE) -j -C $(KS)/target
+	$(MAKE) -j$(JOBS) -C $(KS)/target
 
 # Pattern rule for the DSO directories
 # Each depends on the library and support directories
 $(SO_DIRS) : support $(LIBRARY)
-	$(MAKE) -j -C $(KS)/$@
+	$(MAKE) -j$(JOBS) -C $(KS)/$@
 
 # Clean all subdirectories
 clean :

sks/code/code_block.py

@@ -379,12 +379,10 @@ class Code(klammer_base.Klammer_base):
         width = max(len(line.rstrip()) for line in lines)
         rule = indent + klammer_base.hide_typographic("-" * width)
         body = [indent + prepared(line) for line in lines]
-        # A caption above the listing is ruled off by the caption pass, so
-        # the listing draws its own top rule only when nothing does.
-        captioned = self.number or self.caption
-        caption_above = captioned and self.caption_side in ("top", "left")
-        if not caption_above:
-            body.insert(0, rule)
+        # The listing's frame is its own: a rule above and below, whether
+        # or not a caption stands over it (the caption pass draws no rule,
+        # 2026-09-28 -- no target rules a caption off).
+        body.insert(0, rule)
         body.append(rule)
         result = phases.txt_lay_out("\n".join(body))
         return txt_util.add_caption(

sks/image/image.k

@@ -9,6 +9,22 @@
 @@@
 
 @@@state Image_output_dir :desc Output directory for images :value img @@@
+@@@state Image_txt_style
+         :desc How an image is drawn in characters under txt and ansi:
+               halfblock (two pixels per cell in full colour under ansi -- the
+               nearest to the raster, and the default; under txt a solid
+               block, since its picture is only its colours), shade (block
+               shades, coloured tiles under ansi), ascii (a density ramp of
+               typewriter characters), quadrant (four sub-pixels per cell, two
+               colours per cell under ansi), braille (eight dots per cell).
+         :value halfblock
+@@@
+@@@state Image_txt_dark_background
+         :desc Under txt and ansi, the density ramp assumes a dark terminal
+               background (true): bright pixels are the dense characters.
+               false reverses it for a light background.
+         :value true
+@@@
 
 @@@state Image_default_width :desc Default width for images :value .667w @@@
 
@@ -45,10 +61,18 @@
 An image read from a file.  The basename names the file, which is looked
 for in the image search path and converted to a format the target can use.
 ^:width is the image's width in the text column, ^:hpos and ^:offset place
-it there, and the caption arguments caption it.
+it there, and the caption arguments caption it.  Under txt and ansi the
+image is drawn in characters (the Image_txt_style state variable:
+halfblock, the default, or shade, ascii, quadrant, braille), and ansi
+colours them; the
+measure is the terminal's width
+less a small margin when ktext runs in one, else the text width, and
+^:width applies to that (a fraction, a number of columns, or f for all of
+it).  The Image_txt_dark_background state variable (true) reverses the
+ramp for a light terminal.
 @@
 
-@@image.html,tex :: @eval image.Image(K) eval@ @@
+@@image.html,tex,txt :: @eval image.Image(K) eval@ @@
 
 @@image_grid.k
   image_specs.rest(2)

sks/image/image.py

@@ -9,6 +9,8 @@ import shutil
 import kutil
 import html_util
 import latex_util
+import txt_util
+import phases
 import klammer_base
 import image_cache
 import pprint
@@ -29,16 +31,241 @@ class Image(klammer_base.Klammer_base):
         self.cache = image_cache.Image_cache(cache_dir, self.Image_search_path, verbose=False,
                                              quality=self.Image_quality)
         self.basename = klammer_base.unescape_ktesc(self.basename)
-        self.source, self.pwidth, self.pheight = self.cache.get(self.K_target, self.basename)
+        # Plain text renders the image as characters (txt() below) and reads
+        # its pixels from the raster the html target would use.
+        self.cache_target = "html" if self.K_target in ("txt", "ansi") else self.K_target
+        self.source, self.pwidth, self.pheight = self.cache.get(self.cache_target, self.basename)
         self.as_string = as_string
         if width:
             self.width = width
         self.rel_image = None
         self.rel_fraction = 1.0
         if self.rel:
-            self.rel_image, self.rel_pwidth, self.rel_pheight = self.cache.get(self.K_target, self.rel)
+            self.rel_image, self.rel_pwidth, self.rel_pheight = self.cache.get(self.cache_target, self.rel)
             self.rel_fraction = self.pwidth / self.rel_pwidth
 
+    # ---- plain text and the terminal (txt, ansi) -----------------------
+    # The picture is characters.  Five styles (Image_txt_style, Andy
+    # 2026-09-28, halfblock the default; notes/ansi_images.md): in four of them each cell's
+    # character carries LUMINANCE -- a ramp (shade, ascii) or a shape of set
+    # sub-pixels (quadrant, braille) -- and under ansi colour markers carry
+    # the hue, so the txt render is a monochrome picture on its own and
+    # stripping the escapes from the ansi render gives it byte for byte (the
+    # ansi invariant, sks/tst/ansi_test.sh).  The fifth, halfblock, is the
+    # nearest to the raster (two pixels per cell in full colour) at the price
+    # the invariant makes explicit: its txt twin is a solid block.
+    TXT_STYLES = ("halfblock", "shade", "ascii", "quadrant", "braille")
+    TXT_RAMPS = {"ascii": " .:-=+*#%@",        # dark to bright, for a dark background
+                 "shade": " ░▒▓█"}
+    # Quadrant characters by the bit mask of set quarters: 8 = top left,
+    # 4 = top right, 2 = bottom left, 1 = bottom right.
+    TXT_QUADRANTS = " ▗▖▄▝▐▞▟▘▚▌▙▀▜▛█"
+    TXT_MARGIN = 4               # columns kept free at the terminal's right edge
+    TXT_CELL_ASPECT = 0.5        # a terminal cell is about twice as tall as wide
+
+    @staticmethod
+    def terminal_columns():
+        """The width of the terminal ktext runs in, or None when it runs
+        under a pipe or a redirect on every descriptor (a file beside the
+        input is written from a terminal too, so stdout being a file is not
+        the end of it: stderr and stdin are tried as well)."""
+        for fd in (1, 2, 0):
+            try:
+                if os.isatty(fd):
+                    columns = os.get_terminal_size(fd).columns
+                    if columns > 0:
+                        return columns
+            except OSError:
+                pass
+        return None
+
+    def txt_indent(self):
+        # @code's rule: a left- or right-placed block is inset by :offset,
+        # "none" flows flush, and "center" keeps the block convention.
+        if self.hpos in ("left", "right"):
+            return int(kutil.parse_width("txt", self.offset)[0])
+        if self.hpos == "none":
+            return 0
+        return int(self.Target_txt_indent)
+
+    def txt_columns(self, indent):
+        """How many character columns the picture gets: the terminal's
+        width less a margin when there is one (Andy: use the window), else
+        Target_txt_width, less the indent either way; and :width applies to
+        that measure as it does to the text width elsewhere -- a fraction
+        (.5w, the declared default), a bare number of columns, or f/none
+        for the whole measure."""
+        columns = Image.terminal_columns()
+        measure = (columns - Image.TXT_MARGIN) if columns else int(self.Target_txt_width)
+        measure = max(8, measure - indent)
+        w = str(self.width).strip()
+        if w in ("f", "none", ""):
+            return measure
+        m = re.match(r"^([0-9.]+)([a-z]*)$", w)
+        if not m:
+            return measure
+        number, unit = float(m.group(1)), m.group(2)
+        if unit in ("w", "pw"):
+            return max(4, min(measure, int(round(number * measure))))
+        if unit == "":
+            return max(4, min(measure, int(round(number))))
+        # Any other unit (px, cm, in, pt, em) has no meaning in plain text:
+        # the length parser says so, with the remedy, rather than this
+        # silently taking the whole measure (which is what it did for a day).
+        kutil.parse_width("txt", w)
+        return measure
+
+    def txt_samples(self, width, height):
+        """The image resampled to width x height: rows of (luminance, rgb)
+        with luminance 0..1 and rgb 8-bit.  The pixels come from the SOURCE
+        when it is a raster: the cache's copy of a photograph is a JPEG at
+        Image_quality, whose shifted colours and edge ringing are invisible
+        on a page and plain to see in eighty characters.  A PDF source has
+        to go through the cache's rasterising."""
+        import OpenImageIO as oiio
+        source = self.cache.find_file(self.cache_target, self.basename) or self.source
+        if os.path.splitext(source)[1][1:].lower() in ("pdf", "eps"):
+            source = self.source
+        src = oiio.ImageBuf(source)
+        roi = oiio.ROI(0, width, 0, height, 0, 1, 0, src.nchannels)
+        small = oiio.ImageBufAlgo.resize(src, roi=roi)
+        rows = []
+        for y in range(height):
+            row = []
+            for x in range(width):
+                p = small.getpixel(x, y)
+                r, g, b = (p[0], p[1], p[2]) if len(p) >= 3 else (p[0], p[0], p[0])
+                lum = min(1.0, max(0.0, 0.2126 * r + 0.7152 * g + 0.0722 * b))
+                rgb = tuple(min(255, int(c * 255 + 0.5)) for c in (r, g, b))
+                row.append((lum, rgb))
+            rows.append(row)
+        return rows
+
+    @staticmethod
+    def txt_dither(samples, dark_background):
+        """Floyd-Steinberg error diffusion of the luminance to one bit: True
+        where a dot or a quarter is SET, which on a dark background is the
+        bright side and on a light one the dark side."""
+        h = len(samples); w = len(samples[0]) if h else 0
+        lum = [[s[0] if dark_background else 1.0 - s[0] for s in row] for row in samples]
+        bits = [[False] * w for _ in range(h)]
+        for y in range(h):
+            for x in range(w):
+                old = lum[y][x]
+                new = 1.0 if old >= 0.5 else 0.0
+                bits[y][x] = new == 1.0
+                err = old - new
+                if x + 1 < w:
+                    lum[y][x + 1] += err * 7 / 16
+                if y + 1 < h:
+                    if x > 0:
+                        lum[y + 1][x - 1] += err * 3 / 16
+                    lum[y + 1][x] += err * 5 / 16
+                    if x + 1 < w:
+                        lum[y + 1][x + 1] += err * 1 / 16
+        return bits
+
+    @staticmethod
+    def txt_toned(rgb, dark):
+        """The pixel's colour halfway toward the paper -- black on a dark
+        setting, white on a light one -- for the BACKGROUND of a ramp cell:
+        every cell sets both grounds explicitly (Andy, 2026-09-28: a black
+        pixel must be black on a white terminal too, not the terminal
+        showing through a space), and the character keeps its density on a
+        tile of the pixel's own hue."""
+        paper = 0 if dark else 255
+        return tuple(int((c + paper) / 2 + 0.5) for c in rgb)
+
+    @staticmethod
+    def txt_mean(colors):
+        if not colors:
+            return None
+        n = len(colors)
+        return tuple(int(sum(c[i] for c in colors) / n + 0.5) for i in range(3))
+
+    def txt_cells(self, style, cols, rows, dark):
+        """Rows of cells (character, fg rgb or None, bg rgb or None)."""
+        cells = []
+        if style in ("ascii", "shade"):
+            ramp = Image.TXT_RAMPS[style]
+            if not dark:
+                ramp = ramp[::-1]
+            for row in self.txt_samples(cols, rows):
+                cells.append([(ramp[min(len(ramp) - 1, int(lum * len(ramp)))], rgb, Image.txt_toned(rgb, dark)) for lum, rgb in row])
+        elif style == "halfblock":
+            samples = self.txt_samples(cols, rows * 2)
+            for y in range(rows):
+                cells.append([("▀", samples[2 * y][x][1], samples[2 * y + 1][x][1]) for x in range(cols)])
+        elif style == "quadrant":
+            samples = self.txt_samples(cols * 2, rows * 2)
+            bits = Image.txt_dither(samples, dark)
+            for y in range(rows):
+                row = []
+                for x in range(cols):
+                    quads = [(2 * y, 2 * x, 8), (2 * y, 2 * x + 1, 4), (2 * y + 1, 2 * x, 2), (2 * y + 1, 2 * x + 1, 1)]
+                    mask = sum(b for yy, xx, b in quads if bits[yy][xx])
+                    on = [samples[yy][xx][1] for yy, xx, b in quads if bits[yy][xx]]
+                    off = [samples[yy][xx][1] for yy, xx, b in quads if not bits[yy][xx]]
+                    fg = Image.txt_mean(on) or Image.txt_mean(off)
+                    bg = Image.txt_mean(off) or Image.txt_mean(on)
+                    row.append((Image.TXT_QUADRANTS[mask], fg, bg))
+                cells.append(row)
+        elif style == "braille":
+            samples = self.txt_samples(cols * 2, rows * 4)
+            bits = Image.txt_dither(samples, dark)
+            dots = ((0, 0, 1), (0, 1, 2), (0, 2, 4), (1, 0, 8), (1, 1, 16), (1, 2, 32), (0, 3, 64), (1, 3, 128))
+            for y in range(rows):
+                row = []
+                for x in range(cols):
+                    mask = sum(b for dx, dy, b in dots if bits[4 * y + dy][2 * x + dx])
+                    on = [samples[4 * y + dy][2 * x + dx][1] for dx, dy, b in dots if bits[4 * y + dy][2 * x + dx]]
+                    off = [samples[4 * y + dy][2 * x + dx][1] for dx, dy, b in dots if not bits[4 * y + dy][2 * x + dx]]
+                    # Both grounds explicit: the set dots in their colour, the
+                    # unset ones in theirs (as quadrant does with its quarters).
+                    fg = Image.txt_mean(on) or Image.txt_mean(off)
+                    bg = Image.txt_mean(off) or Image.txt_mean(on)
+                    row.append((chr(0x2800 + mask), fg, bg))
+                cells.append(row)
+        return cells
+
+    def txt(self):
+        from code_block import quote_specials
+        style = str(getattr(self, "Image_txt_style", "halfblock")).strip().lower()
+        if style not in Image.TXT_STYLES:
+            raise Exception(f'Image_txt_style "{style}" is not one of {", ".join(Image.TXT_STYLES)}')
+        dark = str(getattr(self, "Image_txt_dark_background", "true")).strip().lower() in ("true", "1", "yes")
+        indent = self.txt_indent()
+        cols = self.txt_columns(indent)
+        rows = max(1, int(round(self.pheight / self.pwidth * cols * Image.TXT_CELL_ASPECT)))
+        nbsp = txt_util.NBSP
+        lead = nbsp * indent
+        lines = []
+        for cell_row in self.txt_cells(style, cols, rows, dark):
+            # The characters are prepared as @code prepares a line -- the
+            # Klammertext specials quoted (this result is re-read), the
+            # typographic ones hidden ("--" stays two hyphens), spaces as the
+            # nbsp marker -- BEFORE the colour markers go in, which hold
+            # nothing either step would touch.  A marker is written only where
+            # the colour changes, and both grounds are restored at the end.
+            out = []
+            fg_now = bg_now = None
+            for ch, fg, bg in cell_row:
+                if fg != fg_now:
+                    out.append(phases.txt_color_marker(fg))
+                    fg_now = fg
+                if bg != bg_now:
+                    out.append(phases.txt_color_marker(bg, background=True))
+                    bg_now = bg
+                out.append(klammer_base.hide_typographic(quote_specials(ch)).replace(" ", nbsp))
+            if fg_now is not None:
+                out.append(phases.txt_color_marker(None))
+            if bg_now is not None:
+                out.append(phases.txt_color_marker(None, background=True))
+            lines.append(lead + "".join(out))
+        result = phases.txt_lay_out("\n".join(lines))
+        return txt_util.add_caption(result, "Figure", self.number, self.caption,
+                                    self.caption_side or "bottom", indent, centered=True)
+
     def html(self):
         img_dir = f"{self.K_output_dir}/{self.K_output_basename}/{self.Image_output_dir}"
 

sks/target/phases.py

@@ -75,20 +75,43 @@ _STYLE_MARKER_RGX = re.compile(
     "|".join(re.escape(txt_style_marker(s, on))
              for s in TXT_STYLES for on in (True, False)))
 
+# A COLOUR marker carries its colour: __KTEXTFG<rrggbb>__ opens a foreground
+# colour, __KTEXTFGOFF__ restores the default (SGR 39, never a blanket reset).
+# Used by @image under txt/ansi (2026-09-27, Andy's terminal images): the
+# character carries the luminance and the colour the hue, so stripping the
+# escapes still leaves a monochrome picture -- the invariant kept.
+def txt_color_marker(rgb=None, background=False):
+    """A foreground colour marker, or with background=True a background one
+    (__KTEXTBG<rrggbb>__ / __KTEXTBGOFF__, SGR 48;2 and 49): the quadrant
+    and halfblock image styles set two colours per cell."""
+    ground = "BG" if background else "FG"
+    if rgb is None:
+        return f"__KTEXT{ground}OFF__"
+    r, g, b = rgb
+    return f"__KTEXT{ground}{int(r):02X}{int(g):02X}{int(b):02X}__"
+
+_COLOR_MARKER_RGX = re.compile(r"__KTEXT(FG|BG)(?:([0-9A-F]{6})|OFF)__")
+
 def txt_strip_styles(text, K):
-    return _STYLE_MARKER_RGX.sub("", text)
+    return _COLOR_MARKER_RGX.sub("", _STYLE_MARKER_RGX.sub("", text))
 
 def ansi_resolve_styles(text, K):
     for style, (on, off) in TXT_STYLES.items():
         text = text.replace(txt_style_marker(style), on)
         text = text.replace(txt_style_marker(style, False), off)
-    return text
+    def color(m):
+        ground, hex6 = m.group(1), m.group(2)
+        code = 38 if ground == "FG" else 48
+        if hex6 is None:
+            return f"\033[{code + 1}m"       # 39 / 49: the default fore-/background
+        return f"\033[{code};2;{int(hex6[0:2], 16)};{int(hex6[2:4], 16)};{int(hex6[4:6], 16)}m"
+    return _COLOR_MARKER_RGX.sub(color, text)
 
 def txt_visible_length(s):
     """How many columns s occupies once its markers resolve: a KTESC
     marker is one glyph, an nbsp marker one space, a style marker nothing.
     len() is the wrong measure for anything laid out (see txt_util)."""
-    s = _STYLE_MARKER_RGX.sub("", s).replace(txt_verbatim_marker(), "")
+    s = _COLOR_MARKER_RGX.sub("", _STYLE_MARKER_RGX.sub("", s)).replace(txt_verbatim_marker(), "")
     return len(klammer_base.unescape_ktesc(s).replace(txt_nbsp_marker(), " "))
 
 def txt_wrap(text, width, subsequent_indent=""):
@@ -257,6 +280,10 @@ def txt_insert_captions(text, K):
         return widest
     def replace(m):
         indent_run, name, text = m.groups()
+        # The name may carry flags after "+": "center" sets the caption
+        # centred on its block (a figure's, as in html and tex).
+        name, _, flags = name.partition("+")
+        centered = "center" in flags.split("+")
         indent = len(indent_run) // len(nbsp)
         indented_width = max(1, width - indent)
         # The block the caption belongs to: below a top caption, above a
@@ -278,12 +305,16 @@ def txt_insert_captions(text, K):
         else:
             caption = text
         # Visible widths throughout: a caption may carry style markers.
+        # NO RULE under (or over) a caption: none of the targets draws one
+        # (Andy, 2026-09-28 -- the rule this pass drew since 2026-08 was a
+        # txt invention; a table's rules are its own :hline, a listing's its
+        # own frame).  A centred caption is set on the block's width.
         lines = [caption]
         if txt_visible_length(caption) > indented_width:
             lines = txt_wrap(caption, indented_width)
-        line_length = max(txt_visible_length(e) for e in lines)
-        line_length = max(line_length, block - indent)
-        lines.append("-" * line_length)
+        if centered:
+            measure = max(block - indent, max(txt_visible_length(e) for e in lines))
+            lines = [" " * max(0, (measure - txt_visible_length(e)) // 2) + e for e in lines]
         lead = txt_verbatim_marker() + indent_run
         # The first line's marker is already in the text, before the indent
         # run this match begins with (add_caption); the others get theirs.

sks/target/txt_util.py

@@ -58,7 +58,7 @@ def block_width(text_width, indent):
     return max(1, int(text_width) - indent)
 
 def add_caption(element, caption_label, number, caption_text,
-                side="top", indent=0):
+                side="top", indent=0, centered=False):
     """Attach a caption to an already-laid-out block.
 
     `element` is the block's text, indented by `indent` columns of NBSP.
@@ -95,10 +95,14 @@ def add_caption(element, caption_label, number, caption_text,
     # marker substitution, so a caption that arrived there as plain text
     # got none of it: ":number false" silently lost its rule.  The label
     # is what says "number me", not the presence of the marker.
+    # `centered` rides in the marker's name as a "+center" flag, which the
+    # numbering pass reads off: a figure's caption is centred under it, as
+    # in html and tex; a table's or a listing's stays at the block's edge.
+    flag = "+center" if centered else ""
     if number:
-        caption = kutil.caption_marker(caption_label, caption_text, None)
+        caption = kutil.caption_marker(caption_label + flag, caption_text, None)
     elif caption_text:
-        caption = kutil.caption_marker("", caption_text, None)
+        caption = kutil.caption_marker(flag, caption_text, None)
     else:
         return element
     # Marked laid-out, like the block: with no indent the caption begins