Instructions for Authors

From CASA Guides
Jump to navigationJump to search

Our goal for CASA guides is to maintain up-to-date documentation. The documentation should maintain consistent formatting across the tutorials. Cookbook procedures should be written such that they can be extracted as python scripts for use by users or developers (for testing purposes).

Embedded Code

Use the "source" formatting option for codes, and "pre" to illustrate the output of a program. For example:

<source lang="python">
# for CASA
x = 3
y = 2
vis = "OrionBar-Ka.ms"
clean()
</source>

will render as

# for CASA
x = 3
y = 2
vis = "OrionBar-Ka.ms"
clean()

Be sure also to include the command to be executed by user to make the scripts more easily testable by developers.

Links to CASA Tasks

CASA tasks can be linked from within the wiki. The links will be pointing the the online CASA task reference on casa.nrao.edu. This will ensure that the displayed help is the latest available. To do this, use the double curly brackets for markup:

{{clean}}

will produce clean.


Testing Scripts

Any cookbook scripts should be tested and verified; the wiki should include a stamp (in MediaWiki, a template) indicating in which version of CASA the script was last tested. Use the script extractor code to generate the script from the wiki page, debug the wiki page, and then stamp it.

Here's an example stamp in MediaWiki's markup language.

{{Checked 3.0.0}}

which yields

Last checked on CASA Version 3.0.0 (r9860).

In MediaWiki markup, double braces indicate a template for commonly used phrases and bits of writeup ("under construction," that sort of thing). Please make new templates as they are needed to stamp pages. A list of templates is available.


(Also: let Jack Gallimore know if there are any problems with the script extractor. It needs more testing!)

Categories and Indexing

Be sure to include categories on each new wiki page. You can place category tags anywhere in a MediaWiki page, but it's better to place the tags together and near the top to make it easy to edit and update them. Here's an example of categories used to mark the home page:

[[Category:VLA]] [[Category:CARMA]] [[Category:EVLA]] [[Category:ALMA]] [[Category:Calibration]] [[Category:Imaging]]

Navigational Tools

CASAGuides uses a lean installation of MediaWiki and so doesn't currently support any navigational extensions. To provide users with breadcrumbs where you think they might want to go from the current page, create and use templates like the following:


{{VLA Intro}}

{{Interactive Tools Intro}}

which yield:

VLA Tutorials

Interactive Tools