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 $
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
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.
The author can be contacted at:
Laurence D. Finston
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:
GWDG (Gesellschaft fuer wissenschaftliche Datenverarbeitung) server:
DANTE's CTAN server (DANTE = Deutschsprachige Anwendervereinigung TeX e.V.,
CTAN = Comprehensive TeX Archive Network)
and from the author's website:
* Mailing lists
The following mailing lists are planned, but not yet available:
firstname.lastname@example.org --- For bug reports.
email@example.com --- 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
* Web sites
The official 3DLDF website will be
http://www.gnu.org/software/3dldf. This site is not yet
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-22.214.171.124/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
The files /3DLDF-126.96.36.199/CWEB/3DLDFprg.ps and
/3DLDF-188.8.131.52/DOC/TEXINFO/3DLDF.ps contain respectively the documents
_3DLDF: The Program_ and the _3DLDF User and Reference Manual_
in PostScript format. In addition,
/3DLDF-184.108.40.206/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-220.127.116.11/.
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-18.104.22.168/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:
See the file INSTALL for instructions on installing 3DLDF.
* Patch instructions
Since 3DLDF 22.214.171.124 is being released so soon after 3DLDF 1.1.5, I'm
supplying two patch files: `3DLDF-1.1.4-126.96.36.199.diff.gz' and
The following instructions explain how to use
`3DLDF-1.1.4-188.8.131.52.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-184.108.40.206.diff.gz' is to
put the distribution of 3DLDF 1.1.4 in a new directory, e.g.,
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':
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 220.127.116.11.
Instead, the illustrations for the Texinfo manual are in
`3DLDF-18.104.22.168/DOC/TEXINFO/graphics/eps' (for the PostScript version)
and `3DLDF-22.214.171.124/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-126.96.36.199'
mv 3DLDF-1.1.4 3DLDF-188.8.131.52
Now, put `3DLDF-1.1.4-184.108.40.206.diff.gz' in `3DLDF-220.127.116.11'.
Change the working directory to `3DLDF-18.104.22.168' and unpack
mv 3DLDF-1.1.4-22.214.171.124.diff.gz 3DLDF-126.96.36.199/
Apply the patch:
patch -p1 -i 3DLDF-1.1.4-188.8.131.52.diff
* Running 3DLDF
Once 3DLDF is installed, put the code for your drawings in
/3DLDF-184.108.40.206/main.web, and call `make run' from the command
line in the directory /3DLDF-220.127.116.11/ to run 3dldf (the executable
program), MetaPost, TeX, and dvips, to generate a PostScript file
containing your drawings.
As a convenience, 3DLDF-18.104.22.168/ and 3DLDF-22.214.171.124/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-126.96.36.199/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-188.8.131.52/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-184.108.40.206/CWEB/ automatically,
but it does in 3DLDF-220.127.116.11/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,
These targets are new in 3DLDF 18.104.22.168, and are not yet documented in
the _3DLDF User and Reference Manual_ (/3DLDF-22.214.171.124/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-126.96.36.199/DOC/TEXINFO/3DLDF.ps).
Users should avoid the use of the following extensions in
/3DLDF-188.8.131.52/CWEB/: .rpo, .h, .hbk, .tim, and .tmw.
Each CWEB file has corresponding files with the same name and
* 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-184.108.40.206/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
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)))
(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,
./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/.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: