# Special Attributes

`Hsc` adds some special attributes, which can be quite useful to include special data or configure the parser.

- `Hsc.Anchor` - destination URI of last anchor
- `Hsc.Click-Here` - keywords for ``click here''-syndrome
- `Hsc.Color-Names` - values to be used as colors-names
- `Hsc.Content` - content text of current container macro
- `Hsc.Opts.XHTML` - defined if HSC was called in XHTML mode
- `Hsc.Opts.Entitystyle` - reflects the current entity rendering style
- `Hsc.Document.Name` - filename of HTML object
- `Hsc.Document.Path` - directory part of HTML object, relative to the document tree's root
- `Hsc.Document.URI` - full relative URI of HTML object
- `Hsc.DestPath` - relative path to the HTML object's destination directory
- `Hsc.Exec.Result` - return-code of command invoked by `<$exec>`
- `Hsc.LF` - a single linefeed-character
- `Hsc.Source.Name` - filename of hsc-source
- `Hsc.Source.Path` - directory part of hsc-source
- `Hsc.Source.File` - full path and filename of hsc-source
- `Hsc.System` - value depending on operating system
- `Hsc.Format.Filesize` - how to render `GetFileSize()`
- `Hsc.Format.Time` - how to render `GetTime()` and `GetGMTime()`
- `Hsc.TMP.*` - temporary attributes for internal use

## Attributes Containing Special Data

### Hsc.Anchor

This attribute is defined internally during startup and is maintained by `hsc`. It contains the URI of the last anchor referenced to.

Example:

    For updates, take a look at the
    <A HREF="http://www.linguistik.uni-erlangen.de/~msbethke/hsc/">hsc-support-page</A>
    at <STRONG><(HSC.ANCHOR)></STRONG>.

will be converted to:

> For updates, take a look at the hsc-support-page at http://www.linguistik.uni-erlangen.de/~msbethke/hsc/.

### Hsc.Content

This attribute is defined internally during startup and is maintained by `hsc`. It contains the the text which will be inserted if a `<$content>` shows up, and is updated at every call to a container macro.

### Hsc.Opts.XHMTL

This BOOL attribute is defined and set to TRUE (i.e. "1") whenever HSC was called with the XHTML commandline switch. It allows macros to check the current mode and adapt their code, for example with respect to doctypes or attributes used. Test it using

    <$if COND=(defined Hsc.Opts.XHMTL)>
    ... XHTML code ...
    <$else>
    ... old-style HTML code ...
    </$if>

### Hsc.Opts.Entitystyle

This is a STRING attribute, which is always defined and reflects the current entity rendering style, i.e. one of ``keep'', ``replace'', ``numeric'', ``symbolic'' or ``utf-8''. It is set by the ENTITYSTYLE and XHMTL options. The only use of this attribute will probably be in a macro for the automatic generation of an appropriate charset declaration.

### Hsc.Document.Name, Hsc.Document.Path, Hsc.Document.URI, Hsc.DestPath

These attributes are defined internally during startup and are read-only. They contain the filename, the directory, the whole relative URI of the HTML object to be created and the path from the current directory to the HTML object's destination, respectively.

For example,

        hsc FROM people/hugo.hsc TO html:my_project/

will lead to

attribute | value
--- | ---
Hsc.Document.Name | "hugo.html"
Hsc.Document.Path | "people/"
Hsc.Document.URI | "people/hugo.html"
Hsc.DestPath | html:my_project/people/

Note that `Hsc.Document.Path` does not contain the whole destination directory, but only the relative path. If you need the latter, use `Hsc.DestPath`.

### Hsc.Exec.Result

This attribute contains the return-code of the command invoked using `<$exec>`. It is updated after every call of this hsc-tag.

### Hsc.LF

This attribute contains a single linefeed-character (```\n`'') and can be used to include linefeeds into attribute-values without `hsc` whining about them.

### Hsc.Source.Name, Hsc.Source.Path, Hsc.Source.File

These attributes are defined internally during startup and are read-only. They contain the filename, the directory and the full path and filename of the hsc-source you have specified when invoking `hsc`.

For example,

    hsc FROM people/hugo.hsc TO html:my_project/

will lead to

attribute | value
--- | ---
Hsc.Source.Name | "hugo.hsc"
Hsc.Source.Path | "people/"
Hsc.Source.File | "people/hugo.hsc"

### Hsc.System

This attribute is defined internally during startup and is read-only. It contains a value depending on the operating system `hsc` is running on.

OS | `Hsc.System`
--- | ---
AmigaOS | AMIGA
RiscOS | RISCOS
BeOS | BEOS
NextStep | NEXTSTEP
Unixoid | UNIX

This can be useful if you are executing a shell-command during conversion. See `<$exec>` for an example how to include a listing of the current directory, working with more then only a specific OS.

### Hsc.TMP.*

For several tasks, `hsc` declares it's own temporary attributes for internal use. Most of them you can not use inside your own expressions. The only reason why I list them here is, that some of them might show up in messages.

For example, if you are using the special tag <(...)> (insert expression), `hsc` creates an attribute `Hsc.TMP.insert.expression` to assign the value of the expression you passed between the brackets. If this expression contains errors, you will achieve a message mentioning the attribute `Hsc.TMP.insert.expression`.

## Attributes for configuration

### Hsc.Color-Names

This attribute is defined in hsc.prefs and can be altered to the user's needs. However, it's value is scanned only once (immediately after processing hsc.prefs and later changes will not be recognised by `hsc`.

For attributes of type `COLOR`, you can not only use the cryptic `#rrggbb`-style, but also use some predefined values. With this attribute you can declare which values `hsc` should know about, each separated by a vertical bar (```|`'').

Example: <$define Hsc.Color-Names:string/c="aqua|black|blue|fuchsia|gray|green|lime|maroon|navy|olive|purple|red|silver|teal|white|yellow">

This one contains all values recommended for HTML-0.32 and is in the hsc.prefs that came with this distribution.

### Hsc.Click-Here

This attribute is defined in hsc.prefs and can be altered to the user's needs. However, it's value is only scanned once and later changes will not be recognised by `hsc`.

Inside an anchor tag (`<A HREF="...">`), the normal text is scanned for special keywords indicating a ``click here''-syndrome. With this attribute you can declare these keywords, each separated by a vertical bar (```|`''). Example:

    <$define Hsc.Click-Here:string/c="click|here">

When processing German documents, probably this one would fit better:

    <$define Hsc.Click-Here:string/c="klicken|hier">

### Hsc.Format.Filesize

This attribute contains a template that descibes how the result of `GetFileSize()` should be rendered. Conversion specifications:

        %b    is replaced by the filesize in bytes.
        %k    is replaced by the filesize in kilobytes.
        %m    is replaced by the filesize in megabytes.
        %g    is replaced by the filesize in gigabytes.
        %a    is replaced by the filesize, with a reasonable unit computed automatically
        %u    is replaced by the unit for %a

This attribute is defined internally during startup, and contains the value `"%a%u"`, leading to results like `"123K"` or `"12M"`. It can be changed by the user at any time.

### Hsc.Format.Time

This attribute contains a template that describes how the result of `GetTime()` and `GetGMTime()` should be rendered. Conversion specifications (Techn. Note: These are the same as for ANSI-C's `strftime()`):

        %A    is replaced by the full weekday name.
        %a    is replaced by the abbreviated weekday name, where the abbreviation
               is the first three characters.
        %B    is replaced by the full month name.
        %b or %h
               is replaced by the abbreviated month name, where the abbreviation
               is the first three characters.
        %C    is equivalent to ``%a %b %e %H:%M:%S %Y''
        %c    is equivalent to ``%m/%d/%y''.
        %D    is replaced by the date in the format ``mm/dd/yy''.
        %d    is replaced by the day of the month as a decimal number (01-31).
        %e    is replaced by the day of month as a decimal number (1-31); single
               digits are preceded by a blank.
        %H    is replaced by the hour (24-hour clock) as a decimal number
               (00-23).
        %I    is replaced by the hour (12-hour clock) as a decimal number
               (01-12).
        %j    is replaced by the day of the year as a decimal number (001-366).
        %k    is replaced by the hour (24-hour clock) as a decimal number (0-23);
               single digits are preceded by a blank.
        %l    is replaced by the hour (12-hour clock) as a decimal number (1-12);
               single digits are preceded by a blank.
        %M    is replaced by the minute as a decimal number (00-59).
        %m    is replaced by the month as a decimal number (01-12).
        %n    is replaced by a newline.
        %p    is replaced by either ``AM'' or ``PM'' as appropriate.
        %R    is equivalent to ``%H:%M''
        %r    is equivalent to ``%I:%M:%S %p''.
        %t    is replaced by a tab.
        %S    is replaced by the second as a decimal number (00-60).
        %s    is replaced by the number of seconds since the Epoch, UCT.
        %T or %X
               is equivalent to ``%H:%M:%S''.
        %U    is replaced by the week number of the year (Sunday as the first day
               of the week) as a decimal number (00-53).
        %W    is replaced by the week number of the year (Monday as the first day
               of the week) as a decimal number (00-53).
        %w    is replaced by the weekday (Sunday as the first day of the week) as
               a decimal number (0-6).
        %x    is equivalent to ``%m/%d/%y %H:%M:%S''.
        %Y    is replaced by the year with century as a decimal number.
        %y    is replaced by the year without century as a decimal number
               (00-99).
        %Z    is replaced by the time zone name.
        %%    is replaced by ``%''.

This attribute is defined internally during startup, and contains the value ```%d-%b-%Y, %H:%M`'', leading to results like `"04-Apr-2018, 08:26`".