On 10/25/21 12:41 PM, Andrea Tosoni wrote:
Hello,
I'm Andrea Tosoni.
Some years ago I started to write some perl scripts because I don't like to
re-made the same thing many times, especially when I have to write
documentation (I'm a hardware designer).
In these years, scripts have become perl modules that work almost fine.
I started from POD idea: merge code and documentation. I added the
possibility to load parameters from an external file or by constants
defined in my code (VHDL or Verilog or some other language). I can also
calculate fields and iterate on lists or similar basic programming
operations.The markup is very easy. Documentation can be split in many
source files without order and it's merged at the end.
I also added the possibility to load images (vectorial images for the
moment) and create tables.
Today my output is a Framemaker file (in my company it is the tool for
official documentation) but I think to add the possibility to export in
Latex (because I like) and Word (because I have to support it).
I don't know if these modules can help somebody else.
Today I have to rework to remove deprecated modules, increase test coverage
and add some missing functionalities and this can be the moment to
organize in official modules, if you think that can be useful.
Thank you for reading my mail.
Best regards,
Andrea Tosoni
On 10/26/21 11:53 PM, Shlomi Fish wrote:
> I read your message, but I don't understand what you wish to ask.
What is the
> dilemma?
On 10/27/21 8:02 AM, Shlomi Fish wrote:
> AFAIK, one is allowed to upload any FOSS and non-malware code to
CPAN. That put
> aside, I have collected some resources about sw quality guidelines:
>
https://github.com/shlomif/Freenode-programming-channel-FAQ/blob/master/FAQ_with_ToC__generated.md#what-are-some-best-practices-in-programming-that-i-should-adopt
>
> ; I also wrote about the overwhelming state of doc formats here:
>
https://www.shlomifish.org/philosophy/computers/web/choice-of-docs-formats/
.
>
> HTH.
On 10/27/21 12:06 AM, Andrea Tosoni wrote:
> Hello,
>
> sorry : I'm asking if these modules can be a candidate to be posted
on CPAN.
>
> Best regards,
>
> Andrea
On 10/27/21 8:46 AM, Andrea Tosoni wrote:
> Hello,
>
> thank you.
>
> My code is written in pure perl, mainly with Moose: I like object
oriented
> language because code is cleaner. So, no compilation is necessary and the
> output is predictable.
>
> Documentation is written at the end of each module with POD. One test is
> dedicated to verify if all functions have their description.
>
> I don't write malware :) and I try to have full code coverage with
> automatic tests. I can't be sure that all is working fine, but I
think that
> it's a first step.
>
> I will ask for an account and in the next day I will prepare the modules.
> Working locally, normally I don't need a Makefile.PL to automate
> installation and this is new for me to prepare.
>
> Best regards,
>
> Andrea
Contributing to a FOSS project can be an exciting learning experience. :-)
You will want to create a distribution that the various Perl and CPAN
tools can understand. "Writing Perl Modules for CPAN" by Sam Tregar was
helpful back in the day:
https://link.springer.com/book/10.1007/978-1-4302-1152-5
I have always used ExtUtils::MakeMaker and h2xs(1) to create Perl
distributions:
https://man.archlinux.org/man/core/perl/h2xs.1perl.en
Git seems to be the current, popular choice for version control. I use CVS.
GitHub seems to be the current, popular choice for collaboration and
support. I will need to convert to Git to utilize GitHub.
That's the fun stuff. Then there's the not-so-fun stuff -- legal.
Notably, intellectual property (IP) and data privacy. You do not want
to make a mistake here.
You will need to select a license. For Perl, the Artistic License is
traditional. But, there are examples of CPAN distributions with other
licenses. Note that "Public Domain" can be problematic. h2xs(1)
provides a POD license section in the main module that indirectly refers
to the Artistic License. To be pedantic, include a LICENSE file in the
root of your distribution. See:
https://opensource.org/licenses
https://opensource.org/licenses/Artistic-2.0
Do you have sole and complete ownership of everything you plan to
release? More directly: do you have the legal right to release the
software?
In the USA, where I reside, any document I create -- software, data,
this e-mail message, etc. -- is automatically copyrighted. But if I
wish to defend my copyright, I would be wise to submit a copy and file a
copyright application with the United States Patent and Trademark Office
(USPTO).
You mentioned your software in the context of a company. In the USA, if
I conceive, create, use, improve, etc., content in an employment or
consulting arrangement without a contract stating otherwise, then my
employer or client gains rights to all or part of that content. This is
called the "work for hire" principle.
Have you signed any contracts with your employer related to IP and/or
data privacy, such as a Confidential Disclosure Agreement, a
Non-Disclosure Agreement, an Intellectual Property Assignment Agreement,
etc.? Does your employer have any written policies regarding IP and/or
data privacy?
Have you reviewed the license for FrameMaker?
If others helped you with the software, or if you used their ideas
and/or content, then they could have a stake in the software.
Regarding data privacy, be aware of the Health Insurance Portability and
Accountability Act (HIPPA) (USA), the EU Charter of Fundamental Rights,
and whatever laws apply in your country.
What is your strategy for liability of content within the release --
e.g. unauthorized use of copyrighted content, unauthorized use of
patented processes, improper reverse engineering, etc.? Even if
everything is okay today, new patents, etc., may create violations in
the future. Have you heard of "patent trolls"?
You should discuss this with your employer. You or they may wish to
consult an attorney or legal service.
David
