Introduction

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.

File Format

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.

Every file MUST contain the following information (preferably at the beginning as APL comments): There is a file +TEMPLATE-Bits_and_Pieces.apl 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.

Author

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.

Date

The date when the file was submitted to the GNU APL Bits_and_Pieces directory (see Process below).

Copyright

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.

License

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.

Support email

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.

Portability Level

A file containing APL code MUST indicate its portability level, which is one of: See Library Guidelines for details.

Purpose

This should be a brief description of WHAT the code does.

Description

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.

Process

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.
  1. Prepare the file according to the format described above
  2. Send an email to bug-apl@gnu,org with the file attached and declaring that (1) you are the author of the file and (2) you would like it to be published in the GNU APL Bits_and_Pieces directory. In that email, please solicit feedback from the GNU APL Community on your contribution.
  3. We will then look at the file (checking that the format of the file is as described above, that it does not conflict with the GNU philosophy, and that it is suitable for the GNU APL Bits_and_Pieces directory). We will then either accept the file, request modifications, or reject it.
  4. If the file is accepted then send a release announcement to bug-apl@gnu,org (and possibly other places as appropriate).

Removal

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.