User:Sciurus/sandbox

From Wiki
< User:Sciurus
Revision as of 16:44, 21 October 2020 by Sciurus (talk | contribs) (Tweaking an Intro to ConTeXt)
Jump to navigation Jump to search

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

An introduction to ConTeXt =

ConTeXt has a very logical structure. Once you are familiar with its basic underlying principles, you will find that many of its commands seem quite natural.

start-stop, setup, and define

There are three main types of commands in ConTeXt:

  1. start-stop: To apply something to some text, enclose the text in \startsomething \stopsomething.
  2. setup: To configure something, use \setupsomething.
  3. define: To create a named customization of something, use \definesomething.

The usual way to use these types of commands is as follows. If you want to apply something (such as formatting) to text, enclose the text in \startsomething \stopsomething. The arguments of \startsomething, enclosed in [ ], can be used to configure the exact nature of the something that you want to apply. For example, in the middle of a ConTeXt document:

The quick brown fox jumps over the
\startframed[corner=round]
lazy
\stopframed
dog.

produces

However, setting the start-stop arguments locally like this is usually not the best way to configure the something that you are applying. The problem with modifying the arguments locally like this is that if you eventually reuse this configuration — in this document or even in other documents that you might write — you won't be able to edit and maintain the configuration consistently. You might be able to get away applying formatting lcoally like this if you use it in only one single place, but since you generally don’t know how you might want to use the same configuration in the future, it's usually best to avoid modifying modifying the start-stop arguments locally like this.

A somewhat better way to configure something is to use setupsomething in a section of your code that is dedicated to configuration. This will configure something globally: the default configuration of this particular something throughout your document will be whatever you set it to in this way. For example:

\setupframed[corner=round]
The
\startframed
quick
\stopframed
brown fox jumps over the
\startframed
lazy
\stopframed
dog.

produces

Since you have set up framed to have rounded corners here, that is the default behavior throughout the document. You can still override it locally if need be, but in doing so, consider the cautions above about local modifications.

But this still isn't the best way to configure something because what if you might — now or in the future — have more than one type of frame in your document? In order to anticipate such possibilities, the best way to configure something is ordinarily to use definesomething to create a meaningful name for each of your custom configurations. These custom configurations will be easy to modify globally in a consistent way, now and into the future. And if you choose your names well, your ConTeXt code will be easier for human beings (including yourself) to read. For example:

\defineframed[adjectiveFramed][corner=round]
\defineframed[nounFramed]
The
\startframed[adjectiveFramed]
quick brown
\stopframed
\startframed[nounFramed]
fox
\stopframed
jumps over the
\startframed[adjectiveFramed]
lazy
\stopframed
\startframed[nounFramed]
dog.
\stopframed

produces

When you read this code, you can tell immediately that nouns are framed one way, and adjectives another. Since it uses \defineframed and gives these customizations informative names, editing and maintaining this document is much easier. If you decide that you want to give all the adjectives some other type of frame, a simple change to the \defineframed is all that is needed. There is no need to worry about going through with search and replace and trying to make sure that you find and update all the adjective frames. A single small change will make the update globally and consistently throughout the document.

Notice that it was worthwhile to define nounFramed even though it contained no customizations. Even though its current configuration is the same as the default configuration for frames, you might decide to change that later. If you don't set up the definition now, there will be no easy way to make changes to the frames for all nouns (and nothing else) later.

Of course not every command in ConTeXt is a start-stop, setup, or define command, but a large number of them are, including many of the most commonly used commands. If you understand the basic idea behind these types of commands, you will find that you are already able to do lots of things in ConTeXt.


Your first ConTeXt document

Now that you have an idea of how ConTeXt is structured, let’s look at how you use that structure to make documents. Here is a very minimal example of a ConTeXt document:

\starttext
Hello, world!
\stoptext

When you compile this, it produces a page with a 1 in the center at the top and with the text:

That's it — that's all you need to make a ConTeXt document!

You can think of the code here this way: ConTeXt’s way of formatting the entire text of the document is called text, so to apply that way of formatting you enclose the document text in \starttext \stoptext.

Starting to customize things

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. The way that paper is sized for a document in ConTeXt is called papersize. You could use \definepapersize to define a letter configuration for papersize, but that is common enough that ConTeXt has defined it automatically: letter is already built-in. Since you want to configure papersize globally for the entire document, use \setuppapersize[letter]:

\setuppapersize[letter]
\starttext
Hello, world!
\stoptext

Note that paper size is not the type of thing that you ordinarily set locally for only part of the document, so there is no \startpapersize \stoppapersize. You just configure it globally with \setuppapersize, and if you want to define new paper sizes beyond what ConTeXt has already built-in, you use \definepapersize.


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

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

This is another example of the setup notation. The way that pages are numbered in ConTeXt is called pagenumbering, so you use \setuppagenumbering to configure it. And the use of [ ] to enclose the argument is another example of the square brackets notation.

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 setup notation is being used 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 the square brackets notation.

Another example: 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 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.
\stopframed

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

\setupframed[corner=round]
\startframed
An example.
\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 define notation 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.
\stopframed

\startframed[exampleFrame]
An example.
\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 those frame formats are created, and the change will be applied consistently and globally to your whole document.

Example: curly braces notation

You have now seen examples of four of the five notational conventions listed above: all of them except the curly braces notation.

To see one way that the curly braces notation 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.}

This is an example of how 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 start, stop, setup, or define, a fair number of them instead operate on the single unit following them, as \framed does. Some, like \framed, allow you to use either syntax.

Another situation where text needs to be treated as a single unit is when an argument to a command takes some text that involves [ ]. For example, the following code works fine because the text for the section title doesn’t contain [ ]:

\startsection[title=A section title]
\stopsection

However, because the following section title contains [ ], it won’t work unless you do something to tell ConTeXt that those square brackets are not signaling the end of the function’s arguments:

\startsection[title=a[5] and other list elements]
\stopsection

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

\startsection[title={a[5] and other list elements}]
\stopsection

Delimiters in ConTeXt

  1. square brackets: Enclose arguments to ConTeXt commands in [ ].
  2. curly braces: Use { } as delimiters to group text as a single self-contained unit.


Summary

Naturally not everything in ConTeXt is written using these five notational conventions. There are many further notational details to learn, and not everything in ConTeXt is completely consistent with these conventions. However, the design of ConTeXt really is if not entirely consistent at least highly consistent in using these conventions, 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 this notation

Here I'll put some commands.