Help:Editing/House Style

This page lists the various house style conventions that have been adopted on ProofWiki. Active contributors are expected to gradually master these, but when first starting to contribute, seasoned editors will come in and tidy the pages you write or create.

== Internal References ==

Due to the desired standard of rigor on ProofWiki, there are a lot of concepts on any given (proof) page that have their own, dedicated Proof or Definition page on ProofWiki.

To ensure ease of reference and maximal clarity and consistency, the following rules for internal reference are to be adhered to.

For information on creating links, see this section.

References to Theorems and Axioms
Whenever a theorem is invoked or referred to, be it in a proof or, for example, a clarifying comment, it should be referenced by its full title.

Also, for ease of editing, there is no need to change the case of theorem names; the ProofWiki page title will suffice.

Thus, for example, a valid reference to the result Union Distributes over Intersection is simply:


 * "By Union Distributes over Intersection, $A \cup \left({B \cap C}\right) = \left({A \cup B}\right) \cap \left({A \cup C}\right)$."

This is achieved by simply putting the title of the page you want to reference between double square brackets,  and.

The same convention applies to axioms, except that the namespace identifier Axiom: should be removed.

The correct way to reference the page Axiom:Axiom of Choice thus is:


 * Axiom of Choice

which is produced by:



References to Definitions
Whether or not a particular concept should be linked to its definition page is subject to a less strict philosophy.

In general, whenever a part of a definition is critically used in an argument, or is important for understanding the flow of the argument, a link should be included.

A good rule of thumb is to include a reference at least at the first occurrence of a concept on a page, or whenever the concept is used in a new way, or a new context.

It is considered good practice to have at least one reference in a paragraph where the concept is used; this is - naturally - attached to the first occurrence of the concept.

These references are made in a non-intrusive way. Thus, we write:


 * Let $R$ be a ring.

and not:


 * Let $R$ be a Ring (Abstract Algebra).

For example, it is not necessary to include three references to Definition:Ring (Abstract Algebra) in one sentence which happens to have three occurrences of "ring" in it.

If however a proof contains three paragraphs, then it would be good to include at least one reference to Definition:Ring (Abstract Algebra) in each paragraph.

Inline Equations
Inline equations (that is, those that appear as part of a text sentence) merely need the dollar delimiters. For example:


 * The semilinear wave equation $\partial_t U = A U + B \left({U}\right)$ is Hamiltonian.

is produced by the input:


 * The semilinear wave equation  is Hamiltonian.

Displayed Equations
Displayed equations should be indented using a single colon, for example, a displayed equation should look like:


 * $\displaystyle H \left({U}\right) = \int_0^{2 \pi} \frac {\left({\partial_x u}\right)^2} 2 + \frac {v^2} 2 - F \left({u}\right) \ \mathrm d x$

which you can enter as:



Using a format that places the equation on the center of the page:


 * $$E = m c^2$$

is discouraged, because with our "short sentence" house style, this breaks up the reading flow.

Big Operators
The  command should be used at the front of expressions using the 'big operators' such as   and , whether the equation is displayed or inline.

This includes (but may not be exclusive to) the commands,  ,  ,  ,  ,   and.

For example:


 * $\sum_{i \mathop = 1}^n$
 * $\prod_{i \mathop = 1}^n$
 * $\frac {-b \pm \sqrt {b^2 - 4ac}} {2 a}$
 * $\lim_{n \to \infty} \frac 1 n$

all look better as:


 * $\displaystyle \sum_{i \mathop = 1}^n$
 * $\displaystyle \prod_{i \mathop = 1}^n$
 * $\displaystyle \frac {-b \pm \sqrt {b^2 - 4ac}} {2 a}$
 * $\displaystyle \lim_{n \to \infty} \frac 1 n$

and are produced by, respectively:



Note however that instead of, the form  , which has the same effect, is preferred, unless other big operators are used in the same equation (in which case you need to use   anyway).

Furthermore, to improve aesthetic appeal certain characters, such as $=$ and $\in$, when used in subscripts of big operators, must be endowed with the  command to enforce appropriate spacing.

As a contrast, compare:


 * $\displaystyle \sum_{i=1}^n \quad \sum_{i \mathop = 1}^n$
 * $\displaystyle \bigcap_{n \in \N} \quad \bigcap_{n \mathop \in \N}$

The  command is to be used in the following manner (the code produces $\displaystyle \sum_{i \mathop = 1}^n$):

\displaystyle \sum_{i \mathop = 1}^n

The d of Calculus
When writing calculus operators, use a non-italic form for the $\mathrm d$, that is, write it as. So you would have:


 * $\dfrac {\mathrm d y} {\mathrm d x}$

which would be produced by:



rather than:


 * $\dfrac {d y} {d x}$

which would be produced by:



Fonts
We have several fonts available, many of which have particular conventional uses in mathematics.

Examples are:
 * Calligraphy:, which produces $\mathcal{ABCDE} ...$ (uppercase only)
 * Blackboard:  or (preferably) , which produces $\Bbb{ABCDE} ...$ (uppercase only)
 * Script:, which produces $\mathscr{ABCDE} ...$ (uppercase only)
 * Sans serif:, which produces $\mathsf{ABCDE} ... \mathsf{abcde} ...$
 * Fraktur:, which produces $\mathfrak{ABCDE} ... \mathfrak{abcde} ...$
 * Fixed Width:, which produces $\mathtt{ABCDE} ... \mathtt{abcde} ...$

The use of Fraktur and Script are discouraged, as they are not so easy on the eye and can be difficult to decipher on certain browsers.

Punctuation niceties
A sentence broken by a displayed equation should be ended with a colon:


 * $\dfrac {\text{display}} {\text{equation}}$

for a better presentation.

On the other hand, the displayed equation itself should not be ended with a full stop or comma.

That is, one should write:


 * $\displaystyle \bigcap_{S \mathop \in \Bbb S} \Bbb U \setminus S = \Bbb U \setminus \bigcup_{S \mathop \in \Bbb S} S$

and not:


 * $\displaystyle \bigcap_{S \mathop \in \Bbb S} \Bbb U \setminus S = \Bbb U \setminus \bigcup_{S \mathop \in \Bbb S} S$.

This is a style tip borrowed from Ian Stewart.

Q.E.D.
To end a proof, the template  should be used, which looks like:

or if you wish to break your page up into subproofs, end those subproofs with, which looks like:

In a dash for consistent notation, it is understood that these templates should immediately succeed the last line of the proof, i.e.:

Hence the result.

and not:

Hence the result.

Tempting though it is to write "Q.E.D." at the bottom, this is so uncool as to be positively naff.

Code style
There are a few general source code conventions which make your code easier to read and maintain:


 * Each variable, and each command beginning with a backslash should be preceded by a space, except (for some unexplained result of evolution) when enclosing things in brackets. See some of the above instance for a typical example.


 * When enclosing brackets around an object, always use the  format, for example   rather than.


 * There should be no need to use the commands  etc. for specifying the sizes of parentheses. Using the   technique (as above) will almost always automatically size the brackets aesthetically.


 * Punctuation should appear outside the LaTeX environment, for example:


 * Hence $f \left({x}\right)$. (produced by: )


 * as opposed to:


 * Hence $f \left({x}\right).$ (produced by: )


 * Single-character parameters to standard $\LaTeX$ constructs need not be put in curly braces. That is,  is preferred to  . They both produce: $\dfrac 1 2$

It makes the source code significantly easier to read.

Having said that, please do not ignore the rule about spacing. The same effect can also be achieved by  (see, it still looks like $\dfrac12$) but that is significantly harder to interpret visually.

Aligned material
If an equation includes multiple equalities or inequalities, it is best to place each equality on a new line.

For example:


 * $\dfrac {\mathrm d} {\mathrm d t} H \left({U}\right) = \mathrm d H \left({U} \right) \cdot \dot U = \Omega \left({X_H \left({U}\right), \dot U} \right) = \Omega\left({X_H \left({U}\right), X_H \left({U}\right)} \right) = 0$

would look better as an aligned equation. This is done using the following commands:

...

Here, the section following  is a $\LaTeX$ environment, and should contain anything you want to appear to the left of the equals sign.

The section following  is the same, but will appear to the right of the equals sign.

and  are similar, but produce material in columns further to the left and further to the right respectively. In particular, the  column is often used for an "implies" sign where the   and   are used for either side of a string of equations.

All these $\LaTeX$ environments are already in  mode, so there is no need to include that command in your equation.

When entering such an  environment, it should globally look like this:

That is, it adheres to the following principles:


 * Every empty column should in general be omitted, except perhaps for  sections, which can be left as placeholders for possible future addition of comments
 * Non-empty columns are entered on separate lines, with the  and   all aligned

These conventions serve to optimize readability and brevity.

More options and abilities of the  can be found on its page, Template:Eqn.

The section following  is not a $\LaTeX$ environment, and can be used to add any comments about the equation at this point.

So the example we gave above would be typeset as:

The finished result will look like:

The operator that is displayed in this template can be changed using  to show inequalities, etc.

Note the following:


 * Do not include two consecutive open or close curly braces:  or   anywhere in your eqn templates. It will break the interpreter.

Put spaces in:  or   and it will be okay.


 * Do not include the vertical line  (a.k.a. "pipe") in $\LaTeX$ expressions as this also breaks the interpreter. Use   instead.


 * In particular,  (used to produce $\|$) has the same problem. Use   instead.

These caveats apply only within the  environment. Elsewhere on the page such constructs should be fine. To accommodate for the inevitable copy-paste efforts, and for consistency's sake, it is however desirable to always use  and.

Language
This is an English language website, and so all pages are to be presented in English. Where there is a difference between spellings between US and rest-of-world English, the US version is generally used, with a few exceptions (the spelling of metre is under discussion).

Linguistic style
During the presentation of a mathematical argument, a formal style is preferred.

For example:


 * Suppose that ...

is preferred to:


 * Let's suppose that ...

and:


 * Hence the result.

is preferred to:


 * ... and we're done.

As an attempt is being made for ProofWiki to appeal to as wide an audience as possible worldwide, using colloquial language (except for example when illustrating logical concepts by means of everyday examples) is discouraged.

Abbreviations
The difference between "e.g." (exempli gratia - for example) and "i.e." (id est - that is) is sadly falling into obscurity. It is all too common for "i.e." to be used when "for example" is meant, and vice versa.

So as to remove all confusion, such abbreviations are discouraged.

Also, beware the ubiquitous confusion between its and it's. The full version it is should be used instead of it's in any case, so it's should have no reason to appear.

Sentence Length
During the course of an argument to present a mathematical proof, follow these rules:


 * Each sentence should be short.


 * Each sentence should convey one step, either:
 * One simple statement, or:
 * One compound statement of the form $P$, therefore $Q$.


 * Each sentence should be on a separate line.

Compare the presentations:

$(1):$
 * $S$, because of $R$ (we know this from Tom's Theorem), because of $Q$ (from above) which applies when $P$ holds (see Fred's Theorem), but we know $P$ holds because it's what we defined in the first place.

$(2):$
 * Let $P$ hold.
 * From Fred's Theorem, it follows that $Q$.
 * From above, $R$.
 * From Tom's Theorem, $S$.

Whether or not filler words are needed (it follows that, we have, hence etc.) is a stylistic decision. Fewer words are preferred, but clarity and completeness override every other consideration.