aboutsummaryrefslogtreecommitdiffstats
path: root/doc/expert/pre_grap
diff options
context:
space:
mode:
authorJeffrey H. Kingston <jeff@it.usyd.edu.au>2010-09-14 19:21:41 +0000
committerJeffrey H. Kingston <jeff@it.usyd.edu.au>2010-09-14 19:21:41 +0000
commit71bdb35d52747e6d7d9f55df4524d57c2966be94 (patch)
tree480ee5eefccc40d5f3331cc52d66f722fd19bfb9 /doc/expert/pre_grap
parentb41263ea7578fa9742486135c762803b52794105 (diff)
downloadlout-71bdb35d52747e6d7d9f55df4524d57c2966be94.tar.gz
Lout 3.17.
git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@2 9365b830-b601-4143-9ba8-b4a8e2c3339c
Diffstat (limited to 'doc/expert/pre_grap')
-rw-r--r--doc/expert/pre_grap284
1 files changed, 284 insertions, 0 deletions
diff --git a/doc/expert/pre_grap b/doc/expert/pre_grap
new file mode 100644
index 0000000..e75dd21
--- /dev/null
+++ b/doc/expert/pre_grap
@@ -0,0 +1,284 @@
+@Section
+ @Title { "@Graphic" }
+ @Tag { graphic }
+@Begin
+@PP
+graphic.sym @Index { @@Graphic symbol }
+diagrams @Index { Diagrams }
+Lout does not provide the vast repertoire of graphical objects (lines,
+circles, boxes, etc.) required by diagrams. Instead, it provides an
+escape route to some other language that does have these features, via
+its @@Graphic symbol:
+postscript.graphic @SubIndex { used by @@Graphic }
+@ID @OneRow @OneRow @Code {
+"{ 0 0 moveto"
+" 0 ysize lineto"
+" xsize ysize lineto"
+" xsize 0 lineto"
+" closepath"
+" stroke"
+"}"
+"@Graphic"
+"{ //0.2c"
+" ||0.2c hello, world ||0.2c"
+" //0.2c"
+"}"
+}
+The result of the above invocation of the symbol @@Graphic is
+@ID @OneRow @OneRow {
+ @BackEnd @Case {
+ PostScript @Yield {
+ { 0 0 moveto
+ 0 ysize lineto
+ xsize ysize lineto
+ xsize 0 lineto
+ closepath
+ stroke
+ }
+ @Graphic
+ { //0.2c
+ ||0.2c hello, world ||0.2c
+ //0.2c
+ }
+ }
+ PDF @Yield {
+ { 0 0 m
+ 0 __ysize l
+ __xsize __ysize l
+ __xsize 0 l
+ s
+ }
+ @Graphic
+ { //0.2c
+ ||0.2c hello, world ||0.2c
+ //0.2c
+ }
+ }
+ }
+}
+@PP
+The right parameter always appears as part of the result, and indeed the
+result is always an object whose size is identical to the size of the
+right parameter with @@OneCol and @@OneRow applied to
+it. From now on we refer to this part of the result as the {@I base}.
+@PP
+The left parameter is implementation-dependent: that is, its
+meaning is not defined by Lout, and different implementations could
+require different values for it. The following description applies to
+Basser Lout, which uses the PostScript page description language
+@Cite { $adobe1990ps }. Similar but more restricted possibilities exist
+with the PDF back end (see a separate document distributed with Lout);
+to include both, use the @@BackEnd symbol like this:
+@ID @OneRow @Code {
+"{ @BackEnd @Case {"
+" PostScript @Yield"
+" {"
+" ..."
+" }"
+" PDF @Yield"
+" {"
+" ..."
+" }"
+" }"
+" @Graphic"
+" {"
+" ..."
+" }"
+"}"
+}
+Returning to PostScript, the left parameter refers to a coordinate system
+whose origin is the bottom left-hand corner of the base. It may use the symbols
+@Code xsize and @Code ysize to denote the horizontal and vertical size
+of the base; similarly, @Code xmark and @Code ymark denote the positions
+of the base's column and row marks:
+@ID @OneRow 9p @Font @Fig {
+ { &1rt @I ysize /0ik &1rt @I ymark /0ik &1rt 0 } |0.4c
+ { /
+ |0ik @ShowMarks { 1c @High 1.5c @Wide ^| 3c @Wide ^/ 2c @High }
+ |0ik /
+ }
+ /0.2c
+ | 0 | @I xmark | @I xsize
+}
+In addition to these four symbols and 0, lengths may be denoted in
+centimetres, inches, points, ems, f's, v's and s's using the notation
+@ID @OneRow @Tab
+ vmargin { 0.5vx }
+ hmargin { 1m }
+ @Fmta { @Col {@I l @Code A} ! @Col {instead of Lout's} ! @Col {{@I l}B} }
+{
+@Rowa A { cm } B { c }
+@Rowa A { in } B { i }
+@Rowa A { pt } B { p }
+@Rowa A { em } B { m }
+@Rowa A { ft } B { f }
+@Rowa A { vs } B { v }
+@Rowa A { sp } B { s }
+}
+Note that there must be a space between the number and its unit,
+unlike Lout proper.
+@PP
+A point within the base (and, with care, a point outside it) may
+be denoted by a pair of lengths. For example,
+@ID @OneRow @Code {
+"xmark ymark"
+}
+is the point where the marks cross, and
+@ID @OneRow @Code {
+"0 2 cm"
+}
+is a point on the left edge, two centimetres above the bottom left-hand
+corner. These two numbers are called the @I {x coordinate} and the
+@I {y coordinate} of the point.
+@PP
+The first step in specifying a graphic object is to define a
+{@I path}. A path can be thought of as the track of a pen moving over
+the page. The pen may be up (not drawing) or down (drawing a line or
+curve) as it moves. The entire path is a sequence of the following
+items:
+@LP
+2i @Wide { |1rt @I {x y} @Code moveto }
+|2m Lift the pen and move it to the indicated point.
+@JP
+2i @Wide { |1rt @I {x y} @Code lineto }
+|2m Put the pen down and draw a straight line to the indicated point.
+@JP
+2i @Wide { |1rt @I {x y r angle1 angle2} @Code arc }
+|2m Put the pen down and draw a circular arc whose centre has
+coordinates @I x and @I y and whose radius is {@I r}. The arc begins
+at the angle @I angle1 measuring counterclockwise from the point
+directly to the right of the centre, and proceeds counterclockwise to
+{@I angle2}. If the arc is not the first thing on the path, a straight
+line will be drawn connecting the current point to the start of the arc.
+@JP
+2i @Wide { |1rt @I {x y r angle1 angle2} @Code arcn }
+|2m As for arc, but the arc goes clockwise from @I angle1 to
+{@I angle2 }.
+@JP
+2i @Wide @Code { |1rt closepath }
+|2m Draw a straight line back to the point most recently moved to.
+@LP
+The first item should always be a {@Code moveto}, {@Code arc}, or
+{@Code arcn}. It should be clear from this that the path given earlier:
+@ID @OneRow @Code {
+"0 0 moveto"
+"0 ysize lineto"
+"xsize ysize lineto"
+"xsize 0 lineto"
+"closepath"
+}
+traces around the boundary of the base with the pen down.
+@PP
+Once a path is set up, we are ready to @I paint it onto the page. There
+are two choices: we can either @I stroke it, which means to display it
+as described; or we can @I fill it, which means to paint everything
+inside it grey or black. For stroking the two main options are
+@IL
+@LI {
+2i @Wide { |1rt @I length @Code setlinewidth }
+|2m The pen will draw lines of the given width.
+}
+@LI {
+2i @Wide { |1rt @Code "[" @I length @Code {"]" 0 setdash} }
+|2m The pen will draw dashed lines when it is down, with the dashes each
+of the given length.
+}
+@EL
+These options are followed by the word {@Code "stroke"}. So, for example,
+@ID @OneRow @Code {
+"{ 0 0 moveto xsize 0 lineto"
+" 2 pt setlinewidth [ 5 pt ] 0 setdash stroke"
+"}"
+"@Graphic { 3i @Wide }"
+}
+has result
+@ID @OneRow {
+ @BackEnd @Case {
+ PostScript @Yield {
+ { 0 0 moveto xsize 0 lineto
+ 2 pt setlinewidth [ 5 pt ] 0 setdash stroke
+ }
+ @Graphic { 3i @Wide }
+ }
+ PDF @Yield {
+ { [ __mul(5, __pt) ] 0 d __mul(2, __pt) w 0 0 m __xsize 0 l S
+ }
+ @Graphic { 3i @Wide }
+ }
+ }
+}
+@PP
+When filling in the region enclosed by a path, the main option is
+{@Code setgray}, which determines the shade of grey to use, on a scale
+from 0 (black) to 1 (white). So, for example,
+@ID @OneRow @Code {
+"{ 0 0 moveto xsize 0 lineto 0 ysize lineto closepath"
+" 0.8 setgray fill"
+"}"
+"@Graphic"
+"{ 2c @Wide 2c @High }"
+}
+has result
+@ID @OneRow {
+ @BackEnd @Case {
+ PostScript @Yield {
+ { 0 0 moveto xsize 0 lineto 0 ysize lineto closepath
+ 0.8 setgray fill
+ }
+ @Graphic
+ { 2c @Wide 2c @High }
+ }
+ PDF @Yield {
+ { 0 0 m __xsize 0 l 0 __ysize l h
+ 0.8 g f
+ }
+ @Graphic
+ { 2c @Wide 2c @High }
+ }
+ }
+}
+@PP
+There are many other options. The value of the left parameter of
+@@Graphic may be any fragment of the PostScript page description language
+@Cite { $adobe1990ps }. Here are two other examples:
+@ID @OneRow @Code {
+xsize 2 div
+}
+denoting a length equal to half the horizontal size of the base, and
+@ID @OneRow @Code {
+gsave fill grestore stroke
+}
+which both fills and strokes the path. Since Basser Lout does not check
+that the left parameter is valid PostScript, it is possible to cause
+mysterious errors in the printing device, resulting in no output, if an
+incorrect value is given. It is a good idea to encapsulate graphics
+objects in carefully tested definitions, like those of the Diag figure
+drawing package @Cite { $kingston1995lout.user, Chapter 9 },
+diag @Index { Diag diagram-drawing package }
+to be sure of avoiding these errors.
+@PP
+PostScript experts may find the following information helpful when
+designing advanced graphics features. The left parameter of @@Graphic
+may have two parts, separated by {@Code "//"}:
+@ID @OneRow {
+@Code "{" @I {first part} @Code "//" @I {second part} @Code "} @Graphic"
+@I object
+}
+If there is no {@Code "//"}, the second part is taken to be empty. The
+PostScript output has the form
+@ID @OneRow lines @Break {
+@Code gsave
+@I x @I y @Code translate
+@I {Code which defines {@Code xsize}, {@Code ysize}, {@Code xmark}, {@Code ymark}, {@Code ft}, {@Code vs}, and {@Code sp} }
+@Code gsave
+@I {first part}
+@Code grestore
+@I {Code which renders the right parameter in translated coordinates}
+@I {second part}
+@Code grestore
+}
+where @Eq {x, y} is the position of the lower left corner of the
+base. Having two parts permits bracketing operations, like @Code save
+and @Code restore or @Code begin and {@Code end}, to enclose an
+object. See the source file of the Diag package for examples.
+@End @Section