summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/manuals/reference/en/co-figures.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/context/manuals/reference/en/co-figures.tex')
-rw-r--r--Master/texmf-dist/doc/context/manuals/reference/en/co-figures.tex687
1 files changed, 0 insertions, 687 deletions
diff --git a/Master/texmf-dist/doc/context/manuals/reference/en/co-figures.tex b/Master/texmf-dist/doc/context/manuals/reference/en/co-figures.tex
deleted file mode 100644
index 11109278bc7..00000000000
--- a/Master/texmf-dist/doc/context/manuals/reference/en/co-figures.tex
+++ /dev/null
@@ -1,687 +0,0 @@
-\startcomponent co-en-14
-
-\environment contextref-env
-\product contextref
-
-\chapter[figures,external figures]{Figures}
-
-\section{Introduction}
-
-In this chapter we discuss how to place figures in your
-document. In \in {section} [floats] we introduced the float
-mechanism. In this chapter the placement of figures is
-discussed. Most of the time these figures are created with
-external applications.
-
-After processing a document the result is a \DVI\ file or,
-when we use \PDFTEX, a \PDF\ file. The \DVI\ document
-reserves space for the figure, but the figure itself will be
-put in the document during postprocessing of the \DVI\ file.
-\PDFTEX\ needs no postprocessing and the external figures
-are automatically included in the \PDF\ file.
-
-External figures may have different formats like the vector
-formats \EPS\ and \PDF, or the bitmap formats \TIF, \PNG\
-and \JPG. Note that we refer to figures but we could also
-refer to movies. \CONTEXT\ has special mechsnisms to handle
-figures generated by \METAPOST. We have to take care that
-fonts used in \METAPOST\ figures are recognized by \PDFTEX.
-Finally, we'll see that \METAPOST\ code can be embedded in
-\CONTEXT\ documents.
-
-Normally, users need not concern themselves with the
-internal mechanisms used by \CONTEXT\ for figure processing.
-However some insight may be useful.
-
-\section{Defining figures}
-\index{external figures}
-\index{figures+defining}
-\macro{\tex{setupexternalfigures}}
-\macro{\tex{useexternalfigure}}
-\macro{\tex{externalfigure}}
-
-A figure is designed within specific dimensions. These
-dimensions may of may not be known by the document designer.
-
-\startlinecorrection
-\startcombination[4*1]
- {\externalfigure[cow][scale=300,frame=on]}
- {natural dimension}
- {\externalfigure[cow][scale=225,frame=on]}
- {scaled to 25\%}
- {\externalfigure[cow][height=2cm,frame=on]}
- {a height of 2~cm}
- {\externalfigure[cow][height=2cm,width=3cm,frame=on]}
- {a height of 2~cm and a width 3~cm}
-\stopcombination
-\stoplinecorrection
-
-If the original dimensions are unknown, then scaling the
-figure to 40\% can have some astonishing results. A figure
-with width and height of 1~cm becomes almost invisible, but
-a figure width width and height of 50~cm will still be very
-large when scaled to 40\% of its original size. A better
-strategy is to perform the scaling based on the current
-bodyfont size, the width of text on the page, or to set
-absolute dimensions, such as 3~cm by 2~cm.
-
-To give \TEX\ the opportunity to scale the figure adequately
-the file format must be known. \in {Table} [tab:drivers]
-shows the file formats supported by \DVIPS, \DVIPSONE, and
-\PDFTEX\ respectively. \PDFTEX\ has the unique capability to
-determine the file format during processing.
-
-When we use \DVI, \TEX\ can determine the dimensions of an
-\EPS\ illustration by searching for the so called {\em
-bounding box}. However, with other formats such as \TIF, the
-user is responsible for the determination of the figure
-dimensions.
-
-\startbuffer
-\starttable[|l||||||||]
-\HL
-\VL \VL\EPS\VL\PDF\VL\METAPOST\VL\TIF\VL\PNG\VL\JPG\VL\MOV\VL\SR
-\HL
-\VL \DVIPS \VL + \VL -- \VL + \VL - \VL - \VL - \VL + \VL\FR
-\VL \DVIPSONE \VL + \VL -- \VL + \VL + \VL - \VL - \VL + \VL\MR
-\VL \PDFTEX \VL - \VL + \VL + \VL + \VL + \VL + \VL + \VL\LR
-\HL
-\stoptable
-\stopbuffer
-
-\placetable
- [here][tab:drivers]
- {Some examples of supported file formats.}
- {\getbuffer}
-
-Now, let us assume that the dimensions of a figure are
-found. When we want to place the same figure many times, it
-would be obvious to search for these dimensions only once.
-That is exactly what happens. When a figure is found it is
-stored as an object. Such an object is re||used in \TEX\ and
-in \PDF\ but not in \DVI, since reuse of information is not
-supported by the \DVI\ format. To compensate for this
-shortcoming, when producing \DVI\ output, \CONTEXT\ will
-internally reuse figures, and put duplicates in the \DVI\
-file.
-
-\starttyping
-\useexternalfigure[some logo][logo][width=3cm]
-
-\placeexternalfigure{first logo}{\externalfigure[some logo]}
-
-\placeexternalfigure{second logo}{\externalfigure[some logo]}
-\stoptyping
-
-So, when the second logo is placed, the information
-collected while placing the first one is used. In \PDFTEX\
-even the content is reused, if requested, at a different
-scale.
-
-A number of characteristics of external figures are specified
-by:
-
-\showsetup{setupexternalfigures}
-
-This command affect all figures that follow. Three options are
-available: \type {frame}, \type{empty} and \type{test}. With
-\type {empty} no figures are placed, but the necessary space
-is reserved. This can save you some time when \quote
-{testing} a document. \footnote {A similar effect can be
-obtained with the \type {--fast} switch in \TEXEXEC.}
-Furthermore the figure characteristics are printed in that
-space. When \type {frame} is set at \type {on} a frame is
-generated around the figure. The option \type {test} relates
-to testing hyperactive areas in figures.
-
-When \CONTEXT\ is not able to determine the dimensions of an
-external figure directly, it will fall back on a simple
-database that can be generated by the \PERL\ script
-\TEXUTIL. You can generate such a database by calling this
-script as follows:
-
-\starttyping
-texutil --figures *.tif
-\stoptyping
-
-This will generate the \type {texutil.tuf} file, which
-contains the dimensions of the \TIF\ figures found. You need
-to repeat this procedure every time you change a graphic.
-Therefore, it can be more convenient to let \CONTEXT\
-communicate with \TEXUTIL\ directly. You can enable that by
-adding \type {\runutilityfiletrue} to your local \type
-{cont-sys.tex} file.
-
-When a figure itself is not available but it is listed in
-the \type {texutil.tuf} file then \CONTEXT\ presumes that
-the figure does exist. This means that the graphics do not
-need to be physically present on the system.
-
-Although \CONTEXT\ very hard tries to locate a figure, it
-may fail due to missing or invalid figure, or invalid path
-specifications (more on that later). The actual search
-depends on the setup of directories and the formats
-supported. In most cases, it it best not to specify a suffix
-or type.
-
-\starttyping
-\externalfigure[hownice]
-\externalfigure[hownice.pdf]
-\externalfigure[hownice][type=pdf]
-\stoptyping
-
-In the first case, \CONTEXT\ will use the graphic that has
-the highest quality, while in both other cases, a \PDF\
-graphic will be used. In most cases, the next four calls are
-equivalent, given that \type {hownice} is available in
-\METAPOST\ output format with a suffix \type {eps} or \type
-{mps}:
-
-\starttyping
-\externalfigure[hownice]
-\externalfigure[hownice][type=eps]
-\externalfigure[hownice][type=eps,method=mps]
-\externalfigure[hownice][type=mps]
-\stoptyping
-
-In most cases, a \METAPOST\ graphic will have a number as
-suffix, so the next call makes the most sense:
-
-\starttyping
-\externalfigure[hownice.1]
-\stoptyping
-
-Let us summarize the process. Depending on the formats
-supported by the currently selected driver (\DVI, \PDFTEX,
-etc.), \CONTEXT\ tries to locate the graphics file, starting
-with the best quality. When found, \CONTEXT\ first tries to
-determine the dimensions itself. If this is impossible,
-\CONTEXT\ will look into \type {texutil.tuf}. The graphic as
-well as the file \type {texutil.tuf} are searched on the
-current directory (\type {local}) and|/|or dedicated
-graphics directories (\type {global}), as defined by \type
-{\setupexternalfugures}. By default the \type {location} is
-set at \type {{local,global}}, so both the local and global
-directories are searched. You can set up several directories
-for your search by providing a comma||delimited list:
-
-\starttyping
-\setupexternalfigures[directory={c:/fig/eps,c:/fig/pdf}]
-\stoptyping
-
-Even if your operating uses a \texescape\ as separator, you
-should use a \type {/}. The figure directory may be system
-dependent and is either set in the file \type {cont-sys}, in
-the document preamble, or in a style.
-
-An external figure is summoned by the command \type
-{\externalfigure}. The cow is recalled with:
-
-\starttyping
-\externalfigure[cow][width=2cm]
-\stoptyping
-
-For reasons of maintenance it is better to specify all
-figures at the top of your source file or in a separate
-file. The figure definition is done with:
-
-\showsetup{useexternalfigure}
-
-Valid definitions are:
-
-\starttyping
-\useexternalfigure [cow]
-\useexternalfigure [some cow] [cow230]
-\useexternalfigure [big cow] [cow230] [width=4cm]
-\stoptyping
-
-In the first definition, the figure can be recalled as \type
-{cow} and the graphics file is also \type {cow}. In the
-second and third definition, the symbolic name is \type
-{some cow}, while the filename is \type {cow230}. The last
-example also specifies the dimensions.
-
-The \type {scale} is given in percentages. A scale of \type
-{800} (80\%) reduces the figure, while a value of \type
-{1200} (120\%) enlarges the figure. Instead of using
-percentages you can also scale with a factor that is related
-to the actual bodyfont. A setup of \type {hfactor=20}
-supplies a figure with 2~times the height of the bodyfont
-size, and \type {hfactor=120} will result in a width of
-12~times the bodyfont size (so 144pt when using a 12pt
-bodyfont size). When we want to place two figures next to
-one another we can set the height of both figures with \type
-{hfactor} at the same value:
-
-\startexample
-\starttyping
-\useexternalfigure[alfa][file0001][hfactor=50]
-\useexternalfigure[beta][file0002][hfactor=50]
-
-\placefigure
- {Two figures close to one another.}
- \startcombination[2]
- {\externalfigure[alfa]} {this is alfa}
- {\externalfigure[beta]} {this is beta}
- \stopcombination
-\stoptyping
-\stopexample
-
-We can see that \type {\externalfigure} is capable of using
-a predefined figure. The typographical consistency of a
-figure may be enhanced by consistently scaling the figures.
-Also, figures can inherit characteristics of previously
-defined figures:
-
-\startexample
-\starttyping
-\useexternalfigure [alfa] [file0001] [hfactor=50]
-\useexternalfigure [beta] [file0002] [alfa]
-\useexternalfigure [gamma] [file0003] [alfa]
-\useexternalfigure [delta] [file0004] [alfa]
-\stoptyping
-\stopexample
-
-Normalizing a figure's width must also be advised when
-figures are placed with \type {\startfiguretext} below one
-another.
-
-In most cases you will encounter isolated figures of which
-you want to specify width or height. In that case there is
-no relation with the bodyfont except when the units \type
-{em} or \type {ex} are used.
-
-In \in {figure} [fig:factors] we drew a pattern with squares
-of a factor~10.
-
-\placefigure
- [here]
- [fig:factors]
- {Factors at the actual bodyfont.}
- {\vskip\lineheight
- \grid
- [nx=30,ny=10,
- dx=\bodyfontpoints,dy=\bodyfontpoints,
- xstep=1,ystep=1,
- unit=pt]}
-
-\section{Recalling figures}
-\index{figures+recalling}
-\macro{\tex{showexternalfigures}}
-\macro{\tex{externalfigure}}
-
-A figure is recalled with the command:
-
-\showsetup{externalfigure}
-
-For reasons of downward compatibility a figure can also be
-recalled with a command that equals the figure name. In the
-example below we also could have used \type {\acow} and
-\type {\bcow}, unless they are already defined. Using \type
-{\externalfigure} instead is more safe, since it has its own
-namespace.
-
-\startbuffer
-\useexternalfigure[acow][cow][factor=10]
-\useexternalfigure[bcow][cow][factor=20]
-
-\placefigure[left]{none}{\externalfigure[bcow]}
-
-The \hbox {\externalfigure[acow]} is a very well known animal in the Dutch
-landscape. But for environmental reasons the \hbox {\externalfigure[acow]}
-is slowly disappearing. In the near future the cow will fulfil a marginal
-\inleft {\externalfigure[bcow]} role in the Netherlands. That is the
-reason why we would like to write the word \hbox {\externalfigure[bcow]}
-in big print.
-\stopbuffer
-
-\startexample
-\typebuffer
-\stopexample
-
-Here we see how \type {acow} and \type {bcow} are reused.
-This code will result in:
-
-\getbuffer
-
-Normalized figures adapt to the actual bodyfont at least
-when the font is set with \type {\setupbodyfont} or \type
-{\switchtobodyfont}. When a text is used for different media
-and is generated with different fontsizes the use of
-normalized figures is a good practice. The example above
-looks different in a smaller fontsize.
-
-\start
-\switchtobodyfont[small]
-\getbuffer\par
-\stop
-
-\section{Automatic scaling}
-\index{figures+maximum}
-
-In cases where you want the figure displayed as big as
-possible you can set the parameter \type{factor} at
-\type{max}, \type{fit} or \type{broad}. In most
-situations the value \type{broad} will suffice, because then
-the caption still fits on a page.
-
-\placetable{Normalized figures.}
-\starttable[|l|l|]
-\HL
-\VL \bf setup \VL \bf result \VL\SR
-\HL
-\VL \tttf max \VL maximum width or height \VL\FR
-\VL \tttf fit \VL remaining width or height \VL\MR
-\VL \tttf broad \VL more remaining width or height \VL\MR
-\VL \ttsl number \VL scaling factor (times 10) \VL\LR
-\HL
-\stoptable
-
-So, one can use \type {max} to scale a figure to the full
-page, or \type {fit} to let it take up all the remaining
-space. With \type {broad} some space is reserved for a
-caption.
-
-Sometimes it is not clear whether the height or the width of
-a figure determines the optimal display. In that case you
-can set \type {factor} at \type {max}, so that the maximal
-dimensions are determined automatically.
-
-\starttyping
-\externalfigure[cow][factor=max]
-\stoptyping
-
-This figure of a cow will scale to the width or height of
-the text, whichever fits best. Even combinations of settings
-are possible:
-
-\starttyping
-\externalfigure[cow][factor=max,height=.4\textheight]
-\stoptyping
-
-In this case, the cow will scale to either the width o fthe
-text or 40\% of the height of the text, depending on what
-fits best.
-
-As already said, the figures and their characteristics are
-stored in the file \type {texutil.tuf} and can be displayed
-with:
-
-\showsetup{showexternalfigures}
-
-There are two alternatives: \type {a}, \type {b} and~\type
-{c}. The first alternative leaves room for figure
-corrections and annotations, the second alternative is
-somewhat more efficient and places more figures on one page.
-The third alternative puts each figure on its own page. Of
-course one needs to provide the file \type {texutil.tuf} by
-saying:
-
-\starttyping
-texutil --figures *.mps *.jpg *.png
-\stoptyping
-
-Even more straightforward is running \TEXEXEC, for instance:
-
-\starttyping
-texexec --figures=c --pdf *.mps *.jpg *.png
-\stoptyping
-
-This will give you a \PDF\ file of the figures requested,
-with one figure per page.
-
-\section{\TEX||figures}
-\index{figures+tables}
-\index{tables+scaling}
-
-Figures can be scaled. This mechanism can also be used for
-other text elements. These elements are then stored in
-separate files or in a buffer. The next example shows how a
-table is scaled to the pagewidth. The result is typeset in
-\in {figure} [fig:table].
-
-\startbuffer
-\startbuffer[table]
- \starttable[||||||]
- \HL
- \VL \bf factor \VL \bf width \VL
- \bf height \VL \bf width and height \VL
- \bf nothing \VL \SR
- \HL
- \VL \type{max} \VL automatically \VL
- automatically \VL automatically \VL
- width or height \VL \FR
- \VL \type{fit} \VL automatically \VL
- automatically \VL automatically \VL
- width or height \VL \MR
- \VL \type{broad} \VL automatically \VL
- automatically \VL automatically \VL
- width or height \VL \MR
- \VL \type{...} \VL width \VL
- height \VL isometric \VL
- original dimensions \VL \LR
- \HL
- \stoptable
-\stopbuffer
-
-\placefigure
- [here][fig:table]
- {An example of a \TEX\ figure.}
- {\externalfigure[table.buffer][width=\textwidth]}
-
-\placefigure
- {An example of a \TEX\ figure.}
- {\externalfigure[table][width=.5\textwidth, type=buffer]}
-\stopbuffer
-
-% todo: type=buffer and table.buffer are broken in today's context version...
-
-\typebuffer
-
-\getbuffer
-
-With \type{\typesetbuffer} you go a step further: not just one text element
-but a whole document can be typeset and inserted as figure. As an example, the
-second page of some text on A7-paper with landscape orientation is shown in
-\in{figure}[fig:a7-landscape-layout].
-
-\startbuffer
-\startbuffer[a7-buf]
-\setuppapersize[A7, landscape][A7, landscape]
-\showframe
-\input tufte
-\stopbuffer
-
-\placefigure[][fig:a7-landscape-layout]
- {An example for \tex{typesetbuffer}.}
- {\typesetbuffer[a7-buf][page=2]}
-\stopbuffer
-
-% todo: second option to \setuppapersize should not be needed with
-% recent context
-
-\typebuffer
-
-\getbuffer
-
-\section{Extensions of figures}
-\index{figures+extensions}
-
-In the introduction we mentioned different figure formats
-like \EPS\ and \PNG. In most situations the format does not
-have to be specified. On the contrary, format specification
-would mean that we would have to re||specify when we
-switch from \DVI\ to \PDF\ output. The figure format that
-\CONTEXT\ will use depends on the special driver. First
-preference is an outline, second a bitmap.
-
-\METAPOST\ figures, that can have a number as suffix, are
-recognized automatically. \CONTEXT\ will take care of the
-font management when it encounters \METAPOST\ figures. When
-color is disabled, or \RGB\ is to be converted to \CMYK,
-\CONTEXT\ will determine what color specifications have to
-be converted in the \METAPOST\ file. If needed, colors are
-converted to weighted grey scales, that print acceptable on
-black and white printers. In the next step the fonts are
-smuggled into the file.\footnote {Fonts are a problem in
-\METAPOST\ files, since it it up to the postprocessor to
-take care of them. In this respect, \METAPOST\ output is not
-self contained.} In case of \PDF\ output the \METAPOST\ code
-is converted into \PDF\ by \TEX.
-
-If necessary the code needed to insert the graphic is stored
-as a so called object for future re||use. This saves
-processing time, as well as bytes when producing \PDF. You
-can prevent this by setting \type {object=no}.
-
-When \EPS\ and \MPS\ (\METAPOST) figures are processed
-\CONTEXT\ searches for the high resolution bounding box. By
-default the \POSTSCRIPT\ bounding box may have a deviation
-of half a point, which is within the accuracy of our eyes.
-Especially when aligning graphics, such deviations will not
-go unnoticed.
-
-\CONTEXT\ determines the file format automatically, as is the
-case when you use:
-
-\starttyping
-\externalfigure[cow]
-\stoptyping
-
-Sometimes however, as we already explained, the user may
-want to force the format for some reason. This can be done
-by:
-
-\starttyping
-\externalfigure[cow.eps]
-\externalfigure[cow][type=eps]
-\stoptyping
-
-In special cases you can specify in which way figure
-processing takes place. In the next example \CONTEXT\
-determines dimensions asif the file were in \EPS\ format,
-that is, it has a bounding box, but processes the files as
-if it were a \METAPOST\ file. This kind of detailed
-specification is seldom needed.
-
-\starttyping
-\externalfigure[graphic.xyz][type=eps,method=mps]
-\stoptyping
-
-The automatic searching for dimensions can be blocked by
-\type {preset=no}.
-
-\section{Movies}
-\index{movies}
-
-In \CONTEXT\ moving images or \quote {movies} are handled
-just like figures. The file format type is not determined
-automatically yet. This means the user has to specify the
-file format.
-
-\starttyping
-\externalfigure[demo.mov][label=demo,width=4cm,height=4cm,preview=yes]
-\stoptyping
-
-With this setup a preview is shown (the first image of the
-movie). If necessary an ordinary (static) figure can be
-layed over the first movie image with the overlay mechanism.
-
-Movies can be controlled either by clicking on them, or by
-providing navigational tools, like:
-
-\starttyping
-... \goto {start me} [StartMovie{demo}] ...
-\stoptyping
-
-A more detailed discussion on controlling widgets is beyond
-this chapter. Keep in mind that you need to distribute the
-movies along with your document, since they are not included.
-This makes sense, since movies can be pretty large.
-
-\section{Some remarks on figures}
-
-Figures, and photos in particular, have to be produced with
-consistent proportions. The proportions specified in \in
-{figure} [fig:proportions] can be used as a guideline.
-Scaling of photos may cause quality loss.
-
-\def\imageproportion#1:#2%
- {\bgroup
- \dimen0=4em
- \dimen2=#1\dimen0
- \divide\dimen2 by #2
- \framed[width=\dimen0,height=\dimen2]{#1 : #2}%
- \egroup}
-
-\placefigure
- [here][fig:proportions]
- {Some preferred image proportions.}
-\startcombination[3*2]
- {\imageproportion4:5} {}
- {\imageproportion3:4} {}
- {\imageproportion2:3} {}
- {\imageproportion5:4} {}
- {\imageproportion4:3} {}
- {\imageproportion3:2} {}
-\stopcombination
-
-In the background of a figure you typeset a background (see
-\in{figure}[fig:background in figures]). In this example the
-external figures get a background (for a black and white
-reader: a green screen).
-
-\startbuffer
-\def\showacow#1%
- {\externalfigure
- [cow]
- [hfactor=80,background=screen,backgroundscreen=#1]}
-
-\def\showascreen#1%
- {\type{raster=#1}}
-
-\startcombination[3*2]
- {\showacow{0.70}} {\showascreen{0.70}}
- {\showacow{0.75}} {\showascreen{0.75}}
- {\showacow{0.80}} {\showascreen{0.80}}
- {\showacow{0.85}} {\showascreen{0.85}}
- {\showacow{0.90}} {\showascreen{0.90}}
- {\showacow{0.95}} {\showascreen{0.95}}
-\stopcombination
-\stopbuffer
-
-\start
-
-\setupfloats
- [background=color,
- backgroundcolor=green,
- backgroundoffset=3pt]
-
-\placefigure
- [][fig:backgrounds in figures]
- {Some examples of backgrounds in figures.}
- {\getbuffer}
-
-\stop
-
-\startexample
-\starttyping
-\setupfloats
- [background=color,
- backgroundcolor=green,
- backgroundoffset=3pt]
-
-\useexternalfigure [cow]
- [hfactor=80,
- background=screen,
- backgroundscreen=0.75]
-\stoptyping
-\stopexample
-
-Note that we use only one float and that there are six
-external figures. The background of the float is used for
-the complete combination and the background of the external
-figure only for the figure itself.
-
-\stopcomponent
-