File Options

There are several CLI options that specify where hsc should take the input from and where the output should be placed. This section describes the differences and (dis-)advanteges.

Converting single files

This one uses a single file for input and output:

    hsc FROM hugo.hsc TO hugo.html

It will use hugo.hsc and outputs to hugo.html. Both input and output will be located in the current directory. This can be useful if you only want to quickly process a single file trough hsc, and do not want to set up a complete project.

Using different directories for input and output

One of the features of hsc is that your object can be located at a totally different place from the source. This enables you to place your sources at a different disk as the one the WebServer has access to, saving server space.

For instance, you can use

    hsc FROM hugo.hsc TO www:sepp/hugo.html

to use hugo.hsc, located in the current direcory, and create www:sepp/hugo.html. Note that all images, other documents etc. you reference fromout hugo.hsc using relative URIs have to be located at the corresponding place within the directory www:sepp/.

For example, if hugo.hsc contains a tag

    <IMG SRC="image/back.gif" ALT="back">

the image file back.gif will have to be located at www:sepp/image/back.gif.

Using a destination directory

The same as above can be performed using

     hsc FROM hugo.hsc TO www:sepp/

Note the trailing slash that tells hsc that it should now output to a directory and determine the filename by itself. Usually, it will use (input filenname, without ".hsc", but a ".html" appened), resulting into www:sepp/hugo.html as before. You can change this using the CLI option EXTENSION.

Using sub directories

For complex project, usually not all documents are located at the same directory. For example, hugo.hsc is no more placed in the current directory, but in people/hugo.hsc.

Invoking hsc like

    hsc FROM people/hugo.hsc TO www:sepp/

will now ouput to www:sepp/people/hugo.html. Note that you have to take care that the directory www:sepp/people/ exists, hsc will not create any new directories by itself.

If you now want to embed an image located at www:sepp/image/back.gif, you have to use

    <IMG SRC="../image/back.gif" ALT="back">

Alternatively, you can use and absolute URI:

    <IMG SRC=":image/back.gif" ALT="hugo">

Another way to obtain the same result is using

    hsc FROM people/hugo.hsc TO www:sepp/people/hugo.html

In this case, hsc is smart enough to figure out that the destination directory is www:sepp/, and you are using people/ as subdirectory.

But if you try to use

    hsc FROM people/hugo.hsc TO www:sepp/stuff/hugo.html

hsc can not figure out what to use as destination- or subdirectory, and will show up an error message:

    unmatched corresponding relative directories:
      input  `people/'
      output `stuff/'

In this case, you will have to rename your directories.

Using pipes

Short: It is possible to use pipes with hsc, but it should be avoided in most cases; hsc isn't really ``pipable´´. It does not continuously read data from the input and write parts of the output.

(Technical note:It reads the whole input file with a single call to fread(), creates the output in memory and writes it with (more or less) a single fwrite(). The main reasons why it works this way are: I hate to check for I/O errors, fungetc() usually does not work after a linefeed and memory mapped files are not supported by the standard ANSI library.)

Additionally, it impossible for hsc to maintain a project file without knowledge of the filenames for document and source, so several features will be disabled.

If hsc needs to access relative URIs, it will have to use the current directory as starting point.

Therefor, pipes should only be used if you quickly want to test a feature on a single file or something like that.

Anyway, here is an example:

    hsc STDIN

This specifies the (case sensitive) pseudo-filename STDIN as input, which will use stdin. Missing a TO option, the output will be written to stdout. Now using this like

    hsc STDIN <hugo.hsc >hugo.html

would be equal to

    hsc hugo.hsc TO hugo.html

Again: Try to avoid this.

Thomas Aglassinger (agi@giga.or.at), 04-Dec-1996