|
|
| (14 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | LIKE EVERYTHING IN THIS SANDBOX, THIS IS ONLY A DRAFT AND SHOULD NOT BE USED YET.
| + | [[Introduction]] |
| | | | |
| − | = An introduction to ConTeXt ==
| + | [[Some Basic Commands]] |
| − | 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:
| |
| − | | |
| − | # '''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''}}.
| |
| − | | |
| − | 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 {{code|\start''something''}} {{code|\stop''something''}}. The arguments of {{code|\start''something''}}, 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:
| |
| − | | |
| − | <context source="yes" text="produces">
| |
| − | The quick brown fox jumps over the
| |
| − | \startframed[corner=round]
| |
| − | lazy
| |
| − | \stopframed
| |
| − | dog.
| |
| − | </context>
| |
| − | | |
| − | 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 {{code|setup''something''}} 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:
| |
| − | | |
| − | <context source="yes" text="produces">
| |
| − | \setupframed[corner=round]
| |
| − | The
| |
| − | \startframed
| |
| − | quick
| |
| − | \stopframed
| |
| − | brown fox jumps over the
| |
| − | \startframed
| |
| − | lazy
| |
| − | \stopframed
| |
| − | dog.
| |
| − | </context>
| |
| − | | |
| − | 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 {{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:
| |
| − | <context source="yes" text="produces">
| |
| − | \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
| |
| − | </context>
| |
| − | | |
| − | When you read this code, you can tell immediately that nouns are framed one way, and adjectives another. Since it uses {{cmd|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 {{cmd|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 {{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'' 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:
| |
| − | | |
| − | <texcode>
| |
| − | \starttext
| |
| − | Hello, world!
| |
| − | \stoptext
| |
| − | </texcode>
| |
| − | | |
| − | When you compile this, it produces a page with a 1 in the center at the top and with the text:
| |
| − | | |
| − | <context>
| |
| − | Hello, world!
| |
| − | </context>
| |
| − | | |
| − | 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 {{code|text}}, so to apply that way of formatting you enclose the document text in {{cmd|starttext}} {{cmd|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 {{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: {{code|letter}} is already built-in. Since you want to configure {{code|papersize}} globally for the entire document, use {{cmd|setuppapersize|[letter]}}:
| |
| − | | |
| − | <texcode>
| |
| − | \setuppapersize[letter]
| |
| − | \starttext
| |
| − | Hello, world!
| |
| − | \stoptext
| |
| − | </texcode>
| |
| − | 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 {{code|\startpapersize}} {{code|\stoppapersize}}. You just configure it globally with {{cmd|setuppapersize}}, and if you want to define new paper sizes beyond what ConTeXt has already built-in, you use {{cmd|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 make it default to the center of the bottom of the page instead, you can use {{cmd|setuppagenumbering|[location{{=}}bottom]}}.
| |
| − | <texcode>
| |
| − | \setuppapersize[letter]
| |
| − | \setuppagenumbering[location=bottom]
| |
| − | \starttext
| |
| − | Hello, world!
| |
| − | \stoptext
| |
| − | </texcode>
| |
| − | | |
| − | 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.
| |
| − | | |
| − | When you add more text to your document, you might notice that by default, paragraphs are not indented. The way that paragraphs are indented in a ConTeXt is called {{code|indenting}}, so you can use {{cmd|setupindenting}} to configure it globally for your document. To make paragraphs by default indented by a medium amount, use {{cmd|setupindenting|[yes, medium]}}. (Here {{code|yes}} turns the indenting on, but by default the amount is still {{code|none}}, so {{code|medium}} is used to specify the amount.)
| |
| − | | |
| − | <texcode>
| |
| − | \setuppapersize[letter]
| |
| − | \setuppagenumbering[location=bottom]
| |
| − | \setupindenting[yes, medium]
| |
| − | \starttext
| |
| − | \input knuth
| |
| − | \stoptext
| |
| − | </texcode>
| |
| − | | |
| − | produces a full page with the following text:
| |
| − | | |
| − | <context>
| |
| − | \setupindenting[yes, medium]
| |
| − | \input knuth
| |
| − | </context>
| |
| − | | |
| − | To generate some text for these paragraphs, we have used {{cmd|\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.
| |
| − | | |
| − | While using {{cmd|setupindenting}} will do the job, for the reasons discussed above it would actually be better first to use {{cmd|defineindenting}} to give your favorite indentation patterns names. Then you can use {{cmd|setupindenting}} to make one of these the default for this document, as in:
| |
| − | | |
| − | <texcode>
| |
| − | \setuppapersize[letter]
| |
| − | \setuppagenumbering[location=bottom]
| |
| − | \defineindenting[myStandardIndenting][yes, medium]
| |
| − | \setupindenting[myStandardIndenting]
| |
| − | \starttext
| |
| − | \input knuth
| |
| − | \stoptext
| |
| − | </texcode>
| |
| − | | |
| − | produces a full page with the following text:
| |
| − | | |
| − | <context>
| |
| − | \defineindenting[myStandardIndenting][yes, medium]
| |
| − | \setupindenting[myStandardIndenting]
| |
| − | \input knuth
| |
| − | </context>
| |
| − | | |
| − | In practice, you will often see people skip over the {{cmd|defineindenting}}, but as discussed above, for many reasons it is helpful to include it.
| |
| − | | |
| − | == Another small example ==
| |
| − | For another example of what you might want to customize, suppose that you want to boldface terms that will define later in your document. At first glance, it might be tempting just to italicize each one individually, as in:
| |
| − | <context source="yes" text="which produces">
| |
| − | The quick brown {\it fox} jumped over the lazy {\it dogs}.
| |
| − | </context>
| |
| − | | |
| − | Based on the discussions above though, you should know why this isn’t a good idea. What should you do instead? For a hint, the way that ConTeXt formats highlighted text is called ''highlight''. You might think that you could use {{code|\starthighlight}} {{code|\stophighlight}}, and that would be a good guess, since that would fit in with the overall logic of ConTeXt. However, those commands are still under development, so you can't use them yet. But {{cmd|setuphighlight}} and {{cmd|definehighlight}} do exist, and they let you configure and define ways to highlight text.
| |
| − | | |
| − | There is a slight twist though: when you use {{cmd|definehighlight}}, since the ''start-stop'' version of highlights have not yet been implemented, you instead can use the name you defined to produce the highlighting, as in:
| |
| − | | |
| − | <context source="yes" text="which produces">
| |
| − | \definehighlight[definedTerm][style=it]
| |
| − | The quick brown \definedTerm{fox} jumped over the lazy \definedTerm{dogs}.
| |
| − | </context>
| |
| − | | |
| − | As long as you keep in mind that {{code|definedLater}} 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'' to make more readable and reusable code in ConTeXt.
| |
| − | | |
| − | == Delimiters in ConTeXt ==
| |
| − | One other useful thing to understand about ConTeXt is how it uses delimiters. Aside from ''start-stop'' commands, there are two main delimiters in ConTeXt:
| |
| − | | |
| − | # '''square brackets''': arguments to ConTeXt commands are enclosed in [ ].
| |
| − | # '''curly braces''': in ConTeXt, { } are used as delimiters to group text as a single self-contained unit.
| |
| − | | |
| − | === Square brackets ===
| |
| − | You have already seen lots of examples of how arguments to ConTeXt commands are enclosed in [ ]. ConTeXt commands usually have 1, 2, or 3 arguments, and each one is enclosed in [ ]. For example this use of {{cmd|definehighlight}} has two arguments:
| |
| − | <texcode>
| |
| − | \definehighlight[definedTerm][style=it]
| |
| − | </texcode>
| |
| − | | |
| − | 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 and/or ''key=value'' pairs, as in:
| |
| − | <texcode>
| |
| − | \definehighlight[definedTerm][style=it, color=red]
| |
| − | </texcode>
| |
| − | | |
| − | It is worth noting that although each argument is delimited by [ ],
| |
| − | | |
| − | === Curly braces ===
| |
| − | 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 {{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.}
| |
| − | </context>
| |
| − | | |
| − | 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 {{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.
| |
| − | | |
| − | 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 [ ]:
| |
| − | <context source="yes">
| |
| − | \startsection[title=A section title]
| |
| − | \stopsection
| |
| − | </context>
| |
| − | | |
| − | 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:
| |
| − | | |
| − | <context source="yes">
| |
| − | \startsection[title=a[5] and other list elements]
| |
| − | \stopsection
| |
| − | </context>
| |
| − | | |
| − | 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:
| |
| − | | |
| − | <context source="yes">
| |
| − | \startsection[title={a[5] and other list elements}]
| |
| − | \stopsection
| |
| − | </context>
| |
| − | | |
| − | | |
| − | | |
| − | | |
| − | == 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.
| |
