<$define Version:string="0.917"> <$define pre-release:string="0"> <$define release-date:string="21-Sep-1998"> <$define DESCRIPTION:string=("This is the documentation to hsc, a " +"developer tool for html-projects. It acts as a preprocessor " +"and supports macros, expressions, conditionals, include files, " +" replaces special characters, performs a structure check, tests " +" existence of local links and several other things." +" Optionally it can keep track of documents being processed and" +" maintain the dependencies between them, making it relatively" +" easy to integrate it into existing developer environments." )> Hsc - Manual <* * Some day this might work, but currently the Postscript manual * is compressed with lha, therefor it is not "printable", and * so this LINK is still omitted * *> <* pseudo-navigation-bar *>

<*************************************************************************** * * Contents of header * * This includes: * - silly quote * - headings * - version information * **************************************************************************>

Don't believe the hype
Take a look at the small print
Ignore the bold type
(Carter U.S.M, "Do Re Me, So Far So Good")

<* heading *>

Hsc

<* version info *>

(Version <(Version)> <$if cond=(pre-release<>"0")> (pre-release#<(pre-release)>) <$stripws type="both"> , <(release-date)>)

[A.E.I.O.U.] Es gibt keine deutschsprachige Dokumentation.

Preface

About The Program

<(DESCRIPTION)>

A current version of this program and manual should always be available from <(HSC.ANCHOR)>, both as hypertext (html) and printabel (Postscript) document.

<*************************************************************************** * * Contents of Postscript-version * **************************************************************************>

The version of the program described herein is version <(version)>, released <(release-date)>.

About This Manual

This manual was generated from the online documentation, however there are a few minor differences:

This first chapter looks totally different.
There is no tool-bar for navigation, as this apparently does not make sense in a printed document.
The table of contents is at the end of the manual - not because I think that is very smart, but because the conversion is easier for me that way. But as these pages are numbered using Roman digits, you can easily grab them and put them to the beginning of the manual without getting confused.
Several plain text files, like CHANGES, NEWS, but also some example scripts in , are not part of this manual, but can be viewed in the hypertext version by means of links.
Instead of images, you will only see their ALT-text. (Maybe I get this EPS-stuff to work some day, but do not count on it.)

As this is the first release with a printable manual, it might contain some quirks, where a specific rendering or a certain phrase does not make sense. Although I tried to avoid this of course - at least there should not be any shitty Click here!. If you feel like, you might considers these to be bugs and report them (with page number, please). Hopefully no whole chapters are missing.

To those who are now going to mock "And it took you more than two years to convert the manual to Postscript?" (the first public release of was in October 1995) I'd like to say: No, but it took more than two years for somebody to provide an at least rudimentarily bearable application to do this. See the chapter about Use-Cases for details.

(Can you imagine a w3-browser, where you can push Print all, and it automatically analyzes the document for stuff like LINK REL="next" HREF=.., gets all related documents and prints them in correct sequence? Can you imagine getting rid of these crappy html2insert-your-favourite-print-format-here converters? Even if you can, the browser developers can't. At least not in 1998, several years after this html-and-w3-disaster was initiated.)

Furthermore I have to admit that I never really read this flavour of the manual myself. Partially, because Ghostscript for Amiga has a painful user interface, therfore I just gave a glimpse to a few randomly selected pages.

Partially because I am a dedicated Postscript hater, as you can not do much with files in this format: you can not in search it, you can not quickly display it, you can not link around in it and you can hardly convert it to something more reasonable. - "Hey, you can convert it to PDF or DVI!" - Yeah, great! That changes everything.

And finally, because you will have to reprint most of it after the next release and throw away all the paper. - "Who cares, I printed it for free at my university!" - Oh really, and who pays back the tree they had to cut?

(Note for Americans: paper usually is made from trees. - "Can't be, in my town we have a so called paper factory!" - Oh, sorry for confusing you. Forget what I said.)

So this is dedicated to those who prefer to waste paper instead of bandwidth or disk storage,

<$let hsc.format.time="%B %Y"> Thomas Aglassinger
Oulu, <(gettime())>

<*************************************************************************** * * Contents of html-version * **************************************************************************>

About The Program

Introduction - What's this all about?
Copyright And Disclaimer - not-my-fault, Freeware, source included
Author - how to contact me
Changes And News - what's new with this release
Updates - where to find them

Before You Begin

Requirements - what to own and know
Archive Contents - things coming along
Installation - where to put the whole damn thing

Usage

Invoking - options, switches, exit code
Example Usage - how it is supposed to work
File Arguments - specifying input and output
Messages - shit happens
Environment Variables - save the nature

Features

Special Tags - make life a bit easier
Check Existence of local URIs to avoid dangling links
Project Relative URIs - avoid paths like "../../../image/back.gif"
Replace Special Characters by their entities
Get Size of images and set attributes WIDTH and HEIGHT
Special Attributes - access various information
Strip Specific Elements - comments, redundant linefeeds and white-spaces, unneeded tags, tags with external references
Structure And Syntax Check to avoid surprises with different browsers

Advanced Topics

Attribute Assignments
Expressions - there's more to life than strings
Macros - create your own shortcuts and templates.
Conditionals - what if..?
Syntax Definition - what to do if html version 17.3 is out
Execute Shell Commands - poor man's pseudo-CGI
Project Management - I'll
ya
- Project Files - where stores information about a project
- - project interfering and trashing tool
- make - a general purpose tool for project management
- Makefiles - how to adopt them for
- - dependency procreator
- - a Rexx-script utilizing
Some Use-Cases - hints how to do certain things

Miscellaneous

Questions - and maybe some answers..
Source Code - compiling it
Existing Ports - Amiga rulez? Not really.
Other html-Extensions - pre²protranscessingpost
Known Bugs, Problems and Limitations - don't whizz on the electric fence
Future? - No future!
Related stuff - tools and further information

<$let hsc.format.time="%d-%b-%Y">

Thomas Aglassinger (agi@giga.or.at), <(gettime())>