Guile Plotutils

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

Guile-Plotutils

This manual is for Guile Plotutils 1.0.1.


Next: , Previous: , Up: Top   [Contents][Index]

Abstract

Guile Plotutils is a Guile package provides access to some
of the functionality of GNU Plotutils.

It supports GNU/Linux, and has been tested with Guile-2.2 and
Guile-3.0. Guile Plotutils is licensed under the GPL3+. This
documentation is licensed under the FDLv1.3+.

If you want to write a Guile application for that creates scientific
plots that look straight out of the late 1990s, this is the way to go.

Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Warning: This is based on GNU Plotutils, which is venerable but unmaintained software last updated decades ago.

Guile Plotutils has two main components: plot and graph.

The plot component expresses GNU Plotutils’s plotting library, which basically does vector graphics onto image surfaces. You might compare it to SVG or the Cairo library.

The graph component expresses GNU Plotutils’s graphing capabilities, which can plot data or functions on a set of xy axes.


Next: , Previous: , Up: Introduction   [Contents][Index]

1.1 The Concept of Operations

Guile Plotutils has two components: one which basically does vector graphics onto image surfaces, and the other which graphs data.

For the plot component, the concept of operations is this

  1. Open a Guile port which will receive the output plot
  2. Create a <plparams> object, and use methods to set parameters that describe the output surface upon which graphics will be drawn.
  3. Create a <plotter> object, initialized with the <plparams> object, and then use its methods to draw upon the surface.
  4. Use appropriate methods to close the <plotter> object and the port, which writes the file.

A simple example could be this below, which opens a bitmap surface, creates a virtual pen, and then draws on the surface. Upon completion, a PNG file is created.

(use-modules (plotutils plot))
(define fp (open-output-file "tmp.png" #:binary #t))
(define param (newplparams))
(setplparam! param "BITMAPSIZE" "400x400")
(define plotter (newpl "png" fp (current-error-port) param))
(openpl! plotter)
(space! plotter 0.0 0.0 1000.0 1000.0)
(linewidth! plotter 0.25)
(pencolorname! plotter "red")
(erase! plotter)
(move! plotter 600.0 300.0)
(closepl! plotter)
(close fp)

The graph component expresses GNU Plotutils’s graphing capabilities, which can plot data or functions on a set of xy axes.

(use-modules (plotutils graph))
(define xvalues (iota 101 0 0.1))
(with-output-to-port ``tmp.png''
  (lambda ()
    (graph xvalues yvalues
           #:output-format ``png''
           #:top-label ``Title''))
  #:binary #t)

Previous: , Up: Introduction   [Contents][Index]

1.2 Installation

In some happy future, you might be able to get this from whatever method your operating system normally uses to download free software.

If you are trying to build this from the Git repository, use git clone to copy the tree onto your computer. After cloning the repository, manually invoke autoreconf to create a configure file.

If you are building from a guile-plotutils.tar.gz, unpack the file.

From there, running configure, then make, then sudo make install will give you a running system.

In the file archives, look for a file named INSTALL for detailed instructions.


Next: , Previous: , Up: Top   [Contents][Index]

2 Tutorial


Next: , Previous: , Up: Tutorial   [Contents][Index]

2.1 Graphing Tutorial

In (plotutils graph), there is one monolithic graphing function called graph with dozens of options. We’ll demonstrate a couple of them in this tutorial.

2.1.1 Graphing Functions

First let’s explore how to graph mathematical functions. Let’s say you have a mathematical function to plot such as “sin(x)”. This example script calls graph with three arguments.

  1. A procedure of one numerical argument that returns a numerical value
  2. The start of the X range
  3. The end of the X range
#!/usr/local/bin/guile \
-e main -s
!#
(use-modules (plotutils graph))

(define (main args)
  (with-output-to-file (cadr args)
    (lambda ()
      (graph sin 0 6.28
             #:output-format (caddr args)
             #:top-label "Sine Wave"))
    #:binary #t))

The script samples a few hundred points of the procedure and plots the result.

sine-wave

You can also call graph with four arguments. In that case, the fourth argument is the step size on the x-axis.

Here’s the same plot with just a dozen sample points

#!/usr/local/bin/guile \
-e main -s
!#
(use-modules (plotutils graph))

(define (main args)
  (with-output-to-file (cadr args)
    (lambda ()
      (graph sin 0 6.28 0.5
             #:output-format (caddr args)
             #:top-label "Poorly Sampled Sine Wave"))
    #:binary #t))
sine-wave2

2.1.2 Graphing Data

In the previous section, we explored how to call graph when the first argument was a function.

In this section we’ll be calling graph using lists of data. When using data, you either call graph with a single list of data, or create an xy plot using two lists of data.

(define x (list -1 0 1 2 3 4 5))
(define y (list 1 2 1 2 1 2 1))
;; Plot the y data with an automatic abscissa
(graph y)
;; Plot the x,y pairs
(graph x y)

You can also plot multiple graphs on the same axes using the merge helper procedure.

(define x1 (list -1 0 1 2 3 4 5))
(define y2 (list  1 2 1 2 1 2 1))
(define x2 (list -1 0 1 2 3 4 5))
 Plotting Tutorial
(define y2 (list  8 7 6 5 4 3 3))
(graph (merge x1 x2) (merge y1 y2))

Previous: , Up: Tutorial   [Contents][Index]

2.2 Plotting Tutorial

The (plotutils plot) library has a set of graphing primitives that are used by the graphing library. They can be used on their own for drawing.

#!/usr/local/bin/guile \
-e main -s
!#
(use-modules (plotutils plot))

(define (draw-c-curve plotter dx dy order)
  (if (>= order 14)
      (contrel! plotter dx dy)
      ;; else
      (begin
	(draw-c-curve plotter (* 0.5 (- dx dy)) (* 0.5 (+ dx dy)) (+ order 1))
	(draw-c-curve plotter (* 0.5 (+ dx dy)) (* 0.5 (- dy dx)) (+ order 1)))))

(define (main args)
  (let ((fp (open-output-file (cadr args) #:binary #t))
        (param (newplparams)))
    (setplparam! param "BITMAPSIZE" "400x400")
    (let ((plotter (newpl (caddr args) fp (current-error-port) param)))
      (openpl! plotter)
      (space! plotter 0.0 0.0 1000.0 1000.0)
      (linewidth! plotter 0.25)
      (pencolorname! plotter "red")
      (erase! plotter)
      (move! plotter 600.0 300.0)
      
      (draw-c-curve plotter 0.0 400.0 0)
      (closepl! plotter)
      (close fp))))

The script draws a fractal pattern of c curves.

plot-curve

Next: , Previous: , Up: Top   [Contents][Index]

3 Reference Guide

The guile-plotutils project provides two Guile modules: (plotutils plot) and (plotutils graph).


Next: , Previous: , Up: Reference Guide   [Contents][Index]

3.1 The Plotting Library

The (plotutils plot) library contains drawing primitives.

There are two important types to note: <plotter> and <plparams>. Roughly speaking, <plparams> describes the surface on which you are drawing – its size and format – and <plotter> describes the state of the virtual pen being used to draw on that surface.

3.1.1 plparams procedures

Procedure: newplparams

This procedure returns a newly allocated <plparams> in a default state.

Procedure: setplparam! plparams parameter value

This procedure modifies the state of a <plparams> object. Both parameter and value are strings. For the available parameters and values See Plotter Parameters.

3.2 plotter procedures

To make a new <plotter> which is on object that keeps the state of the “pen” being used to draw on a surface, use the procedure newpl.

Procedure: newpl type outp errp param

Creates a new <plotter> object. type is the output format that will result from this plotting: one of “X”, “png”, “svg”, “pcl”, “gif”, or “pnm”. Other options may be present depending on how libplot was compiled in the upstrem GNU Plotutils library.

outp and errp should be Guile output ports. outp will receive the output produced by the plotter in the format specified by type. errp will receive error messages.

param is an object of type <plparams> that has set up the “paper” upon which we are drawing.


Next: , Previous: , Up: The Plotting Library   [Contents][Index]

3.2.1 Control functions

The following are the “control functions” in (plotutils plot). They are the basic functions that open, initialize, or close an already-created Plotter. They are listed in the approximate order in which they would be called.

In the current Guile binding, each of these functions takes a <plotter> as its first argument.

Procedure: openpl! plotter

openpl opens a <plotter>, i.e., begins a page of graphics. This resets the Plotter’s drawing attributes to their default values. A negative return value indicates the Plotter could not be opened.

Currently, an X Plotter pops up a new window on an X Window System display for each page of graphics, i.e., with each invocation of openpl!.

Procedure: bgcolor! plotter red green blue

Given a plotter and three integers bgcolor! sets the background color for the Plotter’s graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the background color. Each is an integer in the range 0x00000xffff, i.e., 0…65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white.

bgcolor affects only Plotters that have a notion of background color, i.e., X Plotters, X Drawable Plotters, PNG Plotters, PNM Plotters, and GIF Plotters (all of which produce bitmaps), CGM Plotters, ReGIS Plotters and Metafile Plotters. Its effect is simple: the next time the erase operation is invoked on such a Plotter, its display will be filled with the specified color.

Procedure: bgcolorname! plotter name

bgcolorname! sets the background color for the the graphics display to be name. Unrecognized colors are interpreted as "white". For information on what color names are recognized, see Color Names. A 24-bit RGB color may also be specified as a six-digit hexadecimal string, e.g., "#c0c0c0".

bgcolorname! affects only Plotters that have a notion of background color, i.e., X Plotters, X Drawable Plotters, PNG Plotters, PNM Plotters, and GIF Plotters (all of which produce bitmaps), CGM Plotters, ReGIS Plotters, and Metafile Plotters. Its effect is simple: the next time the erase operation is invoked on such a Plotter, its display will be filled with the specified color.

SVG Plotters and CGM Plotters support "none" as a value for the background color. It will turn off the background: the drawn objects will not be backed by anything. This is useful when the generated SVG or WebCGM file is to be placed on a Web page.

Procedure: erase! plotter

erase! begins the next frame of a multiframe page, by clearing all previously plotted objects from the graphics display, and filling it with the background color (if any).

It is frequently useful to invoke erase! at the beginning of each page, i.e., immediately after invoking openpl!. That is because some Plotters are persistent, in the sense that objects drawn within an openpl!closepl! pair remain on the graphics display even after a new page is begun by a subsequent invocation of openpl!. Currently, only X Drawable Plotters and Tektronix Plotters are persistent. Future releases may support optional persistence for X Plotters also.

On X Plotters and X Drawable Plotters the effects of invoking erase will be altogether different if the Plotter parameter USE_DOUBLE_BUFFERING is set to "yes". In this case, objects will be written to an off-screen buffer rather than to the graphics display, and invoking erase will (1) copy the contents of this buffer to the display, and (2) erase the buffer by filling it with the background color. This ‘double buffering’ feature facilitates smooth animation. See Plotter Parameters.

Procedure: space! plotter x0 y0 x1 y1

space! takes two pairs of arguments, specifying the positions of the lower left and upper right corners of a rectangular window in the user coordinate system that will be mapped to the ‘viewport’: the rectangular portion of the output device that graphics will be drawn in. The default window is a square, with opposite corners (0,0) and (1,1).

In mathematical terms, calling space! sets the affine transformation from user coordinates to device coordinates. That is, it sets the transformation matrix attribute for each object subsequently drawn on the display. space! would usually be invoked at the beginning of each page of graphics, i.e., immediately after the call to openpl!. Additional calls to space! are allowed, and there are several “mapping functions” that also affect the transformation matrix attribute. See Mapping Functions.

Note that the size and location of the viewport depend on the type of Plotter, and on the Plotter parameters that are specified at Plotter creation time. For example, the default viewport used by any Illustrator, Postscript, Fig, PCL, and HP-GL Plotter is a square whose size depends on the Plotter’s page type. See Page and Viewport Sizes.

Procedure: space2! plotter x0 y0 x1 y1 x2 y2

space2! is an extended version of space!. The arguments are the three defining vertices of an parallelogram-shaped window in the user coordinate system. The specified vertices are the lower left, the lower right, and the upper left. This window will be mapped affinely onto the viewport: the rectangular portion of the output device that graphics will be drawn in.

Procedure: havecap plotter s

havecap is not really a control function: it is a query function. It tests whether or not a Plotter, which need not be open, has a specified capability. The return value is 0, 1, or 2, signifying no/yes/maybe. For unrecognized capabilities the return value is zero. Recognized capabilities include "WIDE_LINES" (i.e., the ability to draw lines with a non-default thickness), "DASH_ARRAY" (the ability to draw in arbitrary dashing styles, as requested by the linedash function), "SETTABLE_BACKGROUND" (the ability to set the color of the background), and "SOLID_FILL". The "HERSHEY_FONTS", "PS_FONTS", "PCL_FONTS", and "STICK_FONTS" capabilities indicate whether or not fonts of a particular class are supported. See Text Fonts.

All Plotters except Tektronix Plotters have the "SOLID_FILL" capability, meaning they can fill paths with solid color. Each such Plotter has at least one of the "EVEN_ODD_FILL" and "NONZERO_WINDING_NUMBER_FILL" capabilities. These indicate the supported rules for determining the ‘inside’ of a path.

The ‘maybe’ value is returned for most capabilities by Metafile Plotters, which do no drawing themselves. The output of a Metafile Plotter must be translated to another format, or displayed, by invoking plot.

Procedure: flushpl! plotter

flushpl! flushes (i.e., pushes onward) all previously plotted objects to the graphics display. This is useful only if the affected Plotter is one that does real-time plotting (X Plotters, X Drawable Plotters, ReGIS Plotters, Tektronix Plotters, and Metafile Plotters). It ensures that all previously plotted objects are visible to the user. On Plotters that do not do real-time plotting, this operation has no effect.

Procedure: closepl! plotter

closepl! closes a Plotter, i.e., ends a page of graphics. If a path is in progress, it is first ended and plotted, as if endpath had been called. A negative return value indicates the Plotter could not be closed.

In the present release of (plotutils plot), some Plotters output each page of graphics immediately after it is plotted, i.e., when closepl! is invoked to end the page. That is the case with PCL and HP-GL Plotters, in particular. Plotters that can output only a single page of graphics (PNG, PNM, GIF, SVG, Illustrator, and Fig Plotters) do so immediately after the first page is plotted, i.e., when closepl is invoked for the first time. Postscript and CGM Plotters store all pages of graphics internally, and do not produce output until they are deleted.


Next: , Previous: , Up: The Plotting Library   [Contents][Index]

3.2.2 Object-drawing functions

The following are the “drawing functions” in (plotutils plot). When invoked on a Plotter, these functions cause it to draw objects (paths, text strings, marker symbols, and points [i.e., pixels]) on the associated graphics display.

Paths may be simple or compound. A simple path is a sequence of contiguous line segments, arc segments (either circular or elliptic), and/or Bezier curve segments (either quadratic or cubic). Such simple paths are drawn incrementally, one segment at a time. A simple path may also be a circle, rectangle, or ellipse. A compound path consists of multiple simple paths, which must be nested.

You do not need to begin a path by calling any special function. You should, at least in theory, end a path under construction, and request that it be drawn on the graphics display, by calling endpath!. But the endpath! function is automatically called when any other object is drawn, and at the end of each page of graphics. It is also called automatically when any path-related attribute is changed: for example, when move! is called to change the graphics cursor position. So endpath! seldom needs to be invoked explicitly.

When drawing a compound path, you would end each of its constituent simple paths by calling endsubpath!, and the compound path as a whole by calling endpath!. After each call to endsubpath!, you are allowed to call move! to reposition the graphics cursor, prior to beginning the next simple path. Such a call to move! will not automatically invoke endpath!. This is an exception to the above rule.

In the current Guile binding, each of these functions takes a pointer to a <plotter> as its first argument.

Procedure: alabel! plotter horiz-justify vert-justify s

alabel! takes three arguments horiz_justify (a symbol), vert_justify (a symbol), and s (a string), which specify an ‘adjusted label,’ i.e., a justified text string. The path under construction (if any) is ended and drawn, as if endpath had been called, and the string s is drawn according to the specified justifications. If horiz_justify is equal to the symbols ‘l’, ‘c’, or ‘r’, then the string will be drawn with left, center or right justification, relative to the current graphics cursor position. If vert_justify is equal to symbols ‘b’, ‘x’, ‘c’, ‘C’, or ‘t’, then the bottom, baseline, center, cap line, or top of the string will be placed even with the current graphics cursor position. The graphics cursor is moved to the right end of the string if left justification is specified, and to the left end if right justification is specified.

The string may contain escape sequences of various sorts (see Text String Format), though it should not contain line feeds or carriage returns. In fact it should include only printable characters, from the byte ranges 0x200x7e and 0xa00xff. The string may be plotted at a nonzero angle, if textangle has been called.

Procedure: arc! plotter xc yc x0 y0 x1 y1
Procedure: arcrel! plotter xc yc x0 y0 x1 y1

arc! takes six arguments specifying the beginning (x0, y0), end (x1, y1), and center (xc, yc) of a circular arc. If the graphics cursor is at (x0, y0) and a path is under construction, then the arc is added to the path. Otherwise the current path (if any) is ended and drawn, as if endpath had been called, and the arc begins a new path. In all cases the graphics cursor is moved to (x1, y1).

The direction of the arc (clockwise or counterclockwise) is determined by the convention that the arc, centered at (xc, yc), sweep through an angle of at most 180 degrees. If the three points appear to be collinear, the direction is taken to be counterclockwise. If (xc, yc) is not equidistant from (x0, y0) and (x1, y1) as it should be, it is corrected by being moved to the closest point on the perpendicular bisector of the line segment joining (x0, y0) and (x1, y1). arcrel and farcrel are similar to arc and farc, but use cursor-relative coordinates.

Procedure: bezier2! plotter x0 y0 x1 y1 x2 y2
Procedure: bezier2rel! plotter x0 y0 x1 y1 x2 y2

bezier2! takes six arguments specifying the beginning p0=(x0, y0) and end p2=(x2, y2) of a quadratic Bezier curve, and its intermediate control point p1=(x1, y1). If the graphics cursor is at p0 and a path is under construction, then the curve is added to the path. Otherwise the current path (if any) is ended and drawn, as if endpath! had been called, and the curve begins a new path. In all cases the graphics cursor is moved to p2. bezier2rel! are similar to bezier2! but use cursor-relative coordinates.

The quadratic Bezier curve is tangent at p0 to the line segment joining p0 to p1, and is tangent at p2 to the line segment joining p1 to p2. So it fits snugly into a triangle with vertices p0, p1, and p2.

When using a PCL Plotter to draw Bezier curves on a LaserJet III, you should set the parameter PCL_BEZIERS to "no". That is because the LaserJet III, which was Hewlett–Packard’s first PCL 5 printer, does not recognize the Bezier instructions supported by later PCL 5 printers. See Plotter Parameters.

Procedure: bezier3! plotter x0 y0 x1 y1 x2 y2 x3 y3
Procedure: bezier3rel! plotter x0 y0 x1 y1 x2 y2 x3 y3

bezier3! take eight arguments specifying the beginning p0=(x0, y0) and end p3=(x3, y3) of a cubic Bezier curve, and its intermediate control points p1=(x1, y1) and p2=(x2, y2). If the graphics cursor is at p0 and a path is under construction, then the curve is added to the path. Otherwise the current path (if any) is ended and drawn, as if endpath! had been called, and the curve begins a new path. In all cases the graphics cursor is moved to p3. bezier3rel! are similar to bezier3!, but use cursor-relative coordinates.

The cubic Bezier curve is tangent at p0 to the line segment joining p0 to p1, and is tangent at p3 to the line segment joining p2 to p3. So it fits snugly into a quadrangle with vertices p0, p1, p2, and p3.

When using a PCL Plotter to draw Bezier curves on a LaserJet III, you should set the parameter PCL_BEZIERS to "no". That is because the LaserJet III, which was Hewlett–Packard’s first PCL 5 printer, does not recognize the Bezier instructions supported by later PCL 5 printers. See Plotter Parameters.

Procedure: box! plotter x1 y1 x2 y2
Procedure: boxrel! plotter x1 y1 x2 y2

box! takes four arguments specifying the starting corner (x1, y1) and opposite corner (x2, y2) of a ‘box’, or rectangle. The path under construction (if any) is ended, and the box is drawn as a new path. This path is also ended, and the graphics cursor is moved to the midpoint of the box. boxrel! is similar to box!, but use cursor-relative coordinates.

Procedure: circle! plotter xc yc r
Procedure: circlerel! plotter xc yc r

circle! takes three arguments specifying the center (xc, yc) and radius (r) of a circle. The path under construction (if any) is ended, and the circle is drawn as a new path. This path is also ended, and the graphics cursor is moved to (xc, yc). circlerel! is similar to circle!, but uses cursor-relative coordinates for xc and yc.

Procedure: cont! plotter x y
Procedure: contrel! plotter x y

cont! take two arguments specifying the coordinates (x, y) of a point. If a path is under construction, the line segment from the current graphics cursor position to the point (x, y) is added to it. Otherwise the line segment begins a new path. In all cases the graphics cursor is moved to (x, y). contrel! is similar to cont!, but uses cursor-relative coordinates.

Procedure: ellarc! plotter xc yc x0 y0 x1 y1
Procedure: ellarcrel! plotter xc yc x0 y1 x1 y1

ellarc! takes six arguments specifying the three points pc=(xc,yc), p0=(x0,y0), and p1=(x1,y1) that define a so-called quarter ellipse. This is an elliptic arc from p0 to p1 with center pc. If the graphics cursor is at point p0 and a path is under construction, the quarter-ellipse is added to it. Otherwise the path under construction (if any) is ended and drawn, as if endpath had been called, and the quarter-ellipse begins a new path. In all cases the graphics cursor is moved to p1.

The quarter-ellipse is an affinely transformed version of a quarter circle. It is drawn so as to have control points p0, p1, and p0+p1-pc. This means that it is tangent at p0 to the line segment joining p0 to p0+p1-pc, and is tangent at p1 to the line segment joining p1 to p0+p1-pc. So it fits snugly into a triangle with these three control points as vertices. Notice that the third control point is the reflection of pc through the line joining p0 and p1. ellarcrel!is similar to ellarc! and fellarc, but use cursor-relative coordinates.

Procedure: ellipse! plotter xc yc rx ry angle
Procedure: ellipserel! plotter xc yc rx ry angle

ellipse! takes five arguments specifying the center (xc, yc) of an ellipse, the lengths of its semiaxes (rx and ry), and the inclination of the first semiaxis in the counterclockwise direction from the x axis in the user coordinate system. The path under construction (if any) is ended, and the ellipse is drawn as a new path. This path is also ended, and the graphics cursor is moved to (xc, yc). ellipserel! is similar to ellipse!, but uses cursor-relative coordinates.

Procedure: endpath! plotter

endpath! terminates the path under construction, if any, and draws it. It also removes the path from the current graphics context, so that a new path may be constructed.

The path under construction may be a simple path, or a compound path constructed with the aid of endsubpath! (see below). A simple path is constructed by one or more successive calls to cont!, line1, arc!, ellarc!, bezier2!, bezier3!. A simple path may also be constructed by a single call to circle!, ellipse!, or box!.

It is often not necessary to call endpath! explicitly, since it is frequently called automatically. It will be called if any non-path object is drawn, if any path-related drawing attribute is set, or if move or fmove is invoked to set the cursor position. It will also be called if restorestate is called to pop a graphics context off the stack, and if closepl is called to end a page of graphics. So it is seldom necessary to call endpath explicitly. However, if a Plotter plots objects in real time, calling endpath will ensure that a completed path is drawn on the graphics display without delay.

Procedure: endsubpath! plotter

endsubpath! terminates the simple path under construction, if any, and signals that the construction of the next simple path in a compound path is to begin. Immediately after endsubpath! is called, it is permissible to call move! to reposition the graphics cursor. (At other times in the drawing of a compound path, calling move! would force a premature end to the path, by automatically invoking endpath!.)

Procedure: label! plotter s

label! takes a single string argument s and draws the text contained in s at the current graphics cursor position. The text is left justified, and the graphics cursor is moved to the right end of the string. This function is provided for backward compatibility; the function call label!(s) is equivalent to alabel!(‘l’,‘x’,s).

Procedure: labelwidth! plotter s

labelwidth! is not really an object-drawing function: it is a query functions. It computes and returns the width of a string in the current font, in the user coordinate system. The string is not drawn.

Procedure: line! plotter x1 y1 x2 y2
Procedure: linerel! plotter x1 y1 x2 y2

line! takes four arguments specifying the start point (x1, y1) and end point (x2, y2) of a line segment. If the graphics cursor is at (x1, y1) and a path is under construction, the line segment is added to it. Otherwise the path under construction (if any) is ended and drawn, as if endpath had been called, and the line segment begins a new path. In all cases the graphics cursor is moved to (x2, y2). linerel! is similar to line!, but use cursor-relative coordinates.

Procedure: marker! plotter x y type size
Procedure: markerrel! plotter x y type size

marker! takes four arguments specifying the position (x,y) of a marker symbol, its type, and its font size in user coordinates. The path under construction (if any) is ended and drawn, as if endpath! had been called, and the marker symbol is plotted. The graphics cursor is moved to (x,y). markerrel! are similar to marker! and fmarker, but use cursor-relative coordinates for the position (x,y).

A marker symbol is a visual representation of a point, which is visible on all types of Plotter. In this it differs from the points produced by the point! function (see below). Marker symbol types 0…31 are taken from a standard set, and marker symbol types 32 and above are interpreted as the index of a character in the current text font. See Marker Symbols.

Procedure: point! plotter x y
Procedure: pointrel! plotter x y

point! takes two arguments specifying the coordinates (x, y) of a point. The path under construction (if any) is ended and drawn, as if endpath! had been called, and the point is plotted. The graphics cursor is moved to (x, y). pointrel! is similar to point!, but use cursor-relative coordinates.

‘Point’ is a misnomer. Any Plotter that produces a bitmap, i.e., an X Plotter, an X Drawable Plotter, a PNG Plotter, a PNM Plotter, or a GIF Plotter, draws a point as a single pixel. Most other Plotters draw a point as a small solid circle, usually so small as to be invisible. So point should really be called pixel.


Next: , Previous: , Up: The Plotting Library   [Contents][Index]

3.2.3 Attribute-setting functions

The following are the “attribute functions” in (plotutils plot). When invoked on a Plotter, these functions set its drawing attributes, or save them or restore them. Path-related attributes include graphics cursor position, pen color, fill color, fill rule, line thickness, line style, cap style, join style, miter limit, and transformation matrix. Text-related attributes include pen color, font name, font size, text angle, and transformation matrix.

Setting any path-related drawing attribute automatically terminates and draws the path under construction (if any), as if the endpath! operation had been invoked. The ‘orientation’ attribute (clockwise/counterclockwise), which affects circles, ellipses, and boxes, is an exception to this. The exception allows a compound path to include circles, ellipses, and boxes with different orientations.

In the current Guile binding, each of these functions takes a <plotter> as its first argument.

Procedure: capmod! plotter s

capmod! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the cap mode (i.e., cap style) for all paths subsequently drawn on the graphics display. Recognized styles are "butt" (the default), "round", and "projecting". The three styles are visibly distinct only if the line thickness is fairly large. Butt caps do not extend beyond the end of the path. The other two kinds do, however. Round caps are filled semicircles, and projecting caps are filled rectangular regions that extend a distance equal to half the line width beyond the end of the path.

PNG, PNM, GIF, PCL, and HP-GL Plotters support a fourth cap mode, "triangular". (For all but PCL and HP-GL Plotters, the support is currently only partial.) Plotters other than these treat "triangular" as equivalent to "round".

This function has no effect on ReGIS or Tektronix Plotters. Also, it has no effect on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default), or on CGM Plotters if the parameter CGM_MAX_VERSION is set to a value less than "3". See Plotter Parameters.

Procedure: color! plotter red green blue

color! is a convenience function. Calling color! is equivalent to calling both pencolor! and fillcolor!, to set both the the pen color and fill color of all objects subsequently drawn on the graphics display. Note that the physical fill color depends also on the fill level, which is specified by calling filltype!.

Procedure: colorname! plotter name

colorname! is a convenience function. Calling colorname! is equivalent to calling both pencolorname! and fillcolorname!, to set both the the pen color and fill color of all objects subsequently drawn on the graphics display. Note that the physical fill color depends also on the fill level, which is specified by calling filltype!.

Procedure: fillcolor! plotter red green blue

fillcolor! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the fill color for all paths subsequently drawn on the graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the fill color. Each is an integer in the range 0x00000xffff, i.e., 0…65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white. Note that the physical fill color depends also on the fill level, which is specified by calling filltype!.

Procedure: fillcolorname! plotter name

fillcolorname! sets the fill color of all paths subsequently drawn on the graphics display to be name. Unrecognized colors are interpreted as "black". For information on what color names are recognized, see Color Names. A 24-bit RGB color may also be specified as a six-digit hexadecimal string, e.g., "#c0c0c0".

Note that the physical fill color depends also on the fill level, which is specified by calling filltype!.

Procedure: fillmod! plotter s

fillmod! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the fill mode, i.e., fill rule, for all paths subsequently drawn on the graphics display. The fill rule affects only compound paths and self-intersecting simple paths: it determines which points are ‘inside’. Two rules are supported: "even-odd" (the default for all Plotters), and "nonzero-winding". For the distinction, see the Postscript Language Reference Manual. "alternate" is an alias for "even-odd" and "winding" is an alias for "nonzero-winding".

CGM, Fig, and ReGIS Plotters do not support the "nonzero-winding" rule, because the CGM, Fig, and ReGIS vector graphics formats do not support it. Also, HP-GL Plotters do not support "nonzero-winding" if HPGL_VERSION is set to a value less than "2" (the default). See Plotter Parameters.

The LaserJet III, which was Hewlett–Packard’s first PCL 5 printer, did not support the nonzero-winding fill rule. However, all later PCL 5 printers from Hewlett–Packard support it.

Procedure: filltype! plotter level

filltype! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the fill level for all subsequently drawn paths. A value of 0 for level specifies no filling. This is the default. A value of 1 specifies 100% filling: the fill color will be the color previously specified by calling fillcolor! or fillcolorname!.

As a convenience to the user, level may be set to any value in the range 0x00000xffff, i.e., 0…65535. Any nonzero value will produce filling. If level=0xffff, the fill color will be white. Values in the range 0x00010xffff are interpreted as specifying a desaturation, or gray level. For example, 0x8000 specifies 50% filling (the fill color will be half-way between the color specified by calling fillcolor or fillcolorname, and white).

To draw the region bounded by a path in an edgeless way, you would call filltype to turn on the filling of the interior, and pentype to turn off the drawing of the boundary.

Tektronix Plotters do not support filling, and HP-GL Plotters support filling of arbitrary paths only if the parameter HPGL_VERSION is equal to "1.5" or "2" (the default). (If the version is "1" then only circles and rectangles aligned with the coordinate axes may be filled.) Opaque filling, including white filling, is supported only if the parameter HPGL_VERSION is "2" and the parameter HPGL_OPAQUE_MODE is "yes" (the default). See Plotter Parameters.

Procedure: miterlimit! plotter limit

miterlimit! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the miter limit for all paths subsequently drawn on the graphics display. The miter limit controls the treatment of corners, if the join mode is set to "miter" (the default). At a join point of a path, the ‘miter length’ is defined to be the distance between the inner corner and the outer corner. The miter limit is the maximum value that will be tolerated for the miter length divided by the line thickness. If this value is exceeded, the miter will be cut off: the "bevel" join mode will be used instead.

Examples of typical values for limit are 10.43 (the default, which cuts off miters if the join angle is less than 11 degrees), 2.0 (the same, for 60 degrees), and 1.414 (the same, for 90 degrees). In general, the miter limit is the cosecant of one-half the minimum angle for mitered joins. The minimum meaningful value for limit is 1.0, which converts all mitered joins to beveled joins, irrespective of join angle. Specifying a value less than 1.0 resets the limit to the default.

This function has no effect on X Drawable Plotters or X Plotters, since the X Window System miter limit, which is also 10.43, cannot be altered. It also has no effect on Tektronix, ReGIS, or Fig Plotters, or on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default). See Plotter Parameters. The miter limit used by HP-GL or PCL Plotters is always rounded to the closest integer, downward.

Procedure: fontname! plotter font-name

fontname! takes a single case-insensitive string argument, font-name, specifying the name of the font to be used for all text strings subsequently drawn on the graphics display. (The font for plotting strings is fully specified by calling fontname!, fontsize!, and textangle!.) The size of the font in user coordinates is returned.

The default font name depends on the type of Plotter. It is "Helvetica" for all Plotters except for PCL Plotters, for which it is "Univers", and PNG, PNM, GIF, HP-GL, ReGIS, Tektronix and Metafile Plotters, for which it is "HersheySerif". If the argument font-name is NULL or the empty string, or the font is not available, the default font name will be used. Which fonts are available also depends on the type of Plotter; for a list of all available fonts, see Text Fonts.

Procedure: fontsize! plotter size

fontsize! takes a single argument, interpreted as the size, in the user coordinate system, of the font to be used for all text strings subsequently drawn on the graphics display. (The font for plotting strings is fully specified by calling fontname!, fontsize!, and textangle!.) The size of the font in user coordinates is returned.

A negative value for size sets the size to the default, which depends on the type of Plotter. Typically, the default font size is 1/50 times the size (i.e., minimum dimension) of the display. The interpretation of zero font size is also Plotter-dependent (most Plotters do not draw text strings if the font size is zero).

Procedure: joinmod! plotter s

joinmod! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the join mode (i.e., join style) for all paths subsequently drawn on the graphics display. Recognized styles are "miter" (the default), "round", and "bevel". The three styles are visibly distinct only if the line thickness is fairly large. Mitered joins are sharp, rounded joins are round, and beveled joins are squared off. However, unusually sharp joins are never mitered: instead, they are beveled. The angle at which beveling replaces mitering may be specified by calling miterlimit!.

PNG, PNM, GIF, PCL, and HP-GL Plotters support a fourth join mode, "triangular". Other Plotters treat "triangular" as equivalent to "round".

This function has no effect on ReGIS or Tektronix Plotters. Also, it has no effect on HP-GL Plotters if the parameter HPGL_VERSION is set to a value less than "2" (the default), or on CGM Plotters if the parameter CGM_MAX_VERSION is set to a value less than "3". See Plotter Parameters.

Procedure: linedash! plotter n dashes offset

linedash! terminates and draws the path under construction (if any), as if endpath! had been called, and set the line style for all paths subsequently drawn on the graphics display. They provide much finer control of dash patterns than the linemod! function (see below) provides. dashes should be an array of length n. Its elements, which should be positive, are interpreted as distances in the user coordinate system. Along any path, circle, or ellipse, the elements dashes[0]…dashes[n-1] alternately specify the length of a dash and the length of a gap between dashes. When the end of the array is reached, the reading of the array wraps around to the beginning. If the array is empty, i.e., n equals zero, there is no dashing: the drawn line is solid.

The offset argument specifies the ‘phase’ of the dash pattern relative to the start of the path. It is interpreted as the distance into the dash pattern at which the dashing should begin. For example, if offset equals zero then the path will begin with a dash, of length dashes[0] in user space. If offset equals dashes[0] then the path will begin with a gap of length dashes[1], and so forth. offset is allowed to be negative.

Not all Plotters fully support linedash!. PCL and HP-GL Plotters cannot dash with a nonzero offset, and in the dash patterns used by X and X Drawable Plotters, each dash or gap has a maximum length of 255 pixels. linedash and flinedash have no effect at all on Tektronix, ReGIS, and Fig Plotters. Also, they have no effect on HP-GL Plotters for which the parameter HPGL_VERSION is less than "2" (the default), or on CGM Plotters for which the parameter CGM_MAX_VERSION is less than "3". For information on Plotter parameters, see Plotter Parameters.

Warning: If the transformation from the user coordinate system to the device coordinate system is anisotropic, each dash pattern should ideally be drawn on the graphics display with a length that depends on its direction. But currently, only SVG and Postscript Plotters do this. Other Plotters always draw any specified dash pattern with the same length, irrespective of its direction. The length that is used is the minimum length, in the device coordinate system, that can correspond to the specified dash pattern length in the user coordinate system.

Procedure: linemod! plotter s

linemod! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the line style for all paths subsequently drawn on the graphics display. The supported line styles are "solid", "dotted", "dotdashed", "shortdashed", "longdashed", "dotdotdashed", "dotdotdotdashed", and "disconnected".

The first seven correspond to the following dash patterns:

"solid"             --------------------------------
"dotted"            -   -   -   -   -   -   -   -   
"dotdashed"         ----   -   ----   -   ----   -
"shortdashed"       ----    ----    ----    ----    
"longdashed"        -------    -------    -------    
"dotdotdashed"      ----   -   -   ----   -   -
"dotdotdotdashed"   ----   -   -   -   ----   -   -   -

In the preceding patterns, each hyphen stands for one line thickness. This is the case for sufficiently thick lines, at least. So for sufficiently thick lines, the distance over which a dash pattern repeats is scaled proportionately to the line thickness.

The "disconnected" line style is special. A "disconnected" path is rendered as a set of filled circles, each of which has diameter equal to the nominal line thickness. One of these circles is centered on each of the juncture points of the path (i.e., the endpoints of the line segments or arcs from which it is constructed). Circles and ellipses with "disconnected" line style are invisible. Disconnected paths are not filled; this includes circles and ellipses.

All line styles are supported by all Plotters, with the following exceptions. HP-GL Plotters do not support the "dotdotdotdashed" style unless the parameter HPGL_VERSION is set to "2" (the default). Tektronix Plotters do not support the "dotdotdotdashed" style, and do not support the "dotdotdashed" style unless the parameter TERM is set to "kermit". See Plotter Parameters.

Procedure: linewidth! plotter size

linewidth! terminates and draws the path under construction (if any), as if endpath! had been called, and set the thickness, in the user coordinate system, of all paths subsequently drawn on the graphics display. A negative value resets the thickness to the default. The default thickness depends on the type of Plotter. For most Plotters, it is 1/850 times the size of the viewport, i.e., the drawn-on portion of the display. (Here ‘size’ means minimum dimension.) But for Plotters that produce bitmaps, i.e., X Plotters, X Drawable Plotters, PNG Plotters, PNM Plotters, and GIF Plotters, it is zero.

By convention, a zero-thickness line is the thinnest line that can be drawn. However, the drawing editors idraw and xfig treat zero-thickness lines as invisible. So when producing editable graphics with a Postscript or Fig Plotter, using a zero line thickness may not be desirable.

Tektronix and ReGIS Plotters do not support drawing with other than a default thickness, and HP-GL Plotters do not support doing so if the parameter HPGL_VERSION is set to a value less than "2" (the default; see Plotter Parameters).

Warning: If the transformation from the user coordinate system to the device coordinate system is anisotropic, each line segment in a polygonal path should ideally be drawn on the graphics display with a thickness that depends on its direction. But currently, only SVG and Postscript Plotters do this. Other Plotters draw all line segments in a path with the same thickness. The thickness that is used is the minimum thickness, in the device coordinate system, that can correspond to the specified line thickness in the user coordinate system.

Procedure: move! plotter x y
Procedure: moverel! plotter x y

move! takes two arguments specifying the coordinates (x, y) of a point to which the graphics cursor should be moved. The path under construction (if any) is ended and drawn, as if endpath had been called, and the graphics cursor is moved to (x, y). This is equivalent to lifting the pen on a plotter and moving it to a new position, without drawing any line. moverel! is similar to move!, but use cursor-relative coordinates.

When a new page of graphics is begun by invoking openpl!, the cursor is initially at the point (0,0) in user space. Most of the drawing functions reposition the cursor. See Drawing Functions.

Procedure: orientation! plotter direction

orientation! sets the orientation for all circles, ellipses, and boxes subsequently drawn on the graphics display. direction must be 1, meaning counterclockwise, or -1, meaning clockwise. The default is 1.

orientation! will have a visible effect on a circle, ellipse, or box only if it is dashed, or if it is one of the simple paths in a filled compound path. Its effects on filling, when the "nonzero-winding" fill rule is used, are dramatic, since it is the orientation of each simple path in a compound path that determines which points are ‘inside’ and which are ‘outside’.

Procedure: pencolor! plotter red green blue

pencolor! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the pen color for all objects subsequently drawn on the graphics display, using a 48-bit RGB color model. The arguments red, green and blue specify the red, green and blue intensities of the pen color. Each is an integer in the range 0x00000xffff, i.e., 0…65535. The choice (0, 0, 0) signifies black, and the choice (65535, 65535, 65535) signifies white.

HP-GL Plotters support drawing with a white pen only if the value of the parameter HPGL_VERSION is "2" (the default), and the value of the parameter HPGL_OPAQUE_MODE is "yes" (the default). See Plotter Parameters.

Procedure: pencolorname! plotter name

pencolorname sets the pen color of all objects subsequently drawn on the graphics display to be name. Unrecognized colors are interpreted as "black". For information on what color names are recognized, see Color Names. A 24-bit RGB color may also be specified as a six-digit hexadecimal string, e.g., "#c0c0c0".

HP-GL Plotters support drawing with a white pen only if the value of the parameter HPGL_VERSION is "2" (the default) and the value of the parameter HPGL_OPAQUE_MODE is "yes" (the default). See Plotter Parameters.

Procedure: pentype! plotter level

pentype! terminates and draws the path under construction (if any), as if endpath! had been called, and sets the pen level for all subsequently drawn paths. A value of 1 for level specifies that an outline of each of these objects should be drawn, in the color previously specified by calling pencolor or pencolorname. This is the default. A value of 0 specifies that outlines should not be drawn.

To draw the region bounded by a path in an edgeless way, you would call pentype! to turn off the drawing of the boundary, and filltype! to turn on the filling of the interior.

pentype! also affects the drawing of marker symbols and points, i.e., pixels. A value of 0 specifies that they should not be drawn.

Procedure: restorestate! plotter

restorestate! pops the current graphics context off the stack of drawing states. The graphics context consists largely of libplot’s drawing attributes, which are set by the attribute functions documented in this section. So popping off the graphics context restores the drawing attributes to values they previously had. A path under construction is regarded as part of the graphics context. For this reason, calling restorestate automatically calls endpath to terminate and draw the path under construction, if any. All graphics contexts on the stack are popped off when closepl! is called, as if restorestate! had been called repeatedly.

Procedure: savestate! plotter

savestate! pushes the current graphics context onto the stack of drawing states. The graphics context consists largely of libplot’s drawing attributes, which are set by the attribute functions documented in this section. A path under construction, if any, is regarded as part of the graphics context. That is because paths may be drawn incrementally, one line segment or arc at a time. The new graphics context created by savestate! will contain no path. When the previous graphics context is returned to by calling restorestate, the path previously under construction may be continued.

Procedure: textangle! plotter angle

textangle! take one argument, which specifies the angle in degrees counterclockwise from the x (horizontal) axis in the user coordinate system, for text strings subsequently drawn on the graphics display. The default angle is zero. (The font for plotting strings is fully specified by calling fontname, fontsize, and textangle.) The size of the font for plotting strings, in user coordinates, is returned.

Warning: Some X Window System displays do not generate or display rotated fonts correctly. In effect, they only support a zero rotation angle.


Previous: , Up: The Plotting Library   [Contents][Index]

3.2.4 Mapping functions

The following are the “mapping functions” in (plotutils plot). When invoked on a <plotter>, they affect the affine transformation it employs to map the user coordinate system to the device coordinate system. That is, they affect the transformation matrix attribute of objects subsequently drawn on the graphics display.

The names of these functions resemble those of the corresponding functions in the Postscript language. For information on how to use them to draw graphics efficiently, consult any good book on Postscript programming, or the Postscript Language Reference Manual.

Each of these functions, if called, terminates and draws the path under construction (if any), as if endpath! had been called.

In the current Guile binding, each of these functions takes a <plotter> as its first argument.

Procedure: setmatrix! plotter m0 m1 m2 m3 tx ty

Use the Postscript-style transformation matrix [m0 m1 m2 m3 tx ty] as the transformation matrix from user space to NDC (normalized device coordinate) space. This matrix determines the transformation matrix from user space to unnormalized device space, i.e., sets the transformation matrix attribute that will be used when subsequently drawing objects on the graphics display.

In NDC space, the graphics display (i.e., viewport) has corners (0,0), (1,0), (1,1), and (0,1). For information on the size of the graphics display in physical units, see Page and Viewport Sizes.

The default transformation matrix from user space to NDC space is [1 0 0 1 0 0], which means that by default, user coordinates are the same as NDC coordinates. This transformation matrix is also altered by space!, space2!, and by the following functions.

Procedure: concat m0 m1 m2 m3 tx ty

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [m0 m1 m2 m3 tx ty]. Equivalently, apply the linear transformation defined by the two-by-two matrix [m0 m1 m2 m3] to the user coordinate system, and then translate by tx units in the x direction and ty units in the y direction.

concat! is a wrapper around the more fundamental fsetmatrix function. The following three functions (frotate, fscale, translate!) are convenience functions that are special cases of concat!.

Procedure: rotate! plotter theta

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [cos(theta) sin(theta) -sin(theta) cos(theta) 0 0]. Equivalently, rotate the user coordinate system axes about their origin by theta degrees counterclockwise, with respect to their former orientation. The position of the user coordinate origin and the size of the x and y units remain unchanged.

Procedure: scale! plotter sx sy

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [sx 0 0 sy 0 0]. Equivalently, make the x and y units in the user coordinate system be the size of sx and sy units in the former user coordinate system. The position of the user coordinate origin and the orientation of the coordinate axes are unchanged.

Procedure: translate! plotter tx ty

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [0 0 0 0 tx ty]. Equivalently, move the origin of the user coordinate system by tx units in the x direction and ty units in the y direction, relative to the former user coordinate system. The size of the x and y units and the orientation of the coordinate axes are unchanged.


Next: , Previous: , Up: Reference Guide   [Contents][Index]

3.3 Plotter parameters

In designing the libplot library, every effort was made to make the Plotter interface independent of the type of Plotter. To the extent that Plotters display individual (i.e., instance-specific) behavior, that behavior is captured by a manageable number of Plotter parameters. For most parameters, the value is a string.

The parameter values of any Plotter are constant over the lifetime of the Plotter, and are specified when the Plotter is created. In the Guile binding, a value for any parameter is specified by calling the setplparam! function. The setplparam! function acts on a <plparams> object, which encapsulates Plotter parameters. When a <plotter> is created by calling newpl, a <plparams> object is passed as the final argument.

If at <plotter> creation time a parameter is not specified, its default value will be used, unless the parameter is string-valued and there is an environment variable of the same name, in which case the value of that environment variable will be used. This rule increases run-time flexibility: an application programmer may allow non-critical <plotter> parameters to be specified by the user via environment variables.

The following are the currently recognized parameters (unrecognized ones are ignored). The most important ones are DISPLAY, which affects X Plotters, BITMAPSIZE, which affects X Plotters, PNG Plotters, PNM Plotters, and GIF Plotters, PAGESIZE, which affects Illustrator, Postscript, CGM, Fig, and HP-GL Plotters, and ROTATION, which affects all Plotters except Metafile Plotters. These four parameters are listed first and the others alphabetically. Most of the remaining parameters, such as the several whose names begin with "HPGL", affect only a single type of Plotter.

DISPLAY

(Default NULL.) The X Window System display on which the graphics display will be popped up, as an X window. This is relevant only to X Plotters.

BITMAPSIZE

(Default "570x570".) The size of the graphics display (i.e., the viewport) in terms of pixels. This is relevant only to X Plotters, PNG Plotters, PNM Plotters, and GIF Plotters. For X Plotters, the value of this parameter will automatically, if it is not set, be taken from the X resource Xplot.geometry. That is for backward compatibility.

X Plotters support precise positioning of the graphics display. For example, if BITMAPSIZE is "570x570+0+0" then it will be positioned in the upper left corner of the X Window System display.

PAGESIZE

(Default "letter".) The page type, which determines the size of the graphics display (i.e., the viewport) used by the Plotter. This is relevant only to SVG, Illustrator, Postscript, CGM, Fig, PCL, and HP-GL Plotters. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"…"a4" or ANSI page size in the range "a"…"e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also.

For Illustrator, Postscript, PCL and Fig Plotters, the graphics display will be, by default, a square region centered on the specified page. (For example, it will be a centered 8in square if PAGESIZE is "letter".) For HP-GL Plotters, it will be a square region of the same size, but will not by default be centered. SVG format and WebCGM format have no notion of the Web page on which the graphics display will ultimately be positioned. They do have a notion of default display size, though this will normally be overridden when the SVG or WebCGM file is placed on a Web page. For this default display size, SVG and CGM Plotters will use the same graphics display size that is used by other Plotters.

For the default size (and location) of the graphics display for each page type, see Page and Viewport Sizes. You do not need to use the default size, since either or both of its dimensions can be specified explicitly. For example, PAGESIZE could be specified as "letter,xsize=4in", or "a4,xsize=10cm,ysize=15cm". The dimensions are allowed to be negative (a negative dimension results in a reflection).

For Plotters other than SVG and CGM Plotters, the position of the graphics display on the page, relative to its default position, can be adjusted by specifying an offset vector. For example, PAGESIZE could be specified as "letter,yoffset=1.2in", or "a4,xoffset=-5mm,yoffset=2.0cm". Inches, centimeters, and millimeters are the supported units. The "xoffset" and "yoffset" options may be used in conjunction with "xsize" and "ysize".

It is also possible to position the graphics display precisely, by specifying the location of its lower left corner relative to the lower left corner of the page. For example, PAGESIZE could be specified as "letter,xorigin=2in,yorigin=3in", or "a4,xorigin=0.5cm,yorigin=0.5cm". The "xorigin" and "yorigin" options may be used in conjunction with "xsize" and "ysize". SVG and WebCGM Plotters ignore the "xoffset", "yoffset", "xorigin", and "yorigin" options, since SVG format and WebCGM format have no notion of the Web page on which the graphics display will ultimately be positioned.

ROTATION

(Default "0.0".) Relevant to all Plotters other than Metafile Plotters, which have no output device. The angle, in degrees, by which the graphics display (i.e., the viewport) should be rotated, relative to its default orientation. The rotation is counterclockwise.

A rotated viewport does not change the position of its four corners. Rather, the graphics are rotated within it. If the viewport is rectangular rather than square, this ‘rotation’ necessarily includes a rescaling.

This parameter is useful for switching between portrait and landscape orientations. Internally, it determines the affine transformation from NDC (normalized device coordinate) space to device space.

BG_COLOR

(Default "white".) The initial background color of the graphics display, when drawing each page of graphics. This is relevant to X Plotters, PNG Plotters, PNM Plotters, GIF Plotters, CGM Plotters, ReGIS Plotters, and Metafile Plotters; also to X Drawable Plotters (for the last, the background color shows up only if erase is invoked). For information on what color names are recognized, see Color Names. The background color may be changed at any later time by invoking the bgcolor (or bgcolorname) and erase operations.

SVG Plotters and CGM Plotters support "none" as a value for the background color. It will turn off the background: the drawn objects will not be backed by anything. This is useful when the generated SVG or WebCGM file is to be placed on a Web page.

CGM_ENCODING

(Default "binary".) Relevant only to CGM Plotters. "binary" means that the CGM output should use the binary encoding. "clear_text" means that the CGM output should use a human-readable encoding. The WebCGM profile requires that the binary encoding be used, but many CGM viewers and interpreters can also parse the clear text encoding. The third standard CGM encoding, "character", is not currently supported.

CGM_MAX_VERSION

(Default "4".) Relevant only to CGM Plotters. An upper bound on the version number of CGM format that is produced. Many older CGM interpreters and viewers, such as the ones built into Microsoft Office and other commercial software, only support version 1 CGM files. For fully adequate handling of fonts and line styles, version 3 is necessary. By default, the present release of libplot produces version 3 CGM files, i.e., it does not use version 4 features.

EMULATE_COLOR

(Default "no".) Relevant to all Plotters. "yes" means that each color in the output should be replaced by an appropriate shade of gray. The well known formula for CIE luminance, namely 0.212671R + 0.715160G + 0.072169B, is used.

This parameter is seldom useful, except when using a PCL Plotter to prepare output for a monochrome PCL 5 device. Many monochrome PCL 5 devices, such as monochrome LaserJets, do a poor job of emulating color on their own. They usually map HP-GL/2’s seven standard pen colors, including even yellow, to black.

GIF_ANIMATION

(Default "yes".) Relevant only to GIF Plotters. "yes" means that the erase operation will have special semantics: with the exception of its first invocation, it will act as a separator between successive images in the written-out pseudo-GIF file. "no" means that erase should act as it does on other Plotters that do not write graphics in real time, i.e., it should erase the image under construction by filling it with the background color. If "no" is specified, the pseudo-GIF file will contain only a single image.

GIF_DELAY

(Default "0".) Relevant only to GIF Plotters. The delay, in hundredths of a second, after each image in a written-out animated pseudo-GIF file. The value should be an integer in the range "0"…"65535".

GIF_ITERATIONS

(Default "0".) Relevant only to GIF Plotters. The number of times that an animated pseudo-GIF file should be ‘looped’. The value should be an integer in the range "0"…"65535".

HPGL_ASSIGN_COLORS

(Default "no".) Relevant only to HP-GL Plotters, and only if the value of HPGL_VERSION is "2". "no" means to draw with a fixed set of pens, specified by setting the HPGL_PENS parameter. "yes" means that pen colors will not restricted to the palette specified in HPGL_PENS: colors will be assigned to “logical pens” in the range #1…#31, as needed. Other than color LaserJet printers and DesignJet plotters, not many HP-GL/2 devices allow the assignment of colors to logical pens. In particular, HP-GL/2 pen plotters do not. So this parameter should be used with caution.

HPGL_OPAQUE_MODE

(Default "yes".) Relevant only to HP-GL Plotters, and only if the value of HPGL_VERSION is "2". "yes" means that the HP-GL/2 output device should be switched into opaque mode, rather than transparent mode. This allows objects to be filled with opaque white and other opaque colors. It also allows the drawing of visible white lines, which by convention are drawn with pen #0. Not all HP-GL/2 devices support opaque mode or the use of pen #0 to draw visible white lines. In particular, HP-GL/2 pen plotters do not. Some older HP-GL/2 devices reportedly malfunction if asked to switch into opaque mode. If the output of an HP-GL Plotter is to be sent to such a device, a "no" value is recommended.

HPGL_PENS

(Default "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan" if the value of HPGL_VERSION is "1.5" or "2" and "1=black" if the value of HPGL_VERSION is "1". Relevant only to HP-GL Plotters. The set of available pens; the format should be self-explanatory. The color for any pen in the range #1…#31 may be specified. For information on what color names are recognized, see Color Names. Pen #1 must always be present, though it need not be black. Any pen in the range #2…#31 may be omitted.

HPGL_ROTATE

(Default "0".) Relevant only to HP-GL Plotters. The angle, in degrees, by which the graphics display (i.e., the viewport) should be rotated on the page relative to the default orientation. Recognized values are "0", "90", "180", and "270"; "no" and "yes" are equivalent to "0" and "90" respectively. "180" and "270" are supported only if HPGL_VERSION is "2".

The rotation requested by HPGL_ROTATE is different from the sort requested by the ROTATION parameter. ROTATION rotates the graphics display in place, but HPGL_ROTATE both rotates the graphics display and moves its lower left corner toward another corner of the page. Altering the plotting area in such a way is supported by the HP-GL language.

The HPGL_ROTATE parameter facilitates switching between portrait and landscape orientations. For HP-GL devices that is frequently a concern, since some HP-GL devices (“plotters”) draw with a default landscape orientation, while others (“printers”) draw with a default portrait orientation. There is no programmatic way of determining which is which.

HPGL_VERSION

(Default "2".) Relevant only to HP-GL Plotters. "1" means that the output should be generic HP-GL, "1.5" means that the output should be suitable for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some HP-GL/2 extensions), and "2" means that the output should be modern HP-GL/2. If the version is less than "2" then the only available fonts will be vector fonts, and all paths will be drawn with a default thickness, so that invoking linewidth, capmod, joinmod, and fmiterlimit will have no effect. Also, the ‘nonzero winding number rule’ will not be supported when filling paths, so invoking fillmod will have no effect. Additionally, if the version is "1" then the filling of arbitrary paths will not be supported (circles and rectangles aligned with the coordinate axes may be filled, however).

INTERLACE

(Default "no".) Relevant only to PNG and GIF Plotters. If the value is "yes", the output file will be interlaced. That means it will be displayed in an interlaced (nonlinear) way by many applications.

MAX_LINE_LENGTH

(Default "500".) The maximum number of defining points that a path may have, before it is flushed to the output device. If this flushing occurs, the path will be split into two or more sub-paths, though the splitting should not be noticeable. Splitting will not be performed if the path is to be filled.

This parameter is relevant to all Plotters except Tektronix and Metafile Plotters. The reason for splitting long paths is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. It is not relevant to Tektronix or Metafile Plotters, since they draw paths in real time and have no buffer limitations.

META_PORTABLE

(Default "no".) Relevant only to Metafile Plotters. "yes" means that the output metafile should use a portable (human-readable) encoding of graphics, rather than the default (binary) encoding.

PCL_ASSIGN_COLORS

(Default "no".) Relevant only to PCL Plotters. "no" means to draw with a fixed set of pens. "yes" means that pen colors will not restricted to this palette: colors will be assigned to “logical pens”, as needed. Other than color LaserJet printers, not many PCL 5 devices allow the assignment of colors to logical pens. So this parameter should be used with caution.

PCL_BEZIERS

(Default "yes".) Relevant only to PCL Plotters. "yes" means that when drawing Bezier curves, the special ‘Bezier instructions’ will be used. "no" means that these instructions will not be used. Instead, each Bezier curve will be approximated and drawn as a polygonal line. Other than the LaserJet III, which was Hewlett–Packard’s first PCL 5 printer, all Hewlett–Packard’s PCL 5 printers support the Bezier instructions.

PNM_PORTABLE

(Default "no".) Relevant only to PNM Plotters. "yes" means that the output should be in a portable (human-readable) version of PBM/PGM/PPM format, rather than the default (binary) version. ‘Portable’ is something of a misnomer, since binary PBM/PGM/PPM files are also portable, in the sense that they are machine-independent.

TERM

(Default NULL.) Relevant only to Tektronix Plotters. If the value is a string beginning with "xterm", "nxterm", or "kterm", it is taken as a sign that the current application is running in an X Window System VT100 terminal emulator: an xterm, nxterm, or kterm. Before drawing graphics, a Tektronix Plotter will emit an escape sequence that causes the terminal emulator’s auxiliary Tektronix window, which is normally hidden, to pop up. After the graphics are drawn, an escape sequence that returns control to the original VT100 window will be emitted. The Tektronix window will remain on the screen.

If the value is a string beginning with "kermit", "ansi.sys", or "nansi.sys", it is taken as a sign that the current application is running in the VT100 terminal emulator provided by the MS-DOS version of kermit. Before drawing graphics, a Tektronix Plotter will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by the Plotter will be kermit-specific. There will be a limited amount of color support, which is not normally the case (the 16 ansi.sys colors will be supported). The "dotdotdashed" line style will be supported, which is also not normally the case. After drawing graphics, the Plotter will emit an escape sequence that returns the emulator to VT100 mode. The key sequence ‘ALT minus’ may be employed manually within kermit to switch between the two modes.

TRANSPARENT_COLOR

(Default "none".) Relevant only to PNG and GIF Plotters. If the value is a recognized color name, that color, if it appears in the output file, will be treated as transparent by most applications. For information on what names are recognized, see Color Names.

If TRANSPARENT_COLOR is set and an animated pseudo-GIF file is produced, the ‘restore to background’ disposal method will be used for each image in the file. Otherwise, the ‘unspecified’ disposal method will be used.

USE_DOUBLE_BUFFERING

(Default "no".) Relevant only to X Plotters and X Drawable Plotters. If the value is "yes", a double buffering scheme will be used when drawing graphics. Each frame of graphics, within a openplclosepl pair, will be written to an off-screen buffer rather than to the Plotter’s display. When erase is invoked to end a frame, or when closepl is invoked, the contents of the off-screen buffer will be copied to the Plotter’s display, pixel by pixel. If successive frames differ only slightly, this will create the illusion of smooth animation.

Some X displays provide special hardware support for double buffering. If this support is available, the X Plotter will detect its presence, and will draw graphics using the appropriate extension to the X11 protocol (either DBE or MBX). In this case the animation will be significantly faster; on high-end graphics hardware, at least.

VANISH_ON_DELETE

(Default "no".) Relevant only to X Plotters. If the value is "yes", when a Plotter is deleted, the window or windows that it has popped up will vanish. Otherwise, each such window will remain on the screen until it is removed by the user (by typing ‘q’ in it, or by clicking with a mouse).

XDRAWABLE_COLORMAP

(Default NULL.) Relevant only to X Drawable Plotters. If the value is non-NULL, it should be a Colormap *, a pointer to a colormap from which colors should be allocated. NULL indicates that the colormap to be used should be the default colormap of the default screen of the X display.

XDRAWABLE_DISPLAY

(Default NULL.) Relevant only to X Drawable Plotters. The value should be a Display *, a pointer to the X display with which the drawable(s) to be drawn in are associated.

XDRAWABLE_DRAWABLE1
XDRAWABLE_DRAWABLE2

(Default NULL.) Relevant only to X Drawable Plotters. If set, the value of each of these parameters should be a Drawable *, a pointer to a drawable to be drawn in. A ‘drawable’ is either a window or a pixmap. At the time an X Drawable Plotter is created, at least one of the two parameters must be set.

X Drawable Plotters support simultaneous drawing in two drawables because it is often useful to be able to draw graphics simultaneously in both an X window and its background pixmap. If two drawables are specified, they must have the same dimensions and depth, and be associated with the same screen of the X display.

XDRAWABLE_VISUAL

(Default NULL.) Relevant only to X Drawable Plotters. If set, the value should be a Visual *, a pointer to the ‘visual’ with which the colormap (see above) is associated. Setting this parameter is not required, but it is recommended that it be set if XDRAWABLE_COLORMAP is set. Under some circumstances, that will speed up color cell allocation.

X_AUTO_FLUSH

(Default "yes".) Relevant only to X Plotters. If the value is "yes", an XFlush operation is performed after each drawing operation. That ensures that graphics are flushed to the X Window System display, and are visible to the user, immediately after they are drawn. However, it slows down rendering considerably. If the value is "no", drawing is faster, since it does not take place in real time.

The Graphing Library


Next: , Previous: , Up: Reference Guide   [Contents][Index]

3.4 The Graphing Library

The (plotutils graph) library is mostly the graph procedure, a single procedure with dozens of options

Procedure: graph ylist
Procedure: graph xlist ylist
Procedure: graph yproc xstart xend
Procedure: graph yproc xstart xend xstep

graph can take up to four arguments.

To plot sampled data, graph is called either with one list or two lists of floating point data. When called with one list, the abscissa will be created automatically. When called with two lists, they must be equal length with one being the x-data and the other being the y-data.

To plot more than one set of sampled data on a plot, two lists can be joined using the merge procedure.

(graph (merge xlist1 xlist2) (merge ylist1 ylist2))

To plot a single-valued function – a procedure that takes one numeric argument and returns one numeric argument – graph can be called with a procedure and two or three arguments that define the x-range of the abcissa. When called with xstart and xend but not xstep a default number of samples will be computed from the procedure: a few hundred points. When xstep is included, it will be the step size of the samples.

There are a couple dozen optional parameters.


Previous: , Up: The Graphing Library   [Contents][Index]

3.4.1 Plot options

#:output-format type

(String, default "meta".) Select an output format of type type, which may be one of the strings "X", "png", "pnm", "gif", "svg", "ai", "ps", "cgm", "fig", "pcl", "hpgl", "regis", "tek", and "meta". These refer respectively to the X Window System, PNG format, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the XML-based Scalable Vector Graphics format, the format used by Adobe Illustrator, idraw-editable Postscript, the WebCGM format for Web-based vector graphics, the format used by the xfig drawing editor, the Hewlett–Packard PCL 5 printer language, the Hewlett–Packard Graphics Language (by default, HP-GL/2), the ReGIS (remote graphics instruction set) format developed by DEC, Tektronix format, and device-independent GNU graphics metafile format.

#:toggle-axis-end x|y

(String) Set the position of the indicated axis to be on the other end of the plotting box from what is currently the case. E.g., ‘#:toggle-axis-end ``y''’ will cause the y axis to appear on the right of the plot rather than the left, which is the default. Similarly, ‘#:toggle-axis-end ``x''’ will cause the x axis to appear at the top of the plot rather than the bottom. Note that if the x axis appears at the top, no plot title will be drawn, since there will be no room.

#:font-size size

(Float, default 0.0525.) Set the size of the font used for the axis and tick labels to be size. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box.

#:font-name font_name

(String, default "Helvetica" except for pcl, for which "Univers" is the default, and png, pnm, gif, hpgl, regis, tek, and raw graph, for all of which "HersheySerif" is the default.) Set the font used for the axis and tick labels, and for the plot title (if any), to be font_name. The choice of font for the plot title may be overridden with the ‘#:title-font-name’ option (see below). Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which ‘-T’ option is used. For a list of all fonts, see Text Fonts.

#:grid-style grid_style

(Integer in the range 0…4, default 2.) Set the grid style for the plot to be grid_style. Grid styles 0 through 3 are progressively more fancy, but style 4 is a somewhat different style.

  1. no axes, tick marks or labels.
  2. a pair of axes, with tick marks and labels.
  3. box around plot, with tick marks and labels.
  4. box around plot, with tick marks and labels; also grid lines.
  5. axes intersect at the origin, with tick marks and labels.
#:height-of-plot height

(Float, default 0.6.) Set the fractional height of the plot with respect to the height of the display (or virtual display, in the case of a multiplot) to be height. A value of 1.0 will produce a plotting box that fills the entire available area. Since labels and tick marks may be placed outside the plotting box, values considerably less than 1.0 are normally chosen.

#:toggle-frame-on-top

Toggle whether or not a copy of the plot frame should be drawn on top of the plot, as well as beneath it. This option is useful when the plotted dataset(s) project slightly beyond the frame, which can happen if a large line thickness or symbol size is specified.

#:tick-size length

(Float, default .02.) Set the length of the tick marks on each axis to be length. A value of 1.0 produces tick marks whose length is equal to the minimum dimension (width or height) of the plotting box. A negative length yields tick marks that extend outside the box, rather than inside.

#:clip-mode clip_mode

(Integer, default 1.) Set the clip mode for the plot to clip_mode. The clip mode is relevant only if data points are being joined by a line, and the line is not being filled to create a filled region (since filled regions are clipped in a fixed way).

There are three clip modes: 0, 1, and 2. They have the same meaning as in the gnuplot plotting program. Clip mode 0 means that a line segment joining two data points will be plotted only if neither point is outside the plotting box. Clip mode 1 means that it will be plotted if no more than one of the two points is outside, and clip mode 2 means that it will be plotted even if both are outside. In all three clip modes the line segment will be clipped to the plotting box.

#:toggle-log-axis x|y

(String) Set the specified axis to be a log axis rather than a linear axis, or vice versa. By default, both axes are linear axes.

#:top-label top_label

(String, default empty.) Place the text string top_label above the plot, as its ‘top label’, i.e., title. The string may include escape sequences (see Text String Format). The ‘--title-font-size’ option may be used to specify the size of the font. The font is normally the same as the font used for labeling axes and ticks, as selected by the ‘-F’ option. But this can be overridden with the ‘--title-font-name’ option.

#:toggle-no-ticks x|y

(string) Toggle the presence of ticks and tick labels on the specified axis. This applies to the grid styles that normally include ticks and tick labels, i.e., grid styles 1, 2, 3, and 4.

#:toggle-rotate-y-label

Position the label on the y axis (which is set with the ‘-Y’ option) horizontally instead of vertically, or vice versa. By default, the label is rotated, so that it is parallel to the y axis. But some output devices (e.g., old X Window System displays, and buggy new ones) cannot handle rotated fonts. So if you specify ‘-T X’, you may also need ‘-Q.

#:right-shift right

(Float, default 0.2.) Move the plot to the right by a fractional amount right with respect to the width of the display (or virtual display, in the case of a multiplot). This produces a margin on the left side of the plotting box. A value of 0.5 will produce a margin half the width of the available area. Note that the tick marks and labels are drawn in the margin.

#:toggle-round-to-next-tick x|y

(string) Toggle whether or not the upper and lower limits of the specified axis should be expanded, so that they both become integer multiples of the spacing between labeled tick marks.

This option is meaningful whenever the user specifies either or both of the limits, by using the ‘-x’ or ‘-y’ option. If the user leaves both limits unspecified, they will always be chosen to satisfy the ‘integer multiple’ constraint.

#:save-screen

Save the screen. This option requests that graph not erase the output device before it begins to plot.

This option is relevant only to graph -T tek and raw graph. Tektronix displays and emulators are persistent, in the sense that previously drawn graphics remain visible. So by repeatedly using graph -T tek -s, you can build up a multiplot.

#:toggle-transpose-axes

Transpose the abscissa and ordinate. This causes the axes to be interchanged, and the options that apply to each axis to be applied to the opposite axis. That is, data points are read in as (y, x) pairs, and such options as ‘-x’ and ‘-X’ apply to the y axis rather than the x axis. If the#:input-format e’ option is in force, so that the data points are read with error bars, the orientation of the error bars will be switched between vertical and horizontal.

#:upward-shift up

(Float, default 0.2.) Move the plot up by a fractional amount up with respect to the height of the display (or virtual display, in the case of a multiplot). This produces a margin below the plotting box. A value of 0.5 will produce a margin half the height of the available area. Note that the tick marks and labels are drawn in the margin.

#:width-of-plot width

(Float, default 0.6.) Set the fractional width of the plot with respect to the width of the display (or virtual display, in the case of a multiplot) to be width. A value of 1.0 will produce a plotting box that fills the entire available area. Since labels and tick marks may be placed outside the plotting box, values considerably less than 1.0 are normally chosen.

#:x-limits [lower_limit [upper_limit [spacing]]]

(Floats.) The arguments lower_limit and upper_limit specify the limits of the x axis, and the optional argument spacing specifies the spacing of labeled ticks along the axis. If any of the three arguments is missing or is supplied as ‘- (i.e., as a single hyphen), it is computed from the data. Both arguments lower_limit and upper_limit must be present if graph is to act as a real-time filter.

By default, the supplied limit(s) are strictly respected. However, the ‘#:toggle-round-to-next-tick x’ option may be used to request that they be rounded to the nearest integer multiple of the spacing between labeled ticks. The lower limit will be rounded downward, and the upper limit upward.

#:x-label x_label

(String, default empty.) Set the label for the x axis to be the text string x_label. The string may include escape sequences (see Text String Format). The ‘#:font-size’ and ‘#:font-name’ options may be used to specify the name of the font and the size of the font.

#:y-limits [lower_limit [upper_limit [spacing]]]

(Floats.) The arguments specify the limits of the y axis, and the spacing of labeled ticks along it, as for the x axis (see above). Both arguments lower_limit and upper_limit must be present if graph is to act as a real-time filter.

By default, the supplied limit(s) are strictly respected. However, the ‘#:toggle-round-to-next-tick y’ option may be used to request that they be rounded to the nearest multiple of the tick spacing. The lower limit will be rounded downward, and the upper limit upward.

#:y-label y_label

(String, default empty.) Set the label for the y axis to be the text string y_label. The string may include escape sequences (see Text String Format). The label will be rotated by 90 degrees so that it is parallel to the axis, unless the ‘-Q’ option is used. (Some X Window System displays, both old and new, do not properly support rotated labels, so that if you specify ‘#:output-format X’, you may also need ‘#:toggle-rotate-y-label’.) The ‘#:font-size’ and ‘#:font-name’ options can be used to specify the name of the font and the size of the font.

#:bg-color name

(String, default "white".) Set the color used for the plot background to be name. This is relevant only to graph #:output-format ``X'', #:output-format ``png'', pnm, gif, cgm, regis, and meta. An unrecognized name sets the color to the default. For information on what names are recognized, see Color Names. The environment variable BG_COLOR can equally well be used to specify the background color.

If the ‘#:output-format ``png''’ or ‘#:output-format ``gif''’ option is used, a transparent PNG file or a transparent pseudo-GIF, respectively, may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See graph Environment. If the#:output-format ``svg''’ or ‘#:output-format ``cgm''’ option is used, an output file without a background may be produced by setting the background color to "none".

#:bitmap-size bitmap_size

(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to graph X, png, pnm, and gif, for all of which the size can be expressed in terms of pixels. The environment variable BITMAPSIZE may equally well be used to specify the size.

The graphics display used by X is a popped-up X window. Command-line positioning of this window on an X Window System display is supported. For example, if bitmap_size is "570x570+0+0" then the window will be popped up in the upper left corner.

If you choose a rectangular (non-square) window size, the fonts in the plot will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. Any font that cannot easily be anisotropically scaled will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif".

For backward compatibility, X allows the user to set the window size and position by setting the X resource Xplot.geometry, instead of ‘#:bitmap-size’ or BITMAPSIZE.

#:emulate-color option

(String, default "no".) If option is "yes", replace each color in the output by an appropriate shade of gray. This is seldom useful, except when using ‘#:output-format ``pcl''’ to prepare output for a PCL 5 device. (Many monochrome PCL 5 devices, such as monochrome LaserJets, do a poor job of emulating color on their own. They usually map HP-GL/2’s seven standard pen colors, including even yellow, to black.) You may equally well request color emulation by setting the environment variable EMULATE_COLOR to "yes".

#:frame-color name

(String, default "black".) Set the color used for drawing the plot frame, and for drawing monochrome datasets (if any) to be name. An unrecognized name sets the color to the default. For information on what names are recognized, see Color Names.

#:frame-line-width frame_line_width

(Float, default -1.0.) Set the thickness of lines in the plot frame, as a fraction of the size (i.e., minimum dimension) of the graphics display, to frame_line_width. A negative value means that the default value for the line thickness provided by the GNU libplot graphics library should be used. This is usually 1/850 times the size of the display, although if ‘X’, ‘png’, ‘pnm’, or ‘gif’ is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible.

tek and regis do not support drawing lines with other than a default thickness, and hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

#:max-line-length max_line_length

(Integer, default 500.) Set the maximum number of points that a polygonal line drawn through any dataset may contain, before it is flushed to the output device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the ‘#:fill-fraction’ option, which requests filling, is used.

The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on tek or raw graph, since they draw polylines in real time and have no buffer limitations.

#:page-size pagesize

(String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to #:output-format ``svg'', ai, ps, cgm, fig, pcl, and hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"…"a4" or ANSI page size in the range "a"…"e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size.

For ai, ps, pcl, and fig, the graphics display (or ‘viewport’) within which the plot is drawn will be, by default, a square region centered on the specified page. For graph -T hpgl, it will be a square region of the same size, but may be positioned differently. Either or both of the dimensions of the graphics display can be specified explicitly. For example, pagesize could be specified as "letter,xsize=4in", or "a4,xsize=10cm,ysize=15cm". The dimensions are allowed to be negative (a negative dimension results in a reflection).

The position of the graphics display, relative to its default position, may optionally be adjusted by specifying an offset vector. For example, pagesize could be specified as "letter,yoffset=1.2in", or "a4,xoffset=-5mm,yoffset=2.0cm". It is also possible to position the graphics display precisely, by specifying the location of its lower left corner relative to the lower left corner of the page. For example, pagesize could be specified as "letter,xorigin=2in,yorigin=3in", or "a4,xorigin=0.5cm,yorigin=0.5cm". The preceding options may be intermingled.

svg and cgm ignore the "xoffset", "yoffset", "xorigin", and "yorigin" options, since SVG format and WebCGM format have no notion of the Web page on which the graphics display will ultimately be positioned. However, they do respect the "xsize" and "ysize" options. For more on page sizes, see Page and Viewport Sizes.

#:pen-colors colors

(String, default "1=red:2=green:3=blue:4=magenta:5=cyan".) Set the colors of the pens used for drawing plots, as numbered, to be colors. The format should be self-explanatory. An unrecognized name sets the corresponding color to the default. For information on what names are recognized, see Color Names.

#:rotation angle

(Integer, default 0.) Set the rotation angle of the graphics display to be angle degrees. The rotation is counterclockwise. The environment variable ROTATION can equally well be used to specify the rotation angle.

This option is used for switching between portrait and landscape orientations, which have rotation angles 0 and 90 degrees respectively. Postmodernists may also find it useful.

#:title-font-name font_name

(String, default "Helvetica" except for #:output-format ``pcl'', for which "Univers" is the default, and png, pnm, gif, hpgl, regis, and tek, for all of which "HersheySerif" is the default.) Set the font used for the plot title to be font_name. Normally the font used for the plot title is the same as that used for labeling the axes and the ticks along the axes, as specified by the ‘#:font-name’ option. But the ‘#:title-font-name’ option can be used to override this. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which ‘#:output-format’ option is used. For a list of all fonts, see Text Fonts.

#:title-font-size size

(Float, default 0.07.) Set the size of the font used for the top label (‘title’), as specified by the ‘#:top-label’ option, to be size. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box.

#:auto-abscissa [step_size [lower_limit]]

(Floats, defaults 1.0 and 0.0.) Automatically generate abscissa (x) values. Irrespective of data format (‘a’, ‘e’, ‘f’, ‘d’, or ‘i), this option specifies that the abscissa (x) values are missing from the input file: the dataset(s) to be read contain only ordinate (y) values. The increment from each x value to the next will be step_size, and the first x value will be lower_limit. To return to reading abscissa values from the input, i.e., for subsequent input files, you would use ‘-a 0’, which disables automatic generation of the abscissa values and returns step_size and lower_limit to their default values.

#:toggle-auto-bump

By default, the linemode (set with ‘#:line-mode’, see below) is ‘bumped’ (incremented by unity) at the beginning of each new dataset. This option toggles auto-bumping: it turns it off if it was on, and on if it was off.

The following options affect the way in which individual datasets are drawn as part of a plot. These options set the six ‘attributes’ (symbol type, symbol font, linemode, line thickness, fill fraction, and color/monochrome) that each dataset has.

#:line-mode line_mode

(Integer, default 1.) line_mode specifies the mode (i.e., style) of the lines drawn between successive points in a dataset. By convention, linemode #0 means no line at all (data points are disconnected). If the dataset is being rendered in monochrome, the interpretation of line_mode is as follows.

  1. solid
  2. dotted
  3. dotdashed
  4. shortdashed
  5. longdashed

Thereafter (i.e., for line_mode greater than 5) the sequence of five linemodes repeats. So besides linemode #0, there are a total of five distinct monochrome linemodes. If the dataset is being rendered in color (as may be requested with the ‘#:toggle-use-color’ option), the interpretation of linemodes #1 through #5 is instead

  1. red, solid
  2. green, solid
  3. blue, solid
  4. magenta, solid
  5. cyan, solid

Linemodes #6 through #10 use the same five colors, but are dotted; linemodes #11 through #15 are dotdashed; linemodes #16 through #20 are shortdashed; and linemodes #21 through #25 are longdashed. So besides linemode #0, there are a total of 25 distinct colored linemodes. A negative linemode indicates that no line should be drawn, but that the marker symbol, if any (see below), should be in the color of the corresponding positive linemode.

#:symbol [symbol_number [symbol_size]]

(Integer and float, defaults 0 and 0.03.) Draw a marker symbol at each data point. symbol_number specifies the symbol type, and symbol_size specifies the font size of the symbol, as a fraction of the minimum dimension (width or height) of the plotting box. If the dataset is being rendered in color, the symbol will have the color of the line that is being drawn to connect the data points.

If you use the ‘#:symbol’ option, you would usually also use the ‘#:line-mode’ option, to request that the symbols be drawn without any line connecting them. By specifying a negative argument to ‘#:line-mode (a ‘negative linemode’), you may obtain colored symbols.

The following table lists the first few symbols (by convention, symbol #0 means no symbol at all).

  1. dot
  2. plus (+)
  3. asterisk (*)
  4. circle
  5. cross

Marker symbols 0…31 are furnished by the GNU libplot graphics library. See Marker Symbols. Symbol numbers greater than or equal to 32 are interpreted as characters in a symbol font, which can be set with the ‘#:symbol-font-name’ option (see below).

#:line-width line_width

(Float, default -1.0.) Set the thickness of the lines used to join successive points in a dataset, as a fraction of the size (i.e., minimum dimension) of the graphics display, to line_width. A negative value means that the default value for the line thickness provided by the GNU libplot graphics library should be used. This is usually 1/850 times the size of the display, although if ‘X’, ‘png’, ‘pnm’, or ‘gif’ is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible.

tek and regis do not support drawing lines with other than a default thickness, and hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

#:fill-fraction fill_fraction

(Float, default -1.0.) If successive points in a dataset are joined by line segments, set the shading intensity for the polygon formed by the line segments to be fill_fraction. A solid polygon (i.e., one filled with the ‘pen color’ used for drawing the line segments) is obtained by choosing fill_fraction=1.0. The interior of the polygon will be white if fill_fraction=0.0. The polygon will be unfilled (transparent) if fill_fraction is negative.

If the polygon intersects itself, the ‘even-odd fill rule’ will normally be used to determine which points are inside rather than outside, i.e., to determine which portions of the polygon should be shaded. The even-odd fill rule is explained in the Postscript Language Reference Manual.

This option has no effect on tek, and it is only partly effective in hpgl if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

#:toggle-use-color

Toggle between color and monochrome rendering of datasets. The interpretation of linemode depends on whether the rendering is being performed in color or monochrome; see the ‘#:line-mode’ option above.

#:symbol-font-name symbol_font_name

(String, default "ZapfDingbats" unless ‘png’, ‘pnm’, ‘gif’, ‘pcl’, ‘hpgl’, ‘regis’, or tek is specified, in which case it is "HersheySerif".) Set the symbol font, from which marker symbols numbered 32 and higher are selected, to be symbol_font_name. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which ‘#:output-format’ option is used. For example, if the ‘pcl’ or ‘hpgl’ option is used then normally the Wingdings font, which is an alternative source of symbols, becomes available. For a list of all fonts, see Text Fonts. The GNU plotutils plotfont utility will produce a character map of any available font..


Previous: , Up: Reference Guide   [Contents][Index]

3.5 Environment variables

The behavior of graph is affected by several environment variables. We have already mentioned the environment variables BITMAPSIZE, PAGESIZE, BG_COLOR, EMULATE_COLOR, MAX_LINE_LENGTH, and ROTATION.


Next: , Previous: , Up: Top   [Contents][Index]

Appendix A Appendices


Previous: , Up: Apendices   [Contents][Index]

A.1 Available marker symbols

The GNU libplot library supports a standard set of marker symbols, numbered 0…31. A marker symbol is a visual representation of a point.

Like a text string, a marker symbol has a font size. In any output format, a marker symbol is guaranteed to be visible if its font size is sufficiently large. Marker symbol #0 is an exception to this: by convention, symbol #0 means no symbol at all. Marker symbols in the range 1…31 are defined as follows.

  1. dot
  2. plus (+)
  3. asterisk (*)
  4. circle
  5. cross
  6. square
  7. triangle
  8. diamond
  9. star
  10. inverted triangle
  11. starburst
  12. fancy plus
  13. fancy cross
  14. fancy square
  15. fancy diamond
  16. filled circle
  17. filled square
  18. filled triangle
  19. filled diamond
  20. filled inverted triangle
  21. filled fancy square
  22. filled fancy diamond
  23. half filled circle
  24. half filled square
  25. half filled triangle
  26. half filled diamond
  27. half filled inverted triangle
  28. half filled fancy square
  29. half filled fancy diamond
  30. octagon
  31. filled octagon

The interpretation of marker symbols 1 through 5 is the same as in the well known Graphical Kernel System (GKS).

By convention, symbols 32 and up are interpreted as characters in a certain text font. For (plotutils plot), this is simply the current font. But for the (plotutils graph) program, it is the symbol font selected with the ‘#:symbol-font-name’ option. By default, the symbol font is the ZapfDingbats font except in #:output-format ``png'', pnm, gif, pcl, hpgl and tek. Those variants of graph normally have no access to ZapfDingbats and other Postscript fonts, so they use the HersheySerif font instead.


Next: , Previous: , Up: Top   [Contents][Index]

Appendix B Specifying Colors by Name

The library allows colors to be specified by the user. It includes the bgcolorname, pencolorname, and fillcolorname functions, each of which takes a color as an argument. In any of these contexts, a color may be specified precisely as a hexadecimal string that gives by its 48-bit RGB representation. For example, "#c0c0c0" is a silvery gray, and "#ffffff" is white. Also, colors may be specified by name. 665 distinct names are recognized, including familiar ones like "red", "green", and "blue", and obscure ones like "dark magenta", "forest green", and "olive drab". Color names are case-insensitive, and spaces are ignored. So, for example, "RosyBrown" is equivalent to "rosy brown", and "DarkGoldenrod3" to "dark goldenrod 3".

The following table lists the 665 color names
recognized by the GNU libplot library and by the
GNU plotting utilities, such as `graph'.  The
representation of each color in the RGB color
model is also listed.  Names are case-insensitive,
and spaces in names are ignored, so that
"antiquewhite1", "antique white 1" and
"AntiqueWhite1" are equivalent.

The recognized color names are essentially the
names recognized by recent releases of the X
Windows System.  However for every color name
containing the string "gray", a version containing
"grey" is included.

The R, G, and B numbers for each color are the
intensities of its red, green, and blue
components, in a 24-bit color model (255=full
intensity, 0=none).  To convert to the
corresponding intensities in the 48-bit color
model used by GNU libplot, multiply each intensity
by 257.



 R   G   B       Color Name
---------------------------

240 248 255	aliceblue
250 235 215	antiquewhite
255 239 219	antiquewhite1
238 223 204	antiquewhite2
205 192 176	antiquewhite3
139 131 120	antiquewhite4
127 255 212	aquamarine
127 255 212	aquamarine1
118 238 198	aquamarine2
102 205 170	aquamarine3
 69 139 116	aquamarine4
240 255 255	azure
240 255 255	azure1
224 238 238	azure2
193 205 205	azure3
131 139 139	azure4
245 245 220	beige
255 228 196	bisque
255 228 196	bisque1
238 213 183	bisque2
205 183 158	bisque3
139 125 107	bisque4
  0   0   0	black
255 235 205	blanchedalmond
  0   0 255	blue
  0   0 255	blue1
  0   0 238	blue2
  0   0 205	blue3
  0   0 139	blue4
138  43 226	blueviolet
165  42  42	brown
255  64  64	brown1
238  59  59	brown2
205  51  51	brown3
139  35  35	brown4
222 184 135	burlywood
255 211 155	burlywood1
238 197 145	burlywood2
205 170 125	burlywood3
139 115  85	burlywood4
 95 158 160	cadetblue
152 245 255	cadetblue1
142 229 238	cadetblue2
122 197 205	cadetblue3
 83 134 139	cadetblue4
127 255   0	chartreuse
127 255   0	chartreuse1
118 238   0	chartreuse2
102 205   0	chartreuse3
 69 139   0	chartreuse4
210 105  30	chocolate
255 127  36	chocolate1
238 118  33	chocolate2
205 102  29	chocolate3
139  69  19	chocolate4
255 127  80	coral
255 114  86	coral1
238 106  80	coral2
205  91  69	coral3
139  62  47	coral4
100 149 237	cornflowerblue
255 248 220	cornsilk
255 248 220	cornsilk1
238 232 205	cornsilk2
205 200 177	cornsilk3
139 136 120	cornsilk4
  0 255 255	cyan
  0 255 255	cyan1
  0 238 238	cyan2
  0 205 205	cyan3
  0 139 139	cyan4
  0   0 139	darkblue
  0 139 139	darkcyan
184 134  11	darkgoldenrod
255 185  15	darkgoldenrod1
238 173  14	darkgoldenrod2
205 149  12	darkgoldenrod3
139 101   8	darkgoldenrod4
169 169 169	darkgray
  0 100   0	darkgreen
169 169 169	darkgrey
189 183 107	darkkhaki
139   0 139	darkmagenta
 85 107  47	darkolivegreen
202 255 112	darkolivegreen1
188 238 104	darkolivegreen2
162 205  90	darkolivegreen3
110 139  61	darkolivegreen4
255 140   0	darkorange
255 127   0	darkorange1
238 118   0	darkorange2
205 102   0	darkorange3
139  69   0	darkorange4
153  50 204	darkorchid
191  62 255	darkorchid1
178  58 238	darkorchid2
154  50 205	darkorchid3
104  34 139	darkorchid4
139   0   0	darkred
233 150 122	darksalmon
143 188 143	darkseagreen
193 255 193	darkseagreen1
180 238 180	darkseagreen2
155 205 155	darkseagreen3
105 139 105	darkseagreen4
 72  61 139	darkslateblue
 47  79  79	darkslategray
151 255 255	darkslategray1
141 238 238	darkslategray2
121 205 205	darkslategray3
 82 139 139	darkslategray4
 47  79  79	darkslategrey
151 255 255	darkslategrey1
141 238 238	darkslategrey2
121 205 205	darkslategrey3
 82 139 139	darkslategrey4
  0 206 209	darkturquoise
148   0 211	darkviolet
255  20 147	deeppink
255  20 147	deeppink1
238  18 137	deeppink2
205  16 118	deeppink3
139  10  80	deeppink4
  0 191 255	deepskyblue
  0 191 255	deepskyblue1
  0 178 238	deepskyblue2
  0 154 205	deepskyblue3
  0 104 139	deepskyblue4
105 105 105	dimgray
105 105 105	dimgrey
 30 144 255	dodgerblue
 30 144 255	dodgerblue1
 28 134 238	dodgerblue2
 24 116 205	dodgerblue3
 16  78 139	dodgerblue4
178  34  34	firebrick
255  48  48	firebrick1
238  44  44	firebrick2
205  38  38	firebrick3
139  26  26	firebrick4
255 250 240	floralwhite
 34 139  34	forestgreen
220 220 220	gainsboro
248 248 255	ghostwhite
255 215   0	gold
255 215   0	gold1
238 201   0	gold2
205 173   0	gold3
139 117   0	gold4
218 165  32	goldenrod
255 193  37	goldenrod1
238 180  34	goldenrod2
205 155  29	goldenrod3
139 105  20	goldenrod4
190 190 190	gray
  0   0   0	gray0
  3   3   3	gray1
  5   5   5	gray2
  8   8   8	gray3
 10  10  10	gray4
 13  13  13	gray5
 15  15  15	gray6
 18  18  18	gray7
 20  20  20	gray8
 23  23  23	gray9
 26  26  26	gray10
 28  28  28	gray11
 31  31  31	gray12
 33  33  33	gray13
 36  36  36	gray14
 38  38  38	gray15
 41  41  41	gray16
 43  43  43	gray17
 46  46  46	gray18
 48  48  48	gray19
 51  51  51	gray20
 54  54  54	gray21
 56  56  56	gray22
 59  59  59	gray23
 61  61  61	gray24
 64  64  64	gray25
 66  66  66	gray26
 69  69  69	gray27
 71  71  71	gray28
 74  74  74	gray29
 77  77  77	gray30
 79  79  79	gray31
 82  82  82	gray32
 84  84  84	gray33
 87  87  87	gray34
 89  89  89	gray35
 92  92  92	gray36
 94  94  94	gray37
 97  97  97	gray38
 99  99  99	gray39
102 102 102	gray40
105 105 105	gray41
107 107 107	gray42
110 110 110	gray43
112 112 112	gray44
115 115 115	gray45
117 117 117	gray46
120 120 120	gray47
122 122 122	gray48
125 125 125	gray49
127 127 127	gray50
130 130 130	gray51
133 133 133	gray52
135 135 135	gray53
138 138 138	gray54
140 140 140	gray55
143 143 143	gray56
145 145 145	gray57
148 148 148	gray58
150 150 150	gray59
153 153 153	gray60
156 156 156	gray61
158 158 158	gray62
161 161 161	gray63
163 163 163	gray64
166 166 166	gray65
168 168 168	gray66
171 171 171	gray67
173 173 173	gray68
176 176 176	gray69
179 179 179	gray70
181 181 181	gray71
184 184 184	gray72
186 186 186	gray73
189 189 189	gray74
191 191 191	gray75
194 194 194	gray76
196 196 196	gray77
199 199 199	gray78
201 201 201	gray79
204 204 204	gray80
207 207 207	gray81
209 209 209	gray82
212 212 212	gray83
214 214 214	gray84
217 217 217	gray85
219 219 219	gray86
222 222 222	gray87
224 224 224	gray88
227 227 227	gray89
229 229 229	gray90
232 232 232	gray91
235 235 235	gray92
237 237 237	gray93
240 240 240	gray94
242 242 242	gray95
245 245 245	gray96
247 247 247	gray97
250 250 250	gray98
252 252 252	gray99
255 255 255	gray100
  0 255   0	green
  0 255   0	green1
  0 238   0	green2
  0 205   0	green3
  0 139   0	green4
173 255  47	greenyellow
190 190 190	grey
  0   0   0	grey0
  3   3   3	grey1
  5   5   5	grey2
  8   8   8	grey3
 10  10  10	grey4
 13  13  13	grey5
 15  15  15	grey6
 18  18  18	grey7
 20  20  20	grey8
 23  23  23	grey9
 26  26  26	grey10
 28  28  28	grey11
 31  31  31	grey12
 33  33  33	grey13
 36  36  36	grey14
 38  38  38	grey15
 41  41  41	grey16
 43  43  43	grey17
 46  46  46	grey18
 48  48  48	grey19
 51  51  51	grey20
 54  54  54	grey21
 56  56  56	grey22
 59  59  59	grey23
 61  61  61	grey24
 64  64  64	grey25
 66  66  66	grey26
 69  69  69	grey27
 71  71  71	grey28
 74  74  74	grey29
 77  77  77	grey30
 79  79  79	grey31
 82  82  82	grey32
 84  84  84	grey33
 87  87  87	grey34
 89  89  89	grey35
 92  92  92	grey36
 94  94  94	grey37
 97  97  97	grey38
 99  99  99	grey39
102 102 102	grey40
105 105 105	grey41
107 107 107	grey42
110 110 110	grey43
112 112 112	grey44
115 115 115	grey45
117 117 117	grey46
120 120 120	grey47
122 122 122	grey48
125 125 125	grey49
127 127 127	grey50
130 130 130	grey51
133 133 133	grey52
135 135 135	grey53
138 138 138	grey54
140 140 140	grey55
143 143 143	grey56
145 145 145	grey57
148 148 148	grey58
150 150 150	grey59
153 153 153	grey60
156 156 156	grey61
158 158 158	grey62
161 161 161	grey63
163 163 163	grey64
166 166 166	grey65
168 168 168	grey66
171 171 171	grey67
173 173 173	grey68
176 176 176	grey69
179 179 179	grey70
181 181 181	grey71
184 184 184	grey72
186 186 186	grey73
189 189 189	grey74
191 191 191	grey75
194 194 194	grey76
196 196 196	grey77
199 199 199	grey78
201 201 201	grey79
204 204 204	grey80
207 207 207	grey81
209 209 209	grey82
212 212 212	grey83
214 214 214	grey84
217 217 217	grey85
219 219 219	grey86
222 222 222	grey87
224 224 224	grey88
227 227 227	grey89
229 229 229	grey90
232 232 232	grey91
235 235 235	grey92
237 237 237	grey93
240 240 240	grey94
242 242 242	grey95
245 245 245	grey96
247 247 247	grey97
250 250 250	grey98
252 252 252	grey99
255 255 255	grey100
240 255 240	honeydew
240 255 240	honeydew1
224 238 224	honeydew2
193 205 193	honeydew3
131 139 131	honeydew4
255 105 180	hotpink
255 110 180	hotpink1
238 106 167	hotpink2
205  96 144	hotpink3
139  58  98	hotpink4
205  92  92	indianred
255 106 106	indianred1
238  99  99	indianred2
205  85  85	indianred3
139  58  58	indianred4
255 255 240	ivory
255 255 240	ivory1
238 238 224	ivory2
205 205 193	ivory3
139 139 131	ivory4
240 230 140	khaki
255 246 143	khaki1
238 230 133	khaki2
205 198 115	khaki3
139 134  78	khaki4
230 230 250	lavender
255 240 245	lavenderblush
255 240 245	lavenderblush1
238 224 229	lavenderblush2
205 193 197	lavenderblush3
139 131 134	lavenderblush4
124 252   0	lawngreen
255 250 205	lemonchiffon
255 250 205	lemonchiffon1
238 233 191	lemonchiffon2
205 201 165	lemonchiffon3
139 137 112	lemonchiffon4
173 216 230	lightblue
191 239 255	lightblue1
178 223 238	lightblue2
154 192 205	lightblue3
104 131 139	lightblue4
240 128 128	lightcoral
224 255 255	lightcyan
224 255 255	lightcyan1
209 238 238	lightcyan2
180 205 205	lightcyan3
122 139 139	lightcyan4
238 221 130	lightgoldenrod
255 236 139	lightgoldenrod1
238 220 130	lightgoldenrod2
205 190 112	lightgoldenrod3
139 129  76	lightgoldenrod4
250 250 210	lightgoldenrodyellow
211 211 211	lightgray
144 238 144	lightgreen
211 211 211	lightgrey
255 182 193	lightpink
255 174 185	lightpink1
238 162 173	lightpink2
205 140 149	lightpink3
139  95 101	lightpink4
255 160 122	lightsalmon
255 160 122	lightsalmon1
238 149 114	lightsalmon2
205 129  98	lightsalmon3
139  87  66	lightsalmon4
 32 178 170	lightseagreen
135 206 250	lightskyblue
176 226 255	lightskyblue1
164 211 238	lightskyblue2
141 182 205	lightskyblue3
 96 123 139	lightskyblue4
132 112 255	lightslateblue
119 136 153	lightslategray
119 136 153	lightslategrey
176 196 222	lightsteelblue
202 225 255	lightsteelblue1
188 210 238	lightsteelblue2
162 181 205	lightsteelblue3
110 123 139	lightsteelblue4
255 255 224	lightyellow
255 255 224	lightyellow1
238 238 209	lightyellow2
205 205 180	lightyellow3
139 139 122	lightyellow4
 50 205  50	limegreen
250 240 230	linen
255   0 255	magenta
255   0 255	magenta1
238   0 238	magenta2
205   0 205	magenta3
139   0 139	magenta4
176  48  96	maroon
255  52 179	maroon1
238  48 167	maroon2
205  41 144	maroon3
139  28  98	maroon4
102 205 170	mediumaquamarine
  0   0 205	mediumblue
186  85 211	mediumorchid
224 102 255	mediumorchid1
209  95 238	mediumorchid2
180  82 205	mediumorchid3
122  55 139	mediumorchid4
147 112 219	mediumpurple
171 130 255	mediumpurple1
159 121 238	mediumpurple2
137 104 205	mediumpurple3
 93  71 139	mediumpurple4
 60 179 113	mediumseagreen
123 104 238	mediumslateblue
  0 250 154	mediumspringgreen
 72 209 204	mediumturquoise
199  21 133	mediumvioletred
 25  25 112	midnightblue
245 255 250	mintcream
255 228 225	mistyrose
255 228 225	mistyrose1
238 213 210	mistyrose2
205 183 181	mistyrose3
139 125 123	mistyrose4
255 228 181	moccasin
255 222 173	navajowhite
255 222 173	navajowhite1
238 207 161	navajowhite2
205 179 139	navajowhite3
139 121  94	navajowhite4
  0   0 128	navy
  0   0 128	navyblue
253 245 230	oldlace
107 142  35	olivedrab
192 255  62	olivedrab1
179 238  58	olivedrab2
154 205  50	olivedrab3
105 139  34	olivedrab4
255 165   0	orange
255 165   0	orange1
238 154   0	orange2
205 133   0	orange3
139  90   0	orange4
255  69   0	orangered
255  69   0	orangered1
238  64   0	orangered2
205  55   0	orangered3
139  37   0	orangered4
218 112 214	orchid
255 131 250	orchid1
238 122 233	orchid2
205 105 201	orchid3
139  71 137	orchid4
238 232 170	palegoldenrod
152 251 152	palegreen
154 255 154	palegreen1
144 238 144	palegreen2
124 205 124	palegreen3
 84 139  84	palegreen4
175 238 238	paleturquoise
187 255 255	paleturquoise1
174 238 238	paleturquoise2
150 205 205	paleturquoise3
102 139 139	paleturquoise4
219 112 147	palevioletred
255 130 171	palevioletred1
238 121 159	palevioletred2
205 104 137	palevioletred3
139  71  93	palevioletred4
255 239 213	papayawhip
255 218 185	peachpuff
255 218 185	peachpuff1
238 203 173	peachpuff2
205 175 149	peachpuff3
139 119 101	peachpuff4
205 133  63	peru
255 192 203	pink
255 181 197	pink1
238 169 184	pink2
205 145 158	pink3
139  99 108	pink4
221 160 221	plum
255 187 255	plum1
238 174 238	plum2
205 150 205	plum3
139 102 139	plum4
176 224 230	powderblue
160  32 240	purple
155  48 255	purple1
145  44 238	purple2
125  38 205	purple3
 85  26 139	purple4
255   0   0	red
255   0   0	red1
238   0   0	red2
205   0   0	red3
139   0   0	red4
188 143 143	rosybrown
255 193 193	rosybrown1
238 180 180	rosybrown2
205 155 155	rosybrown3
139 105 105	rosybrown4
 65 105 225	royalblue
 72 118 255	royalblue1
 67 110 238	royalblue2
 58  95 205	royalblue3
 39  64 139	royalblue4
139  69  19	saddlebrown
250 128 114	salmon
255 140 105	salmon1
238 130  98	salmon2
205 112  84	salmon3
139  76  57	salmon4
244 164  96	sandybrown
 46 139  87	seagreen
 84 255 159	seagreen1
 78 238 148	seagreen2
 67 205 128	seagreen3
 46 139  87	seagreen4
255 245 238	seashell
255 245 238	seashell1
238 229 222	seashell2
205 197 191	seashell3
139 134 130	seashell4
160  82  45	sienna
255 130  71	sienna1
238 121  66	sienna2
205 104  57	sienna3
139  71  38	sienna4
135 206 235	skyblue
135 206 255	skyblue1
126 192 238	skyblue2
108 166 205	skyblue3
 74 112 139	skyblue4
106  90 205	slateblue
131 111 255	slateblue1
122 103 238	slateblue2
105  89 205	slateblue3
 71  60 139	slateblue4
112 128 144	slategray
198 226 255	slategray1
185 211 238	slategray2
159 182 205	slategray3
108 123 139	slategray4
112 128 144	slategrey
198 226 255	slategrey1
185 211 238	slategrey2
159 182 205	slategrey3
108 123 139	slategrey4
255 250 250	snow
255 250 250	snow1
238 233 233	snow2
205 201 201	snow3
139 137 137	snow4
  0 255 127	springgreen
  0 255 127	springgreen1
  0 238 118	springgreen2
  0 205 102	springgreen3
  0 139  69	springgreen4
 70 130 180	steelblue
 99 184 255	steelblue1
 92 172 238	steelblue2
 79 148 205	steelblue3
 54 100 139	steelblue4
210 180 140	tan
255 165  79	tan1
238 154  73	tan2
205 133  63	tan3
139  90  43	tan4
216 191 216	thistle
255 225 255	thistle1
238 210 238	thistle2
205 181 205	thistle3
139 123 139	thistle4
255  99  71	tomato
255  99  71	tomato1
238  92  66	tomato2
205  79  57	tomato3
139  54  38	tomato4
 64 224 208	turquoise
  0 245 255	turquoise1
  0 229 238	turquoise2
  0 197 205	turquoise3
  0 134 139	turquoise4
238 130 238	violet
208  32 144	violetred
255  62 150	violetred1
238  58 140	violetred2
205  50 120	violetred3
139  34  82	violetred4
245 222 179	wheat
255 231 186	wheat1
238 216 174	wheat2
205 186 150	wheat3
139 126 102	wheat4
255 255 255	white
245 245 245	whitesmoke
255 255   0	yellow
255 255   0	yellow1
238 238   0	yellow2
205 205   0	yellow3
139 139   0	yellow4
154 205  50	yellowgreen

Next: , Previous: , Up: Top   [Contents][Index]

Appendix C Page Sizes and Viewport Sizes

When producing output in such vector formats as Illustrator, Postscript, PCL 5, HP-GL, and Fig, it is important to specify the size of the page on which the output will appear. Supported page sizes are "letter", "a4", etc.; a full list appears below. The page size is passed to the the GNU libplot library via the PAGESIZE parameter. The command-line graphics programs graph, plot, pic2plot, tek2plot, and plotfont, which are built on libplot, similarly support a PAGESIZE environment variable and a ‘--page-size’ option.

Graphics drawn by libplot are nominally drawn within a graphics display, or ‘viewport’. When producing raster formats such as PNG, PNM, and pseudo-GIF, the viewport is simply a square or rectangular bitmap. But when producing vector formats such as Illustrator, Postscript, PCL 5, HP-GL, and Fig format, the viewport is a square or rectangular region on the output page. (For the meaning of the viewport when the output format is SVG or WebCGM, see below.) Except in the HP-GL case, the viewport will by default be centered on the page. For example, if the page size is "letter", the viewport will be a square 8in by 8in region, centered on a 8.5in by 11.0in page. Graphics will not be clipped to the viewport, so the entire page will in principle be imageable.

Either or both of the dimensions of the viewport can be changed by the user. For example, the page size could be specified as "letter,xsize=4in", or "a4,xsize=10cm,ysize=15cm", where the specified sizes will override the default dimensions of the viewport. The dimensions of the viewport are allowed to be negative (a negative dimension results in a reflection). Inches, centimeters, and millimeters are the supported units.

For most vector output formats, it is possible to position the viewport quite precisely, by specifying the location of its lower left corner relative to the lower left corner of the page. For example, the page size could be specified not merely as "letter" or "a4", but as "letter,xorigin=2in,yorigin=3in", or "a4,xorigin=0.5cm,yorigin=0.5cm". (The ‘xorigin’ and ‘yorigin’ specifiers may be used in conjunction with ‘xsize’ and ‘ysize’.) As an alternative to ‘xorigin’ and ‘yorigin’, the viewport position could be adjusted by supplying an offset vector, the offset being interpreted as a shift away from the default position. For example, the page size could be specified as "letter,yoffset=1.2in", or "a4,xoffset=-5mm,yoffset=2.0cm". The viewport may also be rotated, by setting the ROTATION parameter or environment variable, or (in the case of the graphics programs) by using the ‘--rotation’ option. A rotated viewport does not change the position of its four corners. Rather, the graphics are rotated within it. If the viewport is rectangular rather than square, this ‘rotation’ will necessarily include a rescaling.

Any ISO page size in the range "a0"…"a4" or ANSI page size in the range "a"…"e" may be specified. ("letter" is an alias for "a", which is the default, and "tabloid" is an alias for "b"). "legal", "ledger", and the JIS [Japanese Industrial Standard] size "b5" are recognized also. The following are the supported page sizes and the default square viewport size that corresponds to each.

"a" (or "letter"; 8.5in by 11.0in)

8.0in

"b" (or "tabloid"; 11.0in by 17.0in)

10.0in

"c" (17.0in by 22.0in)

16.0in

"d" (22.0in by 34.0in)

20.0in

"e" (34.0in by 44.0in)

32.0in

"legal" (8.5in by 14.0in)

8.0in

"ledger" (17.0in by 11.0in)

10.0in

"a4" (21.0cm by 29.7cm)

19.81cm

"a3" (29.7cm by 42.0cm)

27.18cm

"a2" (42.0cm by 59.4cm)

39.62cm

"a1" (59.4cm by 84.1cm)

56.90cm

"a0" (84.1cm by 118.9cm)

81.79cm

"b5" (18.2cm by 25.7cm)

16.94cm

As noted, SVG and WebCGM format are special. They have no notion of the size of the Web page on which the viewport will ultimately be positioned. They do have a notion of viewport size, though this will typically be overridden when the output file is placed on a page by a Web page designer. When producing SVG or WebCGM output, the viewport size is set in the usual way: by PAGESIZE, or (in the case of the graphics programs) the ‘--page-size’ option. For example, if the specified page size is "letter", the viewport within which SVG or WebCGM graphics are drawn will be an 8in by 8in square. If it is "letter,xsize=6in,ysize=7in", then the viewport will be a 6in by 7in rectangle, and so forth. The "xorigin", "yorigin", "xoffset", and "yoffset" specifiers, if included, are necessarily ignored.

For a similar reason, the "xorigin" and "yorigin" specifiers are ignored when producing HP-GL or HP-GL/2 output. By default, the lower left corner of the viewport is positioned at the HP-GL ‘scaling point’ P1, whose location is device-dependent and will not normally coincide with the lower left corner of the physical page, though it may be close to it. The "xoffset" and "yoffset" specifiers are respected, however, and may be used to shift the viewport away from its default position.


Next: , Previous: , Up: Page and Viewport Sizes   [Contents][Index]

C.1 Available text fonts

The GNU libplot library and applications built on it can use a limited set of built-in fonts. These include 22 Hershey vector fonts, 35 Postscript fonts, 45 PCL 5 fonts, and 18 Hewlett–Packard vector fonts. We call these 120 supported fonts the ‘built-in’ fonts. The Hershey fonts are constructed from stroked characters digitized c. 1967 by Dr. Allen V. Hershey at the U.S. Naval Surface Weapons Center in Dahlgren, VA. The 35 Postscript fonts are the outline fonts resident in all modern Postscript printers, and the 45 PCL 5 fonts are the outline fonts resident in modern Hewlett–Packard LaserJet printers and plotters. (Of the PCL 5 fonts, the old LaserJet III, which was Hewlett–Packard’s first PCL 5 printer, supported only eight: the Univers and CGTimes fonts.) The 18 Hewlett–Packard vector fonts are fonts that are resident in Hewlett–Packard printers and plotters (mostly the latter).

The Hershey fonts can be used by all types of Plotter supported by libplot, and the Postscript fonts can be used by X, SVG, Illustrator, Postscript, and Fig Plotters. So, for example, all variants of graph can use the Hershey fonts, and graph #:output-format ``X'', svg, ai, ps, cgm and fig can use the Postscript fonts. The PCL 5 fonts can be used by by SVG, Illustrator, PCL, and HP-GL Plotters, and by #:output-format ``svg'', ai, pcl, and hpgl. The Hewlett–Packard vector fonts can be used by PCL and HP-GL Plotters, and by #:output-format ``pcl'' and hpgl. X Plotters and graph #:output-format ``X'' are not restricted to the built-in Hershey and Postscript fonts. They can use any X Window System font.

For the purpose of plotting text strings (see Text String Format), the 120 built-in fonts are divided into typefaces. As you can see from the following tables, our convention is that in any typeface with more than a single font, font #1 is the normal font, font #2 is italic or oblique, font #3 is bold, and font #4 is bold italic or bold oblique. Additional variants (if any) are numbered #5 and higher.

The 22 Hershey fonts are divided into typefaces as follows.

Nearly all Hershey fonts except the Symbol fonts use the ISO-Latin-1 encoding, which is a superset of ASCII. The Symbol fonts consist of Greek characters and mathematical symbols, and use the symbol font encoding documented in the Postscript Language Reference Manual. By convention, each Hershey typeface contains a symbol font (HersheySerifSymbol or HersheySansSymbol, as appropriate) as font #0.

HersheyCyrillic, HersheyCyrillic-Oblique, and HersheyEUC (which is a Japanese font) are the only non-Symbol Hershey fonts that do not use the ISO-Latin-1 encoding.

The 35 Postscript fonts are divided into typefaces as follows.

All Postscript fonts except the ZapfDingbats and Symbol fonts use the ISO-Latin-1 encoding. The encodings used by the ZapfDingbats and Symbol fonts are documented in the Postscript Language Reference Manual. By convention, each Postscript typeface contains the Symbol font as font #0.

The 45 PCL 5 fonts are divided into typefaces as follows.

All PCL 5 fonts except the Wingdings and Symbol fonts use the ISO-Latin-1 encoding. The encoding used by the Symbol font is the symbol font encoding documented in the Postscript Language Reference Manual. By convention, each PCL typeface contains the Symbol font as font #0.

The 18 Hewlett–Packard vector fonts are divided into typefaces as follows.

The Hewlett–Packard vector fonts with an asterisk (the ANK and Symbol fonts) are only available when producing HP-GL/2 graphics, or HP-GL graphics for the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A drafting plotters. That is, they are available only if HPGL_VERSION is "2" (the default) or "1.5".

All Hewlett–Packard vector fonts except the ANK and Symbol fonts use the ISO-Latin-1 encoding. The Arc fonts are proportional (variable-width) fonts, and the Stick fonts are fixed-width fonts. If HP-GL/2 or HP-GL output is selected, the Arc fonts are assumed to be kerned via device-resident kerning tables. But when producing PCL 5 output, it is assumed that the display device will do no kerning. Apparently Hewlett–Packard dropped support for device-resident kerning tables when emulating HP-GL/2 from within PCL 5. For information about Hewlett–Packard vector fonts and the way in which they are kerned (in HP-GL pen plotters, at least), see the article by L. W. Hennessee et al. in the Nov. 1981 issue of the Hewlett–Packard Journal.

To what extent do the fonts supported by libplot contain ligatures? The Postscript fonts, the PCL 5 fonts, and the Hewlett–Packard vector fonts, at least as implemented in libplot, do not contain ligatures. However, six of the 22 Hershey fonts contain ligatures. The character combinations "fi", "ff", "fl", "ffi", and "ffl" are automatically drawn as ligatures in HersheySerif and HersheySerif-Italic. (Also in the two HersheyCyrillic fonts and HersheyEUC, since insofar as printable ASCII characters are concerned, they are identical [or almost identical] to HersheySerif.) In addition, "tz" and "ch" are ligatures in HersheyGothicGerman. The German double-s character ‘ß’, which is called an ‘eszet’, is not treated as a ligature in any font. To obtain an eszet, you must either request one with the escape sequence "\ss" (see Text String Format), or, if you have an 8-bit keyboard, type an eszet explicitly.


Previous: , Up: Page and Viewport Sizes   [Contents][Index]

C.2 Text String Format


Next: , Previous: , Up: Top   [Contents][Index]

D Further Resources and Contact Info

Uh, I dunno.

Maybe the Guile mailing list?


Next: , Previous: , Up: Top   [Contents][Index]

Appendix E GNU Free Documentation License

Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copies of the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  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, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.


Previous: , Up: Top   [Contents][Index]

The Index

Jump to:   A   B   C   E   F   G   H   J   L   M   N   O   P   R   S   T  
Index Entry  Section

A
alabel!: Drawing Functions
arc!: Drawing Functions
arcrel!: Drawing Functions

B
bezier2!: Drawing Functions
bezier2rel!: Drawing Functions
bezier3!: Drawing Functions
bezier3rel!: Drawing Functions
bgcolor!: Control Functions
bgcolorname!: Control Functions
box!: Drawing Functions
boxrel!: Drawing Functions

C
capmod!: Attribute Functions
circle!: Drawing Functions
circlerel!: Drawing Functions
closepl!: Control Functions
color!: Attribute Functions
colorname!: Attribute Functions
concat: Mapping Functions
cont!: Drawing Functions
contrel!: Drawing Functions

E
ellarc!: Drawing Functions
ellarcrel!: Drawing Functions
ellipse!: Drawing Functions
ellipserel!: Drawing Functions
endpath!: Drawing Functions
endsubpath!: Drawing Functions
erase!: Control Functions

F
fillcolor!: Attribute Functions
fillcolorname!: Attribute Functions
fillmod!: Attribute Functions
filltype!: Attribute Functions
flushpl!: Control Functions
fontname!: Attribute Functions
fontsize!: Attribute Functions

G
graph: The Graphing Library
graph: The Graphing Library
graph: The Graphing Library
graph: The Graphing Library

H
havecap: Control Functions

J
joinmod!: Attribute Functions

L
label!: Drawing Functions
labelwidth!: Drawing Functions
line!: Drawing Functions
linedash!: Attribute Functions
linemod!: Attribute Functions
linerel!: Drawing Functions
linewidth!: Attribute Functions

M
marker!: Drawing Functions
markerrel!: Drawing Functions
miterlimit!: Attribute Functions
move!: Attribute Functions
moverel!: Attribute Functions

N
newpl: The Plotting Library
newplparams: The Plotting Library

O
openpl!: Control Functions
orientation!: Attribute Functions

P
pencolor!: Attribute Functions
pencolorname!: Attribute Functions
pentype!: Attribute Functions
plotting: The Plotting Library
point!: Drawing Functions
pointrel!: Drawing Functions

R
restorestate!: Attribute Functions
rotate!: Mapping Functions

S
savestate!: Attribute Functions
scale!: Mapping Functions
setmatrix!: Mapping Functions
setplparam!: The Plotting Library
space!: Control Functions
space2!: Control Functions

T
textangle!: Attribute Functions
translate!: Mapping Functions

Jump to:   A   B   C   E   F   G   H   J   L   M   N   O   P   R   S   T