Документ взят из кэша поисковой машины. Адрес оригинального документа : http://xmm.vilspa.esa.es/sas/6.0.0/doc/devel/documentation.html
Дата изменения: Fri Mar 30 13:46:26 2001
Дата индексирования: Sat Dec 22 13:32:41 2007
Кодировка:
Поисковые слова: http www.arcetri.astro.it
SAS package documentation standards

SAS package documentation standards

The preferred way to document an SAS package is via LaTeX. If you created the package directory structure with the SAS package maker pkgmaker, a subdirectory called doc will have been created with partially filled out LaTeX templates.

These templates are very similar to the task templates used until now, but we tried to make the distinction between to user documentation and the developer documentation a bit more clear. Also, the new structure is seamlessly integrated in the overall SAS make file mechanism so that it becomes possible to generate HTML or PostScript documentation for the whole SAS.

If your package is called, say, hello, the doc subdirectory will contain three files:

Makefile

If your package contains only one task, then default make file should do without any modifications.

If, on the other hand, the package you are developing is made of separate tasks, hello_pn and hello_mos say, that warrant independent documentation, then you should edit the make file like so:

In this case you should duplicate the LaTeX templates so to have hello_pn.tex, hello_pn_description.tex and so on.

The simplest way to go about this could be to let pkgmaker create the templates for you, then merge the contents of the doc subdirectories and adjust the make files.

LaTeX sources

If you have used the task description templates, you will recognise much of its structure in the new templates. You should be able to fit your task description in the new templates by simply copying text from the old templates.

Note that all sections are automatically labeled. Please do not change the label names. If you have multiple LaTeX templates, and you create them by hand, please make sure that the labels are correct by following the label naming conventions illustrated in hello_description.tex.

If you add tables or figures to your document label them according to the following model (shown for the hello package):

Replace dev with user as necessary.

A description of what items should go in what section of the LaTeX templaes can be found in the documentation of the hello package, where you also find a description of the LaTeX macros to be used in the SAS documentation.

External PostScript files

If you include PostScript figures in your LaTeX documents, make sure that their names end with .eps, so as to avoid a warning during the distribution check.

SAS bibliography file

In order to make the bibliographic references consistent across the various packages, we have introduced a common SAS bibliography file. This file is automatically used when the SAS documentation is built.

The BibTeX file is called sas.bib and is pat of the package sas. At the moment this is just a copy of the file used at the SOC, and it should contain entries for all of the XMM related documents. Let the SAS librarian know if you need to make new entries into this file.

In your LaTeX sources use the standard LaTeX citation commands, using labels from the bibliography file. You don't have to worry about any \bib* commands, as these are automatically generated.

The SAS BibTeX file sas.bib can be found in the subdirectory doc/lib of the package sas.

Updated on: March 29, 2001