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: