HowTo:Document an ApCoCoA-2 Package

This page describes how to document an ApCoCoA-2 package in the Wiki. For an overview on how to contribute a package and an example, see HowTo:Contribute an ApCoCoA-2 Package. In order to do this, you need to have a wiki account. Such an account can only be created by a wiki admin, so please contact the ApCoCoA team so we can create an account for you.

Note: In the following description, words marked as <<word>> are placeholders, i.e. you should replace this text after copying.

Main Structure

Currently, the ApCoCoA help is exported from time to time from this wiki. For this to work properly, please carefully proceed with the following steps:

1. Create the page Category:Package <<package name>>.
2. Create the page Package <<package name>> and add the code [[Category:Package <<package name>>]].
3. For every function in the package you want to describe, create a page Package <<package name>>/<<alias>>.<<function name>>, e.g. Package sagbi/SB.IsInSubalgebra
4. (optional) If there was already a similar package in ApCoCoA-1, then you can add links to the old package from the new one and vice versa. For details, see Template:Version.

Creating Package Main Page

The main page of the package is the page Package <<package name>>. For an example, see Package sagbi.

For a description of the MediaWiki syntax, see Help:Wikitext from Wikipedia. While some things may be formated differently in the ApCoCoA Wiki, the syntax here is the same as in Wikipedia. Additionally, you can use LaTeX to write mathematical equations. For instance, the code <math>x_1^2</math> generates $x_{1}^{2}$, the code

:<math>\sum_{i=1}^\infty \left(\frac{1}{2}\right)^n.</math>

generates

$\sum _{i=1}^{\infty }\left({\frac {1}{2}}\right)^{n}$.

For a detailed description of the math extention, see Help:Displaying a formula from Wikipedia.

Note: Each math environment is rendered as an image, which may take the server a view seconds to compile. Therefore it is recommended to backup data (e.g. copying it into the clipboard) before saving the page or viewing the preview.

Creating Function Descriptions

For this step to work correctly, it is necessary to use the following XML template (see also Documentation Principles for ApCoCoA-1) since the ApCoCoA-2 help is exported from the Wiki. Please do not use any Wiki syntax or LaTeX code on the function page as they will not be rendered when exported. If you need to describe anything mathematically, then please use the Package main page instead, otherwise please use the Format options below.

Wikipage template

{{Version|2}}
<command>
  <title><<alias>>.<<function name>></title>
  <short_description>Function description in one sentence</short_description>
  
  <syntax><<alias>>.<<function name>>(<<input parameters and types>>):<<output type>></syntax>
  <description>
    <!-- Here comes a short description of the functions -->
    <itemize>
      <!-- Describe every input parameter of the function -->
      <item>@param <tt><<parameter name>></tt> <<parameter description>></item>
      <item>@param <tt><<parameter name>></tt> <<parameter description>></item>
      <item>@return <<description of the return value>></item>
    </itemize>
 
    <!-- Examples here (also only one or more than two possible) -->
    <!-- It is important to omit any indentation inside the example environment -->
    <!-- may also go over more lines, but the </example>-tag should not be in a new line -->
    <example><<first example>></example>
    <example><<second example>></example>
  </description>

  <!-- Add related pages (also more or none possible) -->
  <seealso>
    <see><<first page>></see>
    <see><<second page>></see>
  </seealso>

  <!-- Add all data types used in the signature of your function (also more or none possible) -->
  <types>
    <type><<first type>></type>
    <type><<second type>></type>
  </types>

  <!-- Add keys here (first three are mandatory, other ones are optional) -->
  <key><<function name>></key>
  <key><<alias>>.<<function name>></key>
  <key><<package name>>.<<function name>></key>
  <key><<first key>></key>
  <key><<second key>></key>

  <wiki-category>Package <<package name>></wiki-category>

</command>

After creating the page, you can remove the comments, i.e. the lines starting with <!-- and ending with -->. Alternatively, you can use the following template comments removed:

Empty Wikipage template

{{Version|2}}
<command>
  <title></title>
  <short_description></short_description>

  <syntax></syntax>
  <description>
    <itemize>
      <item>@param <tt></tt>  </item>
      <item>@param <tt></tt>  </item>
      <item>@return  </item>
    </itemize>

    <example></example>
  </description>

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

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

  <key></key>
  <key></key>
  <key></key>

  <wiki-category>Package </wiki-category>
</command>

Instead of Wiki syntax, you can use the following tags to format the function pages:

• For itemizations, use

<itemize>
  <item>first item</item>
  <item>second item</item>
  ...
</itemize>

• For italics, use

<em>...</em>

• For code in the body text like variables, write

<tt>...</tt>

• For new paragraps (Wiki paragraphs are not exported to the ApCoCoA manual), write:

<par/>