Author guidelines
HTML2WIKI Migration
The ADVANCE wiki has been migrated from the UCL Confluence Wiki to the PBL Semantic Media Wiki. A HTML2WIKI conversion tool has been used to do so. The text, figures, and links are copied but the formatting can look odd, certain links can not work anymore or symbols can not be interpreted and are displayed as a question mark. For that reason all teams should check every page of your model documentation to see if the formatting is correct. In the troubleshooting section, solutions to specific errors that have come up so far can be found.
In addition, the structure of the pages of the model documentation have been changed. Some pages have new names, some have been merged or split and several new pages have been added to the wiki. Therefore it is important to check whether the content placed on the page is still correct for your model.
There are some new features in the Media Wiki:
- Creating Tables
- Creating Equations
- Dynamic referencing to Figures, Tables and Equations
- Dynamic referencing to Citations
More information on these topics can be found below.
Please go through your model documentation pages and update/add these new features where relevant.
Our experience is that editing all the citations in your reference page to the correct format is the most cumbersome task, and that starting with this before editing the pages eases the work.
Note: Wikitext contains all the features required to follow Wikipedia's formatting conventions. However, its formatting capabilities are limited. If you want to have more control of the formatting, such as using colors, text and paragraph styles, and page layout you can use HTML. HTML is the language used to format web pages in the Internet. It is more powerful than Wikitext, but it's also more complex and harder to use.
Edit text
To insert or edit text use the Edit or Edit with form tabs on the top of the page. To see how your edits are displayed save the page. To go back directly to the webpage use the Read tab.
The Edit tab contains some build in functions to format text, such as text style or linking to internal or external webpages.
More tips and tricks on text editing can be found through the following Wiki help pages:
- Wiki markup help page to format text
- Creating lists through bulletpoints or headings
- Cheatsheet containing some basic commands
- Overview of different types of way to place a link
To get you started, some basic examples:
| You type | You get |
| ''italic'' | italic |
|
'''bold''' |
bold |
|
'''''bold italic''''' |
bold italic |
|
SO<sub>4</sub><sup>2-</sup> |
SO42- |
|
Text before ---- Text after |
Text before Text after |
|
*bullet |
|
|
[[Model_Documentation_-_IMAGE|Model_Documentation of IMAGE]] |
|
|
[http://fp7-advance.eu FP7-ADVANCE] |
Headers
Headings are created using sequences of "=" characters, placed before the heading title and after the heading title, on the same line. The level of headings is determined by the number of "=" characters.
Examples:
| Level | Example |
| 2. | ==Plants== |
| 3. | ===Plants=== |
| 4. | ====Plants==== |
Table of content
If you insert four or more headers on your page by default a table of content is displayed. The table of content give a good overview of what can be found on the page. If you want to force display when you have three or less headings use:
__FORCETOC__
More information on the table of content can be found here.
Footnotes
Footnotes can be added to the text by placing the footnote in between the following command:
| You type | You get |
<ref>footnote text</ref> |
[1] |
By default the footnot is displayed at the bottom of the page. If you want to display the footnote at the end of the section - as we have done in this example - type
<references />
at the end of your section.
More information on footnotes can be found here
- ↑ footnote text
Figures
To insert a figure to your text there are a few steps to be followed:
- Upload figure by using the Tools|Upload file link on the left panel of this website.
- You can place the figure in the text by linking to the created file page, which typically is named File:uploadname. File pages can be found by navigating to the Tools|Special Pages on the left panel, and then navigate to Media reports and uploads|File list, or directly through this link. Place the figure in the text as followed:
[[File:uploadname]]
- The figure can be formatted by extending the placed reference:
[[File:uploadname|size|format|caption text]]
.
- To harmonize figure formatting in this platform we use the thumb format option. In addition figures are numbered by using the cross reference extension. For that purpose every figure must have a figure id, as follows:
<figure id="fig:myobject"> [[File:uploadname|size|format|<caption>caption text</caption>]] </figure>
Note that the cross reference only works if the the caption text is enclosed by the <caption></caption> statement.
Example:
</figure>
| You type | You get |
<figure id="fig:MESSAGE_1"> [[File:54067461.png|600px|thumb|<caption>MESSAGE Area projection</caption>]] </figure> |
<figure id="fig:MESSAGE_1"> |
If you want to reference to the figure in the text:
| You type | You get |
<xr id="fig:MESSAGE_1"/> |
<xr id="fig:MESSAGE_1"/> |
More information on figure formatting can be found here
Tables
In this platform we use the standard "wikitable" format to display tables.
Examples:
The following table lacks borders and good spacing but shows the simplest wiki markup table structure.
| You type | You get | ||||||
{| class="wikitable"
!Fruit
!Price
|-
|Orange
|$1
|-
|Apple
|$0.50
|}
|
|
For tables we also use cross references to number the tables on the page, and link to the table in text. In order to do so the tables must have a table id and a caption - similar to the figure cross references.
| You type | You get | ||||||
<figtable id="tab:example">
{| class="wikitable"
|+<caption>Fruit price</caption>
!Fruit
!Price
|-
|Orange
|$1
|-
|Apple
|$0.50
|}
</figtable>
|
<figtable id="tab:example">
</figtable> |
Note that the cross reference only works if the the caption text is enclosed by the <caption></caption> statement.
To refer in the text to the table you can place a link to the tables id. Here it is important that the id is unique.
| You type | You get |
<xr id="tab:example"/> |
<xr id="tab:example"/> |
More information on table formatting can be found here Or look at the table generator here
Equations
We use a latex style equation writer. Equations can be inserted in the text as followed:
| You type | You get |
<math style="font-size: 1.5em;">
\dfrac{k}{k-1} = 0.5</math>
|
|
More information on formatting equations can be found here
Cross Reference
A referenced object is an object which has an identifier and a caption. In the figures and in the tables section it has been explained how this can be used for figure and table numbering and referencing.
Several types of referenced objects are supported:
fig: a figure,tab: a table,eqn: an equation,def: a definition, and
Each of these types have a dedicated HTML tag to declare an object instance:
<figure id="fig:identifier"> text </figure><figtable id="tab:identifier"> text </figtable><equation id=":eqn:identifier"> text </equation><theorem id="def:identifier"> text </theorem>
In the text describing the referenced object, the tag <caption/> may enclose the caption of the object.
You can cross reference to the object by using the following command:
| You type | You get |
|<xr id="fig:MESSAGE_1"/> |
<xr id="fig:MESSAGE_1"/> |
It is important that your object id is unique. Therefore start the id with the type of object and follow with your model name, e.g.
fig:MESSAGE
More information on cross referencing can be found here.
Insert Model Information
Insert the specific model information through the following form. This information is displayed on your model documentation pages in the right panel and in the table on the ADVANCE Wiki introduction page.
Citation Management
To place a reference to journal paper, book or other literature in your text the following steps need do be performed:
- Look up references in a format that can be recognized by the semantic cite extention that we use in this platform. More information about semantic cite can be found here. There are two easy options:
- Use the Citation web search function in the left panel.
- Collect reference information in bibtext format.
Here is an example of how this could look like:
{{#scite:
|reference=van vuuren2013a
|type=journal-article
|title=A new scenario framework for Climate Change Research: scenario matrix architecture
|author=Detlef P. van Vuuren;Elmar Kriegler;Brian C. O’Neill;Kristie L. Ebi;Keywan Riahi;Timothy R. Carter;Jae Edmonds;Stephane Hallegatte;Tom Kram;Ritu Mathur;Harald Winkler|+sep=;
|journal=Climatic Change
|publisher=Springer Science + Business Media
|year=2013
|volume=122
|issue=3
|pages=373-386
|doi=10.1007/s10584-013-0906-1
|subject=Atmospheric Science;Global and Planetary Change|+sep=;
|issn=0165-0009;1573-1480|+sep=;
}}
- The first line, folowing
|references=indicates the key (or id) of the reference, to which you can refer to in your text. It is important you specify a key that is unique. For example by starting the key with your model name. - The second line, following
|type=indicates the type of reference. In this wiki we have specified 5 reference types, namely journal, book, report, book chapter and website. If your reference does not fall under one of these categorization you can specify yourself how the reference is displayed, by adding an extra line with|citation text=. Several examples of the 5 supported reference types in this platform -their required and optional fields can be found on the Citation Resources example page. To avoid incorrect citation display or other errors it is important to follow these instructions carefully. - Add the collected reference description to the Reference page of your model,see for example the Reference page of IMAGE
- Add the reference key to the top row of the page after
|references=. This will display your reference on the References page. The list|references=<ref1;ref2;…;refn>must end with|+sep=;. This tells the system that we use the ‘;’ as list separator. - Insert the key in your model documentation text where you would like to add the reference by using:
[[CiteRef::Referencekey]]
.
The reference is indicated by a footnote, for example:
| You type | You get |
Van Vuuren et al. [[CiteRef::van vuuren2013a]] conclude... |
Van Vuuren et al. van vuuren2013a conclude... |
Note that the reference is automatically displayed at the bottom of the page, and when you render with your mouse over the citation reference it shows you the full reference details.
More information of the Citation Manager can be found here
Troubleshooting
If you have come across issues during the HTML2WIKI editing process that you have solved, please describe your solutions here.
Citation not displayed correctly
The 5 citation templates used here are sensitive to the required field. Check whether you have filled in all the required fields and have named the fields correctly. For example certain bibtext exports include citation types that are not supported by this template, or use pubdate instead of year to indicate the publication date.
Questionmarks in the text
Questionmarks in the text indicate that a symbol that you used in the Confluence Wiki is not recognized. Best is to check the original text in the Confluence Wiki and insert the intended symbol manually.
Red links
Links have been automatically copied but in some cases do not work anymore. If you see a red link in your text the page to which a link is made cannot be found. Check the link and refer to the correct webpage. More infomation on how to insert links can be found under the "Edit text" header on this page.
Forced spacings
In some model documentation pages originally the paragraphs were forced by using the
<br></br>
commands. These are recognized by the current Media Wiki, however results in sometimes strange display of the text. Please remove the these statements and if you want to seperate paragraphs just use the enter key.
Copying of Tables
The tables from the original Confluence Wiki have been copied but rows or columns can be slightly mixed up. Also the formatting might need to be edited as it might not fit the current Wiki as it did originally. Some models, such as TIAM-UCL on the Energy conversion - TIAM-UCL page, have used tables to display lists of input values. Using list formatting might give a better overview. More information on how to insert tables can be found under the #Tables header on this page and how to display list under the #Edit text header.