xm-tool

How To Develop

The xm-tool project is still in its early stages, actually it transform many of older perl snippets from various sources into a full package form. It happens that through time many many perl scripts have been developped to generate, transform and consume xml'ish data. Actually, it became obvious that there were a lot of double-work inherited, so the idea of a perl/xml project came up. Unlike the standard XML tools in the perl area, it uses just simple text as its input medium and output medium - just the xml-tag enhanced series, no special internal form of perl hashes and array that could hardly be scanned with regex expressions.

The use of regex will probably be far easier to understand for many many developers out there, and there are only very few rules to adhere to when it comes to perl regex expressions. And you can always look at the text after each step as it is just normal text. In many places the complexity of combining some xm-tool scripts into a processing tool boils down to just setting up a shell pipe chain. Have a look at the doc-directory that comes with the xm-tool doc-Makefile to see how easy that is.

regenerate

In order to ease the integration of new snippets and documents, I use a pre-automake step called "make x" - have a look at the top Makfile.am, it will just step through a series of subdirectories and generate a Makefile.am from a Makefile.am_ where some filelist variables in that Makfile.am are replaced with the list of files actually existing in that directory. Therefore, if you add some perl snippet or some other document of a known extension-type, the sequence to remake the developer tree is:

make x automake configure

After that, well you can use "make" and "make install". The documentation in the doc/-subdirectory is not made by default, since it is also generated with xm-tool scripts... which happens not to be installed at make-time. Therefore, to remake the doc-directory you do:

make make install make doc

extending

A snippet to be added basically requires a path under the xm-directory, and then be given the package-name that corresponds to that path. Therefore, if you choose to create a new doctype, then the filename is probably "xm/doctype/mytype.pm" and the first lines of that .pm-file should read

package xm::doctype:mytype use xm::o; use strict;

There are few helper routines in xm::o that will help you to scan additional arguments (that are put into a global hash named %o) and to read the xml-ish data from the files provided. xm-specific data that should be able to cross xm-perl package boundaries should put their data into the global hash named %xm.

There is a xm-perl shell-script installed into the standard path that will recognize a package name like xm::cread - this sequence will be transfered into a default minimal perl program that will first call the perl'package ARGS and then feed the result to the perl'package DO subroutine. Therefore a shell-call as "xm-perl xm::cread myfile.c" will actually run a perl script like

use xm::cread $_ = xm::cread::ARGS(\@ARGV); print xm::cread::DO($_) if length;

The xm-perl shell-script enables you to run an xm-tool snippet directly from the commandline, or inside a shell-pipeline. Of course you could run the xm::cread::DO routine from inside a more complex perl-script that wants to use the functionality of that perl-module. And the xm-tool module could export a lot more subroutines for general usage - they would just have to be prefixed with the packagename. And please remember, if your complex scripts exhibits to be something useful, then you should submit it to the xm-tool project - it does not need to be of general usage, just invent a subdirectory of the xm-directory and place your snippets in there - they can be atleast a guideline and make the life of many people easier who need to do something not far unlike what you did. Programmers will often have a need to do sth. similar, so don't hesitate about bad coding, just turn your perl-script into a xm-tool snippet by adding the five lines as described (or seen in the provided scripts), and submit it to the xm-tool project.

(note that the scripts for the generation of the pfe documentation live in this package, and not there. It will serve you as examples for your own scripts, and it should really encourage you to submit your own xm-tool based documentation generator in here. The parts that are very pfe specific are named xm::pfe::snipppet)

If you create a new subdirectory then you may want to add a similar Makefile.am_ as you can see in the other subdirctory - actually just a few shell-variables, and an automake-target to specify what should be installed to the global xm-tool share-directory and which other files should be just packaged along when calling "make dist" in the toplevel directory. A new directory with a new Makefile.am_ should also be registered in the AC_OUTPUT section of configure.in and the "make x"-target of the toplevel Makefile.am (then run autoconf/autoconf/ and so on).

Of course I can do all that for you, just contact me.