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

[Juergen Sauermann]

Hi Jean,

yes, we can put your workspace into Bits_and_pieces.

The recommendations in  Library-Guidelines.html have not
found much attention, so they are basically obsolete. What is important
is that the library (i.,e. APL code and documentation) code is easy to use,
and follows similar naming conventions.

Regarding GPL vs. LGPL it is entirely your decision what you consider appropriate.
The requirement of Bits_and_pieces for licensing is is only that one of the two is used.
You can add other licenses, but the wisdom of the GNU project has it, that dual or multi-licensing
is a bad thing because multiple licenses can undermine each other and complicate things
more than necessary.

When converting to GNU APL please proceed as follows:

1. make sure that the workspace works properly in GNU APL,
2. use command )DUMP-HTML to convert to the format used in Bits_and_pieces,
3. Fill in Copyright etc. in the .html file produced by  )DUMP-HTML

I haven't looked too deeply into your code, but IMHO an empty line between two function
definitions would improve its readability.

--------------------------------------

Re. 1.4.1, as I said the guidelines are obsolete. Don't worry about metadata.
Re. 2.1 I believe it is just common practice in APL to prefer shorter names over long ones.
Re. 3.1 This term is defined in the companion document Library-Guidelines-GNU-APL.html

Re. 4, it is generally bad if a library is spread over multiple files, because that makes cut-and-past
cumbersome. In GNU APL you can use command ]NEXTFILE at the end of your APL code and
append license, API and other documentation after that. That has the advantage that this information
is not lost when the APL code is copied, and you remain independent of programs like zip.

/// Jürgen

On 10/27/2015 09:58 PM, Jean Forget wrote:

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