188
edits
Changes
Jump to navigation
Jump to search
follow up of this thread http://archive.contextgarden.net/message/20120611.213208.62aa59bf.en.html
If ConTeXt appears to behave in a counterintuitive way, chances are
that it’s actually your intuitions that lack calibration.
== Controlling Page Break Before Headings ==
If you add the option <code>page=yes</code> to a heading setup, this
will cause ConTeXt to break the page.
Ordinarily this works as expected, unless, however, the heading
immediately follows a previous section with no text in between.
The rationale behind this is that consecutive headings are conceived of
collectively as one single structural element.
For example, the following code will generate only a single page
break although the unit {{cmd|section}} appears twice.
<texcode>
\setuphead[section][page=yes] %% toggle page breaking
\starttext
\chapter{foo} %% structural inhibits breaking
\section{bar} \input knuth %% -> no break!
\section{baz} \input dawkins %% -> break
\stoptext
</texcode>
In order to get the page break at the section regardless of surrounding
structurals elements, you need to ''unset'' the heading parameter
<code>continue</code> as well.
[http://archive.contextgarden.net/message/20080107.115201.ca26c682.en.html]
<texcode>
\setuphead[section][page=yes,continue=no]
\starttext
\chapter{foo}
\section{bar} \input knuth %% -> break
\section{baz} \input dawkins %% -> break
\stoptext
</texcode>
(For the curious, the explanation can be found in the definition of the
macro {{cmd|\strc_sectioning_handle_page_nop}} in {{src|strc-sec.mkiv}}).
== Unsolicited Vertical Mode ==
Some commands like {{cmd|framed}} cause line breaks to happen if used
in vertical mode, e.g. at the beginning of a line.
Example:
<context source="yes">
\starttext
\framed{foo} bar.
\stoptext
</context>
The explanation according to the corresponding
[http://wiki.contextgarden.net/FAQ#Why_is_there_a_line-break_in_the_output_after_some_commands.3F FAQ item]
is that before the token <code>\frame</code> is encountered, TEX is
in vertical mode.
This state is ''preserved until after TEX finishes typesetting the
<code>\framed</code> macro''.
Consequently, horizontal mode (where paragraphs are made) is entered
only at the tokens <code>bar</code>.
To have the frame begin the paragraph instead, horizontal mode will
have to be initiated explicitly.
There are a couple macros for this purpose: the very basic
{{cmd|leavevmode}} ({{src|syst-ini.mkiv}}; inserts an empty box, same
as in the Plain format) and the more familiar {{cmd|dontleavehmode}}
({{src|syst-aux.mkiv}}).
Just use the immediately before the <code>\framed</code> macro and
everything should be fine:
<context source="yes">
\starttext
\leavevmode \framed{foo} bar.\par
\dontleavehmode \framed{foo} bar.
\stoptext
</context>
== Disappearing Crop Marks ==
Crop marks, activated as <code>\setuplayout[marking=on]</code>, are a
useful feature that Context supports out of the box.
They have a peculiarity, though, which my make them useless in specific
cases: They are, by definition, located ''outside the page dimension''.
This means that they show up iff the paper size exceeds the page size.
Thus if you need auxiliary lines for cutting but have the pages fit the
paper size exactly, you can instead resort to enabling the '''page
background frame'''.
This example sums up the solutions posted by Wolfgang and Marco on
[http://archive.contextgarden.net/message/20120605.202113.0989aa34.en.html
the Context Mailing List].
<texcode>
%% the paper size will be a multiple of the page sizes
\setuppapersize [A6,landscape] [A3]
\setuplayout [nx=2,ny=4]%, marking=on]
%% enable the page frame
\setupbackgrounds [page] [frame=on]
%% some further display setups
\setuppagenumbering [location=]
\setupbackgrounds [page] [background=color, backgroundcolor=gray]
\setupbodyfont [sans,58pt]
%% testing ...
\starttext
\dorecurse{4}
{\null\vfill\centerline\recurselevel\vfill\null\page}
\stoptext
</texcode>
== Left and Right ==
When it comes to the justification of paragraphs, do not trust your
intuitions about ''handedness''.
This is a [[Right_and_left|FAQ item]].
== Footnotes: The Difference between {{cmd|setupnotation}} and {{cmd|setupnote}} ==
There is a bit of terminology mess concerning notes.
<!-- I really loathe the wikitext table syntax. -->
{|cellpadding="10" style="border:2px solid #addeff"
! style="background:#addeff;" | Instruction !! Goal
|-
| {{cmd|setupnotation}}
| This command configures the '''note insert''', i.e. the textual content that will usually be placed at the bottom (with footnotes) or the end of the text (with endnotes). (The control sequence used to be <code>\setupnotedefinition</code>.)
|-
| {{cmd|setupnote}}
| Configure the '''note environment''' where the inserts will be located. Inherits some parameters from {{cmd|framed}}.
|-
| <code>\setupnote[textstyle=,textcommand=]</code>
| Configure the '''note symbol''' as appears in the main text, where the note macro is called.
|-
| Plural forms {{cmd|setupnotes}}, {{cmd|setupnotations}}
| These are synonyms for their singular forms.
|-
| {{cmd|setupfootnotes}}
| This is equivalent to <code>\setupnote[footnote]</code>.
|}
''Summary'':
to setup a blue note, you would first need to define and configure the
insert via {{cmd|setupnotation}}:
<texcode>
\definenote [bluenote] [footnote]
\setupnotation [bluenote] [
color=blue,
style=bf,
]
\starttext foo\bluenote{bar} baz \stoptext
</texcode>
Now adjust the container where the blue notes will reside at the bottom
of the page ({{cmd|setupnote}}):
<texcode>
\definenote [bluenote] [footnote]
\setupnote [bluenote] [
frame=on, %% frame containing all inserts
framecolor=blue,
background=screen,
rulecolor=blue, %% the line above the inserts
rulethickness=1pt, %% both the frame and line width
]
\starttext foo\bluenote{bar} baz \bluenote{xyzzy} \stoptext
</texcode>
Finally, direct your attention to the note indicator, most commonly a
number or a symbol.
For precise control over the placement define a monadic macro and hook
it into <code>textcommand</code>.
<texcode>
\setupnote [bluenote] [
textstyle=\tx\sans\bold\blue,
textcommand=\myfootnotecommand,
]
\define[1]\myfootnotecommand{\rotate[rotation=42]{#1}}
\starttext foo\bluenote{bar} baz \bluenote{xyzzy} \stoptext
</texcode>
(For more definite answers concerning the ''notes'' mechanism, use the
source, Luke: {{src|strc-not.mkvi}}.)
== Float Insertion Issues ==
Floating objects can be tricky.
Deciding where they fit best is hard enough, actually getting them
there may be a lot tougher.
Inserting a float will force a line break where the object is
referenced in the source code.
Thus, very long paragraphs may not leave an opportunity to inject the
float if they cover the entire page.
[http://archive.contextgarden.net/message/20120405.103626.a1349c1c.en.html]
<texcode>
\starttext
Cows make
\placefigure[top]{A genuine Dutch cow.}{\externalfigure[cow]}
great pets.
\stoptext
</texcode>
In these cases the ''postponing mechanism'' offers a reliable way out
({{cmd|startpostponing}}).
It lets you specify an offset (in pages) by which the content of the
postponing environment will be delayed.
In order to place a floating object at the top of the ''n''th page from
the location it is encountered, its argument has needs to be
<code>[+n]</code>.
(Absolute pages can be specified as simply <code>[n]</code>.)
E. g. to put the foat on the following page:
<texcode>
\starttext
\startpostponing[+1]
\placefigure[top]{A genuine Dutch cow.}{\externalfigure[cow.pdf]}
\stoppostponing
\input knuth
\page
Cows make great pets.
\stoptext
</texcode>
Another solution can be the less known ''hangaround environment''
({{cmd|starthangaround}}, cf.
[[Using_Graphics#Flow_text_around_a_picture|Hangaround]]).
It lets the text of a given paragraph (the content of the environment)
flow around a box (the first argument).
In contrast to real floats it does not place a caption.
This poses a problem in MkIV as the new code will not allow placing
captions arbitrarily.
[[http://repo.or.cz/w/context.git/blob/refs/heads/origin:/tex/context/base/strc-flt.mkvi#l257]]
(If you desparately need separate captions please send a feature
request to one of the
[[ConTeXt_Mailing_Lists#Mailing Lists]]).
<context source="yes" mode="mkii">
\starttext
\input dawkins
\starthangaround{
\framed[align=right,frame=off,width=.3\textwidth]{
\externalfigure [cow] [width=.3\textwidth]\crlf
%% NB the fake caption works *only in mkii*
\placefloatcaption
[figure]
[ref:acow]
{A smiling Dutch cow.
{\italic Bos primigenius taurus}}
}
}
\input dawkins
\stophangaround
\input dawkins
\stoptext
</context>
= Syntax =
== Assignments ==
In the most common form of key-value type arguments, ConTeXt will
accept trailing commas or even empty items. For example, the following
code shows this tolerance for the command {{cmd|definehighlight}}.
<texcode>
\definehighlight [dontmiss] [
color=red,
,, %% empty option: do nothing
style=bold, %% trailing delimiter
]
</texcode>
This is the syntax accepted e.g. by the majority of setups and
[[Commands_with_KeyVal_arguments|<code>\getparameters</code>]].
(For the parser code cf. {{src|syst-aux.mkiv}}.)
There are, however, exceptions to this rule. A known case where
options are processed in a less tolerant fashion is
{{cmd|setuplabeltext}}.
[http://www.ntg.nl/pipermail/ntg-context/2012/067585.html]
Thus the following snippet will not compile, forcing ConTeXt to fail
with a cryptic <code>Argument of ...</code> error message.
<texcode>
\setuplabeltext
[Nomen=nomen,
Est=est,
Omen=est,] %% <= fails!
\setuplabeltext [Nomen=nomen, Est=est, Omen=omen] %% <= works
\starttext
\labeltext{Nomen}
\labeltext{Est}
\labeltext{Omen}
\stoptext
</texcode>
(A similar exception concerning {{cmd|definepalet}} has been migrated
to the standard argument model but may still show the earlier behavior
in not so recent installations.
[http://www.ntg.nl/pipermail/ntg-context/2012/067673.html])
<!--
== \usepath ==
Hans announced this one can be expected to be unified in the near
future.
[http://archive.contextgarden.net/message/20110929.151806.3ad6fbdd.en.html]
What’s the status of this?
-->
/context>
== Disappearing Crop Marks ==
Crop marks, activated as
that it’s actually your intuitions that lack calibration.
== Controlling Page Break Before Headings ==
If you add the option <code>page=yes</code> to a heading setup, this
will cause ConTeXt to break the page.
Ordinarily this works as expected, unless, however, the heading
immediately follows a previous section with no text in between.
The rationale behind this is that consecutive headings are conceived of
collectively as one single structural element.
For example, the following code will generate only a single page
break although the unit {{cmd|section}} appears twice.
<texcode>
\setuphead[section][page=yes] %% toggle page breaking
\starttext
\chapter{foo} %% structural inhibits breaking
\section{bar} \input knuth %% -> no break!
\section{baz} \input dawkins %% -> break
\stoptext
</texcode>
In order to get the page break at the section regardless of surrounding
structurals elements, you need to ''unset'' the heading parameter
<code>continue</code> as well.
[http://archive.contextgarden.net/message/20080107.115201.ca26c682.en.html]
<texcode>
\setuphead[section][page=yes,continue=no]
\starttext
\chapter{foo}
\section{bar} \input knuth %% -> break
\section{baz} \input dawkins %% -> break
\stoptext
</texcode>
(For the curious, the explanation can be found in the definition of the
macro {{cmd|\strc_sectioning_handle_page_nop}} in {{src|strc-sec.mkiv}}).
== Unsolicited Vertical Mode ==
Some commands like {{cmd|framed}} cause line breaks to happen if used
in vertical mode, e.g. at the beginning of a line.
Example:
<context source="yes">
\starttext
\framed{foo} bar.
\stoptext
</context>
The explanation according to the corresponding
[http://wiki.contextgarden.net/FAQ#Why_is_there_a_line-break_in_the_output_after_some_commands.3F FAQ item]
is that before the token <code>\frame</code> is encountered, TEX is
in vertical mode.
This state is ''preserved until after TEX finishes typesetting the
<code>\framed</code> macro''.
Consequently, horizontal mode (where paragraphs are made) is entered
only at the tokens <code>bar</code>.
To have the frame begin the paragraph instead, horizontal mode will
have to be initiated explicitly.
There are a couple macros for this purpose: the very basic
{{cmd|leavevmode}} ({{src|syst-ini.mkiv}}; inserts an empty box, same
as in the Plain format) and the more familiar {{cmd|dontleavehmode}}
({{src|syst-aux.mkiv}}).
Just use the immediately before the <code>\framed</code> macro and
everything should be fine:
<context source="yes">
\starttext
\leavevmode \framed{foo} bar.\par
\dontleavehmode \framed{foo} bar.
\stoptext
</context>
== Disappearing Crop Marks ==
Crop marks, activated as <code>\setuplayout[marking=on]</code>, are a
useful feature that Context supports out of the box.
They have a peculiarity, though, which my make them useless in specific
cases: They are, by definition, located ''outside the page dimension''.
This means that they show up iff the paper size exceeds the page size.
Thus if you need auxiliary lines for cutting but have the pages fit the
paper size exactly, you can instead resort to enabling the '''page
background frame'''.
This example sums up the solutions posted by Wolfgang and Marco on
[http://archive.contextgarden.net/message/20120605.202113.0989aa34.en.html
the Context Mailing List].
<texcode>
%% the paper size will be a multiple of the page sizes
\setuppapersize [A6,landscape] [A3]
\setuplayout [nx=2,ny=4]%, marking=on]
%% enable the page frame
\setupbackgrounds [page] [frame=on]
%% some further display setups
\setuppagenumbering [location=]
\setupbackgrounds [page] [background=color, backgroundcolor=gray]
\setupbodyfont [sans,58pt]
%% testing ...
\starttext
\dorecurse{4}
{\null\vfill\centerline\recurselevel\vfill\null\page}
\stoptext
</texcode>
== Left and Right ==
When it comes to the justification of paragraphs, do not trust your
intuitions about ''handedness''.
This is a [[Right_and_left|FAQ item]].
== Footnotes: The Difference between {{cmd|setupnotation}} and {{cmd|setupnote}} ==
There is a bit of terminology mess concerning notes.
<!-- I really loathe the wikitext table syntax. -->
{|cellpadding="10" style="border:2px solid #addeff"
! style="background:#addeff;" | Instruction !! Goal
|-
| {{cmd|setupnotation}}
| This command configures the '''note insert''', i.e. the textual content that will usually be placed at the bottom (with footnotes) or the end of the text (with endnotes). (The control sequence used to be <code>\setupnotedefinition</code>.)
|-
| {{cmd|setupnote}}
| Configure the '''note environment''' where the inserts will be located. Inherits some parameters from {{cmd|framed}}.
|-
| <code>\setupnote[textstyle=,textcommand=]</code>
| Configure the '''note symbol''' as appears in the main text, where the note macro is called.
|-
| Plural forms {{cmd|setupnotes}}, {{cmd|setupnotations}}
| These are synonyms for their singular forms.
|-
| {{cmd|setupfootnotes}}
| This is equivalent to <code>\setupnote[footnote]</code>.
|}
''Summary'':
to setup a blue note, you would first need to define and configure the
insert via {{cmd|setupnotation}}:
<texcode>
\definenote [bluenote] [footnote]
\setupnotation [bluenote] [
color=blue,
style=bf,
]
\starttext foo\bluenote{bar} baz \stoptext
</texcode>
Now adjust the container where the blue notes will reside at the bottom
of the page ({{cmd|setupnote}}):
<texcode>
\definenote [bluenote] [footnote]
\setupnote [bluenote] [
frame=on, %% frame containing all inserts
framecolor=blue,
background=screen,
rulecolor=blue, %% the line above the inserts
rulethickness=1pt, %% both the frame and line width
]
\starttext foo\bluenote{bar} baz \bluenote{xyzzy} \stoptext
</texcode>
Finally, direct your attention to the note indicator, most commonly a
number or a symbol.
For precise control over the placement define a monadic macro and hook
it into <code>textcommand</code>.
<texcode>
\setupnote [bluenote] [
textstyle=\tx\sans\bold\blue,
textcommand=\myfootnotecommand,
]
\define[1]\myfootnotecommand{\rotate[rotation=42]{#1}}
\starttext foo\bluenote{bar} baz \bluenote{xyzzy} \stoptext
</texcode>
(For more definite answers concerning the ''notes'' mechanism, use the
source, Luke: {{src|strc-not.mkvi}}.)
== Float Insertion Issues ==
Floating objects can be tricky.
Deciding where they fit best is hard enough, actually getting them
there may be a lot tougher.
Inserting a float will force a line break where the object is
referenced in the source code.
Thus, very long paragraphs may not leave an opportunity to inject the
float if they cover the entire page.
[http://archive.contextgarden.net/message/20120405.103626.a1349c1c.en.html]
<texcode>
\starttext
Cows make
\placefigure[top]{A genuine Dutch cow.}{\externalfigure[cow]}
great pets.
\stoptext
</texcode>
In these cases the ''postponing mechanism'' offers a reliable way out
({{cmd|startpostponing}}).
It lets you specify an offset (in pages) by which the content of the
postponing environment will be delayed.
In order to place a floating object at the top of the ''n''th page from
the location it is encountered, its argument has needs to be
<code>[+n]</code>.
(Absolute pages can be specified as simply <code>[n]</code>.)
E. g. to put the foat on the following page:
<texcode>
\starttext
\startpostponing[+1]
\placefigure[top]{A genuine Dutch cow.}{\externalfigure[cow.pdf]}
\stoppostponing
\input knuth
\page
Cows make great pets.
\stoptext
</texcode>
Another solution can be the less known ''hangaround environment''
({{cmd|starthangaround}}, cf.
[[Using_Graphics#Flow_text_around_a_picture|Hangaround]]).
It lets the text of a given paragraph (the content of the environment)
flow around a box (the first argument).
In contrast to real floats it does not place a caption.
This poses a problem in MkIV as the new code will not allow placing
captions arbitrarily.
[[http://repo.or.cz/w/context.git/blob/refs/heads/origin:/tex/context/base/strc-flt.mkvi#l257]]
(If you desparately need separate captions please send a feature
request to one of the
[[ConTeXt_Mailing_Lists#Mailing Lists]]).
<context source="yes" mode="mkii">
\starttext
\input dawkins
\starthangaround{
\framed[align=right,frame=off,width=.3\textwidth]{
\externalfigure [cow] [width=.3\textwidth]\crlf
%% NB the fake caption works *only in mkii*
\placefloatcaption
[figure]
[ref:acow]
{A smiling Dutch cow.
{\italic Bos primigenius taurus}}
}
}
\input dawkins
\stophangaround
\input dawkins
\stoptext
</context>
= Syntax =
== Assignments ==
In the most common form of key-value type arguments, ConTeXt will
accept trailing commas or even empty items. For example, the following
code shows this tolerance for the command {{cmd|definehighlight}}.
<texcode>
\definehighlight [dontmiss] [
color=red,
,, %% empty option: do nothing
style=bold, %% trailing delimiter
]
</texcode>
This is the syntax accepted e.g. by the majority of setups and
[[Commands_with_KeyVal_arguments|<code>\getparameters</code>]].
(For the parser code cf. {{src|syst-aux.mkiv}}.)
There are, however, exceptions to this rule. A known case where
options are processed in a less tolerant fashion is
{{cmd|setuplabeltext}}.
[http://www.ntg.nl/pipermail/ntg-context/2012/067585.html]
Thus the following snippet will not compile, forcing ConTeXt to fail
with a cryptic <code>Argument of ...</code> error message.
<texcode>
\setuplabeltext
[Nomen=nomen,
Est=est,
Omen=est,] %% <= fails!
\setuplabeltext [Nomen=nomen, Est=est, Omen=omen] %% <= works
\starttext
\labeltext{Nomen}
\labeltext{Est}
\labeltext{Omen}
\stoptext
</texcode>
(A similar exception concerning {{cmd|definepalet}} has been migrated
to the standard argument model but may still show the earlier behavior
in not so recent installations.
[http://www.ntg.nl/pipermail/ntg-context/2012/067673.html])
<!--
== \usepath ==
Hans announced this one can be expected to be unified in the near
future.
[http://archive.contextgarden.net/message/20110929.151806.3ad6fbdd.en.html]
What’s the status of this?
-->
/context>
== Disappearing Crop Marks ==
Crop marks, activated as
