Re: Conversion text in documentation
On 10/30/21 12:18 AM, Shlomi Fish wrote: Hi David! Hi, Shlomi! do note https://perl-begin.org/topics/cpan/#preparing-dists which superseded it. See https://www.shlomifish.org/philosophy/computers/open-source/foss-licences-wars/rev2/#which-licence-same-as-perl Thank you for the links. :-) David
Re: Conversion text in documentation
Hi David! On Thu, 28 Oct 2021 22:02:43 -0700 David Christensen wrote: > On 10/25/21 12:41 PM, Andrea Tosoni wrote: > > Hello, > > > > 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 > do note https://perl-begin.org/topics/cpan/#preparing-dists which superseded it. > > 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 > See https://www.shlomifish.org/philosophy/computers/open-source/foss-licences-wars/rev2/#which-licence-same-as-perl . > > 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 -- Shlomi Fish https://www.shlomifish.org/ https://www.shlomifish.org/lecture/C-and-CPP/bad-elements/ Ariana Grande has one less problem *with* Chuck Norris. — https://www.shlomifish.org/humour/bits/facts/Chuck-Norris/ Please reply to list if it's a mailing list post - https://shlom.in/reply .
Re: Conversion text in documentation
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
Re: Conversion text in documentation
Hello, sorry : I'm asking if these modules can be a candidate to be posted on CPAN. Best regards, Andrea Il giorno mer 27 ott 2021 alle ore 08:53 Shlomi Fish ha scritto: > Hi Andrea! > > On Mon, 25 Oct 2021 21:41:21 +0200 > 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 read your message, but I don't understand what you wish to ask. What is > the > dilemma? > > > 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 > > > > -- > > Shlomi Fish https://www.shlomifish.org/ > https://shlomifishswiki.branchable.com/Self-Sufficiency/ > > Chuck Norris killed all the members of the Spanish Inquisition, so they > won’t > come unexpectedly. > — http://www.shlomifish.org/humour/bits/facts/Chuck-Norris/ > > Please reply to list if it's a mailing list post - https://shlom.in/reply > . >
Re: Conversion text in documentation
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 Il giorno mer 27 ott 2021 alle ore 17:02 Shlomi Fish ha scritto: > Hi Andrea! > > On Wed, 27 Oct 2021 09:06:07 +0200 > Andrea Tosoni wrote: > > > Hello, > > > > sorry : I'm asking if these modules can be a candidate to be posted on > CPAN. > > > > 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. > > > Best regards, > > > >Andrea > > > > > > Il giorno mer 27 ott 2021 alle ore 08:53 Shlomi Fish < > shlo...@shlomifish.org> > > ha scritto: > > > > > Hi Andrea! > > > > > > On Mon, 25 Oct 2021 21:41:21 +0200 > > > 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 read your message, but I don't understand what you wish to ask. What > is > > > the > > > dilemma? > > > > > > > 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 > > > > > > > > > > > > -- > > > > > > Shlomi Fish https://www.shlomifish.org/ > > > https://shlomifishswiki.branchable.com/Self-Sufficiency/ > > > > > > Chuck Norris killed all the members of the Spanish Inquisition, so they > > > won’t > > > come unexpectedly. > > > — http://www.shlomifish.org/humour/bits/facts/Chuck-Norris/ > > > > > > Please reply to list if it's a mailing list post - > https://shlom.in/reply > > > . > > > > > > > -- > > Shlomi Fish https://www.shlomifish.org/ > https://youtu.be/KxGRhd_iWuE - Never Give Up!! > > Unix was not designed to stop you from doing stupid things, because that > would > also stop you from doing clever things. > — Doug Gwyn ( https://en.wikiquote.org/wiki/Unix ) > > Please reply to list if it's a mailing list post - https://shlom.in/reply > . >
Re: Conversion text in documentation
Hi Andrea! On Wed, 27 Oct 2021 09:06:07 +0200 Andrea Tosoni wrote: > Hello, > > sorry : I'm asking if these modules can be a candidate to be posted on CPAN. > 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. > Best regards, > >Andrea > > > Il giorno mer 27 ott 2021 alle ore 08:53 Shlomi Fish > ha scritto: > > > Hi Andrea! > > > > On Mon, 25 Oct 2021 21:41:21 +0200 > > 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 read your message, but I don't understand what you wish to ask. What is > > the > > dilemma? > > > > > 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 > > > > > > > > -- > > > > Shlomi Fish https://www.shlomifish.org/ > > https://shlomifishswiki.branchable.com/Self-Sufficiency/ > > > > Chuck Norris killed all the members of the Spanish Inquisition, so they > > won’t > > come unexpectedly. > > — http://www.shlomifish.org/humour/bits/facts/Chuck-Norris/ > > > > Please reply to list if it's a mailing list post - https://shlom.in/reply > > . > > -- Shlomi Fish https://www.shlomifish.org/ https://youtu.be/KxGRhd_iWuE - Never Give Up!! Unix was not designed to stop you from doing stupid things, because that would also stop you from doing clever things. — Doug Gwyn ( https://en.wikiquote.org/wiki/Unix ) Please reply to list if it's a mailing list post - https://shlom.in/reply .
Re: Conversion text in documentation
Hi Andrea! On Mon, 25 Oct 2021 21:41:21 +0200 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 read your message, but I don't understand what you wish to ask. What is the dilemma? > 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 -- Shlomi Fish https://www.shlomifish.org/ https://shlomifishswiki.branchable.com/Self-Sufficiency/ Chuck Norris killed all the members of the Spanish Inquisition, so they won’t come unexpectedly. — http://www.shlomifish.org/humour/bits/facts/Chuck-Norris/ Please reply to list if it's a mailing list post - https://shlom.in/reply .
