Difference between revisions of "User:Sciurus/sandbox"

From Wiki
Jump to navigation Jump to search
m (Sandboxing an intro to ConTeXt)
m (Continuing to sandbox an intro to ConTeXt.)
Line 4: Line 4:
  
 
Two rules of syntax:
 
Two rules of syntax:
 +
# '''Square Brackets Rule''': Enclose arguments to ConTeXt commands in [ ].
 
# '''Curly Braces Rule''': To group some text as a single self-contained unit, enclose the text in { }.
 
# '''Curly Braces Rule''': To group some text as a single self-contained unit, enclose the text in { }.
# '''Square Brackets Rule''': Enclose arguments to ConTeXt commands in [ ].
 
  
 
Three principles of organization:
 
Three principles of organization:
Line 12: Line 12:
 
# '''Creating Principle''': To create a named customization of ''something'', use {{code|\define''something''}}.
 
# '''Creating Principle''': To create a named customization of ''something'', use {{code|\define''something''}}.
  
== A minimal example ==
+
== A minimal example: the Applying and Configuring Principles ==
 
To see how these rules and principles work, let’s start with a minimal example of a ConTeXt document:
 
To see how these rules and principles work, let’s start with a minimal example of a ConTeXt document:
 
<texcode>
 
<texcode>
Line 50: Line 50:
 
</texcode>
 
</texcode>
 
The Configuring Principle is being applied 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.
 
The Configuring Principle is being applied 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.
 +
 +
== Another example: The Creating Principle ==
 +
Let&rsquo;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:
 +
 +
<context source="yes">
 +
\startframed[corner=round]
 +
An example of something.
 +
\stopframed
 +
</context>
 +
 +
As you can see, you put the arguments in according to the Square Brackets Rule. 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 for this. The command {{cmd|setupframed|[corner=round]}} will make this the default configuration for the rest of the document:
 +
 +
<context source="yes">
 +
\setupframed[corner=round]
 +
\startframed
 +
An example of something.
 +
\stopframed
 +
</context>
 +
 +
When you have set it up this way, you no longer have to type in the arguments every time you have a box around text. But more importantly, by making this configuration separately at the beginning of your document, you have set up a uniform style throughout your document. This makes it easy to make global style adjustments, which is a very powerful feature.
 +
 +
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 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:
 +
 +
<context source="yes">
 +
\defineframed[definitionFrame][align=flushleft]
 +
\defineframed[exampleFrame][align=flushleft, corner=round]
 +
 +
\startframed[definitionFrame]
 +
A definition of something.
 +
\stopframed
 +
 +
\startframed[exampleFrame]
 +
An example of something.
 +
\stopframed
 +
</context>
 +
 +
Now if at some later time you want to change the way that you format the frames around your definitions and examples, it is easy to do so. You just change the {{cmd|defineframed}} commands where they are set up, and the change will be applied consistently and globally to your whole document.
 +
 +
== Example: the Curly Braces Rule ==
 +
You have seen examples of how the three basic Principles can be applied in ConTeXt, and of how the Square Brackets Rule can be applied, but we haven&rsquo;t yet looked at the Curly Braces Rule.
 +
 +
To see one way that the Curly Braces Rule 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:
 +
 +
<context source="yes">
 +
\framed {An example of something}
 +
</context>
 +
 +
== Summary ==
 +
Naturally not everything in ConTeXt can be derived from these two basic Rules and three basic Principles. There are many further details to learn in order to implement them, and not everything in ConTeXt is completely consistent with these Rules and Principles. However, they serve as a useful guide, and the design of ConTeXt really is remarkably consistent with these Rules and Principles, so they serve as a useful guide when you are trying to figure out how best to use the powerful tools that ConTeXt offers.

Revision as of 18:08, 19 October 2020

LIKE EVERYTHING IN THIS SANDBOX, THIS IS ONLY A DRAFT AND SHOULD NOT BE USED YET.

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

Two rules of syntax:

  1. Square Brackets Rule: Enclose arguments to ConTeXt commands in [ ].
  2. Curly Braces Rule: To group some text as a single self-contained unit, enclose the text in { }.

Three principles of organization:

  1. Applying Principle: To apply something to some text, enclose the text in \startsomething \stopsomething.
  2. Configuring Principle: To configure something, use \setupsomething.
  3. Creating Principle: To create a named customization of something, use \definesomething.

A minimal example: the Applying and Configuring Principles

To see how these rules and principles work, let’s start with a minimal example of a ConTeXt document:

\starttext
\input knuth
\stoptext

Compiling this document typesets a built-in quotation from Knuth, which is inserted with \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 at work: the usual way of processing the entire text of the document is named text, so to apply it you enclose the document text in \starttext \stoptext.

When you compile this document, you'll probably immediately see some things that you want to change. For example, the default paper size in ConTeXt is A4. This works well for most of the world, but if you’re in the United States, you might prefer your paper size to be letter. That’s easy enough: just use \setuppapersize[letter].

\setuppapersize[letter]
\starttext
\input knuth
\stoptext

This is in keeping with the Configuring Principle. The way that paper is sized for a document in ConTeXt is called papersize, so you use \setuppapersize to configure it. The use of [ ] to enclose the argument is in keeping with the Square Brackets Rule.

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 [[Command/[location=bottom]|\[location=bottom]]].

\setuppapersize[letter]
\setuppagenumbering[location=bottom]
\starttext
\input knuth
\stoptext

This is another example of the Configuring Principle. The way that pages are numbered in ConTeXt is called pagenumbering, so you use \setuppagenumbering to configure it. The use of [ ] to enclose the argument is in keeping with the Square Brackets Rule.

You also might want to change the way that paragraphs are indented. By default, they are not indented. To make them indented by a medium amount, use \setupindenting[yes, medium]. (Here yes turns the indenting on, but by default the amount is still none, so medium is used to specify the amount.)

\setuppapersize[letter]
\setuppagenumbering[location=bottom]
\setupindenting[yes, medium]
\starttext
\input knuth
\stoptext

The Configuring Principle is being applied here again. The way that paragraphs are indented in a ConTeXt is called indenting, so you use \setupindenting to configure it. The use of [ ] to enclose the arguments is again in keeping with the Square Brackets Rule.

Another example: The Creating Principle

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 framed, so (in keeping with the Applying Principle) to apply that type of formatting you enclose the text in \startframed \stopframed. Since you want rounded corners, you specify the argument corner=round for rounded corners too:

\startframed[corner=round]
An example of something.
\stopframed

As you can see, you put the arguments in according to the Square Brackets Rule. 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 for this. The command \setupframed will make this the default configuration for the rest of the document:

\setupframed[corner=round]
\startframed
An example of something.
\stopframed

When you have set it up this way, you no longer have to type in the arguments every time you have a box around text. But more importantly, by making this configuration separately at the beginning of your document, you have set up a uniform style throughout your document. This makes it easy to make global style adjustments, which is a very powerful feature.

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 comes in. You can use \defineframed twice to define two meaningfully named configurations (say definitionFrame with rectangular corners and exampleFrame with rounded corners) that you can refer to throughout your document:

\defineframed[definitionFrame][align=flushleft]
\defineframed[exampleFrame][align=flushleft, corner=round]

\startframed[definitionFrame]
A definition of something.
\stopframed

\startframed[exampleFrame]
An example of something.
\stopframed

Now if at some later time you want to change the way that you format the frames around your definitions and examples, it is easy to do so. You just change the \defineframed commands where they are set up, and the change will be applied consistently and globally to your whole document.

Example: the Curly Braces Rule

You have seen examples of how the three basic Principles can be applied in ConTeXt, and of how the Square Brackets Rule can be applied, but we haven’t yet looked at the Curly Braces Rule.

To see one way that the Curly Braces Rule is used, note that enclosing text in \startframed \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 \framed command. This will put a box around the next single unit following it (ignoring whitespace). For example:

\framed {An example of something}

Summary

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