README
  
This file is part of 3DLDF, a package for three-dimensional drawing. 
Copyright (C) 2003, 2004 Laurence D. Finston. 

$Id: README,v 1.10 2004/01/16 16:24:27 lfinsto1 Exp $

* Top

3DLDF is a GNU package. It is part of the GNU Project of the 
Free Software Foundation.  See the website http://www.gnu.org for more
information.  

3DLDF is free software; you can redistribute it and/or modify 
it under the terms of the GNU General Public License as published by 
the Free Software Foundation; either version 2 of the License, or 
(at your option) any later version. 

3DLDF is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
GNU General Public License for more details. 

You should have received a copy of the GNU General Public License 
along with 3DLDF; if not, write to the Free Software 
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 

3DLDF is a GNU package.  
It is part of the GNU Project of the  
Free Software Foundation 
and is published under the GNU General Public License. 
See the website http://www.gnu.org 
for more information.   

* Contact
The author can be contacted at: 

Laurence D. Finston 
Kreuzbergring 41 
D-37075 Goettingen 
Germany 

lfinsto1@gwdg.de 
s246794@stud.uni-goettingen.de 


* Downloading

3DLDF is available for downloading from the following servers using
the protocols indicated (i.e., `ftp', `http', and `rsync'): 

Free Software Foundation/GNU Project server:

ftp://ftp.gnu.org/gnu/3dldf
http://ftp.gnu.org/gnu/3dldf

GWDG (Gesellschaft fuer wissenschaftliche Datenverarbeitung) server: 

http://ftp.gwdg.de/pub/gnu2/3dldf/
ftp://ftp.gwdg.de/pub/gnu2/3dldf/
rsync://ftp.gwdg.de/pub/gnu2/3dldf/ 

DANTE's CTAN server (DANTE = Deutschsprachige Anwendervereinigung TeX e.V., 
                     CTAN  = Comprehensive TeX Archive Network)
 
http://dante.ctan.org/CTAN/graphics/3DLDF/

and from the author's website:  
http://wwwuser.gwgd.de/~lfinsto1 

* Mailing lists

The following mailing lists are planned, but not yet available:
bug-3dldf@gnu.org  --- For bug reports.
help-3dldf@gnu.org --- For users to ask one another for help.  
info-3DLDF@gnu.org --- For sending announcements to users. 

To subscribe to these mailing lists, 
once they are available, send an 
email with ``subscribe'' as the subject.  

Until they are, users can send an email with 
``subscribe 3dldf'' in the subject line to me at 
lfinsto1@gwdg.de


* Web sites
The official 3DLDF website will be
http://www.gnu.org/software/3dldf.  This site is not yet 
available. 
I hope it will be soon.  See also the author's website, 
http://wwwuser.gwdg.de/~lfinsto1, which contains news about 3DLDF,
and a section ``Errata and 
Addenda'', which may be helpful, if a user has problems.


* Description of 3DLDF 

3DLDF is a package for three-dimensional drawing with MetaPost output.
It currently does not possess an input routine, so that user code must
be written in C++, compiled, and linked with the rest of the program.
This file, and the _User and Reference Manual_ 
(/3DLDF-1.1.5.1/DOC/TEXINFO/3DLDF.ps) contain instructions on how to do
this.  3DLDF is intended, among other things, to provide a fairly
convenient way of making 3D drawings that can be included in TeX
documents.


* Documentation

The files /3DLDF-1.1.5.1/CWEB/3DLDFprg.ps and
/3DLDF-1.1.5.1/DOC/TEXINFO/3DLDF.ps contain respectively the documents  
_3DLDF: The Program_ and the _3DLDF User and Reference Manual_ 
in PostScript format.  In addition,
/3DLDF-1.1.5.1/CWEB/3DLDFprg.dvi contains _3DLDF: The Program_ in DVI
format.  If you need to  
regenerate the documentation for some reason, type `make ps' at the
command line from the directory /3DLDF-1.1.5.1/.  
Please note, that if you decide to run cweave on 3DLDFprg.web by hand,
be sure to use the version of the file cwebmacs.tex 
in /3DLDF-1.1.5.1/CWEB/, since I've made a number of additions and changes
to the original.  Ordinarily, it will be used automatically, so most
users won't need to worry about this. 

The file 3DLDF.info contains the _User and Reference Manual_ in
Info format.  It's generated by `make install'.  It can also be
generated by `make info'.  To make an HTML version, call
`makeinfo --html 3DLDF.texi'.  

I apologize for the number of typos and other errors in the
documentation.  I hope they don't detract from their usefulness.  
Please see the section ``Errata and Addenda'' on my website:
http://wwwuser.gwdg.de/~lfinsto1/index.html

* Installing 

See the file INSTALL for instructions on installing 3DLDF.


* Patch instructions

Since 3DLDF 1.1.5.1 is being released so soon after 3DLDF 1.1.5, I'm
supplying two patch files: `3DLDF-1.1.4-1.1.5.1.diff.gz' and 
`3DLDF-1.1.5-1.1.5.1.diff.gz'.

The following instructions explain how to use 
`3DLDF-1.1.4-1.1.5.1.diff.gz' to update 3DLDF 1.1.4.  They apply
equally to 3DLDF 1.1.5, except where noted, as long as the names of
the files and diretories are changed appropriately.

The best way to apply the patch `3DLDF-1.1.4-1.1.5.1.diff.gz' is to 
put the distribution of 3DLDF 1.1.4 in a new directory, e.g.,
`3DLDF-1.1.4'.
You may want you create a distribution by calling `make dist' from a
shell in the working directory `3DLDF-1.1.4/'.
Then you will have to uncompress and expand `3DLDF-1.1.4.tar.gz':

     gunzip 3DLDF-1.1.4.tar.gz
     tar pxvf 3DLDF-1.1.4.tar

If you choose to use your existing `3DLDF-1.1.4' directory instead,
you should save any files you don't want changed in a safe place.  


Delete the directory `3DLDF-1.1.4/DOC/TEXINFO/EPS' (not if you're
patching 3DLDF 1.1.5!):

    rm -rf 3DLDF-1.1.4/DOC/TEXINFO/EPS

This directory doesn't exist in 3DLDF 1.1.5 and 3DLDF 1.1.5.1.  
Instead, the illustrations for the Texinfo manual are in 
`3DLDF-1.1.5.1/DOC/TEXINFO/graphics/eps' (for the PostScript version) 
and `3DLDF-1.1.5.1/DOC/TEXINFO/graphics/png' (for the HTML version). 

Please note that the HTML version of the Texinfo manual is not part of
the distribution.  It is, however, downloadable separately from 
my website and the GWDG server, so there should be no need to
generate it yourself.  See `* Downloading', above, for the
URLs (Uniform Resource Locators).

Rename `3DLDF-1.1.4' `3DLDF-1.1.5.1'  

    mv 3DLDF-1.1.4 3DLDF-1.1.5.1

Now, put `3DLDF-1.1.4-1.1.5.1.diff.gz' in `3DLDF-1.1.5.1'.
Change the working directory to `3DLDF-1.1.5.1' and unpack 
`3DLDF-1.1.4-1.1.5.1.diff.gz':

    mv 3DLDF-1.1.4-1.1.5.1.diff.gz 3DLDF-1.1.5.1/
    cd 3DLDF-1.1.5.1
    gunzip 3DLDF-1.1.4-1.1.5.1.diff.gz

Apply the patch:

    patch -p1 -i 3DLDF-1.1.4-1.1.5.1.diff

* Running 3DLDF

Once 3DLDF is installed, put the code for your drawings in
/3DLDF-1.1.5.1/main.web, and call `make run' from the command
line in the directory /3DLDF-1.1.5.1/ to run 3dldf (the executable
program), MetaPost, TeX, and dvips, to generate a PostScript file
containing your drawings.  

As a convenience, 3DLDF-1.1.5.1/ and 3DLDF-1.1.5.1/CWEB/ both contain an
identical shell script called `ldfr', which simply calls 'make run',
so that 3DLDF can be used conveniently from either directory.  

* make Targets

BUG FIX: I've added `touch 3DLDFmp.mp' to the `3DLDFmp.mp' target in
3DLDF-1.1.5.1/CWEB/Makefile.am.  This ensures that  
TeX and dvips will be run if MetaPost is run on `3DLDFmp.mp'.  This
happens if `3DLDFput.mp' is newer than `3DLDFmp.mp', but the latter
isn't changed, so TeX and dvips weren't being run.  I'm surprized
nobody's complained about this. Not yet documented in the
_3DLDF User and Reference Manual_. 

3DLDF-1.1.5.1/CWEB/Makefile.am contains several 
`PHONY' targets as synonyms for several targets.

These are targets that users may want to call often:

`cpl' for `3dldf':  For compiling and linking `3dldf'.

`mp' for `3DLDFmp.mp':  For running MetaPost on `3DLDFmp.mp'.

`ldf' for `3DLDFput.mp': For running `3dldf'.

Most users should never need to call `make ps' or `make pdf', 
unless they are making changes to 3DLDF.

`ps' for generating `3DLDFprg.ps'.

`pdf' for generating `3DLDFprg.pdf'.  It uses `ps2pdf'.  Automake
doesn't generate a `pdf' target in 3DLDF-1.1.5.1/CWEB/ automatically,
but it does in 3DLDF-1.1.5.1/DOC/TEXINFO/.  However, it requires
`pdftex', which is not installed on the computer I'm using.  It may be
on yours, however, so I didn't want to override the default `pdf' target.

If you want to generate `3DLDF.pdf' for some reason, and `make pdf'
doesn't work on your computer either, try `ps2pdf 3DLDF.ps'.  However,
please note that `3DLDF.pdf' is included in the distribution and
available separately from my website and other download sites (see
"Downloading" above), along with `3DLDF.ps'. 
The HTML version is also available from my website,
http://ftp.gwdg.de/pub/gnu2/3dldf/
ftp://ftp.gwdg.de/pub/gnu2/3dldf/
and 
rsync://ftp.gwdg.de/pub/gnu2/3dldf/ 

These targets are new in 3DLDF 1.1.5.1, and are not yet documented in
the _3DLDF User and Reference Manual_ (/3DLDF-1.1.5.1/DOC/TEXINFO/3DLDF.ps).  

To get rid of the files that 3DLDF generates, without deleting any
important ones, call `make purge'.

For further information, see the _3DLDF User and
Reference Manual_ (/3DLDF-1.1.5.1/DOC/TEXINFO/3DLDF.ps).  

Users should avoid the use of the following extensions in 
/3DLDF-1.1.5.1/CWEB/: .rpo, .h, .hbk, .tim, and .tmw. 
Each CWEB file has corresponding files with the same name and 
these extensions.  

* Information on building:

If only TeX text, comments, or whitespace in the CWEB file are
changed, then no recompilation or relinking takes place, and the CWEB
file isn't retangled the next time `make 3dldf' is called.
Unfortunately, whitespace in literal strings that are part of the C++
code are also ignored, contrary to what I wrote in
3DLDF-1.1.5.1/CWEB/ChangeLog.  It's not likely that this will cause any
problems in actual use, though.

If only the C++ code has changed, the .cxx file is recompiled, and 3dldf is
relinked. 

If the header file has changed, all of the C++ files that depend on it are
recompiled, and 3dldf is relinked.

Two ``timer'' files are used for keeping track of whether
<filename>.h and/or <filename>.cxx has changed. 

The procedure seems to work when multiple files are changed in various
ways.  However, one unpleasant consequence is that the CWEB file must
be touched to give it an earlier timestamp in the case that neither
the C++ file nor the header file 
has changed (but only in this case!).  This means that the file has
changed on disk, so that 
the buffer must be reverted, if the user is currently working on it,
which is likely.  The shell script `tsthdweb' prints a message to this
effect to standard output.  It's annoying to have to revert the
buffer, but I haven't thought of a way
around this problem. It's a consequence of using the timestamps of
files to decide whether they need to be reprocessed. The best solution
may be to return to using an auxilliary program for controlling
recompilation.  However, this will mean maintaining two different
methods of rebuilding, because Automake requires valid build rules.

** Reverting buffers

If you're using Emacs, you can set a key to revert the buffer without
querying by putting the following sexp (s-expression, but I don't know
what ``s'' stands for) into your `.emacs' file:

(global-set-key [f5] '(lambda () (interactive) (revert-buffer t t)))

Or, if you're using, for example, foo mode, you can put the following 
sexp into your foo-mode-hook declaration:

(local-set-key foo-mode-map [f5] '(lambda () (interactive) 
                                  (revert-buffer t t)))
For example,
(setq lisp-mode-hook
      '(lambda ()
       (local-set-key [f5] '(lambda () (interactive) 
                                     (revert-buffer t t)))))

Or, if you've defined a foo mode yourself, you can put the key
assignment into foo-mode-map:

(if foo-mode-map ()
  (setq foo-mode-map (nconc (make-sparse-keymap) c-mode-map))
  (define-key foo-mode-map [f5] '(lambda () (interactive)
                                     (revert-buffer t t))))


*Information about Changes

For information about changes to 3DLDF, see 
NEWS, ChangeLog, ./CWEB/ChangeLog, 
./DOC/ChangeLog, ./DOC/TEXINFO/ChangeLog, 
./RCSFREEZE.log
./CWEB/RCSFREEZE.log, ./DOC/RCSFREEZE.log, and ./DOC/TEXINFO/RCSFREEZE.log.  
The latter files
contain information about frozen configurations, referring to general
changes affecting multiple files.  
	
./CWEB/ChangeLog.dev, ./DOC/TEXINFO/ChangeLog.dev,
./CWEB/.rcsfreeze.log.dev, and ./DOC/TEXINFO/.rcsfreeze.log.dev contain the
ChangeLog files and .rcsfreeze.log files from my development version up to
2003-11-28, when I set up RCS repositories for my releases.  



%% Local Variables:
%% mode:TeX
%% outline-minor-mode:t
%% outline-regexp:"^\\*+"
%% End: