Documentation Principles

Documenting a Package in the Wiki pages

This page describes some common principles to keep in mind when you document your package in the Wiki. The principles are meant to give the documentation a uniform look and feel.

When documenting your package in the Wiki mind the following:

• use for the name of your .cpkg file only lower case letters (if necessary separated by "_"),
• if possible, use for the name of the package (wich is 'not' the global alias) the same name as your .cpkg package has,
• your description should contain which global alias you have chosen for your package,
• how to create an global alias:
  • the alias has to follow the CoCoA4 coding conventions, i.e., has to start with a capital letter,
  • it should be as short as possible and concise.

 For example, assume that in file matrices.cpkg you provide a package matrices that specifies a function Det 
 that, given either a matrix or a list of lists of ring elements, computes the determinant of a matrix. 
 A reasonable global alias for your package then would be Mat.

Structure of your Wiki-page

Write your documentation within the command-XML-tag. The content of your documentation should be structured as follows:

 <command>
 <title>...</title>
 <short_description>...</short_description>

 <syntax>...</syntax>

 <description>
   ...
   <example>
     ...
   </example>
   ...
   <example>
   ...
   </example>
 </description>

 <types>
   <type>...</type>
   <type>...</type>
   ...
 </types>

 <seealso>
 <see>...</see>
 <see>...</see>
 ...
 </seealso>

 <key>...</key>
 <key>...</key>
 <wiki-category>...</wiki-category>
 </command>
 

Title

The title of your command is the concatenation of the global alias, which you have defined for your CoCoA-package, a dot and the name of your function, e.g.

 <title>Mat.Det</title>
 

for a function called Det within a package matrix with global alias Mat.

Important: The title of the Wiki-page and the title of the function have to be the same!

Short Description

Describe shortly the basic functionality of your function. Thereby treat your short description as a real sentence, i.e. your short description has to begin with a capital letter and has to end with a full stop.

 <short_description>Computes the determinant of a matrix.</short_description>
 

Syntax

The syntax of your function has to be complete, i.e., including the types of your parameters and the type of your return value if this is possible! If it is possible to call your function with different types, then itemize the complete syntax for every possibility, e.g.

 <syntax>
 Mat.Det(M:MAT)
 Mat.Det(M:LIST)
 </syntax>
 

In this example it is possible to call the function Det either with the matrix M or with a list (of lists) which defines the matrix M. Here it is not possible to determine the type of the return value, because it depends on the types of the entries of matrix M. Suppose that M only has rational entries. Then the syntax should look like this:

 <syntax>
 Mat.Det(M:MAT):RAT
 Mat.Det(M:LIST):RAT
 </syntax>
 

Description

Describe and explain here in detail what your function does. First of all itemize all your parameters and the return value and describe as short as possible which role they play within your function, e.g.

• @param <em>M</em> Matrix M for which the determinant is computed.
• @return The determinant of matrix M.

Please use in your description the strings "@param" and "@return" to mark the parameters and return values.

Example

Please note, the examples have to be written within the description-tag! Write as many examples as necessary to understand the complete functionality of your function.

• If you write more than one example use a new example-tag for every example!
• The examples should be complete, i.e. they have to begin with Use ... and end with the result. So it is possible for the user to copy the whole example (only having to ommit the the expected ApCoCoA response), paste it into (Ap)CoCoA and execute it.
• Please give intelligent examples, i.e. examples which do not only cover the trivial cases.
• It could also be helpful for the user if you comment your example, especially difficult ones. If you do so, comment every line that is not executable with a --, see second item above.

  <example>
  -- Here goes your first example for the determinant.
  -- TBD!!
  Use ...
  Det.Mat([[1,0][0,1]]);
  ---------------------  
  </example>
  <example>
  -- Here is, within seperate example tags, your second example
  -- demonstrating how matrices are supplied
  Use ...
  M := ...
  Det.Mat(M);
  </example>
 

Types

Declare here all data types that the formal parameters in the signature of your functions have. For example the function Det is a function for types MAT and LIST, so Det has to be added to the group of all functions for type MAT and to the group of all functions for type LIST. Therefore declare all these types within the types-tag, e.g.

 
 <types>
  <type>matrix</type>
  <type>list</type>
 </types>
 

Possible types are: boolean, branching, cast, cocoaserver/apcocoaserver, error, function, groebner, groebner-basic, groebner-interactive, groebner-start, help/online-help, hilbert, ideal, int/integer, io, list, loops, matrix, memory, miscellanous, module, packages, panels, points, poly/polynomial, printing, programming, quotient, rat, ratfun, record, ring, string, system, tags, toric, type, vector, zmod.

Note that the concept of type is not meant in the sense of datatype. It's purpose is to group funcions under different points of view.

See Also

You can set references to other functions which are related to this function. You only have to declare the title of these function within the see-tag, e.g.

 <seealso>
  <see>LinBox.Det</see>
 </seealso>
 

Please be careful with your references! Use only reasonable references, but set as many as possible!

Keywords

The set of keywords is the set of expressions in which a search term is searched by the ? ... or Man-command in (Ap)CoCoA! Therefore be careful with your keywords!

• The following words have to be keywords:
  • the title of the function,
  • the concatenation of the alias of the package and the title of the function,
  • the concatenation of the package name and the title of the function.
• Do not use any names of persons, e.g. your own!
• You are allowed to declare other reasonable keywords.

Example:

 <key>Det</key>
 <key>Mat.Det</key>
 <key>matrix.Det</key>
 

Wiki Category

The wiki-category is always constructed in the same way, i.e. the concatenation of Package_ and the name of the package which contains your function, e.g.

 <wiki-category>Package_matrix</wiki-category>
 

Formatting your text

There are a few XML-tags for formatting the text. Please, do not use any Wiki formatting styles!

• itemization:

 <itemize>
  <item> your text</item>
 </itemize>
 

• bold text:

 <em>your text</em>
 

• true type text:

 <tt>your text</tt>
 

• paragraphs:

 <par/>
 new paragraph
 

Please note: Wiki-Paragraphs will not be taken over to html! Therefore always use the par-tag to structure your text!

Further remarks

• Use as little Tex-code as possible.
• Do not use any pictures!
• Very important: Do not use any quotation marks!!! Please note: All quotation marks in (CoCoA) examples have to be replaced, too! Use for quotations within text or examples the quotes-Tag, e.g.

<quotes>Hello world!</quotes> instead of "Hello world!".