[Axiom-developer] booklet function

[root]

I need a simple C program to do the following:

booklet [-v] bookletfile pamphletfile

The booklet function is basically a recursive macro-expander.

The booklet function takes as input the name of a booklet file and the
name of a pamphlet file. 

The bookletfile is any file that contains special strings of the form:
<<file:filename>>
which we will call a booklet URL. 

The booklet function replaces the whole booklet URL including the
surrounding << and >> symbols by the contents of filename.

The replaced text should be exact with no extra leading or trailing
characters so that x<<file:filename1>><<file:filename2>>y where filename1
contains a single byte 'a' and filename2 contains a single byte 'b'
should result in the inline string 'xaby'.

The replaced text is recursively searched for any instance of a
booklet URL and these are replaced inline.

The resulting text is output to the pamphletfile.

The -v flag is optional. If supplied the booklet function write the
replacement actions to standard output thus:
in (filename1) replacing <<file:filename2>> with text from (filename2)
where (filename1) is the file containing the booklet URL and
filename2 is the parsed filename from the booklet URL. This will
allow the user to trace where replacements are specified and where
the replacement came from.

If the file is not found the booklet function should fail with a clear
diagnostic traceback that outputs the containing file, the failing
booklet URL, and a recursive traceback. This should allow the user to
easily find the path of embeds that led to the failing line. The
failing booklet program should return a -1 to the shell.

Note that the filename in the booklet URL can contain a relative or
absolute pathname and will have to follow system-specific naming
conventions (forward-slash for unix, backslash for windows).

At this time only the file: protocol specifier is needed.

It should be a design criteria that the file: portion of the booklet URL
be considered one of a set of cases for a "protocol specifier" which will
be further specified in the future as needed (likely containing such
things as "http:", "pamphlet:", etc). 

It should be a design criteria that each protocol specifier has it's own
associated parser as the syntax of the booklet URL may vary based on the
protocol specifier. Thus,
<<file:filename>> parses the 'filename' portion as a path and file spec.
<<http:web>> parses the 'web' portion as any valid URL

Note that the booklet program should be developed as a literate program
and be contained in a single pamphlet file that does not use booklet URLs.
This is required so that the booklet function does not depend on itself.

(Axiom will build on multiple platforms and portions of the system will
be specified in booklet files. We need this program to be standalone
as it will be built very early in the process (even before the common
lisp). This will allow portions of the system to be written as booklet
files. The protocol specifiers will be used later to fetch pamphlet
files mentioned in the reference section of a pamphlet. Since we have
not used this feature yet there is no reason to implement anything. 
However, as we expect to use this feature in the future it is important
that the booklet function be (a) flexible enough to add other protocol
specifiers and (b) documented as a pamphlet file so others can change it.)

If this is unclear please ask questions.

Tim Daly
address@hidden
address@hidden