keyval2sh

Name

keyval2sh — Converts XML <keyval> files to bash command line arguments.

Synopsis

Description

The keyval2sh bash shell script treats a <keyval> file as a specification for command line arguments. It can be used to provide the following services when building scripts:

When used with just the --name NAME argument, it will create up to SEVEN files, providing the developer with an initial starting point for creating a bash script with an associated man page.
Subsequent invocations where --name NAME is passed, will only cause the THREE files (NAME_config.sh, NAME_config.docbook_options and NAME.docbook_synopsis) to be generated.
You as the developer will then replace the initial NAME.sh created with the function you want to perform (you don't have to worry about the command line arguments as the code to handle this will be generated for you automatically).
As a developer, you will then want to update the initial NAME.docbook and NAME_config.xml files (and possibly the NAME.mk file) to correspond with your script's behavior.
If you are working in a m4 environment, you have the option of having m4 man page support files generated for you.

A tutorial for using this script is available in the xml-keyval package document.

Options

The following command line options are available:

[ -n TEXT | --name TEXT ]: This utility is designed to work with a set of files all having a root NAME. This option is used to specify the root NAME. This utility assumes that NAME_config.xml will be the source XML file. This utility can then generate NAME_config.sh, NAME_config.docbook_synopis, NAME_config.docbook_options, and NAME_config.sh_m4i. In addition, when templates have not been disabled, it will also generate NAME_config.xml, NAME.sh, NAME.mk, NAME.docbook and NAME.man.m4 if they don't exist.
[ -d TEXT | --doc-type TEXT ]: This option allows one to specify what type of documentation files are to be produced. Use "none" if you don't want any documentation files. Use "docbook" to get a synopsis section and option section suitable for inclusion in a DocBook publication (used for creating man pages and HTML). Use m4 to get a include file suitable for use in a m4 based man page.
[ -t true|false | --templates true|false ]: This utility will stub in template files to get you off on the right foot with creating a new script. Unless you disable this feature, it will generate a template version of NAME_config.xml, NAME.sh, NAME.mk, and either NAME.docbook or NAME.man.m4 (however, this utility never replaces any of these initial files if they already exist).
[ -l FILENAME | --log-file FILENAME ]: If you are encountering errors when running keyval2sh, try using this option and examine the log file after running keyval2sh. It may provide useful clues as to what went wrong.
[ --install-query TEXT ]: This option allows a user to specify options like --install xsl to retrieve information about the package installation. This might be useful for making use of the package files outside of the packaged scripts. --install-query help will list all possible. The following choices are recognized: help - lists what choices are available. xsl - shows the directory the XSL files are stored under. public-id - displays the public ID of the keyval documents. public-url - displays the public URL of the keyval DTD. dtd - shows the location of the keyval DTD file. catalog - shows the location of the XML style catalog file. catalog-oasis - shows the location of the OASIS style catalog. docs - shows local directory where the documents can be found. url - shows the public URL where documenation can be found.
[ --type TEXT ]: This option allows you to specify exactly one type of file to generate from your source XML file (by default, numerous files are generated). For example, if you just want the NAME_config.sh file to be generated, you would specify --type sh. This function makes it easier to include this script in makefiles (or other scripts). Any of the following types are recognized: docbook_options, docbook_synopsis, html, sh or sh_m4i. NOTE: If you specify this option, templates will NOT be generated regardless of the --templates BOOL setting.

Files

/home/pkb/usr/share/vaisala/xml/keyval/dtd/keyval_1_0_0.dtd: Location of the DTD which is used to validate the <keyval> document.
/home/pkb/usr/share/vaisala/xml/keyval/xsl: The directory containing the XSL files used when translating <keyval> documents.
/web/vaisala/xml/keyval: The directory containing the package documentation (including a tutorial on using this utility).
$HOME/tmp/vaisala/jars: The directory where required JAR files will be stored if they need to be downloaded from the network.
/var/vaisala/jars: The system directory which is searched for required JAR files. System administrators may wish to copy the required JAR files to this location to prevent each user from downloading their own copy.
/home/pkb/usr/share/vaisala/xml/keyval/xsl: The directory containing the XSL files used when translating <keyval> documents.

Environment

XML_COMMON_JAVA: When translating XML documents with a XSL style sheet, the keyval2sh will need access to a Java run time environment (v1.4.2 or later). If the java interpreter found in your path is not version 1.4.2 or later, you can use this environment variable to specify the location of the appropriate java interpreter. In addition, you can also use it to specify HTTP proxy information for your java environment. For example, a setting of /liz3/pkb/usr/j2re1.4.2_03/bin/java -DproxyHost=172.26.0.232 -DproxyPort=3128 would specify a path to a particular java interpreter and set the HTTP proxy settings.
XML_COMMON_CLASSPATH: When translating XML documents with a XSL style sheet, the keyval2sh require some JAR files which are not often found with a default java installation. If these JAR files are not found in their expected locations, they will be automatically downloaded and placed in the ${HOME}/tmp/vaisala/jars directory. However, this "automatic download as necessary" can be disabled if you manually set your XML_COMMON_CLASSPATH.

Authors

Paul Blankenbaker created the initial script, XSL files, and build environment.