summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt')
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt209
1 files changed, 209 insertions, 0 deletions
diff --git a/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt b/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt
new file mode 100644
index 0000000000..73df087b87
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt
@@ -0,0 +1,209 @@
+sdapsarray package
+==================
+
+This is a base package for "array" like environments. It really is similar to a
+tabularx environment to some extend. Its purpose is much more specialized compared
+to tabularx. It is less flexible in the types of layouts that can be realized but
+a lot more powerful otherwise. The `sdapsarray` environment has the following
+features:
+
+* All :environ:`sdapsarray` environments in the document can be aligned to each other
+* The environment can span multiple pages
+* Headers will be repeated when page splits are encountered
+* The rows/columns can be swapped on the fly
+* Different ``layouter`` can be plugged in to modify the rendering
+* Fragile content can be used without further preparation
+* Contained content is executed exactly once (important for metadata generation)
+
+Things that are *not* possible currently:
+
+* Row or column backgrounds
+* Grid lines
+
+.. warning::
+ The :environ:`sdapsarray` is **not** a ``tabular`` like environment. It behaves
+ in similar ways, but there are fundamental differences, causing some issues:
+
+ * You **must not** add a trailing ``\\`` to the last row.
+
+.. sdaps:: Example of a sdapsarray environment
+
+ The following two \texttt{sdapsarray} environments are almost identical. They
+ are both aligned to each other because the \texttt{align} option is set to
+ the same value. In the second environment the rows and columnes are swapped
+ by setting the \texttt{flip} option.
+
+ \begin{sdapsarray}[align=testing]
+ row header & colum header & colum header \\
+ row header & cell 1 & cell 2 \\
+ row header & cell 3 & cell 4
+ \end{sdapsarray}
+
+ \hrule
+
+ \begin{sdapsarray}[flip,align=testing]
+ row header & colum header & colum header \\
+ row header & cell 1 & cell 2 \\
+ row header & cell 3 & cell 4
+ \end{sdapsarray}
+
+.. sdaps:: Example of a sdapsarray environment split over two columns using multicols
+ :preamble: \usepackage{multicol}
+
+ \begin{multicols}{2}
+ \begin{sdapsarray}[align=testing,layouter=rotated]
+ colum header 0 & colum header 1 & colum header 2 \\
+ row header 1 & cell 1 & cell 2 \\
+ row header 2 & cell 3 & cell 4 \\
+ row header 3 & cell 5 & cell 6 \\
+ row header 4 & cell 7 & cell 8 \\
+ row header 5 & cell 9 & cell 10 \\
+ row header 6 & cell 11 & cell 12
+ \end{sdapsarray}
+ \end{multicols}
+
+
+Layout and formatting considerations
+------------------------------------
+
+The following hold true inside the environment:
+
+* The row headers are set into a :macro:`\\vtop` with the left over width from
+ the cells. This vertical box is later re-set into a :macro:`\\vbox`. The
+ effect is that the interrow skip is calculated between the last element of
+ the previous row and the first element of the next row. this means you must
+ be careful to not insert invisible content at the start of the vertical box.
+ (e.g. by adding a :macro:`\\leavevmode`).
+* The exception to the above rule is the start of the environment (i.e. the
+ header row) for which the top baseline information is (currently) discarded!
+* Each cell is set into an :macro:`\\hbox` with the last skip in the box removed
+ again (i.e. trailing space). You can use :macro:`\\hfill` to align the box to
+ the left/right but need to prevent the :macro:`\\hfill` to be removed again
+ for left alignment (e.g. by adding a ``\kern 0pt``).
+* Column headers behave like cells but a special layouter can be assigned to
+ them.
+* Row headers and column headers will usually be set on a common baseline. The
+ exception to this is if the column header contains multiple boxes/lines. In
+ that case the cells will be centered ignoring the baselines of both cells
+ and row header.
+* A penalty of 10 is inserted between rows.
+
+
+sdapsarray environment
+----------------------
+
+.. environ::
+ \begin{sdapsarray}[kwargs]
+ content with cells delimitted with & and \\
+ \end{sdapsarray}
+
+ :kwarg flip: Transpose array making rows to columns (default: ``false``)
+ :kwarg layouter: The layouter to use. New layouters can be defined, the following
+ exists by default:
+
+ * ``default``: Simple layout centering cells and giving all leftover space to the row
+ header which will line break automatically (this is the default)
+ * ``rotated``: Similar to default but rotates the column headers
+
+ :kwarg angle: The angle of the header when in ``rotated`` mode
+ :kwarg align: An arbitrary string to align multiple :environ:`sdapsarray` environments
+ to each other. All environments with the same string will be
+ aligned. (default: no alignment)
+ :kwarg keepenv: Do not modify the parser to consume ``&`` and ``\\`` for alignment.
+ Instead, the user must use :macro:`\\sdaps_array_alignment:` and :macro:`\\sdaps_array_newline:`.
+ This is only useful for writing custom environments which use :environ:`sdapsarray` internally.
+ Normal users should simply put any nested `array` environment into :macro:`\\sdapsnested`
+ to prevent issues (see below).
+ :kwarg no_header: Disable column header handling and repeating. Note that this
+ setting is independent of whether the ``flip`` option is set. As such, one may
+ need to take its value into account when setting it. (default: ``false``)
+ :kwarg colsep: Spacing added on the left/right of every cell. This defaults to `6pt`.
+ :kwarg rowsep: Extra spacing added between rows. This defaults to `0pt`.
+
+ The ``keepenv`` option should usually not be used by an end user writing a document, it is very useful
+ when writing environments which use :environ:`sdapsarray` internally (like :environ:`choicearray`).
+
+ .. macro:: \sdapsnested{content}
+
+ Reverts the ``&`` and ``\\`` to their original meaning. Content in an
+ :environ:`sdapsarray` environment can be wrapped with this if it requires
+ these characters to be active (i.e. you can use the ``array`` environment
+ this way for example).
+
+ .. macro:: \sdaps_array_alignment:
+
+ Alternative to using the ``&`` delimiter between cells. This is useful together
+ with the ``keepenv`` kwarg argument. In particular when creating custom environments
+ which use sdapsarray internally.
+
+ .. macro:: \sdaps_array_newline:
+
+ Alternative to using the ``\\`` delimiter between cells. This is useful together
+ with the ``keepenv`` kwarg argument. In particular when creating custom environments
+ which use sdapsarray internally.
+
+ .. sdaps:: Two sdapsarray environments each with a nested array, in one case using the keepenv option.
+ :preamble:
+ \usepackage{multicol}
+ % Wrap the commands with _ as we cannot use them directly. This needs to
+ % be a \def and not a \let because they are redefined dynamically internally.
+ \ExplSyntaxOn
+ \def\sdapsalignment{\sdaps_array_alignment:}
+ \def\sdapsnewline{\sdaps_array_newline:}
+ \ExplSyntaxOff
+
+ \begin{multicols}{2}
+ \begin{sdapsarray}
+ & col 1 & col 2 \\
+ row header 1 & \sdapsnested{$ \begin{array}{cc} a & b \\ c & d \end{array}$} & cell 2 \\
+ \verb^row_header^ & cell 3 & cell 4
+ \end{sdapsarray}
+
+ \begin{sdapsarray}[keepenv]
+ \sdapsalignment col 1 \sdapsalignment col 2 \sdapsnewline
+ row header 1 \sdapsalignment $ \begin{array}{cc} a & b \\ c & d \end{array}$ \sdapsalignment cell 2 \sdapsnewline
+ \verb^row_header^ \sdapsalignment cell 3 \sdapsalignment cell 4
+ \end{sdapsarray}
+ \end{multicols}
+
+
+Defining a custom layouter
+--------------------------
+
+.. warning:: This is an advanced feature and its use a good or even in depth knowledge of how TeX processes boxes and input!
+
+It is possible to register further ``layouter``
+which can subsequently used throughout the document. These layouters need to
+adhere to a number of rules which will not be explained in detail here.
+
+The following code is a copy of the two predefined layouter not showing the
+implementation of the different macros. Visible here is that they only differ
+in the method to render the column header ``colhead``, all other methods are
+identical.
+
+.. code::
+
+ \prop_gput:Nnn \g__sdaps_array_layouter_prop { default } {
+ begin = { \_sdaps_array_begin_default: },
+ row_start = { \_sdaps_array_row_start_default: },
+ rowhead = { \_sdaps_array_rowhead_default:Nw },
+ colhead = { \_sdaps_array_cell_default:Nw },
+ cell = { \_sdaps_array_cell_default:Nw },
+ row = { \_sdaps_array_row_ltr:NNNN },
+ end = { \_sdaps_array_end_default: },
+ }
+
+ \prop_gput:Nnn \g__sdaps_array_layouter_prop { rotated } {
+ begin = { \_sdaps_array_begin_default: },
+ row_start = { \_sdaps_array_row_start_default: },
+ rowhead = { \_sdaps_array_rowhead_default:Nw },
+ colhead = { \_sdaps_array_cell_rotated:Nw },
+ cell = { \_sdaps_array_cell_default:Nw },
+ row = { \_sdaps_array_row_ltr:NNNN },
+ end = { \_sdaps_array_end_default: },
+ }
+
+If you consider modifying the layouter, then please have a look at the relevant
+parts of ``sdapsarray.dtx``. Also, please consider submitting modifications for
+upstream inclusion so that other people can benefit from new features.
+