Difference between revisions of "Command Syntax"
(New page on command syntax (not finished yet)) |
m (Text replacement - "pragma-ade.com" to "pragma-ade.nl") |
||
(13 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
− | '''WARNING: this page has to be finished | + | '''WARNING: this page has to be finished first, than reviewed! Don't rely on actual information.''' |
− | + | == Command == | |
− | + | \command{the command works with its parameter(s)} | |
+ | |||
+ | Command consists of: | ||
+ | <!-- table --> | ||
+ | {| | ||
+ | |- | ||
+ | | <code>\</code> || leading backslash | ||
+ | |- | ||
+ | | <code>name</code> || command name | ||
+ | |- | ||
+ | | <code>{ }</code> || scope or range of the command (if applicable) | ||
+ | |- | ||
+ | | <code>[ ]</code> || setups (if applicable) | ||
+ | |- | ||
+ | | <code>$$ $$</code> || math input (if applicable) | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <pre>\placeformula[...]{...}$$...$$</pre> | ||
+ | |||
+ | == Switch == | ||
+ | |||
+ | {\switch the switch influences everything in its group} | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <pre> | ||
+ | |||
+ | {\em here is emphasized text} | ||
+ | |||
+ | </pre> | ||
+ | |||
+ | == Find definition == | ||
+ | |||
+ | There are several places where you can search for command definitions: | ||
+ | |||
+ | * [http://www.pragma-ade.nl/general/qrcs/setup-en.pdf setup-en.pdf] (and appropriate language variants) most up-to-date ConTeXt command reference (but without explanations). | ||
+ | * [http://pmrb.free.fr/contextref.pdf ConTeXt reference manual] (2013, somewhat outdated) | ||
+ | * The main source for the XML description is in [[source:tex/context/interface/mkiv/context-en.xml|context-en.xml]] | ||
+ | * The sources for the XML command descriptions for MkII: [[source:tex/context/interface/mkii|tex/context/interface/mkii]] (obsolete) | ||
− | |||
− | + | If you can't find specific option, here is an advice from mailing list how to search for them in sources: | |
− | + | <pre> | |
− | + | This is what I usually do to find out about an option. Search | |
− | + | texwebshow for options. If it is there, read the manual for the | |
− | + | description. | |
− | |||
− | + | If I do not find any relevant option, but know that ConTeXt ought to have | |
− | + | an option for what I want (which usually means that it will), look in the | |
+ | sources. My strategy for searching the sources involves finding out which | ||
+ | source file defines the option. (search on sources.contextgarden.net work | ||
+ | for most cases, I use grep for the cases which are more trickier to find). | ||
− | + | Most (all?) commands come with an accompanying \setup command, which | |
+ | initialises all the options for the command. This way, one knows at least | ||
+ | which options a command will accept. In most cases guessing the | ||
+ | functionality of an option is easy, as ConTeXt uses a consistent interface | ||
+ | for everything. | ||
+ | |||
+ | Sometimes, when I have no clue what that option does, I search where the | ||
+ | option is used. Most options are stored using \getparameters[\??xx] | ||
+ | where xx is a two letter abbreviation. Then you can search for | ||
+ | \@@xxoption to see where it is used. That way, you can usually guess what | ||
+ | an option does. | ||
+ | |||
+ | The sources also have some examples that are usually useful in | ||
+ | understanding a few tricks about the command. | ||
+ | |||
+ | If I still can not figure out, I ask on the mailing list. | ||
+ | </pre> | ||
+ | |||
+ | == Referencing of arguments == | ||
+ | |||
+ | In these sources there is different '''referencing of arguments''' to thier possible values and different '''typographic conventions'''. | ||
+ | |||
+ | Example: {{cmd|setupheadertexts}} | ||
*in the manual: | *in the manual: | ||
Line 25: | Line 89: | ||
.2. ''text'' ''section'' date ''mark'' pagenumber | .2. ''text'' ''section'' date ''mark'' pagenumber | ||
.3. ''text'' ''section'' date ''mark'' pagenumber | .3. ''text'' ''section'' date ''mark'' pagenumber | ||
− | * in the | + | * in the wiki Command pages: |
− | + | <syntax>setupheadertexts</syntax> | |
− | < | ||
− | |||
− | |||
* in the emacs help | * in the emacs help | ||
\setupheadertexts<span style='color: #00FF00'>[.1.]</span><span style='color: #FF1493'>[.2.]</span><span style='color: #6495ED'>[.3.]</span> | \setupheadertexts<span style='color: #00FF00'>[.1.]</span><span style='color: #FF1493'>[.2.]</span><span style='color: #6495ED'>[.3.]</span> | ||
Line 36: | Line 97: | ||
<span style='color: #6495ED'>.3. <text> <section> date <mark> pagenumber</span> | <span style='color: #6495ED'>.3. <text> <section> date <mark> pagenumber</span> | ||
− | == | + | == Typographic conventions == |
− | + | As you can see in in previous examples, command references have different typographic conventions. | |
− | |||
− | |||
− | |||
− | |||
− | Following table shows their notation. | + | Following table explains the meaning of values and shows their notation in different sources. |
{| border="1" | {| border="1" | ||
|- | |- | ||
− | | || | + | | || meaning || [http://www.pragma-ade.nl/general/qrcs/setup-en.pdf | setup-en.pdf] || [manual:http://pmrb.free.fr/contextref.pdf ConTeXt reference manual] || [http://texshow.contextgarden.net/ texshow-web] || [http://levana.de/emacs| etexshow] || [[source:cont-en.xml | cont-en.xml]] |
+ | |- | ||
+ | | default || x || x || x || x || x || x | ||
+ | |- | ||
+ | | predefined || x || x || x || x || x || x | ||
+ | |- | ||
+ | | user input || x || x || x || x || x || x | ||
|- | |- | ||
− | | | + | | text || x || x || x || x || x || x |
|- | |- | ||
− | | | + | | number || x || x || x || x || x || x |
|- | |- | ||
− | |||
|- | |- | ||
− | | | + | | reference || x || x || x || x || x || x |
|- | |- | ||
− | | | + | | identifier|| x || x || x || x || x || x |
|- | |- | ||
− | |key | + | | key=value pair || x || x || x || x || x || x |
|- | |- | ||
− | | | + | | triplet || x || x || x || x || x || x |
|- | |- | ||
− | |list of || x || x || x || x | + | | list of || x || x || x || x || x || x |
|- | |- | ||
− | | | + | | command || x || x || x || x || x || x |
+ | |- | ||
+ | |- | ||
+ | | ...,...,... || x || x || x || x || x || x | ||
+ | |- | ||
+ | | || x || x || x || x || x || x | ||
+ | |- | ||
+ | |- | ||
+ | | || x || x || x || x || x || x | ||
+ | |- | ||
+ | | || x || x || x || x || x || x | ||
|- | |- | ||
|} | |} | ||
− | == | + | == Other notes == |
+ | |||
+ | * In LaTeX optional arguments come before mandatory arguments. This is not true in ConTeXt. Optional argument can be at any position. | ||
+ | \definetextvariable | ||
+ | * If <code>key=value</code> pair is missing the value, than the key is assigned the default value. | ||
+ | <code>location=</code> | ||
+ | |||
+ | == This wiki == | ||
− | While writing | + | While writing on this wiki you can refer to user commands with the [[:Template:cmd|cmd]] template, like so: |
+ | <pre> | ||
+ | {{cmd|goto}} | ||
+ | or | ||
+ | {{cmd|goto|{some text}[label:1]}} | ||
+ | </pre> | ||
+ | This displays as {{cmd|goto}} or {{cmd|goto|{some text}[label:1]}}, respectively. The link leads to the command definition in [[:Category:Commands]]. | ||
== Missing commands, descriptions and examples == | == Missing commands, descriptions and examples == | ||
+ | [[Command Syntax/Missing]] | ||
− | + | [[Category:Tools]] | |
+ | [[Category:Basics]] |
Latest revision as of 08:27, 2 July 2022
WARNING: this page has to be finished first, than reviewed! Don't rely on actual information.
Contents
Command
\command{the command works with its parameter(s)}
Command consists of:
\ |
leading backslash |
name |
command name |
{ } |
scope or range of the command (if applicable) |
[ ] |
setups (if applicable) |
$$ $$ |
math input (if applicable) |
Example:
\placeformula[...]{...}$$...$$
Switch
{\switch the switch influences everything in its group}
Example:
{\em here is emphasized text}
Find definition
There are several places where you can search for command definitions:
- setup-en.pdf (and appropriate language variants) most up-to-date ConTeXt command reference (but without explanations).
- ConTeXt reference manual (2013, somewhat outdated)
- The main source for the XML description is in context-en.xml
- The sources for the XML command descriptions for MkII: tex/context/interface/mkii (obsolete)
If you can't find specific option, here is an advice from mailing list how to search for them in sources:
This is what I usually do to find out about an option. Search texwebshow for options. If it is there, read the manual for the description. If I do not find any relevant option, but know that ConTeXt ought to have an option for what I want (which usually means that it will), look in the sources. My strategy for searching the sources involves finding out which source file defines the option. (search on sources.contextgarden.net work for most cases, I use grep for the cases which are more trickier to find). Most (all?) commands come with an accompanying \setup command, which initialises all the options for the command. This way, one knows at least which options a command will accept. In most cases guessing the functionality of an option is easy, as ConTeXt uses a consistent interface for everything. Sometimes, when I have no clue what that option does, I search where the option is used. Most options are stored using \getparameters[\??xx] where xx is a two letter abbreviation. Then you can search for \@@xxoption to see where it is used. That way, you can usually guess what an option does. The sources also have some examples that are usually useful in understanding a few tricks about the command. If I still can not figure out, I ask on the mailing list.
Referencing of arguments
In these sources there is different referencing of arguments to thier possible values and different typographic conventions.
Example: \setupheadertexts
- in the manual:
\setupheadertexts[.1.][.2.][.3.] .1. text margin edge .2. text section date mark pagenumber .3. text section date mark pagenumber
- in the wiki Command pages:
\setupheadertexts[...][...][...][...][...] | |
[...] | text margin edge |
[...] | date pagenumber mark text command |
[...] | date pagenumber mark text command |
[...] | date pagenumber mark text command |
[...] | date pagenumber mark text command |
- in the emacs help
\setupheadertexts[.1.][.2.][.3.] .1. <text> margin edge .2. <text> <section> date pagenumber .3. <text> <section> date pagenumber
Typographic conventions
As you can see in in previous examples, command references have different typographic conventions.
Following table explains the meaning of values and shows their notation in different sources.
meaning | setup-en.pdf] | [manual:http://pmrb.free.fr/contextref.pdf ConTeXt reference manual] | texshow-web | etexshow] | cont-en.xml | |
default | x | x | x | x | x | x |
predefined | x | x | x | x | x | x |
user input | x | x | x | x | x | x |
text | x | x | x | x | x | x |
number | x | x | x | x | x | x |
reference | x | x | x | x | x | x |
identifier | x | x | x | x | x | x |
key=value pair | x | x | x | x | x | x |
triplet | x | x | x | x | x | x |
list of | x | x | x | x | x | x |
command | x | x | x | x | x | x |
...,...,... | x | x | x | x | x | x |
x | x | x | x | x | x | |
x | x | x | x | x | x | |
x | x | x | x | x | x |
Other notes
- In LaTeX optional arguments come before mandatory arguments. This is not true in ConTeXt. Optional argument can be at any position.
\definetextvariable
- If
key=value
pair is missing the value, than the key is assigned the default value.
location=
This wiki
While writing on this wiki you can refer to user commands with the cmd template, like so:
{{cmd|goto}} or {{cmd|goto|{some text}[label:1]}}
This displays as \goto or \goto{some text}[label:1], respectively. The link leads to the command definition in Category:Commands.