Changes

ConTeXt has a very logical structure. It has five basic notational conventions: there are two basic rules of syntax and three basic principles of organization.

Two rules of syntax:# '''Square Brackets Rulesquare brackets''': Enclose arguments to ConTeXt commands in [ ].# '''Curly Braces Rulecurly braces''': Use { } as delimiters to group text as a single self-contained unit.# '''start-stop''': To apply ''something'' to some text, enclose the text in {{code|\start''something''}} {{code|\stop''something''}}.# '''setup''': To configure ''something'', use {{code|\setup''something''}}.# '''define''': To create a named customization of ''something'', use {{code|\define''something''}}.

Three principles of organization:# '''Applying Principle'''== A minimal example: To apply ''something'' to some text, enclose the text in {{code|\start''something''}} {{code|\-stop''something''}}.# '''Configuring Principle''': To configure and ''something'', use {{code|\setup''something''}}.# '''Creating Principle''': To create a named customization of ''something'', use {{code|\define''something''}}. == A minimal example: the Applying and Configuring Principles notation ==To see how these rules and principles worknotational conventions get used, let’s start with a minimal example of a ConTeXt document:

Compiling this document typesets a built-in quotation from Knuth, which is inserted with {{code|\input knuth}}. (Throughout the ConTeXt documentation, you'll find this and other similarly built-in texts used to illustrate examples.) You can already see the Applying Principle start-stop at work: the usual way of processing the entire text of the document is named {{code|text}}, so to apply it you enclose the document text in {{cmd|starttext}} {{cmd|stoptext}}.

This is in keeping with example uses the Configuring Principle''setup'' notation. The way that paper is sized for a document in ConTeXt is called {{code|papersize}}, so you use {{cmd|setuppapersize}} to configure it. The use of [ ] to enclose the argument is in keeping with an example of the Square Brackets Rule''square brackets'' notation.

Another thing you might like to change is the page numbering. By default, ConTeXt places a page number at the center of the top of the page. To put it at the center of the bottom of the page instead, you can use {{cmd|setuppagenumbering|2=[location{{=}}bottom]}}.

This is another example of the Configuring Principle''setup'' notation. The way that pages are numbered in ConTeXt is called {{code|pagenumbering}}, so you use {{cmd|setuppagenumbering}} to configure it. The And the use of [ ] to enclose the argument is in keeping with another example of the Square Brackets Rule''square brackets'' notation.

The Configuring Principle ''setup'' notation is being applied used here again. The way that paragraphs are indented in a ConTeXt is called {{code|indenting}}, so you use {{cmd|setupindenting}} to configure it. The use of [ ] to enclose the arguments is again in keeping with the Square Brackets Rule''square brackets'' notation.

== Another example: The Creating Principle ''define'' notation ==Let’s look at another example. Suppose you have a ConTeXt document, and you want to place a box with rounded corners around some text. The way to place boxes around text in ConTeXt is called {{code|framed}}, so (in keeping with the Applying Principle) to apply that type of formatting you enclose the text in {{cmd|startframed}} {{cmd|stopframed}}. Since you want rounded corners, you specify the argument {{code|1=corner{{=}}round}} for rounded corners too:

As you can see, you put the arguments in according to with the Square Brackets Rule''square brackets'' notation. But what if you want to make this configuration the default for ''all'' of your frames in the document? You can use the Configuring Principle ''setup'' notation for this. The command {{cmd|setupframed|[corner=round]}} will make this the default configuration for the rest of the document:

But what if you want to have two types of frames, one with rounded corners and one without, and you'll be using both of them lots of times? This is where the Creating Principle ''define'' notation comes in. You can use {{cmd|defineframed}} twice to define two meaningfully named configurations (say {{code|definitionFrame}} with rectangular corners and {{code|exampleFrame}} with rounded corners) that you can refer to throughout your document:

== Example: the Curly Braces Rule ''curly braces'' notation ==You have now seen examples of how four of the three basic Principles can be applied in ConTeXt, and five notational conventions listed above: all of how the Square Brackets Rule can be applied, but we haven’t yet looked at them except the Curly Braces Rule''curly braces'' notation.

To see one way that the Curly Braces Rule ''curly braces'' notation is used, note that enclosing text in {{cmd|startframed}} {{cmd|stopframed}} is not the only way to put a box around text. Another way, which is really just syntactic sugar for the same thing, is to used the {{cmd|framed}} command. This will put a box around the next single unit following it (ignoring whitespace). For example:

This is an example of how the Curly Braces Rule ''curly braces'' notation is used in ConTeXt. In order to delimit the single unit that follows it, you use { }. Although many of ConTeXt's commands involve {{code|start}}, {{code|stop}}, {{code|setup}}, or {{code|define}}, a fair number of them instead operate on the single unit following them, as {{cmd|framed}} does. Some, like {{cmd|framed}}, allow you to use either syntax.

One way to get around this problem is to apply the Curly Brace Rule''curly braces'' notation: enclose the title in { } so that ConTeXt will treat the title text as a single unit. Then it works just fine: 

Naturally not everything in ConTeXt can be derived from is written using these two basic Rules and three basic Principlesfive notational conventions. There are many further notational details to learn in order to implement them, and not everything in ConTeXt is completely consistent with these Rules and Principlesconventions. However, the design of ConTeXt really is remarkably if not entirely consistent with at least highly consistent in using these Rules and Principlesconventions, so they serve as a useful guide when you are trying to figure out how best to use the powerful tools that ConTeXt offers.

== Some commands that use these principles this notation ==