Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1556
News FAQ
Search Home

NOTE 249 - The AIPS++ Recipes Repository

George Moellenbrock, NRAO-Socorro

30 January 2002

A postscript version of this note is available.

Contents

Introduction

The Glish Command-Line Interface (CLI) in AIPS++ is a very powerful and flexible environment for data manipulation and analysis. In addition to providing a concise means of access to and operation of the standard astronomy reduction tools in AIPS++ an impressive array of generic tools are available. One of the greatest strengths of AIPS++ is the ability to combine standard astronomy reductions with ad hoc analyses devised by individual users.

Owing to this exceptional flexibility, and a tendency among users to document standard reduction sequences as glish scripts, a tremendous wealth of user-designed Glish scripts exists all over the world. As glish scripts are the language of AIPS++ it is therefore desirable to collect useful recipes in one place where than can be used as written, or as practical examples from which unique data analysis tools can be easily developed by users. This document describes the revitalized AIPS++ Recipes Repository, and how to contribute to it.

More information about how to use Glish itself can be found in AIPS++ Note 195, Getting Started in Glish, and the Glish User's Manual. The AIPS++ User Reference Manual describes how to use all AIPS++ modules and tools in Glish, and is often referred to in individual recipes.

How to Contribute a Recipe

It is now a fairly simple matter to contribute a recipe. Just follow the instructions described in the next few sections for formatting your script file (a template .g file is available here: recipe.g). Give it a short descriptive filename that ends in rec.g, and send it to aips2-recipes@nrao.edu.

Basic Principles

A useful recipe is not simply a random glish script. The purpose of the Recipes Repository is to supplement the conventional AIPS++ documentation with concrete examples that will prove instructive for novice glish script-writers. To make the most of the AIPS++ Recipes Repository, some guiding principles are required:

The Recipe Script Format

Scripts submitted for the Recipes Repository must follow a standard format. A template .g file is available here: recipe.g). The format consists of four main sections, Titles, Script, Output, and Credits. These are described in turn:

Titles

The Titles section provides comment keywords for general information about the script, its goals and its results. It should be possible to recognize a particular recipe as useful to one's own purposes from a quick scan of this section. The keywords in the Titles section are as follows:

#RECIPE: A descriptive title for the recipe (not the filename)

#CATEGORY: The category to which the recipe belongs (General, Synthesis, or Single Dish)

#GOALS: The specific goals of the recipe, in one line

#USING: The AIPS++ modules and/or tools used in the script

#RESULTS: A one-line description of the output of the script

#ASSUME: A one-line description of assumptions made by the script, in particular, which external data files may be required

#SYNOPSIS: A paragraph describing the novelty of the script; this is the only Titles keyword which may extend beyond a single line. Each line should be prepended by ``# ''.

#SCRIPTNAME: The .g filename of the script (used for markup purposes)

Script

The Script section is where the script itself resides, and it begins with the keyword ``#SCRIPT:'' on a line by itself. The script should written following these rules:

Output

The output section begins with ``#OUTPUT:'' (on its own line) and contains sample output from the script. This section is very important since it enables a novice user to determine if the recipe (or their adaptation of it) is running properly. Rules for including recipe output are as follows:

Credits

The Credits section provides for any last words of advice for using the script, and for attribution. The following keywords are supported:

#CONCLUSION: Like the synopsis, this section is useful for describing details of the recipe, in this case, those appropriate after a user has run the recipe. All lines must be prepended with ``# ''.

#SUBMITTER: The full name of the submitter should be supplied here.

#SUBMITAFFL: The affiliation of the submitter should be supplied here.

#SUBMITDATE: The date of submission should be supplied here, formatted as yyyy-mmm-dd, e.g., 2002-Jan-29.

The Recipe Script Format: An example

An example of a properly formatted recipe script can be found here: plotrec.g.

The Recipe LATEX Markup

This section describes the LATEX markup of recipes for the Recipes Repository web-page. Users submitting recipes for the Repository need not concern themselves with this section since AIPS++ project staff will handle this part of the recipe submission if the contributed script is properly formatted as described above.

The recipe script format described above is designed to make markup for the Recipes Repository web-page very simple. LATEX macros for each of the recipe script format keywords are defined in ahrecipe.tex. Via these macros, the Titles and Credits sections of the script format are duplicated in the LATEX markup, with commands for linking to the script itself and to the relevant module or tool documentation the only added information. For simplicity's sake, the Script and Output sections of the script format are included as verbatim blocks. In this way, the script looks like a script (and is readable if the prescribed format is followed), and lines of the script may be copied directly to the Glish CLI with mouse-driven cut-and-paste.

A template .latex file is available here: recipe.latex).

The Recipe LATEX Markup: An example

An example of a proper recipe LATEX markup can be found here: plotrec.latex.

Recipes Repository Implementation

The Recipes Repository consists of two parts. First, the recipes themselves are to be checked in as well-commented glish scripts (see above for details of the required format) in code/contrib/recipes. The build system copies the scripts to libexec so that they may be accessed directly.

The second part of the Repository is the documentation of each recipe. The directory structure for the documentation is as follows:

code/doc/recipes root directory for Recipe docs
   
code/doc/recipes/Recipes.latex LATEX markup for main Recipes web-page
code/doc/recipes/makefile makefile for Recipes.latex
code/doc/recipes/index.html forwarding html for main Recipes web-page
   
code/doc/recipes/General/ directory for General recipes markup
code/doc/recipes/General/General.latex LATEX markup for General category web-page
code/doc/recipes/General/makefile makefile for General recipes
code/doc/recipes/General/index.html forwarding html for General category web-page
   
code/doc/recipes/Synthesis/ directory for Synthesis recipes markup
code/doc/recipes/Synthesis/Synthesis.latex LATEX markup for Synthesis category web-page
code/doc/recipes/Synthesis/makefile makefile for Synthesis recipes
code/doc/recipes/Synthesis/index.html forwarding html for Synthesis category web-page
   
code/doc/recipes/SingleDish/ directory for SingleDish recipes markup
code/doc/recipes/SingleDish/SingleDish.latex LATEX markup for SingleDish category web-page
code/doc/recipes/SingleDish/makefile makefile for SingleDish recipes
code/doc/recipes/SingleDish/index.html forwarding html for SingleDish category web-page
   

The LATEX markup file for each recipe (see above for details of the required format) is to be deposited into the markup directory appropriate to the recipe's category. The LATEX markup file for the category should be updated with the recipe name and title, and the appropriate line added to the category's makefile. The build system will then process the recipe's LATEX markup file and generate .ps.gz and html files in the appropriate locations in the docs tree.


next up previous
Please send questions or comments about AIPS++ to aips2-request@nrao.edu.
Copyright © 1995-2000 Associated Universities Inc., Washington, D.C.

Return to AIPS++ Home Page
2006-10-15