Introduction

This document describes the appropriate style to be used in adding content to the CASA Docs.  Please follow these guidelines when writing and editing documentation.

CASA Docs Organization

The CASA Docs are organized first by CASA release version. You can see this by opening the CASA Docs home page.  The latest version of the documentation is the "Stable" version. Other released versions of CASA, beginning with CASA 5.0 are also available here. At the time of a CASA release, a snapshot of the stable documentation will be taken and that documentation will be frozen on the Plone server.

Within each release version, the CASA documentation is divided into chapters, which may be selected from the directory at the left sidebar. Each chapter may have one or more pages, and each page may have zero or more subpages.  The only difference between a page and subpage is the way the item is formatted in the left sidebar directory.  Subpages are indented, whereas pages are not.  This allows authors to break long sections into multiple pages and indicate to the reader that the content is all related.  Aside from directory indentation, pages and subpages are identical.

This style guide provides instructions on how to format different elements of each page. The goal is to have a rather uniform CASAdocs look and feel.  

Page Design and Layouts

Headers

Content within a page can be divided into sections by using headers.  Four headers are available from the "Formats->Formats->Headers" pull down menu.  The highest level sections should use Header 1, followed by Header 2, 3, and 4.

Header 1

Header 2

Header 3

Header 4

All section headers should be left aligned. 

Captions for Tables, Figures, Equations etc.

To create a caption that can be referenced from the text, place your cursor directly underneath the table. Then select "Insert->Insert Template->Caption" and press ok. That will create a caption box. In the "Type" field, enter "Table" for Tables, "Figure" for figures, etc. and under "ID", create an identifier text that is unique. We recommend to use a scheme like "pagename-fig/tab/eq/fn-identifier' where the second word is fig for figures, tab for tables, eq for equations, and fn for footnotes. e.g. "styleguide-fig-casalogo" for the caption of the CASA logo below. Under "Caption" enter the caption text. Save the page. In the updated page, the caption will show a little link symbol and clicking on it reveals a unique URL. This URL can then be used to refer to the table in the text. Select as 'external URL' and add the string when the link is created in plone.

See the Table and Figure captions below for examples.

Tables 

Tables are created through "Table"->"Insert Table". As a first step, define the numbers of rows and column on the displayed grid.

Headers can be used within tables to create heading cells for rows, columns, or the entire table.  We use a template for the property of all header cells. Place the cursor in a cell, or mark the cell or multiple content. Multiple cells can be selected. Right-click and go to "Cell Properites"  and switch "Cell Type" to "Header Cell".  Although little may change, setting the cell type to "Header" will allow the automatic application of table header templates that will propagate throughout the document.  

Table captions are inserted as described above.

Images

Images may be added using the "Insert/Edit Image" button  in the editor control bar (the little postcard symbol).  It is highly recommended to include multiple images with documentation in order to add an illustrative dimension to content. Captions should be added as described above.

Sizing

Alignment

Equations/Text and Math Formatting

LaTex/MathJax

LaTex code can be used to render math and long text documentation. This is possible through a local version of MathJax. 

Inserting a formula with MathJax

Our local version of MathJax uses  $...$ as a delimiter to signal an equation.

$a^2 + b^2 = c^2$

(the above was using the "Pre" formatting, which does not render latex, but shows text verbatim)

will lead to 

$a^2 + b^2 = c^2$. 

Other characters, such as "&" can occasionally cause formatting issues when placed inside a MathJax formula. This can be fixed by replacing the "&" with its hexidecimal unicode: \unicode{x26}, or placing it outside the /$.../$

delimiters to prevent it from rendering in MathJax.  

Equations can have captions as decribed above.

Preventing LaTex/MathJax When it is not Wanted

Where more than one dollar sign is used in a block of text, MathJax may be triggered unintentionally.  To prevent this, a special HTML tag may be used.  Follow these steps:

1. To edit HTML, change the drop-down menu below the editor window to "text/x-web-textile". 
2. Find the dollar sign that is being interpreted as the beginning of the MathJax code. 
3. Put that dollar sign into an HTML span block with class equal to "tex2jax_ignore":

   <span class="tex2jax_ignore">$span>

Note that the span block can include more than just the dollar sign, and everything inside the span block will be excluded from MathJax interpretation.

CASA Formatting

CASA tasks and tool (methods) are in bold font, parameters of task or tools in italics. For example. "In gaincal set caltable='table.cal' to define the output name of the calibration table." Similarly, use italics when referring to table columns, like CORRECTED_DATA. 

Known task names will be automatically rendered by Plone, creating links to the task/tool description. This is based on a table of known tasks. If a task is not recognized, please submit a JIRA ticket to Anand to have it added to the list of known tasks. We maintain a list of tasks that are auto-linked and ones that are not. For instance, the task find is not linked (as it appears a lot in regular text).

Shell commands will be formatted with "Courier New" and in italics, e.g. "ls -rt".

Python code will be written in "Courier New" (regular font/no italics) "listobs(vis='test.ms')".

 Other writing conventions:

• If you want to place an emphasis on a text, italics are acceptable. Other options could be underline text to distinguish from parameters. And don't forget that there are boxes as explained in the next paragraph. 
• Names of books, organizations, space-based telescopes should be italicized.
• Use “Formats” → “Block” →  “Blockquote” for long quotes or indented paragraphs.
• Strikethroughs may be used to indicate the omission of text, while still leaving the omitted text available to view.

CASA Naming Convention

if possible use the following spelling conventions throughout the document:

MeasurementSet
Multi-MS
Sub-MS
MS
MMS

Tags and Paths

General Tags and Alert Boxes

We have a number of different pre-defined boxes. 

1) For CASA inputs, please use the approriate "CASA input box" from the "en.Insert template" button (looks like a shelf): 

interface listings will also go into a CASA input box. The CASA input and output boxes shall be formatted in fixed width font. To do so, mark the text and select "Font Family->Courier New". For clarification, The text could start with '#In CASA": 

2) For CASA ouput, we have a different template "CASA output box" 

3) Alert Boxes. Alerts are quite frequent in the cookbook. To transfer those and in general to point out important issues, please use the "Alert Box" option in the "en.Insert template" tool, add "Alert:" in bold: 

4) Information Boxes: They can be used if additional material is being pointed out that is not critical. Could be references to futher reading, references to the toolbok etc. Add "Info:" in bold when appropriate:

5) Terminal/shell commands: 

Use the "Terminal" template. It will create a grey box. Use again Courier New font. You can add "#In Terminal" if it helps distinguishing shell from CASA commands. 

6) Some highlighting can also be obtained with the "Format"->"Formats"->"Block"->"Pre" setting. Note, however, that some formatting may be lost.

p.callout - Inserts a grey highlight box. 

Paths

When creating paths between functions and pages on plonedocs, use Relative Paths rather than UIDs. This will alow paths to remain intact when versions of plonedocs are rolled over.   

Anchors

If the anchor is to a section of the current page, then mark the relevant text, and open the link menu. Go to the anchor tab and select the section from the drop-down menu. An anchor can also be set anywhere with the "Anchor" template ("Insert->Insert Template->"Anchor". It will work just as figure and table captions, but not display any text. Once the "Anchor"  template is set and given a unique id, save the file and click on the link symbol at that location. The pop-up will reveal a unique link that can be used at the referring text. To avoid confusion, we again recommend an identifier naming scheme like "pagename-an-identifier' (where "an" stands for "anchor").

Links/URLS 

URLs shall be hidden in most cases and linked in the text appropriately. There are exceptions where the URL can be spelled out entirely (e.g. my.nrao.edu). Feel free to use the most appropriate way. 

Footnotes 

Footnotes are not automatically numbered, so please take care about the numbering. First, insert a footnote marker template "Insert->Insert Template->Link to Footnote". Insert a footnotemarker that is unique for the given page.^[a]  

Then create the footnote itself. Insert a "Footnote" template ("Insert->Insert Template->Footnote") and a box will be created where the relevant footnotemarker can be specified as well as the footnote text. The footnote will automatically appear at the bottom of the document in a "Footnote(s)" section, in alphabetical order, independent of the location of this box.

Citations/Bibliography

Similar to footnotes, there are two templates for bibliography references. We recommend astronomy stle reference formats: 

CASAdocs will apply regular astronomy citation style. 

e.g. 

for two-author papers:

Pan & Doe (1999) [1]

three-author papers:

Pan, Doe, & Kern (2000) [2]

more than three authors: 

Pan et al. (2001) [3]

If there are more than one paper per year with the same authors, they shall be appended with letters in the year, e.g. 2000a, 2000b, 2000c.

In parentheses the citations look like: 

(Pan & Doe 1999) [1]

more than one citation: 

(Pan & Doe 1999; Pan et al. 2001) [1]  [3]

After each citation, insert a "Link to Citation" template. Edit the template to the appropriate index number of the citation (remove the hashtag), as seen above. This will create an index that links to that number in the bibliography. After that, insert a "Citation" template. This template contains a Citation Number and Citation Text entry.  Match the Citation Number with the index number you listed in the "Link to Citation" template. In the Citation Text area, write the author(s) and year and create a hyperlink to ADS, arxiv, or elsewhere to the actual paper, if possible. (Look at this page in Edit mode if you need an explicit example). Using citation templates will automatically create a Bibiogrpy at the end the page, sorted by the citation id/number.