View source for Documentation Principles

=Documenting a Package in the Wiki pages=
This pages describes some common principles to keep in mind when you document your package in the Wiki pages and
is meant to give the documentation a uniform look and feel.


By documenting your package mind the following:

* use for the name of your <code>.cpkg</code> 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 <code>.cpkg</code> 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 CoCoA 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:
 <nowiki>
 <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>
 </nowiki>

==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. 
 <nowiki>
 <title>Mat.Det</title>
 </nowiki>
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 has 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'''.

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

==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.

 <nowiki>
 <syntax>
 Mat.Det(M:MAT)
 Mat.Det(M:LIST)
 </syntax>
 </nowiki>
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:

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

==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.

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

Please use by 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 <code>Use ...</code> 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 a support for the user if you comment your example especially by difficult examples. If you do so, comment every line that is not executable with a ''--'', see second item above.

 <nowiki>
  <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>
 </nowiki>

==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.

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

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.

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

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 <code>? ...</code> or <code>Man</code>-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:

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

==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.

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

=Formatting your text=
There are a few XML-tags for formatting the text. Please, do not use any Wiki formatting styles!
* itemization:
 <nowiki>
 <itemize>
  <item> your text</item>
 </itemize>
 </nowiki>
* bold text:
 <nowiki>
  <em>your text</em>
 </nowiki>
* true type text:
 <nowiki>
  <tt>your text</tt>
 </nowiki>
* paragraphs:
 <nowiki>
 <par/>
 new paragraph
 </nowiki>
'''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 <code>quotes</code>-Tag, e.g.
<code><quotes>Hello world!</quotes></code> instead of "Hello world!"

[[Category:ApCoCoA|{{PAGENAME}}]]