<!-- -*-jfw-sgml-*- -->
<!doctype document public "-//JFW//DTD Document//EN"[
<!ENTITY sdc "sdc">
]>

<document
face="nidx 1c"
author="J&oe;rg Wittenberger"
inst="TU Dresden"
>Installation procedure

The installation is pretty straight forward, but if you have to install
something else first, it may take some time.

<enum>
<o>Make sure you have sgmls installed somewhere in you path.

<o>You need bigloo to compile the source (or change it to be useful
for another scheme system).  Thus probably better get bigloo.

<o>If you want to use Lout for the backend install it too.

<o>For EPS pictures in the LaTeX (prior to 2E) output you need
<code/epsfig.sty/.

<o>Then install the package itself.

</enum>

Installation of the package:

During the installation the following rules apply:

<list>
<o> No file is created by the (basic) installation process outside of
the base directory named DD (choosen in the toplevel Makefile).

<o> The runtime access to intalled files goes via the directory named
SR choosen in the toplevel Makefile.

<o> After installation the directory where the distribution was
untared may be removed.

<o> The documentation is installed from the DD directory and has it's
own custumizable target directories.
</list>

The installation process:

Unfortunatly there is always a problem. Some systems don't have a full
featured install other lack the -R switch on cp. There is a install
program in the install subdirectory of the distribution. Use it if
your's doesn't understand the -d switch. (This install also supports
an environment variable INSTALLFILE, which can point to a file where a
list of installed files is to be loged.)

<enum>
<o>Untar the distribution

<o>Edit the Makefile.  Usually all you have to set up is the base
directory (SR) or only the "prefix".

Set the variable <code/PARSEPROG/ to either "sgmls" or "nsgmls".
Do <em/not/ use a full path here!

Also decide whether to generate the LaTeX for the graphics package or
the epsfig substyle.  There is the variable <code/GRPHPKG/ for. Set
this to "grphcs" or to "epsfig".  I don't know if epsfig works with
LaTeX2e nor if graphics works with LaTeX 2.09. I recomented to use
epsfig with version 2.09 and graphics with 2e.

If you need, adapt the variables holding the make, cp and mkdir
program as well as the mkdir options used through the installation
process.

There is still some support for the and the variable <code/REMLOC/
left in. This is from the old version, may disappear some day and is
no longer full supported. You can choose either local or remote
(probably local). (The remote installation sets up a quite tricky
environment, where some of the used commands are accessed on a remote
host.)

<o>**Only** for bigloo version 1.7:

You need to change the source back to the old module language of
bigloo.

Within the module clauses (these is the first declaration within a
file) of the files
 <list>
 <o><code/typeset.scm/
 <o><code/files.scm/
 </list>
are comments like
<quote<verb>
;BEGIN BIGLOO1.x
; .....
;END BIGLOO1.x
</verb</quote>

Also further down within <code/typeset.scm/ there is a block
surounded with the same comments.
It's a work around a bug within bigloo1.7.

Find these lines, remove the semicolons commenting out the lines
between ";BEGIN BIGLOO1.7" and ";END BIGLOO1.7" respectivly comment
out those line only for version 1.8.

<o>Do "make all" to compile the executable and hardwire the installation
directory in some runtime files (have a coffee).

<o>Now the hand work part: got to include/layout.scm and set
latex-latex-type either to 'LATEX209 or to 'LATEX2E. (The default
setting is 'LATEX2E).

<o>Do a make install. This will copy the distribution and the
executable into the choosen DD directory and hardwire the SR name in
some of the files.

<o>Make a symlink from the executable (Named by <code/$(EXE)/ in the
toplevel Makefile, to be found in the <code/bin/ directory; default
name: &sdc;) to something anywhere in your path (like
<code>/usr/local/bin/&sdc;</code>). (I don't recomment to move or
copy the executable around cause updates and uninstall will be easier
this way.)

<o>Thats all you need, but it's better to set <code/DOCPATH/ to the
root of your personal document tree (see the typeset man page).

<o>To install the documentation do a "make installdoc". This will
install the documentation in the default places.

Because these places may be different in your system, you might want
to cd into the doc directory of the distribution.  Do a "make help" to
see what you can do.  Then edit the Makefile to reflect your system
and do a "make doc" to install the documentation. If you have trouble
with the local handling of the notations you'll get some warnings.

<o>The <code/include/ directory holds some files (i.e.,
<code/layout.scm/, <code/manpage.scm/ and <code/language.scm/) which
might to be custumized. See the comments and 
<code>doc/targets.sgml</code> or compile it into a format you like to
read.

<quote>
(e.g., &sdc; -O ps -o targets.ps targets.sgml)
</quote>

<o>There is a file <code>sgml/local.ent</code>. Change this to reflect
your system, if you need. Things like localy defined notations go
here. (Only for advanced users installation.)

<o>If your use emacs you might want to extend <code/compilation-
error-regexp-alist/ with a line:

<verb>
("SGML error at \\([, \t\n]+\\), line \\([0-9]+\\)" 1 2)
</verb>

to get the goto-next-error funtions and the like in compile mode
right.
Uhm, for nsgmls you need a different pattern.
But this should probably work out of the box.

I personally found the SGML-mode of emacs not suitable (these DTD's
require to few markup to make this mode resonalble and the text
formatting support was too limited for my taste).
Therefor I (and others) hacked a slight modification.
 <code>bin/mode.el</code> holds the code for a new
mode I like (especially for the folding properties).
(Please note that this mode reflects personal taste.)
It's far from perfect, especialy the highlighting is broken.
Unfortunatly the 19.31 update broke the code.
Users of older version might uncomment one line in the
keymap to get the closing angle work again.

<o>If you want to install automatic figure handling or some other
notations on your system, see <code>doc/notations.sgml</code> (which
is also the source for the some other files) to see whats going
on. Among the packages involved there are: ghostscript, xfig, tgif,
pnmtools, groff, latex and lout. But you are not forced to have them.

<o>If you want install bbset, a program to correct/insert correct
bounding boxes in EPS files, for use without &sdc;. It's installed
as a part of &sdc; (in it's private bin directory) but might be
useful for other things.

If you issue a "make instbbset" from the distribution directory you
get it installed in <code>$(prefix)/bin</code> and the manpage in 
<code>$prefix/man/man1</code>.

<o>See the file <code>doc/targets.text</code> for details about the
formating in the various target formats. For easy reading format it
into the type you like. E.g.,

<quote>
&sdc; -O latex -o targets.tex doc/targets.sgml
</quote>

Note, that you need to format the file <code>doc/target.sgml<code>
which includes the other <code>doc/target.text</code>.

</enum>

In the case you encounter any problems or find bugs, typos etc. please
mail me: Joerg.Wittenberger@inf.tu-dresden.de.