Tricki
a repository of mathematical know-how

Revision of Formatting: article structure from Fri, 06/02/2009 - 19:55

There is a set of recommendations for how a Tricki article should be written; see the Guidelines for writing Tricki articles page. If you are about to write a Tricki article and feel uncertain about how you should lay out the content, then you should begin by reading that page. If you are wondering more about the technical aspects of structuring an article, you can find more information below. There is more information about the Tricki's markup on the formatting page.

Sections

The Tricki has a few sectioning features that you should try to make use of in all your articles. The following types of sections exist.

[QUICK DESCRIPTION]
[PREREQUISITES]
[EXAMPLE]
[GENERAL DISCUSSION]
[PARENT ARTICLE]

This list will appear automatically when you go to create an article, but the automatically supplied list is just a guide that you can modify if the article content calls for it. Not all the sections need to be present, though it is highly recommended for them to be even if you just write 'this section needs to be written', and you may add more sections of types [EXAMPLE] and [GENERAL DISCUSSION]. More detailed discussion of section-types and examples of what they look like is given further below.

Ending sections

A general rule that applies to each of these section-identifiers is that a section ends where the next section begins, whether started by a new section-identifier as specified above or by a new top-level heading (=== ... ===). If you wish to specify precisely where the section ends, you simply end it using [/SECTION-NAME]. For example, you may write [EXAMPLE]...[/EXAMPLE] if you wish to specify where the example ends, or you may use just [EXAMPLE] if the example ends where the next section begins. There is never any harm in specifying where the section ends.

Examples

Below are some examples of sectioning. Since technique examples are a very important part of the Tricki, [EXAMPLE] sections are highlighted on the site by being shown as indented. Interspersing examples and general discussion can be a very helpful way of explaining a particular technique, and the formatting features of the Tricki are intended to make this easy. The simplest way to create an example is the use the [EXAMPLE] section-identifier on its own. Below is a list illustrating more options, followed by examples.
  • [EXAMPLE]
  • [EXAMPLE id]
  • [EXAMPLE|Title]
  • [EXAMPLE id|Title]
Note: IDs can only consist of the characters a-z and _. You should use descriptive IDs, and not ones that are related to the order in which the examples appear, since this may very well change.

Example 1: How to use example sections

This example section has been created using the markup [EXAMPLE|How to use example sections].

Example 2: An example section with an id that can be continued later

This section was created using the markup [EXAMPLE example_with_id|An example section with an id that can be continued later]. If you wish to continue the same example at some later point, simply use [EXAMPLE example_with_id], inputting the appropriate id.

General discussion

This [GENERAL DISCUSSION] section is just here so that we may continue the previous example afterwards.

Example 2, continued

This section continues the one before the general discussion. It was created using the markup [EXAMPLE example_with_id].

Referencing example sections

You can give [EXAMPLE] sections IDs as illustrated above. If you want to refer to an example section with an ID at some point in your article, you can use the same markup as for referencing theorems and other environments: [ref Example #id]. For example, here is a reference to Example 2 above, created using the markup [ref reference to Example #example_with_id].

Headings

You can create headings by enclosing the heading text inbetween two sequences of '=' signs. There are three levels of headings, from === Level 1 === to ===== Level 3 =====, decreasing in size as follows.

Level 1

Level 2

Level 3
Level 1 headings should be used for section titles, and lower headings can be used for subsections. However, you should not use this markup to start a section that has a special section identifier as mentioned above. Using the special section markup mentioned above will help the Tricki to understand the structure of articles, meaning it can process them in better ways.