search

briandfoy / PerlPowerTools

Perl Power Tools
https://metacpan.org/pod/PerlPowerTools
Other
214 stars 53 forks source link

Make consistent Pod documentation #3

Open briandfoy opened 10 years ago

briandfoy commented 10 years ago

Inside each program under bin/, create consistent Pod documentation, including the name of the program, the list of the contributors, and so on. See bin/factor for an example.

jgpuckering commented 1 year ago

In addition to POD, it would be useful to have all these scripts support command line arguments for getting help and a usage synopsis. That deserves its own ticket, I suppose.

Also I’ve noticed the scripts have a mix of Getopt::Std and Getopt::Long. I wonder if that results in some inconsistencies in argument handling that ought to be addressed? (The syntax and semantics of options needs to match the equivalent Unix utility as much as possible — but should also be internally consistent within PPT.)

briandfoy commented 1 year ago

Note that we specifically do not have a goal of consistency. Tom's original idea was that these programs could do the same work as the common unix counterparts, which as a set are also not consistent.

But, if something does not have --help or -h options, and the original command does not use those for something else, we might add those. However, the original interface for the command we are copying should be the guide. Michael was able to do that for several previous PRs. I think that's what you are also saying, but I want to make sure that's said.

However, we can have consistent POD docs where we show everything in the same way. That would be a big help. How a particular program decides to show that for you is a different matter.

jgpuckering commented 1 year ago

Ok, I agree with all that. My takeaway is that there there’s wiggle room for differences, but a low tolerance for inconsistencies with the Unix counterparts. Inconsistencies amongst the scripts are tolerated to the extent they exist in the Unix counterparts. We shouldn’t make those any worse!

My recent changes to units included the ability to optionally feed input via command line arguments. The Unix version doesn’t have that, although I think it should. In retrospect I should probably have implemented that as a new command line parameter, but I was going for simplicity: units 12m ft vs units -input “12m ft”. Also I was thinking at the time about using that mechanism for testing — before going a different route. It probably doesn’t matter in units, but adding optional unkeyed parameters could cause someone a compatibility problem if I did that in a script like bc, which doesn’t expect any parameters. Seems unlikely given its interactive design, but perhaps I should change units anyway. What do you think?

To sum up, with all these points in mind, I’ll probably work on adding POD where it’s missing or deficient (e.g. bc) as well as -help support.

One last point. For -help and -usage/-? can I make use of POD::Usage and pod2usage?

briandfoy commented 1 year ago

Pod::Usage is fine since it's a core module since 5.006