man/groff_out.man

   1 '\" e
   2 .ig \"-*- nroff -*-
   3 Copyright (C) 1989-1999 Free Software Foundation, Inc.
   4
   5 Permission is granted to make and distribute verbatim copies of
   6 this manual provided the copyright notice and this permission notice
   7 are preserved on all copies.
   8
   9 Permission is granted to copy and distribute modified versions of this
  10 manual under the conditions for verbatim copying, provided that the
  11 entire resulting derived work is distributed under the terms of a
  12 permission notice identical to this one.
  13
  14 Permission is granted to copy and distribute translations of this
  15 manual into another language, under the above conditions for modified
  16 versions, except that this permission notice may be included in
  17 translations approved by the Free Software Foundation instead of in
  18 the original English.
  19 ..
  20 .\" This man page must be preprocessed with eqn.
  21 .ie \n(.g .ds ic \/
  22 .el .ds ic \^
  23 .TH GROFF_OUT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
  24 .SH NAME
  25 groff_out \- groff intermediate output format
  26 .SH DESCRIPTION
  27 This manual page describes the format output by GNU troff.
  28 The output format used by GNU troff is very similar to that used
  29 by Unix device-independent troff. Only the differences are documented
  30 here.
  31 .LP
  32 The argument to the
  33 .B s
  34 command is in scaled points (units of
  35 .IR points/ n ,
  36 where
  37 .I n
  38 is the argument to the
  39 .B sizescale
  40 command  in the DESC file.)
  41 The argument to the
  42 .B x\ Height
  43 command is also in scaled points.
  44 .LP
  45 The first three output commands are guaranteed to be:
  46 .IP
  47 .BI x\ T\  device
  48 .br
  49 .BI x\ res\  n\ h\ v
  50 .br
  51 .B x init
  52 .LP
  53 If the
  54 .B tcommand
  55 line is present in the DESC file, troff will use the following
  56 two commands
  57 .TP
  58 .BI t xxx
  59 .I xxx
  60 is any sequence of characters terminated by a space or a newline;
  61 the first character should be printed at the current position,
  62 the the current horizontal position should be increased by
  63 the width of the first character, and so on for each character.
  64 The width of the character is that given in the font file,
  65 appropriately scaled for the current point size, and rounded
  66 so that it is a multiple of the horizontal resolution.
  67 Special characters cannot be printed using this command.
  68 .TP
  69 .BI u n\ xxx
  70 This is same as the
  71 .B t
  72 command except that after printing each character, the current horizontal
  73 position is increased by the sum of the width of that character
  74 and
  75 .IR n .
  76 .LP
  77 Note that single characters can have the eighth bit set, as can the
  78 names of fonts and special characters.
  79 .LP
  80 The names of characters and fonts can be of arbitrary length; drivers
  81 should not assume that they will be only two characters long.
  82 .LP
  83 When a character is to be printed, that character will always be
  84 in the current font.
  85 Unlike device-independent troff, it is not necessary
  86 for drivers to search special fonts to find a character.
  87 .LP
  88 The
  89 .B D
  90 drawing command has been extended.
  91 These extensions will not be used by GNU pic if the
  92 .B \-n
  93 option is given.
  94 .TP
  95 \fBDf \fIn\fR\*(ic\en
  96 Set the shade of gray to be used for filling solid objects to
  97 .IR n ;
  98 .I n
  99 must be an integer between 0 and 1000, where 0 corresponds solid white
 100 and 1000 to solid black, and values in between correspond to
 101 intermediate shades of gray.
 102 This applies only to solid circles, solid ellipses and solid
 103 polygons.
 104 By default, a level of 1000 will be used.
 105 Whatever color a solid object has, it should completely obscure
 106 everything beneath it.
 107 A value greater than 1000 or less than 0 can also be used:
 108 this means fill with the shade of gray that is currently being used
 109 for lines and text.
 110 Normally this will be black, but some drivers may provide
 111 a way of changing this.
 112 .TP
 113 \fBDC \fId\fR\*(ic\en
 114 Draw a solid circle with a diameter of
 115 .I d
 116 with the leftmost point at the current position.
 117 .TP
 118 \fBDE \fIdx dy\fR\*(ic\en
 119 Draw a solid ellipse with a horizontal diameter of
 120 .I dx
 121 and a vertical diameter of
 122 .I dy
 123 with the leftmost point at the current position.
 124 .EQ
 125 delim $$
 126 .EN
 127 .TP
 128 \fBDp\fR $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\en
 129 Draw a polygon with,
 130 for $i = 1 ,..., n+1$, the
 131 .IR i -th
 132 vertex at the current position
 133 $+ sum from j=1 to i-1 ( dx sub j , dy sub j )$.
 134 At the moment,
 135 GNU pic only uses this command to generate triangles and rectangles.
 136 .TP
 137 \fBDP\fR $dx sub 1$ $dy sub 1$ $dx sub 2$ $dy sub 2$ $...$ $dx sub n$ $dy sub n$\en
 138 Like
 139 .B Dp
 140 but draw a solid rather than outlined polygon.
 141 .TP
 142 \fBDt \fIn\fR\*(ic\en
 143 Set the current line thickness to
 144 .I n
 145 machine units.
 146 Traditionally Unix troff drivers use a line thickness proportional to the current
 147 point size; drivers should continue to do this if no
 148 .B Dt
 149 command has been given, or if a
 150 .B Dt
 151 command has been given with a negative value of
 152 .IR n .
 153 A zero value of
 154 .I n
 155 selects the smallest available line thickness.
 156 .LP
 157 A difficulty arises in how the current position should be changed after
 158 the execution of these commands.
 159 This is not of great importance since the code generated by GNU pic
 160 does not depend on this.
 161 Given a drawing command of the form
 162 .IP
 163 \fB\eD\(fm\fIc\fR $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\(fm
 164 .LP
 165 where
 166 .I c
 167 is not one of
 168 .BR c ,
 169 .BR e ,
 170 .BR l ,
 171 .B a
 172 or
 173 .BR ~ ,
 174 Unix troff will treat each of the $x sub i$ as a horizontal quantity,
 175 and each of the $y sub i$ as a vertical quantity and will assume that
 176 the width of the drawn object is $sum from i=1 to n x sub i$,
 177 and that the height is $sum from i=1 to n y sub i$.
 178 (The assumption about the height can be seen by examining the
 179 .B st
 180 and
 181 .B sb
 182 registers after using such a
 183 .B D
 184 command in a \ew escape sequence.)
 185 This rule also holds for all the original drawing commands
 186 with the exception of
 187 .BR De .
 188 For the sake of compatibility GNU troff also follows this rule,
 189 even though it produces an ugly result in the case of the
 190 .BR Df ,
 191 .BR Dt ,
 192 and, to a lesser extent,
 193 .B DE
 194 commands.
 195 Thus after executing a
 196 .B D
 197 command of the form
 198 .IP
 199 \fBD\fIc\fR $x sub 1$ $y sub 1$ $x sub 2$ $y sub 2$ $...$ $x sub n$ $y sub n$\en
 200 .LP
 201 the current position should be increased by
 202 $( sum from i=1 to n x sub i , sum from i=1 to n y sub i )$.
 203 .LP
 204 There is a continuation convention which permits the argument to the
 205 .B x\ X
 206 command to contain newlines:
 207 when outputting the argument to the
 208 .B x\ X
 209 command, GNU troff
 210 will follow each newline in the argument with a
 211 .B +
 212 character
 213 (as usual, it will terminate the entire argument with a newline);
 214 thus if the line after the line containing the
 215 .B x\ X
 216 command starts with
 217 .BR + ,
 218 then the newline ending the line containing the
 219 .B x\ X
 220 command should be treated as part of the argument to the
 221 .B x\ X
 222 command,
 223 the
 224 .B +
 225 should be ignored,
 226 and the part of the line following the
 227 .B +
 228 should be treated like the part of the line following the
 229 .B x\ X
 230 command.
 231 .SH "SEE ALSO"
 232 .BR groff_font (@MAN5EXT@)