Common options

I personally prefer Getopt::Long for option handling. Your preferences may vary, but please provide at least the options specified in this example statement:

    # get options
  
    GetOptions(%options,
  
               "activeContents",    # evaluation of active contents;
  
               "cache",             # control the cache;
  
               "cacheCleanup",      # cache cleanup;
  
               "docstreaming=s",    # document stream handling;
  
               "help",              # online help, usage;
  
               "includelib=s@",     # library pathes;
  
               "nocopyright",       # suppress copyright message;
  
               "noinfo",            # suppress runtime informations;
  
               "nowarn",            # suppress runtime warnings;
  
               "quiet",             # suppress all runtime messages except of error ones;
  
               "safeOpcode=s@",     # permitted opcodes in active contents;
  
               "set=s@",            # user settings;
  
               "skipstream=s@",     # skip certain document streams;
  
               "tagset=s@",         # add a tag set to the scripts own tag declarations;
  
               "trace:i",           # activate trace messages;
  
              );

activeContents

flags if active contents shall be evaluated or not.

cache

allows user to activate and deactivate the cache.

cacheCleanup

enforces a cleanup of existing cache files.

docstreaming

specifies how document streams shall be handled.

help

displays a usage message, which is usually the complete converter manpage. The converter is stopped after performing the display task.

includelib

specifies a directory to be scanned for files included via an \INCLUDE tag - think of perl's -I option. Users are allowed to specify as many directories as necessary, to be investigated in the specified order. (Note: the environment variable PERLPOINTLIB can be used for the same purpose, but -includelib pathes will be scanned first.)

nocopyright , noinfo and nowarn

suppress informations a user can occasionally live without: copyright messages, informations and warnings.

quiet

combines nocopyright, noinfo and nowarn.

safeOpcode

Embedded code ("Active Contents") is usually executed in a Safe compartment. This way a user can control which operations shall be allowed and which shall be denied. According to the interface of Safe, allowed operations are specified by Perl opcodes as defined by the Opcode module. With this option, a user can specify such an opcode to allow its execution. It can be used multiply to accept several opcodes. Alternatively, the user might pass the special string ALL which flags that Active Contents shall be executed without any restriction - which will be done by using eval() instead of Safe.

set

provides a way to inject user defined settings into Active Contents. This is helpful to process documents in various ways, without a need to modify document sources.

skipstream

allows a user to hide a certain document stream. Can be specified multiply.

tagset

can be used multiply to declare that foreign tags shall be accepted. Foreign tags are tags not supported by the converter, but defined for other converters. By accepting them, a user can make a source pass to the converter even if it uses tags of another converter.

trace

activates several traces, at least of the frameset modules.

Luckily, the implementation of most of these options is as common as the options themselves and shown in the following sections. So in most cases it's no extra effort to provide these features.

For example, quiet can be implemented by

    @options{qw(nocopyright noinfo nowarn)}=() x 3 if exists $options{quiet};

It should be possible to control traces by an environment variable SCRIPTDEBUG as well as by option trace:

    $options{trace}=$ENV{SCRIPTDEBUG} if not exists $options{trace} and exists $ENV{SCRIPTDEBUG};