% author : Hans Hagen
% copyright : PRAGMA ADE & ConTeXt Development Team
% license : Creative Commons Attribution ShareAlike 4.0 International
% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
% origin : the ConTeXt distribution
%
% comment : Because this manual is distributed with TeX distributions it comes with a rather
% liberal license. We try to adapt these documents to upgrades in the (sub)systems
% that they describe. Using parts of the content otherwise can therefore conflict
% with existing functionality and we cannot be held responsible for that. Many of
% the manuals contain characteristic graphics and personal notes or examples that
% make no sense when used out-of-context.
%
% comment : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
% Group journal or otherwise. Thanks to the editors for corrections. Also thanks
% to users for testing, feedback and corrections.
\environment manuals-xml-environment.tex
\useMPlibrary [ove]
\usemodule[x][mathml]
\usemodule[m][steps]
\startdocument[title=Steps,author=Hans Hagen,palet=steps]
\startbuffer
\startSTEPchart
\cell {A}
\cell {one} \text{+2}
\cell {two} \text{+3}
\cell {three} \text{+4}
\cell {four} \text{+5}
\cell {five}
\stopSTEPchart
\stopbuffer
\startsection[title=Description]
This module is written in the process of defining a couple of styles for an
educational math book. The macros provide you a way to visualize steps in for
instance solving equations.
The horizontal visualization is called stepchart, while the vertical alternative
carries the name steptable. The vertical alternative has a special case that
permits alignment on a mid symbol (in most cases a relation).
The implementation uses a combination of \TEX\ and \METAPOST, and is set up in
such a way that hyperlinks and alike will work okay.
\stopsection
\startsection[title=Structure]
The horizontal stepcharts have at most four rows: two rows of cells with each an
associated row of texts. The plural elements \type {cells} and \type {texts} each
have two subelements. The \type {texts} elements are put between \type {cells}.
\startbuffer
some text some text
text text
some text some text
\stopbuffer
\typebuffer \processxmlbuffer
When a singular \type {cell} element is used in combination with the plural \type
{texts}, we get one row of step cells with both top and bottom texts.
\startbuffer
some text |
text text
some text |
\stopbuffer
\typebuffer \processxmlbuffer
The third horizontal alternative only has singular elements, and as a result the
texts are put above the step cells.
\startbuffer
some cell |
another cell | a bit of text
third cell | more text
last cell |
\stopbuffer
\typebuffer \processxmlbuffer
Normally, the lines go from cell to cell via a text. When you let the \type
{cell} element follow by more than one \type {text} element (or their plural
forms), all lines will start at the same point.
\startbuffer
some text |
some text | text 1 text 2
some text |
some text | text 3
some text |
\stopbuffer
\typebuffer \processxmlbuffer
The vertical alternative (of course) looks different and permits pretty long
explanations.
\startbuffer
cell 1 |
text 1
cell 2 |
text 2
cell 3 |
\stopbuffer
\typebuffer \processxmlbuffer
When the plural element \type {cells} is used, three sub||elements are expected.
These align around the mid element \type {c2}.
\startbuffer
left center right
text
lft ctr rgt
text
l c r
\stopbuffer
\typebuffer \processxmlbuffer
\stopsection
\startsection[title=Lines]
You can draw lines normally or dashes and with or without arrows in both
directions. This is controlled by the \type {alternative} option of \type
{\setupSTEPaligntable}. As an example we use this table:
\startbuffer[table]
\startSTEPaligntable
\cells {$2c$} {$=$} {$2a+3b$}
\text {with $a=5$}
\cells {$2c$}{$=$} {$10+3b$}
\text {and $b=6$}
\cells {$2c$} {$=$} {$10+18$}
\text {we get}
\stopSTEPaligntable
\stopbuffer
\typebuffer[table]
Next we show the (currently) 9 alternatives. The zero alternative draws no lines
so there we can make the distance smaller.
\startbuffer
\setupSTEPlines
[alternative=0,
width=.5em]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=1]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=2]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=3]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=4]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=5]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=6]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=7]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\startbuffer
\setupSTEPlines
[alternative=8]
\stopbuffer
\typebuffer \startlinecorrection \getbuffer \getbuffer[table] \stoplinecorrection
\stopsection
\startsection[title=Usage]
The step chart module is loaded with:
\starttyping
\usemodule[cell] % was step
\stoptyping
\noindentation but in the case of embedded math, you should also load the \MATHML\ module:
\starttyping
\usemodule[cell,mathml]
\stoptyping
\stopsection
\startsection[title=\XML\ example]
Because we don't want to clutter the examples with \MATHML\ we stick to a simple
mapping:
\startbuffer
\startxmlsetups xml:math:simple
\xmlsetsetup {#1} {m} {xml:math:simple:tex}
\stopxmlsetups
\startxmlsetups xml:math:simple:tex
\mathematics{\xmlflush{#1}}
\stopxmlsetups
\xmlregistersetup{xml:math:simple}
\stopbuffer
\typebuffer \getbuffer
So, in the next examples the \type {m} element contains \TEX\ math.
\startbuffer
A B
one five
+2 -2
two four
+3 -3
three three
+4 -4
four two
+5 -5
five one
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
A |
one | +2
two | +3
three | +4
four | +5
five |
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
|
with
|
and
|
we get
|
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
c = 2a+3b
with a=5
c = 10+3b
and b=6
c = 10+18
we get
c = 28
\stopbuffer
\typebuffer \processxmlbuffer
\stopsection
\startsection[title=\TEX\ example]
\startbuffer
\startSTEPchart
\cells {A} {B}
\cells {one} {five or more} \texts{$+2$}{$-2$}
\cells {two} {four} \texts{$+3$}{$-3$}
\cells {three} {three} \texts{$+4$}{$-4$}
\cells {four} {two} \texts{$+5$}{$-5$}
\cells {five or more} {one}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPchart
\cell {A}
\cell {one} \texts{$+2$}{$-2$}
\cell {two} \texts{$+3$}{$-3$}
\cell {three} \texts{$+4$}{$-4$}
\cell {four} \texts{$+5$}{$-5$}
\cell {five or more}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPchart
\cells {A} {B}
\cells {one} {five or more} \texts{$+2$}{}
\cells {two} {four} \texts{}{$-3$}
\cells {three} {three} \texts{$+4$}{}
\cells {four} {two} \texts{}{$-5$}
\cells {five or more} {one}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPchart
\cell {A}
\cell {one} \text{+2} \text{+3} \text{+4} \text{+5}
\cell {two}
\cell {three}
\cell {four}
\cell {five}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPchart
\cell {A}
\cell {one} \texts{}{+2} \texts{}{+3}
\cell {two}
\cell {three} \texts{+4}{} \texts{+5}{}
\cell {four}
\cell {five}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPchart
\cell {A}
\cell {one} \text{+2}
\cell {two} \text{+3}
\cell {three} \text{+4}
\cell {four} \text{+5}
\cell {five}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPtable
\cell {$c=2a+3b$}
\text {with $a=5$}
\cell {$c=10+3b$}
\text {and $b=6$}
\cell {$c=10+18$}
\text {we get}
\cell {$c=28$}
\stopSTEPtable
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPaligntable
\cells {$2c$} {$=$} {$2a+3b$}
\text {with $a=5$}
\cells {$2c$}{$=$} {$10+3b$}
\text {and $b=6$}
\cells {$2c$} {$=$} {$10+18$}
\text {we get}
\cells {$2c$} {$=$} {$28$}
\text {and therefore}
\cells {$c$} {$=$} {$28/2$}
\text {which reduces to}
\cells {$c$} {$=$} {$14$}
\stopSTEPaligntable
\stopbuffer
\typebuffer \getbuffer
\startbuffer
\startSTEPchart
\cells {A} {B}
\cells {one} {five} \texts{$+2$}{$-2$}
\cells {two} {four} \texts{$+3$}{$-3$}
\cells {three} {three} \texts{$+4$}{$-4$}
\cells {four} {two} \texts{$+5$}{$-5$}
\cells {five} {one}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\stopsection
\startsection[title=Configuring]
The charts and tables can have their own spacing set. Quite certainly the
distances between cells will differ.
\starttabulate[|Tl|l|]
\HL
\NC \rlap{\tex{setupSTEPcharts} \tex{setupSTEPtables}} \NC \NC \NR
\HL
\NC after \NC hook for commands to execute after the table \NC \NR
\NC before \NC hook for commands to execute before the table \NC \NR
% \NC method \NC line drawing method\NC \NR
% \NC height \NC height of the connecting line \NC \NR
% \NC offset \NC the distance between lines and cells and texts \NC \NR
% \NC hoffset \NC the horizontal distance between cells \NC \NR
% \NC voffset \NC the vertical distance between cells \NC \NR
\HL
\stoptabulate
Both charts and tables have common settings with respect to the cells, texts and
lines.
\starttabulate[|Tl|l|]
\HL
\NC \rlap{\tex{setupSTEPcells} \tex{setupSTEPtexts}} \NC \NC \NR
\HL
\NC alternative \NC the kind of shape to be drawn \NC \NR
\NC backgroundcolor \NC the background color identified by name \NC \NR
\NC rulethickness \NC the width of frame around cells \NC \NR
\NC framecolor \NC the frame color identified by name \NC \NR
\NC offset \NC the space between content and frame \NC \NR
\NC style \NC a (preferable named) style \NC \NR
\NC color \NC the color of the content \NC \NR
\HL
\stoptabulate
\starttabulate[|Tl|l|]
\HL
\NC \rlap{\tex{setupSTEPlines}} \NC \NC \NR
\HL
\NC alternative \NC the kind of line to draw between cells \NC \NR
\NC distance \NC the distance between lines and text \NC \NR
\NC offset \NC the shift to the right of the start of the line \NC \NR
\NC height \NC the height of the (curved) line \NC \NR
\NC rulethickness \NC the width of the lines between cells \NC \NR
\NC color \NC the line color identified by name \NC \NR
\HL
\stoptabulate
In \TEX, some of the settings, like \type {style} and \type {color} can be set
between elements. In \XML, the settings are passed as processing instructions.
\startbuffer
\startSTEPchart
\cell {A}
\cell {one} \text{+2}
\cell {two} \text{+3}
\start
\setupSTEPcells[color=darkred,style=bold]
\cell {three} \text{+4}
\cell {four} \text{+5}
\stop
\cell {five}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
There are a couple of alternative shapes available. The most relevant ones are:
\removeunwantedspaces \dostepwiserecurse {5} {9} {1} { \TestShape {\recurselevel}}
\removeunwantedspaces \dostepwiserecurse {12} {19} {1} { \TestShape {\recurselevel}}
\removeunwantedspaces \dostepwiserecurse {22} {29} {1} { \TestShape {\recurselevel}}.
Although it is not too wise to set up the layout in the middle of a document, for
graphics one can seldom get by some local fine||tuning. Here we encounter a
rather fundamental difference between \TEX\ and \XML. In \TEX, you can easily
change settings on a temporary basis by using groups. In \XML\ on the other hand,
settings are bound to a category. So, in \TEX\ you can do this:
\startbuffer
\setupSTEPcells
[important]
[color=darkgreen,
style=bold]
\startSTEPchart
\cell {A}
\cell {one} \text{+2}
\cell {two} \text{+3}
\cell [important] {three} \text{+4}
\cell [important] {four} \text{+5}
\cell {five}
\stopSTEPchart
\stopbuffer
\typebuffer \getbuffer
\noindentation An \XML\ example is:
\startbuffer
\setupSTEPcells[demo-1][alternative=5]
\setupSTEPcells[demo-1][framecolor=darkred]
\setupSTEPtexts[demo-1][framecolor=darkgreen]
\setupSTEPlines[demo-1][alternative=4]
\setupSTEPtexts[demo-2][style=bold]
\stopbuffer
\typebuffer \getbuffer
\noindentation This will be applied to:
\startbuffer
type 5 |
type 6
type 7 |
type 8
type 9 |
\stopbuffer
\typebuffer
\noindentation so that we get:
\processxmlbuffer
You can also use processing instructions:
\startbuffer
some text 1 some text 2
text 3 text 4
some text 5 some text 6
text 7t
some text 8
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
cell 12 | 12 to 13
cell 13 | 13 to 14
cell 14 | 14 to 15
cell 15 |
\stopbuffer
\typebuffer \processxmlbuffer
Some settings apply to the whole chart. In \TEX\ this is easy since we
can group the whole chart including settings but in \XML\ this is somewhat
problematic. We can however fall back on basic tex commands but it's
probably better to use as category (class), like:
\startbuffer
\setupSTEPtexts[demo-5][distance=3em]
\stopbuffer
\typebuffer \getbuffer
\noindentation So, the following works as expected:
\startbuffer
a b c
test 1
aa b ccc
a b c
test 2
aa b ccc
a b c
test 3
aa b ccc
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
from here there
to to
and here there
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
some cell |
another cell | a bit of text
third cell | more text
last cell |
\stopbuffer
\typebuffer \processxmlbuffer
\startbuffer
some cell |
another cell | a bit of text
third cell | more text
last cell |
\stopbuffer
\typebuffer \processxmlbuffer
\stopsection
\startsection[title=Documentation]
There is no additional documentation on this module.
\stopsection
\stopdocument