Hot Shareware 35

home *** CD-ROM | disk | FTP | other *** search

/ Hot Shareware 35 / hot35.iso / ficheros / DINET / ORB13DOS.ZIP / ORBMAN.TXT < prev next >

Wrap

Text File | 1996-11-17 | 30KB | 783 lines

ORB An HTML Preprocessor Version 1.3 -- October 1996 UserÆs Manual Copyright 1996 by Craig Berry cberry@cinenet.net http://www.cinenet.net/users/cberry/orbinfo.html 1. Overview Orb is a tool for Web developers which makes design, development, and maintenance of large sites easier. I created it while working on my first relatively large Web project, the Ordo Templi Orientis U.S. Grand Lodge site at http://otohq.org/oto/ . The uniform ôlook and feelö of that site was achieved and is maintained using Orb. Orb source files consist of normal HTML source with additional Orb-specific markup; the latter is parsed and replaced by Orb to create a pure HTML output file. As a result, existing HTML files can simply be renamed (from .html to .orb) to become Orb files, with internal changes then made incrementally. 1.1 Major features File Inclusion As in C and other programming languages, you can put common HTML elements (like navigation bars), variable definitions (see below), and so forth in "header files," which are then included by each Orb source file at a site. Changing the look or contents of your site is then as easy as changing one header file and recompiling. Symbolic Variables Nothing is more annoying than re-entering a long link reference which occurs multiple times across many pages at a site. Even if you use an HTML editor to simplify this task, you're still in trouble if the link address changes; this requires manual editting of each link instance...if you can find them all. Orb allows you to define symbolic variable names for commonly used addresses, HTML elements, or whatever -- put these in a common header, and suddenly your maintenance problem is solved. Time Formatting Orb provides built-in support for including the date and time of HTML file creation on your pages in any desired format, using local or GMT time. This makes it easy to "time stamp" your documents with last-revision information automatically. Conditional compilation What HTML gets generated can be made dependent on whether certain variables have been defined. This is handy in (for example) using one source set to generate pages targeted for different browsers. Better comments Native HTML comments (like ) are notoriously hard to use. Different browsers react differently to tricks such as commenting out HTML markup. Orb provides its own comment syntax, for both single-line and block comments. These comments entirely disappear during Orb preprocessing, making your production HTML files cleaner and shorter. Predefined variables Orb offers a variety of predefined variables for such things as the time and date of compilation, the Orb and HTML file names, and so forth. These simplify many common site housekeeping chores, such as ensuring that all pages are marked with their last-modified dates. 1.2 Orb vs. CGI/SSI Many of the things Orb is best at (file inclusion, last- modified date stamping, and so forth) can also be accomplished using CGI and even its subset, Server-Side Includes (SSI). However, Orb is a better solution for building page data if that data changes relatively infrequently. Consider that CGI/SSI requires server-side system resources on each page fetch to construct the served page, while Orb allows this overhead to be paid just once, at page compilation time, with zero additional cost during page accesses. Also, CGI and SSI are not available on all Web servers, nor are the details of usage identical between servers which do support them. All told, thereÆs a great deal to be said for the Orb preprocessing approach over CGI/SSI. 1.3 Availability Orb is available for a number of platforms, including DOS, OS/2, and various flavors of Unix. For current information on supported platforms and other late-breaking developments, consult the Orb information page at http://www.cinenet.net/users/cberry/orbinfo.html. Orb is shareware. If you find this tool useful in creating and managing your Web sites, please register your copy by sending $20 (US) to the following address: Craig Berry 11301 W. Olympic Blvd., #547 W. Los Angeles, CA 90064 USA Be sure to include your email and (optionally) snail-mail address with your payment. Registering Orb will ensure that you receive all future upgrades directly by email when they become available. Perhaps more important, it will compensate me for the time and effort involved in creating Orb, encouraging me and other developers to continue making high-quality software available through shareware distribution. 1.4 Notes I welcome comments, suggestions, and bug reports concerning Orb, from both registered and unregistered users. I can be reached at cberry@cinenet.net. The name ôOrbö refers to the most commonly recognized form of spiderweb -- the ôcircles and spokesö variety created by many garden spiders. I wanted a short, catchy name which had something to do with the Web; Orb struck me as a natural. 2. Installation 2.1 Parts list The following files comprise the DOS and OS/2 shareware packages: ORB.EXE The Orb preprocessor itself ORBMAN.TXT A plain text (ôflat ASCIIö) version of the Orb UserÆs Manual ORBMAN.WRI A Microsoft Windows Write version of the Orb UserÆs Manual TEST1.ORB An example Orb home page source file TEST2.ORB An example Orb subpage source file HEADER.ORH An example Orb header include file FOOTER.ORH An example Orb footer include file TEST.MAK An example Orb makefile On other operating systems, the .WRI version of the documentation is omitted, the filenames are lowercase, and the executable will be named ôorbö with no extension. 2.2 System Requirements The following applies only to Orb for DOS: - IBM PC or compatible, 8086+ - DOS v3+ - 100+ KB conventional memory - Text display (no graphics required) Orb uses no temporary files, initialization files, or anything of that sort. The Orb executable contains everything needed by the Orb application; all other components of the distribution package are documentation and examples. Orb also makes no use of extended or expanded memory. 2.3 Installation steps 1. Create a new directory for the Orb components -- C:\ORB under DOS, for example. 2. Copy the Orb distribution files into this directory. 3. Edit your AUTOEXEC.BAT, .cshrc script, or whatever, adding the Orb directory to your PATH variable. 3. How It Works Note that in the following description, DOS filename conventions are used. Under Unix and many other operating systems, the standard extensions are lowercase, and can be longer than three characters. Orb tries to do the ôright thingö on each platform. Orb is a preprocessor which allows you to create Web pages using a superset of HTML. By convention, Orb input files have the extension .ORB (for primary source files) or .ORH (for ôheaderö files which are to be included in other Orb files). Orb will (in most cases) generate one output file (with the default extension .HTM) for each primary source (.ORB) file it processes, using the original base name of each input file. So, for example, the command orb foo.orb bar.orb baz.orb would (if all went well, and no output-redirection overrides occurred in the source files) create three files named FOO.HTM, BAR.HTM, and BAZ.HTM. One may think of Orb as compiling .ORB source files for use on your Web site as .HTM ôexecutables,ö in analogy with the way (for example) .C source files are compiled into .EXE files by a C compiler. Because Orb is a superset of HTML, it will (in almost all cases) pass ordinary HTML content through to the output file undisturbed. This is an important consideration if you are converting existing HTML documents into Orb source files. You can achieve the first step just by renaming XXX.HTM to XXX.ORB, with the latter compiling to yield the original file. You may then begin adding Orb elements incrementally. Orb will only take special action when it finds an Orb element in the input file. All Orb elements consist of a pair of open-square-brackets - [[ - followed by zero or more other characters, possibly including embedded Orb elements, followed by a balancing pair of close-square- brackets - ]] - all on the same source line. Note that nesting can occur; the (nonsensical) source line Blah blah [[foo [[bar]][[baz]]]] and blah blah blah contains one top-level Orb element, which in turn contains two nested elements. In order to provide maximum compatibility with existing HTML documents which might happen to contain square-bracket pairs, Orb will pass through without modification anything that looks like an element, but cannot be parsed to yield a valid operation (see next section). Orb will generate a warning in this circumstance, however. Orb elements are intended to perform operations -- sending special text to the output file, or changing the internal state of Orb itself by defining a variable, or perhaps conditionally or unconditionally suppressing output from a region of the source file. Operations come in two varieties -- directives and variable references. 3.1 Directives Directives all begin with a dollar sign - $ - just inside the opening [[. They cause Orb to perform special functions like setting variable values, outputting formatted dates, including other files to be processed by Orb, and controlling processing of sections of the source file. The following directives are currently defined (note that all directive names are case sensitive): 3.1.1 Variable value manipulation $define name {value} [Synonyms: $def, $set] Sets the value of an Orb variable, which may then be used in later variable references (see below). If name has already been set, the new value quietly replaces the old one. The name should include only letters, digits, and underscores, start with a letter or underscore, and be at most 32 characters long (these limitations are not all currently enforced, but will be in an upcoming version). The value may contain spaces, embedded Orb elements, and anything else up to the closing ]] -- though remember that it must all fit on a single source line. Leading spaces in the value are not included, but explicit spaces may be obtained using the SP predefined variable if required. If value is not provided, a zero-length string is used. The $def synonym is intended as a convenient abbreviation which also better parallels $ifdef, $undef, and so forth. The $set synonym is provided for backward-compatibility with earlier versions of Orb. The next major version will drop support for $set, so donÆt use it in new development, and change old source to use $def/$define as soon as possible. Example: [[$define email cberry@cinenet.net]] $undef name Causes Orb to ôforgetö the value of a variable. No warning is generated if the variable does not exist. Example: [[$undef email]] $val var {default} If the variable var is defined, this behaves just like a simple variable reference (see below), substituting that variableÆs value into the output. If var is not defined, the value of default is used instead. If default is not provided, no output occurs for this directive. Example: [[$val title No title provided]] 3.1.2 Conditional compilation $ifdef name Starts a conditional-compilation block. If name is defined, everything proceeds normally until an $else or $endif is encountered. If name is not defined, nothing will be processed from the source file until the next $else or $endif. In the $else case, the source between that $else and the closing $endif will be processed if the code above the $else was not, and vice versa. See ôConditional Logicö below for more discussion and examples. Example: [[$ifdef toplevel]]Hey, I have a top level![[$endif]] $ifndef name The reverse of $ifdef; conditonally compiles based on whether name is not defined. Example: [[$ifndef toplevel]]Oops, I donÆt have a top level![[$endif]] $else Only occurs inside if-blocks (see $ifdef). Causes the conditional state to flip; active if it was inactive, and vice versa. Only one $else can follow each $ifdef/$ifndef. Example: [[$ifdef foo]] I have foo... [[$else]] I donÆt have foo. [[$endif]] $endif Closes an if-block. Only one can follow a given $ifdef/$ifndef. 3.1.3 File handling $include filename Brings the entire contents of the named file into the current one, as if the text of that file were contained in this one. By convention, files intended for inclusion in this manner have the extension .ORH (ôORb Headerö). Note that the -I command line option and the ORBPATH environment variable can be used to specify additional directories in which to search for include files. The current directory is always searched first, then any -I paths, and finally paths from ORBPATH. Example: [[$include header.orh]] $target filename Closes the current output (ôtargetö) file, opens the named file as the new output file, and continues compilation of the source file. This allows a single Orb source file to produce several HTML output files. Example: [[$target part2.html]] 3.1.4 Time formatting $time {mode {format}} Sends a textual representation of the current system time at the start of compilation to the output file. The mode argument can be lcl, which selects local time, or gmt, which selects Greenwich Mean Time, also known as UTC time. The format argument provides a time format string of the type used by the ANSI C strftime() function (see Appendix C for details). If no arguments are given, local time is assumed; if no format is supplied, the output looks like this: 1996/03/17 15:23:34 -- with the hour in 24-hour (ômilitaryö) format. See also the datetime_gmt and datetime_lcl predefined variables, described below, for another approach to using time value in Orb. Example: [[$time gmt %M/%D/%y]] This example outputs the month, day, and two-digit year, separated by slashes. 3.1.5 Comments $comment [Synonym: $/*] Opens a comment block. This will inactivate all other Orb processing and output until a matching $endcomment (synonym: $*/) is encountered. Note that this even overrides conditional compilation; a comment opening inside an ôinactiveö block will start a comment block, which will in turn hide all conditional directives until the comment closes. The synonym $/* is inspired by the C open-comment marker. Example: [[$/*]]Here I am, inside a comment[[$*/]] $endcomment [Synonym: $*/] Closes a comment block. $rem anything [Synonym: $//] Completely ignores its arguments and sends nothing to the output file. The may be used to put comments (ôremö is short for ôremarkö) in Orb text. The $// synonym is inspired by the C++ unterminated-comment mark; note that (unlike the C++ version) a space must separate the $// and what follows. Example: [[$rem This section defines globally useful links.]] 3.1.6 User-detected errors $error anything [Synonym: $err] Halts Orb processing with a fatal error, incorporating the error-message in the resulting message to the user. This can be combined with conditional processing to detect configuration problems; for example, if some value is supposed to be provided on the Orb command line using the - D option (see below), you can check for this using this syntax... Example: [[$ifndef cfgparm]] [[$error cfgparm not defined on command line!]] [[$endif]] $message anything [Synonym: $msg[ Similar to $error, but for informational and warning-level messages. Does not halt Orb processing. 3.2 Variable References The value of a variable defined with the $def directive (see above) or provided by Orb (see below) can be placed in the output file using a variable reference. This consists simply of the name of the variable, enclosed by bracket pairs as usual. So, for example, the Orb source statements [[$def email cberry@cinenet.net]] You can <A HREF=ômailto:[[email]]ö>contact me</A> for more information about Orb. would produce this output: You can <A HREF=ômailto:cberry@cinenet.net>contact me</A> for more information about Orb. As mentioned above, each variable reference returns the most recent value assigned to that variable. Note that an Orb element which looks like a variable reference, but names a nonexistent variable, will be passed through ôrawö (square brackets and all) to the output. The Orb compiler will generate a warning message if this occurs. 3.3 Predefined Orb variables The Orb compiler itself makes a few useful variables available to you. Note that your own Orb code should avoid changing these values, though nothing prevents you from doing so. 3.3.1 Orb configuration information orb_platform The platform on which Orb is being run (e.g., ôDOSö). orb_vernum The version number of Orb, X.Y (e.g., ô1.2ö). orb_version A string indicating OrbÆs version and platform information (e.g., ôOrb v1.2 for DOSö). orb_generator A preformatted META tag, suitable for direct inclusion in an HTML <HEAD> section, indicating that the target HTML document was generted by Orb (e.g., ô<META NAME=ôgeneratorö CONTENT=ôOrb v1.2 for DOSö>ô). 3.3.2 File information base The name of the primary source file (the .ORB file, most typically) which is currently being compiled. Note that this stays fixed throughout the compilation of a given .ORB file, as opposed to the source variable (see below), which changes to track included files. source The name of the specific source file currently being processed by Orb. Initially, this will be the same value as base, but source will change if other files are brought in using the $include directive. target The target, or output file, of the current compilation; typically a file with the extension .html. 3.3.3 Time information datetime_gmt The date and time at the start of Orb compilation, expressed in the HTTP standard format, which looks like: Sunday, 03-Mar-96 23:45:14 GMT datetime_local As above, but the local time rather than GMT. If your environment is set up properly (most notably, if youÆve defined the environment variable TZ), your own timezone code will replace GMT at the end of the string. 3.3.4 Special characters OBR One open-square-bracket - [ OBR2 Two open-square-brackets - [[ CBR One close-square-bracket - ] CBR2 Two close-square-brackets - ]] NL Newline. Becaue it's currently difficult to represent a newline in ORB, this predefined variable is provided for your use. Because of the near insensitivity of HTML to textual line structure, the uses of this variable should be relatively few. SP A single space character. This is useful for adding blank space to the beginning of a variableÆs value in a $def directive. 4. File processing A backslash \ at the very end of a line (followed by nothing but the end-of-line character) may be used to ôspliceö two lines together. The \ itself is discarded. This can be used to spread an Orb element over several source lines, while obeying the one-line-per-element rule. In the unlikely event your source has meaninful \ characters at the ends of lines which must be preserved in the output HTML, the -s option turns off line splicing. However, note that putting a space after the \ would accomplish the same goal. The -s option is provided only in the interests of fulfilling OrbÆs design goal of passing through all existing HTML source without modification. 5. Running Orb Orb accepts a number of command line options. The full syntax is: orb { opt | file }+ That is, an orb command may take one or more arguments, which can be options and file names in any order. Note that options (which begin with a dash) only apply to files listed after that option. Thus, typically you will want to put all the options first. The options available are: -b ôBashfulö mode -- suppresses title/copyright message. -Ccase Controls case-adjustment of all filenames. This option will rarely be necessary on operating systems other than DOS. The three case values supported are L (lowercase), U (uppercase), and M (mixed case). The default is -CL under DOS, and -CM on all other operating systems. Because DOS filenames are case insensitive, it is wise to force them to a single case for consistency. Generally, lowercase is more attractive, but you can force uppercase using -CU. -Dvar={val} One syntax for command-line variable definition. Within all source files listed after this option, the variable var will be defined with the value val, just as if it had appeared in a $def directive. If val is omitted, var will be given a zero-length string value. -Dvar val Alternate syntax for command-line variable definition. In this form, the value is listed as a separate argument, immediately following the -D option. On some operating systems (notably DOS), this makes it possible to define variables from the command line whose values contain spaces (e.g., -Dtitle ôMy Home Pageö). -Ipath Give alternate directories in which to find include files (see $include directive, above). Directories are separated by semicolons under DOS and OS/2, and by colons elsewhere. -h or -? Prints out an abbreviated version of this option description. -ofilename Send output to the named file, overriding the default behavior of using the source file basename and a .html extension. -o+{filename} Send output to the ôstandard outputö (the screen, unless you redirect it via a pipe or > on the command line). If the optional file name is supplied, Orb pretends internally that itÆs writing to the file named for purpses of setting the target variable. -q and -v By default, Orb produces enough output to let you know that progress is being made, without going overboard with detailed messages. These two options can be used to change this behavior. -q selects ôquietö mode, in which only the copyright notice and serious error messages appear. -v selects ôverboseö mode, in which more low-level information about Orb processing is displayed. -s Turns off line-splicing (see ôFile processing,ö above). -xstring By default, Orb will use the extension .html for the output files it generates. The -x option allows you to specify a different string for Orb to use. It may be up to 10 characters long. You should not include the initial period in this string! Note that only the first three characters will actually appear in the generated fileÆs name under DOS, but the target predefined variable will have the full extension. For example, the Orb command line orb -v -xhtx -Dtitle ôTestö -Dlogo=logo13.gif test1.orb would compile test1.orb to test1.htx, producing lots of output along the way. The variables ôtitleö and ôlogoö would be defined as indicated during the compilation. Wildcards in file names are fully supported, following the usual conventions for each operating system. Orb will return a zero status code on successful completion; any nonzero value indicates a compilation failure has occurred. An environment variable, ORBPATH, may be used to specify a standard set of paths to search for include files. Under DOS, the list of paths should be separated with semicolons; on all other platforms, colons should be used. For example, you might add this line to your AUTOEXEC.BAT under DOS: set ORBPATH=c:\www\pages\std;c:\www\pages\local This would cause Orb to search first the current directory, then any directories specified using the -I command line option, and finally these two directories when trying to locate an include file. 6. Orb and MAKE Orb is easy to use with any standard MAKE program. MAKE is a utility included with many compilers which simplifies the process of building large software systems. MAKE operates on a "Makefile" which contains instructions on how to transform source files into object code. It examines file revision dates to ensure that only necessary compilations occur. The example file TEST.MAK, included with this distribution, demonstrates one way to set up an implicit rule for building HTML files from Orb source files. Obviously, this two-page project cannot really display the usefulness of MAKE, but for larger projects, MAKE's ability to rebuild only those components necessary after a source change can be very, very useful. 7. Example Files Included with the shareware distribution of Orb are four example Orb source files, TEST1.ORB, TEST2.ORB, HEADER.ORH, and FOOTER.ORH. You can compile the two example .ORB files to TEST1.HTM and TEST2.HTM by entering the command orb *.orb or, if you have a typical MAKE program, you can enter the command make -ftest.mak Note that HEADER.ORH and FOOTER.ORH are intended to demonstrate how a consistent ôlook and feelö can be attained by encapsulating common HTML elements in include files; these files could be shared by many other .ORB files at a large site. Appendix A: Acknowledgments Two Orb beta testers, Arnoud Galactus Engelfriet and Nick Sweeney, deserve special recognition. Their feature suggestions and boundless patience with buggy early betas have been of enormous value to me. Appendix B: Change History 1996/03/01 1.0: Original release 1996/03/25 1.0a: Doc-only update - coverage of all operating systems, pointer to Orb web page, more overview material. 1996/04/01 1.1: -C, -D, -I, -?/h command-line opts, $val and $target directives, support for empty-value $set, ORBPATH environment variable. 1996/05/23 1.2: conditionals, block comments, line splicing, error directive, many new predefined variables. 1996/11/17 1.3: Better memory handling, many bug fixes. Appendix C: Time formatting Here are some typical values for time format strings used by the $time directive. The exact set available will vary from platform to platform; under Unix, do ôman strftimeö to see your local list. %% same as the ``percent'' character (%) %a locale's abbreviated weekday name (ôSunö) %A locale's full weekday name (ôSundayö) %b locale's abbreviated month name (ôNovö) %B locale's full month name (ôNovemberö) %c locale's appropriate date and time representation %d day of month ( 01 - 31 ) %H hour ( 00 - 23 ) %I hour ( 01 - 12 ) %j day number of year ( 001 - 366 ) %m month number ( 01 - 12 ) %M minute ( 00 - 59 ) %p locale's equivalent of either AM or PM %S seconds ( 00 - 61 ), allows for leap seconds %U week number of year ( 00 - 53 ), Sunday is the first day of week 1 %w weekday number ( 0 - 6 ), Sunday = 0 %W week number of year ( 00 - 53 ), Monday is the first day of week 1 %x locale's appropriate date representation %X locale's appropriate time representation %y year within century ( 00 - 99 ) %Y year as ccyy ( for example 1986) %Z time zone name or no characters if no time zone exists