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

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.   


3DLDF is available for downloading from 
http://ftp.gnu.org/gnu/3dldf
It is also available from 
http://www.dante.de/software/ctan/, the Dante www-server  
and from http://wwwuser.gwgd.de/~lfinsto1, 
the author's website.  

Please send bug reports to bug-3DLDF@gnu.org 
The mailing list help-3DLDF@gnu.org is available for people to 
ask other users for help.  
The mailing list info-3DLDF@gnu.org is for sending 
announcements to users. To subscribe to these mailing lists, send an 
email with ``subscribe <email-address>'' as the subject.  


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

The author can be contacted at: 

Laurence D. Finston 
Kreuzbergring 41 
D-37075 Goettingen 
Germany 

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

$Id: README,v 1.7 2003/12/10 17:00:37 lfinsto1 Exp lfinsto1 $

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.4/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.

See the file INSTALL for instructions on installing 3DLDF.

Please send bug reports to bug-3DLDF@gnu.org. (Not yet available!)

The mailing list help-3DLDF@gnu.org is available for people to ask
other users for help. (Not yet available!)
The mailing list info-3DLDF@gnu.org is for sending announcements to
users. (Not yet available!)

To subscribe to these mailing lists (once they are available), send an
email with `subscribe <email-address>' as the subject.
<email-address> is optional; if it's 
missing, I will use the `Reply-To' address of the email you sent.

Until they are made available, please contact the author at:
lfinsto1@gwdg.de

If you send a mail with `subscribe 3DLDF <email-address>' to me, I
will put you on my 3DLDF mailing list, and subscribe you to
info-3DLDF@gnu.org, when it becomes available.  <email-address> is
optional, as above.


Documentation

The files /3DLDF-1.1.4/CWEB/3DLDFprg.ps and
/3DLDF-1.1.4/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.4/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.4/.  
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.4/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.  I
would have liked to have proofread and corrected them again before
publication, but for reasons external to 3DLDF, it is necessary
for me to publish now.  
I plan to set up an errata list on the website:
http://www.gnu.org/software/3DLDF

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

As a convenience, /3DLDF-1.1.4/ and /3DLDF-1.1.4/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

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.4/DOC/TEXINFO/3DLDF.ps).  

Users should avoid the use of the following extensions in 
/3DLDF-1.1.4/CWEB/: .hbk, .tim, and .tmw. 
Each CWEB file has corresponding files with the same name and 
these extensions.  They are used for controlling retangling,
recompilation, and relinking.  


System dependencies:

In 3DLDF 1.1.4, the constant float MAX_REAL is now really the second
largest float value, but only on 32-bit little-endian architectures.  
On big-endian and 64-bit little-endian architectures, this will fail,
and 3dldf will exit with an error message.  

I plan to fix this so it will work on other architectures soon.  If
you have this problem, and can't fix it yourself, please contact me. 


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.4/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.

Previously, a ``timer'' file was used for keeping track of whether
<filename>.h had changed.  Now, a second ``timer'' is used for keeping
track of whether <filename>.cxx has changed. (Insert pun about
``two-timing'' here, when I've thought of one.) 

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.  This shell script prints a message to this effect to
standard output.  This is annoying, 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.

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've
forgotten 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 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
%% End:
