Arguments to Control WebLord, the Document Assembly Tool
Logo WebLord v2.2
The Document Assembly Tool

WebLord Arguments

WebLord accepts a number of arguments on the command line. Only on of these is required: the site argument.

The order of arguments is of no importance, but if the site keyword is omitted, then the first unrecognized word on the command line is assumed to be the site argument. Any additional unrecognized arguments are assumed to be the names of pages to be built (see page).

The Getting Started section has examples on how to run WebLord.

Properties

Keyword Description

site

Gives the name of the Site Definition File.

The keyword 'SITE' is optional. If you omit it, the first unrecognized word on the command line is used.

Example: SITE my-definitions/foo.wl


page

Gives the name of a defined page to build. Multiple PAGE arguments maybe given on the command line.

If no pages are specified, then the Site Object object will supply the list of Default Pages to be built.

The keyword 'PAGE" is optional. If you omit it, unrecognized words on the command line will be used as a list of page names. See also: site, all

Example: PAGE Amiga PAGE Linux


all

Indicates that all pages defined in the site definition should be built.

This set of pages may include pages that are not part of the set of Default Pages.

See also: site, page

Example: ALL


nosubpages

Suppresses WebLord's processing of the subpages property of Page Objects. This is useful if you wish to build only one specific page within a tree of pages.

Example: NOSUBPAGES


define

Allows you to define one or more properties from the command line that temporarily become part of the Site Object. Such a temporary property will override any property that is previously defined by the Site Object.

Notice that you cannot override special properties, such as _OS.

Example: define "given-name='udo'; family-name='schuermann'"

Notice that the keyword 'define' is followed by a quoted string that encloses two properties, given-name and family-name, each with a value. The two are separated from each other with a semicolon.


saveas

Saves the site definition from your input back out to a file. This can be helpful when you want to have WebLord reformat your input or when you want to ensure that what WebLord read is correct.

Note: NEVER write the output to the same file as your input file, as an unforeseen problem could easily lose your input definition!

Example: SAVEAS scratch:test.output

See also: saveafterbuild, saveall


saveafterbuild

When used in conjuction with the saveas argument, tells WebLord to first process your site, build pages, etc. and then write the definition. The difference is, basically, that there are some situations where the definition may have changed due to events during processing. By saving the definition after these changes may have occurred you get a snapshot of these changes.

Example: SAVEAS foo.output SAVEAFTERBUILD

See also: saveas, saveall


saveall

When used in conjunction with the saveas argument, tells WebLord to include in the output all objects that actually came from files that were included (see include and try-include) which effectively merges the entire definition into a single file. This can be helpful when you need to take a snapshot of your site without any risk that later changes to the include files could affect your work.

Example: SAVEAS ~/test.output SAVEALL

See also: saveas, saveafterbuild


force

Pages are written out and their post-exec properties are evaluated and executed only if the page has changed in some way. To force WebLord to always write pages to the output, use 'force' mode.

As there is no guarantee that a previously created page file remains available against which a new page can be compared, WebLord generates a so-called "signature" of the pages it builds. This signature is quite small but unique and able to reveal any change to a page, however small.

WebLord keeps a record of these signatures against the exact names of the output files in a file that is called the Page Signature Database.

In order to determine if a page has changed or not, WebLord must still build what may be a new version of the page. This requires the same amount of time as building the page in "force mode"; what you save without forcing the pages to be written is the possible upload time to your ISP, a possible change to a this page last updated on ... tag that might otherwise be updated senselessly with every run of WebLord, etc.

See also: pagesigdb, noupdate


createpath

Any component of the output file path that does not exist will be created when you specify the createpath argument.


outputbase

The given directory forms the root of any page files written by WebLord that are not absolute paths.


pagesigdb

When used with force this gives the name of a specific file to be used for the Page Signature Database.

WebLord ordinarily looks for a file named wl-pgsig.db in...

  1. the current working directory,
  2. the weblord directory in your home directory (~/weblord/)
  3. the /opt/share/weblord/ directory, which may or may not be available or even writeable.

If WebLord cannot find the file in these places, it will create a new copy in the current working directory, but will also attempt to work "backwards" through the list above until it succeeds or finally fails.

Example: PAGESIGDB page-sig.db

See also: force, noupdate


noupdate

This tells WebLord not to actually enter new or changed page signatures into the Page Signature Database. The database is still used, of course, to determine whether or not a page has actually changed. Is ignored when using force

See also: force, pagesigdb


preexec

Enables the evaluation and execution of pre-exec commands for all pages.

Note: In versions before 2.0, WebLord always executed these commands unless a 'noexec' command was given; beginning with 2.0, you must explicitly enable, rather than disable, this command.

See also: postexec


postexec

Enables the evaluation and execution of post-exec commands for all pages.

Note: In versions before 2.0, WebLord always executed these commands unless a 'noexec' command was given; beginning with 2.0, you must explicitly enable, rather than disable, this command.

See also: preexec


cgi

Asks WebLord to scan and process a certain set of Environment Variable relating to CGI (Common Gateway Interface) operations on web (http) servers. Such operations come into play when a form submission is processed by a so-called CGI-program. WebLord can act as such a CGI-program when run with the 'cgi' argument.

The 'cgi' argument accepts any of the following three values:

get
WebLord will process only GET operations.
post
WebLord will process only POST operations.
getpost or postget
WebLord will process both GET and POST operation simultaneously, merging the submission of both or either. This is the most flexible mode.

The following properties are made available in the site object, based on a variety of factors, such as environment variables and POST input on the stdin (standard input) stream:

cgi-query-string
The contents of the QUERY_STRING variable, the original query of a GET operation as available after the '?' symbol on the URL.
cgi-content-length
The length of the total contents provided by a POST operation.
cgivar-...
All key=value pairs are encoded as cgivar-key=value, regardless if provided through a GET or a POST operation.
cgi-server_software
The contents of the SERVER_SOFTWARE variable
cgi-server-name
The contents of the SERVER_NAME variable
cgi-gateway-interface
The contents of the GATEWAY_INTERFACE variable
cgi-server-protocol
The contents of the SERVER_PROTOCOL variable
cgi-server-port
The contents of the SERVER_PORT variable
cgi-request-method
The contents of the REQUEST_METHOD variable
cgi-http-accept
The contents of the HTTP_ACCEPT variable
cgi-path-info
The contents of the PATH_INFO variable
cgi-path-translated
The contents of the PATH_TRANSLATED variable
cgi-script-name
The contents of the SCRIPT_NAME variable
cgi-remote-host
The contents of the REMOTE_HOST variable
cgi-remote-addr
The contents of the REMOTE_ADDR variable
cgi-remote-user
The contents of the REMOTE_USER variable
cgi-auth-type
The contents of the AUTH_TYPE variable
cgi-content-type
The contents of the CONTENT_TYPE variable

The CGI argument is not necessary if the environment variables tt>GATEWAY_INTERFACE begins with the string CGI/ and/or if REQUEST_METHOD has a value of either GET or POST. When only GATEWAY_INTERFACE is available then both POST and GET parameters will be made available within WebLord.

Note to system administrators who install WebLord as a general purpose CGI tool:

WebLord has the ability to construct, process, and execute arbitrary command lines. It is decidedly unsafe to permit arbitrary users access to the system in this manner, unless WebLord is made to execute in the user's own context, rather than root or some other privileged account. WebLord will also not run as suid/guid for obvious reasons.


listpages

Rather than processing the pages, WebLord will instead list all defined pages in the site definition. You can use this to determine the names of Page Object objects for use with the page argument.


stats

WebLord will provide some timing statistics after it has completed processing.


quiet

Suppresses the output of general notes. WebLord will give very little feedback in this case. The 'QUIET' argument will not affect the listpages and the stats arguments.


nowarnings

Suppresses the output of warnings, usually generated by minor syntactical problems that you should make an effort to fix.


noerrors

Suppresses the output of errors. This is strongly discouraged as errors are usually the severest indicator of problem.

As soon as a page with errors finishes processing WebLord will stop all further processing and terminates.


debug

Allows (internal) debugging messages into the output. Although these are primarily meant to shed light on internal processing events, you may derive some value from these when something is not working the way you expected it to. No attempt will be made to explain these messages.


outonerrors

Output of pages is ordinarily suppressed when an error has occurred. The use of this argument tells WebLord to write out a page even if it has produced errors. You should be extremely careful with this argument, especially if you have also used the noerrors argument, as you will then have no way of knowing if a page is anywhere near complete or correct!



This material is Copyright © 1997,1998,1999,2000,2001 RingLord Technologies and Udo Schuermann. All rights reserved. The latest versions of the WebLord software and (this) documentation can be obtained from the WebLord Home Page (the link will only function if you are connected to the internet.)