diff options
Diffstat (limited to 'doc/expert/pre_grap')
| -rw-r--r-- | doc/expert/pre_grap | 284 |
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 |