Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Code development makedefs conventions Up: Code development Previous: Overview of code development

Subsections

Coding conventions

This section discusses some aspects of the AIPS++ system which have a direct effect on the way source code is written.

Include files

It is essential in AIPS++ that the

   #include <Header.h>

form of preprocessor #include statement be used. This form looks for Header.h in the search path defined by -I compiler options and allows the AIPS++ makefiles to control the include process. The other form admitted by the C preprocessor, namely

   #include "Header.h"

should never be used in AIPS++ source code. It causes the preprocessor to look for the include file in the same directory as the source file, regardless of the search path defined by -I compiler options. This may cause problems where, for example, a programmer has checked out and is modifying a C++ class implementation file but doesn't have the relevant header files checked out alongside.

Include files are specified as in the following example:

   #include <aips/Tables/Table.h>

This refers to the specific header file $(AIPSCODE)/aips/implement/Tables/Table.h by virtue of the symlink

   $(AIPSCODE)/include/aips -> $(AIPSCODE)/aips/implement

and the fact that $(AIPSCODE)/include is added to the include path via a -I compiler option (see §1.1.1). Symlinks for each package are created by the symlinks rule in the top-level makefile (§10.9), and they are created in programmer workspaces by mktree (p).

Another caveat on include files is that they must have a .h file suffix. This is mandated by the need for vpath directives in the makefiles, specifically for the dependency analysis used in programmer compilations.

perl scripts

perl scripts must begin with a line of the form

   #!/usr/local/bin/perl4

   #!/usr/local/bin/perl5

When the scripts are installed the makefile will replace these strings with the full pathname to the perl4 or perl5 executable encoded in the PERL4 and PERL5 makedefs variables. perl options may be added after these strings in the usual way.

Documentation include files

Files included by TEX, L^ATEX and Texinfo source files may be deposited in a subdirectory with the same basename as the source file but with a .dir suffix. For example, the source for this manual consists of System.latex which simply defines the document style and a few commands and environments and then includes a separate .tex file for each chapter. System.latex resides in $AIPSCODE/doc/reference and the chapters reside in $AIPSCODE/doc/reference/System.dir.

The documentation makefile automatically adds any .dir subdirectory to the TEXINPUTS environment variable which defines TEX's search path for included files. Note that, while .dir subdirectories can contain any type of file, TEX, L^ATEX and Texinfo may themselves impose constraints, for example L^ATEX requires a .tex file suffix for included files.

The .dir subdirectories should not contain a makefile, nor should they have subdirectories. Other than that there is really no restriction on what they may contain.

URLs in HTML documents

Because AIPS++ HTML documents are propagated to many sites and installed with minimal changes it is important that the URLs (Uniform Resource Locators) in these documents be relative to $AIPSDOCS whenever possible. Someone navigating the AIPS++ documentation at one site should not be directed to another AIPS++ installation without needing to be. Once such a traversal is made the error is compounded since the links stay remote unless the link stack is unwound.

A document in a subdirectory of $AIPSCODE/doc is installed within the corresponding subdirectory of $AIPSDOCS. For example, $AIPSCODE/doc/html/homepage.html is installed in $AIPSDOCS/html/homepage.html. Thus a link from homepage.html to, say, $$AIPSDOCS/projects/mission.html should be given as

   <A HREF="../project/mission.html">Mission Statement</A>

The following prescription should be observed:

Use a relative URL if the linked-to file exists (or ought to exist) in all AIPS++ installations.
Use an absolute URL if the linked-to file does not exist in all AIPS++ installations. Typically these would be links to web services provided by the master as described in §13.1.

HTML meta-markups

The HTML comment

<!$Date$>

may be used to automatically record timestamp information in the installed HTML file. The following fragment shows an example of its use, typically near the end of the file:

   <P>Copyright &#169; 1996-98,2000,2001,2004 Associated Universities Inc., Washington, D.C.</P>
   <ADDRESS>aips2adm@nrao.edu</ADDRESS>

<!$Date$>

   </BODY>
   </HTML>

RCS substitutes the current time (GMT) for the $Date$ string when the file is checked in (see ai (p)) thereby transforming the meta-markup to something resembling

<!$Date: 1995/08/04 05:22:48 $>

The documentation makefile parses this into HTML and also adds the time when the .html file was installed in the relevant subdirectory of $AIPSDOCS (see §1.2). Within an HTML browser the result is as follows:

   Copyright (c) 1995-98,2000,2001,2004 Associated Universities Inc., Washington, D.C.

   aips2adm@nrao.edu

   ---------------------------------------------------------------------------

   Modified:  1995/08/04 05:22:48 GMT
   Installed: 1995/08/06 19:32:08 GMT

It is permissable to insert additional text within the meta-markup as follows:

<!$Date$ by mcalabre@atnf.csiro.au>

This would appear as:

   Copyright (c) 1995-98,2000,2001,2004 Associated Universities Inc., Washington, D.C.

   aips2adm@nrao.edu

   ---------------------------------------------------------------------------

   Modified:  1995/08/04 05:22:48 GMT by mcalabre@atnf.csiro.au
   Installed: 1995/08/06 19:32:08 GMT

The <!$Date$> meta-markup must appear as the first and only text on a line (with no leading whitespace). It should be the last item before the </BODY> HTML markup.

Next: Code development makedefs conventions Up: Code development Previous: Overview of code development Contents Index