improved doc for figures & tables

latexlike_minilang_howto.md

@@ -1,7 +1,27 @@
 # LaTeX-inspired mini-language in text
 
 In most text fields, you can make use of the following LaTeX-inspired
-features:
+features.
+
+## An example
+
+Here's an example to get you started:
+
+```latex
+Text can contain some simple LaTeX macros, for instance
+for \textbf{bold text} and \emph{italic text}.
+
+Use two line breaks to start a new paragraph. You
+can use inline math like \(\alpha=\sum_j\beta_j\) and
+display equations like
+\begin{align}
+    S_1 &= I\,X\,Z\,Z\,X\ ;  \nonumber\\
+    S_2, \ldots, S_4 &= \text{cyclical permutations of \(S_1\)}\ .
+    \label{eq:stabilizers}
+\end{align}
+
+Refer to equations with \eqref{eq:stabilizers}, etc. ...
+```
 
 ## Bold, emphasis, special characters
 
@@ -83,66 +103,108 @@ features:
 
 ## Figures and tables
 
-  - At last, we have support for the float environments
-    ``\begin{figure} ... \end{figure}`` and ``\begin{table}
-    ... \end{table}``.  Both of these environments produce a break in
-    the text (they place their content immediately), in contrast to
-    their standard LaTeX implementation.  The syntax of these
-    environments is as follows:
-    ```
+  - You can use the float environments ``\begin{figure} ... \end{figure}`` and
+    ``\begin{table} ... \end{table}``.  The syntax of these environments is as
+    follows:
+
+    ```latex
     \begin{figure}
         \includegraphics{figure_file_name}
         \caption{Your figure can have a caption}
         \label{figure:my-figure-label}
     \end{figure}
+
+    \begin{table}
+        \begin{cells}
+          \celldata{
+            (... table content, see below...)
+          }
+        \end{cells}
+        \caption{Your table can have a caption}
+        \label{table:my-table-label}
+    \end{table}
     ```
+    
+    Both of these environments produce a break in the text (they place their
+    content immediately), in contrast to their standard LaTeX implementation.
+    However, you should avoid counting on this behavior, and use the standard
+    label-ref mechanism to refer to the figure from the main text.
 
-    The ``figure_file_name`` must be the name of an image file that is
-    in the code YAML file tree, which is searched relative to the code
-    YAML file's path.  In ``figure_file_name``, the file name
-    extension (e.g., ``.svg``) can be omitted.  The preferred file
-    structure for codes that have image files is to place the code
-    YAML file along with the image files in their own, separate folder
-    that is specific to that code.
+    You may omit both ``\caption`` and ``\label`` commands to generate
+    a figure without any caption.  If you specify a ``\label`` and
+    omit the ``\caption`` command, a figure with the simple legend
+    text “*Figure X*” or “*Table X*” will be generated.
+    
+    You can also use the label to reference the figure from the main
+    text with ``\ref{figure:my-figure-label}``.  The label prefix
+    `figure:` or `table:` must match the float environment name.  *In
+    contrast to standard LaTeX, the ``\ref`` command will include the
+    word “Figure” or “Table” along with the reference*.  In this
+    regard, ``\ref`` acts more like
+    LaTeX/[cleveref](https://ctan.org/pkg/cleveref)'s ``\cref``
+    command.
+
+    Our parser is very picky about the syntax of commands within float
+    environments and will issue errors if you deviate from it.
+
+  - *Figure images:* The ``figure_file_name`` must be the name of an
+    image file that is in the code YAML file tree, which is searched
+    relative to the code YAML file's path.  In ``figure_file_name``,
+    the file name extension (e.g., ``.svg``) can be omitted.  The
+    preferred file structure for codes that have image files is to
+    place the code YAML file along with the image files in their own,
+    separate folder that is specific to that code.
     
     You may not specify optional sizing/trimming/cropping arguments to
     the ``\includegraphics`` command.  Please prepare your figure
     directly at the correct size.  Bear in mind that if you have text
     elements in your figure, then resizing the figure will cause a
-    visual mismatch with the article text appearance.
+    visual mismatch with the article text appearance.  See notes on
+    images below.
+
+  - *Tables:* We now support an experimental mechanism for building
+    pretty tables.  The table's data is given through the
+    ``\begin{cells}...\end{cells}`` environment.  See below for a
+    description of the syntax for specifying table contents.
+    
 
-    You may omit both ``\caption`` and ``\label`` commands to generate
-    a figure without any caption.  If you specify a ``\label`` and
-    omit the ``\caption`` command, a figure with the simple legend
-    text “*Figure X*” will be generated.  You can also use the label
-    to reference the figure from the main text with
-    ``\ref{figure:my-figure-label}``.  The label prefix `figure:`
-    or `table:` must match the float environment name.
 
-    Our parser is very picky about this syntax and will issue errors
-    if you deviate from it.
+### Image files
     
-  - The preferred file format is a vector SVG file.
+The preferred file format is a vector SVG file.
   
-    The size at which you place elements in your SVG file is
-    important.  The stated physical dimensions that are present in the
-    SVG file are used to place the image at the correct size and
-    resolution to match the surrounding article.  General text should
-    be typeset preferably using the ‘Source Sans Pro’ at 10 point
-    size, to match the typography of the surrounding article.  (You
-    can place smaller or bigger text for axis markers, or use a
-    different font if it's necessary, or etc.; use your good judgment
-    and common sense.  We'll come back at you in case we'd prefer some
-    changes.)
-    
-    Be sure also to set the page dimensions of your SVG document
-    correctly to match the size of your graphic.  If you use Inkscape,
-    you can select “File” → “Document Properties” → “Resize page to
-    drawing or selection.”
-    
-    You can also use PNG or JPG/JPEG files.  In this case, the
-    stated physical dots-per-inch or pixels-per-inch setting of the
-    image, read directly from the image metadata, is honored.
+The size at which you place elements in your SVG file is important.
+The stated physical dimensions that are present in the SVG file are
+used to place the image at the correct size and resolution to match
+the surrounding article.  General text should be typeset preferably
+using the ‘Source Sans Pro’ at 10 point size, to match the typography
+of the surrounding article.  (You can place smaller or bigger text for
+axis markers, or use a different font if it's necessary, or etc.; use
+your good judgment and common sense.  We'll come back at you in case
+we'd prefer some changes.)
+    
+Be sure also to set the page dimensions of your SVG document correctly
+to match the size of your graphic.  If you use Inkscape, you can
+select “File” → “Document Properties” → “Resize page to drawing or
+selection.”
+
+If you set the SVG image's dimensions in units of pixels ("px"), we'll
+assume a resolution of 96 DPI (as per web standards).  *[If you're
+using Affinity Designer, set the document resolution to 96 dpi, and
+uncheck ‘Set viewBox’ in the SVG export options.]*
+    
+You can also use PNG or JPG/JPEG files.  **Please make sure you set
+the physical resolution (DPI) correctly**, as this information is
+honored to determine the figure size.  Good graphics software will
+allow you to adjust this setting (look for "physical dimensions",
+"dots-per-inch", "pixels-per-inch", or "DPI").  In
+[GIMP](https://www.gimp.org/), you can set the resolution with "Image"
+-> "Resize" and providing any two of physical dimensions (e.g.,
+mm,cm,in,pt), pixel dimensions, and DPI.  Please keep your figure
+width to *at most 12cm (5.5in)* to obtain a good page layout without
+the user having to scroll the figure horizontally.
+
+
 
   - Tables function in exactly the same way as figures, and
     furthermore, the table content must be provided as an external
@@ -182,26 +244,136 @@ features:
     code YAML tree, in case the table needs to be modified or
     regenerated at a later point in time.
     
-    
 
 
-## An example
+### Table Contents — Cells
+
+The syntax for the table cells is as follows:
+
+```latex
+\begin{cells}
+  \celldata{
+     One & Two & Three \\
+     Four & Five & Six
+  }
+  [ ... ]
+\end{cells}
+```
+
+The ``{cells}`` environment may contain any number of calls to the
+macros ``\celldata`` and ``\cell``.  Each such macro call adds new
+cells to the table.  The macros have the following syntax:
+
+- ``\cell{contents}``, ``\cell<style1 style2 ...>{contents}``,
+  ``\cell[location]{contents}``,
+  ``\cell<styles...>[location]{contents}``: Add a single cell to
+  the table.  Unless a location is specified, the cell is added in
+  the next column on the current row.
+
+  The `[location]` can either specify a column `[COL]` (will use
+  the current row) or a pair `[ROW;COL]`.  Each of `COL` and `ROW`
+  can be:
+
+  - a row/column number (row and column numbers start at 1);
 
-For example:
+  - left empty, or set to the character ``.``, to mean the current
+    row/column;
 
-    Text can contain some simple LaTeX macros, for instance
-    for \textbf{bold text} and \emph{italic text}.
+  - a ``\merge{INDEXRANGE}`` command to create a merged cell
+    spanning multiple rows/columns.  Here, the ``INDEXRANGE`` can
+    be comma-separated numbers (e.g., ``1,2,3`` to include the
+    given row/column numbers), including ranges specified as
+    ``START-END`` (such as e.g. ``2-4`` for row/column indices 2
+    through 4, included) as well as ``START+NUMBER`` to include
+    ``NUMBER`` columns starting at index number ``START`` (e.g.,
+    ``2+3`` will include column numbers ``2``, ``3`` and ``4``).
+    Ranges can be combined, separated by commas, but in any case
+    the `INDEXRANGE` must correspond to a contiguous set of
+    indices.
 
-    Use two line breaks to start a new paragraph. You
-    can use inline math like \(\alpha=\sum_j\beta_j\) and
-    display equations like
-    \begin{align}
-        S_1 &= I\,X\,Z\,Z\,X\ ;  \nonumber\\
-        S_2, \ldots, S_4 &= \text{cyclical permutations of \(S_1\)}\ .
-        \label{eq:stabilizers}
-    \end{align}
+  The ``<styles...>`` argument specifies the style that will be
+  applied to the cell.  See information on cell styles below.  You
+  can specify multiple styles by separating them with spaces.
+
+  *Example:* ``\cell<H l>[1;\merge{3-4}]{Hi!}`` will create a
+  left-aligned (``l``) header (``H``) cell at row ``1`` and
+  spanning the columns ``3`` and ``4``, with the contents
+  “``Hi!``”.
+
+
+- ``\celldata{tabular data}``, ``\celldata<cellstyles>{tabular
+  data}``, ``\celldata[locations]{tabular data}``,
+  ``\celldata<cellstyles>[locations]{tabular data}``: A shorthand
+  for sequentially adding multiple cells.
+
+  The ``{tabular data}`` is specified as you'd do for the LaTeX
+  ``\begin{tabular} ... \end{tabular}`` environment, by separating
+  rows with ``\\`` and separating columns with ``&``.
+
+  The cells can be placed at given locations, and each cell is
+  styled according to the given styles.
+
+  The optional ``[locations]`` is of the form of either
+  ``[COLUMNS]`` or ``[ROWS;COLUMNS]``.  If ``ROWS`` are not
+  specified, then rows are added sequentially starting from the
+  current row.  Each of ``ROWS`` and ``COLUMNS`` specify a
+  sequence of row/column indices to which the given data will be
+  assigned.  For instance, ``\celldata[3,2,1]{A & B & C}`` will
+  place ``A`` in the 3rd column, ``B`` in the 2nd column, and
+  ``C`` in the 1st column.  More specifically, ``ROWS`` and
+  ``COLUMNS`` are specified a comma-separated list of indices, of
+  ranges of the form ``START-END`` or ``START+NUMBER`` (see
+  above), and of ``\merge{}`` commands (see above).  Omitting
+  ``START`` or ``END`` is interpreted as the current or the last
+  index, respectively.  For instance:
+
+  - ``\celldata[2-5]{A & B & C & D\\ E & F & G & H}`` will place
+    ``A``, ``B``, ``C``, ``D`` in columns 2, 3, 4, 5 of the first
+    row, and place ``E``, ``F``, ``G``, ``H`` in columns 2, 3, 4,
+    5 of the following row;
+
+  - ``\celldata[\merge{1,2},\merge{+2};4,6]{A & AA \\ B & BB}``
+    will place ``A`` in a merged cell spanning rows ``1,2`` and in
+    column ``4``, ``AA`` in a merged call spanning rows ``1,2``
+    and in column ``6``, ``B`` in a merged call spanning rows
+    ``3,4`` and in column ``4``, and ``BB`` in a merged call
+    spanning rows ``3,4`` and in column ``6``.
+
+  The ``styles`` is a comma-separated list of styles to apply to
+  the different columns.  The same style is applied to all
+  provided cells of that column.  The sequence corresponds to the
+  given data, not the final column number.  If there are fewer
+  style specifications than columns, then the last style is
+  repeated as necessary.  For each column style you can specify
+  multiple styles by separating them with spaces.  For instance:
+
+  - ``\celldata<H>{One & Two & Three}`` Creates three header
+    (``H``) cells on a single row.
 
-    Refer to equations with \eqref{eq:stabilizers}, etc. ...
+  - ``\celldata<H l, H c>{One & Two & Three}`` Creates one
+    left-aligned (``l``) header (``H``) cell with content
+    “``One``”, and two centered (``c``) header (``H``) cells with
+    respective content “``Two``” and “``Three``”.
 
 
 
+*Cell styles:*
+
+- ``H`` — this cell is a column header.  It will be typeset in a
+  more prominent form (e.g., boldface with a light bottom border);
+
+- ``rH`` — this cell is a row header.  It will be typeset more
+  prominently (e.g., boldface);
+
+- ``l``, ``c``, ``r`` — align cell contents ``l``eft, ``c``entered
+  or ``r``ight;
+
+- ``lvert``, ``rvert`` — add a thin vertical border on the left or
+  the right side of the cell;
+
+- ``green``, ``blue``, ``yellow``, ``red`` — apply a background
+  color to the cell to emphasize it in some way.
+
+
+
+

stylesheets/llm-formatting.scss

@@ -63,6 +63,9 @@ table.cells {
   .cellstyle-green {
       background-color: rgb(200,255,215);
   }
+  .cellstyle-blue {
+      background-color: rgb(200,220,255);
+  }
   .cellstyle-yellow {
       background-color: rgb(255,255,200);
   }