← Back to branch summary

~ubuntu-branches/ubuntu/vivid/psicode/vivid

« back to all changes in this revision

Viewing changes to doc/progman/documentation.tex

  • Committer: Bazaar Package Importer
  • Author(s): Michael Banck
  • Date: 2008-06-07 16:49:57 UTC
  • mfrom: (2.1.2 hardy)
  • Revision ID: james.westby@ubuntu.com-20080607164957-8pifvb133yjlkagn
Tags: 3.3.0-3
http://bugs.debian.org/464867
* debian/rules (DEB_MAKE_CHECK_TARGET): Do not abort test suite on
  failures.
* debian/rules (DEB_CONFIGURE_EXTRA_FLAGS): Set ${bindir} to /usr/lib/psi.
* debian/rules (install/psi3): Move psi3 file to /usr/bin.
* debian/patches/07_464867_move_executables.dpatch: New patch, add
  /usr/lib/psi to the $PATH, so that the moved executables are found.
  (closes: #464867)
* debian/patches/00list: Adjusted.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/progman/documentation.tex
2
2
users. The usefulness of the code will depend heavily on the quality
3
3
of its documentation.  One great failing of most of the PSI code is
4
4
that it contains little to no documentation.  We strongly advocate
5
 
documentation of three types:
 
5
documentation of at least the first two types:
6
6
\begin{enumerate}
7
 
\item A short description of the code's function and keywords {\em must} be written
8
 
for each new module and library added to the \PSIthree\ package.
9
 
There is no convention yet what should be the preferred medium for
10
 
such a description, but the following are common:
 
7
\item A short description of the code's function and keywords {\em must} be 
 
8
written for each new module and library added to the \PSIthree\ package.
11
9
\begin{itemize}
12
 
\item A UNIX \file{man} page --- all old and some newer \PSIthree\ codes
13
 
use \file{man} pages as the medium of choice.  To access the 
 
10
\item Direct inclusion in the \PSIthree\ manuals --- binaries
 
11
(modules) should be included in the user's manual and libraries in the
 
12
programmer's manual.
 
13
\item A UNIX \file{man} page --- These provide ``quick-and-dirty'' access
 
14
to the program options even when logged in remotely via a terminal window.
 
15
A \file{man} page should be added for each \PSIthree\ module, and doing so 
 
16
is not difficult when working off another \PSIthree\ \file{man} page as a
 
17
template.  To access the 
14
18
\PSIthree\ \file{man} pages, you will need to add the \file{man} directory
15
19
to your {\tt MANPATH}.  For example, if you run csh or tcsh, and
16
20
assuming \PSIthree\ has been installed in \file{/usr/local/psi3-bin},
21
25
The usual man path should be added after the \PSIthree\ part and
22
26
will be different for different systems.  Different directories are
23
27
separated by colons.
24
 
 
25
 
\item HTML-based documentation --- this is a much more flexible medium
26
 
than \file{man} pages and is accessible by anyone anywhere in the
27
 
world.  Although HTML has its own drawbacks (e.g.\ the separation of the
28
 
form and the function is not always enforced, and it does not allow
29
 
tags to be customized), it is pretty safe to assume that HTML will
30
 
remain the dominant means of distributing information.  Hence we
31
 
encourage \PSIthree\ contributors to write documentation in HTML
32
 
format. Documentation for \PSIcints\ and \library{libpsio.a} can be
33
 
used for examples.
34
 
 
35
 
\item Direct inclusion in the \PSIthree\ manuals --- binaries
36
 
(modules) should be included in the user's manual and libraries in the
37
 
programmer's manual.
 
28
\item It is also helpful, particularly for complex programs or libraries,
 
29
to have even more extensive documentation.  Certain parts of \PSIthree\
 
30
have been documented in more detail via HTML documents (e.g., {\tt
 
31
cints}, {\tt libdpd}, and {\tt libpsio}).  These documents are stored
 
32
in the associated source code directories and installed in the installation 
 
33
directory under {\tt doc/html}.
38
34
\end{itemize}
39
35
 
40
36
\item Second, as mentioned before, the source code should be directly
41
 
documented by comment lines in the code.
 
37
documented by comment lines in the code.  We use a special formatting
 
38
for in-code documentation, which is described in detail in section
 
39
\ref{code-commenting}.
42
40
 
43
 
\item A {\em complete manual} should be written for all finished programs,
44
 
describing all input options, explaining how the program works (theory and 
45
 
technical details), and providing solutions to common problems encountered
46
 
with the program.  Sometimes, the latter documentation is included in the
47
 
man page: for a good example, see the man page for \module{intder95}.  
48
 
Alternatively, a separate document can be created; for another example,
49
 
see the documentation of \module{fcmgen}.
50
41
\end{enumerate}
 
42
 
 
43
Note also that full documentation should also include citations to any
 
44
relevant publications upon which the code may be based.
 
45