Re: Improving Documentation of support scripts

[David G <..hidden..>]

Hi Robert,

On 02/01/16 22:51, Robert James Clay wrote:
> On Wednesday, December 30, 2015 02:16:34 PM David G wrote:
>> Hi,
>>
>> A while ago Erik and I were discussing the need to better document the
>> various scripts and files that are not directly part of the LedgerSMB code.
>    That also brings to mind; do we have any requirement or 'best practice'  to 
> have copyright/license information explicitly in the scripts, etc?
Funny you should mention that, we (Erik, John, and I) had quite a
discussion regarding  copyright on IRC last night.
I believe Erik covered part of the teams thoughts in a thread titled
"Copyright Dates"
However it does bear more discussion.
Perhaps a comment on that thread?

>
>> An alternative would be to require every script to provide a number of
>> command line options. ....
>> The arguments I propose all executables (scripts and binaries) support are
>>      * --help 	  displays a Usage Summary followed by more detail if
>>                         required.
>    Agreed...
>
>
>>     * --readme   displays a markdown formatted chunck containing
>>                         script description an usage summary
>    I can see possible issues where there are more documentation lines than 
> code lines but that's not necessarily a bad thing and one can always just make 
> sure that the '--help' option is markdown safe and use that for the '--readme' 
> option as well. 
The --readme entry could be a single line (brief usage)
The main generation/colation script could easily include --readme +
--version + --help.
That should reduce the required lines in individual scripts
>    
>
>>     * --version  reports the script version in "scriptname v1.0.0" format
>     Sometimes it doesn't have an explicit version number like that, but OTOH 
> it can just display whatever it does use.
>
>
> And this reminds me that a bash script that I have the Debian package install 
> to the tools/ directory ('config-lsmb-db-user.sh'; used to configure the 
> LedgerSMB DB admin user) needs to have such information added to it.
If there isn't an explicit version number, it really isn't hard to add one.
There are advantages, such as confirming that a fix has been applied (to
a script) before calling it (from another script).
Right now there are few scripts that this would matter for, but with the
new Release Notification scripts in /utils/release/ and some upcomming
additions that may be more important in the future.
>
>
>
>
> Jame
>
>
>
>
>
> ------------------------------------------------------------------------------
> _______________________________________________
> Ledger-smb-devel mailing list
> ..hidden..
> https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel
>


------------------------------------------------------------------------------
_______________________________________________
Ledger-smb-devel mailing list
..hidden..
https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel