diff options
Diffstat (limited to 'macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt')
-rw-r--r-- | macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt | 209 |
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. + |