Open main menu

Changes

2,314 bytes added ,  09:28, 29 April 2021
\setupsidebar: better description and more examples
<cd:commandgroup name="setupsidebar" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807">
<cd:shortdesc><!-- a short command summary goes here -->
The command <tt>\setupsidebar</tt> is used to customize vertical bars. They that are drawn starting from the left edge of the text, but you can move them anywhere horizontally. `\startsidebar[...]` ... `\stopsidebar` can be placed inside the text of a paragraph used to "vertically underline"portions of text. The bars follow the lines where there's the text between `\startsidebar[...]` and `\stopsidebar`.They are drawn from the top of the first line to the bottom of the last line of that portion of text. You can fine-tune the starting and ending points of a bar with `topoffset` and `bottomoffset`. `\startsidebar[...]` ... `\stopsidebar` can be nested: in this case the `distance` parameter is used to move the second bar (the inner one) relatively to the first one.</cd:shortdesc>
<cd:variants>
<cd:command category="rules" file="anch-bar.mkiv" interfacedate="2020-06-19T13:41" interfacefile="i-sidebar.xml" level="style" name="setupsidebar" variantnumber="1">
</cd:parameter>
<cd:parameter name="leftmargindistance">
<cd:paramdoc>distance from the left edge of the text; if it's zero, it's made equal to distance</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="level">
<cd:paramdoc>a number specifying a sort of layer on which the bar is drawn; when a bar is already drawn in the same level, the next one will be drawn with a `distance` offset; if you draw a second bar in a higher level, it will overlap bars of lower levels</cd:paramdoc>
<cd:constant type="cd:number"></cd:constant>
</cd:parameter>
</cd:variants>
<cd:description><!-- the long description of the command goes here -->
`\setupsidebar` customizes the appearance of vertical bars drawn along the portions of text between `\startsidebar[...]` and `\stopsidebar`.
 
`\startsidebar[...]` ... `\stopsidebar` can be placed inside the text of a paragraph to "vertically underline"
portions of text.
They are drawn from the top of the first line to the bottom of the last line of the text between the two commands.
 
You can fine-tune the starting and ending points of a bar with `topoffset` and `bottomoffset`.
 
`\startsidebar[...]` ... `\stopsidebar` can be nested: in this case the `distance` parameter is used to move the second bar (the inner one) relatively to the first one. The first one is drawn at distance `distance` from the left edge of the text, each of the next ones will be drawn at distance `distance` from the previous one.
 
In case you specify a non zero length for the `leftmargindistance` parameter, you can discriminate the distance from the text (`leftmargindistance`) from the distance between bars (`distance`).
 
The `level` parameter lets you define sidebars on different layers. The bars with higher values of `level` are drawn on top.
</cd:description>
<cd:examples><cd:example title="A simple side bar"><context source="yes" text="produces">\definesidebar[simple][rulethickness=1pt,distance=3pt4pt]
\starttext
\hsize=4cm
The sidebar follows the text between \type{\startsidebar[simple]} and \type{\stopsidebar},
\startsidebar[simple] {\blue from the top of the first line to the bottom of the last line.}\stopsidebar
Here the text between \type{\startsidebar[simple]} and \type{\stopsidebar} has been colored in blue. \parblank When the \startsidebar[simple] same bar is started twice on the same text, \startsidebar[simple]a second bar \stopsidebar will be drawn, with an offset equal to the \type{distance} parameter.\stopsidebar \blank \setupsidebar[simple][leftmargindistance=0pt,distance=4pt]When \type{leftmargindistance} is zero, \startsidebar[simple]the bar is drawn at distance \type{distance} from the left edgeof the text,\stopsidebar which means 4pt in this example. \blank \setupsidebar[simple][leftmargindistance=0.1pt,distance=4pt]When \type{leftmargindistance} is not zero, \startsidebar[simple]the bar is drawn at distance \type{leftmargindistance} from the left edgeof the text, which means 0.1pt in this example.\startsidebar[simple] A second bar will be drawn at distance \type{distance}from the first one.\stopsidebar\stopsidebar \blank \setupsidebar[simple][leftmargindistance=0pt,distance=4mm,rulethickness=2mm,level=1]\definesidebar[over][distance=4mm,rulethickness=1mm,rulecolor=green,level=1]When \startsidebar[simple]\startsidebar[over] two sidebars are in the same level,they are drawn at distance \type{distance}.\stopsidebar\stopsidebar \blank \setupsidebar[over][level=2]When \startsidebar[simple]\startsidebar[over] two sidebars are in different levels,they are drawn as if they were in different layers.\stopsidebar\stopsidebar \blank \setupsidebar[simple][rulethickness=1pt,leftmargindistance=\dimexpr -\hsize - 4pt\relax]\startsidebar[simple] You can put a bar in the right margin.\stopsidebar 
\stoptext
</context></cd:example><cd:example title="Custom fancy sidebars">You can define fancy, zig zag bars redefining the `anch_sidebars_draw` macro:
\stopMPcode
\def\samplewithbar#1{The sidebar follows the text
between \type{\startsidebar[...]} and \type{\stopsidebar},
\startsidebar[#1] {\blue from the top of the first line to the bottom of the last line.}\stopsidebar
26

edits