# 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:

    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.