26
edits
Changes
Jump to navigation
Jump to search
first version of \setupsidebar (work in progress)
<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 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 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:arguments>
<cd:keywords list="yes" optional="yes" ordinal="1">
<cd:keywordsdoc></cd:keywordsdoc>
<cd:constant type="cd:name"></cd:constant>
</cd:keywords>
<cd:assignments list="yes" ordinal="2">
<cd:assignmentsdoc></cd:assignmentsdoc>
<cd:parameter name="rulethickness">
<cd:paramdoc>thickness of the bar, i.e. 1pt</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="rulecolor">
<cd:paramdoc>the bar's color</cd:paramdoc>
<cd:constant type="cd:color"></cd:constant>
</cd:parameter>
<cd:parameter name="alternative">
<cd:paramdoc>a number specifying the style of the bar (currently 0=solid bar, 1=dashed bar)</cd:paramdoc>
<cd:constant type="cd:number">0 = solid bar
1 = dashed bar</cd:constant>
</cd:parameter>
<cd:parameter name="topoffset">
<cd:paramdoc>offset to start drawing the bar, from the top of the first line of text between `\startsidebar...\stopsidebar`</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="bottomoffset">
<cd:paramdoc>offset to stop drawing the bar from the bottom of the last line of text between `\startsidebar...\stopsidebar`</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="distance">
<cd:paramdoc>the distance from the left edge of the text or from the previous bar, in case of nested `\startsidebar...\stopsidebar`</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="leftmargindistance">
<cd:paramdoc></cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="level">
<cd:paramdoc></cd:paramdoc>
<cd:constant type="cd:number"></cd:constant>
</cd:parameter>
</cd:assignments>
</cd:arguments>
</cd:command>
</cd:variants>
<cd:description><!-- the long description of the command goes here -->
</cd:description>
<cd:examples><cd:example title="A simple side bar"><context source="yes" text="produces">
\definesidebar[simple][rulethickness=1pt,distance=3pt]
\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.\par
\stoptext
</context></cd:example><cd:example title="Custom fancy sidebars">You can define fancy, zig zag bars redefining the `anch_sidebars_draw` macro:
<context source="yes">
\definesidebar[zigzag1][rulecolor=black,distance=4pt,rulethickness=1pt,alternative=2]
\definesidebar[zigzag2][rulecolor=red,distance=4pt,rulethickness=1pt,alternative=3]
\definesidebar[wave1][rulecolor=blue,distance=4pt,rulethickness=1pt,alternative=4]
\definesidebar[wave2][rulecolor=cyan,distance=4pt,rulethickness=1pt,alternative=5]
\definesidebar[obliquedashes][rulecolor=darkgreen,distance=4pt,rulethickness=1pt,alternative=6]
\startMPcode
% draws a bar repeating a pattern defined from (0,0) to (0,1)
def draw_pattern_bar(expr a, b, pattern, patternlength, patternheight, linewidth, linecolor) =
draw image (
begingroup ;
save p, q, stp ;
pair p, q, stp ;
stp := ( ( b - a ) / arclength( a -- b ) ) * patternlength ;
path q ; q := pattern xscaled patternlength yscaled patternheight rotated (angle(stp)) ;
p := a ;
forever :
draw
q shifted p
withpen pencircle scaled linewidth
withcolor linecolor ;
p := p + stp ;
exitif arclength( a -- p ) > arclength( a -- b ) ;
endfor ;
endgroup ;
clip currentpicture to
(xpart llcorner currentpicture, ypart b) --
(xpart lrcorner currentpicture, ypart b) --
(xpart urcorner currentpicture, ypart a) --
(xpart ulcorner currentpicture, ypart a) -- cycle ;
) ;
enddef ;
% modified from metapost/context/base/mpiv/mp-apos.mpiv to add alternatives
def anch_sidebars_draw (expr p_b_self, p_e_self, y_b_self, y_e_self, h_b_self, d_e_self,
x, y, w, h, alternative, distance, linewidth, linecolor, topoffset, bottomoffset) =
% beware, we anchor at (x,y)
begingroup ;
if alternative = 1 :
interim linecap := rounded ;
else :
interim linecap := butt ;
fi ;
save a, b ; pair a, b ;
if p_b_self = p_e_self :
a := (-distance,y_b_self+h_b_self-y) ;
b := (-distance,y_e_self-d_e_self-y) ;
elseif RealPageNumber = p_b_self :
a := (-distance,y_b_self+h_b_self-y) ;
b := (-distance,0) ;
elseif RealPageNumber = p_e_self :
a := (-distance,h) ;
b := (-distance,y_e_self-d_e_self-y) ;
else :
a := (-distance,h) ;
b := (-distance,0) ;
fi ;
a := (xpart a, min(ypart a + topoffset, h)) ;
b := (xpart b, max(ypart b - bottomoffset,0)) ;
if alternative = 2 :
draw_pattern_bar( a, b, ((0,0)--(0.25,-0.5)--(0.75,0.5)--(1,0)), 2pt, 2pt, linewidth, linecolor ) ;
elseif alternative = 3 :
draw_pattern_bar( a, b, ((0,0)--(0.25,-0.5)--(0.75,0.5)--(1,0)), 4pt, 1.5pt, linewidth, linecolor ) ;
elseif alternative = 4 :
draw_pattern_bar( a, b, ( ((0,0) .. controls (0,0.5) and (0.5,0.5) .. (0.5,0)) -- ((0.5,0) .. controls (0.5,-0.5) and (1,-0.5) .. (1,0)) ), 6pt, 4pt, linewidth, linecolor ) ;
elseif alternative = 5 :
draw_pattern_bar( a, b, ( (0,0) .. controls (0,1) and (1,1) .. (1,0) ), 4pt, 2pt, linewidth, linecolor ) ;
elseif alternative = 6 :
draw_pattern_bar( a, b, ( (0,0.5) .. (1,-0.5) ), 4pt, 2pt, linewidth, linecolor ) ;
else :
draw
a -- b
if alternative = 1 :
dashed (withdots scaled (linewidth/2))
fi
withpen pencircle scaled linewidth
withcolor linecolor ;
fi ;
endgroup ;
enddef ;
\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
Here the text between \type{\startsidebar[...]} and \type{\stopsidebar} has been colored in blue.\par
\blank}
\starttext
\hsize=4cm
\samplewithbar{zigzag1}
\samplewithbar{zigzag2}
\samplewithbar{wave1}
\samplewithbar{wave2}
\samplewithbar{obliquedashes}
\stoptext
</context>
The metapost macro `draw_pattern_bar` draws a repeating `pattern` along the bar length.
The pattern is a sort of waveform defined with a path from (0,0) to (1,0).
Its bounding box should have a height of 1, so that the base waveform has amplitude 1.
The length of the pattern and its "amplitude" are magnified
according to `patternlength` and `patternheight`.</cd:example></cd:examples>
<cd:notes></cd:notes>
<cd:seealso>
<cd:commandref name="definesidebar" originator="system"></cd:commandref>
<cd:source file="anch-bar.mkiv" originator="system"></cd:source>
<cd:wikipage originator="system" page="Category:Rules"></cd:wikipage>
<cd:source file="mp-apos.mpiv"></cd:source></cd:seealso>
</cd:commandgroup>
<cd:shortdesc><!-- a short command summary goes here -->
The command <tt>\setupsidebar</tt> is used to customize vertical bars.
They 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 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:arguments>
<cd:keywords list="yes" optional="yes" ordinal="1">
<cd:keywordsdoc></cd:keywordsdoc>
<cd:constant type="cd:name"></cd:constant>
</cd:keywords>
<cd:assignments list="yes" ordinal="2">
<cd:assignmentsdoc></cd:assignmentsdoc>
<cd:parameter name="rulethickness">
<cd:paramdoc>thickness of the bar, i.e. 1pt</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="rulecolor">
<cd:paramdoc>the bar's color</cd:paramdoc>
<cd:constant type="cd:color"></cd:constant>
</cd:parameter>
<cd:parameter name="alternative">
<cd:paramdoc>a number specifying the style of the bar (currently 0=solid bar, 1=dashed bar)</cd:paramdoc>
<cd:constant type="cd:number">0 = solid bar
1 = dashed bar</cd:constant>
</cd:parameter>
<cd:parameter name="topoffset">
<cd:paramdoc>offset to start drawing the bar, from the top of the first line of text between `\startsidebar...\stopsidebar`</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="bottomoffset">
<cd:paramdoc>offset to stop drawing the bar from the bottom of the last line of text between `\startsidebar...\stopsidebar`</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="distance">
<cd:paramdoc>the distance from the left edge of the text or from the previous bar, in case of nested `\startsidebar...\stopsidebar`</cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="leftmargindistance">
<cd:paramdoc></cd:paramdoc>
<cd:constant type="cd:dimension"></cd:constant>
</cd:parameter>
<cd:parameter name="level">
<cd:paramdoc></cd:paramdoc>
<cd:constant type="cd:number"></cd:constant>
</cd:parameter>
</cd:assignments>
</cd:arguments>
</cd:command>
</cd:variants>
<cd:description><!-- the long description of the command goes here -->
</cd:description>
<cd:examples><cd:example title="A simple side bar"><context source="yes" text="produces">
\definesidebar[simple][rulethickness=1pt,distance=3pt]
\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.\par
\stoptext
</context></cd:example><cd:example title="Custom fancy sidebars">You can define fancy, zig zag bars redefining the `anch_sidebars_draw` macro:
<context source="yes">
\definesidebar[zigzag1][rulecolor=black,distance=4pt,rulethickness=1pt,alternative=2]
\definesidebar[zigzag2][rulecolor=red,distance=4pt,rulethickness=1pt,alternative=3]
\definesidebar[wave1][rulecolor=blue,distance=4pt,rulethickness=1pt,alternative=4]
\definesidebar[wave2][rulecolor=cyan,distance=4pt,rulethickness=1pt,alternative=5]
\definesidebar[obliquedashes][rulecolor=darkgreen,distance=4pt,rulethickness=1pt,alternative=6]
\startMPcode
% draws a bar repeating a pattern defined from (0,0) to (0,1)
def draw_pattern_bar(expr a, b, pattern, patternlength, patternheight, linewidth, linecolor) =
draw image (
begingroup ;
save p, q, stp ;
pair p, q, stp ;
stp := ( ( b - a ) / arclength( a -- b ) ) * patternlength ;
path q ; q := pattern xscaled patternlength yscaled patternheight rotated (angle(stp)) ;
p := a ;
forever :
draw
q shifted p
withpen pencircle scaled linewidth
withcolor linecolor ;
p := p + stp ;
exitif arclength( a -- p ) > arclength( a -- b ) ;
endfor ;
endgroup ;
clip currentpicture to
(xpart llcorner currentpicture, ypart b) --
(xpart lrcorner currentpicture, ypart b) --
(xpart urcorner currentpicture, ypart a) --
(xpart ulcorner currentpicture, ypart a) -- cycle ;
) ;
enddef ;
% modified from metapost/context/base/mpiv/mp-apos.mpiv to add alternatives
def anch_sidebars_draw (expr p_b_self, p_e_self, y_b_self, y_e_self, h_b_self, d_e_self,
x, y, w, h, alternative, distance, linewidth, linecolor, topoffset, bottomoffset) =
% beware, we anchor at (x,y)
begingroup ;
if alternative = 1 :
interim linecap := rounded ;
else :
interim linecap := butt ;
fi ;
save a, b ; pair a, b ;
if p_b_self = p_e_self :
a := (-distance,y_b_self+h_b_self-y) ;
b := (-distance,y_e_self-d_e_self-y) ;
elseif RealPageNumber = p_b_self :
a := (-distance,y_b_self+h_b_self-y) ;
b := (-distance,0) ;
elseif RealPageNumber = p_e_self :
a := (-distance,h) ;
b := (-distance,y_e_self-d_e_self-y) ;
else :
a := (-distance,h) ;
b := (-distance,0) ;
fi ;
a := (xpart a, min(ypart a + topoffset, h)) ;
b := (xpart b, max(ypart b - bottomoffset,0)) ;
if alternative = 2 :
draw_pattern_bar( a, b, ((0,0)--(0.25,-0.5)--(0.75,0.5)--(1,0)), 2pt, 2pt, linewidth, linecolor ) ;
elseif alternative = 3 :
draw_pattern_bar( a, b, ((0,0)--(0.25,-0.5)--(0.75,0.5)--(1,0)), 4pt, 1.5pt, linewidth, linecolor ) ;
elseif alternative = 4 :
draw_pattern_bar( a, b, ( ((0,0) .. controls (0,0.5) and (0.5,0.5) .. (0.5,0)) -- ((0.5,0) .. controls (0.5,-0.5) and (1,-0.5) .. (1,0)) ), 6pt, 4pt, linewidth, linecolor ) ;
elseif alternative = 5 :
draw_pattern_bar( a, b, ( (0,0) .. controls (0,1) and (1,1) .. (1,0) ), 4pt, 2pt, linewidth, linecolor ) ;
elseif alternative = 6 :
draw_pattern_bar( a, b, ( (0,0.5) .. (1,-0.5) ), 4pt, 2pt, linewidth, linecolor ) ;
else :
draw
a -- b
if alternative = 1 :
dashed (withdots scaled (linewidth/2))
fi
withpen pencircle scaled linewidth
withcolor linecolor ;
fi ;
endgroup ;
enddef ;
\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
Here the text between \type{\startsidebar[...]} and \type{\stopsidebar} has been colored in blue.\par
\blank}
\starttext
\hsize=4cm
\samplewithbar{zigzag1}
\samplewithbar{zigzag2}
\samplewithbar{wave1}
\samplewithbar{wave2}
\samplewithbar{obliquedashes}
\stoptext
</context>
The metapost macro `draw_pattern_bar` draws a repeating `pattern` along the bar length.
The pattern is a sort of waveform defined with a path from (0,0) to (1,0).
Its bounding box should have a height of 1, so that the base waveform has amplitude 1.
The length of the pattern and its "amplitude" are magnified
according to `patternlength` and `patternheight`.</cd:example></cd:examples>
<cd:notes></cd:notes>
<cd:seealso>
<cd:commandref name="definesidebar" originator="system"></cd:commandref>
<cd:source file="anch-bar.mkiv" originator="system"></cd:source>
<cd:wikipage originator="system" page="Category:Rules"></cd:wikipage>
<cd:source file="mp-apos.mpiv"></cd:source></cd:seealso>
</cd:commandgroup>
