This copyright notice applies to the text and source
code of this web site, and the graphics that appear on it.
The software described in this text has its own copyright notice and
license, which can be found in the distribution itself.

Permission is granted to copy, distribute, and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of this license is included in the file
COPYING.TXT

It is also available from the Git repository for project at Savannah:
git clone git://git.savannah.gnu.org/3dldf.git

This is the first release since 1.1.5.1 in 2004. It is also the first release
including the interactive program `3dldf', which implements a language intended
to resemble Donald Knuth's METAFONT language and John Hobby's MetaPost
language, which is based on METAFONT.

In previous releases, the GNU 3DLDF package was more like a library of C++
classes and functions which could be used by users to write programs for making
drawings. For several years, versions of the package allowing interactive use
have been available via Savannah, but 2.0 is the first official release
including this feature.

There have been many other changes, too numerous to list here.

This release has been delayed so long, because the change in the way the
package is meant to be used (i.e., interactively) means that the manual must be
completely rewritten. Unfortunately, it has not been possible for me to do
this. However, in order not to delay the release any longer, I have decided to
go ahead without a new manual. As a partial substitute, many examples are
included in the subdirectory 3DLDF-2.0/examples/.

2006.01.25.
The most recent version of the GNU 3DLDF manual (see below) documents Release 1.1.5.1.
I need to rewrite it completely in order to account for the many changes I've made in
my development versions. I have been
documenting the latter on these web pages. The old manual may still be of use to
people who want to know how 3DLDF is implemented, but it is quite out-of-date
by now.

2005-01-22.
I've abandoned work on the
GNU 3DLDF 1.2.0 Manual --- Plain Text Version
(Last updated 2005-01-31).
I now plan to convert it to Texinfo. Until I do, however, it may
still be useful to people who want to learn how to use
3DLDF 1.2.0.

The downloadable versions of 3DLDF: The Program,
and the versions in the distribution
have the table of contents at the front. This is not the case, if
you generate them yourself.
In order to do this, I used dviselect and dviconcat. I have not
yet written make rules to do have this done automatically.

2005-09-02
The utility
conveps is included in the GNU 3DLDF distribution.
It is for converting the Encapsulated PostScript files generated by
MetaPost
to other formats.

When the EPS files generated by
MetaPost
don't contain any TeX text,
there's no problem converting them to other formats, so there's no
need for a special utility.
However, when they do, programs that convert one graphics file format
to another can't handle them.

conveps solves this problem by including the EPS files in
TeX files,
and running TeX,
dvips, mogrify, and convert.
The structured PostScript (PS) files produced by dvips namely
can be converted to other formats.

The source code is available here:
conveps.webconveps has quite a few options for manipulating the images in
various ways.
The cweaved output of conveps.web contains instructions on how
to use it.
The versions of this as of this date (2005.12.16) are contained in the
following files:

It's sometimes useful to convert
TeX text into other formats, so that
it can be displayed in a browser or combined with images created in
some other way.
ImageMagick's convert program can be used to convert the PostScript
files generated from TeX text to other formats.

The file box_math.txt
contains TeX code for making examples of this.
(It's called box_math.txt so browsers will display it as an
ASCII, i.e., plain text, file without complaining.)
The version of this file included in the 3DLDF distribution
may be found here:
box_math.tex. The latter file may be more recent than the
version on this web page.

There are two basic ways of formatting text using the code in
box_math.txt. The first way
formats running text using a specified \hsize. In this case,
TeX chooses the line breaks. The
second way is for the user to specify the line breaks. In this case,
the macro \boximage in box_math.txt
chooses an \hsize large enough for the longest line.

In the following examples, the frames aren't part of the images. I've
added them to show the size of the images.

This is an example of running text with \hsize == 15cm:

This is an example of text with explicit line breaks:

It would be very tedious to type in the code for explicit
line breaking for more than a couple of examples.
Instead, the code in box_math.txt
is intended to be used by a utility that generates images from
TeX code and a few arguments for setting options.

The macro \boximage puts the text into a \vbox and
surrounds it with a red frame made up of \vrules.
The top, bottom, left, and right margins between the frame and the
block of text can be set by the user. After running tex and
dvips, a PNG file (b.png) is created from the resulting
PostScript file (b.ps) by the command
convert -crop 0x0 +antialias -fill white -opaque "rgb(255,0,0)" b.ps b.png.
The -crop 0x0 option removes the parts of the image that lie
outside the frame. The -fill and -opaque options
together change the color of the red frame to white.
The +antialias option disables use of
anti-aliasing, so that the color of pixels in the image are left unchanged.
Without this option, the -fill and -opaque wouldn't be
able to remove the red frame cleanly, because some of the red pixels
would have been changed. If a frame is desired, the
-fill and -opaque options can be omitted.
The first argument to \boximage makes it possible to specify a
different color for the frame, if the image contains red text. The
color used for the frame shouldn't appear in the image.

One problem with converting PostScript files created using
TeX to
images is the poor resolution and hence the poor appearance of such
images when displayed in a browser. The relationship between image
size and resolution is tricky. The fonts used for
TeX are mostly
available in small sizes for use on devices with relatively high
resolution. Plain magnification doesn't produce good results,
because single pixels are merely replaced by groups of pixels. I
still have a lot to learn about the issues involved.

Another problem is that the images are not scalable in browsers.
Increasing the display size of the text on a web page has no effect on
the included images. It might be possible to have a set of images
that are identical except for the font size and use JavaScript or PHP to
choose the right one based on the magnification used for the web
page. However, this would only work if JavaScript or PHP was enabled,
and it might not be desirable to require this.

2005-05-02.
I've replaced @ with -*-AT-*- in all of the email
addresses on these webpages, and removed all clickable references to
email addresses. I've been forced to this step by the huge amounts of
spam I receive.

2005-05-21.
I have reactivated the
help-3dldf-*-AT-*-gnu.org
mailing list, but only for subscribers. Postings from non-subscribers
are automatically discarded. I have deactivated the other GNU 3DLDF
mailing lists.
I have been forced to take this step by the huge amounts of spam
posted to these lists.
For the same reason, I've also replaced
@ with -*-AT-*- in all
of the email
addresses on these webpages, and removed all clickable references to
email addresses. If would prefer that all queries and comments be
addressed to help-3dldf-*-AT-*-gnu.org, but if you don't wish
to subscribe, you may contact me directly.

2005-05-21.
The following mailing list is now available:
(Replace -*-AT-*- with @ for the email address.)
help-3dldf-*-AT-*-gnu.org
for users to ask one another for help.