README Created by Laurence D. Finston (LDF) * (1) Copyright and License. This file is part of GNU 3DLDF, a package for three-dimensional drawing. Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The Free Software Foundation GNU 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 3 of the License, or (at your option) any later version. GNU 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 GNU 3DLDF; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA GNU 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. GNU 3DLDF is available for downloading from http://www.gnu.org/software/3dldf/LDF.html. Please send bug reports to Laurence.Finston@gmx.de 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 '' as the subject. The author can be contacted at: Laurence D. Finston c/o Free Software Foundation, Inc. 51 Franklin St, Fifth Floor Boston, MA 02110-1301 USA Laurence.Finston@gmx.de $Id: README,v 1.12 2010/01/20 18:22:22 lfinsto1 Exp $ * IMPORTANT! LDF 2004.09.09. I am currently in the process of preparing an alpha release, to be called "GNU 3DLDF 1.2.0.1". I will be using the number "1.2.0" to identify preliminary versions, so this number does not identify a particular release. I am also working on updating this file. Some of the information in it _no longer applies_. Please contact `help-3dldf@gnu.org' if you have questions. For more information specifically about the preliminary versions, see the files `00README' and `00NEWS'. * Downloading GNU 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 now 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 the maintainer of GNU 3DLDF to send announcements to users. To subscribe to these mailing lists, please send an email with ``subscribe'' as the subject. * Web sites The official GNU 3DLDF website is http://www.gnu.org/software/3dldf. * Description of GNU 3DLDF GNU 3DLDF is a package for three-dimensional drawing with MetaPost output. * Documentation The files /3DLDF-1.2.0/CWEB/3DLDFprg.ps and /3DLDF-1.2.0/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.2.0/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.2.0/. 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.2.0/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 GNU 3DLDF. * Patch instructions The following instructions explain how to use `3DLDF-1.1.5.1-1.2.0.diff.gz' to update 3DLDF 1.1.5.1. The best way to apply the patch `3DLDF-1.1.5.1-1.2.0.diff.gz' is to put the distribution of GNU 3DLDF 1.1.5.1 in a new directory, e.g., `3DLDF-1.1.5.1'. You may want you create a distribution by calling `make dist' from a shell in the working directory `3DLDF-1.1.5.1/'. Then you will have to uncompress and expand `3DLDF-1.1.5.1.tar.gz': gunzip 3DLDF-1.1.5.1.tar.gz tar pxvf 3DLDF-1.1.5.1.tar If you choose to use your existing `3DLDF-1.1.5.1' directory instead, you should save any files you don't want changed in a safe place. 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.5.1' `3DLDF-1.2.0' mv 3DLDF-1.1.5.1 3DLDF-1.2.0 Now, put `3DLDF-1.1.5.1-1.2.0.diff.gz' in `3DLDF-1.2.0'. Change the working directory to `3DLDF-1.2.0' and unpack `3DLDF-1.1.5.1-1.2.0.diff.gz': mv 3DLDF-1.1.5.1-1.2.0.diff.gz 3DLDF-1.2.0/ cd 3DLDF-1.2.0 gunzip 3DLDF-1.1.5.1-1.2.0.diff.gz Apply the patch: patch -p1 -i 3DLDF-1.1.5.1-1.2.0.diff * Running GNU 3DLDF Once GNU 3DLDF is installed, put the code for your drawings in /3DLDF-1.2.0/main.web, and call `make run' from the command line in the directory /3DLDF-1.2.0/ to run 3dldf (the executable program), MetaPost, TeX, and dvips, to generate a PostScript file containing your drawings. As a convenience, 3DLDF-1.2.0/ and 3DLDF-1.2.0/CWEB/ both contain an identical shell script called `ldfr', which simply calls 'make run', so that GNU 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.2.0/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.2.0/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 GNU 3DLDF. `ps' for generating `3DLDFprg.ps'. `pdf' for generating `3DLDFprg.pdf'. It uses `ps2pdf'. Automake doesn't generate a `pdf' target in 3DLDF-1.2.0/CWEB/ automatically, but it does in 3DLDF-1.2.0/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 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 GNU 3DLDF 1.2.0, and are not yet documented in the _3DLDF User and Reference Manual_ (/3DLDF-1.2.0/DOC/TEXINFO/3DLDF.ps). To get rid of the files that GNU 3DLDF generates, without deleting any important ones, call `make purge'. For further information, see the _3DLDF User and Reference Manual_ (/3DLDF-1.2.0/DOC/TEXINFO/3DLDF.ps). Users should avoid the use of the following extensions in /3DLDF-1.2.0/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.2.0/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 .h and/or .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 GNU 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. %% Local Variables: %% mode:TeX %% outline-minor-mode:t %% outline-regexp:"^\\*+" %% End: