@database Umentiler.guide
@author "Lee Kindness"
@$VER: Umentiler_Guide />Version Umentiler NONAME NODATE<\
/>SETVAR PROGRAM Umentiler<\/>SETVAR FREQNAME UMENTILER<\
@node main "Umentiler />Version Umentiler NONAME NODATE<\"

   Umentiler :                   Umentiler version />Version Umentiler NONAME NODATE<\
                                 Copyright ©1995-/>DATE LF="%y"<\ Lee Kindness
 doc@{fg highlight}@{b}ument@{ub}@{fg text}
     comp@{fg highlight}@{b}iler@{ub}@{fg text}                    Easier document management... or something!


                   @{"  Introduction  " link INTRO   } : What does it do?
                   @{"     Usage      " link USAGE   } : More options...
                   @{"     Legal      " link LEGAL   } : Copyright, distribution...
                   @{"    History     " link HISTORY } : Version history
                   @{"     Other      " link OTHER   } : Other programs
                   @{"    Contact     " link CONTACT } : Author contact

---
Compiled              />Date from Umentiler LF="%A %d %B %Y %q:%M:%S"<\
Distribution built    />Date LF="%A %d %B %Y %q:%M:%S"<\ 
Exe size              />Program NL List Umentiler LFORMAT=%l<\ bytes
Main source size      />Program NL List source/umentiler.c LFORMAT=%l<\ bytes
Version               />Version Umentiler FULL<\
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node INTRO "Introduction"

 Right... what does it do? Umentiler simply compiles documents. It replaces
 and expands certain tags in the file. For example you could insert the 
 current time, version of a command, output from a command, another file
 into a file.
 
 ...But why? Well I am the author of over 28 programs, and a constantly
 releasing new versions. When a new version is released I would have to
 manually update the version numbers and my (constantly changing) email
 addresses... Rather frustrating!

 This guide, of course, has been compiled with the aid of Umentiler. The
 uncompiled version is called 'Umentiler_uc.guide'. You may wish to compare
 these documents...
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node USAGE "Usage"

                   @{" Invocation " link USEDC } : Launching Umentiler
                   @{"   Format   " link FORMAT} : Format of tags in files
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node USEDC "Launching Umentiler"

 Umentiler must be launched from a Shell. It accepts the following argument
 template:
 
   @{i}SOURCE/A,DESTINATION,BUFFER/K/N,QUIET/S@{ui}

 In short the first argument is the file to @{"process" link FORMAT} and the second is the
 destination. If you do not pass DESTINATION then SOURCE will be overwritten!
 For example:

   @{i}>Umentiler textfile textfile.um@{ui}

 Will expand all the @{"tags" link FORMAT} in 'textfile' and output to 'textfile.um'

 The BUFFER key word lets you specify the size of buffers (in bytes) that
 Umentiler uses for each open file. This is only effective with Workbench 3.1
 and higher, defaults to 4096 bytes.

 If you specify QUIET then Umentiler will not print out the number of processed,
 escaped and invalid tags.
 
 Umentiler is a pure command, and as such can be made resident. The 'p' bit
 should be set for the Umentiler command. It is not set then you should
 set it using:

   @{i}Protect Umentiler P ADD@{ui}

 You can then make Umentiler resident by typing:

   @{i}Resident Umentiler@{ui}
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node FORMAT "Tag Format"

 (If you are using Amigaguide rather than Multiview to view this then the
 output might not be correct...)
 
 The source file that you supply Umentiler with should be plain ASCII. It
 can contain 'tags' which will be processed by Umentiler. The format
 of the tags is:

   @{i}!/>Command options...<\ @{ui}

 Where 'Command' is one of:
 
   @{" Insert  " link C_INSERT}
   @{" Version " link C_VERSION}
   @{" Program " link C_PROGRAM}
   @{"  Date   " link C_DATE}
   @{" Setvar  " link C_SETVAR}
   @{"   Var   " link C_VAR}
   @{"   Tag   " link C_TAG}
 
 The command and arguments are not case sensitive. All the commands accept
 arguments in the normal Amiga ReadArgs template form.

 The output from the Insert and Program commands is itself parsed for
 tags. They are then replaced.

 To escape a tag, ie if you really want to include it in your text, then
 you simply precede it by '!':
 
   @{i}!!/>This will not be processed<\ @{ui}

 You can add as many '!'s as you wish, one less is always printed.

@{b}NOTE:@{ub}

 If you are putting an Amigaguide tag directly after an escaped Umentiler 
 tag then you should leave a space between the end of the Umentiler command 
 and the start of the Amigaguide tag:
 
   @{i}\@{i}!!/>Command options...<\ \@{ui}@{ui}
 
 rather than:
 
   @{i}\@{i}!!/>Command options...<\\@{ui}@{ui}
 
 Failing to leave a space will cause the Amigaguide tag to be escaped by the
 trailing '\' in the escaped Umentiler tag.
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_INSERT "The INSERT Command"

 The Insert command is used to insert the contents of a file. It accepts
 the following argument template:

   @{i}FILE/A@{ui}

 FILE: The path and name of the file to insert, must be given.
 
 For example:
 
   @{i}!/>Insert S:Startup-Sequence<\ @{ui}

 would insert your startup-sequence into the file.
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_VERSION "The VERSION Command"

 The Version command is used to insert version information from a program
 or file. It accepts the following argument template:

   @{i}FROM/A,F=FULL/S,NN=NONAME/S,NV=NOVER/S,ND=NODATE/S,NPD=NOPARSEDATE/S,USETAG/S@{ui}

 FROM: The file or program to read the version information from. Must be
     given. NOTE since this command uses the 'Version' AmigaDOS command
     you can also supply additional arguments to 'Version' in it, you
     could for example use "exec.library INTERNAL" for this argument.

 FULL: Print out the whole persion string, do not parse further with the
     NONAME, NOVER and NODATE options. Usefull if the version string
     is nonstandard.

 NONAME: Specifies not to print the name part of the version information.
     You can use NN for short.

 NOVER: Specifies not to print the version part of the version information.
     You can use NV for short.

 NODATE: Specifies not to insert the date section of the version information.
     You can use ND for short.

 NOPARSEDATE: If given then the date string will not be parsed, ie the
     brackets will not be removed.

 USETAG: If specifed then the Version command will not be used to retrieve
 the version information from the file. The internal TAG command will be used.

 For example:
 
   @{i}!/>Version C:Dir<\ @{ui}

 would produce:

   @{i}/>Version C:Dir<\@{ui}

   @{i}!/>Version C:List NONAME ND<\ @{ui}

 would produce:

   @{i}/>Version C:List NONAME ND<\@{ui}

   @{i}!/>Version C:Type ND<\ @{ui}

 would produce

   @{i}/>Version C:Type ND<\@{ui}

@{b}NOTE:@{ub}

 If the version string of the program is not 100% in the standard format then
 the results of the NONAME, NOVER and NODATE command options will not be as 
 expected! This is not my fault it is the fault of that programs author.
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_PROGRAM "The PROGRAM Command"

 The Program command is used to insert the output of a command or script.
 By default the commands input stream is NIL:, you can change this by using
 redirection in the CMDLINE. It accepts the following argument template:

   @{i}NL=NOLINES/S,CMDLINE/A/F@{ui}

 NOLINES: Specifies that you want any newline characters generated by the
     command to be stripped. You can use NL as a shortcut.

 CMDLINE: The command line to launch. This argument automatically expands
     to the end of the tag, so if the command line has spaces in it there
     is no need to suround it in quotes. Must be given.

 For example:

   @{i}!/>Program List C:d#?<\ @{ui}

 would use an 8000 byte stack and produce:

   @{i}/>Program List C:d#?<\@{ui}

   @{i}C:Dir is !/>Program NOLINES List C:Dir LFORMAT=%l<\ bytes long@{ui}

 would produce:

   @{i}C:Dir is />Program NOLINES List C:Dir LFORMAT=%l<\ bytes long@{ui}


@{b}NOTE:@{ub}

 If you re-direct the output of the command to NIL: then it has the effect
 of executing a command but not inserting any text.
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_DATE "The DATE Command"

 The Date command can be used to insert the date or time. It accepts the 
 following argument template:

   @{i}FROM/K,LF=LOCALEFORMAT/K,F=FORMAT/N/K,NY=NODAY/S,ND=NODATE/S,NT=NOTIME/S@{ui}

 FROM: Normally the date/time is read in from the system clock. If this
     keyword is specified then they are read in from the specified file.
     Keyword.

 LOCALEFORMAT: This keyword can be used to specify a locale date format
     string. Keyword. Can use FL for short. The format string may contain
     the following formatting codes:

         %a - abbreviated weekday name
         %A - weekday name
         %b - abbreviated month name
         %B - month name
         %c - same as "%a %b %d %H:%M:%S %Y"
         %C - same as "%a %b %e %T %Z %Y"
         %d - day number with leading 0s
         %D - same as "%m/%d/%y"
         %e - day number with leading spaces
         %h - abbreviated month name
         %H - hour using 24-hour style with leading 0s
         %I - hour using 12-hour style with leading 0s
         %j - julian date
         %m - month number with leading 0s
         %M - the number of minutes with leading 0s
         %n - insert a linefeed
         %p - AM or PM strings
         %q - hour using 24-hour style
         %Q - hour using 12-hour style
         %r - same as "%I:%M:%S %p"
         %R - same as "%H:%M"
         %S - number of seconds with leadings 0s
         %t - insert a tab character
         %T - same as "%H:%M:%S"
         %U - week number, taking Sunday as first day of week
         %w - weekday number
         %W - week number, taking Monday as first day of week
         %x - same as "%m/%d/%y"
         %X - same as "%H:%M:%S"
         %y - year using two digits with leading 0s
         %Y - year using four digits with leading 0s
         %% - percentage sign

     You will require Workbench 2.1 or higher to use this option. If you
     use this option then the FORMAT, NODAY, NODATE and NOTIME options
     are ignored (unless locale.library is unavailable).
     (NOTE: it appears that locale.library has a bug in it... this results
     in the %U and %W formatting codes giving incorrect results)

 FORMAT: Format of the produced date. Keyword. Can use F for short. You can
     use any of the following:

         0 - DOS format, dd-mmm-yy (Default)
         1 - International format, yy-mm-dd
         2 - USA format, mm-dd-yy
         3 - Canadian/British format, dd-mm-yy
         4 - Default locale format

 NODAY: Specifies that the day part of the date string should not be inserted.
     Can use NY for short.

 NODATE: Specifies that the date part of the date string should not be
     inserted. Can use ND for short.

 NOTIME: Specifies that the time part of the date string shouldn't be inserted.
     Can use NT for short.

For example:

   @{i}!/>Date LF="%n%A %d %B %Y%n%a %d %b %y%nDay%t%j"<\ @{ui}

would produce:

   @{i}/>Date LF="%n%A %d %B %Y%n%a %d %b %y%nDay%t%j"<\@{ui}

   @{i}!/>Date F=0<\ @{ui}
   @{i}!/>Date F=1<\ @{ui}
   @{i}!/>Date F=2<\ @{ui}
   @{i}!/>Date F=3<\ @{ui}
   @{i}!/>Date F=4<\ @{ui}

would produce:

   @{i}/>Date F=0<\@{ui}
   @{i}/>Date F=1<\@{ui}
   @{i}/>Date F=2<\@{ui}
   @{i}/>Date F=3<\@{ui}
   @{i}/>Date F=4<\@{ui}

   @{i}!/>Date NODATE NOTIME<\ @{ui}
   @{i}!/>Date NODAY NOTIME<\ @{ui}
   @{i}!/>Date NODAY NODATE<\ @{ui}

would produce:

   @{i}/>Date NODATE NOTIME<\@{ui}
   @{i}/>Date NODAY NOTIME<\@{ui}
   @{i}/>Date NODAY NODATE<\@{ui}
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_SETVAR "The SETVAR Command"

 This command never causes any text to be inserted. It allows you to set up
 a local environmental variable. This could be useful say if you were wanting
 to include a legal document (copyright, disclaimer...) in each of your
 program documents. You would use this command to set a variable to the
 program name and then in the lagal document you could insert the program
 name using the @{"VAR" link C_VAR} command. This command accepts the following
 argument template:

   @{i}NAME/A,TEXT/A/F@{ui}

 NAME: The name of the variable to create. This name follows file system
     naming rules. Must be given.

 TEXT: What to set the variable to. Expands to the end of the tag, so no
     need to enclose in quotes. Must be given.

 For example:

   @{i}!/>Setvar PROGRAM Umentiler<\ @{ui}

 would setup a variable called 'PROGRAM' and set it to 'Umentiler'

   @{i}!/>Setvar NAME Lee Kindness<\@{ui}

 would set up a local variable called 'NAME' and set it to 'Lee Kindness'
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_VAR "The VAR Command"

 The Var command can be used to insert the contents of local and global
 environmental variables. It accepts the following argument template:

   @{i}FROM/A,NL=NEWLINE/S,G=GLOBAL/S,L=LOCAL/S@{ui}

 NAME: Name of the variable to insert. Must be given.

 NEWLINE: If specified then a newline will be inserted after the variable
     is printed. Can use NL for short.

 LOCAL: Specifies only to search for a local variable that matches NAME.
     By default a local variable is searched for first, then a global. Can
     use L for short.

 GLOBAL: Specifies only to search for a global variable. Can use G for
     short.

 For example:

   @{i}Process !/>Var process L<\, RC = !/>Var RC L<\, Secondary RC = !/>Var Result2 L<\ @{ui}

 would insert:

   @{i}Process />Var process L<\, RC = />Var RC L<\, Secondary RC = />Var Result2 L<\@{ui}

   @{i}!/>Setvar PROGRAM Umentiler<\!/>Var PROGRAM L<\ @{ui}

 would insert:

   @{i}/>Setvar PROGRAM Umentiler<\/>Var PROGRAM L<\@{ui}
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node C_TAG "The TAG Command"

 The TAG command can be used to insert the contents of 'tags' from files into
 the document. A tag is defined as "$TAGNAME: text...". A prime example
 of a tag is the $VER version string used by the majority of programs. Some
 other programs use AUTHOR, ID, NAME and CONTACT tags.

   @{i}TAG/A,FILE/A,NONLCUT/S,DOLLERCUT/S@{ui}

 TAG: Name of the tag to search for. Case sensitive! Must be given.

 FILE: File to search for the tag in. Must be given

 NONLCUT: No newline cut. By default the tag text will only be printed
     upto the first null byte, newline or return character. Setting
     this switch causes the text to only be terminated by a null byte.
     Use with caution as tags in text files will not be null terminated
     and will result in the rest of the file being inserted into the document!

 DOLLERCUT: Will parse the file until a doller '$' character terminates the
     tag. Interacts with the NONLCUT option. This can be useful for use with
     RCS.

 For example:

   @{i}!/>tag VER Umentiler<\ @{ui}

 would insert:

   @{i}/>tag VER Umentiler<\@{ui}

   @{i}!/>tag MOOD Umentiler<\ @{ui}

 would insert:

   @{i}/>tag MOOD Umentiler<\@{ui}

   @{i}!/>tag MOOD Umentiler nonlcut<\ @{ui}

 would insert:

   @{i}/>tag MOOD Umentiler nonlcut<\@{ui}
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node LEGAL "Disclaimer, Distrubution and Copyright"

/>Insert S:Legal<\
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node CONTACT "Contact"

/>Insert S:Contact<\

I hope you find the program useful.

/>Insert S:ffplug<\


/>Insert S:Signature<\
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node HISTORY "History"

/>Insert History<\
@endnode
@remark &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
@node OTHER "Other Programs"

/>Insert S:Programs<\
@endnode
@remark MULTIVIEW BUG BARRIER!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!