# Project Management

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.

## Overview

There are several tools and concepts involved in project management. Within the next paragraphs, the basic ideas will be roughly described. If you already worked with a command line based compiler environment and know how Makefiles and a dependency creator work, there should not be many new things.

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`.

- Project Files - where `hsc` stores the required information.
- `hscpitt` - `hsc`'s project interfering and trashing tool
- `make` - a general purpose tool for project management
- Makefiles - how to adept them for `hsc`
- `hscdepp` - `hsc`'s dependency procreator
- `hscpaltrow` - utilizing the output of `hscpitt`.

## Creating A New Project

The first step is to create a project-file. This can simply be done by

    hscpitt new

This 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 list

or, if you do not want to see the header displayed:

    hscpitt quiet list

All these commands will use a default name, ```hsc.project`'' for the project-file. If you want to use a different name, you can use the commandline option `PRJFILE`, for example:

    hscpitt prjfile=sepp.project new

But note that then you will have to specify this option every time you invoke `hscpitt` or `hscdepp`.

## Adding New Documents To The Project

There are two ways to add a document to the project: the first is `hsc`, because is will automatically add or update document entries in the project-file after it successfully wrote a document to the storage.

To make `hsc` keep the project-file up-to-date, you have to use the commandline option `PRJFILE=projec_file`. For example,you can invoke `hsc` using

    hsc FROM=sepp.hsc TO=html:sepp-pages/ PRJFILE=hsc.project

## Maintaining The Makefile

Another possibility for adding documents is `hscpitt`. For example:

    hscpitt add html:sepp-pages/sepp.html sepp.hsc

will 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.hsc

Or, if you would have used relative paths on a NeXTStep system like

    hscpitt add ../../sepp-pages/sepp.html sepp.hsc

the dependency would look like:

    ../../sepp-pages/sepp.html : sepp.hsc

However, `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.

## When To Call Hscdepp

As you just learned, `hsc` and `hscpitt` are completely independent from `make`, and `hscdepp` only provides an optional link between them. In other words: `hsc` does not care if it is invoked from a Makefile or not. And `make` does not care about the project-file, but only about its own Makefile.

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`...

- after adding a new document using `hscpitt` or `hsc`
- after successfully processing new a document with `hsc` the first time after adding it with `hscpitt`, because then it not only depends on its main source, but also on the files included during processing.
- after changing the include files of your pattern rule in the Makefile
- once in a while.

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.

## Checking IDs

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 NAME="id">`).

Now `hsc` will not only whine about 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, too.

## Alternative Approaches

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.

## Example Projects

There are some example project included, with most of them consisting of only a few sample documents. To try them out, open a Shell and change into the corresponding directory with the Makefile. View the README if there are some preparations needed.

Maybe you will also have to change the variables `HSC` 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.

Fetzenschädl
  This project is located in examples/fetzenschaedl/. There you will also find a README and a Makefile. Both HTML document and hsc-source will be located in the same directory, which makes maintenence easier, but has several obstacles shortly discussed there. It uses a Makefile, but no project-file, so only `hsc` and `make` are required to try is out.
Simple
  This project is located in examples/simple/. There you will also find a README and a Makefile. These are the same documents as before, but now HTML objects will be located in a different directory you will have to create manually. Only a few changes to the Makefile are required to accomplish this.
Advanced
  This project is located in docs/source/ and contains the source code used to create this manual. See docs-source/README. The Makefile used for this utilizes `hscdepp` and contains a pattern rule to also validate the created document with an external HTML checker.