HowTo:Contribute an ApCoCoA-2 Package

There are three main steps for contributing an ApCoCoA Package:

1. Implementing the package functions.
2. Adding a manual, a version info and the copyright licence to the package file
3. Send us your package
4. Describing the package in the ApCoCoA Wiki.

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

Implementation

At the very first, you have to create a file <<package name>>.cpkg5. This is the package file and will later be located in the folder

/plugins/apcocoa/lib/cocoa/packages/apcocoa/

in the apcocoa directory. If the package is self-contained, you can first put it anywhere and load it into ApCoCoA or CoCoA-5 for testing the functions. Otherwise, we recommend putting it in the ApCoCoA package directory on your system and test it using ApCoCoA. The package can be reloaded for testing using the command

Source MEMORY_ApCoCoA_Packages_Path + "<<package name>>.cpkg5";

The following is a minimal example for the package:

Package $apcocoa/<<package name>>
export skip;

EndPackage;

The line export skip; is needed in order to tell CoCoA that this package does not export any functions. If you want to export functions, you can delete this line.

Afterwards you can now add the functions you want to have in the package. For instance, if you write

Package $apcocoa/<<package name>>
export skip;

Define Foo()
  PrintLn "Foo";
EndDefine; -- Foo

EndPackage;

you can call this function from CoCoA with $apcocoa/<<package name>>.foo();.

Adding package info

At first, add the following copyright information at the top of the package file (above Package $apcocoa/<<package name>>):

Copyright information

--
-- This file is part of the ApCoCoA package pool.
--
--   Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
--
--   Authors: <<year>> <<author name>>
--
-- Visit http://apcocoa.org/ for more information regarding ApCoCoA.
-- Visit http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues for bugs, problems 
-- and known issues.
--
-- The ApCoCoA package pool is free software; you can redistribute it and/or
-- modify it under the terms of the GNU General Public License (version 3 or
-- later) as published by the Free Software Foundation. A copy of the full
-- licence may be found in the file COPYING in this directory.
--
-- The ApCoCoA package pool is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with the ApCoCoA package pool; if not, write to the Free Software
-- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Then create two functions:

Define About()
  PrintLn "    	Topic   : <<Topic name (single word)>>";
  PrintLn "    	Keywords: <<keywords>>";
  PrintLn "    	Authors : <<author name>>";
  PrintLn "    	Version : <<current CoCoA version>>";
  PrintLn "    	Date    : <<release date>>";
EndDefine; -- About

Define Man()
  PrintLn "Recommended Alias:";
  PrintLn "   Alias <<alias>> := $apcocoa/<<package name>>;";
  PrintLn;
  ...
EndDefine; -- Man

The function Man() should contain a short description for every function contained in the package. For a clearer description of About() see the example below.

Send us your package

This point should be clear. Send the package to one of our team members with a short description what this package is for, why it is important and which global alias you would like to get for it. Then we can give you feedback whether everything is correct and add the global alias to the meta package meta.cpkg5.

Wiki Description

Please note that for step you need 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.

Currently, the ApCoCoA help is exported from time to time from this wiki. For this to work properly, 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>>]]. Here you can describe the package using all wiki tools including latex.
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 replace {{Version|1}} by {{Version|1|<<link to new function page>>}} on the old page and {{Version|2}} by {{Version|2|<<link to old function page>>}} on the new page. For more information, see Template:Version.

For the third step to work correctly, it is necessary to use the following XML template (see also Documentation Principles for ApCoCoA-1):

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>

Format options

Please do not use any Wiki styles on the function pages as they can not be exported to the ApCoCoA manual. Instead, use the following tags to format your text.

• For itemizations, use

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

• For bold text, use

<em>...</em>

• For code in the body text like variables, write

<tt>...</tt>

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

<par/>

• For quotes, use

<quotes>...</quotes>

Important notes

• Do not use any quotation marks on the function pages, not even in the CoCoA examples. Instead, replace them by

<quotes>...</quotes>

• Do not use TeX or pictures on the function pages as they can not be exported to the Wiki manual. If you want to describe your package using TeX or pictures, please use the package page Package <<package name>> you created before.

Example

The file sagbi.cpkg5 in the directory apcocoa/ in the package directory starts with the following lines:

Source code of sagbi.cpkg5 (the relevant part)

--
-- This file is part of the ApCoCoA package pool.
--
--   Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
--
--   Authors: 2020 Bernhard Andraschko
--
-- Visit http://apcocoa.org/ for more information regarding ApCoCoA.
-- Visit http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues for bugs, problems 
-- and known issues.
--
-- The ApCoCoA package pool is free software; you can redistribute it and/or
-- modify it under the terms of the GNU General Public License (version 3 or
-- later) as published by the Free Software Foundation. A copy of the full
-- licence may be found in the file COPYING in this directory.
--
-- The ApCoCoA package pool is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with the ApCoCoA package pool; if not, write to the Free Software
-- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Package $apcocoa/sagbi

export skip;
  
Define About()
  PrintLn "    	Topic   : Subalgebras";
  PrintLn "    	Keywords: Subalgebra, SAGBI bases";
  PrintLn "    	Authors : B. Andraschko";
  PrintLn "    	Version : CoCoA 5.3.2";
  PrintLn "    	Date    : 7 September 2020";
EndDefine; -- About

Define Man()
  PrintLn "Recommended Alias:";
  PrintLn "   Alias SB := $apcocoa/sagbi;";
  PrintLn;
  PrintLn;
  PrintLn "Description:";
  PrintLn "   Contains basic functions for subalgebras of polynomial rings, e.g.";
  PrintLn "   Hilbert series, SAGBI bases of testing for subalgebra membership.";
  PrintLn "   In our context, a subalgebra is a tagged record containing all";
  PrintLn "   informations about the subalgebra as e.g. a unique ID, the base ring,";
  PrintLn "   generators, etc.";
  PrintLn "   To get these informations, one can use the getter methods described";
  PrintLn "   below. For Details about the record fields see the description of the";
  PrintLn "   function Subalgebra(...).";
  PrintLn;
  PrintLn;
  PrintLn "Function Description:";
  PrintLn "   Note: we write short \"SUBALGEBRA\" for \"TAGGED(\"$sagbi.Subalgebra\")\"";
  PrintLn "   For a short function list type in";
  PrintLn "     SB.FnList();";
  PrintLn;
  PrintLn " Main functions:";
  PrintLn;
  PrintLn "   Subalgebra(R: RING, fs: LIST) : SUBALGEBRA";
  PrintLn "     Input: a polynomial ring R and a list fs of polynomials in R";
  PrintLn "     Output: a tagged record S containing the following fields:";
  PrintLn "       ID: A unique ID";
  PrintLn "       CoeffRing: the coefficient ring K of R";
  PrintLn "       Ring: the super ring of S, i.e. R";
  PrintLn "       gens: a list of generators of the subalgebra, i.e. S = K[fs]";
  PrintLn "       SAGBI: a storage field for a (truncated) SAGBI basis of S";
  PrintLn "              - initially []";
  PrintLn "       trunc: the truncation degree of the currently computed truncated";
  PrintLn "              SAGBI basis - initially 0. If SAGBI is a complete SAGBI basis,";
  PrintLn "              then trunc is set to -1.";
  PrintLn "       HS: Hilbert Series of S - initially 0.";
  PrintLn "     Note: Assumes R is standard-graded ring";
  PrintLn;
  PrintLn "   SAGBI(G: LIST): LIST";
  PrintLn "     Input: a list of polynomials G";
  PrintLn "     Output: a SAGBI basis of K[G]";
  ...
EndDefine; -- Man

SubalgebraID := 0;

Define Subalgebra(R,fs)
  ...
EndDefine;

...

EndPackage;

In this Wiki, we have the pages Package sagbi, Category:Package sagbi and function pages like Package sagbi/SB.SAGBI:

Source code of the wiki page Package sagbi/SB.SAGBI

{{Version|2|[[ApCoCoA-1:SB.Sagbi]] and [[ApCoCoA-1:SB.ReducedSagbi]]}}

<command>
  <title>SB.SAGBI</title>
  <short_description>Computes a finite SAGBI-basis of a subalgebra if existing.</short_description>
  
<syntax>
SB.SAGBI(G:LIST of POLY):LIST of POLY
</syntax>
  <description>
This function computes a finite SAGBI-basis of a subalgebra <tt>S</tt> generated by the polynomials of the list <tt>G</tt>, if a finite SAGBI-basis of <tt>S</tt> is existing. Then a list of polynomials is returned which form a SAGBI-basis of <tt>S</tt>. Otherwise the computation runs until it is interrupted.
<itemize>
  <item>@param <em>G</em> A list of polynomials which generates a subalgebra.</item>
  <item>@return A list of polynomials which form a finite SAGBI-basis of the subalgebra generated by <tt>G</tt>.</item>
</itemize>

<example>
Use QQ[x,y,z], DegRevLex;
S := SB.SAGBI([x^2 -z^2,  x*y +z^2,  y^2 -2*z^2]);
indent(S);
-- [
--   y^2 -2*z^2,
--   x*y +z^2,
--   x^2 -z^2,
--   x^2*z^2 +x*y*z^2 +(1/2)*y^2*z^2 +(-1/2)*z^4
-- ]
</example>
  </description>
  <seealso>
    <see>Package sagbi/SB.TruncSAGBI</see>
    <see>Package sagbi/SB.SAGBITimeout</see>
    <see>Package sagbi/SB.IsSAGBIOf</see>
    <see>Package sagbi/SB.GetSAGBI</see>
    <see>Package sagbi/SB.GetTruncSAGBI</see>
  </seealso>
  <types>
    <type>sagbi</type>
    <type>poly</type>
  </types>
  <key>SAGBI</key>
  <key>SB.SAGBI</key>
  <key>apcocoa/sagbi.SAGBI</key>
  <wiki-category>Package sagbi</wiki-category>
</command>