This directory contains small files that contain APL code fragments, APL functions, entire APL workspaces, or files that are otherwise related to GNU APL, and that the author of the file would like to share with other APL users (GNU APL or not).
The files are self-contained in the sense that no other information about them is required or available. Some files are GNU APL workspaces (created with the )DUMP command) while others are meant for direct cut-and-paste from a web browser into GNU APL without the need to download them first.
Please note that the files are NOT maintained by the GNU APL project but by the author named in each file.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119
All files MUST be HTML and UTF8-encoded. The file extension MUST be .html (so that the web server can produce the proper content type without additional configuration).
Every file MUST contain the following information (preferably at the beginning as APL comments):
There is a file +TEMPLATE-Bits_and_Pieces.html in this directory that can serve as a template for contributions of APL code. The details of the mandatory information in a file is described in the following sub-chapters.
It MAY be a good idea to add meta tags into the <HEAD;> section of the HTML header. The author SHOULD use an HTML validator before submitting a file.
The author is the name of the person that has written the code. It MUST NOT be the name of a legal entity (company, corporation etc.). The author MAY provide additional information like postal address, but should keep in mind that this information will be visible on the internet.
The author is responsible for the content of the file. The author (and NOT the GNU APL project) is also responsible for maintaining the file.
The date when the file was submitted to the GNU APL Bits_and_Pieces directory (see Process below).
The file MUST contain a copyright line like:
Copyright (C) 2015 by Author
with, of course, 2015 and Author replaced by the actual date and name. We currently assume that the author is also the copyright owner. If the author differs from the copyright owner then we need to check with the GNU project how to handle the contribution.
The file MUST declare under which license it is being published. The license MUST be either GPL or LGPL at the discretion of the author.
The file MUST contain an email address to which support requests (questions and bug reports) should be sent. Since this email address appears on the internet, the author MAY obscure it in a way that is easy to understand by human readers but difficult to handle by programs that scan the internet automatically.
A file containing APL code MUST indicate its portability level, which is one of:
See Library Guidelines for details.
This should be a brief description of WHAT the code does.
This should be a description of HOW the code is supposed to be used.
In general, more is better. However a too long description at the beginning of the file can reduce the readability of the file considerably. For that reason it is recommended to put a brief description at the beginning of the file and a longer, more detailed description at the end. This can be achieved by ending the APL code with command )OFF or with command ]NEXTFILE. After )OFF or ]NEXTFILE you can then add the long description (without worrying about performance because the interpreter stops processing of the file at the )OFF or ]NEXTFILE command.
If you would like to share a file by publishing it in the the GNU APL GNU APL Bits_and_Pieces directory, then please do the following.
There could be reasons to remove a file, for example if the support email address becomes invalid, support requests are not answered, or the code in the file is obsoleted by other contributions.
We will, if possible, inform the author of a file before removing it.
The author of a file can also, at any time, request the removal of the file.