Synopsis


scriptinfo [options] scriptname

Options

General options:

-h,--help	print short help and exit
-H,--Help	print full documentation and exit
-V,--version	print version and exit

Output options:

-b,--brief	print brief output for usage in scripts
-m,--markdown	use markdown for github-compatible output
-o,--options	list the options and exits

Description

For a script with gendoc documentation, scriptinfo prints the script's short description, type, author, authors email, version, license and intro. The --brief option gives very terse output, the --markdown option generates a README file and the --options option lists the options formatted for the gendoc documentation.

If the script has no path information and is not found, it is looked up in PATH.

short description is found in the line starting with: =␣<scriptname>␣-␣
type is found in the shebang line.
author and authors email are extracted from the line after the line starting with =␣Author.
version must be on a single line and may be capitalized; the first occurrence will be used. Recognized formats are:

   version = 1.23
   $version = 1.23
   my $version = 1.23
   version => 1.23a
   version = "1.23"
   version = '1.23d'

  Whitespace in these formats may be arbirarily long or absent,
  including at the start of the line, anything may follow at the end,
  but a single lower letter will be part of the version number.

license is extracted from the line after the line starting with =␣Copyright.

The output of scriptinfo comes in three formats. The default is the long format, which for scriptinfo itself is like this:

    script: scriptinfo
      type: bash
    author: Wybo Dekker
     email: wybodekker@me.com
   version: 2.00
   license: GNU General Public License
     intro: For a script with gendoc documentation, scriptinfo
            prints the script's short description, type, author,
            authors email, version, license and intro.  The --brief
            option gives very terse output, the --markdown option
            generates a README file and the --options option lists
            the options formatted for the gendoc documentation.

With the --brief option, exactly 3 lines are output, one for each of short description, type, version. This is the output used by the instscript and gendoc scripts. For scriptinfo itself it looks like this:

   for a gendoc-documented script, print concise info
   bash
   2.00

With the --markdown option, a markdown version is produced, which is useful as a README file for github uploads. This option disables the --brief option. The output for scriptinfo itself is:

   scriptinfo                                                                 
                                                                              
  for a gendoc-documented script, print concise info                          
                                                                              
  ## Properties                                                               
                                                                              
              key │ value                                                     
  ────────────────┼─────────────────────────────────────────────────────────  
          script: │ ./scriptinfo                                              
            type: │ bash                                                      
          author: │ Wybo Dekker                                               
           email: │ wybodekker@me.com[1]                                      
         version: │ 2.00                                                      
         license: │ GNU General Public License                                
           intro: │ For a script with gendoc documentation, scriptinfo        
                  │ prints the script's short description, type, author,      
                  │ authors email, version, license and intro.  The --brief   
                  │ option gives very terse output, the --markdown option     
                  │ generates a README file and the --options option lists    
                  │ the options formatted for the gendoc documentation.       
                                                                              
  [1]: wybodekker@me.com mailto:wybodekker@me.com                             
                                                                              
  ## Options                                                                  
                                                                              
   option                       │ description                                 
  ──────────────────────────────┼───────────────────────────────────────────  
   General options:             │                                             
   -h,--help                    │ print short help and exit                   
   -H,--Help                    │ print full documentation and exit           
   -V,--version                 │ print version and exit                      
   Output options:              │                                             
   -b,--brief                   │ print brief output for usage in scripts     
   -m,--markdown                │ use markdown for github-compatible output   
   -o,--options                 │ list the options and exits

The --options option is useful when writing the documentation for a shell script. When the option handler contains lines like these:

   (-n|--nothing)# this option does nothing
   (-o|--output)# set output file name to X

then the command:

   scriptinfo -o script

will generate lines like this:

-n,--nothing	# this option does nothing
-o,--output=X	# set output file name to X

which can be inserted in the documentation. Note that the single character X, when it occurs in the comment line(s), is considered to be an argument of the option.

When you are editing the script with vim, you can insert such lines by giving the ex-command:

  :r!scriptinfo -o %

C binaries

My C binaries are compiled from bash scripts that copy their gendoc documentation into the C-source as text for the -h option; by inserting a newline before the text it is ensured that all lines can be grepped from the binary. The version information is not in these lines: it is obtained by running the binary with the -V option, which must have been programmed, of course.

Author

Wybo Dekker

Copyright

Released under the GNU General Public License

Functions used:

handle_options

synopsis:	handle_options "$@"
description:	handle the options.
globals used:	Myname Version
globals set:	args brief markdown listoptions

listopts

synopsis:	listoptions
description:	List the options in the format we need in the documentation.
	We don't take this info from the documentation, because this is meant for developers, who may add, remove or change options and their comments and want to update the documentation. This works for bash and zsh (where we scan the getopts call for info) and for ruby and python (where the built-in option `-h` provides the information. It does not for binaries of course, so here were trust that the options `-H]␣and␣`-V`␣are␣programmed␣to␣provide␣the␣needed␣info.`
globals used:	Nor Red doc script type
globals set:	-

print-readme

synopsis:	print-readme
description:	Print the README.md file for github
globals used:	blok properties scriptname short
globals set:	-