File Options

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

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 w3-Server 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 directory, and create www:sepp/hugo.html. Note that all images, other documents etc. you reference from out 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.png" 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 filename, without ``.hsc'', but a ``.html'' appended), resulting into www:sepp/hugo.html as before. You can change the default extension using the commandline option Extension.

Using Subdirectories

For complex project, usually not all documents are located in 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 output 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 into this document, you have to use
<img SRC="../image/back.png" ALT="back">
Alternatively, you can use a Project Relative URI:
<img SRC=":image/back.png" ALT="back">
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 is 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:
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.