Difference between revisions of "Help:Contents"

From Planck Legacy Archive Wiki
Jump to: navigation, search
(MathJax)
m
 
(205 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Organisation of the Explanatory Supplement ==
+
== Organization of the Explanatory Supplement ==
The explanatory supplement is organised in terms of what MediaWiki calls [http://meta.wikimedia.org/wiki/Help:Category Categories]. Using categories provides an automatic mechanism for Index and Table of Contents generation that would otherwise be time consuming and error prone. On top of that, there are a number of extensions based on the category concept, providing a useful set of features for the development, maintenance and use of this Wiki.  
+
The Explanatory Supplement (ES) is organized in terms of what MediaWiki calls [http://meta.wikimedia.org/wiki/Help:Category Categories]. Using categories provides an automatic mechanism for Index and Table of Contents generation that would otherwise be time consuming and error prone. On top of that, there are a number of extensions based on the category concept, providing a useful set of features for the development, maintenance, and use of this Wiki.  
  
Each of the entries in the table of contents in the [[Main_Page | Main Page]] is a category. Categories are pages (and for the ES one expects them to be reasonably self contained for the subject they cover) and can independently be added to a [[Help:Contents#Collection | Collection]]. A typical example can be found in the [[:Category:Mission_products | Mission Products]] Section: a user interested in frequency maps may or may not be interested in timelines as well but will certainly be interested in understanding the formats the maps are stored, the naming conventions, the size of the maps and will most likely also look for the details of the map making process possibly in the form of papers explaining algorithms. It will therefore make sense for the frequency maps page to contain sections on format, naming conventions, size and references to the map making process. On the other hand, the description of the timelines will most naturally appear under a different page. In order not to end up with a huge number of separate pages, instead of creating a page for frequency maps only we grouped all the map products under a single [[:Category:Maps|maps]] page which is also a category. After all, it is not entirely unexpected that a user interested in frequency maps may also be interested in other types of maps.
+
Each of the entries in the table of contents in the [[Main_Page | Main Page]] is a category. Categories are pages (and for the ES one expects them to be reasonably self contained for the subject they cover) and can independently be added to a [[Help:Contents#Collection | Collection]]. A typical example can be found in the [[:Category:Mission_products | Mission Products]] Section: a user interested in frequency maps may or may not be interested in timelines as well, but will certainly be interested in understanding the formats in which the maps are stored, the naming conventions, the size of the maps, and will most likely also look for the details of the mapmaking process, possibly in the form of <div id="html_div_link"></div>papers explaining algorithms. It will therefore make sense for the frequency maps page to contain sections on format, naming conventions, size and references to the map making process. On the other hand, the description of the timelines will most naturally appear under a different page. In order not to end up with a huge number of separate pages, instead of creating a page for frequency maps only, we grouped all the map products under a single [[:Category:Maps|maps]] page that is also a category. After all, it is not entirely unexpected that a user interested in frequency maps may also be interested in other types of map.
  
 
=== Guidelines for development ===
 
=== Guidelines for development ===
 
In order to keep the development of the wiki under control we would like to ask all contributors to follow a set of very simple guidelines.
 
In order to keep the development of the wiki under control we would like to ask all contributors to follow a set of very simple guidelines.
  
*Each topic on the table of contents is assigned to particular contributors (look [[Help:Contents#contributors|here]] for the current list). This does not mean the others can not make minor changes or corrections but in general it would be advisable that contributors not assigned to a specific topic refrain from making major corrections on that topic's pages;
+
*Each topic on the table of contents is assigned to particular contributors (look [[Help:Contents#contributors|here]] for the current list). This does not mean the others cannot make minor changes or corrections, but in general it would be advisable that contributors not assigned to a specific topic refrain from making major corrections on that topic's pages.
*A very concise help with some recipes for common editing actions can be found below. For a more detailed User Guide please refer to the [http://meta.wikimedia.org/wiki/Help:Contents MediaWiki User's Guide];
+
*A very concise help section with some recipes for common editing actions can be found below. For a more detailed User Guide please refer to the [http://meta.wikimedia.org/wiki/Help:Contents MediaWiki User's Guide].
*Concerning pages mostly contributed to by other contributors try to keep in mind the following:
+
*Concerning pages mostly contributed to by other contributors, try to keep in mind the following.
**Fixing typos or performing minor corrections is encouraged. If you find one of those please go ahead and fix it;
+
**Fixing typos or performing minor corrections is encouraged, so if you find those please go ahead and fix them.
**If what you have in mind is a major rewriting or you would like to propose extensive changes we ask you not to do so before discussing it with all those concerned. For each page there is a discussions page associated which can be accessed through one of the tabs at[[File:discussion.png|frame|Location of the discussion tab]] the top of the page. Please use it to circulate more widely the changes you would like to propose.
+
**If what you have in mind is a major rewriting, or you would like to propose extensive changes, we ask you not to do so before discussing it with all those concerned. For each page there is a discussions page associated, which can be accessed through one of the tabs at  the top. Please use this to more widely circulate the changes you would like to propose.
*If you would like to add a new page bear in mind the discussion [[Help:Contents#Organisation of the Explanatory Supplement | above]]. If you are still convinced the new page is necessary, make your intention know in the discussion page associated with the root page of your new page. If your proposal is approved follow the procedure for the creation of a new [[Help:Contents#Adding a new section | page]]
+
[[File:discussion.png|thumb|center|700px|Location of the discussion tab]]
 +
*If you would like to add a new page, bear the discussion in mind [[Help:Contents#Organisation of the Explanatory Supplement | above]]. If you are still convinced that the new page is necessary, make your intention known on the discussion page associated with the root page of your new page. If your proposal is approved then follow the procedure for the creation of a new [[Help:Contents#Adding a new section | page]]
  
Note that as all contributors have access to the entire wiki the enforcement of these simple rules depends on self-discipline and it is absolutely essential you stick to them.
+
Note that as all contributors have access to the entire wiki, the enforcement of these simple rules depends on self-discipline and '''it is absolutely essential''' that you stick to them.
 +
 
 +
===Template for product description===
 +
In order to create a uniform document, we suggest using a template for product descriptions. A tentative version can be found [[Help:Product Description Template|here]]. Any suggestions or comments on this proposal are more than welcome.
 +
 
 +
In order to use it, navigate to the page with the [[Help:Product Description Template|template]], copy the MediWiki content by entering the edit page and pasting it to the pages describing the product(s) you are editing.
 +
===Keeping track of changes===
 +
Changes can be traced through the [[Special:RecentChanges|recent changes page]]. However, for those of us who would like to keep up to date on the status of the wiki, it may not always be convenient to login to the ES wiki just for the purpose of tracking changes. In that case it is possible to use RSS feeds to stay informed of all the changes. All you need is an RSS client. If you point your client to  [http://www.sciops.esa.int/wikiSI/planckpla/index.php?title=Special:RecentChanges&instance=Planck_PLA_ES&feed=rss http://www.sciops.esa.int/wikiSI/planckpla/index.php?title=Special:RecentChanges&instance=Planck_PLA_ES&feed=rss] you will be notified every time the recent changes page is updated, which should trace all the updates in the content of the wiki. These notifications consist of a link to a page showing the differences between the old and the new versions of the updated page.
 +
 
 +
This mechanism should also work with and atom feed, although testing in this case has not been done. In this case just use ''feed=atom'' instead of ''feed=rss'' in the url provided to your news reader.
 +
 
 +
For those with android phones or tablets, we have a very simple locally developed rss client. It is extremely simple, but can easily be customized to suit the specific requirements of individual ES wiki developers.
  
 
===Contributors list===
 
===Contributors list===
 
+
TBW
  
 
== Common tasks ==
 
== Common tasks ==
 
=== Including figures ===
 
=== Including figures ===
 
====Uploading a figure====
 
====Uploading a figure====
Figures can be embedded in the text with the ''<nowiki>[[File]]</nowiki>'' tag. This tag has a large number of options for resizing, borders, formating and more and the details can be found [http://www.mediawiki.org/wiki/Help:Images here]. The basic use is however very simple. Placing a  
+
We consider two possibilities: small figures that should be displayed in the wiki pages; and larger, high resolution figures that are referred to in the wiki pages, but are not intended to be embedded in the page itself. Here we deal with the first case. For the second possibility, have a look [[here]].
 +
 
 +
Figures can be embedded in the text with the ''<nowiki>[[File]]</nowiki>'' tag. This tag has a large number of options for resizing, borders, formatting, and more, and the details can be found [http://www.mediawiki.org/wiki/Help:Images here]. The basic use is very simple, however. Placing a  
 
<pre>
 
<pre>
 
[[File:image.png]]
 
[[File:image.png]]
 
</pre>
 
</pre>
 
in the text will create a link when the page is displayed. Clicking on that link will cause a selection page to appear and the file to be embedded can then be selected.
 
in the text will create a link when the page is displayed. Clicking on that link will cause a selection page to appear and the file to be embedded can then be selected.
[[File:UploadFile.png|center|800px|Selection page for uploads]]
+
[[File:UploadFile.png|thumb|center|700px|Selection page for uploads]]
  
To produce the figure included above showing the location of the discussion tab the syntax used was  
+
To produce the figure included above, showing the location of the discussion tab, the syntax used was  
 
<pre>
 
<pre>
 
[[File:discussion.png|frame|Location of the discussion tab]]
 
[[File:discussion.png|frame|Location of the discussion tab]]
 
</pre>
 
</pre>
In this case the <nowiki>frame</nowiki> option indicates the images will be displayed within a frame and the last field is the caption of the figure. Note that captions may behave a little differnet from what was expected: when a caption is given and the frame option is used, the cpation will appear just below the figure inside the frame. When no frame option is used, the caption will be displayed when hovering with the mouse over the figure. One more thing to note is that any size options do not have any effect when the frame option is used. For the details you are strongly advised to look [http://www.mediawiki.org/wiki/Help:Images here].
+
In this case the <nowiki>frame</nowiki> option indicates that the images will be displayed within a frame and the last field is the caption of the figure. Note that captions may behave a little differently from what was expected: when a caption is given and the frame option is used, the caption will appear just below the figure inside the frame; and when no frame option is used, the caption will be displayed when hovering with the mouse over the figure. One more thing to note is that any size options do not have any effect when the frame option is used. For details you are strongly advised to look [http://www.mediawiki.org/wiki/Help:Images here].
  
Once an image is uploaded and displayed on a page, left clicking on the image in the wiki will show a page with information about the image, a special link allowing its update and a special link allowing its deletion. This page will also show the history of the figure with an entry for the original upload and one more entry for every time the figure was updated. In this case we see three different versions of the image were uploaded.
+
Once an image is uploaded and displayed on a page, left clicking on the image in the wiki will show a page with information about that image, a special link allowing its update, and a special link allowing its deletion. This page will also show the history of the figure, with an entry for the original upload and one more entry for every time the figure was updated. In this case we see that three different versions of the image were uploaded.
[[File:history.png|center|800px|Page with image history info]]
+
[[File:history.png|thumb|center|800px|File history info]]
From here it is easy to navigate back toany page where the figure appears by using any of the links at the bottom of the page under the heading ''File Links''.
+
From here it is easy to navigate back to any page where the figure appears by using any of the links at the bottom of the page under the heading ''File Links''.
  
 
====Reusing a figure====
 
====Reusing a figure====
 
Once the file containing the figure has been uploaded we can display it again with the same syntax. The figure below was produced using exactly the same syntax as before.
 
Once the file containing the figure has been uploaded we can display it again with the same syntax. The figure below was produced using exactly the same syntax as before.
[[File:discussion.png|frame|center|Location of the discussion tab]] The important thing to take into account here is to use the same name as was used for the image when it was first uploaded. Note that the name of a figure in the wiki is completely independent of the original name of the figure in the user's hard drive.
+
[[File:discussion.png|thumb|center|800px|Location of the discussion tab]] The important thing to take into account here is to use the same name as was used for the image when it was first uploaded. In this case the name to use is ''discussion.png,'' regardless of the filename in the user's disk. Note that the name of a figure in the wiki is completely independent of the original name of the figure on the user's computer.
  
 
====List of figures available in the wiki====
 
====List of figures available in the wiki====
 
It is not possible to display a list containing <b>only</b> the figures upload to the wiki. However a list of all the files uploaded can be easily generated.
 
It is not possible to display a list containing <b>only</b> the figures upload to the wiki. However a list of all the files uploaded can be easily generated.
In order to retrieve a list of all the files that were uploaded to the wiki the following steps should be followed:
+
In order to retrieve a list of all the files that were uploaded to the wiki, the following steps should be followed
#Click on the "Special Pages" link on the toolbox on the left  
+
#Click on the "Special Pages" link on the toolbox on the left.
 
#In the "Special Pages" page follow the ''File List'' link under 'Media reports and uploads'. Here you will find a list of all the files uploaded to the wiki so far, as shown in the figure below.
 
#In the "Special Pages" page follow the ''File List'' link under 'Media reports and uploads'. Here you will find a list of all the files uploaded to the wiki so far, as shown in the figure below.
[[file:fileList.png|center|800px]]
+
[[file:fileList.png|thumb|center|800px|FIle list]]
 +
 
 +
====Naming convention====
 +
In order to avoid the possibility of name clashes between images uploaded by differnet contributors we ask you to strictly adhere to the following name convention:
 +
<pre>
 +
DPC_x_[x_x_x]_fileName.ext
 +
</pre>
 +
Here DPC is one of HFI or LFI, x_x_x_x the section number for the page where the image will be displayed (where the [] indicates that the rightmost xs may be ommited if the section number does not contain all the four possible digits), fileName the filename to be used in the Wiki, and ext the extension describing the format of the image.
 +
 
 +
A png figure uploaded by the LFI to be displayed in section 2.3 would be named ''LFI_2_3_someName.png'' and a jpeg figure uploaded by the HFI to be displayed in section 6.4.3.1 would be named ''HFI_2_3_someOtherName.jpg''.
  
 
=== Links ===
 
=== Links ===
 
==== Links to other pages in the wiki====
 
==== Links to other pages in the wiki====
A link to a page in ES wiki is achieved with the following syntax
+
A link to a page in the ES wiki is achieved with the following syntax:
 
<pre>
 
<pre>
 
[[PageName]]
 
[[PageName]]
 
[[PageName|link]]
 
[[PageName|link]]
 
</pre>
 
</pre>
where the first line produces a link where the link text is PageName and the second a link with the text link ''link''. As an example of the first syntax we have <nowiki>[[Main Page]]</nowiki> prodicing a link to the [[Main Page]] of this wiki. For the second syntax we can write <nowiki>[[Main Page|Table of Contents]]</nowiki> which produces a link to the ES [[Main Page|Table of Contents]].
+
Here the first line produces a link where the link text is PageName and the second a link with the text link ''link''. As an example of the first syntax type, we have <nowiki>[[Main Page]]</nowiki> producing a link to the [[Main Page]] of this wiki. For the second syntax type, we can write <nowiki>[[Main Page|Table of Contents]]</nowiki>, which produces a link to the ES [[Main Page|Table of Contents]].
  
If the page we wish to link too is a Category a small addition to the syntax is required. In this case the page name will necessarily be of the form Category:PageName. However just using Category:PageName as PageName in the link syntax as defined above will  
+
If the page we wish to link to is a Category a small addition to the syntax is required. In this case the page name will necessarily be of the form Category:PageName. However, just using Category:PageName as PageName in the link syntax as defined above will:
 
#introduce the page where it appears in the Category hierarchy;
 
#introduce the page where it appears in the Category hierarchy;
 
#produce a link to Category:PageName at the bottom of the page.
 
#produce a link to Category:PageName at the bottom of the page.
This can be put to good use (see [[Help:Contents#New section as new page|below]]) but it is not what have in mind here. To produce a ''normal'' link to a category page a semi-colon must be added before Category:PageName:
+
This can be put to good use (see [[Help:Contents#New section as new page|below]]), but it is not what have in mind here. To produce a ''normal'' link to a category page a semi-colon must be added before Category:PageName:
 
<pre>
 
<pre>
 
[[:Category:PageName]]
 
[[:Category:PageName]]
 
[[:Category:PageName|link]]
 
[[:Category:PageName|link]]
 
</pre>
 
</pre>
The two different syntaxes above work exactly as in the examples above. A link to the maps chapter can produced with <nowiki>[[:Category:Maps|maps chapter]]</nowiki> resulting as expected in a link to the [[:Category:Maps|maps chapter]] in the ES.
+
These two different syntax types work exactly as in the examples above. A link to the maps chapter can produced with <nowiki>[[:Category:Maps|maps chapter]]</nowiki>, resulting, as expected in a link to the [[:Category:Maps|maps chapter]] in the ES.
  
It is also possible to define a link to a specific section in a given page (where a section is defined using the [[Help:Contents#New section in an existing page|''='' syntax]]). In this case the syntax is
+
It is also possible to define a link to an anchor defined in a page. Linking to a section in a page is the simplest case, since section headers (defined with the [[Help:Contents#New section in an existing page|''='' syntax]]) provide automatic anchors. In this case the syntax is
 
<pre>
 
<pre>
 
[[PageName#SectionName]]
 
[[PageName#SectionName]]
 
[[PageName#SectionName|link]]
 
[[PageName#SectionName|link]]
 
</pre>
 
</pre>
where the two differnet syntaxes work as described above. As an example, the link at the beginning of this paragraph was produced with  
+
where the two different syntax types work as described above. As an example, the link at the beginning of this paragraph was produced with  
 
<pre>  
 
<pre>  
 
[[Help:Contents#New section in an existing page|''='' syntax]].
 
[[Help:Contents#New section in an existing page|''='' syntax]].
 
</pre>
 
</pre>
 +
If an anchor reference starts with a #, a link to the current page will be generated.
 +
 +
Defining an arbitrary anchor inside a page requires html. Unfortunately the <a> tag cannot be used in mediawiki. However, using <div> with the id attribute can be used to create an anchor. The following piece of code
 +
<pre>
 +
some text <div id="anchor_definition"></div> and even more text
 +
...
 +
and a link to the text [[#anchor_definition|above]]
 +
</pre>
 +
The following [[#html_div_link|link]] uses this syntax.
  
 
==== Links to external pages ====
 
==== Links to external pages ====
Line 85: Line 117:
 
<pre>[http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17 ESA Planck page]</pre>
 
<pre>[http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17 ESA Planck page]</pre>
 
and results in this link to the [http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17 ESA Planck page].
 
and results in this link to the [http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17 ESA Planck page].
Dropping ''text'' will also work as expected but with a different appearance.  
+
Dropping ''text'' will also work, as expected, but with a different appearance.  
 
With  
 
With  
 
<pre>[http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17]</pre>
 
<pre>[http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17]</pre>
 
we produce [http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17].
 
we produce [http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17].
  
When comparing with the syntax for internal links note the use of a single [ instead of [[ and also the link text is separated by the url by a space and there is no need for a | as in the case of internal links.  
+
When comparing with the syntax for internal links, note the use of a single [ instead of [[ and also note that the link text is separated by the url with a space and there is no need for a | as in the case of internal links.  
  
 
External links can be easily identified in the displayed pages by an arrow next to the link.
 
External links can be easily identified in the displayed pages by an arrow next to the link.
  
 
=== Uploading documents ===
 
=== Uploading documents ===
Uploading a document can be done exactly as described above for figures. Note however that the file types that can be uploaded are limited to png, gif, jpg, jpeg, pdf, txt, zip and the size of each individual document is limited to 100MB. What this means is that MediWiki knows what to do with files of these types (a png or jpg files will be displayed without the need to explicitely tell MediWiki to display them).
+
Uploading a document can be done exactly as described above for figures. Note, however, that the file types that can be uploaded are limited to png, gif, jpg, jpeg, pdf, txt, zip, and the size of each individual document is limited to 100MB. What this means is that MediWiki knows what to do with files of these types (a png or jpg files will be displayed without the need to explicitely tell MediWiki to display them).
  
 
For files of other types please have a look at the section [[Help:Contents#Attachments|Attachments]] below.
 
For files of other types please have a look at the section [[Help:Contents#Attachments|Attachments]] below.
 +
 +
===External documents===
 +
It is possible to include in the ES wiki extra information in the form of data, higher resolution images that exceed the 100MB limit for uploaded files, or documents in formats other than the ones directly supported by the default MediWiki upload mechanism.
 +
 +
For this purpose we created a special area in livelink. Inside the [http://www.rssd.esa.int/llink/livelink?func=ll&objid=3110897&objAction=browse&sort=name Explanatory supplement documents folder] we created one subfolder per ES chapter. Documents can be uploaded following the same procedures as for any other Livelink document. In order to link to an external document in the ES area of livelink, all you need to do is create a link to the document as explained in the [[Help:Contents#Links to external pages| Links to external pages]] section above.
 +
 +
The following line creates a link to a test document in the ES area in livelink.
 +
<pre>
 +
[http://www.rssd.esa.int/llink/livelink/open/3111114#page=10 example link]
 +
</pre>
 +
Clicking on this [http://www.rssd.esa.int/llink/livelink/open/3111114#page=10 example link] will retrieve a test document from Livelink.
  
 
=== Adding a new section ===
 
=== Adding a new section ===
Line 109: Line 152:
 
More details can be found in the [http://meta.wikimedia.org/wiki/Help:Contents MediaWiki User's Guide].
 
More details can be found in the [http://meta.wikimedia.org/wiki/Help:Contents MediaWiki User's Guide].
  
====New section as new page====
+
====New section as a new page====
Should the new section appear as a new page (see the [[guidelines]] above on the addition of new pages) the Category syntax should be used:
+
Should the new section appear as a new page (see the [[Help:Contents#Guidelines for development|guidelines]] above on the addition of new pages) the Category syntax should be used:
  
'''STEP 1''': ''Add a link to the (still non-existing) new page in the Table of Contents on the [[Main Page]]'':
+
'''STEP 1''': ''Add a link to the (still non-existent) new page in the Table of Contents on the [[Main Page]]'':
 
: Assuming a new page with the title New Page is to be added to the ES, add the line  
 
: Assuming a new page with the title New Page is to be added to the ES, add the line  
 
: <pre>[[:Category:New Page|New Page]]</pre>
 
: <pre>[[:Category:New Page|New Page]]</pre>
: to the [[Main Page]]. This will create a link to the (yet non existing) page New Page. Note the slightly different link syntax: the : after the [[ is required otherwise the tag would be interpreted not as a link but as a Category hierarchy definitios (see step 2 below).
+
: to the [[Main Page]]. This will create a link to the (yet non-existent) page New Page. Note the slightly different link syntax: the : after the [[ is required otherwise the tag would be interpreted not as a link but as a Category hierarchy definition (see step 2 below).
  
: When the Category link above is added to the Main Page make sure it appears in the correct location as the Main Page is basically a table of contents for the ES.  
+
: When the Category link above is added to the Main Page make sure it appears in the correct location, since the Main Page is basically a table of contents for the ES.  
 
'''STEP 2''': ''Create the page (and Category)'':
 
'''STEP 2''': ''Create the page (and Category)'':
:Clicking on the link just created on step 1 (which will be displayed in red as the page still does not exist) will take you to an empty page displaying the warning '''''You have followed a link to a page that does not exist yet'''''. Enter the content of the new page as you would for any other page. Since we want this page to be part of the category tree enter the line
+
:Clicking on the link just created in step 1 (which will be displayed in red as the page still does not exist) will take you to an empty page displaying the warning '''''You have followed a link to a page that does not exist yet'''''. Enter the content of the new page as you would for any other page. Since we want this page to be part of the category tree enter the line
 
: <pre>[[Category:TopCategory]]</pre>
 
: <pre>[[Category:TopCategory]]</pre>
: where '''''TopCategory''''' is the existing category under which the new category will appear in the Category Tree. If this last step step is missed the new page will not be part of the Category Tree and you will therefore not be able to take advantage of the Category Tree features. The line above can be entered anywhere on the page but the structure of the page results easier to understand if it appears consistently at the end.
+
: where '''''TopCategory''''' is the existing category under which the new category will appear in the Category Tree. If this last step step is missed the new page will not be part of the Category Tree and you will therefore not be able to take advantage of the Category Tree features. The line above can be entered anywhere on the page, but the structure of the page results are easier to understand if it appears consistently at the end.
  
:For example, in the [[:Category:Maps|maps]] section under [[:Category:Mission products|mission products]], the following line appears at the end of the page
+
:For example, in the [[:Category:Catalogues|Catalogues]] section under [[:Category:Mission products|mission products]], the following line appears at the end of the page:
 
: <pre>[[Category:Mission products]]</pre>
 
: <pre>[[Category:Mission products]]</pre>
 
: This guarantees the maps section will correctly appear in the Category Tree
 
: This guarantees the maps section will correctly appear in the Category Tree
 +
 +
====<font color=red>'''Very important point'''</font>====
 +
Please bear in mind that
 +
<pre>
 +
[[Category:myPage]]
 +
</pre>
 +
and
 +
<pre>
 +
[[myPage]]
 +
</pre>
 +
are completely different entities. The first defines a Category called my page and the second defines a page with the same name, but they can coexist separately and independently. If you add some content to <code>myPage</code> and then look for it in <code>Category:myPage</code> you will obviously not find it. This point can be a bit confusing so please bear it in mind before taking any further action if what you see in some page is completely different from what you were expecting to find.
 +
 +
=== Referencing documents===
 +
==== Planck Collaboration papers ====
 +
Citations to Planck papers can be included in the text using the [[Template:PlanckPapers|PlanckPapers]] template. For the documentation have a look [[Template:PlanckPapers|here]].
 +
 +
This is an example of a citation {{PlanckPapers|planck2013-p01a}}. The template produces a direct link to the paper, and a link to the full bibliographical  record in the form of a number enclosed in square brackets. Clicking on the number will take the reader to the bibliographical record in the References section at the bottom of the page (assuming the page author has followed the instructions in the template [[Template:PlanckPapers|documentation]]). From the references list it is easy to return to the exact location where the citation was produced in the page by clicking on the little arrow or in the numbers next to the arrow. Additionally when hovering the mouse over the link in the text a tooltip will appear containing the full reference and a link to the paper or to its abstract in the electronic version of the journal where it was published or in the arXiv. '''Important note''': the tooltip may not display correctly in every browser, since it was tested only on Firefox and Chrome. In any case the link to the paper can also be found in the full record at the bottom of the page.
 +
 +
==== Other papers ====
 +
References to non-Planck papers can be introduced in the text using the [[Template:BibCite|BibCite]] temaplate. The documentation can be found here [[Template:BibCite|here]].
 +
 +
Citation in the text look like this{{BibCite|page2003b}}. This is similar to the citation to Planck papers except that this time there is no direct link to the paper in the text.
 +
 +
===== Adding entries to the bibliography =====
 +
TBW
 +
 +
===== Citing a reference =====
 +
TBW
 +
 +
==== Planck interface control documents (ICDs) ====
 +
For references to the Planck ICDs a very similar mechanism to the one described above for the Planck papers can be used. In this case the template is called ICD and the syntax would be
 +
<pre>
 +
{{ICD|name|page=page_number|link=link_text}}
 +
</pre>
 +
The parameters page and text are optional and they work as described above. If "page" is omitted the ICD will open in page 1. If "link" is omitted the link text will be ICD. The name parameter is defined in this [[ICDTable | table]] for all the ICDs in use during operations. Referring to page 10 of the DQR ICD can done using
 +
<pre>
 +
{{ICD|DQR|page=10|link=DQR ICD}}
 +
</pre>
 +
and creating a link to the PPL ICD can easily be done with the following line
 +
<pre>
 +
{{ICD|PPL|link=PPL ICD}}
 +
</pre>
 +
The examples above result in links to the {{ICD|DQR|page=10|link=DQR ICD}} and the {{ICD|PPL|link=PPL ICD}}.
 +
 +
== Links to PLA products ==
 +
'''<span style="font-size:180%"> <span style="color:Red"><b>This section is now superseded by the documentation included in the templates</b></span></span>.''' 
 +
'''<span style="font-size:180%"> <span style="color:blue"><b>then please remove superseded text to avoid confusion - thank you</b></span></span>.''' 
 +
#For links to single files look here [[Template:PLASingleFile]]
 +
#For links to frequency maps metadata look here [[Template:PLAFreqMaps]]
 +
#For links to component maps metadata look here [[Template:PLACompMaps]]
 +
#For links to catalogues look here (to be added soon)
 +
#For links to Operational files the template below is broken, but it will be fixed soon, and authors should not change anything on pages that make use of the template.
 +
 +
===Maps===
 +
Links to lists of maps available in the archive can be inserted in any page using the [[Template:PLAMaps|PLAMaps]] template. The syntax is
 +
<pre>
 +
{{PLAMaps|type=TYPE|inst=INSTRUMENT|freq=FREQUENCY|link=TEXT}}
 +
</pre>
 +
where "type" is one of DETECTOR, FULL, JACKKNIFE, and SURVEY (these are the names for the map <b>categories</b> when you open the Java WebStart version of the archive), "instrument" is one of LFI and HFI, and "FREQUENCY" is one of the Planck frequencies. You will note that all parameters are optional. If no parameters are supplied you will get a list of all the available {{PLAMaps}}. A list of all the frequency maps can be achieved with
 +
<pre>
 +
{{PLAMaps|type=NOMINAL|link=frequency maps}}
 +
</pre>
 +
The line above results in a link to the list of {{PLAMaps|type=FULL|link=frequency maps}} currently available for DR5.
 +
 +
Please note that this template does not provide a query mechanism (for instance producing a list of all the maps at 44 and 100 GHz). If something like that is required it can also be provided, but this template is certainly not the mechanism for that.
 +
 +
===Operational files===
 +
Links to a list of the operational files available can be inserted in any page using the [[Template:PLAOp|PLAOp]] template. The syntax is
 +
<pre>
 +
{{PLAOp|type|link=TEXT}}
 +
</pre>
 +
where "type" is one of AHF, APS, DHF, DQRH, DQRL, FAHF, GHF, LEV, ORB, PPL, SIAM, WHRL, or WHRH. To obtain a list of all the AHF files available you could write
 +
<pre>
 +
{{PLAOp|AHF|link=AHF files}}
 +
</pre>
 +
If the "link" parameter is omitted an automatic link text will be generated. Using the syntax above we get the following link to the complete list of {{PLAOp|AHF|link=AHF files}}. Note that you may be asked to login to the PLA using your PLA credentials.
  
 
== Use of the available extensions ==
 
== Use of the available extensions ==
 
=== MathJax ===
 
=== MathJax ===
The [http://www.mediawiki.org/wiki/Extension:MathJax MathJax extension] allows the use of [http://www.mathjax.org/ MathJax], a display engine for mathematics providing high quality mathematics fonts. The main interest for the ES lies in its ability to produce high quality display of latex formulae with no need for any extra tags. Equations may simply be written in Latex and MathJax will recognize the Latex Tags.  
+
VERY IMPORTANT NOTE: Although MathJax produces high quality equations, the use of LaTeX tags in the ES wiki is strongly discouraged. Please see the [[#caveat|CAVEAT]] below. In case of doubt please contact the editor.
 +
 
 +
The [http://www.mediawiki.org/wiki/Extension:MathJax MathJax extension] allows the use of [http://www.mathjax.org/ MathJax], a display engine for mathematics providing high quality mathematics fonts. The main interest for the ES lies in its ability to produce high quality display of LaTeX formulae with no need for any extra tags. Equations may simply be written in LaTeX and MathJax will recognize the LaTeX Tags.  
  
 
Simple mathematical expressions can be easily written inline. The following
 
Simple mathematical expressions can be easily written inline. The following
Line 137: Line 258:
 
will be displayed by MathJax as $x^2 + y^2 +z^2 = 1$.
 
will be displayed by MathJax as $x^2 + y^2 +z^2 = 1$.
  
We can write complex equations and even make use of <nowiki>\newcommand </nowiki> as illustrated by the following lines.
+
We can write complex equations and even make use of <nowiki>\newcommand </nowiki>, as illustrated by the following lines.
 
<pre>
 
<pre>
 
$
 
$
Line 157: Line 278:
 
</pre>
 
</pre>
 
MathJax will display these as  
 
MathJax will display these as  
$
+
<math>
  \newcommand{\Re}{\mathrm{Re}\,}
 
  \newcommand{\pFq}[5]{{}_{#1}\mathrm{F}_{#2} \left( \genfrac{}{}{0pt}{}{#3}{#4} \bigg| {#5} \right)}
 
$
 
 
\begin{align}
 
\begin{align}
 
   \label{def:Wns}
 
   \label{def:Wns}
Line 170: Line 288:
  
 
\begin{align}
 
\begin{align}
 +
\newcommand{\Re}{\mathrm{Re}\,}
 +
\newcommand{\pFq}[5]{{}_{#1}\mathrm{F}_{#2} \left( \genfrac{}{}{0pt}{}{#3}{#4} \bigg| {#5} \right)}
 +
 
   \label{eq:W3k}
 
   \label{eq:W3k}
 
   W_3(k) &= \Re \, \pFq32{\frac12, -\frac k2, -\frac k2}{1, 1}{4}.
 
   W_3(k) &= \Re \, \pFq32{\frac12, -\frac k2, -\frac k2}{1, 1}{4}.
 
\end{align}
 
\end{align}
 +
</math>
  
We can also refer to equations with a valid \label using the latex \eqref command. The second of the two eqautions above can be referred to with  
+
We can also refer to equations with a valid \label using the LaTeX \eqref command. The second of the two eqautions above can be referred to with  
 
<pre>
 
<pre>
 
\eqref{eq:W3k}
 
\eqref{eq:W3k}
Line 180: Line 302:
 
resulting in a correct reference to equation \eqref{eq:W3k} above. Note the reference works as a link. Clicking it you will be taken to the equation referred to.
 
resulting in a correct reference to equation \eqref{eq:W3k} above. Note the reference works as a link. Clicking it you will be taken to the equation referred to.
  
Right clicking on an equation will generate a pop up menu that among other things allows to extract the latex code used to generate the equation on the page. [[file:showSource.png|frame|center|MathJax menu]]
+
Right clicking on an equation will generate a pop up menu that, among other things, allows you to extract the LaTeX code used to generate the equation on the page. [[file:showSource.png|thumb|center|700px|MathJax menu]]
Selecting ''Show Source'' a window will pop up showing the latex code used to create the equation displayed. The figure below show the result of this operation applied to \eqref{def:Wns} above.
+
Selecting ''Show Source'' a window will pop up showing the LaTeX code used to create the equation displayed. The figure below show the result of this operation applied to \eqref{def:Wns} above.
[[file:mjSource.png|frame|center|MathJax latex source window]] Note that although copying latex code from this window is allowed, editing the equation n the source code window is not possible.
+
[[file:mjSource.png|thumb|center|700px|MathJax latex source window]] Note that although copying LaTeX code from this window is allowed, editing the equation in the source code window is not possible.
 +
 
 +
<span id="caveat">'''CAVEAT: '''</span>There is unfortunately a caveat associated with the use of MathJax. While MathJax is able to use high quality fonts to display equations, the export of pages using MathJax to LaTeX will in general require some manual editing of the LaTeX source produced.
 +
 
 +
The default equation displaying mechanism for MediaWiki uses the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag and therefore the wiki2latex extension converting MediaWIki to LaTeX will also look for this tag when it looks for the chunks of content that need special treatment (the equations). In MathJax however, the use of the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag is not required and the usual LaTeX tags for equations can be used instead (<code>$</code>...<code>$</code>, <code>\begin{equation}</code>...<code>\end{equation}</code> and so on). This means that when attempting the conversion on a Wiki page containing equations tagged using only the LaTeX standard tags the conversion to LaTeX will not produce the expected result. In most cases this problem can be solved by directly using the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag in equations, since it is accepted by MathJax as a valid way to tag mathematical contents. However, as MathJax can make use of a much larger subset of the LaTeX set of tags dealing with mathematical content than the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag can handle, this means the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag will not be able to handle quite a large number of situations (for instance, in the equations above, using the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag instead of the <code>\begin{align}</code>...<code>\end{align}</code> tags) and may produce unexpected results. The problem is such that when trying to convert MediaWiki directly to pdf using the mechanism described below, the process will in most cases fail. A partial workaround is provided [[Help:Contents#Converting from MediaWiki to latex and pdf| below]].
  
'''CAVEAT''': There is unfortunately a caveat associated with the use of MathJax. While MathJax is able to use high quality fonts to display equations, the export of pages using MathJax to Latex will in general require some manual editing in the Latex source produced. The default equation displaying mechanism for MediaWiki uses the <nowiki><</nowiki><math><nowiki>></nowiki> tag and therefore the wiki2latex extension converting MediaWIki to Latex will also look for this tag when it looks for the chunks of content that need special treatment (the equations). In MathJax however, the use of the <tt>math</tt> tag is not required and the usual Latex tags for equations can be used instead (<tt>$</tt>...<tt>$</tt>, <tt>\begin{equation}</tt>...<tt>\end{equation}</tt> and so on). This means that when attempting the conversion on a Wiki page containing equations tagged using only the Latex standard tags the conversion to Latex will not produce the expected result. In most cases this problem can be solved by using directly the <tt><math></tt> tag in equations as it is accepted by MathJax as a valid way to tag mathematical contents. However, as MathJax can make use of a much larger subset of the Latex set of tags dealing with mathematical content than the <code>math</code> tag can handle, this means the <code>math</code> tag will not be able to handle quite a large number of situations (for instance, in the equations above, using the <code>math</code> tag instead of the <code>\begin{align}</code>...<code>\end{align}</code> tags) and will produce unexpected results.
+
In view of what was said above we advise you to use the <nowiki><code><</nowiki>math<nowiki>></code></nowiki> tag by default. When the desired result is not what you wanted, then use the appropriate LaTeX tags.
The problem is such that when trying to convert MediaWiki directly to pdf using the mechanism described below, the process will in most cases fail. We therefore recommend to proceed as follows
 
  
===Converting from MediaWiki to latex and pdf===
+
===Converting from MediaWiki to LaTeX and PDF===
 +
Conversion from MediaWiki pages to LaTeX and PDF is achieved in Mediawiki by the extension [http://www.mediawiki.org/wiki/Extension:Wiki2LaTeX Wiki2LaTeX]. Because of the use of MathJax, direct conversion to PDF may not always work. The recommended method of converting wiki pages to PDF will therefore consist of several steps with some manual editing necessary if the sections to be converted contain anything other than trivial LaTeX. What trivial means in this context will unfortunately have to be discovered by trial and error on a case by case basis.
  
=== Collection ===
+
Once you have your wiki page ready to be exported proceed as follows:
The [http://www.mediawiki.org/wiki/Extension:Collection Collection extension] allows a user to organise a set of pages as a book that can be converted to pdf. This comes handy for a user that is interested in a few sections of the ES but would rather print only the contents of the sections of interested than the entire ES. The user adds each section of interest to a <i>book</i> using a button on the toolbar. When the selection is complete the generate pdf button is pressed and a pdf version of the selected section, including a table of contents, is generated.
+
#'''Try a direct export to pdf''': In the tool bar at the top of the page of interest choose the latex/pdf tag. [[file:wiki2pdf.png|thumb|center|800px|Wiki2LaTeX tab.]] You will then be taken to the export page. In principle what you see should be very similar to the figure below. If it is not, change the different options in order to match the example below. To proceed with the export press the '''Start Export''' button [[file:topdf.png|thumb|center|700px|Export settings page when exporting to pdf.]] If the export succeeds  you will see something similar to the next figure. In this case you can download the result of the export process by clicking the file name on the top left of the page. You will also be able to download the TeX file generated as part of the export process by clicking on the link on the top right (circled orange).[[file:converted.png|thumb|center|700px|Export was successful.]] If the export fails you will see something like this, where it is clear part of the export process was unsuccessful. [[file:failure.png|thumb|center|700px|Export was unsuccessful.]]In this case do not despair (yet...) and move on to the next step.
 +
#'''Export the wiki page of interest to latex''': When presented with the export options page choose the export to LaTeX, as shown here, and press the '''Start Export''' button. [[file:exportToLatex.png|thumb|center|700px|Export settings page when exporting to LaTeX.]]
 +
#Run LaTeX and manually fix any problems: Once you have a LaTeX file, process it as you would for any other LaTeX file. If you are following this step that means the direct export to PDF failed, so you should not expect LaTeX to run cleanly on the exported file. From here all you have to do is manually fix the exported file and eventually you will end up with a valid LaTeX file. At this point you can generate a pdf file as you normally do for any other LaTeX file.
  
<span style="background:#00FF00"> This section is still incomplete waiting for the extension to be installed. </span>
+
=== PDF book ===
 +
A brief description of how the PDF book facility should be used can be found [[Help:Books|here]].
  
 
=== CategoryTree ===
 
=== CategoryTree ===
The Category tree extension generates a tree on the left hand side of the browser window.
+
[[file:categoryTree.png|frame|right|Category Tree]] The Category tree extension generates a tree on the left hand side of the browser window.
[[file:categoryTree.png|frame|Category Tree]]. The category tree can Each entry on the initial unexpanded tree is a category  
+
Each entry on the initial unexpanded tree is a category. Clicking on each branch of the tree will show all the inner branches. This is very useful for navigating between pages and it is one of the reasons we organized the contents of the ES wiki based on the concept of category.
 +
 
 +
For the ES there is one main category from which all the other categories branch out. The important thing to remember here is that when opening a new category (which should in general not be done unless there is a very good reason for doing so, as discussed [[Help:Contents#Guidelines for development|here]]) is to add in the page for the new category the mother category for the newly created category. This is the only way the category tree can be effectively maintained.
 +
 
 +
As an example we can mention the ''Satellite'' page. This page defines the ''Satellite'' category and since it is not a root category (in our case the only root category is ''Explanatory supplement'') we must tell Mediawiki that ''Satellite'' is a branch of some mother category. In this case the category from which ''Satellite'' branches out is ''Explanatory supplement'' and we establish this fact with the line
 +
<pre>
 +
[[Category:Explanatory supplement]]
 +
</pre>
 +
in the ''Satellite'' page. The inclusion of this line in the ''Satellite'' category page will also guarantee an entry will be generated for it and all its descendant categories in the category tree in the toolbar. Note that although in principle this line can be entered [[file:categoryPage.png|frame|center|A category page displays a list of all its subcategories]] at any point in the page defining the category, to make things easier to follow we will always place it at the bottom of the page defining the Category.
 +
 
 +
Another interesting feature of using the category tree extension is the automatic inclusion in the category page of all the its subcategories. Following the link to the Satellite page this is what we will see.  On top we see the usual content of the page circled in blue (in this case this is the sentence ''This is the content of the Satellite page'') and below that we see a list of all the subcategories branching out of the ''Satellite'' page (circled in orange). The number in front of each subcategory is the number of subcategories for the subcategories of ''Satellite''. At the bottom of the page (circled in black) we see a list of all the categories to which the current category belong.
 +
 
 
===Attachments===
 
===Attachments===
Attachments can be used to include extra information in the form of data, higher resolution images that exceed the 100MB limit for uploaded files or documents in formats other than the ones directly supported by the default MediWiki upload mechanism.  
+
Attachments can be used to include extra information in the form of data, higher resolution images that exceed the 100MB limit for uploaded files, or documents in formats other than the ones directly supported by the default MediWiki upload mechanism.
 +
 
 +
Attachments, as we define them here, are not natively supported by MediaWiki, but as with most other things in MediaWiki an extension was developed to allow the use of [http://www.mediawiki.org/wiki/Extension:PageAttachment attachments with MediaWiki].
 +
 
 +
==Converting LaTeX documents for use in MediaWiki==
 +
As far as we can tell there is no way of exporting a LaTeX document to MediaWiki at a click of a button, and even less so of copying a complex LaTeX document to MediWiki and making MediaWiki understand what the document contains (apart from equations which where dealt with [[Help:Contents#MathJax|above]]). There is, however, an external tool, [http://johnmacfarlane.net/pandoc/ pandoc], that will do the job. You need to download it and install it in your computer, but installation is straightforward and should not be a problem. Pandoc is a versatile and powerful translator between markup languages, but as far as we are concerned for the ES wiki the basic syntax is
 +
<pre>
 +
pandoc input.tex -f latex -t mediawiki -o output.mdw
 +
</pre>
 +
where <tt>input.tex</tt> is the input latex file, the -f and -t option are followed by the markup language '''f'''rom which and '''t'''o which we want to perform the conversion (in our case atex and mediawiki) and the name following the -o option is the name of the output file containing the MediaWiki content. Note the .mdw extension is completely arbitrary.
  
Attachments as we define them here are not natively supported by MediaWiki but as with most other things in MediaWiki an extension was developed to allow the use of [http://www.mediawiki.org/wiki/Extension:PageAttachment attachments with MediaWiki].
+
Once your LaTeX files where translated to MediaWiki markup they can easily be inserted in the ES wiki with a simple cut and paste.
  
==Converting latex documents for use in MediaWiki==
+
'''CAVEAT''':I did some testing of this tool and although for very complex LaTeX files it may '''not''' always work immediately, by copying the relevant portions of the LaTeX files we want to export to MediaWiki and processing them separately this seems to work very well. I am performing some further testing with this tool, with special emphasis on exporting bibtex files to MediaWiki and I will report the results here very shortly.
As far as we can tell there is no way of exporting a latex document to Media Wiki at a click of a button, and even less so of copying a complex latex document to MediWiki and making MediaWiki understand what the document contains (apart from equations which where dealt with [[Help:Contents#MathJax|above]]). The best that can be done at the moment seems to be the used of blabala. We where able to install it on
+
==Other useful stuff==
 +
=== Usefull help pages and tutorials ===
 +
*[http://qed.princeton.edu/index.php/MediaWiki:Color_Names Font colors] in mediawiki;
 +
*[http://www.mediawiki.org/wiki/Help:Tables Tables tutorial]
  
'''CAVEAT''': Unfortunately processing a very complex latex document with this tool may not always produce the desired results in one simple pass. Simple constructs like tables and simple equations are processed almost flawlessly. However when it comes to complex tables, equations or any constructs based on \new command things seem to be a lot more complicated. Our advice here is to process the input documents in small chunks and add everything that is still missing after the conversion or has incorrectly been converted by hand.
+
== References ==
 +
<references />

Latest revision as of 01:01, 25 September 2014

Organization of the Explanatory Supplement[edit]

The Explanatory Supplement (ES) is organized in terms of what MediaWiki calls Categories. Using categories provides an automatic mechanism for Index and Table of Contents generation that would otherwise be time consuming and error prone. On top of that, there are a number of extensions based on the category concept, providing a useful set of features for the development, maintenance, and use of this Wiki.

Each of the entries in the table of contents in the Main Page is a category. Categories are pages (and for the ES one expects them to be reasonably self contained for the subject they cover) and can independently be added to a Collection. A typical example can be found in the Mission Products Section: a user interested in frequency maps may or may not be interested in timelines as well, but will certainly be interested in understanding the formats in which the maps are stored, the naming conventions, the size of the maps, and will most likely also look for the details of the mapmaking process, possibly in the form of

papers explaining algorithms. It will therefore make sense for the frequency maps page to contain sections on format, naming conventions, size and references to the map making process. On the other hand, the description of the timelines will most naturally appear under a different page. In order not to end up with a huge number of separate pages, instead of creating a page for frequency maps only, we grouped all the map products under a single maps page that is also a category. After all, it is not entirely unexpected that a user interested in frequency maps may also be interested in other types of map.

Guidelines for development[edit]

In order to keep the development of the wiki under control we would like to ask all contributors to follow a set of very simple guidelines.

  • Each topic on the table of contents is assigned to particular contributors (look here for the current list). This does not mean the others cannot make minor changes or corrections, but in general it would be advisable that contributors not assigned to a specific topic refrain from making major corrections on that topic's pages.
  • A very concise help section with some recipes for common editing actions can be found below. For a more detailed User Guide please refer to the MediaWiki User's Guide.
  • Concerning pages mostly contributed to by other contributors, try to keep in mind the following.
    • Fixing typos or performing minor corrections is encouraged, so if you find those please go ahead and fix them.
    • If what you have in mind is a major rewriting, or you would like to propose extensive changes, we ask you not to do so before discussing it with all those concerned. For each page there is a discussions page associated, which can be accessed through one of the tabs at the top. Please use this to more widely circulate the changes you would like to propose.
Location of the discussion tab
  • If you would like to add a new page, bear the discussion in mind above. If you are still convinced that the new page is necessary, make your intention known on the discussion page associated with the root page of your new page. If your proposal is approved then follow the procedure for the creation of a new page

Note that as all contributors have access to the entire wiki, the enforcement of these simple rules depends on self-discipline and it is absolutely essential that you stick to them.

Template for product description[edit]

In order to create a uniform document, we suggest using a template for product descriptions. A tentative version can be found here. Any suggestions or comments on this proposal are more than welcome.

In order to use it, navigate to the page with the template, copy the MediWiki content by entering the edit page and pasting it to the pages describing the product(s) you are editing.

Keeping track of changes[edit]

Changes can be traced through the recent changes page. However, for those of us who would like to keep up to date on the status of the wiki, it may not always be convenient to login to the ES wiki just for the purpose of tracking changes. In that case it is possible to use RSS feeds to stay informed of all the changes. All you need is an RSS client. If you point your client to http://www.sciops.esa.int/wikiSI/planckpla/index.php?title=Special:RecentChanges&instance=Planck_PLA_ES&feed=rss you will be notified every time the recent changes page is updated, which should trace all the updates in the content of the wiki. These notifications consist of a link to a page showing the differences between the old and the new versions of the updated page.

This mechanism should also work with and atom feed, although testing in this case has not been done. In this case just use feed=atom instead of feed=rss in the url provided to your news reader.

For those with android phones or tablets, we have a very simple locally developed rss client. It is extremely simple, but can easily be customized to suit the specific requirements of individual ES wiki developers.

Contributors list[edit]

TBW

Common tasks[edit]

Including figures[edit]

Uploading a figure[edit]

We consider two possibilities: small figures that should be displayed in the wiki pages; and larger, high resolution figures that are referred to in the wiki pages, but are not intended to be embedded in the page itself. Here we deal with the first case. For the second possibility, have a look here.

Figures can be embedded in the text with the [[File]] tag. This tag has a large number of options for resizing, borders, formatting, and more, and the details can be found here. The basic use is very simple, however. Placing a

[[File:image.png]]

in the text will create a link when the page is displayed. Clicking on that link will cause a selection page to appear and the file to be embedded can then be selected.

Selection page for uploads

To produce the figure included above, showing the location of the discussion tab, the syntax used was

[[File:discussion.png|frame|Location of the discussion tab]]

In this case the frame option indicates that the images will be displayed within a frame and the last field is the caption of the figure. Note that captions may behave a little differently from what was expected: when a caption is given and the frame option is used, the caption will appear just below the figure inside the frame; and when no frame option is used, the caption will be displayed when hovering with the mouse over the figure. One more thing to note is that any size options do not have any effect when the frame option is used. For details you are strongly advised to look here.

Once an image is uploaded and displayed on a page, left clicking on the image in the wiki will show a page with information about that image, a special link allowing its update, and a special link allowing its deletion. This page will also show the history of the figure, with an entry for the original upload and one more entry for every time the figure was updated. In this case we see that three different versions of the image were uploaded.

File history info

From here it is easy to navigate back to any page where the figure appears by using any of the links at the bottom of the page under the heading File Links.

Reusing a figure[edit]

Once the file containing the figure has been uploaded we can display it again with the same syntax. The figure below was produced using exactly the same syntax as before.

Location of the discussion tab

The important thing to take into account here is to use the same name as was used for the image when it was first uploaded. In this case the name to use is discussion.png, regardless of the filename in the user's disk. Note that the name of a figure in the wiki is completely independent of the original name of the figure on the user's computer.

List of figures available in the wiki[edit]

It is not possible to display a list containing only the figures upload to the wiki. However a list of all the files uploaded can be easily generated. In order to retrieve a list of all the files that were uploaded to the wiki, the following steps should be followed

  1. Click on the "Special Pages" link on the toolbox on the left.
  2. In the "Special Pages" page follow the File List link under 'Media reports and uploads'. Here you will find a list of all the files uploaded to the wiki so far, as shown in the figure below.
FIle list

Naming convention[edit]

In order to avoid the possibility of name clashes between images uploaded by differnet contributors we ask you to strictly adhere to the following name convention:

DPC_x_[x_x_x]_fileName.ext

Here DPC is one of HFI or LFI, x_x_x_x the section number for the page where the image will be displayed (where the [] indicates that the rightmost xs may be ommited if the section number does not contain all the four possible digits), fileName the filename to be used in the Wiki, and ext the extension describing the format of the image.

A png figure uploaded by the LFI to be displayed in section 2.3 would be named LFI_2_3_someName.png and a jpeg figure uploaded by the HFI to be displayed in section 6.4.3.1 would be named HFI_2_3_someOtherName.jpg.

Links[edit]

Links to other pages in the wiki[edit]

A link to a page in the ES wiki is achieved with the following syntax:

[[PageName]]
[[PageName|link]]

Here the first line produces a link where the link text is PageName and the second a link with the text link link. As an example of the first syntax type, we have [[Main Page]] producing a link to the Main Page of this wiki. For the second syntax type, we can write [[Main Page|Table of Contents]], which produces a link to the ES Table of Contents.

If the page we wish to link to is a Category a small addition to the syntax is required. In this case the page name will necessarily be of the form Category:PageName. However, just using Category:PageName as PageName in the link syntax as defined above will:

  1. introduce the page where it appears in the Category hierarchy;
  2. produce a link to Category:PageName at the bottom of the page.

This can be put to good use (see below), but it is not what have in mind here. To produce a normal link to a category page a semi-colon must be added before Category:PageName:

[[:Category:PageName]]
[[:Category:PageName|link]]

These two different syntax types work exactly as in the examples above. A link to the maps chapter can produced with [[:Category:Maps|maps chapter]], resulting, as expected in a link to the maps chapter in the ES.

It is also possible to define a link to an anchor defined in a page. Linking to a section in a page is the simplest case, since section headers (defined with the = syntax) provide automatic anchors. In this case the syntax is

[[PageName#SectionName]]
[[PageName#SectionName|link]]

where the two different syntax types work as described above. As an example, the link at the beginning of this paragraph was produced with

 
[[Help:Contents#New section in an existing page|''='' syntax]].

If an anchor reference starts with a #, a link to the current page will be generated.

Defining an arbitrary anchor inside a page requires html. Unfortunately the <a> tag cannot be used in mediawiki. However, using

with the id attribute can be used to create an anchor. The following piece of code
some text <div id="anchor_definition"></div> and even more text
...
and a link to the text [[#anchor_definition|above]]

The following link uses this syntax.

Links to external pages[edit]

In this case the syntax is

[url text]

Linking to the ESA Planck page can be achieved with

[http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17 ESA Planck page]

and results in this link to the ESA Planck page. Dropping text will also work, as expected, but with a different appearance. With

[http://sci.esa.int/science-e/www/area/index.cfm?fareaid=17]

we produce [1].

When comparing with the syntax for internal links, note the use of a single [ instead of [[and also note that the link text is separated by the url with a space and there is no need for a | as in the case of internal links.

External links can be easily identified in the displayed pages by an arrow next to the link.

Uploading documents[edit]

Uploading a document can be done exactly as described above for figures. Note, however, that the file types that can be uploaded are limited to png, gif, jpg, jpeg, pdf, txt, zip, and the size of each individual document is limited to 100MB. What this means is that MediWiki knows what to do with files of these types (a png or jpg files will be displayed without the need to explicitely tell MediWiki to display them).

For files of other types please have a look at the section Attachments below.

External documents[edit]

It is possible to include in the ES wiki extra information in the form of data, higher resolution images that exceed the 100MB limit for uploaded files, or documents in formats other than the ones directly supported by the default MediWiki upload mechanism.

For this purpose we created a special area in livelink. Inside the Explanatory supplement documents folder we created one subfolder per ES chapter. Documents can be uploaded following the same procedures as for any other Livelink document. In order to link to an external document in the ES area of livelink, all you need to do is create a link to the document as explained in the Links to external pages section above.

The following line creates a link to a test document in the ES area in livelink.

[http://www.rssd.esa.int/llink/livelink/open/3111114#page=10 example link]

Clicking on this example link will retrieve a test document from Livelink.

Adding a new section[edit]

New section in an existing page[edit]

In this case the syntax is the following:

==New Section==
===New Subsection===
====New SubSubSection====

More details can be found in the MediaWiki User's Guide.

New section as a new page[edit]

Should the new section appear as a new page (see the guidelines above on the addition of new pages) the Category syntax should be used:

STEP 1: Add a link to the (still non-existent) new page in the Table of Contents on the Main Page:

Assuming a new page with the title New Page is to be added to the ES, add the line
[[:Category:New Page|New Page]]
to the Main Page. This will create a link to the (yet non-existent) page New Page. Note the slightly different link syntax: the : after the [[ is required otherwise the tag would be interpreted not as a link but as a Category hierarchy definition (see step 2 below).
When the Category link above is added to the Main Page make sure it appears in the correct location, since the Main Page is basically a table of contents for the ES.

STEP 2: Create the page (and Category):

Clicking on the link just created in step 1 (which will be displayed in red as the page still does not exist) will take you to an empty page displaying the warning You have followed a link to a page that does not exist yet. Enter the content of the new page as you would for any other page. Since we want this page to be part of the category tree enter the line
[[Category:TopCategory]]
where TopCategory is the existing category under which the new category will appear in the Category Tree. If this last step step is missed the new page will not be part of the Category Tree and you will therefore not be able to take advantage of the Category Tree features. The line above can be entered anywhere on the page, but the structure of the page results are easier to understand if it appears consistently at the end.
For example, in the Catalogues section under mission products, the following line appears at the end of the page:
[[Category:Mission products]]
This guarantees the maps section will correctly appear in the Category Tree

Very important point[edit]

Please bear in mind that

[[Category:myPage]]

and

[[myPage]]

are completely different entities. The first defines a Category called my page and the second defines a page with the same name, but they can coexist separately and independently. If you add some content to myPage and then look for it in Category:myPage you will obviously not find it. This point can be a bit confusing so please bear it in mind before taking any further action if what you see in some page is completely different from what you were expecting to find.

Referencing documents[edit]

Planck Collaboration papers[edit]

Citations to Planck papers can be included in the text using the PlanckPapers template. For the documentation have a look here.

This is an example of a citation Planck-2013-XXXI[1]. The template produces a direct link to the paper, and a link to the full bibliographical record in the form of a number enclosed in square brackets. Clicking on the number will take the reader to the bibliographical record in the References section at the bottom of the page (assuming the page author has followed the instructions in the template documentation). From the references list it is easy to return to the exact location where the citation was produced in the page by clicking on the little arrow or in the numbers next to the arrow. Additionally when hovering the mouse over the link in the text a tooltip will appear containing the full reference and a link to the paper or to its abstract in the electronic version of the journal where it was published or in the arXiv. Important note: the tooltip may not display correctly in every browser, since it was tested only on Firefox and Chrome. In any case the link to the paper can also be found in the full record at the bottom of the page.

Other papers[edit]

References to non-Planck papers can be introduced in the text using the BibCite temaplate. The documentation can be found here here.

Citation in the text look like this[2]. This is similar to the citation to Planck papers except that this time there is no direct link to the paper in the text.

Adding entries to the bibliography[edit]

TBW

Citing a reference[edit]

TBW

Planck interface control documents (ICDs)[edit]

For references to the Planck ICDs a very similar mechanism to the one described above for the Planck papers can be used. In this case the template is called ICD and the syntax would be

{{ICD|name|page=page_number|link=link_text}}

The parameters page and text are optional and they work as described above. If "page" is omitted the ICD will open in page 1. If "link" is omitted the link text will be ICD. The name parameter is defined in this table for all the ICDs in use during operations. Referring to page 10 of the DQR ICD can done using

{{ICD|DQR|page=10|link=DQR ICD}}

and creating a link to the PPL ICD can easily be done with the following line

{{ICD|PPL|link=PPL ICD}}

The examples above result in links to the DQR ICD and the PPL ICD.

Links to PLA products[edit]

This section is now superseded by the documentation included in the templates. then please remove superseded text to avoid confusion - thank you.

  1. For links to single files look here Template:PLASingleFile
  2. For links to frequency maps metadata look here Template:PLAFreqMaps
  3. For links to component maps metadata look here Template:PLACompMaps
  4. For links to catalogues look here (to be added soon)
  5. For links to Operational files the template below is broken, but it will be fixed soon, and authors should not change anything on pages that make use of the template.

Maps[edit]

Links to lists of maps available in the archive can be inserted in any page using the PLAMaps template. The syntax is

{{PLAMaps|type=TYPE|inst=INSTRUMENT|freq=FREQUENCY|link=TEXT}}

where "type" is one of DETECTOR, FULL, JACKKNIFE, and SURVEY (these are the names for the map categories when you open the Java WebStart version of the archive), "instrument" is one of LFI and HFI, and "FREQUENCY" is one of the Planck frequencies. You will note that all parameters are optional. If no parameters are supplied you will get a list of all the available Frequency Maps. A list of all the frequency maps can be achieved with

{{PLAMaps|type=NOMINAL|link=frequency maps}}

The line above results in a link to the list of frequency maps currently available for DR5.

Please note that this template does not provide a query mechanism (for instance producing a list of all the maps at 44 and 100 GHz). If something like that is required it can also be provided, but this template is certainly not the mechanism for that.

Operational files[edit]

Links to a list of the operational files available can be inserted in any page using the PLAOp template. The syntax is

{{PLAOp|type|link=TEXT}}

where "type" is one of AHF, APS, DHF, DQRH, DQRL, FAHF, GHF, LEV, ORB, PPL, SIAM, WHRL, or WHRH. To obtain a list of all the AHF files available you could write

{{PLAOp|AHF|link=AHF files}}

If the "link" parameter is omitted an automatic link text will be generated. Using the syntax above we get the following link to the complete list of AHF files. Note that you may be asked to login to the PLA using your PLA credentials.

Use of the available extensions[edit]

MathJax[edit]

VERY IMPORTANT NOTE: Although MathJax produces high quality equations, the use of LaTeX tags in the ES wiki is strongly discouraged. Please see the CAVEAT below. In case of doubt please contact the editor.

The MathJax extension allows the use of MathJax, a display engine for mathematics providing high quality mathematics fonts. The main interest for the ES lies in its ability to produce high quality display of LaTeX formulae with no need for any extra tags. Equations may simply be written in LaTeX and MathJax will recognize the LaTeX Tags.

Simple mathematical expressions can be easily written inline. The following

$x^2 + y^2 +z^2 = 1$

will be displayed by MathJax as $x^2 + y^2 +z^2 = 1$.

We can write complex equations and even make use of \newcommand , as illustrated by the following lines.

$
  \newcommand{\Re}{\mathrm{Re}\,}
  \newcommand{\pFq}[5]{{}_{#1}\mathrm{F}_{#2} \left( \genfrac{}{}{0pt}{}{#3}{#4} \bigg| {#5} \right)}
$
\begin{align}
  \label{def:Wns}
  W_n (s)
  &:= 
  \int_{[0, 1]^n} 
    \left| \sum_{k = 1}^n \mathrm{e}^{2 \pi \mathrm{i} \, x_k} \right|^s \mathrm{d}\boldsymbol{x}
\end{align}

\begin{align}
  \label{eq:W3k}
  W_3(k) &= \Re \, \pFq32{\frac12, -\frac k2, -\frac k2}{1, 1}{4}.
\end{align}

MathJax will display these as [math] \begin{align} \label{def:Wns} W_n (s) &:= \int_{[0, 1]^n} \left| \sum_{k = 1}^n \mathrm{e}^{2 \pi \mathrm{i} \, x_k} \right|^s \mathrm{d}\boldsymbol{x} \end{align} \begin{align} \newcommand{\Re}{\mathrm{Re}\,} \newcommand{\pFq}[5]{{}_{#1}\mathrm{F}_{#2} \left( \genfrac{}{}{0pt}{}{#3}{#4} \bigg| {#5} \right)} \label{eq:W3k} W_3(k) &= \Re \, \pFq32{\frac12, -\frac k2, -\frac k2}{1, 1}{4}. \end{align} [/math]

We can also refer to equations with a valid \label using the LaTeX \eqref command. The second of the two eqautions above can be referred to with

\eqref{eq:W3k}

resulting in a correct reference to equation \eqref{eq:W3k} above. Note the reference works as a link. Clicking it you will be taken to the equation referred to.

Right clicking on an equation will generate a pop up menu that, among other things, allows you to extract the LaTeX code used to generate the equation on the page.
MathJax menu

Selecting Show Source a window will pop up showing the LaTeX code used to create the equation displayed. The figure below show the result of this operation applied to \eqref{def:Wns} above.

MathJax latex source window
Note that although copying LaTeX code from this window is allowed, editing the equation in the source code window is not possible.

CAVEAT: There is unfortunately a caveat associated with the use of MathJax. While MathJax is able to use high quality fonts to display equations, the export of pages using MathJax to LaTeX will in general require some manual editing of the LaTeX source produced.

The default equation displaying mechanism for MediaWiki uses the <code><math></code> tag and therefore the wiki2latex extension converting MediaWIki to LaTeX will also look for this tag when it looks for the chunks of content that need special treatment (the equations). In MathJax however, the use of the <code><math></code> tag is not required and the usual LaTeX tags for equations can be used instead ($...$, \begin{equation}...\end{equation} and so on). This means that when attempting the conversion on a Wiki page containing equations tagged using only the LaTeX standard tags the conversion to LaTeX will not produce the expected result. In most cases this problem can be solved by directly using the <code><math></code> tag in equations, since it is accepted by MathJax as a valid way to tag mathematical contents. However, as MathJax can make use of a much larger subset of the LaTeX set of tags dealing with mathematical content than the <code><math></code> tag can handle, this means the <code><math></code> tag will not be able to handle quite a large number of situations (for instance, in the equations above, using the <code><math></code> tag instead of the \begin{align}...\end{align} tags) and may produce unexpected results. The problem is such that when trying to convert MediaWiki directly to pdf using the mechanism described below, the process will in most cases fail. A partial workaround is provided below.

In view of what was said above we advise you to use the <code><math></code> tag by default. When the desired result is not what you wanted, then use the appropriate LaTeX tags.

Converting from MediaWiki to LaTeX and PDF[edit]

Conversion from MediaWiki pages to LaTeX and PDF is achieved in Mediawiki by the extension Wiki2LaTeX. Because of the use of MathJax, direct conversion to PDF may not always work. The recommended method of converting wiki pages to PDF will therefore consist of several steps with some manual editing necessary if the sections to be converted contain anything other than trivial LaTeX. What trivial means in this context will unfortunately have to be discovered by trial and error on a case by case basis.

Once you have your wiki page ready to be exported proceed as follows:

  1. Try a direct export to pdf: In the tool bar at the top of the page of interest choose the latex/pdf tag.
    Wiki2LaTeX tab.
    You will then be taken to the export page. In principle what you see should be very similar to the figure below. If it is not, change the different options in order to match the example below. To proceed with the export press the Start Export button
    Export settings page when exporting to pdf.
    If the export succeeds you will see something similar to the next figure. In this case you can download the result of the export process by clicking the file name on the top left of the page. You will also be able to download the TeX file generated as part of the export process by clicking on the link on the top right (circled orange).
    Export was successful.
    If the export fails you will see something like this, where it is clear part of the export process was unsuccessful.
    Export was unsuccessful.
    In this case do not despair (yet...) and move on to the next step.
  2. Export the wiki page of interest to latex: When presented with the export options page choose the export to LaTeX, as shown here, and press the Start Export button.
    Export settings page when exporting to LaTeX.
  3. Run LaTeX and manually fix any problems: Once you have a LaTeX file, process it as you would for any other LaTeX file. If you are following this step that means the direct export to PDF failed, so you should not expect LaTeX to run cleanly on the exported file. From here all you have to do is manually fix the exported file and eventually you will end up with a valid LaTeX file. At this point you can generate a pdf file as you normally do for any other LaTeX file.

PDF book[edit]

A brief description of how the PDF book facility should be used can be found here.

CategoryTree[edit]

Category Tree
The Category tree extension generates a tree on the left hand side of the browser window.

Each entry on the initial unexpanded tree is a category. Clicking on each branch of the tree will show all the inner branches. This is very useful for navigating between pages and it is one of the reasons we organized the contents of the ES wiki based on the concept of category.

For the ES there is one main category from which all the other categories branch out. The important thing to remember here is that when opening a new category (which should in general not be done unless there is a very good reason for doing so, as discussed here) is to add in the page for the new category the mother category for the newly created category. This is the only way the category tree can be effectively maintained.

As an example we can mention the Satellite page. This page defines the Satellite category and since it is not a root category (in our case the only root category is Explanatory supplement) we must tell Mediawiki that Satellite is a branch of some mother category. In this case the category from which Satellite branches out is Explanatory supplement and we establish this fact with the line

[[Category:Explanatory supplement]]
in the Satellite page. The inclusion of this line in the Satellite category page will also guarantee an entry will be generated for it and all its descendant categories in the category tree in the toolbar. Note that although in principle this line can be entered
A category page displays a list of all its subcategories
at any point in the page defining the category, to make things easier to follow we will always place it at the bottom of the page defining the Category.

Another interesting feature of using the category tree extension is the automatic inclusion in the category page of all the its subcategories. Following the link to the Satellite page this is what we will see. On top we see the usual content of the page circled in blue (in this case this is the sentence This is the content of the Satellite page) and below that we see a list of all the subcategories branching out of the Satellite page (circled in orange). The number in front of each subcategory is the number of subcategories for the subcategories of Satellite. At the bottom of the page (circled in black) we see a list of all the categories to which the current category belong.

Attachments[edit]

Attachments can be used to include extra information in the form of data, higher resolution images that exceed the 100MB limit for uploaded files, or documents in formats other than the ones directly supported by the default MediWiki upload mechanism.

Attachments, as we define them here, are not natively supported by MediaWiki, but as with most other things in MediaWiki an extension was developed to allow the use of attachments with MediaWiki.

Converting LaTeX documents for use in MediaWiki[edit]

As far as we can tell there is no way of exporting a LaTeX document to MediaWiki at a click of a button, and even less so of copying a complex LaTeX document to MediWiki and making MediaWiki understand what the document contains (apart from equations which where dealt with above). There is, however, an external tool, pandoc, that will do the job. You need to download it and install it in your computer, but installation is straightforward and should not be a problem. Pandoc is a versatile and powerful translator between markup languages, but as far as we are concerned for the ES wiki the basic syntax is

pandoc input.tex -f latex -t mediawiki -o output.mdw

where input.tex is the input latex file, the -f and -t option are followed by the markup language from which and to which we want to perform the conversion (in our case atex and mediawiki) and the name following the -o option is the name of the output file containing the MediaWiki content. Note the .mdw extension is completely arbitrary.

Once your LaTeX files where translated to MediaWiki markup they can easily be inserted in the ES wiki with a simple cut and paste.

CAVEAT:I did some testing of this tool and although for very complex LaTeX files it may not always work immediately, by copying the relevant portions of the LaTeX files we want to export to MediaWiki and processing them separately this seems to work very well. I am performing some further testing with this tool, with special emphasis on exporting bibtex files to MediaWiki and I will report the results here very shortly.

Other useful stuff[edit]

Usefull help pages and tutorials[edit]

References[edit]

  1. Planck 2013 results. XXXI. Consistency of Planck data, Planck Collaboration, 2014, A&A, 571, A31.
  2. First-Year Wilkinson Microwave Anisotropy Probe (WMAP) Observations: Interpretation of the TT and TE Angular Power Spectrum Peaks, L. Page, M. R. Nolta, C. Barnes, C. L. Bennett, M. Halpern, G. Hinshaw, N. Jarosik, A. Kogut, M. Limon, S. S. Meyer, H. V. Peiris, D. N. Spergel, G. S. Tucker, E. Wollack, E. L. Wright, ApJS, 148, 233-241, (2003).

Explanatory Supplement

Data Processing Center

(Planck) High Frequency Instrument

(Planck) Low Frequency Instrument

European Space Agency

Interface Control Document

Daily Quality Report

Pre-programmed Pointing List

Planck Legacy Archive

Attitude History File

Spacecraft Instrument Alignment Matrix