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. Adding a global alias to the package meta.cpkg5
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 information at the top of the package file (above Package $apcocoa/<<package name>>):

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

Adding a global alias

Global aliases are managed on top of the meta package meta.cpkg5. Just add the line

Alias <<alias>> := $apcocoa/<<package name>>

to the other global aliases. This part is usually done by the ApCoCoA Team.

Send us your package

This point should be clear. Send the package to one of our team members with a short description why and which package you have written and if everything is fine about it.

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 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 <em><<parameter name>></em> <<parameter description>></item>
      <item>@param <em><<parameter name>></em> <<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 -->
    <example>
<<first example>>
    </example>
    <example>
<<second example>>
    </example>

  </description>

  <!-- Add related pages -->
  <seealso>
    <see><<first page>></see>
    <see><<second page>></see>
  </seealso>

  <!-- (I have no idea what this is supposed to do) -->
  <types>
    <type><<first type>></type>
    <type><<second type>></type>
  </types>

  <!-- Add keys here -->
  <key><<first key>></key>
  <key><<second key>></key>

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

</command>

Empty template:

{{Version|2}}
 
<command>

  <title> </title>
  <short_description> </short_description>
  
  <syntax>
     
  </syntax>
  <description>
    <itemize>
      <item>@param <em> </em>  </item>
      <item>@param <em> </em>  </item>
      <item>@return  </item>
    </itemize>
 
    <example>

    </example>

  </description>

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

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

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

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

</command>

Example

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

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