Welcome Boyz and Girls to the Non-Official Shit-Reduction Program
(Novi Sad, "Me, Myself, All Over Again")

# Introduction

The main purpose of this chapter is to help you deciding whether you should go on reading this documentation or not.

## Motivation

If you read this, it's quite likely that you tried to design an HTML page. And you probably found out that HTML is a very clumsy thing: No macros, no include files and several other features lacking.

And what can you do after your page is ready? View it with a browser and test-click all links? Pfuahahaha! Most browsers are designed to handle as many errors as possible and display a readable page, but don't mention your errors! And link-testing is a very stupid task...

Of course, there are several tools around: You can use a macro languages like `m4` to define macros and include files, use some of the various HTML validators, replace your special characters with `recode` and run a link validation tool on your page.

So, after installing several tools, compilers and interpreters, you are ready to go—and have to start five programs after a simple change to one of your pages.

## What It Is

`Hsc` tries to summarize the functionality of all these tools in one program: it performs a (basic) syntax check, validates your links, replaces special characters with entities and provides a way to define macros which resembles HTML.

It also supports several features you probably will not find in most other tools, like project relative URIs, stripping useless whitespace and automatically setting the attributes for images size.

Furthermore it provides some concepts to maintain your project with popular tools like `make`.

## How It Works

`Hsc` simply acts as a preprocessor: You give it an ``extended'' HTML-source (later on referred to as ``hsc source'') containing special commands, and `hsc` interprets it and produces a pure HTML output as object file. This output file can be viewed with your browser.

Normally you will create your `hsc` sources using a simple text editor, maintain them in a Makefile and process them with `hsc`. At least I consider this the recommended way of using this tool.

## What It Is Not

Obviously, there is no fancy GUI, no (pseudo-)WYSIWYG, no drag&drop—there are other programs which provide these functionalities. But a common shortcoming of these programs usually is that they yield incredibly crappy HTML that will look halfway decent on at most one make of browser (i.e. IE), give less support for large projects and are limited in configurability.

If you just want to create your own personal homepage, write a short HTML document with information about your three freeware-proggies, include a picture of your cat, send greets to Sepp and Hugo or something like that, there are probably other tools which are easier to handle and will serve your needs more or less well.

It should also be stated that you will require various skills usually not needed for W3-authoring (or better: not expected to be needed by most people). This includes a basic understanding of macro creation, writing Makefiles and playing around with scripting languages like Rexx. If you have never done such things before, I recommend you forget this package soon and come back in a few years.

This also is no install-and-run package. You will need several other tools to fully use it, and it is not within the scope of this documentation which one you choose. However, it contains some comments and suggestions on that in various places.

Despite the general HTML- and W3-hype of the recent years, both this tool and its authors consider many concepts introduced with it ridiculous, braindead and sometimes even pure crap. So this manual contains opinions and language you might consider offensive. If you want to hear the usual ``Oh how great are all those things!'', you will have to look for something else.