/usr/share/doc/hsc/docs/usecases.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>hsc - Some Use-Cases</title>
<link rev="owns" title="Thomas Aglassinger" href="mailto:agi@giga.or.at">
<link rel="Next" href="questions.html">
<link rel="Copyright" href="copy.html">
<link rel="Previous" href="project/hscpaltrow.html">
<meta name="ROBOTS" content="NOINDEX, NOFOLLOW">
</head>
<body>
<a href="index.html"><img src="image/main.png" alt="Contents" align="middle" width="70" height="16"></a>
<img src="image/noindex.png" alt="-----" align="middle" width="70" height="16">
<a href="copy.html"><img src="image/copy.png" alt="Copyright" align="middle" width="70" height="16"></a>
<a href="index.html"><img src="image/back.png" alt="Up" align="middle" width="70" height="16"></a>
<a href="project/hscpaltrow.html"><img src="image/prev.png" alt="Previous" align="middle" width="70" height="16"></a>
<a href="questions.html"><img src="image/next.png" alt="Next" align="middle" width="70" height="16"></a>
<hr>
<h1>Some Use-Cases</h1>
This chapter gives some hints how you can do certain things you might
be interested in. It is probably only interesting for experienced
users.
<h2>Multi-lingual Documents</h2>
This will shortly outline how to create multiple versions of one
source file, for example to support more than one language. For
example, you want to have a document with a picture being the same in
all flavours, but a text depending on the language. Maybe you have a
source file <i>hugo.hsc</i> with the interesting part looking
like

<pre>
&lt;img src="hugo.gif" alt="hugo&gt;
&lt;english&gt;This is Hugo.&lt;/english&gt;
&lt;suomi&gt;T&auml;m&auml; on Hugo.&lt;/suomi&gt;
</pre>
and as result, you want two documents: an English one

<pre>
&lt;img src="hugo.gif" alt="hugo&gt;
This is Hugo.
</pre>
and a Finnish one

<pre>
&lt;img src="hugo.gif" alt="hugo&gt;
T&auml;m&auml; on Hugo.
</pre>
This can easily be achieved by defined two macro sets, one
being stored as <i>english.hsc</i>

<pre>
&lt;$macro english /close&gt;&lt;$content&gt;&lt;/$english&gt;
&lt;$macro suomi /close&gt;&lt;/$suomi&gt;
</pre>
and another one stored as <i>suomi.hsc</i>

<pre>
&lt;$macro english /close&gt;&lt;/$english&gt;
&lt;$macro suomi /close&gt;&lt;$content&gt;&lt;/$suomi&gt;
</pre>
<p>The first one defines two container macros, with <code>&lt;english&gt;</code>
simply every time inserting the whole content passed to it, and
<code>&lt;suomi&gt;</code> always removing any content enclosed in it.</p>
If you now invoke <kbd>hsc</kbd> with a call like

<pre>hsc english.hsc hugo.hsc to en-hugo.html</pre>
it will look like the first output document described above. To gain
a result looking like the second one, you only have to use

<pre>hsc suomi.hsc hugo.hsc to fi-hugo.html</pre>
<p>This is simply because the macros declared in
<i>suomi.hsc</i> work just the other way round like those in
<i>english.hsc</i>: everything enclosed in <code>&lt;english&gt;</code> will
be ignored, and everything being part of <code>&lt;suomi&gt;</code> remains.</p>
Of course you can have multiple occurrences of both macros, and of
course you can define similar macros for other languages.
<h2>Extended Character Encodings</h2>
<p>This version of <kbd>hsc</kbd> officially only supports Latin-1 as input
character set. The exact definition of that is a bit messy, but
basically it refers to most of those 255 characters you can input on
your keyboard.</p>
<p>For this character set, all functions described herein should work,
especially the CLI-option <a href="options.html#rplcent"><kbd>RplcEnt</kbd></a>.</p>
<p>Although Latin-1 is widely used within most decadent western
countries, it does not provide all characters some people might need.
For instance those from China and Japan, as their writing systems work
completely different.</p>
<p>As the trivial idea if Latin was to use 8 bit instead of the rotten
7 bit of ASCII (note that the ``A'' in ASCII, stands for
American), the trivial idea of popular encodings like JIS, Shift-JIS or
EUC is to use 8 to 24 bit to encode one character.</p>
<p>Now what does <kbd>hsc</kbd> say if you feed such a document to it?</p>
<p>Unless you do not specify <kbd>RPLCENT</kbd>, it should work
without much bothering about it. However, you will need a w3-browser
that also can display these encodings, and some fiddling with
<code>&lt;META&gt;</code> and related tags.</p>
<p>If you think you are funny and enable <kbd>RPLCENT</kbd>, <kbd>hsc</kbd>
will still not mind your input. But with great pleasure it will cut
all your nice multi-byte characters into decadent western 8-bit
``cripplets'' (note the pun). And your browser will display loads
of funny western characters - but not a single funny Japanese one.</p>
<p>Recently an old western approach to these encodings problems has
gained popularity: Unicode - that's the name of the beast - was
created as some waste product of the Taligent project around 1988 or
so, as far as I recall.</p>
<p>Initially created as an unpopular gadget not supported by anything,
it is now in everybody's mouth, because Java, the language-of-hype,
several MS-DOS based operating systems and now - finally - the rotten
hypertext language-of-hype support it. At least to some limited
extent. (Technical note: Usually you only read of UCS-2 instead of
UCS-4 in all those specifications, and maybe some blurred proposals to
use UTF-16 later.)</p>
<p>As <kbd>hsc</kbd> is written in the rotten C-language (an American product,
by the way), it can not cope with zero-bytes in its input data, and
therefore is unable to read data encoded in UCS-4, UTF-16 or (w&uuml;rg,
kotz, reiha) UCS-2; it simply will stop after the first zero in the
input.</p>
<p>Because the rotten C-language is so widely used, there are some
zero-byte work-around formats for Unicode, most remarkably UTF-8 and
UTF-7. These work together with <kbd>hsc</kbd>, although with the same
limitations you have to care for when using the eastern encodings
mentioned earlier. Read: Don't use CLI option
<code>RplcEnt</code>.</p>
<p>Note that it needs at least five encodings to make Unicode work
with most software - again in alphabetical order: UCS-2, UCS-4,
UTF-16, UTF-7 and UTF-8. I wonder what the ``Uni'' stands for...</p>
Anyway, as conclusion: you can use several extended character sets,
but you must not enable <kbd>RPLCENT</kbd>.
<h2>Html 4.0</h2>
<p>Once upon a time, HTML-4.0 was released, and it sucked surprisingly
less (as far as ``sucks less'' is applicable at all to HTML). Of course
there still is no browser capable of displaying all these things,
but nevertheless you can use <kbd>hsc</kbd> to author for it - with some
limitations. This will shortly outline how.</p>
<p>As already mentioned, HTML now supports those extended character
encodings. See above how to deal with input files using such an
encoding, and which to avoid.</p>
<p>If your system does not allow you to input funny characters (for
instance one can easily spend ATS 500.000 on a Workstation just for
being absolutely unable to enter a simple ``&auml;''), you can use
numeric entities, both in their decimal or hexadecimal representation:
for example, to insert a Greek Alpha, you can use
<code>&amp;#913</code> or <code>&amp;#x391</code>, <kbd>hsc</kbd> will accept
both. However, you still can not define entities beyond 8-bit range
using <a href="features/prefs.html#defent"><code>&lt;$defent&gt;</code></a>.</p>
<p>Some highlights are that the <code>ALT</code> attribute of <code>&lt;IMG&gt;</code>
is no required and that there are now loads of ``URIs'' instead of
``URLs'' around. Nothing new for old <kbd>hsc</kbd>-users... he he he.</p>
<p>Another interesting thing is that the DTD now contains some
meta-information that was not part of earlier DTDs so it maybe can
make sense to use the DTD as a base for a <i>hsc.prefs</i> converter.</p>
<h2>XHTML</h2>
<p>2002 update: seems the W3 committee has learned a thing or two. XHTML has
been out for a while now, and they are working on the 2.0 specification. While
the chances of turning the official DTD into an HSC prefs file using a dumb
ARexx script have gotten even slimmer (anyone for a real parser using Expat or
something?), XHTML seems a move in the right direction, regarding the
separation of content and presentation and putting an end to the ``tag
soup'' that much of the Web is today. It remains to be seen how successful
it will be. HSC now has some rudimentary support for authoring XHTML documents,
mainly regarding lowercase tag and attribute names and the new empty-tag syntax
with a trailing slash, as in ``<code>&lt;br /&gt;</code>''. CSS support should be
better though, perhaps some automatic rewriting of obsolete presentation
attributes to CSS <code>&lt;style&gt;</code> tags...</p>
<h2>Creating A Postscript Version</h2>
<p>As you can now optionally read this manual in a Postscript version,
there might be some interest how it was done.</p>
<p>The rudimentarily bearable application used for conversion is (very
originally) called <kbd>html2ps</kbd> and can be obtained from <a href="http://www.tdb.uu.se/~jan/html2ps.html">http://www.tdb.uu.se/~jan/html2ps.html</a>. As
common with such tools, ``it started out as a small hack'' and ``what
really needs to be done is a complete rewriting of the code", but "it
is quite unlikely that this [...] will take place''. The usual standard
disclaimer of every public Perl-script. All quotes taken from the
manual to <kbd>html2ps</kbd>.</p>
<p>Basically the HTML and the Postscript-version contain the same
words. However, there are still some differences, for example the
printed version does not need the toolbar for navigation provided at
the top of every HTML page.</p>
<p>Therefore, I wrote two macros, <code>&lt;html-only&gt;</code> and
<code>&lt;postscript-only&gt;</code>. The principle works exactly like the one
described for <code>&lt;english&gt;</code> and <code>&lt;suomi&gt;</code> earlier in this
chapter, and you can find them in <a href="../docs-source/inc/html.hsc"><i>docs-source/inc/html.hsc</i></a> and <a href="../docs-source/inc/ps.hsc"><i>docs-source/inc/ps.hsc</i></a>.</p>
<p>However, there is a small difference to the multi-lingual examples,
as I do not really want to create two versions all the time. Instead,
I prefer to create either a fully hypertext featured version or
a crippled Postscript-prepared HTML document in the same location.</p>
<p>You can inspect <a href="../docs-source/Makefile"><i>docs-source/Makefile</i></a> how this
is done: if <kbd>make</kbd> is invoked without any special options, the
hypertext version is created. But if you instead use <kbd>make
PS=1</kbd> and therefor define a symbol named <code>PS</code>, the
pattern rule responsible for creating the HTML documents acts
differently and produces a reduced, Postscript-prepared document
without toolbar.</p>
Basically, the rule looks like this:

<pre>
$(DESTDIR)%.html : %.hsc
ifdef PS
        @$(HSC) inc/ps.hsc   $(HSCFLAGS) $&lt;
else
        @$(HSC) inc/html.hsc $(HSCFLAGS) $&lt;
endif
</pre>
<p>Needless to say that the conditional in the <i>Makefile</i> does not
work with every <kbd>make</kbd> - I used <kbd>GNUmake</kbd> for that, your
<kbd>make</kbd>-tool maybe has a slightly different syntax.</p>
<p>For my convenience, there are two rules called <code>rebuild</code>
and <code>rebuild_ps</code> with their meanings being obvious: they
rebuild the whole manual in the desired flavour.</p>
<p>So after a successful <code>make rebuild_ps</code>, everything only
waits for <kbd>html2ps</kbd>. Maybe you want to have a look at the
<a href="../docs-source/html2ps.config"><i>docs-source/html2ps.config</i></a> used, although it is
strait forward and does not contain anything special. This should not
need any further comments, as there is a quite useful manual supplied
with it.</p>
<p>However, making <kbd>html2ps</kbd> work with an Amiga deserves some
remarks. As you might already have guessed, you will need the
Perl-archives of GG/ADE - no comments on that, everybody interested
should know what and where GG is.</p>
I suppose you can try the full Unix-alike approach with <kbd>hsc</kbd> compiled
for AmigaOS/ixemul and GG more or less taking over your machine, and
therefor directly invoke <kbd>perl</kbd>. This will require a rule
like

<pre>
ps :
        html2ps -W l -f html2ps.config -o ../../hsc.ps ../docs/index.html
</pre>
<p>As I am a dedicated hater of this, I used the AmigaOS-binary, a
SAS-compiled <kbd>GNUmake</kbd> and the standard CLI. A usually
quite successful way to make such things work is with the help of
<kbd>ksh</kbd>, which, for your confusion, is in a archive at GG
called something like <i>pdksh-xxx.tgz</i> (for ``Public
Domain ksh''). Invoking <kbd>ksh</kbd> with no arguments will
start a whole shell-session (w&uuml;rg!), but you can use the switch
<kbd>-c</kbd> to pass a single command to be executed. After that,
<kbd>ksh</kbd> will automatically exit, and you are back in your
cosy CLI, just as if nothing evil has had happened seconds before.</p>
<p>So finally the rule to convert all those HTML files into one
huge Postscript file on my machine is:

<pre>
ps :
        ksh -c "perl /bin/html2ps -W l -f html2ps.config -o ../../hsc.ps ../docs/index.html"
</pre>
<p>Note that <kbd>html2ps</kbd> is smart enough to follow those
(normally invisible) <code>&lt;LINK REL="next" ..&gt;</code> tags being part of
the HTML documents, so only the first file is provided as argument,
and it will automatically convert the other ones.</p>
<p>Well, it least you see it can be done.</p>
</body></html>
hsc 0.934-1ubuntu2 / usr / share / doc / hsc / docs / usecases.html
