Changes

ConTeXt has a very logical structure. Once you are ’re familiar with its basic underlying principles, you will find that many of its commands seem quite natural. In this introduction, we’ll look at two aspects of ConTeXt’s structure: # the three main types of commands# the three main delimiters Let’s start with the commands...

# '''setup''': To configure ''something''for the rest of the document, use {{code|\setup''something''}}.

However, setting the arguments of a ''start-stop'' arguments command 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 with applying formatting lcoally locally 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'' command arguments locally like this.

A somewhat better way to configure ''something'' is to use {{code|setup''something''}} at the start of your document, perhaps even in a section of your code that is dedicated devoted to configurationsuch configurations. This will configure ''something'' globallyfrom then on in the document: the default configuration of this particular ''something'' throughout from then on in your document will be whatever you have set it to in this way. For example:

Since you have set up framed to have used {{cmd|setupframed}} for rounded corners hereat the start, that is the default behavior for {{cmd|startframed}} 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 {{code|define''something''}} 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:

Notice that it was worthwhile to define {{code|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'' type of command, but a large number many 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.

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

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

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 {{code|papersize}}. You could use {{cmd|definepapersize}} to define a {{code|letter}} configuration for {{code|papersize}}, but that is common enough that ConTeXt has defined it automatically: the page size {{code|letter}} is already built-in, so you don’t need to do that. Since So since you want to configure {{code|papersize}} globally for the entire document, use {{cmd|setuppapersize|[letter]}}at the start of your document:

It’s worth thinking about why you use {{cmd|setuppagenumbering}} here. A page numbering is inherently global to a document: it can be turned on and off, and it can be configured differently in different parts of the document, but there is only one ''page numbering'' for a document. So all you can do is configure it with {{cmd|setuppagenumbering}}. There is no {{code|\definepagenumbering}} and no {{code|\startpagenumbering}} or {{code|\stoppagenumbering}}. (Oddly enough, there is a {{cmd|setupuserpagenumber}} command though, so if you find that {{cmd|setuppagenumbering}} isn’t giving you enough options, you might look at {{cmd|setupuserpagenumber}} too.)

To generate some text for these paragraphs, we have used {{cmdcode|\input knuth}} to include a quotation from Knuth that is built-in to ConTeXt. You will find that this quotation is often used in ConTeXt documentation.

Note that ConTeXt does not have a {{code|\startindenting}} or {{code|\stopindenting}} command. Instead, the named indenting configurations that you have defined with {{cmd|defineindenting}} can be used in other commands that define regions that can have indenting. == Another small example Custom highlighting ==For another example of what you might want to customize, suppose that in a book you are writing, you want to boldface italicize terms that you will define later in your documentthe book. At first glance, it might be tempting just to italicize each one individually, as in:

There is a slight twist though: when you use {{cmd|definehighlight}}, since the ''start-stop'' version of highlights have not yet been implemented, you can instead can use the name you defined to produce the highlighting, as in:

As long as you keep in mind that {{code|definedLaterdefinedTerm}} is really just an alternative version in place of {{code|\starthighlight}} {{code|\stophighlight}} (which aren’t implemented in ConTeXt yet), this still fits into the overall logic of ConTeXt.

Even though this example contains some extra complications, it gives another illustration of how you can use ''define'' commands to make more readable and reusable code in ConTeXt.

One other useful thing to understand about ConTeXt is how what it uses for delimiters. There are three main delimiters in ConTeXt:

You have already seen lots of examples of how arguments to ConTeXt commands are enclosed in [ ]. ConTeXt commands usually have 1one, 2two, or 3 three (occasionally more) arguments, and each one is enclosed in [ ]. For example , this use of {{cmd|definehighlight}} has two arguments:

Many ConTeXt commands have optional arguments. These can be written as [ ] or just completely omitted.

Some arguments in ConTeXt are single words or strings, as in {{code|definedTerm}} above. Other arguments are ''key=value'' pairs, as in {{code|style{{=}}it}} above. Still other arguments are comma-separated lists of strings words and/or ''key=value'' pairs, as in:

It is worth noting that although In this example, there are two arguments and three parameters (each argument is delimited by [ ], item in a comma-separated list being counted as a parameter).

In this case, {{code|\definedTerm}} is the type of command that operates on the single unit that follows it, so you need { } to indicate that the enclosed ''fox'' is and ''dogs'' are what is to be operated on. A fair number of ConTeXt commands work this way: they may have some optional arguments that configure them enclosed in [ ], but whatever comes immediately after that is what the command is applied to.