# SPIP Installation

## install0/Setting up permissions

### Preliminary: Setting up permissions

When you install SPIP files by FTP on your own server, or if you’re using a shared kernel installation of SPIP, some of the data directories may not be created or configured correctly: in such cases, you will need to modify their configurations through your usual FTP or SSH client.

This operation concerns four distinct directories, and SPIP will indicate where they should be located. This may vary depending on whether SPIP is being used in shared kernel mode or not, and also depending on the version of SPIP that you are installing; since SPIP 1.9, these four directories have been called:
-  /CACHE
-  /IMG
-  /ecrire
-  /ecrire/data

FTP "clients" differ in their specific functions but the procedure is generally the same as detailed below:

-  select the folder for which you want to modify the "permissions";

-  find in your FTP client a feature called "change (or modify or set permissions";

-  if this feature appears as a graphical interface, check the box corresponding to "Write" for the group of "Others" (or "World" or "All users"):

-  If this feature appears in "text" mode, the numeric setting should be "777".

When you have made this modification for each directory indicated by the installation system, you must then reload the page and the procedure will automatically resume.

## install1/Your MySQL connection

### Your MySQL connection

This step consists of entering the necessary information for the connection of SPIP to the MySQL server.

-  Database address: depending on your host’s choice, this field will simply be "localhost", or your site’s address ("www.mysite.org").

-  Connection login: it is often the same login that you use to upload your files by FTP.

-  Connection password: it is often the same password as the one you use to access your site by FTP.

-  These settings cannot be just made up during the install routine: not knowing them means that your host has not given them to you. So if you do not have this information at hand, you will not be able to continue.

-  These settings are provided to you by the host of your site: to obtain them, you must contact the site host directly (do not ask the SPIP development team to give them to you, we do not know them!). Some hosts provide such information in an online guide.

-  You should also note that very often, you will need to ask your host to activate your MySQL access, or complete yourself a specific procedure to accomplish that. Several hosts claiming to provide support for MySQL databases do not activate this connection automatically at the time of the setting up of a site; an additional request from your part (after opening your account with this host) is often necessary. In this case, refer to the documentation provided by your host to know how to activate your MySQL connection. (Again, the SPIP team cannot help you here.)

## install2/Choosing your database

### Choosing your database

-  You must select the name of the database that was attributed to you by your host. This information is provided to you by your host: if you do not have it, ask him or refer to the online documentation provided by this host (it is no use requesting it from the SPIP development team, we do not have this information).

-  Very often, this information corresponds to the login of your hosting account (the one you use to connect to your site with FTP).

-  First option (more often than not): an accounts list is displayed (sometimes a bit longish, depending on the configuration set by the host). Amongst the accounts listed, only one corresponds to yours, you simply select it then and validate it to go through to the next step.

-  Second option: only one name, corresponding to your account, is displayed (your host has automatically configured its system to only display your account). Easy: select this account and validate.

-  Third option (generally, for a professional account or on a server over which you have extended rights): you must create your own database. In this case (after verifying that such an account does not exist in the above list), you can enter the name of your choice next to the instruction "Create a new database".

-  Last option (failure): your account does not appear in the displayed list, and you cannot create one yourself. This is a rare occurrence: it means that your host created an access for you to the database server, but forgot to create your account. In this case, you should contact your host directly.

## install5/Personal information

### Personal information

This step is very simple, but it should be completed carefully. Indeed, it is this step that determines your site connection identification! If you proceed too hastily, you might not be able to connect again later...

Note that once your site is installed, you will have the opportunity to change this information if and when you want to.

-  Your public identity: that is what will appear as the signature for your articles.

-  Your connection identification: this is the identification that you yourself choose to connect to your own SPIP system. This information does not need to be identical to the one your host gave you to connect to your account by FTP. On the contrary, we urge you not to use the same identification for your access to SPIP (which you choose freely) as for your FTP connection (imposed on you by your host).

## ftp_auth/Authentication by FTP

### Authentication by FTP

Some of SPIP’s functionalities have a direct influence on the structure and the content itself of the database (in particular, updates, backups and restores of the database...). For these very sensitive features, an FTP authentication procedure has been put in place as a way to restrict their usage to the few users who have been granted FTP access to the site server (more generally, if a site admits several SPIP administrators, FTP access is restricted to the main webmaster).

To be able to use these features, you have to simultaneously:

• connect to the web with your usual browser; when you launch the action, SPIP specifies a name of the format "admin_xxxxx", that you must write down (copy to the clipboard works too);
• then also connect to your site’s server by FTP, and create a file (or an empty directory) and name it "admin_xxxxx" in the /ecrire/data folder (paste from the clipboard works here as well);
• once you have created this file or directory, go back to your web browser and reload the page, which concludes the FTP authentication and triggers the desired action.

## erreur_mysql/A problem with a template?

### A template problem

When SPIP encounters an error in its communications with the MySQL database, it displays the failed query on the screen as well as the error message returned by the database (in red).

The problem could result from :
-  either from an error in the definition of your template, if you are in the process of modifying your site;
-  or from a failure in the database.

For instance, a message of the sort
> Unknown column 'articles.chapi' in 'where clause'
indicates that the loop calls a selection criteria (chapi) which is not valid for the table in question.

On the other hand, a message of the sort
> Can't open file: 'spip_articles.MYD'
indicates a serious problem in the MySQL database itself: in such circumstances, you should then ask your host to verify its installation and/or repair your database. If you have a recent version of MySQL (3.23.14 at least), you can also try an automatic repair of the database (provided your database is configured to permit this).

# Articles

## raccourcis/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.

### Simple typographical shortcuts in SPIP

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 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:

-  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:

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: 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->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->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.

find out more: links to a glossary,
ancres nommées.

-  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."

-  Quoting an excerpt (from the forum)

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 :-)

### More complete features

The following shortcuts provide more advanced functionalities, intended for a more specific use. If this is your first experience with the shortcuts of SPIP, it is probably useless to try and memorize them at this stage. You only need to know that they exist; once you really need them, come back to this page, it will then be much easier for you to memorise the shortcuts that you really need.

-  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 ||

-  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

-  Hyperlinks to an 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.

-  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.

-  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".

-  Displaying 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;
}

-------

[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.

## arttitre/Title, top title, subtitle

### Title, top title, subtitle

-  The title is compulsory.

-  The top title and the subtitle are completely optional. If you do not need them, leave them blank, the site layout will adapt automatically to their presence or absence.

Should they wish so, the administrators can disable the use of the top title and/or the subtitle in the ’Precise configuration’ section.

## artrub/Selecting the section

### Selecting the section

The menu shows the complete sections hierarchy (in the order in which they where created by the site administrators): select the section in which you want to place your article.

A lot of novice users seem to be oblivious to this feature though very simple, and drop their article "anywhere" within the site structure. Consequently, the administrators are advised to always check if an article is in the right section before validating it.

## artdesc/Brief description

### Brief description

The brief description is used for the purpose of navigating in the site: it shows briefly the topic of the article(s), in the contents page for instance.

This description is optional; furthermore it can be of any length. However, it was originally meant for short texts (one or two sentences), which will display in the lists of articles (contents, list of a particular author’s articles, sorting of articles by keywords, search engine results, etc.)

The site administrators can completely disable the display of the description in the ’precise Configuration’ section.

## artchap/Deck

### The deck

In the publishing jargon, the deck is the short text (cap) that "covers" the article. It is optional.

Administrators can, via the page ’Precise configuration ’, disable the use of the deck completely.

## artvirt/Redirection of an article

### Article redirection

This option allows you to create a "Virtual Article": it is an article which has its title, date and authors recorded in your site under SPIP, but which points to another URL.

This feature enables you to reference in your SPIP system any articles that were not created by SPIP (for instance, if you need to integrate pages created prior to the installation of SPIP into the navigation system of your SPIP site).

To signal that your article is a "Virtual Article", you just have to enter the URL of the target article in the corresponding box (for referencing items external to your site) or the internal SPIP link to the article, section, news item etc. internal to your site, e.g. (art123, br5, doc28, ...).

To remove the redirection, you simply "empty" that redirection box (delete the URL of the target article).

## arttexte/Text

### The article’s text

Pretty straightforward: this is the text of your article as its name suggests.

-  However, there is one point which could create a problem: the length of the text. It happens sometime that if the text is too long (according to our own experience, bigger than 32 Kb), it is truncated or indeed rejected during its transfer to SPIP. This problem is not caused by SPIP, but by the web browser that you are using. If you find yourself with a very long text for one browser, try to use another one.

-  The article text is very well suited for use of SPIP’s typographical shortcuts

## artdate/Date

### Date of online publishing

Generally, the article’s date corresponds to the date of its online appearance (or publication on the web site).

-  This date is automatically set to the time of the article’s validation by an administrator (therefore, to the time of its appearance on the public site).

-  However, after validating the article, the administrator can still modify this date.

## artdate_redac/Date of earlier publishing

### Date of earlier publishing

This feature was added for very specific cases, where SPIP is used to install archives and where these archives must have a publication date different from the online date.

It is a case of being able to indicate that a document has already been the subject of an earlier publication: newspaper article, book...

-  By default , this date is not displayed: the option "Hide date of earlier publishing" is selected at the time of the creation of the article.

-  If you want to specify such a date, you must select the option "Show date of earlier publishing" as well as use the drop-down menus to set it up.

Unlike the "publication date" of the article, this date is not automatically determined at the time of the validation of the article. That is why it can be modified at any time.

The site administrators can disable the use of the earlier publication date in the ’<a href="./?exec=aide_index&aide=confart" target="_top">precise Configuration’ section.

## artauteurs/Authors

### Authors

When an administrator or an editor creates an article, he is considered automatically to be the author of the article. In several cases the authors should be changed (i.e. when a third party story is added to the site, when a story shouldn’t be signed, or when it is edited by several users...)

-  Adding an author

A drop-down menu showing the list of all the site editors allows selecting and adding a new author.

If more than 50 editors contribute to the site, it becomes awkward to display them in a drop-down menu (it slows the loading dramatically); in this case, the drop-down menu is replaced by a search box: you enter the name of the author you wish to add and click on "search". If the search returns more than one author, the system will let you select the one you want.

-  Removing an author

Next to each author of the article, the link "Remove this author" allows you to simply remove this author.

It is only as the author of this particular article that the editor is removed; he obviously remains present in the list of the site editors.

-  Replacing an author by another

This can be achieved in two steps: simply add the new author and remove the first one (see above).

-  It must be stressed finally that the administrators have more power over this authors list than the editors. Particularly, the editors cannot remove themselves from an article. If an editor wishes to publish an anonymous article (without author), he must ask an administrator to perform that operation.

## logoart/Article’s logo

### Article’s logo

With SPIP you can install a logo corresponding to the article. This way, it will be possible, in the public site, to display a graphic button linking to the article.

For an article, it is possible:
-  not to use any logo;
-  to install a simple graphical logo;
-  to use an animated logo that supports "hovering" (a logo with "2 positions": the logo changes when the mouse hovers over it).

-  Images formats

When you create your images (with your usual application), you must save them in one of the following formats:
-  GIF (the GIF file could be an "animated GIF");
-  JPEG;
-  PNG (we advise against it because several browsers do not support it correctly).

In order to avoid serious operating errors, SPIP rejects image files bigger than 256 KB. Advice: because such "buttons" are elements of the graphical interface, make sure that their file size (in kilobytes) is not too big (generally, less than 10 KB) if you want your site navigation to remain fluid.

In particular, make sure that the names of your files have an extension indicating their formats: .gif, .jpg or .png. the file name itself is of no importance whatsoever provided that you do not forget the extension.

If you create a button which supports "hovering", create two different graphic files (one for the "normal" state of the button and another one that appears when the mouse hovers over the button): it is imperative, then, that the two files have the same size (in pixels).

-  Simple logo (no hovering)

To add a button, a box is provided in the left column of the article, under the title "ARTICLE’S LOGO".

Depending on your browser version, click on the button "Browse", "Select", "File"...which opens a dialogue box allowing you to select the graphic file corresponding to your button from your hard drive.

Once the file is selected, click on the button "Upload". Et voilà...! your button appears. It is followed by a button "Delete logo" that simply offers you to delete this logo.

If you do not plan to use a hovering logo, no more steps are needed.

-  Replacing the logo

You could wish to replace the logo with another file. This is achieved in two steps:
-  start by "Deleting the logo": the previous box, containing the "Upload" button reappears;
-  upload the new file, according to the procedure already described.

Due to the way browsers work, the image which is displayed then, is wrong, since it is in fact the previous version (the image is in the browser’s "cache"). Click on this image (with the right button of your mouse, or while pressing the "ctrl" key on the Macintosh) to show a contextual drop-down menu: select the option "Reload image". The new version of your logo will then appear.

-  Logo for hovering

After installing the first file, the box displays not only the logo you have just installed on the server, but adds to it a second box, entitled "HOVERING LOGO". It is in this box that you can select the second file aimed at the management of hovering.

If, after installing both files, you delete the first one (the "simple" button), the box of the second logo disappears. Indeed, in the absence of the first logo, there is no point in managing any hovering!

No intervention in the "text" of your article is necessary. At the time of the display on the public site, the management of the sections logos is entirely automated. The HTML code will be generated according to the size of the logo, and the hovering instructions in JavaScript will be created automatically as well.

## artstatut/Article status

### Article status

The article status concerns its editorial situation in the site. the article can take the following states:
-  editing in progress;
-  submitted for evaluation;
-  published online;
-  to the dustbin;
-  rejected.

These states, that only the administrators can modify, enable the site management.

P.S. the article’s status is symbolised by coloured bullets.

editing in progress

When it is created, an article is of course considered as being in progress: its authors are in the process of writing it or modifying it ...

When editing is in progress, the article appears only to its authors and to the administrators. The other site editors do not have access to it.

Submitted for evaluation

When the author considers that his article is ready, he "submits" it to the other participants, so that it could possibly be discussed collectively, before being validated (published online) or rejected.

When the article is "submitted for evaluation", it appears in the "Launch pad" page of all the users of the private area, who are requested to join in its discussion through the internal discussion forum located below the article.

Such an article is then visible to all editors. On the other hand, it can only be modified by its author or an administrator.

Published online

After being possibly discussed by the editors (during the submission stage), an article could be "validated", that is, published online by an administrator. With this action, it is then made available to all the visitors of the public site.

Once an article has been published online, only administrators can modify it. Its author- unless also an administrator - can no longer modify it, but has to go through an administrator to make any corrections.

Rejected

A "submitted" article, which does not conform to the editorial line of the site, can be "rejected" if the administrators refuse to publish it online.

A "rejected" article becomes visible only to its author and to the administrators.

However, a "rejected" article cannot be modified by its author any more, hence stopping him from re-submitting it for publication. In the case of an article requiring modification, it is then advised to re-place the article in the "editing in progress" status instead of just "rejecting" it, in order for its author to be able to modify it and re-submit it later.

To the dustbin

An article can be sent «to the dustbin» only by an administrator.

An article sent "to the dustbin" is not visible any more in the private area, even for the administrators. Be careful then, this option is "radical": the article disappears completely.

In fact, the article is still saved in the database, but becomes extremely difficult to reach with the tools provided by SPIP.

Therefore, this option is reserved to articles created by mistake, and destined to be totally removed. Often then, it is advised to choose the "rejected" option instead because it is less dramatic.

-  Finally, it is worth noting that the administrators can, at any time, modify the status of an article. Hence a published article could well be placed again in "editing" mode. However, once an article is published online, do not overdo these changes of status: you will end up with a site "full of holes", with appearing and disappearing pages, which is very annoying to site visitors.

## artprop/Submitting an article

### Submitting an article

While an article is in progress (see the section ’Article status’), it displays a button "asking for the publication of this article".

Only the article’s author is allowed to perform this operation.

This means that the article is "submitted for evaluation", that is, submitted to all the other editors who are requested to comment on it while awaiting to be validated (published) or rejected by the administrators.

Warning: once the article is submitted for evaluation, it is not possible any more for the author to reconsider his decision and to re-place his text in the "editing in progress" mode. Consequently, the operation "Ask for the publication of this article" must only be performed after the author makes sure that his text is complete and final. Only an administrator can place the text again in the "editing in progress" mode.

# Sections

## rubhier/Hierarchical structure of the sections

### Hierarchical structure of the sections

The sections structure constitutes the framework of your site; it is this structure which will determine its interface, its method of navigating through the site, the relationship between articles and news items...

In SPIP, this structure is of the hierarchical type: a section can contain sub-sections which can contain other sub-sections themselves, and so on.

In the above example, we clearly see that section 222 belongs to section 22, which itself belongs to section 2 which does not belong to any other section (in this case, we say that section 2 is in the site root.

By hierarchical structure we mean that a section is a child of only one other section (and not of several) and that a section cannot be the child of one of its own sub-sections (which means that SPIP does not allow circular structures). This very classical structure was adopted because of its ease of use.

Only administrators can create, modify or delete sections.

## rubrub/Selecting a section

### Selecting the section

The operation of this drop-down menu is very simple: the menu displays the whole section hierarchy (in the order in which the site administrators created them), you just have to select the one in which you want to place your sub-section.

-  Moving a section

Through this drop-down menu, you can transfer this section to make it the child of another different section. In this case, you must understand that the set of sub-sections contained in this section will "move" along with it in the hierarchy of the site. In the same way, the articles contained in this section and its sub-sections will move along with the original section.

## rublogo/Section’s logo

### The section’s logo

You can install a logo for each section on your site. This logo could be unique (fixed image) or animated to handle mouse hovering.

The installation of images for this section logo is exactly the same as the installation of an article’s logo.

P.S. The section logos have a recursive behaviour: in the event that a logo is missing for a given section, SPIP will try to substitute it with the logo of a parent section:

In the above hierarchy, and when there is a missing logo for section 221, SPIP will substitute in (an only for visits to the public site) the logo of section 22 or if that one is also missing its logo, SPIP will use the logo from section 2. Otherwise, SPIP will display the logo installed in the site root for the whole site.

You should note also that, if the webmaster has programmed it that way, a section logo could be used as a default substitution logo for any articles that this section contains.

# News items

## breves/News items

### News

News items are a simple and fast method of publication in SPIP. Unlike articles, news item are made of a very small volume of information: a title, a text and a hypertext link. Therefore, the news system is ideal for a follow-up of current events, a press review, etc.

## brevesrub/Selecting a section

### The positioning of news in the site structure

In order to ease their use (and to avoid redundancy between news and articles), integration of news in the sections hierarchy is reduced to the bare minimum: news relate only to sections located at the root of the site.

In our example, we can put news in sections 1 and 2 but not in their sub-sections (unlike articles which we can put anywhere). Because of this, the layout of the news page is created in terms of these upper sections and the drop-down menu that offers to set the position of the news is very short indeed.

### News hypertext links

In order to ease the use of news as part of an online press review, each news item can be attributed a hypertext link. You just indicate the name of the referenced site or article and its URL.

Of course, this information is optional.

P.S. This linking system does not prevent the insertion of hypertext links in the body of the news item’s text, but the separate hypertext link allows the webmaster to apply a specific graphical treatment to it.

## brevesstatut/News item’s status

### News status

The management of a news item is simpler than that of an article. A news item does not have an author. Its status is either “Submitted” or “Validated” or “Rejected”. Only administrators can modify its status.

-  News item submitted

“Submitted” news items are indicated on the page “Launch pad”: all the editors can consult them and edit them. Administrators are presented with two buttons - enabling their immediate validation or rejection.

-  News item validated

“Validated” news items are those that appear on the public site. Only administrators can edit them once they have been published.

-  News item rejected

A “rejected” news item is not published on the public site and only administrators can have access to it in the private site.

## breveslogo/News item’s logo

### News item’s logo

You can install a logo for each news item on your site. This logo can be unique (fixed image) or animated to manage mouse hovering.

The installation of the images for this news item logo is exactly the same as the installation of the article’s logo.

# Images and documents

## ins_img/Inserting images

### Inserting images into the text

SPIP offers you the possibility to illustrate your articles and news items with images. This is achieved in a number of steps: you must first upload the image file to the site, and then insert the image inside the text.

Preparing: Image formats

When you create your images (with your usual application), you will need to save them in one of the following formats:
-  GIF; (extension .gif)
-  JPEG; (extension .jpg)
-  PNG (extension .png).

You should particularly make sure that your files names are created with an extension indicating their format: .gif, .jpg or .png. If you install a file with a missing extension in its name, the system will not know how to use that image file.

Step 1: Installing the images on the server

Before you can insert your images in the text, you obviously have to install them on the server. Using the SPIP system, this is done through the normal graphical interface of the private zone.

When you “modify” an article or a news item, the left column displays a form labelled: “Add an image”. This is a form with a text field followed by a button labelled (depending on which browser you use) “Browse”, “Select”, “File”...

When you click on this button, a dialogue box opens to allow you to browse your disk resources and select the graphic file you want.

Having done this, you then need to click on the button labelled: “Upload”.

If the operation succeeds, your image will appear in the left column, accompanied by several settings...

Step 2: information concerning your image

Once your image has been uploaded on the server, a new panel will be displayed on the left of the screen. It contains all the information that relates to that image (part of this information will be hidden by default, so click on the small triangle to “unfold” the information box).

-  Thumbnail display. A preview of your image is displayed. If the image is too large (more than 200 pixels wide), a thumbnail of the image is automatically calculated and displayed instead.

-  SPIP shortcuts. See below for more information: SPIP will remind you of the 3 “shortcuts” available which enable you to insert this image within your text. It is worth noting that every image is uniquely “numbered” like these examples: “IMG1”, “IMG2”... These “shortcuts” are used in the third step.

-  Image size. Just above the image, its width and height (in pixels) are displayed.

-  Image title and description. If you want to, you can enter a title and a description for each image, such as an explanation, the photographer’s copyright notice...

-  Delete this image. As you can guess, the “Delete this image” button allows you to delete this file if you made a mistake or if you decide you do not want to use the image in the text. It is recommended that you delete unused images to prevent clogging the server with unwanted files.

You can repeat this operation with as many images as you wish (an article or a news item can contain as many images as needed).

Step 3: Inserting an image inside the text

At this stage, the graphic files are now stored on the server, but you now need to indicate where they should be inserted into your text. There is no need to write complicated HTML code for that, as SPIP offers you "shortcuts" to insert your images very easily.

-  Images without captions

For each image, look at the 3 shortcuts:
-  <img1|left>
-  <img1|center>
-  <img1|right>

Copy one of these shortcuts (the image number corresponds to the number assigned to the image which is unique for each file), and paste it inside the box labelled “Text” in the position where you want the image to appear. “left” aligns the image to the left, “right” to the right and “center” centres your image in the text.

When the page is displayed, SPIP will replace these shortcuts with the corresponding HTML tags by automatically calculating the dimensions of the images.

-  Images with titles and descriptions

If you entered a title and/or a description, the code <img...> is replaced with:
-  <doc1|left>

-  <doc1|center>
-  <doc1|right>

These shortcuts are used in the same way as above; however, when you insert one of these “shortcuts”, SPIP inserts not only the image but also the title and the description that you previously entered. This means that your image will display with whatever explanation, copyright notice, the name of the artist etc. you have previously entered. This information is presented according to the standard "model" for "doc" elements.

## ins_doc/Attaching documents

### Attaching multimedia documents

The SPIP interface allows you to integrate multimedia files on your site (sound, video, text,...).

Editors can attach documents to articles. These documents can be located either at the end of the text (a bit like “attachments”), or inside the text as a preview vignette (or thumbnail).

Site administrators can also install documents directly into the sections of the sites.

You should note the important difference between those two methods: in articles, documents are “attachments” which are useless without the article to which they are associated (in the site navigation, you can view these files from the articles); when they are installed directly in the sections, these documents become elements of the site like the articles and news items, and not just an informational supplement any more.

Step 1: Installing the documents on the server

The installation of files on the server is done by using the "Attach document" interface for the articles and “Publish a document in this section” for the sections.

Notice that, for the articles, this interface appears in two different locations: at the bottom of each article’s page and on the left (under the images) when you modify an article. Those two interfaces have exactly the same functions, and you can use either of them according to your needs. As for the sections, the installation of documents is done on the page for the section in question.

Before you install your files, you have to create them on your computer. The document upload interface reminds you of the list of formats supported by the system. You should make sure that you name your files with the correct extension (for instance, “xxxxxx.mp3” for an MP3 file.)

The interface is the same as the one for the images: the button labelled “File” or “Browse” (depending on your browser) opens a dialogue window allowing you to select the file on your hard drive. Once you have selected the file, click on “Upload” to send a copy of it to the server. Warning: this operation may take a lot of time, depending on the size of the file. You should also note that depending on your server host settings, large files might be rejected; in this case you can bypass this limitation by installing your files via FTP.

Step 2: Information details and thumbnails

Once the file has been transferred to the server, an information panel is displayed. Several operations can be performed using this panel.

-  Preview thumbnail

This concept is very important: unlike images which can be inserted directly into the text, documents do not appear on the corresponding page straight away. A preview thumbnail is displayed to the visitor, who can click on it should he need the corresponding document.

The top part of the information box allows you to choose the preview thumbnail. You can accept the default thumbnail or install a customised logo.

The default thumbnail is installed automatically by the system, depending on the document format. The advantage of accepting this thumbnail is that the symbols for documents of the same type will be consistent across the whole site.

If you prefer, you can install a logo (preferably small and of the format GIF, JPG or PNG) which will appear instead of the default thumbnail. Once this logo is installed, a “Delete the customised thumbnail” link allows you to go back to the default thumbnail if necessary.

-  In the article modification page, the “shortcuts” allowing you to insert a document in the text are identical to those for the images.

-  The bottom part enables you to enter a title and a description for your document. There is no need here to enter the format or the size of the multimedia file, as this information will be automatically provided by the publishing system.

-  Finally, the “Delete this document” button is used to delete any unnecessary files. You should note that it is essential to delete any unwanted documents, otherwise they will still display on the public site.

-  Concerning the documents installed in the sections, you can also modify the publication date of the document (according to the same principle for modification of articles and news). Once these settings have been submitted, any section documents are immediately available on the public site (there is no need to validate them like there is for articles and news).

Step 3: Inserting documents into the text for articles

Concerning the documents associated with articles, you can simply install them and enter the information (steps 1 and 2 above). When you publish the article, these documents will appear at the end of the text as a list of attached documents.

However, you can also decide to insert the preview thumbnails inside the text. This will then insert images that the site visitor can click on that are inserted inside the article’s text.

The procedure here is exactly the same as the one for the images, the only difference is that the thumbnails will be elements that you can click. Insert a shortcut like <imgxx|yy> or <docxx|yy> whether you want to display the thumbnail alone or with its associated title and description.

You should note that any documents that you install inside the text will not appear underneath the article text any more. For articles, there are two locations where the documents will display: either inside the text (thumbnails that you can click on), or at the end of the article under the reference to “Attached documents”.

Special cases: Video and sound documents

Some multimedia files are meant to be displayed directly on a web page (e.g. a video clip inserted directly into the article).

To be able to insert such a document inside the text as an embedded multimedia animation and not just as a clickable thumbnail, you need to enter its dimensions: width and height strictly greater than zero (for sound files you choose the width you wish to attribute to the play cursor and a minimal height such as 25 pixels).

You should note that the boxes allowing you to enter the dimensions will only appear for the documents of certain formats supported by SPIP for their integration in the articles (namely: avi, quicktime, real, flash).

Once you have entered these dimensions, an additional SPIP shortcut will be provided, in the shape of <embxx|yy> (being a shortened form of “embed”).

If you are already familiar with this sort of integration, you will be happy to know that you can add additional parameters such as:

<emb54|center|autostart=true|quality=high>

## ins_upload/Installing files via FTP or SCP

### Installing files using FTP or SCP

Some servers do not allow files to be uploaded through a web interface. Or which forbid the uploading of particularly large files using such a mechanism. And even when you can do this, it can be a very slow process doing so. SPIP allows you to bypass these limitations by installing files used for images and documents by using FTP or SCP.

Of course, this operation is restricted to users who have access codes to the HTTP servers’ disks.

-  The upload folder

The location of the folder where you need to place the files depends on the status of the site and the version of SPIP that is installed. Prior to SPIP 1.9, this folder was the upload sub-folder inside the root ecrire directory, and SPIP would only show the contents of this directory to the site’s principal administrators. From SPIP 1.9 onwards, the upload folder is a sub-folder of the root tmp directory, but is still called upload and SPIP will only show all of its contents to the site’s principal administrators (those nominated as having "webmaster" privileges. But in addition to that, there is also a facility to have as many sub-folders as there are restricted administrators, with the names of these folders being the login names of those administrators. For each restricted administrator, SPIP will only show the contents of the folder with the matching name.

After installing your files by uploading them with FTP or SCP, make sure that they are read accessible by the HTTP server (both the folders and the files stored in those folders).

-  The drop-down files menu

Having done that, a drop-down menu appears automatically after the interface of web files uploading and displays the files contained in this folder. You only have to select the file that you need and validate your choice. Note that SPIP will only display the files known to be safe, which excludes any files not stored with the correct MIME filename extensions, especially those that have no extension at all. You can work around this restriction by using one of the permitted file extensions (e.g. rename x.php as x.txt), which allows you to load the file in place while still preventing that file being used in an abusive manner on the site. You can then use the document’s description form to indicate what the file’s correct original name used to be.

Using this menu, you can then select the file that you want and validate your selection.

If the operation succeeds, remember to delete the file from the /ecrire/upload folder (the system has created a copy of this file in another location on the server, so your original file is therefore not needed any more) to avoid overloading the drop-down menu with entries that are no longer necessary.

-  All the files at once

If you want to install several files at once in the /ecrire/upload folder, an additional feature is available for you on the site interface: you can install all these files in one batch. This can prove to be very practical to create large portfolios very quickly.

### Collections of images and documents

You can easily add a collection of images and documents in one go by uploading a zip archive containing all of the documents in question.

SPIP will then suggest adding this archive "as-is" to the article (i.e. as a zip file) or to extract the archive to attach its contents to the article, or even to do both at the same time. If the operation you choose is to unzip the archive, then of course the same file exclusion mechanisms as described above still apply to limit the potential danger of any member files. You can additionally request that the name of each file be automatically recopied as the name of the document thereby attached to the SPIP object in question.

# Keywords

## mots/The keywords principle

### Keywords

One of SPIP’s most significant restrictions is its hierarchical structure: each article can belong to only one section, which can sometimes lead to classification problems.

Keywords offer a way of cross navigation inside the site. By associating one or more keywords to an article, we have at our disposal a way to create links to other articles with similar topics but which are located in other sections.

Keywords really only offer a benefit when each one is associated with several articles as a way of linking such various to each other.

Only the administrators are able to create and modify keywords.

Very often the section structure can work without keywords if it has been carefully constructed: articles with the same topic are simply located in the same section, so it’s quite pointless to add keywords that simply repeat a topic which is common to them already. In such cases, a site administrator can totally disable the use of keywords on the site’s content configuration page.

## artmots/Keywords

### Keywords

In order to provide alternative navigation within a site, it is possible to assign Keywords to articles, news, and referenced sites. This allows the site visitor to not only browse the site content from section to section, but also from one article dealing with a topic (indicated by a keyword) to another article associated with that same keyword.

For any given article, news item or site, it is possible to specify as many keywords as are needed.

A drop-down menu lists all the keywords of the site, and is very simple to use. Note: if the number of keywords exceeds 50, this drop-down menu is replaced by a mini search facility: just enter the desired keyword and click on "Search".

P.S. Only the administrators can create keywords from within the page dedicated to their management (the "Keywords" button from the top navigation bar option "Site edit").

Administrators can disable the use of keywords for the whole site on ’the site’s content’ configuration section.

## motsgroupes/Keyword groups

### Keyword groups

If you use a lot of keywords, it can become awkward to manage them efficiently. To help you organise them, you are able to create groups that contain various collections of those keywords. The interface then becomes a lot tidier (for instance, a "Countries" group could contain "Namibia", "Germany", and "Peru" while a "Topics" group could contain "Unemployment", "Poetry", "Animals", etc.).

# Referenced sites

## reference/Referencing a site

### Referenced sites

SPIP offers a complete management system for lists of links to other sites. This system is very comprehensive and notably offers:
-  grouping of these lists in sections (the same sections which contain the articles or specific sections dedicated just for the purpose, in the same way as a links directory);
-  association of a logo with each site;
-  assigning of keywords with each referenced site;
-  addition of a customised description for each site.

Furthermore, and for the sites that permit it, you can automatically fetch the latest articles published on those sites (refer to "Syndicated sites" ).

Referencing a new site

A button labelled "Reference a new site" is shown on every section page in your site to allow you to add a new site.

The "traditional" way is to indicate the site’s name and its URL, then to insert a description. It is also possible to select the section of your site in which this site reference link is to be inserted.

A panel at the bottom of the page allows you to manage any possible syndication of the site’s contents. For more details on this matter refer to the explanation of syndicated sites. For a straightforward reference link, you just select the option "no syndication".

Quick referencing

During the creation of a new site reference, a panel is shown at the top of the page to offer you a quick reference of a site without needing to enter its name or description by hand. To use it, just enter the URL of the page you wish to reference and click on submit. As far as it can, SPIP will access that address and try to automatically fetch the page title and a description. You can modify this information at a later time.

Who can propose sites to be referenced?

In the "Site’s content" configuration page, administrators can specify that either only administrators have the possibility to propose sites, or also the editors, or even also the site visitors (in the last case, a form on the public site will give the visitors the opportunity to propose sites).

In all of these cases, it is still only the administrators who can validate these referencing suggestions. When a site referencing is suggested, all the participants to the private area can discuss the relevance of the suggestion in a forum linked to each site.

## rubsyn/Syndicated sites

### Syndicated sites

Sites developed by an automated publishing system (like SPIP or phpNuke) can easily create a file that always details a list of their latest publications. In particular, there is standard format for this sort of file called the "backend file".

This file can be easily and automatically analysed in order to regularly fetch the list of latest news articles from such sites. In this way, SPIP allows you to display, on your own site, the list of the latest articles published by other sites.

For each referenced site in your own sections, you have the possibility to fetch the list of the latest articles published on that site. That is, of course, if the referenced site offers a backend file.

-  How to find the files "backend.php" files?

For sites managed under SPIP or phpNuke, those backend files are easy to locate: it is simply a file located in the site root and called "backend.php3" (or "backend.html"). For example, as regards the uZine (http://www.minirezo.net/) site, the backend file address is:

• http://www.minirezo.net/backend.php

Other examples of backend files include:

• http://www.davduf.net/backend.php
• http://www.vacarme.eu.org/backend.php
• http://www.vakooler.com/backend.php
• You should note that The other portal provides such files for the sites which it references, even if those sites do not have their own backend system. You will find on that page about thirty backend files for the sites referenced by The other portal, as well as a handful of theme files.

-  Adding a syndicated site to your own site

When you reference a site in one of your sections, in addition to indicating the name of the site, its homepage URL and a description, you can choose to syndicate it (therefore, a syndicated site is primarily a referenced site from which we ask SPIP to fetch the list of the latest publications).

To do this, simply select the "syndication" option and enter the URL of the backend file of the desired site. Immediately after submitting your entries, a message will be shown to tell whether the syndication has succeeded or not.

If the syndication fails:
-  make sure you entered the correct URL for that site;
-  make sure that the site you are trying to syndicate is actually accessible online.

-  Quick referencing

The quick site referencing feature (directly enter the site’s URL and SPIP will undertake the task of fetching the necessary information automatically) is very well suited for syndicated sites. Indeed, instead of entering the homepage URL during the referencing, you should enter the backend file URL of this site: SPIP will automatically fetch a large volume of information and proceed directly with the syndication.

-  Syndicated articles

When the syndication succeeds, SPIP displays the list of the latest articles published by that site. Look at the help page dedicated to the management of those links.

-  The backend file of your own site

SPIP automatically creates the backend file of your own site. However, do not forget to set up the name and the URL of your site on the The Site’s contents page.

## artsyn/Syndicated articles

### Syndicated articles

When you request a site syndication, SPIP displays a list of the latest articles published on that site, under the label "Syndicated articles pulled out from this site".

For each article, SPIP displays:
-  the article’s title (you just click on this title to access the article on its original site);
-  the article’s authors, should there be any;
-  the article’s description, should there be one.

This information, pulled automatically from the referenced site, cannot be modified.

Furthermore, for each article, a button labelled "block this link" allows you to block its display on your own site (because the article does not suit you or there is an error disabling this link...). You can restore the display of this article on your site at any time.

It is also possible to request that each future link coming from the site should be blocked pre-emptively. The articles pulled out will not be displayed unless you validate each one of them "manually".

## confhttpproxy/Using a proxy

### Using an HTTP proxy

If your site is behind a firewall, you might find that you need to configure an HTTP proxy to be able to fetch the new syndicated sites over the internet.

This proxy must allow outgoing requests without any authentication.

In your site configuration (in the section labelled "SPIP features"), enter the proxy in the following format:

http://proxyname:port/

where proxyname is the name of the server acting as a proxy, and port is the number of the TCP port (most frequently 3128, 8080, or even 80) which will handle the requests.

Warning: This set-up is global: SPIP will fetch all the syndicated sites through this proxy. Since SPIP 1.9, it has been possible to specify that certain hosts should not use this proxy. But for any prior versions of SPIP or if you need more precise configurations, you will need to contact your own network administrator directly.

# Internal messaging

## messut/ Messages between users

### Messages between users

SPIP makes it easy to exchange messages between users of the site, without going through e-mails.

When a message is «sent» by a user to one or several other users, it turns into a private discussion forum. That way, once a message is sent, a discussion can take place, in the shape of a forum located under this message. With SPIP, we can consider that a message is also a private forum (that is, there is no point in exchanging a large amount of messages to hold a discussion, you simply «remain» in the same message with your correspondent to "chat", thanks to the private forum associated with him).

Note: Messages between users and their associated forums are private, this means that SPIP does not offer any interface for the administrators to see those messages. However, bear in mind that this confidentiality is very relative: a site administrator armed with a direct access tool to the database, can always check these messages.

-  Creating a message/discussion

The simplest way to send a message is to click on the green logo (a small «M» followed by a triangle) displayed next to the recipient name. This will immediately opens a new message.

The second way is to use the button labelled «New Message» which appears on every page in SPIP. This will open a new message without recipient. Before sending the message, you should, of course, specify the recipient.

The editing interface of these messages is very straightforward.

The only common error to avoid is to forget to «send» this message: as long as the message has the status «Editing in progress», only its author can have access to it. It should then be sent in order for the recipients to see it (warning: once a message has been sent, it cannot be modified anymore).

-  Adding/removing a recipient

At any moment in time, it is possible to add a recipient: either during the editing of the message or after it was sent (for instance, to add a new participant to a discussion in a forum which is interesting to him).

In the same way, you can remove a participant at any moment. Besides, a button labelled «Stop participation to this discussion» allows any participant to remove himself from a discussion.

-  Making a appointment

Any message can be turned into a appointment: this means that it is linked to a date displayed in SPIP’s calendar.

-  Can we write to any user of the site?

Some editors could be unreachable (they do not show in the list «Add a participant» and their name is not accompanied by a messaging logo):
-  editors could decide individually, not to use the internal messaging system;
-  editors who did not connect to the private area for more than 15 days are unreachable (for these users who seldom connect, it is preferable to use ordinary e-mails).

## messpense/ Memos

### Memos

A memo («memorandum» or «memory juggler») is shaped like a message: but it does not require any recipient. Only its author can have access to it.

It is clear from its name that the memo aims at recording elements we would like to preserve.

-  Inserting a memo in the calendar

The most practical use of the memo is to give it a date. That way, the memo acts as a reminder to its author until that date (and during the following 24 hours) and it appears in SPIP’s calendar.

Note: As with messages between users, we attract your attention to the relative confidentiality of these memos. SPIP does not offer any interface for the administrators to see your messages. However, other direct access tools to the database, are capable of doing it.

## messcalen/The calendar

### The calendar

SPIP’s calendar offers two types of information:

-  information common to the whole site; these are the published articles and news - That way, the calendar allows articles retrieval according to their date of online publication;

-  private information; these are the messages between users and the memos endowed with an appointment date. This calendar then, can act as a reminder and a diary.

You should note that each calendar day is accompanied by a small blue logo: this logo allows the creation of a memo directly associated to that date (the time of the appointment can be adjusted more precisely thanks to the editing interface of this memo).

## messconf/Messaging customisation

### Messaging customisation

Each user can customise the configuration of internal messaging.

Note: Site administrators can decide not to use the messaging system or the list of connected users. Anyway, if an option is disabled globally for the whole site (by an administrator), editors cannot have access to it.

-  Do not use internal messaging

If internal messaging is available for the whole site (option reserved for administrators), each user can take an individual decision not to use it (That is, he simply does not wish to exchange messages with other users through this system).

-  Do not use the list of connected users

When this feature is available (by the administrators choice), and while he is using internal messaging, an editor can take an individual decision not to participate to the list of connected users.

This feature continuously displays the list of connected users in real time, which makes it easy for users to take part in quick discussions. Some users may find this feature intrusive and/or may not wish to be «disturbed» when they connect. They just have to disable this option: they will not appear on the list of connected editors anymore, and this list will no longer show on their pages.

Note: When an administrator indicates that he does not wish to appear on the list of connected editors, the list still shows: he «sees» the others, but the others do not «see» him.

# Forum monitoring

## suiviforum/Forum monitoring

### Forum monitoring

The forum monitoring page is an important element of your site if you allow the use of public forums (for more on this subject, refer to the documentation about public forums configuration). It is on this page, in fact, that forum moderation is conducted.

-  Message display

Messages are not displayed here according to their hierarchical structure (by threads), but one after the other in reverse chronological order (the most recent first). On the other hand, each message is accompanied by the name of the article it refers to.

-  Deleting messages

The main feature here is the ability to delete contributions. Warning: this operation is irreversible. However, a deleted message is not removed from the database: it appears on this page surrounded by a red frame, accompanied by the date that the message was received and the IP address of the sender.

-  If you already configured public forums with the option of a pre-publishing moderation, pending messages are framed in yellow and offer two buttons: delete this message and validate this message.

# The site configuration

## confnom/Name and URL of your site

### Name and URL of your site

The name and URL of your site are, in particular, used to generate the "backend" file which enables the syndication of your site (i.e. display of the last 10 articles published by your site to another site).

Your site’s URL must be the address of the homepage folder not that of the corresponding HTML file; therefore it must be ended with the character "/". If your homepage address is:

http://www.mysite.net/index.html,

then your site’s URL should be written like this:

http://www.mysite.net/

## confart/Articles content

### Contents of the articles

Articles are comprised of a number of elements: the title, the top title, the subtitle, the description, the deck (or standfirst), the postscript... However, some sites do not need all these elements: either the editors do not use them or the graphical layout of the public site does not include them.

In order to make the site’s management interface less cluttered and/or simply to stop the editors from using certain elements that the webmaster does not wish to include, "The site’s content" configuration page allows you to completely disable the use of any of these elements.

N.B. It is important to understand that, with regard to the choice of simplified interface / complete interface, which only influences the interface of each user, the choice of the options of "The site’s content" configuration page affects all of the site’s users. So if you disable the use of the top title, none of the editors nor the administrators can use top titles in their articles.

The backend interface will also adapt to the presence or the absence of these elements. If you disable the use of keywords, the corresponding button in the top navigation bar will simply disappear.

## confdates/Post-dated articles

### Publication of post-dated articles

It is possible for administrators to modify an article’s date of online publication (when this article is declared as "published online").

But how should SPIP behave when we set this date of online publication to a date value in the future? Should SPIP publish all the articles, whatever their publication date (risking an odd display with an article showing "31st of May 2002" while we are only on the 21st of May), or should it wait for the due date (31st of May in this case) before displaying this article on the public site?

-  The main advantage of this operation is to be able to schedule the publication of a series of articles in advance. Practically speaking: the webmaster goes on holiday for a month; if he already wrote several articles, he can place them in the private area as "published online", but set for them publication dates spread over the month while he is absent. That way, rather than publishing online a bundle of articles in one go, then nothing for a month, the site will regularly publish "new" articles despite the absence of their author.

-  As for a science fiction site publishing a Martian chronicle, it should find it desirable to disable this feature, unless it wants to wait for the year 2030 to publish its stories. The same thing applies to a monthly online publication when it publishes its April issue on the 20th of March.

## confforums/Operating the forums

### Operation of the public forums

The method for managing public forums varies from one webmaster to another, and more specifically according to the actual needs of the site. Some webmasters do not want forums at all, some want free access forums, and yet others prefer to moderate the forums pre-publication, by publishing the messages only after they have been validated by an administrator.

SPIP allows you to determine the operation of your public-facing forums (the forums which are internal to the site’s management team are always managed as open forums for all the editors, and moderated post publication, which means all such forum entries are published internally by default, but can be vetoed at any time later on).

-  Disabling the public forums

When the forums are disabled, the interface for making such forum contributions disappears and any old contributions are no longer displayed (they are not deleted from the database, but their display is simply interrupted). This option stops the operation of the forums, even if display of the forums is still coded into the site’s layout (templates).

You can use it either as a permanent measure (the site never provides discussion forums) or as a temporary setting (suspend forums activity to discourage a relentless spammer or to go on a troll-hunting expedition ... or simply if you are transferring your site to another server and don’t want to lose any contributions in the process).

-  Post-publishing moderated forums

When forums are moderated a posteriori, contributions are displayed as soon as the users have submitted them. You are then free to use the forums follow-up page provided by SPIP to moderate these messages with various degrees of severity. a posteriori moderation is the default mode for SPIP.

-  Pre-publishing moderated forums

In a priori moderated forums, user contributions are submitted and stored in the system but not immediately displayed. Administrators must use the forum follow-up page provided by SPIP to validate (or reject) each message.

-  Forums accessed by subscription

If the forums are accessible by subscription, users wishing to contribute must register by providing their e-mail address. They then receive their site identification credentials by e-mail, so that they can log in in order to submit comments to the forums. For editors who already have access to the private site, this identification corresponds to their usual login credentials.

This mode is a compromise between the need for responsibility (participants must provide a valid e-mail address) and the absence of a priori moderation (once they are registered, these users can post their contributions directly).

Furthermore, this mode allows you to exclude users who misuse forums (black-listing). In fact, when you delete (via the forums follow-up page) a contribution posted in the "by subscription" mode, you can have access to the "file" (extremely small) of the author of that contribution. You can simply dispatch that author "to the dustbin": his identification will not work any more and he will not be able to obtain a new one with the same e-mail address.

Warning: the "forum by subscription" mode requires that your host supports automated e-mailing. If this is not the case, perhaps you should change your host ;)

## confbreves/The news system

### Enabling/disabling the news system

Some sites do not use the news items, i.e. short articles without specific authors. Or perhaps the webmaster simply decided not to include them in the layout of the public site.

In this case, you can simply tell SPIP to disable them. Doing so will mean that the editors cannot create them, and the interface will be just that little less complicated.

## confmessagerie/Internal messaging

### Internal messaging

SPIP offers an internal messaging system (a section of the present documentation is dedicated to messages between users, to memos and to the calendar).

You can decide to use all or parts of this system.

-   Enabling/disabling internal messaging

A reason for not using internal messaging could be the space that these messages consume in the database: these messages (such as the messages of the forums linked to your articles, for instance) are stored in the database and therefore take up disk space on your web host account. Moreover, the internal messaging features add an additional burden on the machine which is hosting your site (database queries): if your machine is of a small configuration (and/or very slow), you might prefer to lighten its workload by disabling the messaging.

-  Enabling/disabling the list of connected editors

If you enable this feature, the list of users connected to your site’s private area will be permanently displayed in the private zone. This will notably encourage more communication using instant messages between your users.

This feature does involve additional queries being made to the database; you might better disable this feature on a slow machine. It is also worth noting that some users may find this feature intrusive.

You should note that: When you enable the above features for the whole site, it is still possible, for each individual user, to disable these features for their own usage. This way, if a user finds the internal messaging functions unnecessary or intrusive, he can simply disable this feature for his own use.

## confstat/Visits statistics

### Visits statistics

SPIP contains a very simple system allowing you to count and track the number of visits to the site and to each article. It also allows you to know which other sites directed visitors to your site and to each article.

-  Number of visits

Every day, SPIP identifies the "unique visitors* to your site according to their IP addresses. This system is fast and relatively reliable (it is a relatively accurate estimate of the number of visitors to the site, and not just the "hits" or "page views"; a visitor coming back several times to the same page is counted as a single "unique visitor").

-  Direct visits or referrers

A "direct visit" is an arrival at the site or to an article’s page from another web site which contains a hypertext link to your own site (the former is itself considered as a "referrer").

For the entire site and for each article, SPIP displays the list of the main "referrers" (the pages displaying a hypertext link to your site), accompanied by the number of "direct visits" (the number of visitors who followed this link).

-  A "relatively" reliable system

A complete system for traffic analysis is a very demanding application in terms of power and memory; therefore, the SPIP system is very simplified in order to be as fast as possible and as small as possible on the server’s hard drive. Furthermore, the counting of "unique visitors" is based on the visitors IP address every day, which is not the most precise method, but we still consider that it provides "relatively" reliable information.

If you want a more thorough analysis of your site’s traffic, you could use another system more specialised for such statistical analyses.

-  A daily calculation

The traffic follow-up system integrated to SPIP performs calculation sof the number of visitors and referrers daily (not in real time). Consequently, some information may sometime appear incoherent because it does not integrate the visits of the current day. If in doubt, the specific page displaying the statistics is the one most reliable and detailed. Therefore, the statistics page of an article is only available after the first day of publication of that article (figures are unknown before that because SPIP has not analysed them yet).

-  Enabling/disabling statistics and referrers

The counting of the number of unique visitors should not occupy a lot of space nor use up a lot of computing power. There is little point, then, in disabling it unless the server is very slow.

On the other hand, the system of counting referrers and direct visits is considerably more demanding. It is, therefore, disabled by default. It is recommended that it be enabled only on servers with no problems in computing power (servers which already struggle to calculate lengthy articles can certainly not cope with the burden of referrer calculations).

-  N.B. The disk space and computing time necessary for the monitoring visits and referrers will increase with your site’s traffic. The more a site is visited, the greater will be the technical needs requirements to execute those tasks.

## confmails/Automated e-mailing

### Automated e-mailing

Editors and administrators do not necessarily spend their lives in the site management area. To facilitate collective work and follow-up of the site’s life, the system can advise the site’s managers by e-mail of certain events that may occur on the site...

Warning: some hosts disable the automated e-mailing feature. If you face this situation, the following options can not be enabled.

-  Follow-up of public forum messages

In order to enable authors to monitor the discussions triggered by their articles, this option offers to automatically forward to the author each message posted to his articles.

If this option is enabled, the author(s) of the article will receive by mail the text of any message posted to their article as well as a reminder of that article’s URL; with one click, the author(s) can then go to the page of the article and if they so choose to, post an answer to that message.

-   Monitoring editorial activity

When an article is submitted for validation or published, you can ask SPIP to notify you about it by mail. In this way, participants of the site are informed in real time of any significant developments made to the site.

For a collective site (several editors), we recommend that you create a mailing list of editors (SPIP does not provide the mailing list feature) to which you can post such messages.

-  News announcements

This feature provided by SPIP offers to create e-mails of the kind "Latest news": if you enable it and set up the delay between announcements, an e-mail is sent regularly to the specified address, summarising the latest published articles and news.

This feature is very simple to implement: if you enable this option by fixing the delay to 7 days, then once every 7 days, SPIP will send the list of articles and news items published during those 7 days to the specified address.

A "Send now" button triggers the immediate sending of this summary e-mail (and starts a new time interval of 7 days before the next such e-mail will be generated and issued).

You can send this latest news announcement mail to the main webmaster’s address (who will forward it), or, if you prefer fully self-managed sites, you can send the mail to the list of your subscribers (SPIP does not provide the mailing list feature).

## confmoteur/Integrated search engine

### Enabling/disabling the search engine

SPIP contains its very own internal search engine. When it is enabled, a system for analysing the articles will index the contents of all your articles. This operation, even though it then offers subsequent extremely fast searches, requires a lot of work from the server hosting the site. In the case of a slow host, this may well cause a few problems.

For this reason, you can enable or disable the system indexing.

The data managed by the search engine integrated to SPIP nearly trebles the disk space used by the database. On the other hand, on slow or heavily loaded systems, indexing could cause a slight degradation of performance, or even execution time-out errors (extreme case).

Generally, if your site is very large, we advise not to use the search engine integrated to SPIP, and to choose other specialised products such as ht://Dig.

You should also note that the search engine does not index all the pages in one go. If you enable it while your site already contains a large number of articles, you will need to wait until your site records a certain number of hits (approximately) equal to the number of texts to index in order for the engine to be updated.

# Personal interface customisation

## intersimple/Simplified / complete interface

### Simplified interface / complete interface

Each SPIP user can modify his own display (without affecting the display for the other users, contrary to the «Precise configuration» page).

Several SPIP features are very rarely used (or not at all) by some editors. Therefore, choosing the «simplified interface» allows to lighten this interface and to simplify its comprehension. In this mode, only the elements really necessary to the management of the site are displayed. For example, very few users need the «date of earlier publication» which does not appear in the «simplified interface» mode.

P.S. the differences between the two mode of display are more obvious to the administrators who have at their disposal more features than the editors of the site.

For these modifications to take effect, you must accept the use of cookies.

Administrators can activate a cookie which triggers the display of additional information during the visit of the public site.

A button labelled «Refresh this page» will appear on all the pages of the public site. Because SPIP integrates a cache system, some modifications may not appear immediately online. (Pages displayed on the public site are not directly pulled out from the database: they are refreshed at regular intervals and stored in the cache.)

By refreshing a page, the administrator instigates the display of the page according to the elements stored in the database, without the need to wait for the next refresh of the cache.

-  Modifying...

The pages of articles, sections and news contain a button labelled «Modify this article» (or «section»...). This button takes you directly from the public site to the page in the private area corresponding to this article (or section...). This button makes it easier then, for the correction of mistakes discovered online, or the update of any element of the site.

-  Number of visits

If the statistical system integrated to SPIP is enabled, the following information is added to the articles pages: number of visits (estimate) and number of different referrers.

Referrers are links to this particular article from outside the site (that is, when a site offers a direct link to this article, or when this article’s address was passed by e-mail).

-  Connection identifier

The administration cookie also enables SPIP to recognise your browser when you connect again: you then just have to enter your password to be able to get access to the private area.

(PS: if the connection is cookie dependant - it is the most common situation -, this cookie is placed in the private area as soon as you reach it.)

## deconnect/Disconnect

### Disconnecting

You can click on the button «Disconnect» to cancel your identification in the private area. When you click on it the login information that you entered to access the private area are «lost» by the system; SPIP will ask you to re-enter this information or to go back to the public site.

The main benefit of this feature is to deny to another person using your machine any access to the private area by taking advantage of your own login information.

-  You are working on your own and you are the only one having access to the computer

In this case, it may seem that disconnecting through this feature is somewhat superfluous. Disconnecting is of course recommended, but there is not much harm if you forget.

-  You access the private area with a multi-user machine (office computer, cyber-café...)

In this case, it is strongly advised that you disconnect systematically through this feature when you finish your work. This will completely deny any access to the private area to any person other than you who is using the same machine.

-  Using several identifiers for the same site

Some users would like to access the private area with more than one identity. In this case, they can use the disconnect feature to exit then connect again under new identifiers.

## artmodif/Articles currently being modified

### Articles currently being edited

When an editor opens an article to modify it, the other participants to the site who navigate to that article’s page are warned and are advised to open the article later in turn after the current editor is finished.

In fact, if two editors open the same article at the same time, the modifications that one editor makes risk "overriding" the modifications made by the other.

If you see the warning notice "Warning - an editor is working on this article", then you are strongly advised not to modify it at the moment. Come back to this article later, once the other editor has made and saved his modifications.

Conversely, when you yourself are working on modifying an article, other site participants who visit that page will be pre-warned that you are working on it. So long as you are modifying the article, and for a period of one hour, the other editors are invited not to open the article for modification. When you think that you have finished working on that article, and that others might want to take their turn at it, then you can "release" that article. The warning to the other participants will disappear, and they can then make their own changes to the document should they so wish.

## suivimodif/Monitoring new versions

### List of versions

List of modifications

Monitoring the versions of articles makes it possible to see the changes that have been made to articles throughout its "published life".

Only articles that are already published or currently being validated are visible in this list. By clicking on the title of an article in the list, you will be shown a page that highlights the differences between the most recent version and its precedent.

Displaying the modifications

You can compare the current version with a previous version by clicking on the corresponding "compare" link.
You can also change the version displayed by clicking on the date of the version that you would like to view.

Simple colour coding is used to highlight the changes made:

• the text segments highlighted in green are the new text sections,
• the text segments highlighted in blue are the text sections that have been moved,
• the text segments highlighted in red and crossed out are the sections that have been deleted.

## previsu/Previewing

### Previewing

When an article has been "submitted for evaluation", the administrators and/or editors (depending on the system configuration) can preview that article using the site’s templates.

This makes it possible to check the correct formatting and presentation of the article. Previewing also works for news articles, sections, etc.

## latex/Mathematical formulae

### Mathematical formulae

SPIP allows you to insert mathematical formulae using LaTeX notation, which will be automatically converted into an image inserted into the text.

You surround your mathematical "text" inside the $and$ tags. The LaTeX code for a formula will be placed between two "$" dollar signs. In this way, the text: $the formula a = \sqrt{b^{2} + c^{2}} is a reformulation of Pythagorus' formula: a^{2} = b^{2} + c^{2}$ will be displayed as: the formula is a reformulation of Pythagorus’ formula: An article in the documentation explains this functionality in greater depth. ## confurl/URL address types ### Selecting a URL naming convention SPIP offers the possibility, as presented in the configuration page table, of selecting the URL naming convention that you would like to employ (You must eliminate —comment our or delete — the $type_urls variable in your mes_options.php file, in order to make that configuration table be visible.).

In order for your URL naming convention to be taken into consideration, it is normally common for most installations that you use an htaccess file:
Start with the htaccess.txt file supplied with SPIP as a base example, and which works with most ISP hosting services for the types of URL naming offered.

To activate it, you must copy it back into the root directory as .htaccess. It is highly recommended to open it before copying it to check certain elements of the configuration ( warning: any modification of the .htaccess file can lead to serious impacts on the operation and performance of your web site.)

You should then test the validity of these new URL addresses by calling the "View online" page link for an article, an author, a news article, a section, etc.

You can find more information about "how to use personalised URLs" in this article of the documentation.

# SPIP - a free software

## licence/License and conditions of use

License and conditions of use

SPIP, Internet Publishing System

Copyright © 2001-2021, Arnaud Martin, Antoine Pitrou, Philippe Rivière and Emmanuel Saint-James.

This programme is free software; you may distribute it and/or make changes to it in accordance with the terms of the GNU General Public License, as published by the Free Software Foundation; version 2 of that license, or (your choice) any subsequent version.

This programme is distributed in the hope that it will be useful, but WITHOUT ANY GUARANTEE, without even the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for details.

A copy of the GNU General Public License must always be distributed together with the programme. If this is not the case, write to: Free Software Foundation Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

This programme can be downloaded from the website: https://www.spip.net/, where you will also find instructions for use and further information.

In French law SPIP Is governed by the terms of the code of intellectual property (CPI). The core of SPIP is the cooperative work of several authors designated above (article L 113-1 of the CPI). The overall SPIP project is a collective work in the meaning of articles L 113-2 and L 113-5 of the CPI. The authors make this work available for anyone, according to the rights and obligations set out in the GNU General Public License.

The icons used by the programme are by Diala Aschkar and Jakub "Jimmac" Steiner.

The translations of the editing interface are the work of a team of translators who contribute via the site spip.net.

GNU General Public License:
— text version;
— HTML version.