Author guidelines

Important note (!) : Do not use Internet Explorer for editing the wiki. Some functions don't work properly. Preferably use Chrome, Firefox etc.

Edit text

To insert or edit text use the Edit or Edit source tabs on the top of the page. Edit launches the Visual Editor, edit source the Wiki editor. The Visual Editor is the most user friendly editor, but sometimes the Wiki editor is needed. The most easy way to get the documentation into the wiki pages is via copy/paste from a Word document. Save the page to store the text and to see how your edits are displayed. Use the Read tab to go back directly to the webpage.

Some actions are more complicated: uploading and displaying figures; cross referencing figures, equations and tables; drafting equations; using citations and footnotes. Some of these actions are included in the visual editor, some of them need to be done in the wiki editor. These actions will be treated separately in the guidelines.

Visual editor

This is a so called what you see is what you get (WYSIWYG) editor. After clicking the edit tab on top of the page the editor loads the page content and displays your text in final format as well as generated text. Generated text consists of the ' infobox ' template and if applicable the' not yet published ' warning template on top of the page. Don't edit these template texts!

• First edit: If the documentation page is new then start editing by moving the mouse alongside the left margin from the title down. The mouse cursor will change into a hand and the text '+ insert paragraph' will appear on the first and the third line. Left mouse click on the third line - the cursor should change into a blinking pipe - then start typing. The new paragraph should be below the 'not yet published ' warning box on top of the page.
• Help: An extensive help function is available at the user guide of the Visual editor.
• Styling and edit functions: You can enter text and format the style with the functions in the toolbar at the top of the page.
• Word copy: Text and tables from a Word document can be copied and paste directly, style and table definitions will be preserved.

You always need to save your changes! Use the Save changes button in the toolbar.

Wiki editor

The Edit source tab contains some built-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 bullet points or headings
• Cheat sheet containing some basic commands
• Overview of different types of way to place a link

Footnotes

Footnotes can be added to the text in the Visual editor (edit -> cite tab). Type the footnote text in the text field or reuse an existing footnote. In this example a group is used.

You click and enter	You get
Toolbar => Cite => Basic text: footnote text group: Section footnote

Use Toolbar => Insert => References list and select a group to display the references list at the desired position. See the footnote (reuse of footnote) at the end of this section.

Figures

To insert a figure to your text there are a few steps to be followed:

You click and enter	You get
Toolbar = >Insert => Media tab upload; select and upload a file, here the iamc logo Give it a name, description and caption. The advanced tab lets you position and format this figure	IAMC logo

Note that cross reference to a figure only works if the figure has a caption text. See section about cross referencing.

More information on figure formatting can be found here

Tables

Tables may be created by using copy/paste from Word or by using the Toolbar => Insert => Table function. A pasted table does not copy the styling, except bold and italic. You can adapt a table by clicking on a cell. An arrow sign will appear. Click this sign and column /row edit functions will popup. Double click on a cell to edit the content.

Clicking on a cell also gives access to the Table => Properties dialog, where you can give your table a caption; give it the wikitable style; make it sortable and/or make it collapsible. On this platform we use the wikitable styling. The table below has all the mentioned properties set.

Caption

a	b	c	d
AAAAAAAAAA	BBBBBBBBBBBBBBB	CCCCCCCCCCCCCCCCC	DDDDDDDDDDDDDDD
one	two	three	four

For tables we also use cross references to number the tables on the page, and to 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.

Note that the cross reference only works if the table has a caption. 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. See the section about cross referencing.

Equations

We use a latex style equation writer. You can insert an equation with Toolbar => Insert => Math formula dialog. Equations can be inserted in the text as followed:

You click and enter	You get
Click: Toolbar => Insert => Math formula Enter: \dfrac{k}{k-1} = 0.5	${\dfrac {k}{k-1}}=0.5$

The equation text must in latex language.

More information on formatting equations can be found here

Check if your equation text works can be done through this link

Cross Reference

A referenced object is an object which has an identifier and a caption.

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>

It is important that your object identifier (id) is unique. Therefore start the id with the type of object and follow with your model name (see example), e.g.

fig:MESSAGE

.

Example 1: Cross referencing figure

Use the Wiki editor (Edit source tab) and surround the figure ([[File:file name ....]]) statement with the <figure id="identifier"> ... </figure> tags

</figure> </syntaxhighlight>

</figure>

MESSAGE Area projection

MESSAGE Area projection

You type	You get
<syntaxhighlight lang="html"> <figure id="fig:MESSAGE_1">
<figure id="fig:MESSAGE_1">

And a reference to the <xr id="fig:MESSAGE_1">figure</xr> with <xr id="fig:MESSAGE_1"></xr> .

Example 2: Cross referencing table

Use the Wiki editor (Edit source tab) and surround the table statement with the <figtable id="identifier"> ... </figtable> tags

You type	You get
	<syntaxhighlight lang="html"> <figtable id="tab:example"> Fruit price Fruit Price Orange $1 Apple $0.50 </figtable> </syntaxhighlight>	<figtable id="tab:example"> Fruit price Fruit Price Orange $1 Apple $0.50 </figtable>

And a reference to the table <xr id="tab:example"></xr> with <xr id="tab:example"></xr> .

More information on cross referencing can be found here.

Input reference card

The reference card can be filled- in through the following link, The result of this action are the reference card - <model> pages displayed on the left panel. Each field in the reference card has a specific id and to compare models input data you can use the Model comparison tool. A selection of the reference card information is displayed on your model documentation pages in the right panel and in the table on the IAMC 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 in the wiki-editor (edit source).

1. 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 what 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=;
}}

2. The first line, following |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.
3. 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.
4. Add the collected reference description to the Reference page of your model,see for example the Reference page of IMAGE
5. 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.
6. 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

Empty documentation pages, deletion and re-creation

In order to facilitate model comparability, the sections and sub-sections are standardized for all models, and therefore all models need to be documented within a similar set of sections (the sections are presented in the table of contents in the text box on the right-hand side of each model page). Not all models have the same scope, and therefore not all pages will be filled by all models.

You may delete empty pages under the following conditions:

1. The page is not in the main branch of the documentation tree (Model scope and methods;Socio-economic drivers; Macro-economy; Energy; Land-use; Emissions; Climate; Non-climate sustainability dimension; Appendices; References)
2. The page is a leaf in the documentation tree and not a node.

The menu option More=>Delete will delete the page after confirmation.

You can recreate a page via Editor tools=>Model pages setup. Do not use Internet explorer for this action!.

• Open the setup page of your model. All pages of the model documentation are listed here. If a page does not exist it is displayed as a red link, preceded with Create: .

• Clicking the red link will create the page for your model and take care of the documentation tree.
• You should see a message like this one: Capital and labour markets - IMAGE: Successfully modified Capital and labour markets - IMAGE using form ModelDocumentationForm.
• Navigate via the 'Model documentation' to your recreated page and refresh the page with top-menu option: more=>refresh

Troubleshooting

If you have come across issues during the editing process that you have solved, please describe your solutions here. If you are not able to solve your problem, then contact us via an email to iamc@pbl.nl

Overlap of figure and Model documentation box

To force the placement of a figure beneath the Model Documentation box add the following line in your text:

<div style="clear:both"> </div>

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.

Red links

If you see a red link in your text the page to which a link is made cannot be found. edit the link in the Visual editor and refer to the correct webpage.

Forced spacings

In some model documentation pages originally the paragraphs were forced by using the tags

<br></br>

visible in the wiki-editor. These are recognized by the current Media Wiki, however results in sometimes strange display of the text. Please remove 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 to fit the current Wiki. Some models, such as TIAM-UCL on the Energy conversion 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..