As the amount of documents you are processing grows, so does the amount of work required to maintain the whole bunch of your (wannabe-)information. To reduce waste of time for stupid project management tasks, hsc is able to maintain a project file and to utilize some additional tools.
If you did not, there is quite some work in front of you. For details about the aforementioned things, you can refer to the chapters listed below, but this is not meant to be an idiot-proof tutorial to make.
hscpitt newThis will create an empty project in the current directory with no documents in it. To see which documents are part of your project, you can use
hscpitt listor, if you do not want to see the header displayed:
hscpitt quiet list
All these commands will use a default name, ``
the project-file. If you want to use a different name, you can use the
PRJFILE, for example:
hscpitt prjfile=sepp.project newBut note that then you will have to specify this option every time you invoke hscpitt or hscdepp.
To make hsc keep the project-file up-to-date, you have to use the
For example,you can invoke hsc using
hsc FROM=sepp.hsc TO=html:sepp-pages/ PRJFILE=hsc.project
hscpitt add html:sepp-pages/sepp.html sepp.hscwill add the same document and main source file as before to the project. This can be handy if you have a big and fat pattern rule with many options that will take care of invoking hsc after a new dependency has been added to the Makefile. This relieves you from typing in a long sequence of command line options.
Nevertheless hscpitt leaves the Makefile untouched. Actually you do not need a Makefile at all to use hscpitt - it only stores information in project-file.
So if you invoke make right after hscpitt, nothing will have changed. To translate the contents of the project-file into a list of dependencies, you will have to use hscdepp. This tool simply creates a dependency line for every document it finds in the project-file, and stores this information in a Makefile.For example, after the call to hscpitt done before, hscdepp will create the dependency
html:sepp-pages/sepp.html : sepp.hscOr, if you would have used relative paths on a NeXTStep system like
hscpitt add ../../sepp-pages/sepp.html sepp.hscthe dependency would look like:
../../sepp-pages/sepp.html : sepp.hscHowever, hscdepp does not care about the rules and options for hsc you use in the Makefile. It only takes care of the dependencies, and everything else is up to you.
Therefore, every time something changed in the project-file, it is left to the user to invoke hscdepp and also reflect these changes in the Makefile.In general, it is a good idea to call hscdepp...
Of course sometimes it can be convenient not to call hscdepp, for example when you add multiple documents by calling hscpitt several times, without invoking hsc or make meanwhile. Nevertheless, invoking hscdepp too often should not cause any harm.
The usage of the project-file also improves the functionality of
hsc. Now it even can remember which IDs for link targets inside a
document have been defined (for example using HTML code like
<a HREF="#unknown">but also
<a HREF="existing.html#unknown">with in both cases the ID ``
unknown'' not being defined within the document, but the document existing.html being in place.
Until all documents have been added to the project (either by hsc or hscpitt), message #51 ("no entry for document .. to check id") might show up some times. This can be ignored.
Until all documents have been processed by hsc with a
PRJFILE set at least once (not only been added by
hscpitt) to the project-file), there will also be some occurrences
of message #74 ("unknown id") you can ignore. This is because
even if the IDs are actually defined in the document, hsc does not
yet know about them because it did not store them in the project-file,
It should be emphasized that all of the above tools and concepts are optional to hsc. You do not have to use hscdepp to maintain your dependencies, but can also do manually, without any pattern rules in the Makefile.
You even do not have to use make, but a different tool for project management. Although then you will have too find a substitute for hscdepp, if you still want to maintain the dependencies automatically. Maybe hscpaltrow can help you with this.
Of course you can use hsc without a project-file at all, and for example use a simple Shell- or Rexx-script to convert all your documents, if there are only few of them.
Maybe you will also have to change the variables
to point to the hsc-executable and
DESTDIR to contain the
name of the parent directory, which differs from system to system. Use
/'' for AmigaOS or ``
../'' for most other systems.