Typographical shortcuts

To make the layout of the documents published by SPIP an easier task, the system offers a number of "SPIP shortcuts" which:
-  simplify matters for users who do not know HTML;
-  make it possible for page layout to be processed automatically.

So naturally you can still use HTML code in your SPIP documents, but we recommend that you opt to use these few SPIP shortcuts instead, which are much easier to remember and more especially, provide the system with some automated operations.

In short

{{An intertitle }}}

Text with {italic} and {{bold}} or a {{ {mix of both} }}.
A line break with [an external link->https://www.spip.net] and [an internal link->art12] with an automatic title [->rubrique10].

Another paragraph with [[A footnote]] and a [?glossary] term.

-* A list
-* A list
-** A sub-element of a list

-# An ordered list
-# An ordered list
-## Sub-item of an ordered list

A separator
----

A table
| {{ Location }} | {{ Action }} |
| Caves | Spip Party |
|Toulouse | Spip in pink |

The definition of an anchor [direct<-] with a link to get there [->#direct].

<quote>A quote</quote>

An intertitle

Text with italic and bold or a mix of both .
A line break with an external link and an internal link with an automatic title rubrique 10.

Another paragraph with [1] and a glossary term.

  • A list
  • A list
    • A sub-element of a list
  1. An ordered list
  2. An ordered list
    1. Sub-item of an ordered list

A separator


A table

Location Action
Caves Spip Party
Toulouse Spip in pink

The definition of an anchor with a link to go there #direct.

A quote

[1A footnote

Simple formatting

To start with, we present the simplest and most common shortcuts. For the users who wish to have more control over the layout of their texts, we will then later introduce some more complex versions of these shortcuts.

N.B. The simple shortcuts fulfil most of the formatting requirements, and make online publication almost as easy as writing an email.

-  Automatic French typography

SPIP automatically accommodates the standard rules for spacing in French typography (and some other languages) - it will insert unbreakable white space before any occurrence of the characters ":", ";", "!", and "?", and will insert unbreakable spaces before and after any phrases enclosed in «French style quotation marks».

(Note: this functionality is ONLY activated if the principal language for the site is French.)

-  Creating paragraphs

To create paragraphs, you simply leave a blank line, a bit like separating paragraphs in a e-mail (by "skipping" a line).

The simple "line feed" (enter or return) without separating the two paragraphs is insufficient to create a new paragraph (as a matter of fact, it does not even create a line feed).

You can leave several consecutive blank lines without any effect on the layout. The redundant blank lines will just be eliminated.

-  Creating bulleted or numbered lists

You can create lists in SPIP in the same way as in an e-mail: you only need to enter a line feed and start the new line with a dash/hyphen ("-").

Notice that, here, a simple line feed is enough (you can create lists in the same paragraph); but if you leave a blank line before the one beginning with a hyphen, then a blank line will appear before the list

For example,

- I like work;
- it fascinates me.
- I can sit and look at it for hours.
 (Jerome K. Jerome)

will display:


-  I like work;
-  it fascinates me.
-  I can sit and look at it for hours. (Jerome K. Jerome)

Note here that this is just inserting a bullet, and is not creating a list (to create lists see)

Bold and italic

You specify a text in italic by placing it between simple braces: "...some text {in italic} in...».

You specify a text in bold by placing it between double braces: "...some text {{in bold}} in...".

-  Paragraph headings

Paragraph headings are titles inside a text that show its structure. In SPIP, they are very simply defined by placing them between treble braces: "{{{Section heading}}}" will display the heading, bold and centred:

Section heading

-  Horizontal rule

It is very simple to insert a horizontal rule (or a separation line) across the width of the text: you just insert a line containing only a series of at least four hyphens, like this:

----

which will generate:


Hypertext links

You can easily create a hypertext link with the following code:

SPIP is an initiative from the [minirezo->http://www.minirezo.net/].

which becomes

SPIP is an initiative from the minirezo.

(To help remember this: the dash followed by the greater-than sign makes a kind of arrow, showing that the link’s text (before the arrow) "points to" an address.)

The link’s URL can be absolute (starting, as in this example, with http://), relative (to another page of the same site), a link to a document using an internet protocol (ftp://...) an e-mail address ("[->mailto:minirezo@rezo.net]")...

Specific application: when nothing is entered before the "arrow", the text of the passed URL is displayed as a clickable link. For example:

[->http://dmoz.org/World/Deutsch/Kultur/Literatur/Autoren_und_Autorinnen/P/Proust,_Marcel/]

returns:

http://dmoz.org/World/Deutsch/Kultu...

Remember that in the case of very long URLs, the display is truncated (in order to avoid the degradation of your graphic interface), but the hypertext link points to the whole correct address.

It is possible to specify the language of the page that the link points to, which browsers may display as they so choose. To do this, just put the language code between braces.

[A site in French{fr}->http:///www.adresse.tld]

This is particularly recommended whenever the destination page is not in the same language as your current source text.

If you want to provide a lot of information about the link without excessively extending the clickable zone, you can provoke the appearance of a tool-tip instead by inserting the vertical bar sign | before the arrow, and follow it with the text that you want in the tool-tip:

[see here|This link will tell you everything you ever wanted to know about some very complex process->http:///www.adresse.tld]

will display as see here, and the rest of the text will only appear when you move your mouse over the link.

-  Hypertext links inside the site

Furthermore, this same hypertext links system makes it easy to create links inside your site with SPIP. The only trick consists of finding the number of the article or the section or the news item to which you want to link: NUMERO when you "visit" an article, a news item or a section in the private area, the left-hand column contains a box indicating this number in large digits.

This is the number that you should insert in the hypertext link:

  • Link to article 342 (4 possibilities):
    link to [article->342]
    link to [article->art342]
    link to [article->article 342]

A particular use: [->art342] (no text before the "arrow") will automatically display the title of article 342 with a link to that article.

  • Link to section 12:
    link to [section->rub12]
    link to [section->rubrique 12]
  • Link to news item 65:
    link to [news item->br65]
    link to [news item->breve 65]
    link to [news item->brève 65]
  • Authors, keywords, sites, images, documents:
    link to [an author->aut13] or [the same author->auteur13]
    link to [a keyword->mot32]
    link to [a syndicated site->site1]
    link to [an attached document->doc17] or [the same document->document17]
    link to [an image->img13] or [the same image->image13]

Specific application: here too, we can put nothing before the "arrow" ([->aut13]...). SPIP will automatically insert the required information. In the case of an attached document or an image, if we manually entered a title, that title will be displayed; otherwise, the file name itself will be used.

Footnotes

A footnote is usually indicated by a number inserted in the text then repeated at the bottom of the page and offering additional information.

In SPIP, this feature (pretty awkward to manage manually in HTML) is automated: the footnotes are numbered by SPIP, which also manages the hypertext links inside the document to jump directly from the number to the corresponding footnote and vice versa.

In SPIP, a footnote is placed between double brackets: "A[[Here is additional information.]] footnote." will be displayed as: "A [1] footnote."

Non-automated notes

In most cases, the aforementioned system of automatic footnotes is quite enough. However, you may manage the footnotes in a non automatic fashion by "imposing" the choice of the number or even the displayed text used to craft the link.

The general principle is that you put the clickable text between angle brackets at the beginning of the note, like this:

The text is annotated[[<xxx> This is the note.]]

Following this principle, you can:

- use automatically numbered notes[[By placing the text of the note between double square brackets.]], or
- force the number of the note[[<23> By putting the number between angle brackets: < and >]], or
- use asterisks to indicate a note[[<*> By putting an asterisk between the angle brackets < and >]], or
- add notes without any visible link to/from the main text. You do this by[[<> Putting angle brackets <> with nothing between them.]], or
- give an abbreviation or name as the link to the note; in some languages this is often used for references indicating authorship of quotations[[<Rab> Fran&ccedil;ois Rabelais.]], or
- add a link to an existing note[[<23>]] by placing the number of the note between angle brackets, < and >, and giving no text to the note.

returns:


-  use automatically numbered notes [2], or
-  force the number of the note [23], or
-  use asterisks to indicate a note [*], or
-  add notes without any visible link to/from the main text. You do this by, or
-  give an abbreviation or name as the link to the note; in some languages this is often used for references indicating authorship of quotations [Rab], or
-  add a link to an existing note [23] by placing the number of the note between angle brackets, < and >, and giving no text to the note.

[1Here is additional information.

[2By placing the text of the note between double square brackets.

[23By putting the number between angle brackets: < and >

[*By putting an asterisk between the angle brackets < and >

Putting angle brackets <> with nothing between them.

[RabFrançois Rabelais.

Quotes

It is often practical, in a discussion forum, to quote an excerpt from the message which we are replying to. To make the presentation of such quotes consistent, SPIP offers the shortcut <quote>...</quote>.

For example:

<quote>Pretty good that SPIP.</quote>

Right you are, rubber duck :-)

gives:

Pretty good that SPIP.

Right you are, rubber duck :-)

Tables

To create simple tables in SPIP, you just have to create lines with "cells" separated by the symbol "|" (vertical bar), making sure that the lines start and end with vertical bars too. It is imperative to leave blank lines before and after this table.

For example, the table:

Surname Forename Age
Smith John 23 years
Captain not known
Bloggs Philip 46 years
Cadoc Baby 4 months

is coded like this:

| {{Surname}} | {{Forename}} | {{Age}} |
| Smith | John | 23 years |
| Captain | | not known |
| Bloggs | Philip | 46 years |
| Cadoc | Baby | 4 months |

Note that all the entries of the first row appear in bold. SPIP uses this identification to mean that this is the row containing the column headings and applies a presentation to it different from the other rows (different background colour). The presence of such a row is not mandatory.

You can also specify the optional caption and summary of the table. This information is quite important to make the table accessible, in particular, the summary gives a better view of the table without having to read through all the lines and columns.
This information is specified between two vertical lines before the table like this:

||Caption|Summary||
| {{Name}} | {{Date of birth}} | {{City}} |
| Jacques | 5/10/1970 | Paris |
| Claire | 12/2/1975 | Belfort |
| Martin | 1/31/1957 | Nice |
| Marie | 23/12/1948 | Perpignan |

and will be formatted as is:

Caption
Summary
Name Date of birth City
Jacques 5/10/1970 Paris
Claire 12/2/1975 Belfort
Martin 1/31/1957 Nice
Marie 23/12/1948 Perpignan

You don’t have to specify both fields. In the case of setting only the table summary, you need to remember to put the single vertical line before it. Like this: || | Summary ||

Lists and enumerations

-  Advanced management of lists and enumerations

-  A simple carriage return can be performed by typing _ (the underscore symbol) at the beginning of the line, followed by a blank space.

N.B. In traditional typography, use of a "new line" by itself is very rare (restricted, more or less, to poetry). It is often confused with a new paragraph as found in printed documents (with no additional vertical spacing between the paragraphs). Web browsers however, by default, insert a vertical spacing between paragraphs. Many users try to emulate the look of the printed page (no additional vertical spacing) by typing a simple line feed between what they consider to be paragraphs. This is an error which can make their site more difficult to maintain and develop. The correct solution is to define a stylesheet (CSS) in your templates which describes the layout behaviour of paragraphs (i.e. whether or not there is an additional vertical space between paragraphs, the amount of indentation of the first line, etc.).

-  You can create nested lists by adding asterisks after the list hyphen.

For example:

-* Your horse is:
-** chestnut;
-** bay;
-** black;
-* but my rabbit is
-** white:
-*** angora
-*** or short-haired.

gives:

  • Your horse is:
    • chestnut;
    • bay;
    • black;
  • but my rabbit is
    • white:
      • angora
      • or short-haired.

-  Lastly, ordered list can be made using the following symbol # instead of the asterisk:

-# first
-# second
-# third

returns:

  1. first
  2. second
  3. third
External glossary

You can also very quickly create a hyperlink to a definition in an external glossary. For any given term, you simply insert this shortcut in your text [?term].

So the following code: "{Frankenstein} is the masterpiece of [?Mary Shelley]." will show on the screen: "Frankenstein is the masterpiece of Mary Shelley." Remember to click the link in order to check that the term which has been entered (whether a name or common noun) is spelt correctly and links to a valid destination.

The default external glossary is Wikipedia. It is a multilingual encyclopaedia created co-operatively and opened to all contributors over the internet. Please take the time to acquaint yourself with it, to respect it and to contribute to it in order to enrich this shared fund of knowledge.

You can also reference another glossary be inserting the # symbol after the term in question, followed by the name G of the glossary. SPIP will then apply the glossaire_G function to the term to obtain the link to be inserted. This function will have been entered into the mes_options.php file. If the name G ends with numerals, they will first be removed from that name, and will form the second argument to the function, which is very useful for a glossary that is divided into numbered sections. We would then write:

[?read#man2]

to indicate that we are referencing the explanation of the term read in section 2 of the glossary named as man.

The shortcuts for referencing the language and creating a tool-tip, explained above for the external links, works just as well for glossary references as well.

Named anchors

You can define "HTML anchors" within your text so that you can construct direct links into a specific section in the middle of a page of a SPIP site. This kind of shortcut is created like this one:

[direct<-]

and which will create an anchor named direct at that point in the text. So then for article 3723, the URL http://mysite/article.php3?id_article=3723#direct will link directly to the location in the article where that anchor has been inserted.

Note that anchors are also compatible with hypertext links internal to the site. In this way, the shortcut "[this exact point->art123#precis]" will lead to the anchor named as "precis" defined within article 123.

Programming code

Some users could wish at one point to display programming code in their pages. The shortcut ... is available for this purpose.

Example: <?php     //this is some php code
echo "hello";
?>
gives

<?php  //this is some php code
echo "hello";
?>

There is another shortcut to display extracts of programming code on several lines: <cadre>...</cadre>.This will put the code in a "form" (It is often used on this current page). The advantage of this method is to make it easier to copy-paste from you web page: you just have to move the cursor to the code you wish to copy, to choose "select all" to be able to directly copy the code. Furthermore, in many browsers, this frame (cadre) allows a better rendering of the tabs at the beginning of the lines.

Here is an example:

class Text {
 var 
type = 'text';
 var 
text;
}

 class Field{
 var 
type = 'field';
 var 
field_name, 
field_id;
 var 
cond_before, 
cond_after; // table of objects
 var 
functions;
}

Bypassing SPIP shortcuts

In some cases, it can be useful to tell SPIP that some parts of a document should not be "processed" by the typographical shortcuts filter: you do not want to correct the typography or you want to display source code (e.g. in PHP, JavaScript...).

The code of this shortcut is: "<HTML>Warning; text to leave as is</HTML>", which gives: "Warning; text to leave as is".