@c instlrun.texi
   
@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004 Laurence D. Finston 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.

@c $Id: instlrun.texi,v 1.6 2004/01/12 18:39:06 lfinsto1 Exp lfinsto1 $


@node Installing and Running 3DLDF, Typedefs and Utility Structures, Intersections, Top
@chapter Installing and Running 3DLDF

@menu
* Installing 3DLDF::            
* Running 3DLDF::               
@end menu

@node Installing 3DLDF, Running 3DLDF, Installing and Running 3DLDF, Installing and Running 3DLDF
@section Installing 3DLDF

3DLDF is available for downloading from
@uref{http://ftp.gnu.org/gnu/3dldf}.
The official 3DLDF website is 
@uref{http://www.gnu.org/software/3dldf}.
The ``tarball'', i.e., the compressed archive file
@file{3DLDF-@value{VERSION}.tar.gz} unpacks into a directory called
@file{/3DLDF-@value{VERSION}/}.

On a typical Unix-like system, entering the following commands
at the command line in a shell will unpack the 3DLDF distribution.
Please note that the form of the commands may differ on your system.

@example
gunzip 3DLDF-@value{VERSION}.tar.gz
tar xpvf 3DLDF-@value{VERSION}.tar
@end example

The @samp{p} option to @command{tar} ensures that the files will have
the same permissions as when they were packed.

The directory @file{3DLDF-@value{VERSION}/} contains a
@command{configure} script, which should 
be called from the command line in the shell, using the absolute path of
@file{3DLDF-@value{VERSION}/} as the prefix argument.  For example, if
the path is @file{/usr/local/mydir/3DLDF-@value{VERSION}/},
@command{configure} should be invoked as follows:

@example
cd 3DLDF-@value{VERSION}
configure --prefix=/usr/local/mydir/3DLDF-@value{VERSION}/
@end example

@command{configure} generates a @file{Makefile} 
from the @file{Makefile.in} in @file{3DLDF-@value{VERSION}/}, and
in each of the subdirectories @file{3DLDF-@value{VERSION}/CWEB},
@file{3DLDF-@value{VERSION}/DOC}, 
and @file{3DLDF-@value{VERSION}/DOC/TEXINFO}.   
Now, @command{make install} causes the 3DLDF to be built.
The executable is called @file{3dldf}.

See the files @file{README} and @file{INSTALL} in the 3DLDF distribution
for more information.

@menu
* Template Functions::          
@end menu

@node Template Functions,  , Installing 3DLDF, Installing 3DLDF
@subsection Template Functions

@cindex templates
@cindex template functions 
@cindex function templates 
@c
3DLDF 1.1.5 is the first release that contains @dfn{template functions},
namely 
@code{template <class C> C* create_new()}, which is defined in 
@file{creatnew.web}, and 
@code{template <class Real> Real get_second_largest()}, which is defined
in @code{gsltmplt.web}.
@xref{Dynamic Allocation of Shapes}, and 
@ref{Get Second Largest Real}.

In order for template functions to be instantiated correctly, their
@emph{definitions} must be available in each compilation unit where
specializations are declared or used.  For non-template functions, it
suffices for their @emph{declarations} to be available, and their
definitions are found at link-time.  For this reason, the 
definitions of @code{create_new()} and @code{get_second_largest()} are
in their own CWEB files, and are written to their own header files.  The
latter are included in the other CWEB files that need them.

In addition, @samp{AM_CXXFLAGS = -frepo} has been added to the file 
@file{Makefile.am} in @file{3DLDF-1.1.5/CWEB/}, so that the @cpp{}
compiler is called using the @samp{-frepo} option.  
The manual @cite{Using and Porting the GNU Compiler
Collection} explains this as follows:

@quotation
``Compile your template-using code with @samp{-frepo}. The compiler will
generate files with the extension @file{.rpo} listing all of the template
instantiations used in the corresponding object files which could be
instantiated there; the link wrapper, @samp{collect2}, will then update the
@file{.rpo} files to tell the compiler where to place those instantiations and
rebuild any affected object files. The link-time overhead is negligible
after the first pass, as the compiler will continue to place the
instantiations in the same files.''@c
@c
@footnote{Stallman, Richard M. @cite{Using and Porting the GNU Compiler
Collection}, p.@w{ }285.} 
@c
@end quotation

The first time the executable @file{3dldf} is built, the files that use
the template functions are recompiled one or more times, and the linker
is also called several times.  This doesn't happen anymore, once the
@file{.rpo} files exist.

Template instantiation differs from compiler to compiler, so using
template functions will tend to make 3DLDF less portable.  I am no
longer able to compile it on the DECalpha Personal Workstation I had
been using with the DEC @cpp{} compiler.
@xref{Ports}, for more information.  

@node Running 3DLDF,  , Installing 3DLDF, Installing and Running 3DLDF
@section Running 3DLDF

To use 3DLDF, call
@command{make run} from the command line in the 
shell.  The working directory should be 
@file{3DLDF-@value{VERSION}/} or @file{3DLDF-@value{VERSION}/CWEB}. 
Either will work, but the latter may be more convenient, because
this is the location of the CWEB, @TeX{} and MetaPost files that you'll
be editing.
Alternatively, call @command{ldfr}, which is merely a
shell script that calls @command{make run}.  
This takes care of running @command{3dldf}, MetaPost, @TeX{},
and @command{dvips}, producing a PostScript file containing your
drawings.  You can display the latter on your terminal using Ghostview
or some other 
PostScript viewer, print it out, and whatever else you like to do with
PostScript files.  

However, you can also perform the actions performed by 
@command{make run} by hand, by writing your own shell
scripts, by defining Emacs-Lisp commands, or in other ways.  Even if you
choose to use @command{make run}, it's important to understand what it
does.  The following explains how to do this by hand.  

The CWEB source files for 3DLDF are in the subdirectory
@file{3DLDF-@value{VERSION}/CWEB/}.  They 
must be @command{ctangled}, and the resulting @cpp{} files must be
compiled and 
linked, in order to create the executable file @file{3dldf}.  
The @cpp{} files and header files generated by @command{ctangle}, 
the object files generated by the compiler, and the executable
@file{3dldf} all  reside in @file{3DLDF-@value{VERSION}/CWEB/}. Therefore, the
latter must be your working directory.

Since 3DLDF has no input routine as yet, 
as explained in @ref{No Input Routine},
it is necessary to add @cpp{} code to the function @code{main()} in
@file{main.web}, and/or in a separate function in another file.  In the
latter case, the function containing the user code must be invoked in
@code{main()}.  Look for the line ``Your code here!'' in
@file{main.web}. 

This is an example of what you could write in @code{main()}.  
Feel free to make it more complicated, if you wish.  

@example
beginfig(1);
default_focus.set(2, 3, -10, 2, 3, 10, 20);
Rectangle R(origin, 5, 3);
Circle C(origin, 3, 90);
C.half(180).filldraw(black, light_gray);
R.filldraw();
C.half().filldraw(black, light_gray);
Point p = C.get_point(4);
p.shift(0, -.5 * p.get_y());
p.label("$C$", "");
Point q = R.get_mid_point(0);
q.shift(0, 0, -.5 * q.get_z());
q.label("$R$", ""); 
current_picture.output(default_focus, PERSP, 1, NO_SORT); 
endfig(1);
@end example

@iftex 
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 3, -10, 2, 3, 10, 20);}
\immediate\write\examples{Rectangle R(origin, 5, 3);}
\immediate\write\examples{Circle C(origin, 3, 90);}
\immediate\write\examples{C.half(180).filldraw(black, light_gray);}
\immediate\write\examples{R.filldraw();}
\immediate\write\examples{C.half().filldraw(black, light_gray);}
\immediate\write\examples{Point p = C.get_point(4);}
\immediate\write\examples{p.shift(0, -.5 * p.get_y());}
\immediate\write\examples{p.label("$C$", "");}
\immediate\write\examples{Point q = R.get_mid_point(0);}
\immediate\write\examples{q.shift(0, 0, -.5 * q.get_z());}
\immediate\write\examples{q.label("$R$", ""); }
\OEX{default_focus, PERSP, 1, NO_SORT}
\EGRP
\EEX 1
\fi
\PEX
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.72.png"
alt="[Figure 72. Not displayed.]"
/>
<br>
<br>
Fig. 72.
<br>
</p>  
@end html
@end ifhtml

@ifinfo
[Figure 72 not displayed.]
@end ifinfo

@enumerate 
@item
Save @file{main.web}, and any other CWEB files you've changed.  
Since these files have changed, they must be @command{ctangled}, and the
resulting @cpp{} files must be recompiled.  If you've changed any files
other than 
@file{main.web}, @command{ctangle} will also generate a header
file for each of these files.  If a header file differs from the version
that existed before @command{ctangle} was run, all of the @cpp{} files
that depend on it must be recompiled.  Then @file{3dldf} must be
relinked.  To do this, call @command{make 3dldf} from the command line. 

If you've made any errors in typing your code, the
compiler should have issued error messages, so go back into
the appropriate CWEB file and correct your errors.  Then call
@command{make 3dldf} again. 

@item
Call @command{CWEB/3dldf} at the command line.  It writes a
file of MetaPost code called @file{3DLDFput.mp}.

@item
Run MetaPost on the file @file{3DLDFmp.mp}, which inputs
@file{3DLDFput.mp}.  

@example
mpost 3DLDFput
@end example

@noindent
The result is an Encapsulated PostScript file
@file{3DLDFput.}<@i{integer}> for each figure in your drawing.

@item
The file @file{3DLDFtex.tex} should contain code for including the 
@file{3DLDFput.}<@i{integer}> files.  This is an example taken from 
the @file{3DLDFtex.tex} included in the distribution.
You may change it to suit your purposes.

@example
\vbox to \vsize@OCB{}\vskip 2cm
\line@OCB{}\hskip 2cm Figure 1.\hss@CCB{}%
\vfil
\line@OCB{}\hskip 2cm\epsffile@OCB{}3DLDFmp.1@CCB{}\hss@CCB{}%
\vss@CCB{}
@end example

@item
@noindent
Run @TeX{} on @file{3DLDFtex.tex} to produce the DVI file,
@file{3DLDFtex.dvi}. 

@example
tex 3DLDFtex
@end example

@item
Run @command{dvips} on the DVI file to produce the PostScript file,
@file{3DLDFtex.ps}.

@example
dvips -o 3DLDFtex.ps 3DLDFtex
@end example

@item
@file{3DLDFtex.ps} can be viewed using Ghostview, it can be printed using
@command{lpr} (on a Unix-like system),  you can convert it to PDF with
@code{ps2pdf}, or to some other format using the appropriate program.  
@end enumerate

I sincerely hope that it worked.  If it didn't, ask your local computer
wizard for help.

On the computer I'm using, I found that @code{special} arguments for
setting @code{landscape} and @code{papersize} in @TeX{} files for 
DIN A3 landscape didn't work.  Ghostview cut off the right sides of the
drawings.  Nor did it work to call 
@command{dvips -t landscape -t a3}.
This caused an error message which said that
@code{landscape} would be ignored.  When I called @command{dvips} 
with the @option{-t landscape} option alone, it worked, and
Ghostview showed the entire drawing. 

Another problem was Adobe Acrobat.  It would display the entire DIN A3
page, but not always in landscape format.  I was unable to find a way of
rotating the pages in Acrobat.  I finally found out, that if I included
even a single letter of text in a label, Acrobat would display the
document correctly. 

@menu
* Converting EPS Files::        
* Command Line Arguments::      
@end menu


@node Converting EPS Files, Command Line Arguments, Running 3DLDF, Running 3DLDF
@subsection Converting EPS Files

@cindex ImageMagick
@cindex ImageMagick convert
@cindex convert (ImageMagick)
@cindex PNG (Portable Network Graphics)
@cindex Portable Network Graphics (PNG)
@cindex PS (PostScript)
@cindex PostScript (PS)
@cindex structured PostScript
@cindex PostScript, structured
@cindex EPS (Encapsulated PostScript)
@cindex Encapsulated PostScript (EPS)
@c
@uref{http://www.imagemagick.org, ImageMagick} is a 
``collection of tools and libraries'' for image manipulation.
It provides a `@t{convert}' utility which can convert images from one
format to another.  It can convert structured PostScript (PS) to 
to @uref{http://www.libpng.org/pub/png/index.html, 
Portable Network Graphics (PNG)}, but @emph{not} 
EPS (Encapsulated PostScript) to PNG.  Nor can it convert EPS to
structured PostScript.

It is possible to have MetaPost generate structured PostScript directly
by including the command @samp{prologues:=1;} at the beginning of the
MetaPost input.
However, this ``generally doesn't work when you use @TeX{} 
fonts.''@c
@footnote{Hobby, @cite{A User's Manual for MetaPost}, pp.@w{ }21--22.}
@c
This is a significant problem if your labels contain math mode
material, and you haven't already taken steps to ensure that appropriate
fonts will be used in the PS output.

In the following, I describe the @emph{only way} I've found to convert
an EPS image to PNG format while still using @TeX{} fonts.  There may be
other and better ways of doing this, but I haven't found them.


@enumerate
@item
Assume the EPS image is in the file @file{3DLDFmp.1}
Include the EPS image in a @TeX{} file 
which looks like this:

@example
\advance\voffset by -1in
\advance\hoffset by -1in
\nopagenumbers
\input epsf
\epsfverbosetrue
\def\epsfsize#1#2@OCB{}#1@CCB{}
\setbox0=\vbox@OCB{}\epsffile@OCB{}3DLDFmp.1@CCB{}@CCB{}
\vsize=\ht0
\hsize=\wd0
\special@OCB{}papersize=\the\wd0,\the\ht0@CCB{}
\box0
\bye
@end example

@b{Do not} name this file @file{3DLDFmp.1.tex}!  
While this worked fine for me on a DECalpha Personal Workstation
running under Tru64 Unix 5.1, with @TeX{}, Version 3.1415 
(C version 6.1), and @b{dvipsk} 5.58f,
it failed on a PC Pentium II XEON under Linux 2.4, 
with @TeX{}, Version 3.14159 (Web2C 7.4.5), and 
@b{dvips(k)} 5.92b, kpathsea version 3.4.5,
with the following error message:
@display
``No BoundingBox comment found in file examples.1; using defaults''
@end display

@noindent
The resulting PS image had the wrong size and the 
the graphic was positioned improperly. 

Apparently, it confuses the EPSF macros when the name of an
included image is the same as @samp{\jobname}.
So, for this example, let's call it @file{3DLDFmp.1_.tex}.

You don't really need to call the macro @samp{\epsfverbosetrue}.  If you
do, it will print the measurements of the bounding box and other information
to standard output.@c
@c
@footnote{Rokicki, @cite{Dvips: A DVI-to-PostScript Translator}, p.@w{ }24.} 

@item
Run @samp{tex 3DLDFmp.1_.tex}.

@item
Run @samp{dvips -o 3DLDF.1.ps 3DLDFmp.1_.dvi}.

@item
Run @samp{convert 3DLDF.1.ps 3DLDFmp.1.png}.
@end enumerate


@cindex ImageMagick
@cindex ImageMagick display
@cindex display (ImageMagick)
@c
@uref{http://www.imagemagick.org, ,ImageMagick} 
supplies a `@command{display}' utility, which can be used to display the
PNG image:
 
@example
display 3DLDFmp.1.png
@end example

It can be included in an HTML document as follows:

@example
<img src="3DLDFmp.1.png"
         alt="[Fig. 1]." 
@end example

@menu
* Converting EPS Files ELISP::  
@end menu

@node Converting EPS Files ELISP,  , Converting EPS Files, Converting EPS Files
@subsubsection Emacs-Lisp Functions


@cindex PNG (Portable Network Graphics)
@cindex Portable Network Graphics (PNG)
@cindex PS (PostScript)
@cindex PostScript (PS)
@cindex structured PostScript
@cindex PostScript, structured
@cindex EPS (Encapsulated PostScript)
@cindex Encapsulated PostScript (EPS)
@c
@cindex Emacs-Lisp
The file @file{3DLDF-@value{VERSION}/CWEB/cnepspng.el} contains
definitions of two Emacs-Lisp functions that can be used to
convert Encapsulated PostScript (EPS) files to structured PostScript
(PS) and Portable Network Graphics (PNG) files.   

@deffn {Emacs-Lisp function} convert-eps filename do-not-delete-files
@c
Converts an EPS image file to the PS and PNG formats.  

If called interactively, @command{convert-eps} prompts for the
filename, including the extension, of an 
EPS image file.  It follows the procedure described above in
@ref{Converting EPS Files}, to create 
@file{@var{filename}.ps} and @file{@var{filename}.png}.

If @var{do-not-delete-files} is @code{nil}, 
the @file{.tex}, @file{.dvi}, and @file{.log} files will be deleted. 
This is the case when @command{convert-eps} is called interactively
with no prefix argument.
If @command{convert-eps} is called interactively with a prefix
argument, or non-interactively with a non-@code{nil} 
@var{do-not-delete-files} argument, these files will not be deleted.
@end deffn

@deffn {Emacs-Lisp function} convert-eps-loop arg start end
@c
Converts a set of EPS image files to the PS and PNG formats.  
The files
must all have the same filename, and the extensions must form a range of
positive integers.  For example, @command{convert-eps-loop} can be
used to convert the files @file{3DLDFmp.1}, @file{3DLDFmp.2}, and
@file{3DLDFmp.3} to @file{3DLDFmp.1.ps}, @file{3DLDFmp.2.ps}, and
@file{3DLDFmp.3.ps} on the one hand, and 
@file{3DLDFmp.1.png}, @file{3DLDFmp.2.png}, 
@file{3DLDFmp.3.png} on the other.
 
If @command{convert-eps-loop} is called interactively, 
it prompts for @var{filename} @emph{with no extension}
and the starting and ending numbers of the range.  

For all @math{i \in \INT} and @var{start} @math{\le i \le} @var{end}, 
@command{convert-eps-loop} checks whether a file named
@file{@var{filename.@math{i}}} exists.  If it does, 
it calls @command{convert-eps}, passing
@file{@var{filename.@math{i}}} as the latter's @var{filename} argument. 


@var{do-not-delete-files} is also passed to @command{convert-eps}.  If
it's @code{nil}, 
the @file{.tex}, @file{.dvi}, and @file{.log} files will be deleted. 
This is the case when @command{convert-eps-loop} is called interactively 
with no prefix argument.
If @command{convert-eps-loop} is called interactively with a prefix
argument, or non-interactively with a non-@code{nil} 
@var{do-not-delete-files} argument, these files will not be deleted.
@end deffn


@node Command Line Arguments,  , Converting EPS Files, Running 3DLDF
@subsection Command Line Arguments
@command{3dldf} can be called with the following 
@dfn{command line arguments}.

@table @code
@item --help
Prints information about the valid command line options to standard
output and exits with return value 0.

@item --silent
Suppresses some output to standard output
and standard error when @command{3dldf} is run

@item --verbose
Causes status information to be printed to standard output
when @command{3dldf} is run.

@item --version
Prints the version number of 3DLDF
to standard output and exits with return value 0.
@end table

Currently, @command{3dldf} can only handle long options.  @samp{-}
cannot be substituted for @samp{--}.  However, the names of the options
themselves can be abbreviated, as long as the abbreviation is
unambigous.  For example, @samp{3dldf --h} and @samp{3dldf --verb} are
valid, but @samp{3dldf --ver} is not.


@c !! TO DO: Put this in large, boldface type like a chapter heading,
@c for the printed output.  Having it be a node caused problems with the
@c Info output.  Using `@iftex' doesn't work, because the nodes are used
@c for making the menus.
@c  
@c It has to be here, because of the restrictions on
@c multiple files.
@c 
@c Class and Function Reference












