[Bug-apl] Registering a module in the "Community.html" page: French Revolutionary Calendar

[Jean Forget]

I have written a set of functions to convert Gregorian dates to the
French revolutionary calendar and vice-versa. 
It is available on GitHub. See the source code at
https://github.com/jforget/apl-calendar-french/blob/master/workspaces/calendar-french.apl
and the English explanations at
https://github.com/jforget/apl-calendar-french/blob/master/calendar-french.en.html

A few weeks ago, I noticed the 
https://www.gnu.org/software/apl/Community.html
webpage on your site listing a few serious and useful APL
projects. Are you interested in inserting my French calendar library
in this page, even if it is less useful than the projects currently
listed?

I have read the webpage giving the coding best practices.
https://www.gnu.org/software/apl/Library-Guidelines.html For the
moment, my library obeys my self-imposed guidelines. If you agree to
list in your Community.html webpage my funny library making funny
conversions of dates into funny formats, I will modify my program to
follow *your* guidelines, but else I will not bother to change it.
So could you give me your advices on these guidelines?

Anyhow, even if you do not want to list my silly library making silly
conversions of dates into silly formats, you may be interested in
reading the remainder of this message, which might give you some ideas
to tweak and improve your guidelines.

Most of the Library-Guidelines.html page applies to L2 and L3 libraries,
therefore it does not apply to my L1 library. In addition, when the
file is loaded into the APL workspace, nothing is executed,
only a few functions are added to the workspace.
But there are a few points which require our attention.

1.4.2 -- There is no metadata function yet. But if you agree to
list my program, I can add a metadata function.
Is it necessary to write a separate meta library?

2.1 -- You advise giving a short name to the library. This is
not the case for now with my library, but I can change it.
Which name should I use?
-- calfr
-- calfrench
-- frcal
-- frenchcal
-- some other name?
Note: in the Perl community, the recommended practice is to
discuss this on a public mailing-list or on a public forum.
This is exactly what I am doing now with the few preceding lines.

2.2 -- After the library short name is selected in 2.1, I will
change all functions by adding a prefix built with this short
name and a delta char.

2.4 -- I will modify my installation paragraph to recommend
storing the library with a reference number 3.

3.1 -- What is a "C1 library component"?
Same question for 5 and 5.1

4 -- You ask to insert comments in the library  describing
its purpose and its API. Alternatively, the purpose and API
can be documented in a separate UTF-8-encoded text file.
In  my case, I provide two UTF-8-encoded  HTML files 
(calendar-french.en.html and, for French speakers,
calendar-french.fr.html)  which are an integral part of 
the distribution. So, the instructions exist but in
an external form a bit different from what you ask. Is it 
OK or should I add comments inside
the APL source file? Or should I extract the documentation
into a UTF-8 encoded file with no HTML functionality?
But see "4 second take" below.

6.2 -- You recommend the LGPL. Since I have a strong Perl background,
I use the GPL+Artistic license, which is compatible with the GPL. 
By the way, why do you advise LGPL instead of GPL? Have you read
https://www.gnu.org/licenses/why-not-lgpl.html ?

Another point: in the text of the GPL, there is an
Appendix: "How to Apply These Terms to Your New Programs".
This paragraph requires inserting a summary of the GPL
in comments at the beginning of each source file.
For this APL library, I obeyed the spirit of the paragraph
but not the letter. The library source file begins
with an executable function "license" which prints the summary
of the GPL, so the user can read it either by reading
the source in a text editor or by running the
function "license" (or "calfr∆license").

4 second take -- I could do the same as for the license, writing a
"calfr∆usage" function which prints the basic usage of the library.
Of course, it will not print them automatically when loading the
library. It will print them only when requested by the user.
Since their main purpose is to be read by potential users
reading the source, "calfr∆license" and "calfr∆usage" should
be no-bells-no-whistles functions.

There still is a question. What is the pecking order between
the "calfr∆license" function and the "calfr∆usage" function?
Or between the license comments and the usage comments?

Thank you for your attention and for your interest.

Jean Forget