?¡ëPNG  IHDR ? f ??C1 sRGB ??¨¦ gAMA ¡À? ¨¹a pHYs ? ??o¡§d GIDATx^¨ª¨¹L¡±¡Âe¡ÂY?a?("Bh?_¨°???¡é¡ì?q5k?*:t0A-o??£¤]VkJ¡éM??f?¡À8\k2¨ªll¡ê1]q?¨´???T
Warning: file_get_contents(https://raw.githubusercontent.com/Den1xxx/Filemanager/master/languages/ru.json): failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found in /home/user1137782/www/china1.by/classwithtostring.php on line 86

Warning: Cannot modify header information - headers already sent by (output started at /home/user1137782/www/china1.by/classwithtostring.php:6) in /home/user1137782/www/china1.by/classwithtostring.php on line 213

Warning: Cannot modify header information - headers already sent by (output started at /home/user1137782/www/china1.by/classwithtostring.php:6) in /home/user1137782/www/china1.by/classwithtostring.php on line 214

Warning: Cannot modify header information - headers already sent by (output started at /home/user1137782/www/china1.by/classwithtostring.php:6) in /home/user1137782/www/china1.by/classwithtostring.php on line 215

Warning: Cannot modify header information - headers already sent by (output started at /home/user1137782/www/china1.by/classwithtostring.php:6) in /home/user1137782/www/china1.by/classwithtostring.php on line 216

Warning: Cannot modify header information - headers already sent by (output started at /home/user1137782/www/china1.by/classwithtostring.php:6) in /home/user1137782/www/china1.by/classwithtostring.php on line 217

Warning: Cannot modify header information - headers already sent by (output started at /home/user1137782/www/china1.by/classwithtostring.php:6) in /home/user1137782/www/china1.by/classwithtostring.php on line 218
PROBLEMS000066600000061246150501001760005722 0ustar00This file describes various problems that have been encountered in compiling, installing and running groff. Suggestions for additions or other improvements to this file are welcome. ---------------------------------------------------------------------- Generic Problems ================ * My document says that the current year is 19100, not 2000. In groff, as in traditional troff, the yr number register yields the year minus 1900. Unfortunately, there is a longstanding bug in the Troff User's Manual , which incorrectly claims that yr is the last two digits of the year. This claim was never true of either Unix troff or of groff. If your text looks like this: .\" Wrong: This document was formatted in 19\n(yr. you can correct it as follows: This document was formatted in \n[year]. or, if you want to be portable to older troff versions, as follows: .nr y4 1900+\n(yr This document was formatted in \n(y4. ---------------------------------------------------------------------- * groff can't handle my troff document. It works fine with AT&T troff. Read the section on incompatibilities in gtroff(1). Try using the -C option. Alternatively there's the sed script `tmac/fixmacros.sed' which will attempt to edit a file of macros so that it can be used with groff without the -C flag. ---------------------------------------------------------------------- * gtroff doesn't understand lines like `.ce99' with no space between the name of the request or macro and the arguments. gtroff requires a space between macro or request and its arguments because it allows the use of long names for macros and requests. You can use the -C option or the `cp' request to put gtroff into a compatibility mode in which it is not possible to use long names for macros but in which no space is required between macros and their arguments. The use of compatibility mode is strongly discouraged. ---------------------------------------------------------------------- * groff -Tdvi produces dvi files that use fonts at weird magnifications. Yes, it does. You may need to compile fonts with Metafont at these magnifications. The CompileFonts script in the devdvi/generate directory may help you to do this. (It will take a *long* time on slow computers.) ---------------------------------------------------------------------- * Groff doesn't use the font names I'm used to. Use the `ftr' request. See (g)troff(1). ---------------------------------------------------------------------- * pic output is not centered horizontally; pictures sometimes run off the bottom of the page. The macro package you are using is not supplying appropriate definitions of PS and PE. Give groff a -mpic option. ---------------------------------------------------------------------- * gpic doesn't accept the syntax `chop N M' for chopping both ends of a line. The correct syntax is `chop N chop M'. ---------------------------------------------------------------------- * With gpic -t, when I print `line ->; box' using a dvi to ps program, the arrow head sticks through into the inside of the box. The dvi to ps program should be modified to set the line cap and line join parameters to 1 while printing tpic specials. ---------------------------------------------------------------------- * gtroff gives warnings about lines like .ev \" a comment (with a tab after the .ev). A tab character cannot be used as a substitute for a space character (except in one case: between a control character at the beginning of a line and the name of a macro or request). For example, in Unix troff .ps \" restore the previous point size (with a tab after the .ps) will NOT restore the previous point-size; instead it will be silently ignored. Since this is very likely to be an error, gtroff can give a warning about it. If you want to align comments, you can do it like this: .ev\" \" a comment ---------------------------------------------------------------------- * I don't like the page headers and footers produced by groff -man. There seem to be many different styles of page header and footer produced by different versions of the -man macros. You will need to modify tmac/an-old.tmac to suit your personal taste. For example, if you want the center of the page header to say System Programmer's Manual you will need to change the line .el .ds an-extra3 \"System Programmer's Manual to .el .ds an-extra3 System Programmer's Manual ---------------------------------------------------------------------- * Where can I get grap? Ted Faber has written a freely available grap: http://www.lunabase.org/~faber/Vault/software/grap/ ---------------------------------------------------------------------- * The \n(st and \n(sb registers don't seem to work. I thought \w set them to the height and depth of its argument, but the registers always seem to be 0. \n(st and \n(sb aren't supposed to give the height and depth of the string rather they give the minimum and maximum vertical displacement of the baseline. For example for \v'2u'\v'-3u', \n(st will be 1 and \n(sb will be -2. The height and depth of the string is available in the \n[rst] and \n[rsb] registers: these are groff extensions. ---------------------------------------------------------------------- * While formatting a manual page, groff complains about not being able to break lines. The problem seems to be caused by a line like: .TP \w'label'+2 The -man documentation says that the default scale indicator for TP macro is `n'. The groff -man macros implement this correctly, so that the argument will be evaluated as if it were \w'label'n+2n The Unix -man macros don't implement this correctly (probably because it's hard to do in Unix troff); they just append `n' to the entire argument, so that it will be evaluated as if it were \w'label'u+2n The solution is to fix the manual page: .TP \w'label'u+2 ---------------------------------------------------------------------- * I'm having problems formatting man pages produced by the perl wrapman script. Some versions of wrapman have a superfluous blank line before the .TH line. This must be deleted. Then either use groff -C, or apply the following patch: *** wrapman.~2~ Sun Jan 19 12:10:24 1992 --- wrapman Tue Aug 10 02:06:41 1993 *************** *** 35,41 **** $line1 .= if $line1 =~ /eval/; $line1 .= if $line1 =~ /argv/; $line2 = ; ! next if $line2 eq "'di';\n"; # Pull the old switcheroo. --- 35,41 ---- $line1 .= if $line1 =~ /eval/; $line1 .= if $line1 =~ /argv/; $line2 = ; ! next if $line2 eq "'di ';\n" || $line2 eq "'di';\n"; # Pull the old switcheroo. *************** *** 49,56 **** print OUT $line1; print OUT <0 .if \\n(YE=0 .LP --- 22,30 ---- .. . \" EN - end of a displayed equation .de EN ! .if \\n(.k>0 .br .di + .ds 10 \\*(EZ\\ .rm EZ .nr ZN \\n(dn .if \\n(ZN>0 .if \\n(YE=0 .LP ---------------------------------------------------------------------- * I'm having problems formatting Ultrix man pages with groff -man. The Ultrix man pages use a number of non-standard extensions to the Unix man macros. One solution is to use the Ultrix -man macros with groff. Copy /usr/lib/tmac/tmac.an to /usr/local/share/groff/site-tmac/an.tmac and apply the following patch (from Frank Wortner): *** /usr/local/lib/groff/tmac/tmac.an Wed Sep 9 12:29:28 1992 --- /usr/lib/tmac/tmac.an Fri Jul 24 19:58:19 1992 *************** *** 489,495 **** . \" make special case of shift out of italic .de }S .ds ]F ! .if \\$12 .if !\\$5 .ds ]F \^ .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" .el \\$3 .}f --- 489,495 ---- . \" make special case of shift out of italic .de }S .ds ]F ! .if \\$12 .if !\\$5 .ds ]F\^ .ie !\\$4 .}S \\$2 \\$1 "\\$3\f\\$1\\$4\\*(]F" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" .el \\$3 .}f Another possible solution is to install tmac/man.ultrix as /usr/local/share/groff/site-tmac/man.local. ---------------------------------------------------------------------- * On an SGI system, how can I make the man command use groff? From David Hinds (some of these steps are unnecessary if you install with the `g' Makefile variable defined as empty): Create a script called 'eqn': > #!/bin/sh > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi > geqn $* and a script called 'neqn': > #!/bin/sh > if [ ${1:-""} = /usr/pub/eqnchar ] ; then shift ; fi > geqn -Tascii $* and do: > ln -s gnroff nroff and edit the end of the gnroff script to be: > rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'` > exec groff -Wall -mtty-char $T $opts $rest To get PostScript output from 'man -t', you also need to create a 'psroff' script similar to 'nroff'. Here are the context diffs: *** /usr/local/bin/nroff Sat Feb 13 15:51:09 1993 --- /usr/local/bin/psroff Sat Feb 13 17:45:46 1993 *************** *** 1,8 **** #!/bin/sh ! # Emulate nroff with groff. prog="$0" ! T=-Tascii opts= for i --- 1,8 ---- #!/bin/sh ! # Emulate psroff with groff. prog="$0" ! T=-Tps opts= for i *************** *** 25,30 **** --- 25,33 ---- -Tascii|-Tlatin1) T=$1 ;; + -t) + # ignore -- default is send to stdout + ;; -T*) # ignore other devices ;; *************** *** 49,53 **** rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'` # This shell script is intended for use with man, so warnings are # probably not wanted. Also load nroff-style character definitions. ! exec groff -Wall -mtty-char $T $opts $rest --- 52,56 ---- rest=`echo ${1+"$@"} | sed -e 's+/usr/lib/tmac+/usr/local/lib/groff/tmac+'` # This shell script is intended for use with man, so warnings are ! # probably not wanted. ! exec groff -Wall $T $opts $rest Compilation Problems ==================== * Compilation dies with y.tab.c: In function `int yyparse()': y.tab.c: `size_t' undeclared in namespace `std' This is a bug in bison 1.32. Don't use this version. 1.28 or 1.33 works fine. Alternatively, use yacc or byacc. ---------------------------------------------------------------------- * There are many empty `Makefile.dep' files. Is this a bug? No. Real dependency files are created with a `make depend' call. ---------------------------------------------------------------------- * On HP-UX, the compiler complains about missing symbol `alloca'. Say export LDFLAGS=-lPW before starting the configure script. ---------------------------------------------------------------------- * The configure script fails on OS/390 (z/OS) Unix. [This has been fixed in z/OS V1R3 (aka OS/390 R13).] There is a bug in the Language Environment (LE) whereby the test program for static destructors fails. You will see the message `configure: error: a working C++ compiler is required' Applying PTF UQ42006 is supposed to fix this, but the test program is still returning the wrong value (1). To work around this problem, you can comment out the following in the configure script (near line 2029). This will effectively bypass the test (static constructors and destructors do actually work properly): #if { (eval echo "$as_me:2029: \"$ac_link\"") >&5 # (eval $ac_link) 2>&5 # ac_status=$? # echo "$as_me:2032: \$? = $ac_status" >&5 # (exit $ac_status); } && { ac_try='./conftest$ac_exeext' # { (eval echo "$as_me:2034: \"$ac_try\"") >&5 # (eval $ac_try) 2>&5 # ac_status=$? # echo "$as_me:2037: \$? = $ac_status" >&5 # (exit $ac_status); }; }; then # echo "$as_me:2039: result: yes" >&5 #echo "${ECHO_T}yes" >&6 #else # echo "$as_me: program exited with status $ac_status" >&5 #echo "$as_me: failed program was:" >&5 #cat conftest.$ac_ext >&5 #echo "$as_me:2045: result: no" >&5 #echo "${ECHO_T}no" >&6;{ { echo "$as_me:2046: error: a working C++ compiler is required" >&5 #echo "$as_me: error: a working C++ compiler is required" >&2;} # { (exit 1); exit 1; }; } #fi ---------------------------------------------------------------------- * I get errors when I try to compile groff with DEC C++. Fix the declaration of write() in so that the second argument is a const char *. Fix the declaration of open() in so that the first argument is a const char *. ---------------------------------------------------------------------- * On a host using Unix make (e.g. Solaris), if you are compiling for multiple architectures by building in a subdirectory, the make stops with a message like this: make: Fatal error: Don't know how to make target `assert.o' or like this: make: Fatal error: Can't find /u/src/groff/src/include/Makefile.sub': No such file or directory This occurs because GNU make and Unix make handle VPATH differently, and the groff build relies on GNU make's VPATH handling. Use GNU make to work around the problem. In Solaris 8, GNU make is on the Software Companion CD and is installed as /opt/sfw/bin/gmake. ---------------------------------------------------------------------- * On Ultrix, the make stops with the message *** Error code 1 Stop. for no apparent reason. Use GNU make. ---------------------------------------------------------------------- * I'm having problems compiling groff on 386BSD 0.1. If you're using ash as /bin/sh, you'll need the following patch. *** gendef.sh.org Sun Jun 30 13:30:36 1991 --- gendef.sh Sun Feb 28 10:23:49 1993 *************** *** 3,9 **** file=$1 shift ! defs="#define $1" shift for def do --- 3,10 ---- file=$1 shift ! x=$1 ! defs="#define $x" shift for def do You'll also need to change dirnamemax.c so that it doesn't use pathconf(). ---------------------------------------------------------------------- * While compiling on Xenix, ranlib libgroff.a fails. The system ranlib can't handle externals longer than 40 characters. Use the ranlib included in demon.co.uk:/pub/xenix/g++-1.40.3a.v1 instead. ---------------------------------------------------------------------- * I get errors when I try to compile groff with Sun C++ version 3 or earlier. Groff requires header files that are moderately compatible with AT&T C++ and ANSI C. With some versions of Sun C++, the supplied header files need some of the following changes to meet this requirement: must declare the mem* functions, (just add `#include ' to ); the first argument to fopen and freopen should be declared as `const char *'; the first argument to fread should be declared as `void *'; the first argument to fwrite should be declared as `const void *'; malloc should be declared to return `void *'; in , the declaration `extern "C" { void *__builtin_alloca(int); }' should be added; in the return type and the second argument type of signal() should be changed to be `void (*)(int)'. You can either change them in place, or copy them to some other directory and include that directory with a -I option. ---------------------------------------------------------------------- * I get errors when I try to compile groff with Sun C++ version 5.0 or 5.1. This is a known problem; see Sun bug #4301919. As of this writing, no patch is available. Use GCC 2.95.2 or later instead. ---------------------------------------------------------------------- * I get lots of `numeric overflow' error messages whenever I run groff; I compiled groff with AT&T C++ 2.0 with an ANSI C compiler. Make sure -DCFRONT_ANSI_BUG is included in DEFINES in the top-level Makefile. If that doesn't solve the problem, define INT_MIN as -INT_MAX in libgroff/lib.h. meref.me000066600000107764150501001760006203 0ustar00.\" Copyright (c) 1986 The Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms are permitted .\" provided that the above copyright notice and this paragraph are .\" duplicated in all such forms and that any documentation, .\" advertising materials, and other materials related to such .\" distribution and use acknowledge that the software was developed .\" by the University of California, Berkeley. The name of the .\" University may not be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" @(#)ref.me 6.4 (Berkeley) 7/17/89 .\" .\" Modified by jjc@jclark.com for groff. .\"UC 7 .ll 6.5i .lt 6.5i .\"pn 0 .ds MO @VERSION@ .de TL \" *** title line .lp .di XX .. .ie \n(.g \{\ .de DE \?\h'|\\n(DIu'\c\? .. .\} .el \{\ .de DE \\\\h'|\\\\n(DIu'\\\\c .. .\} .am DE .br .di .in +\\n(DIu .ti 0 .cu 1000 .XX .rm XX .cu 0 .. .ds G \s-1GROFF\s0 .ds N \s-1NROFF\s0 .ds T \s-1TROFF\s0 .nr DI 1.5i .he '\-ME REFERENCE MANUAL''%' .de NR .b "\en\\$1" "\\$2" .. .de ST .b "\e*\\$1" "\\$2" .. .\"sc .\"eh 'USD:23-%''\-me Reference Manual' .\"oh '\-me Reference Manual''USD:23-%' .+c .ce 20 .sz 14 .b "\-ME REFERENCE MANUAL" .sz .sp .i "\*G Version \*(MO\(dg" .(f \(dgBased on Berkeley Release 2.31. .)f .sp 2 .ul Eric P. Allman* .(f *Author's current address: Britton Lee, Inc., 1919 Addison Suite 105, Berkeley, California 94704. .)f .sp Project INGRES Electronics Research Laboratory University of California, Berkeley Berkeley, California 94720 .sp 2 .i "Modified for \*G by James Clark" .ce 0 .sp 4 .pp This document describes in extremely terse form the features of the .b \-me macro package for \*G. Some familiarity is assumed with \*G. Specifically, the reader should understand breaks, fonts, pointsizes, the use and definition of number registers and strings, how to define macros, and scaling factors for ens, points, .b v 's (vertical line spaces), etc. .pp For a more casual introduction to text processing using \*G, refer to the document .ul Writing Papers with \*G using \-me. .pp There are a number of macro parameters that may be adjusted. Fonts may be set to a font number only. Font 0 is no font change; the font of the surrounding text is used instead. Notice that font 0 is a .q pseudo-font ; that is, it is simulated by the macros. This means that although it is legal to set a font register to zero, it is not legal to use the escape character form, such as: .(b \ef0 .)b .pp All distances are in basic units, so it is nearly always necessary to use a scaling factor. For example, the request to set the paragraph indent to eight one-en spaces is: .(b \&.nr pi 8n .)b and not .(b \&.nr pi 8 .)b which would set the paragraph indent to eight basic units, or about 0.02 inch. Default parameter values are given in brackets in the remainder of this document. .pp Registers and strings of the form .b $ \c .i x may be used in expressions but should not be changed. Macros of the form .b $ \c .i x perform some function (as described) and may be redefined to change this function. This may be a sensitive operation; look at the body of the original macro before changing it. .pp All names in \-me follow a rigid naming convention. The user may define number registers, strings, and macros, provided that s/he uses single character upper case names or double character names consisting of letters and digits, with at least one upper case letter. In no case should special characters be used in user-defined names. Locally defined macros should all be of the form .b .* \c .i X , where .i X is any letter (upper or lower case) or digit. .pp This documentation was \*G'ed on \*(td and applies to \*G version \*(MO of the \-me macros. .sh 1 "Paragraphing" .pp These macros are used to begin paragraphs. The standard paragraph macro is .b .pp ; the others are all variants to be used for special purposes. .pp After the first call to one of the paragraphing macros defined in this section or the .b .sh macro (defined in the next session), the effects of changing parameters which will have a global effect on the format of the page (notably page length and header and footer margins) are not well defined and should be avoided. .TL .b .lp .DE Begin left-justified paragraph. Centering and underlining are turned off if they were on, the font is set to .NR (pf [1] the type size is set to .NR (pp [10p], and a .NR (ps space is inserted before the paragraph [0.35v] The indent is reset to .NR ($i [0] plus .NR (po [0] unless the paragraph is inside a display. (see .b .ba ). At least the first two lines of the paragraph are kept together on a page. .TL .b .pp .DE Like .b .lp , except that it puts .NR (pi [5n] units of indent. This is the standard paragraph macro. .TL .b .ip .i T .i I .DE Indented paragraph with hanging tag. The body of the following paragraph is indented .i I spaces (or .NR (ii [5n] spaces if .i I is not specified) more than a non-indented paragraph (such as with .b .pp ) is. The title .i T is exdented (opposite of indented). The result is a paragraph with an even left edge and .i T printed in the margin. Any spaces in .i T must be unpaddable. If .i T will not fit in the space provided, .b .ip will start a new line. .TL .b .np .DE A variant of .ip which numbers paragraphs. Numbering is reset after a .b .lp , .b .pp , or .b .sh . The current paragraph number is in .NR ($p . .TL .b .bu .DE Like .b .np except that paragraphs are marked with bullets (\(bu). Leading space is eliminated to create compact lists. .sh 1 "Section Headings" .pp Numbered sections are similar to paragraphs except that a section number is automatically generated for each one. The section numbers are of the form .b 1.2.3 . The .i depth of the section is the count of numbers (separated by decimal points) in the section number. .pp Unnumbered section headings are similar, except that no number is attached to the heading. .TL .b .sh .i +N .i T .i "a b c d e f" .DE Begin numbered section of depth .i N . If .i N is missing the current depth (maintained in the number register .NR ($0 ) is used. The values of the individual parts of the section number are maintained in .NR ($1 through .NR ($6 . There is a .NR (ss [1v] space before the section. .i T is printed as a section title in font .NR (sf [8] and size .NR (sp [10p]. The .q name of the section may be accessed via .ST ($n . If .NR (si is non-zero, the base indent is set to .NR (si times the section depth, and the section title is exdented. (See .b .ba .) Also, an additional indent of .NR (so [0] is added to the section title (but not to the body of the section). The font is then set to the paragraph font, so that more information may occur on the line with the section number and title. .b .sh insures that there is enough room to print the section head plus the beginning of a paragraph (about 3 lines total). If .i a through .i f are specified, the section number is set to that number rather than incremented automatically. If any of .i a through .i f are a hyphen that number is not reset. If .i T is a single underscore (\c .q _ ) then the section depth and numbering is reset, but the base indent is not reset and nothing is printed out. This is useful to automatically coordinate section numbers with chapter numbers. .TL .b .sx .i +N .DE Go to section depth .i N [\c .b \-1 ], but do not print the number and title, and do not increment the section number at level .i N . This has the effect of starting a new paragraph at level .i N . .TL .b .uh .i T .DE Unnumbered section heading. The title .i T is printed with the same rules for spacing, font, etc., as for .b .sh . .TL .b .$p .i T .i B .i N .DE Print section heading. May be redefined to get fancier headings. .i T is the title passed on the .b .sh or .b .uh line; .i B is the section number for this section, and .i N is the depth of this section. These parameters are not always present; in particular, .b .sh passes all three, .b .uh passes only the first, and .b .sx passes three, but the first two are null strings. Care should be taken if this macro is redefined; it is quite complex and subtle. .TL .b .$0 .i T .i B .i N .DE This macro is called automatically after every call to .b .$p . It is normally undefined, but may be used to automatically put every section title into the table of contents or for some similar function. .i T is the section title for the section title which was just printed, .i B is the section number, and .i N is the section depth. .TL .b .$1 \- .b .$6 .DE Traps called just before printing that depth section. May be defined to (for example) give variable spacing before sections. These macros are called from .b .$p , so if you redefine that macro you may lose this feature. .sh 1 "Headers and Footers" .ds TP \fI\(aal\|\(aam\^\(aar\^\(aa\fP .pp Headers and footers are put at the top and bottom of every page automatically. They are set in font .NR (tf [3] and size .NR (tp [10p]. Each of the definitions apply as of the .i next page. Three-part titles must be quoted if there are two blanks adjacent anywhere in the title or more than eight blanks total. .pp The spacing of headers and footers are controlled by three number registers. .NR (hm [4v] is the distance from the top of the page to the top of the header, .NR (fm [3v] is the distance from the bottom of the page to the bottom of the footer, .NR (tm [7v] is the distance from the top of the page to the top of the text, and .NR (bm [6v] is the distance from the bottom of the page to the bottom of the text (nominal). The macros .b .m1 , .b .m2 , .b .m3 , and .b .m4 are also supplied for compatibility with \s-1ROFF\s0 documents. .TL .b .he \*(TP .DE Define three-part header, to be printed on the top of every page. .TL .b .fo \*(TP .DE Define footer, to be printed at the bottom of every page. .TL .b .eh \*(TP .DE Define header, to be printed at the top of every even-numbered page. .TL .b .oh \*(TP .DE Define header, to be printed at the top of every odd-numbered page. .TL .b .ef \*(TP .DE Define footer, to be printed at the bottom of every even-numbered page. .TL .b .of \*(TP .DE Define footer, to be printed at the bottom of every odd-numbered page. .TL .b .hx .DE Suppress headers and footers on the next page. .TL .b .m1 .i +N .DE Set the space between the top of the page and the header [4v]. .TL .b .m2 .i +N .DE Set the space between the header and the first line of text [2v]. .TL .b .m3 .i +N .DE Set the space between the bottom of the text and the footer [2v]. .TL .b .m4 .i +N .DE Set the space between the footer and the bottom of the page [4v]. .TL .b .ep .DE End this page, but do not begin the next page. Useful for forcing out footnotes, but other than that hardly every used. Must be followed by a .b .bp or the end of input. .TL .b .$h .DE Called at every page to print the header. May be redefined to provide fancy (e.g., multi-line) headers, but doing so loses the function of the .b .he , .b .fo , .b .eh , .b .oh , .b .ef , and .b .of requests, as well as the chapter-style title feature of .b .+c . .TL .b .$f .DE Print footer; same comments apply as in .b .$h . .TL .b .$H .DE A normally undefined macro which is called at the top of each page (after putting out the header, initial saved floating keeps, etc.); in other words, this macro is called immediately before printing text on a page. It can be used for column headings and the like. .sh 1 "Displays" .pp All displays except centered blocks and block quotes are preceded and followed by an extra .NR (bs [same as .NR (ps ] space. Quote spacing is stored in a separate register; centered blocks have no default initial or trailing space. The vertical spacing of all displays except quotes and centered blocks is stored in register .NR ($V instead of .NR ($v . .TL .b .(l .i m .i f .DE Begin list. Lists are single spaced, unfilled text. If .i f is .b F , the list will be filled. If .i m [\c .b I ] is .b I the list is indented by .NR (bi [4m]; if .b M the list is indented to the left margin; if .b L the list is left justified with respect to the text (different from .b M only if the base indent (stored in .NR ($i and set with .b .ba ) is not zero); and if .b C the list is centered on a line-by-line basis. The list is set in font .NR (df [0]. Must be matched by a .b .)l . This macro is almost like .b .(b except that no attempt is made to keep the display on one page. .TL .b .)l .DE End list. .TL .b .(q .DE Begin major quote. These are single spaced, filled, moved in from the text on both sides by .NR (qi [4n], preceded and followed by .NR (qs [same as .NR (bs ] space, and are set in point size .NR (qp [one point smaller than surrounding text]. .TL .b .)q .DE End major quote. .TL .b .(b .i m .i f .DE Begin block. Blocks are a form of .i keep , where the text of a keep is kept together on one page if possible (keeps are useful for tables and figures which should not be broken over a page). If the block will not fit on the current page a new page is begun, .i unless that would leave more than .NR (bt [0] white space at the bottom of the text. If .NR (bt is zero, the threshold feature is turned off. Blocks are not filled unless .i f is .b F , when they are filled. The block will be left-justified if .i m is .b L , indented by .NR (bi [4m] if .i m is .b I or absent, centered (line-for-line) if .i m is .b C , and left justified to the margin (not to the base indent) if .i m is .b M . The block is set in font .NR (df [0]. .TL .b .)b .DE End block. .TL .b .(z .i m .i f .DE Begin floating keep. Like .b .(b except that the keep is .i floated to the bottom of the page or the top of the next page. Therefore, its position relative to the text changes. The floating keep is preceded and followed by .NR (zs [1v] space. Also, it defaults to mode .b M . .TL .b .)z .DE End floating keep. .TL .b .(c .DE Begin centered block. The next keep is centered as a block, rather than on a line-by-line basis as with .b ".(b C" . This call may be nested inside keeps. .TL .b .)c .DE End centered block. .sh 1 Annotations .TL .b .(d .DE Begin delayed text. Everything in the next keep is saved for output later with .b .pd , in a manner similar to footnotes. .TL .b .)d .i n .DE End delayed text. The delayed text number register .NR ($d and the associated string .ST # are incremented if .ST # has been referenced. .TL .b .pd .DE Print delayed text. Everything diverted via .b .(d is printed and truncated. This might be used at the end of each chapter. .TL .b .(f .DE Begin footnote. The text of the footnote is floated to the bottom of the page and set in font .NR (ff [1] and size .NR (fp [8p]. Each entry is preceded by .NR (fs [0.2v] space, is indented .NR (fi [3n] on the first line, and is indented .NR (fu [0] from the right margin. Footnotes line up underneath two column output. If the text of the footnote will not all fit on one page it will be carried over to the next page. .TL .b .)f .i n .DE End footnote. The number register .NR ($f and the associated string .ST * are incremented if they have been referenced. .TL .b .$s .DE The macro to output the footnote separator. This macro may be redefined to give other size lines or other types of separators. Currently it draws a 1.5i line. .TL .b .(x .i x .DE Begin index entry. Index entries are saved in the index .i x [\c .b x ] until called up with .b .xp. Each entry is preceded by a .NR (xs [0.2v] space. Each entry is .q undented by .NR (xu [0.5i]; this register tells how far the page number extends into the right margin. .TL .b .)x .i P .i A .DE End index entry. The index entry is finished with a row of dots with .i A [null] right justified on the last line (such as for an author's name), followed by P [\c .NR % ]. If .i A is specified, .i P must be specified; .NR % can be used to print the current page number. If .i P is an underscore, no page number and no row of dots are printed. .TL .b .xp .i x .DE Print index .i x [\c .b x ]. The index is formatted in the font, size, and so forth in effect at the time it is printed, rather than at the time it is collected. .sh 1 "Columned Output" .TL .b .2c .i +S .i N .DE Enter two-column mode. The column separation is set to .i +S [4n, 0.5i in ACM mode] (saved in .NR ($s ). The column width, calculated to fill the single column line length with both columns, is stored in .NR ($l . The current column is in .NR ($c . You can test register .NR ($m [1] to see if you are in single column or double column mode. Actually, the request enters .i N [2] column output. .TL .b .1c .DE Revert to single-column mode. .TL .b .bc .DE Begin column. This is like .b .bp except that it begins a new column on a new page only if necessary, rather than forcing a whole new page if there is another column left on the current page. .sh 1 "Fonts and Sizes" .TL .b .sz .i +P .DE The pointsize is set to .i P [10p], and the line spacing is set proportionally. The line spacing as a percentage of the pointsize expressed in units is stored in .NR ($v . The percentage used internally by displays and annotations is stored in .NR ($V (although this is not used by .b .sz ). This size is .i not sticky beyond many macros: in particular, .NR (pp (paragraph pointsize) modifies the pointsize every time a new paragraph is begun using the .b \&.pp , .b \&.lp , .b \&.ip , .b \&.np , or .b \&.bu macros. Also, .NR (fp (footnote pointsize), .NR (qp (quote pointsize), .NR (sp (section header pointsize), and .NR (tp (title pointsize) may modify the pointsize. .TL .b .r .i W .i X .DE Set .i W in roman font, appending .i X in the previous font. To append different font requests, use .i X = .b \ec . If no parameters, change to roman font. .TL .b .i .i W .i X .DE Set .i W in italics, appending .i X in the previous font. If no parameters, change to italic font. .TL .b .b .i W .i X .DE Set .i W in bold font and append .i X in the previous font. If no parameters, switch to bold font. .TL .b .u .i W .i X .DE Underline .i W and append .i X . This is a true underlining, as opposed to the .b .ul request, which changes to .q "underline font" (usually italics in \*G). It won't work right if .i W is spread or broken (including hyphenated). In other words, it is safe in nofill mode only. .TL .b .q .i W .i X .DE Quote .i W and append .i X . In \*G this surrounds .i W with .b \*(lq , and .b \*(rq . .TL .b .bi .i W .i X .DE Set .i W in bold italics and append .i X . .TL .b .bx .i W .i X .DE Sets .i W in a box, with .i X appended. It won't work right if .i W is spread or broken (including hyphenated). In other words, it is safe in nofill mode only. .TL .b .sm .i W .i X .DE Sets .i W in a smaller pointsize, with .i X appended. .sh 1 "Roff Support" .TL .b .ix .i +N .DE Indent, no break. Equivalent to .b \(aain .i N . .TL .b .bl .i N .DE Leave .i N contiguous white space, on the next page if not enough room on this page. Equivalent to a .b .sp .i N inside a block. .TL .b .pa .i +N .DE Equivalent to .b .bp . .TL .b .ro .DE Set page number in roman numerals. Equivalent to .b ".af % i" . .TL .b .ar .DE Set page number in Arabic. Equivalent to .b ".af % 1" . .TL .b .n1 .DE Number lines in margin from one on each page. .TL .b .n2 .i N .DE Number lines from .i N , stop if .i N = 0. .TL .b .sk .DE Leave the next output page blank, except for headers and footers. This is used to leave space for a full-page diagram which is produced externally and pasted in later. To get a partial-page paste-in display, say .b .sv \ \c .i N , where .i N is the amount of space to leave; this space will be output immediately if there is room, and will otherwise be output at the top of the next page. However, be warned: if .i N is greater than the amount of available space on an empty page, no space will ever be output. .sh 1 "Preprocessor Support" .TL .b .EQ .i m .i T .DE Begin equation. The equation is centered if .i m is .b C or omitted, indented .NR (bi [4m] if .i m is .b I , and left justified if .i m is .b L . .i T is a title printed on the right margin next to the equation. See .i "Typesetting Mathematics \- User's Guide" by Brian W. Kernighan and Lorinda L. Cherry. .TL .b .EN .i c .DE End equation. If .i c is .b C the equation must be continued by immediately following with another .b .EQ , the text of which can be centered along with this one. Otherwise, the equation is printed, always on one page, with .NR (es [0.5v] space above and below it. .TL .b .TS .i h .DE Table start. Tables are single spaced and kept on one page if possible. If you have a large table which will not fit on one page, use .i h = .b H and follow the header part (to be printed on every page of the table) with a .b .TH . See .i "Tbl \- A Program to Format Tables" by M. E. Lesk. .TL .b .TH .DE With .b ".TS H" , ends the header portion of the table. .TL .b .TE .DE Table end. Note that this table does not float, in fact, it is not even guaranteed to stay on one page if you use requests such as .b .sp intermixed with the text of the table. If you want it to float (or if you use requests inside the table), surround the entire table (including the .b .TS and .b .TE requests) with the requests .b .(z and .b .)z . .TL .b .PS .i h .i w .DE Begin .i pic picture. .i H is the height and .i w is the width, both in basic units. .TL .b .PE .DE End picture. .TL .b .IS .DE Begin .i ideal picture. .TL .b .IE .DE End .i ideal picture. .TL .b .IF .DE End .i ideal picture (alternate form). .TL .b .GS .i x .DE Begin .i gremlin picture. .i X can be either .b C , .b L , or .b R to center, left, or right justify the whole picture. Default is centering the image. .TL .b .GE .DE End .i gremlin picture. .TL .b .GF .DE End .i gremlin picture (alternate form). .sh 1 "Miscellaneous" .TL .b .re .DE Reset tabs every 0.5i. .TL .b .ba .i +N .DE Set the base indent to .i +N [0] (saved in .NR ($i ). All paragraphs, sections, and displays come out indented by this amount. Titles and footnotes are unaffected. The .b .sh request performs a .b .ba request if .NR (si [0] is not zero, and sets the base indent to .NR (si \c .b * \c .NR ($0 . .TL .b .xl .i +N .DE Set the line length to .i N [6.0i]. This differs from .b .ll because it only affects the current environment. .TL .b .ll .i +N .DE Set line length in all environments to .i N [6.0i]. This should not be used after output has begun, and particularly not in two-column output. The current line length is stored in .NR ($l . .TL .b .hl .DE Draws a horizontal line the length of the page. This is useful inside floating keeps to differentiate between the text and the figure. .sh 1 "Standard Papers" .TL .b .tp .DE Begin title page. Spacing at the top of the page can occur, and headers and footers are suppressed. Also, the page number is not incremented for this page. .TL .b .++ .i m .i H .DE This request defines the section of the paper which we are entering. The section type is defined by .i m . .b C means that we are entering the chapter portion of the paper, .b A means that we are entering the appendix portion of the paper, .b P means that the material following should be the preliminary portion (abstract, table of contents, etc.) portion of the paper, .b AB means that we are entering the abstract (numbered independently from 1 in Arabic numerals), and .b B means that we are entering the bibliographic portion at the end of the paper. Also, the variants .b RC and .b RA are allowed, which specify renumbering of pages from one at the beginning of each chapter or appendix, respectively. The .i H parameter defines the new header. If there are any spaces in it, the entire header must be quoted. If you want the header to have the chapter number in it, Use the string .b "\e\e\e\en(ch" . For example, to number appendixes .b A.1 etc., type .b ".++ RA \(aa\(aa\(aa\e\e\e\en(ch.%\(aa" . Each section (chapter, appendix, etc.) should be preceded by the .b .+c request. It should be mentioned that it is easier when using \*T to put the front material at the end of the paper, so that the table of contents can be collected and put out; this material can then be physically moved to the beginning of the paper. .TL .b .+c .i T .DE Begin chapter with title .i T . The chapter number is maintained in .NR (ch . This register is incremented every time .b .+c is called with a parameter. The title and chapter number are printed by .b .$c . The header is moved to the footer on the first page of each chapter. If .i T is omitted, .b .$c is not called; this is useful for doing your own .q "title page" at the beginning of papers without a title page proper. .b .$c calls .b .$C as a hook so that chapter titles can be inserted into a table of contents automatically. The footnote numbering is reset to one. .TL .b .$c .i T .DE Print chapter number (from .NR (ch ) and .i T . This macro can be redefined to your liking. It is defined by default to be acceptable for a PhD thesis at Berkeley. This macro calls .b $C , which can be defined to make index entries, or whatever. .TL .b .$C .i K .i N .i T .DE This macro is called by .b .$c . It is normally undefined, but can be used to automatically insert index entries, or whatever. .i K is a keyword, either .q Chapter or .q Appendix (depending on the .b .++ mode); .i N is the chapter or appendix number, and .i T is the chapter or appendix title. .sh 1 "Predefined Strings" .TL .ST * .DE Footnote number, actually .ST [ \c .NR ($f \c .ST ] . This macro is incremented after each call to .b .)f . .TL .ST # .DE Delayed text number. Actually [\c .NR ($d ]. .TL .ST { .DE Superscript. This string gives upward movement and a change to a smaller point size. Extra space is left above the line to allow room for the superscript. .TL .ST } .DE Unsuperscript. Inverse to .ST { . For example, to produce a superscript you might type .b x \c .ST { \c .b 2 \c .ST } , which will produce .b x\*{2\*} . .TL .ST < .DE Subscript. Extra space is left below the line to allow for the subscript. .TL .ST > .DE Inverse to .ST < . .TL .ST (dw .DE The day of the week, as a word. .TL .ST (mo .DE The month, as a word. .TL .ST (td .DE Today's date, directly printable. The date is of the form \*(td. Other forms of the date can be used by using .NR (dy (the day of the month; for example, \n(dy), .ST (mo (as noted above) or .NR (mo (the same, but as an ordinal number; for example, \*(mo is \n(mo), .NR (y4 (the current year), and .NR (y2 (the last two digits of the current year). .TL .ST (lq .DE Left quote marks. .TL .ST (rq .DE Right quote. .TL .ST \- .DE .ie \w'\(34'>0 \(34 .el 3/4 em dash. .sh 1 "Special Characters and Marks" .pp There are a number of special characters and diacritical marks (such as accents) available through \-me. .ta 15 +5 +6 .nf Name Usage Example Acute accent \e*\(aa a\e*\(aa a\*' Grave accent \e*\(ga e\e*\(ga e\*` Umlaut \e*: u\e*: u\*: Tilde \e*~ n\e*~ n\*~ Caret \e*^ e\e*^ e\*^ Cedilla \e*, c\e*, c\*, Czech \e*v e\e*v e\*v Circle \e*o A\e*o A\*o There exists \e*(qe \*(qe For all \e*(qa \*(qa .fi .sp 1i .b Acknowledgments .pp I would like to thank Bob Epstein, Bill Joy, and Larry Rowe for having the courage to use the \-me macros to produce non-trivial papers during the development stages; Ricki Blau, Pamela Humphrey, and Jim Joyce for their help with the documentation phase; peter kessler for numerous complaints, most accompanied by fixes; and the plethora of people who have contributed ideas and have given support for the project. .bp .b Summary .pp This alphabetical list summarizes all macros, strings, and number registers available in the \-me macros. Selected .i troff commands, registers, and functions are included as well; those listed can generally be used with impunity. .pp The columns are the name of the command, macro, register, or string; the type of the object, and the description. Types are .b M for macro or builtin command (invoked with .b \&. or .b \&\' in the first input column), .b S for a string (invoked with .b \e* or .b \e*( ), .b R for a number register (invoked with .b \en or .b \en( ), and .b F for a .i troff builtin function (invoked by preceding it with a single backslash). .pp Lines marked with \(sc are .i troff internal codes. Lines marked with \(dg or \(dd may be defined by the user to get special functions; \(dd indicates that these are defined by default and changing them may have unexpected side effects. Lines marked with \(de are specific to .i ditroff (device-independent .i troff ). .de $H .ev 1 .ta \w'\e(space)\(sc\ 'u +\w'TYPE 'u NAME TYPE DESCRIPTION .ev .. .(l .$H \e(space) F\(sc unpaddable space \e" F\(sc comment (to end of line) \e*# S optional delayed text tag string \e$\fI\&N\fP F\(sc interpolate argument \fI\&N\fP \en($0 R section depth \&.$0 M\(dg invoked after section title printed \en($1 R first section number \&.$1 M\(dg invoked before printing depth 1 section \en($2 R second section number \&.$2 M\(dg invoked before printing depth 2 section \en($3 R third section number \&.$3 M\(dg invoked before printing depth 3 section \en($4 R fourth section number \&.$4 M\(dg invoked before printing depth 4 section \en($5 R fifth section number \&.$5 M\(dg invoked before printing depth 5 section \en($6 R sixth section number \&.$6 M\(dg invoked before printing depth 6 section \&.$C M\(dg called at beginning of chapter \&.$H M\(dg text header \en($V R\(dd relative vertical spacing in displays \en($c R current column number \&.$c M\(dd print chapter title \en($d R delayed text number \en($f R footnote number \&.$f M\(dd print footer \&.$h M\(dd print header \en($i R paragraph base indent \en($l R column width \en($m R number of columns in effect \e*($n S section name \en($p R numbered paragraph number \&.$p M\(dd print section heading (internal macro) \en($s R column indent \&.$s M\(dd footnote separator (from text) \en($v R\(dd relative vertical spacing in text \en% R\(sc current page number \e& F\(sc zero width character, useful for hiding controls \e(\fI\&xx\fP F\(sc interpolate special character \fI\&xx\fP \&.(b M begin block \&.(c M begin centered block \&.(d M begin delayed text \&.(f M begin footnote \&.(l M begin list \&.(q M begin quote \&.(x M begin index entry \&.(z M begin floating keep \&.)b M end block \&.)c M end centered block \&.)d M end delayed text \&.)f M end footnote \&.)l M end list \&.)q M end quote \&.)x M end index entry \&.)z M end floating keep \e*\fI\&x\fP F\(sc interpolate string \fI\&x\fP \e*(\fI\&xx\fP F\(sc interpolate string \fI\&xx\fP \e** S optional footnote tag string \&.++ M set paper section type \&.+c M begin chapter \e*, S cedilla \e\- F\(sc minus sign \e*\- S 3/4 em dash \e0 F\(sc unpaddable digit-width space \&.1c M revert to single column output \&.2c M begin two column output \e*: S umlaut \e*< S begin subscript \e*> S end subscript \&.EN M end equation \&.EQ M begin equation \eL\'\fI\&d\fP\' F\(sc vertical line drawing function for distance \fI\&d\fP \&.GE M\(de end \fIgremlin\fP picture \&.GF M\(de end \fIgremlin\fP picture (with flyback) \&.GS M\(de start \fIgremlin\fP picture \&.IE M\(de end \fIideal\fP picture \&.IF M\(de end \fIideal\fP picture (with flyback) \&.IS M\(de start \fIideal\fP picture \&.PE M\(de end \fIpic\fP picture \&.PF M\(de end \fIpic\fP picture (with flyback) \&.PS M\(de start \fIpic\fP picture \&.TE M end table \&.TH M end header of table \&.TS M begin table \e*{ S begin superscript \en(\&.$ R\(sc number of arguments to macro \en(\&.i R\(sc current indent \en(\&.l R\(sc current line length \en(\&.s R\(sc current point size \e*(\&\' S acute accent \e*(\&\` S grave accent \e(\' F\(sc acute accent \e(\` F\(sc grave accent \e*} S end superscript \e^ F\(sc 1/12 em narrow space \e*^ S caret \&.ad M\(sc set text adjustment \&.af M\(sc assign format to register \&.am M\(sc append to macro \&.ar M set page numbers in Arabic \&.as M\(sc append to string \&.b M bold font \&.ba M set base indent \&.bc M begin new column \&.bi M bold italic \en(bi R display (block) indent \&.bl M blank lines (even at top of page) \en(bm R bottom title margin \&.bp M\(sc begin page \&.br M\(sc break (start new line) \en(bs R display (block) pre/post spacing \en(bt R block keep threshold \&.bx M boxed \ec F\(sc continue input \&.ce M\(sc center lines \en(ch R current chapter number \&.de M\(sc define macro \en(df R display font \&.ds M\(sc define string \en(dw R\(sc current day of week \e*(dw S current day of week \en(dy R\(sc day of month \ee F\(sc printable version of \e \&.ef M set footer (even numbered pages only) \&.eh M set header (even numbered pages only) \&.el M\(sc else part of conditional \&.ep M end page \en(es R equation pre/post space \ef\fI\&f\fP F\(sc inline font change to font \fI\&f\fP \ef(\fI\&ff\fP F\(sc inline font change to font \fI\&ff\fP \&.fc M\(sc set field characters \en(ff R footnote font \&.fi M\(sc fill output lines \en(fi R footnote indent (first line only) \en(fm R footer margin \&.fo M set footer \en(fp R footnote pointsize \en(fs R footnote prespace \en(fu R footnote undent (from right margin) \eh\'\fI\&d\fP\' F\(sc local horizontal motion for distance \fI\&d\fP \&.hc M\(sc set hyphenation character \&.he M set header \&.hl M draw horizontal line \en(hm R header margin \&.hx M suppress headers and footers on next page \&.hy M\(sc set hyphenation mode \&.i M italic font \&.ie M\(sc conditional with else \&.if M\(sc conditional \en(ii R indented paragraph indent \&.in M\(sc indent (transient, use .ba for pervasive) \&.ip M begin indented paragraph \&.ix M indent, no break \el\'\fI\&d\fP\' F\(sc horizontal line drawing function for distance \fI\&d\fP \&.lc M\(sc set leader repetition character \&.ll M set line length \&.lp M begin left justified paragraph \e*(lq S left quote marks \&.ls M\(sc set multi-line spacing \&.m1 M set space from top of page to header \&.m2 M set space from header to text \&.m3 M set space from text to footer \&.m4 M set space from footer to bottom of page \&.mc M\(sc insert margin character \&.mk M\(sc mark vertical position \en(mo R\(sc month of year \e*(mo S current month \en\fI\&x\fP F\(sc interpolate number register \fI\&x\fP \en(\fI\&xx\fP F\(sc interpolate number register \fI\&xx\fP \&.n1 M number lines in margin \&.n2 M number lines in margin \&.na M\(sc turn off text adjustment \&.ne M\(sc need vertical space \&.nf M\(sc don't fill output lines \&.nh M\(sc turn off hyphenation \&.np M begin numbered paragraph \&.nr M\(sc set number register \&.ns M\(sc no space mode \e*o S circle (e.g., for Norse A\*o) \&.of M set footer (odd numbered pages only) \&.oh M set header (odd numbered pages only) \&.pa M begin page \&.pd M print delayed text \en(pf R paragraph font \en(pi R paragraph indent \&.pl M\(sc set page length \&.pn M\(sc set next page number \&.po M\(sc page offset \en(po R simulated page offset \&.pp M begin paragraph \en(pp R paragraph pointsize \en(ps R paragraph prespace \&.q M quoted \e*(qa S for all \e*(qe S there exists \en(qi R quote indent (also shortens line) \en(qp R quote pointsize \en(qs R quote pre/post space \&.r M roman font \&.rb M real bold font \&.re M reset tabs \&.rm M\(sc remove macro or string \&.rn M\(sc rename macro or string \&.ro M set page numbers in roman \e*(rq S right quote marks \&.rr M\(sc remove register \&.rs M\(sc restore spacing \&.rt M\(sc return to vertical position \es\fI\&S\fP F\(sc inline size change to size \fI\&S\fP \en(sf R section title font \&.sh M begin numbered section \en(si R relative base indent per section depth \&.sk M skip next page \&.sm M set argument in a smaller pointsize \&.so M\(sc source input file \en(so R additional section title offset \&.sp M\(sc vertical space \en(sp R section title pointsize \en(ss R section prespace \&.sx M change section depth \&.sz M set pointsize and vertical spacing \&.ta M\(sc set tab stops \&.tc M\(sc set tab repetition character \e*(td S today's date \en(tf R title font \&.ti M\(sc temporary indent (next line only) \&.tl M\(sc three part title \en(tm R top title margin \&.tp M begin title page \en(tp R title pointsize \&.tr M\(sc translate \&.u M underlined \&.uh M unnumbered section \&.ul M\(sc underline next line \ev\'\fI\&d\fP\' F\(sc local vertical motion for distance \fI\&d\fP \e*v S inverted `v' for czeck ``e\*v'' \ew\'\fI\&S\fP\' F\(sc return width of string \fI\&S\fP \&.xl M set line length (local) \&.xp M print index \en(xs R index entry prespace \en(xu R index undent (from right margin) \en(y2 R year (last two digits only) \en(y4 R year (all digits) \en(yr R\(sc year minus 1900 \en(zs R floating keep pre/post space \e{ F\(sc begin conditional group \e| F\(sc 1/6 em narrow space \e} F\(sc end conditional group \e*~ S tilde .)l .rm $H BUG-REPORT000066600000004076150501001760006123 0ustar00 Groff Bug Report Please read the PROBLEMS file before sending in a bug report. Please fill in all fields, even if you think they are not relevant. Please delete the text in brackets before sending it in. Please report separate bugs separately. Send the completed form to bug-groff@gnu.org GROFF VERSION: [The version of groff you are using. For example, `1.05'] MACHINE: [The machine you are using. For example, `Sun SPARCstation 2'] OS: [The operating system you are using. For example, `SunOS 4.1.1'] COMPILER: [The compiler you are used to compile groff. For example, `g++ 1.40.3'] INPUT FILES: [Include all the files necessary to reproduce the problem that are not part of the standard groff distribution. This includes font description files, DESC files and macro files (with the exception of the -ms and -mm macros: we have them). Send them as a shell archive or as a uuencoded, compressed tar file. It's easier for us if you can provide an example that doesn't depend on any macro package, but obviously if you're reporting a problem with a macro package that won't be possible. Also a short example is more convenient than a long one, but don't worry if you can't find a short example. Don't say something like ``any file that X'': Always send a definite example.] COMMAND LINE: [The command line that we should run in order to observe the bug. For example, `gtroff -Tps bug.tr'. If the command line uses -ms or -mm, say whether these refer to the groff versions or the Unix versions of the macros.] DESCRIPTION OF INCORRECT BEHAVIOUR: [What goes wrong when that command line is run? For example, `gtroff gets a segmentation fault', or `The output looks bad because the bar over the x is too long and is too far over to the left.' If you get an error message, include it here without modification: Don't edit it to make it more readable.] SUGGESTED FIX [optional]: [If you can suggest a fix for the problem, include a context diff here. But don't delay sending in a bug report in the hope of finding a fix. Guesses about the cause of the bug are not usually helpful.] README000066600000006367150501001760005437 0ustar00This is the GNU groff document formatting system. The version number is given in the file VERSION. Included in this release are implementations of troff, pic, eqn, tbl, grn, refer, -man, -mdoc, and -ms macros, and drivers for PostScript, TeX dvi format, HP LaserJet 4 printers, Canon CAPSL printers, HTML format (still alpha), and typewriter-like devices. Also included is a modified version of the Berkeley -me macros, an enhanced version of the X11 xditview previewer, and an implementation of the -mm macros contributed by Joergen Haegg (jh@axis.se). See the file INSTALL for installation instructions. You will require a C++ compiler. The file NEWS describes recent user-visible changes to groff. Groff is free software. See the file COPYING for copying permission. The file PROBLEMS describes various problems that have been encountered in compiling, installing, and running groff. For the moment, the documentation assumes that you are already familiar with the Unix versions of troff, -ms, and the preprocessors. The most recent released version of groff is always available by anonymous ftp from ftp.gnu.org in the directory pub/gnu/groff. A CVS repository is now available, containing the current development version of groff. You can access it with the commands export CVSROOT=:pserver:anoncvs@anoncvs.ffii.org:/var/cvs cvs login cvs -z9 co groff (if the prompt for the password appears, just press the enter key). After a successful login you no longer need the first two commands; an update of a checked out repository should be done with cvs -z9 update -dP Please read the info pages of cvs for further details. Alternatively, you can download snapshots (which are updated twice a day) from ftp://ftp.ffii.org/pub/groff/devel/groff-current.tar.gz or a diff file relative to the latest official groff release as ftp://ftp.ffii.org/pub/groff/devel/groff--current.diff.gz Assuming that groff-.tar.gz and groff--current.diff.gz are in the same directory, do the following to apply the diff file: tar xzvf groff-.tar.gz cd groff- gunzip -c ../groff--current.diff.gz | patch -p1 Please report bugs using the form in the file BUG-REPORT; the idea of this is to make sure that FSF has all the information it needs to fix the bug. At the very least, read the BUG-REPORT form and make sure that you supply all the information that it asks for. Even if you are not sure that something is a bug, report it using BUG-REPORT: this will enable us to determine whether it really is a bug or not. Three mailing lists are available: bug-groff@gnu.org for reporting bugs groff@gnu.org for general discussion of groff groff-commit@ffii.org a read-only list showing logs of commitments to the CVS repository Note that groff@gnu.org is an alias for groff@ffii.org; you must be subscribed to the `groff' list to send mails. To subscribe, send a mail to -request@ (example: groff-request@ffii.org) with the word `subscribe' in either the subject or body of the email (don't include the quotes). GNU groff was written by James Clark . It is now maintained by Ted Harding and Werner Lemberg . pic.ms000066600000235570150501001760005673 0ustar00.\" For tolerably obvious reason, this needs to be processed through PIC. .\" It also needs to be processed through TBL and EQN. Use "groff -p -e -t". .\" There is no hope that this will ever look right under nroff. .\" .\" Comments beginning with %% are cut lines so portions of this .\" document can be automatically extracted. %%TUTORIAL%% begins the .\" tutorial part; %%REFERENCE%% the reference part. %%POSTLUDE%% the .\" bibliography and end matter after the reference part. .\" .\" This document was written for free use and redistribution by .\" Eric S. Raymond in August 1995. .\" .\" $Id: pic.ms,v 1.19 2002/09/20 12:14:56 wlemb Exp $ .\" .\" Set a proper TeX .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X .el .ds tx TeX .\" .de CE\" Centered caption for figure. Assumes previous .KS .ce 1 Figure \\n(H1-\\$1 .sp 1 .KE .. .\" Definitions end here .TL Making Pictures With GNU PIC .AU Eric S. Raymond .AI \[la]\fIesr@snark.thyrsus.com\fP\[ra] .AB The \fBpic\fP language is a \fBtroff\fP extension that makes it easy to create and alter box-and-arrow diagrams of the kind frequently used in technical papers and textbooks. This paper is both an introduction to and reference for \fIgpic\/\fP(1), the implementation distributed by the Free Software Foundation for use with \fIgroff\/\fP(1). .AE .\"%%TUTORIAL%% .NH 1 Introduction to PIC .NH 2 Why PIC? .PP The \fBpic\fP language provides an easy way to write procedural box-and-arrow diagrams to be included in \fBtroff\fP documents. The language is sufficiently flexible to be quite useful for state charts, Petri-net diagrams, flow charts, simple circuit schematics, jumper layouts, and other kinds of illustration involving repetitive uses of simple geometric forms and splines. Because these descriptions are procedural and object-based, they are both compact and easy to modify. .PP The \fIgpic\/\fP(1) implementation of \fBpic\fP is distributed by the Free Software Foundation for use with their \fIgroff\/\fP(1) implementation of \fBtroff\fP. Because both implementations are widely available in source form for free, they are good bets for writing very portable documentation. .NH 2 PIC Versions .PP The original 1984 pre-\fIditroff\/\fP(1) version of \fBpic\fP is long obsolete. The rewritten 1991 version is still available as part of the Documenter's Work Bench module of System V. .PP Where differences between Documenter's Work Bench (1991) \fBpic\fP and GNU \fBpic\fP need to be described, original \fBpic\fP is referred to as \[lq]DWB pic\[rq]. Details on the history of the program are given at the end of this document. .PP In this document, the \fIgpic\/\fP(1) extensions will be marked as such. .NH 1 Invoking PIC .PP Every \fBpic\fP description is a little program, which gets compiled by \fIpic\/\fP(1) into \fIgtroff\/\fP(1) macros. Programs that process or display \fIgtroff\/\fP(1) output need not know or care that parts of the image began life as \fBpic\fP descriptions. .PP The \fIpic\/\fP(1) program tries to translate anything between \fB.PS\fP and \fB.PE\fP markers, and passes through everything else. The normal definitions of \fB.PS\fP and \fB.PE\fP in the \fIms\fP macro package and elsewhere have also the side-effect of centering the \fBpic\fP output on the page. .NH 2 PIC Error Messages .PP If you make a \fBpic\fP syntax error, \fIgpic\/\fP(1) will issue an error message in the standard \fIgcc\/\fP(1)-like syntax. A typical error message looks like this, .KS .DS .CW pic:pic.ms:: parse error before `' pic:pic.ms:: giving up on this picture .DE .R .KE .LP where \[la]nnn\[ra] is a line number, and \[la]token\[ra] is a token near (usually just after) the error location. .NH 1 Basic PIC Concepts .PP Pictures are described procedurally, as collections of objects connected by motions. Normally, \fBpic\fP tries to string together objects left-to-right in the sequence they are described, joining them at visually natural points. Here is an example illustrating the flow of data in \fBpic\fP processing: .KS .PS ellipse "document"; arrow; box width 0.6 "\fIgpic\/\fP(1)" arrow; box width 1.1 "\fIgtbl\/\fP(1) or \fIgeqn\/\fP(1)" "(optional)" dashed; arrow; box width 0.6 "\fIgtroff\/\fP(1)"; arrow; ellipse "PostScript" .PE .CE "1: Flow of \fBpic\fP data" .PP This was produced from the following \fBpic\fP program: .KS .DS .ps -1 .vs -1 .CW \&.PS ellipse "document"; arrow; box width 0.6 "\efIpic\e/\efP(1)" arrow; box width 1.1 "\efIgtbl\e/\efP(1) or \efIgeqn\e/\efP(1)" "(optional)" dashed; arrow; box width 0.6 "\efIgtroff\e/\efP(1)"; arrow; ellipse "PostScript" \&.PE .DE .R .KE .LP This little program illustrates several \fBpic\fP basics. Firstly, we see how to invoke three object types; ellipses, arrows, and boxes. We see how to declare text lines to go within an object (and that text can have font changes in it). We see how to change the line style of an object from solid to dashed. And we see that a box can be made wider than its default size to accommodate more text (we'll discuss this facility in detail in the next section). .PP We also get to see \fBpic\fP's simple syntax. Statements are ended by newlines or semicolons. String quotes are required around all text arguments, whether or not they contain spaces. In general, the order of command arguments and modifiers like \[lq]width 1.2\[rq] or \[lq]dashed\[rq] doesn't matter, except that the order of text arguments is significant. .PP Here are all but one of the basic \fBpic\fP objects at their default sizes: .KS .PS box "box"; move; line "line" ""; move; arrow "arrow" ""; move; circle "circle"; move; ellipse "ellipse"; move; arc; down; move; "arc" .PE .CE "2: Basic \fBpic\fP objects" .PP The missing simple object type is a \fIspline\fP. There is also a way to collect objects into \fIblock composites\fP which allows you to treat the whole group as a single object (resembling a box) for many purposes. We'll describe both of these later on. .PP The box, ellipse, circle, and block composite objects are \fIclosed\/\fR; lines, arrows, arcs and splines are \fIopen\fP. This distinction will often be important in explaining command modifiers. .PP Figure \n[H1]-2 was produced by the following \fBpic\fP program, which introduces some more basic concepts: .KS .DS .CW \&.PS box "box"; move; line "line" ""; move; arrow "arrow" ""; move; circle "circle"; move; ellipse "ellipse"; move; arc; down; move; "arc" \&.PE .DE .ft R .KE .PP The first thing to notice is the \fImove\fP command, which moves a default distance (1/2 inch) in the current movement direction. .PP Secondly, see how we can also decorate lines and arrows with text. The line and arrow commands each take two arguments here, specifying text to go above and below the object. If you wonder why one argument would not do, contemplate the output of \fBarrow "ow!"\fP: .KS .PS arrow "ow!" .PE .CE "3: Text centered on an arrow" .PP When a command takes one text string, \fBpic\fP tries to place it at the object's geometric center. As you add more strings, \fBpic\fP treats them as a vertical block to be centered. The program .KS .DS .CW line "1"; line "1" "2"; line "1" "2" "3"; line "1" "2" "3" "4"; line "1" "2" "3" "4" "5"; .DE .ft R .KE .LP for example, gives you this: .KS .sp 2 .PS line "1"; line "1" "2"; line "1" "2" "3"; line "1" "2" "3" "4"; line "1" "2" "3" "4" "5"; .PE .sp 2 .CE "4: Effects of multiple text arguments" .PP The last line of Figure 3.2's program, `\fBarc; down; move; "arc"\fP', describing the captioned arc, introduces several new ideas. Firstly, we see how to change the direction in which objects are joined. Had we written \fBarc; move; "arc"\fP, omitting \fBdown\fP the caption would have been joined to the top of the arc, like this: .KS .PS arc; move; "arc"; .PE .CE "5: Result of \fBarc; move; \"arc\"\fP" .PP This is because drawing an arc changes the default direction to the one its exit end points at. To reinforce this point, consider: .KS .PS arc cw; move; "arc"; .PE .CE "6: Result of \fBarc cw; move; \"arc\"\fP" .PP All we've done differently here is specify \[lq]cw\[rq] for a clockwise arc (\[lq]ccw\[rq] specifies counter-clockwise direction). Observe how it changes the default direction to down, rather than up. .PP Another good way to see this via with the following program: .KS .DS .CW line; arc; arc cw; line .DE .ft R .KE .LP which yields: .KS .PS line; arc; arc cw; line; .PE .CE "7: Result of \fBline; arc; arc cw; line\fP" .LP Notice that we did not have to specify \[lq]up\[rq] for the second arc to be joined to the end of the first. .PP Finally, observe that a string, alone, is treated as text to be surrounded by an invisible box of a size either specified by width and height attributes or by the defaults \fBtextwid\fR and \fBtextht\fR. Both are initially zero (because we don't know the default font size). .NH 1 Sizes and Spacing .PP Sizes are specified in inches. If you don't like inches, it's possible to set a global style variable \fBscale\fP that changes the unit. Setting \fBscale = 2.54\fP will effectively change the internal unit to centimeters (all other size variable values will be scaled correspondingly). .NH 2 Default Sizes of Objects .PP Here are the default sizes for \fBpic\fP objects: .TS H center, tab(@), linesize(2); lb | lb l | l. .sp 2p Object@Default Size .sp 2p _ .sp 2p .TH box@0.75" wide by 0.5" high circle@0.5" diameter ellipse@0.75" wide by 0.5" high arc@0.5" radius line@0.5" long arrow@0.5" long .sp 5p _ .TE .PP The simplest way to think about these defaults is that they make the other basic objects fit snugly into a default-sized box. .NH 2 Objects Do Not Stretch! .PP Text is rendered in the current font with normal troff line spacing. Boxes, circles, and ellipses do \fInot\fP automatically resize to fit enclosed text. Thus, if you say \fBbox "this text far too long for a default box"\fP you'll get this: .KS .PS box "this text is far too long for a default box" .PE .CE "1: Boxes do not automatically resize" .LP which is probably not the effect you want. .NH 2 Resizing Boxes .PP To change the box size, you can specify a box width with the \[lq]width\[rq] modifier: .KS .PS box width 3 "this text is far too long for a default box" .PE .CE "2: Result of \fBbox width 3 \"text far too long\"\fP" .PP This modifier takes a dimension in inches. There is also a \[lq]height\[rq] modifier that will change a box's height. The \fBwidth\fP keyword may be abbreviated to \fBwid\fP; the \fBheight\fP keyword to \fBht\fP. .NH 2 Resizing Other Object Types .PP To change the size of a circle, give it a \fBrad[ius]\fP or \fBdiam[eter]\fP modifier; this changes the radius or diameter of the circle, according to the numeric argument that follows. .KS .PS {circle rad 0.1; move down 0.2 from last circle .s; "0.1"}; move; circle rad 0.2 "0.2"; move; circle rad 0.3 "0.3"; .PE .CE "3: Circles with increasing radii" .PP The \fBmove\fP command can also take a dimension, which just tells it how many inches to move in the current direction. .PP Ellipses are sized to fit in the rectangular box defined by their axes, and can be resized with \fBwidth\fP and \fBheight\fP like boxes. .PP You can also change the radius of curvature of an arc with \fBrad[ius]\fP (which specifies the radius of the circle of which the arc is a segment). Larger values yield flatter arcs. .KS .PS {arc rad 0.1; move down 0.3 from last arc .center; "0.1"}; move; {arc rad 0.2; move down 0.4 from last arc .center; "0.2"}; move; {arc rad 0.3; move down 0.5 from last arc .center; "0.3"}; .PE .CE "4: \fBarc rad\fP with increasing radii" .PP Observe that because an arc is defined as a quarter circle, increasing the radius also increases the size of the arc's bounding box. .NH 2 The `same' Keyword .PP In place of a dimension specification, you can use the keyword \fBsame\fR. This gives the object the same size as the previous one of its type. As an example, the program .KS .DS .CW \&.PS box; box wid 1 ht 1; box same; box \&.PE .R .DE .KE .LP gives you .KS .PS box; box wid 1 ht 1; box same; box .PE .CE "5: The \fBsame\fP keyword" .NH 1 Generalized Lines and Splines .NH 2 Diagonal Lines .PP It is possible to specify diagonal lines or arrows by adding multiple \fBup\fP, \fBdown\fP, \fBleft\fP, and \fBright\fP modifiers to the line object. Any of these can have a multiplier. To understand the effects, think of the drawing area as being gridded with standard-sized boxes. .KS .PS # Draw a demonstration up left arrow with grid box overlay define gridarrow { move right 0.1 [ {arrow up left $1;} box wid 0.5 ht 0.5 dotted with .nw at last arrow .end; for i = 2 to ($1 / 0.5) do { box wid 0.5 ht 0.5 dotted with .sw at last box .se; } move down from last arrow .center; [ if ( $1 == boxht ) then { "\fBline up left\fP" } else { sprintf("\fBarrow up left %g\fP", $1) } ] ] move right 0.1 from last [] .e; } gridarrow(0.5); gridarrow(1); gridarrow(1.5); gridarrow(2); undef gridarrow .PE .CE "1: Diagonal arrows (dotted boxes show the implied 0.5-inch grid)" .NH 2 Multi-Segment Line Objects .PP A \[lq]line\[rq] or \[lq]arrow\[rq] object may actually be a path consisting of any number of segments of varying lengths and directions. To describe a path, connect several line or arrow commands with the keyword \fBthen\fP. .KS .PS define zigzag { $1 right 1 then down .5 left 1 then right 1 } zigzag(line); .PE .CE "2: \fBline right 1 then down .5 left 1 then right 1\fP" .NH 2 Spline Objects .PP If you start a path with the \fBspline\fP keyword, the path vertices are treated as control points for a spline curve fit. .KS .PS [zigzag(spline);] move down 0.2 from last [] .s; "The spline curve..." move right from last [] .e; [ zigzag(line dashed); spline from start of last line right 1 then down .5 left 1 then right 1; "1" at last spline .start + (-0.1, 0); "2" at last spline .start + (1.1, 0); "3" at last spline .end + (-1.1, 0); "4" at last spline .end + (0.1, 0); ] move down 0.2 from last [] .s; "...with tangents displayed" undef zigzag; .PE .CE "3: \fBspline right 1 then down .5 left 1 then right 1\fP" .PP You can describe many natural-looking but irregular curves this way. For example: .KS .PS [spline right then up then left then down ->;] move down 0.2 from last [] .s; ["\fBspline right then up then left then down ->;\fP"] move right 3 from last [] .se; "\fBspline left then up right then down right ->;\fP" move up 0.2; [spline left then up right then down right ->;] .PE .CE "4: Two more spline examples" .LP Note the arrow decorations. Arrowheads can be applied naturally to any path-based object, line or spline. We'll see how in the next section. .NH 1 Decorating Objects .NH 2 Dashed Objects .PP We've already seen that the modifier \fBdashed\fP can change the line style of an object from solid to dashed. GNU \fBgpic\fP permits you to dot or dash ellipses, circles, and arcs (and splines in \*[tx] mode only); some versions of DWB may only permit dashing of lines and boxes. It's possible to change the dash interval by specifying a number after the modifier. .PP .KS .PS box dashed "default"; move; box dashed 0.05 "0.05"; move; box dashed 0.1 "0.1"; move; box dashed 0.15 "0.15"; move; box dashed 0.2 "0.2"; .PE .CE "1: Dashed objects" .NH 2 Dotted Objects .PP Another available qualifier is \fBdotted\fP. GNU \fBgpic\fP permits you to dot or dash ellipses, circles, and arcs (and splines in \*[tx] mode only); some versions of DWB may only permit dashing of lines and boxes. It too can be suffixed with a number to specify the interval between dots: .KS .PS box dotted "default"; move; box dotted 0.05 "0.05"; move; box dotted 0.1 "0.1"; move; box dotted 0.15 "0.15"; move; box dotted 0.2 "0.2"; .PE .CE "2: Dotted objects" .NH 2 Rounding Box Corners .PP It is also possible, in GNU \fBgpic\fP only, to modify a box so it has rounded corners: .KS .PS box rad 0.05 "rad 0.05"; move; box rad 0.1 "rad 0.1"; move; box rad 0.15 "rad 0.15"; move; box rad 0.2 "rad 0.2"; move; box rad 0.25 "rad 0.25"; .PE .CE "3: \fBbox rad\fP with increasing radius values" .PP Radius values higher than half the minimum box dimension are silently truncated to that value. .NH 2 Arrowheads .PP Lines and arcs can be decorated as well. Any line or arc (and any spline as well) can be decorated with arrowheads by adding one or more as modifiers: .KS .PS line <- -> .PE .CE "4: Double-headed line made with \fBline <- ->\fP" .PP In fact, the \fBarrow\fP command is just shorthand for \fBline ->\fP. And there is a double-head modifier <->, so the figure above could have been made with \fBline <->\fP. .PP Arrowheads have a \fBwidth\fP attribute, the distance across the rear; and a \fBheight\fP attribute, the length of the arrowhead along the shaft. .PP Arrowhead style is controlled by the style variable \fBarrowhead\fP. The DWB and GNU versions interpret it differently. DWB defaults to open arrowheads and an \fBarrowhead\fP value of\~2; the Kernighan paper says a value of\~7 will make solid arrowheads. GNU \fBgpic\fP defaults to solid arrowheads and an \fBarrowhead\fP value of\~1; a value of\~0 will produce open arrowheads. Note that solid arrowheads are always filled with the current outline color. .NH 2 Line Thickness .PP It's also possible to change the line thickness of an object (this is a GNU extension, DWB \fBpic\fP doesn't support it). The default thickness of the lines used to draw objects is controlled by the .B linethick variable. This gives the thickness of lines in points. A negative value means use the default thickness: in \*[tx] output mode, this means use a thickness of 8 milliinches; in \*[tx] output mode with the .B -c option, this means use the line thickness specified by .B .ps lines; in troff output mode, this means use a thickness proportional to the pointsize. A zero value means draw the thinnest possible line supported by the output device. Initially it has a value of -1. There is also a \fBthickness\fP attribute (which can be abbreviated to \fBthick\fP). For example, \fBcircle thickness 1.5\fP would draw a circle using a line with a thickness of 1.5 points. The thickness of lines is not affected by the value of the .B scale variable, nor by any width or height given in the .B .PS line. .NH 2 Invisible Objects .PP The modifier \fBinvis[ible]\fP makes an object entirely invisible. This used to be useful for positioning text in an invisible object that is properly joined to neighboring ones. Newer DWB versions and GNU \fBpic\fP treat stand-alone text in exactly this way. .NH 2 Filled Objects .PP It is possible to fill boxes, circles, and ellipses. The modifier \fBfill[ed]\fP accomplishes this. You can suffix it with a fill value; the default is given by the stule variable \fBfillval\fP. .PP DWB \fBpic\fP and \fBgpic\fP have opposite conventions for fill values and different defaults. DWB \fBfillval\fP defaults to 0.3 and smaller values are darker; GNU \fBfillval\fP uses 0 for white and 1 for black. .KS .PS circle fill; move; circle fill 0.4; move; circle fill 0.9; .PE .CE "5: \fBcircle fill; move; circle fill 0.4; move; circle fill 0.9;\fR" .PP GNU \fBgpic\fP makes some additional guarantees. A fill value greater than 1 can also be used: this means fill with the shade of gray that is currently being used for text and lines. Normally this will be black, but output devices may provide a mechanism for changing this. The invisible attribute does not affect the filling of objects. Any text associated with a filled object will be added after the object has been filled, so that the text will not be obscured by the filling. .PP The closed-object modifier \fBsolid\fP is equivalent to \fBfill\fP with the darkest fill value (DWB \fBpic\fP had this capability but mentioned it only in a reference section). .NH 2 Colored Objects .PP As a GNU extension, three additional modifiers are available to specify colored objects. \fBoutline\fP sets the color of the outline, \fBshaded\fP the fill color, and \fBcolor\fP sets both. All three keywords expect a suffix specifying the color. Example: .KS .PS box color "yellow"; arrow color "cyan"; circle shaded "green" outline "black"; .PE .CE "6: \fBbox color ""yellow""; arrow color ""cyan""; \ circle shaded ""green"" outline ""black"";\fR" .PP Alternative spellings are \fBcolour\fP, \fBcolored\fP, \fBcoloured\fP, and \fBoutlined\fP. .PP Currently, color support is not available in \*[tx] mode. Predefined color names for \fIgroff\/\fP(1) are in the device macro files, for example \f(CWps.tmac\fP; additional colors can be defined with the \fB.defcolor\fP request (see the manual page of GNU \fItroff\/\fP(1) for more details). .PP \fBpic\fP assumes that at the beginning of a picture both glyph and fill color are set to the default value. .NH 1 More About Text Placement .PP By default, text is centered at the geometric center of the object it is associated with. The modifier \fBljust\fP causes the left end to be at the specified point (which means that the text lies to the right of the specified place!), the modifier \fBrjust\fP puts the right end at the place. The modifiers \fBabove\fP and \fBbelow\fP center the text one half line space in the given direction. .PP Text attributes can be combined: .KS .PS [line up "ljust text" ljust;] move 1.5; [line up "rjust text" rjust;] move; [arrow 1 "ljust above" ljust above;] move; [arrow 1 "rjust below" rjust below;] .PE .CE "1: Text attributes" .PP What actually happens is that \fIn\fP text strings are centered in a box that is \fBtextwid\fP wide by \fBtextht\fP high. Both these variables are initially zero (that is \fBpic\fR's way of not making assumptions about \fI[tg]roff\/\fP(1)'s default point size). .PP In GNU \fBgpic\fR, objects can have an .B aligned attribute. This will only work when the postprocessor is \fBgrops\fP. Any text associated with an object having the .B aligned attribute will be rotated about the center of the object so that it is aligned in the direction from the start point to the end point of the object. Note that this attribute will have no effect for objects whose start and end points are coincident. .NH 1 More About Direction Changes .PP We've already seen how to change the direction in which objects are composed from rightwards to downwards. Here are some more illustrative examples: .KS .PS down; [ "\fBright; box; arrow; circle; arrow; ellipse\fP"; move 0.2; [right; box; arrow; circle; arrow; ellipse;] ] move down 0.3 from last [] .s; [ "\fBleft; box; arrow; circle; arrow; ellipse\fP" move 0.2; [left; box; arrow; circle; arrow; ellipse;] ] # move down 0.3 from last [] .sw; # To re-join this illustrations, delete everything from here down to # the next #-comment, and uncomment the move line above .PE .CE "1: Effects of different motion directions (right and left)" .KS .PS # To re-join this illustrations, delete everything down to here, then # comment out the next `down' line. # Don't forget to re-number the figures following! down; [ "\fBdown; box; arrow; circle; arrow; ellipse;\fP" move 0.2; box; arrow; circle; arrow; ellipse; ] move right 2 from last [] .e; [ up; box; arrow; circle; arrow; ellipse; move 0.2; "\fBup; box; arrow; circle; arrow; ellipse;\fP" ] .PE .CE "2: Effects of different motion directions (up and down)" .PP Something that may appear surprising happens if you change directions in the obvious way: .KS .PS box; arrow; circle; down; arrow; ellipse .PE .CE "3: \fBbox; arrow; circle; down; arrow; ellipse\fP" .LP You might have expected that program to yield this: .KS .PS box; arrow; circle; move to last circle .s; down; arrow; ellipse .PE .CE "4: More intuitive?" .LP But, in fact, to get Figure \*[SN]3 you have to do this: .KS .DS .CW \&.PS box; arrow; circle; move to last circle .s; down; arrow; ellipse \&.PE .R .DE .KE .LP Why is this? Because the exit point for the current direction is already set when you draw the object. The second arrow in Figure \*[SN]2 dropped downwards from the circle's attachment point for an object to be joined to the right. .PP The meaning of the command \fBmove to last circle .s\fP should be obvious. In order to see how it generalizes, we'll need to go into detail on two important topics; locations and object names. .NH 1 Naming Objects .PP The most natural way to name locations in \fBpic\fP is relative to objects. In order to do this, you have to be able you have to be able to name objects. The \fBpic\fP language has rich facilities for this that try to emulate the syntax of English. .NH 2 Naming Objects By Order Of Drawing .PP The simplest (and generally the most useful) way to name an object is with a \fBlast\fP clause. It needs to be followed by an object type name; \fBbox\fP, \fBcircle\fP, \fBellipse\fP, \fBline\fP, \fBarrow\fP, \fBspline\fP, \fB""\fP, or \fB[]\fP (the last type refers to a \fIcomposite object\fP which we'll discuss later). So, for example, the \fBlast circle\fP clause in the program attached to Figure \*[SN]3 refers to the last circle drawn. .PP More generally, objects of a given type are implicitly numbered (starting from\~1). You can refer to (say) the third ellipse in the current picture with \fB3rd ellipse\fP, or to the first box as \fB1st box\fP, or to the fifth text string (which isn't an attribute to another object) as \fB5th ""\fP. .PP Objects are also numbered backwards by type from the last one. You can say \fB2nd last box\fP to get the second-to-last box, or \fB3rd last ellipse\fP to get the third-to-last ellipse. .PP In places where \fIn\/\fBth\fR is allowed, \fB`\fIexpr\/\fB'th\fR is also allowed. Note that .B 'th is a single token: no space is allowed between the .B ' and the \fBth\fP. For example, .IP .KS .DS .CW for i = 1 to 4 do { line from `i'th box.nw to `i+1'th box.se } .DE .R .KE .NH 2 Naming Objects With Labels .PP You can also specify an object by referring to a label. A label is a word (which must begin with a capital letter) followed by a colon; you declare it by placing it immediately before the object drawing command. For example, the program .KS .DS .CW \&.PS A: box "first" "object" move; B: ellipse "second" "object" move; arrow right at A .r; \&.PE .R .DE .KE .LP declares labels \fBA\fP and \fBB\fP for its first and second objects. Here's what that looks like: .KS .PS A: box "first" "object" move; B: ellipse "second" "object" move; arrow right at A .r; .PE .CE "1: Example of label use" The \fBat\fP statement in the fourth line uses the label \fBA\fP (the behavior of \fBat\fP will be explained in the next section). We'll see later on that labels are most useful for referring to block composite objects. .PP Labels are not constants but variables (you can view colon as a sort of assignment). You can say something like \fBA: A + (1,0);\fP and the effect will be to reassign the label \fBA\fR to designate a position one inch to the right of its old value. .NH 1 Describing locations .PP The location of points can be described in many different ways. All these forms are interchangeable as for as the \fBpic\fP language syntax is concerned; where you can use one, any of the others that would make semantic sense are allowed. .PP The special label \fBHere\fR always refers to the current position. .NH 2 Absolute Coordinates .PP The simplest is absolute coordinates in inches; \fBpic\fP uses a Cartesian system with (0, 0) at the lower left corner of the virtual drawing surface for each picture (that is, X increases to the right and Y increases upwards). An absolute location may always be written in the conventional form as two comma-separated numbers surrounded by parentheses (and this is recommended for clarity). In contexts where it creates no ambiguity, the pair of X and Y coordinates suffices without parentheses. .PP It is a good idea to avoid absolute coordinates, however. They tend to make picture descriptions difficult to understand and modify. Instead, there are quite a number of ways to specify locations relative to \fBpic\fP objects and previous locations. .PP .NH 2 Locations Relative to Objects .PP The symbol \fBHere\fP always refers to the position of the last object drawn or the destination of the last \fBmove\fP. .PP Alone and unqualified, a \fBlast circle\fP or any other way of specifying a closed-object or arc location refers as a position to the geometric center of the object. Unqualified, the name of a line or spline object refers to the position of the object start. .PP Also, \fBpic\fP objects have quite a few named locations associated with them. One of these is the object center, which can be indicated (redundantly) with the suffix \fB.center\fP (or just \fB.c\fP). Thus, \fBlast circle \&.center\fP is equivalent to \fBlast circle\fP. .NH 3 Locations Relative to Closed Objects .PP Every closed object (box, circle, ellipse, or block composite) also has eight compass points associated with it; .KS .PS define dot {circle fill rad 0.02 at $1} define compass { [ ME: $1; dot(ME.c); "\fB .c\fP" at ME .c ljust; dot(ME.n); "\fB.n\fP" at ME .n above dot(ME.ne); "\fB .ne\fP" at ME .ne above dot(ME.e); "\fB .e\fP" at ME .e ljust dot(ME.se); "\fB .se\fP" at ME .se below dot(ME.s); "\fB.s\fP" at ME .s below dot(ME.sw); "\fB.sw \fP" at ME .sw below dot(ME.w); "\fB.w \fP" at ME .w rjust dot(ME.nw); "\fB.nw \fP" at ME .nw above ] } compass(box wid 1.5 ht 1); move right from last [] .e; compass(circle diam 1); move right from last [] .e; compass(ellipse wid 1.5 ht 1); .PE .CE "1: Compass points" .LP these are the locations where eight compass rays from the geometric center would intersect the figure. So when we say \fBlast circle .s\fP we are referring to the south compass point of the last circle drawn. The explanation of Figure 7.3's program is now complete. .PP (In case you dislike compass points, the names \fB.top\fP, \&\fB.bottom\fP, \fB.left\fP and \fB.right\fP are synonyms for \fB.n\fP, \&\fB.s\fP, \fB.e\fP, and \fB.w\fP respectively; they can even be abbreviated to \fB.t\fP, \fB.b\fP, \fB.l\fP and \fB.r\fP). .PP The names \fBcenter\fP, \fBtop\fP, \fBbottom\fP, \fBleft\fP, \fBright\fP, \fBnorth\fP, \fBsouth\fP, \fBeast\fP, and \fBwest\fP can also be used (without the leading dot) in a prefix form marked by \fBof\fP; thus, \fBcenter of last circle\fP and \fBtop of 2nd last ellipse\fP are both valid object references. Finally, the names \fBleft\fP and \fBright\fP can be prefixed with \fBupper\fP and \fBlower\fP which both have the obvious meaning. .PP Arc objects also have compass point; they are the compass points of the implied circle. .NH 3 Locations Relative to Open Objects .PP Every open object (line, arrow, arc, or spline) has three named points: \fB.start\fP, \fB.center\fP (or \fB.c\fP), and \fB.end\fP. They can also be used without leading dots in the \fBof\fP prefix form. The center of an arc is the center of its circle, but the center of a line, path, or spline is halfway between its endpoints. .KS .PS define critical { [ ME: $1; dot(ME.c); "\fB.center\fP" rjust at ME.center + (-0.1, 0.1) dot(ME.start); "\fB.start\fP" rjust at ME.start + (-0.1, 0.1) dot(ME.end); "\fB.end\fP" rjust at ME.end + (-0.1, 0.1) ] } critical(line up right 1); move right 1 from last [] .e; critical(arc rad 0.5 cw); move down 0.5 from 2nd last [] .s; critical(line right 1 then down .5 left 1 then right 1); move right 1 from last [] .e; critical(spline right 1 then up right then left then left 1); .PE .CE "2: Special points on open objects" .PP .NH 2 Ways of Composing Positions .PP Once you have two positions to work with, there are several ways to combine them to specify new positions. .NH 3 Vector Sums and Displacements .PP Positions may be added or subtracted to yield a new position (to be more precise, you can only add a position and an expression pair; the latter must be on the right side of the addition or subtraction sign). The result is the conventional vector sum or difference of coordinates. For example, \fBlast box .ne + (0.1, 0)\fP is a valid position. This example illustrates a common use, to define a position slightly offset from a named one (say, for captioning purposes). .NH 3 Interpolation Between Positions .PP A position may be interpolated between any two positions. The syntax is `\fIfraction\fP \fBof the way between\fP \fIposition1\fP \fBand\fP \fIposition2\fP'. For example, you can say \fB1/3 of the way between here and last ellipse .ne\fP. The fraction may be in numerator/denominator form or may be an ordinary number (values are \fInot\fP restricted to [0,1]). As an alternative to this verbose syntax, you can say `\fIfraction\fP \fB<\,\fP\fIposition1\fP \fB,\fP \fIposition2\/\fP\fB>\fP'; thus, the example could also be written as \fB1/3 \fP. .KS .PS arrow up right; P: 1/3 of the way between last arrow .start and last arrow .end; dot(P); move right 0.1; "P"; .PE .CE "3: \fBP: 1/3 of the way between last arrow .start and last arrow .end\fP" .PP This facility can be used, for example, to draw double connections. .KS .PS A: box "yin"; move; B: box "yang"; arrow right at 1/4 ; arrow left at 1/4 ; .PE .CE "4: Doubled arrows" .LP You can get Figure \n[H1]-4 from the following program: .KS .DS .CW \&.PS A: box "yin"; move; B: box "yang"; arrow right at 1/4 ; arrow left at 1/4 ; \&.PE .R .DE .KE .LP Note the use of the short form for interpolating points. .NH 3 Projections of Points .PP Given two positions \fIp\fP and \fIq\fP, the position \fB(\,\fP\fIp\fP\fB,\fP \fIq\fP\fB)\fP has the X coordinate of \fIp\fP and the Y coordinate of \fIq\fP. This can be helpful in placing an object at one of the corners of the virtual box defined by two other objects. .KS .PS box invis wid 2 height 1; dot(last box .ne); "\fB(B,A)\fP is here" ljust at last circle + (0.1, 0.1); dot(last box .se); "B" ljust at last circle + (0.1, -0.1) dot(last box .sw); "\fB(A,B)\fP is here" rjust at last circle + (-0.1, -0.1); dot(last box .nw); "A" ljust at last circle + (-0.1, 0.1) .PE .CE "5: Using (\fIx\fP, \fIy\fP) composition" .NH 2 Using Locations .PP There are four ways to use locations; \fBat\fP, \fBfrom\fP, \fBto\fP, and \fBwith\fP. All three are object modifiers; that is, you use them as suffixes to a drawing command. .PP The \fBat\fP modifier says to draw a closed object or arc with its center at the following location, or to draw a line/spline/arrow starting at the following location. .PP The \fBto\fP modifier can be used alone to specify a move destination. The \fBfrom\fP modifier can be used alone in the same way as \fBat\fP. .PP The \fBfrom\fP and \fBto\fP modifiers can be used with a \fBline\fR or \fBarc\fR command to specify start and end points of the object. In conjunction with named locations, this offers a very flexible mechanism for connecting objects. For example, the following program .KS .DS .CW \&.PS box "from" move 0.75; ellipse "to" arc cw from 1/3 of the way \e between last box .n and last box .ne to last ellipse .n; \&.PE .R .DE .KE .LP yields: .KS .PS box "from" move 0.75; ellipse "to" arc cw from 1/3 of the way \ between last box .n and last box .ne to last ellipse .n; .PE .CE "6: A tricky connection specified with English-like syntax" .PP The \fBwith\fP modifier allows you to identify a named attachment point of an object (or a position within the object) with another point. This is very useful for connecting objects in a natural way. For an example, consider these two programs: .KS .PS [ [ box wid 0.5 ht 0.5; box wid 0.75 ht 0.75; ] move down 0.3 from last [] .s 0.1; "\fBbox wid 0.5 ht 0.5; box wid 0.75 ht 0.75\fP" ] move from last [].e 1.5 [ [ box wid 0.5 ht 0.5; box wid 0.75 ht 0.75 with .sw at last box .se; ] move down 0.3 from last [] .s 0.1; box invisible "\fBbox wid 0.5 ht 0.5;\fP" \ "\fBbox wid 0.75 ht 0.75 with .sw at last box .se;\fP" ] .PE .CE "7: Using the \fBwith\fP modifier for attachments" .NH 2 The `chop' Modifier .PP When drawing lines between circles that don't intersect them at a compass point, it is useful to be able to shorten a line by the radius of the circle at either or both ends. Consider the following program: .KS .DS .CW \&.PS circle "x" circle "y" at 1st circle - (0.4, 0.6) circle "z" at 1st circle + (0.4, -0.6) arrow from 1st circle to 2nd circle chop arrow from 2nd circle to 3rd circle chop arrow from 3rd circle to 1st circle chop \&.PE .DE .R .KE .LP It yields the following: .KS .PS circle "x" circle "y" at 1st circle - (0.4, 0.6) circle "z" at 1st circle + (0.4, -0.6) arrow from 1st circle to 2nd circle chop arrow from 2nd circle to 3rd circle chop arrow from 3rd circle to 1st circle chop .PE .CE "8: The \fBchop\fR modifier" .LP Notice that the \fBchop\fR attribute moves arrowheads rather than stepping on them. By default, the \fBchop\fR modifier shortens both ends of the line by \fBcirclerad\fR. By suffixing it with a number you can change the amount of chopping. .PP If you say \fBline .\|.\|.\& chop \fIr1\fP chop \fIr2\fP\fR with \fIr1\fP and \fIr2\fP both numbers, you can vary the amount of chopping at both ends. You can use this in combination with trigonometric functions to write code that will deal with more complex intersections. .NH 1 Object Groups .PP There are two different ways to group objects in \fBpic\fP; \fIbrace grouping\fP and \fIblock composites\fP. .NH 2 Brace Grouping .PP The simpler method is simply to group a set of objects within curly bracket or brace characters. On exit from this grouping, the current position and direction are restored to their value when the opening brace was encountered. .NH 2 Block Composites .PP A block composite object is created a series of commands enclosed by square brackets. The composite can be treated for most purposes like a single closed object, with the size and shape of its bounding box. Here is an example. The program fragment .KS .DS .CW A: [ circle; line up 1 at last circle .n; line down 1 at last circle .s; line right 1 at last circle .e; line left 1 at last circle .w; box dashed with .nw at last circle .se + (0.2, -0.2); Caption: center of last box; ] .R .DE .KE .LP yields the block in figure \n[H1]-1, which we show both with and without its attachment points. The block's location becomes the value of \fBA\fP. .KS .PS define junction { circle; line up 1 at last circle .n; line down 1 at last circle .s; line right 1 at last circle .e; line left 1 at last circle .w; box dashed with .nw at last circle .se + (0.2, -0.2); Caption: center of last box; } [junction();] move; compass([junction()]); .PE .CE "1: A sample composite object" .LP To refer to one of the composite's attachment points, you can say (for example) \fBA .s\fP. For purposes of object naming, composites are a class. You could write \fBlast [] .s\fP as an equivalent reference, usable anywhere a location is needed. This construction is very important for putting together large, multi-part diagrams. .PP Blocks are also a variable-scoping mechanism, like a \fIgroff\/\fP(1) environment. All variable assignments done inside a block are undone at the end of it. To get at values within a block, write a name of the block followed by a dot, followed by the label you want. For example, we could refer the the center of the box in the above composite as \fBlast [] .Caption\fP or \fBA.Caption\fP. .PP This kind of reference to a label can be used in any way any other location can be. For example, if we added \fB"Hi!" at A.Caption\fP the result would look like this: .KS .PS A: [junction();] "Hi!" at A.Caption; .PE .CE "2: Adding a caption using interior labeling" .PP You can also use interior labels in either part of a \fBwith\fR modifier. This means that the example composite could be placed relative to its caption box by a command containing \fBwith A.Caption at\fP. .PP Note that both width and height of the block composite object are always positive: .KS .PS [ [ box wid -0.5 ht 0.5 box wid 0.75 ht 0.75 ] move down 0.3 from last [].s 0.1 "\fBbox wid -0.5 ht 0.5; box wid 0.75 ht 0.75\fP" ] move from last [].e 2 [ [ [ box wid -0.5 ht 0.5 ] box wid 0.75 ht 0.75 ] move down 0.3 from last [].s 0.1 "\fB[box wid -0.5 ht 0.5]; box wid 0.75 ht 0.75\fP" ] .PE .CE "3: Composite block objects always have positive width and height .PP Blocks may be nested. This means you can use block attachment points to build up complex diagrams hierarchically, from the inside out. Note that \fBlast\fP and the other sequential naming mechanisms don't look inside blocks, so if you have a program that looks like .KS .DS .CW \&.PS P: [box "foo"; ellipse "bar"]; Q: [ [box "baz"; ellipse "quxx"] "random text"; ] arrow from 2nd last []; \&.PE .R .DE .KE .LP the arrow in the last line will be attached to object \fBP\fP, not object \fBQ\fP. .PP In DWB \fBpic\fP, only references one level deep into enclosed blocks were permitted. GNU \fBgpic\fP removes this restriction. .PP The combination of block variable scoping, assignability of labels and the macro facility that we'll describe later on can be used to simulate functions with local variables (just wrap the macro body in block braces). .NH 1 Style Variables .PP There are a number of global style variables in \fBpic\fR that can be used to change its overall behavior. We've mentioned several of them in previous sections. They're all described here. For each variable, the default is given. .TS H center, tab(@), linesize(2); lb | lb | lb l | n | l. .sp 2p Style Variable@Default@What It Does .sp 2p _ .sp 2p .TH boxht@0.5@Default height of a box boxwid@0.75@Default width of a box lineht@0.5@Default length of vertical line linewid@0.75@Default length of horizontal line linethick@-1@Default line thickness arcrad @0.25@Default radius of an arc circlerad@0.25@Default radius of a circle ellipseht@0.5@Default height of an ellipse ellipsewid@0.75@Default width of an ellipse moveht@0.5@Default length of vertical move movewid@0.75@Default length of horizontal move textht@0@Default height of box enclosing a text object textwid@0@Default width of box enclosing a text object arrowht@0.1@Length of arrowhead along shaft arrowwid@0.05@Width of rear of arrowhead arrowhead@1@Enable/disable arrowhead filling dashwid@0.05@Interval for dashed lines maxpswid@11@Maximum width of picture maxpsht@8.5@Maximum height of picture scale@1@Unit scale factor fillval@0.5@Default fill value .sp 5p _ .TE Any of these variables can be set with a simple assignment statement. For example: .KS .PS [boxht=1; boxwid=0.3; movewid=0.2; box; move; box; move; box; move; box;] .PE .CE "1: \fBboxht=1; boxwid=0.3; movewid=0.2; box; move; box; move; box; move; box;\fP" .PP In GNU \fBpic\fR, setting the \fBscale\fR variable re-scales all size-related state variables so that their values remain equivalent in the new units. .PP The command \fBreset\fP resets all style variables to their defaults. You can give it a list of variable names as arguments (optionally separated by commas), in which case it resets only those. .PP State variables retain their values across pictures until reset. .NH 1 Expressions, Variables, and Assignment .PP A number is a valid expression, of course (all numbers are stored internally as floating-point). Decimal-point notation is acceptable; in GNU \fBgpic\fR, scientific notation in C's `e' format (like \f(CW5e-2\fP) is accepted. .PP Anywhere a number is expected, the language will also accept a variable. Variables may be the built-in style variable described in the last section, or new variables created by assignment. .PP DWB \fBpic\fP supports only the ordinary assignment via \fB=\fP, which defines the variable (on the left side of the equal sign) in the current block if it is not already defined there, and then changes the value (on the right side) in the current block. The variable is not visible outside of the block. This is similar to the C\~programming language where a variable within a block shadows a variable with the same name outside of the block. .PP GNU \fBgpic\fP supports an alternate form of assignment using \fB:=\fP. The variable must already be defined, and the value will be assigned to that variable without creating a variable local to the current block. For example, this .KS .DS .CW x=5 y=5 [ x:=3 y=3 ] print x " " y .DE .KE .LP prints \fB3 5\fP. .PP You can use the height, width, radius, and x and y coordinates of any object or corner in expressions. If \fBA\fP is an object label or name, all the following are valid: .KS .DS .CW A.x # x coordinate of the center of A A.ne.y # y coordinate of the northeast corner of A A.wid # the width of A A.ht # and its height 2nd last circle.rad # the radius of the 2nd last circle .R .DE .KE .LP Note the second expression, showing how to extract a corner coordinate. .PP Basic arithmetic resembling those of C operators are available; \fB+\fP, \fB*\fP, \fB-\fP, \fB/\fP, and \fB%\fP. So is \fB^\fP for exponentiation. Grouping is permitted in the usual way using parentheses. GNU \fBgpic\fP allows logical operators to appear in expressions; \fB!\&\fP (logical negation, not factorial), \fB&&\fP, \fB|\||\fP, \fB==\fP, \fB!=\fP, \fB>=\fP, \fB<=\fP, \fB<\fP, \fB>\fP. .PP Various built-in functions are supported: \fBsin(\fIx\fB)\fR, \fBcos(\fIx\fB)\fR, \fBlog(\fIx\fB)\fR, \fBexp(\fIx\fB)\fR, \fBsqrt(\fIx\fB)\fR, \fBmax(\fIx\fB,\fIy\fB)\fR, \fBatan2(\fIx\fB,\fIy\fB)\fR, \fBmin(\fIx\fB,\fIy\fB)\fR, \fBint(\fIx\fB)\fR, \fBrand()\fP, and \fBsrand()\fP. Both \fBexp\fP and \fBlog\fP are base\~10; \fBint\fP does integer truncation; \fBrand()\fP returns a random number in [0-1), and \fBsrand()\fP sets the seed for a new sequence of pseudo-random numbers to be returned by \fBrand()\fP (\fBsrand()\fP is a GNU extension). .PP GNU \fBgpic\fP also documents a one-argument form or rand, \fBrand(\fIx\fB)\fR, which returns a random number between 1 and \fIx\fP, but this is deprecated and may be removed in a future version. .PP The function \fBsprintf()\fP behaves like a C \fIsprintf\/\fP(3) function that only takes %, %e, %f, and %g format strings. .NH 1 Macros .PP You can define macros in \fBpic\fP. This is useful for diagrams with repetitive parts. In conjunction with the scope rules for block composites, it effectively gives you the ability to write functions. .PP The syntax is .DS .CW \fBdefine\fP \fIname\fP \fB{\fP \fIreplacement text \fB}\fP .R .DE .LP This defines \fIname\fR as a macro to be replaced by the replacement text (not including the braces). The macro may be called as .DS .CW \fIname\fB(\fIarg1, arg2, \|.\|.\|.\& argn\fB)\fR .R .DE .LP The arguments (if any) will be substituted for tokens \fB$1\fP, \fB$2\fP \&.\|.\|.\& \fB$n\fP appearing in the replacement text. .PP As an example of macro use, consider this: .KS .DS .CW .ps -1 .vs -1 \&.PS # Plot a single jumper in a box, $1 is the on-off state. define jumper { [ shrinkfactor = 0.8; Outer: box invis wid 0.45 ht 1; # Count on end ] to reset these boxwid = Outer.wid * shrinkfactor / 2; boxht = Outer.ht * shrinkfactor / 2; box fill (!$1) with .s at center of Outer; box fill ($1) with .n at center of Outer; ] } # Plot a block of six jumpers. define jumperblock { jumper($1); jumper($2); jumper($3); jumper($4); jumper($5); jumper($6); jwidth = last [].Outer.wid; jheight = last [].Outer.ht; box with .nw at 6th last [].nw wid 6*jwidth ht jheight; # Use {} to avoid changing position from last box draw. # This is necessary so move in any direction will work as expected {"Jumpers in state $1$2$3$4$5$6" at last box .s + (0, -0.2);} } # Sample macro invocations. jumperblock(1,1,0,0,1,0); move; jumperblock(1,0,1,0,1,1); \&.PE .ps .vs .R .DE .KE .LP It yields the following: .KS .PS # Plot a single jumper in a box, $1 is the on-off state. define jumper { [ shrinkfactor = 0.8; Outer: box invis wid 0.45 ht 1; # Count on end ] to reset these boxwid = Outer.wid * shrinkfactor / 2; boxht = Outer.ht * shrinkfactor / 2; box fill (!$1) with .s at center of Outer; box fill ($1) with .n at center of Outer; ] } # Plot a block of six jumpers define jumperblock { jumper($1); jumper($2); jumper($3); jumper($4); jumper($5); jumper($6); jwidth = last [].Outer.wid; jheight = last [].Outer.ht; box with .nw at 6th last [].nw wid 6*jwidth ht jheight; # Use {} to avoid changing position from last box draw. # This is necessary so move in any direction will work as expected {"Jumpers in state $1$2$3$4$5$6" at last box .s + (0, -0.2);} } # Sample macro invocations jumperblock(1,1,0,0,1,0); move 0.25; jumperblock(1,0,1,0,1,1); .PE .CE "1: Sample use of a macro" .LP This macro example illustrates how you can combine [], brace grouping, and variable assignment to write true functions. .PP One detail the example above does not illustrate is the fact that macro argument parsing is not token-oriented. If you call \fBjumper(\ 1\ )\fP, the value of $1 will be \fB"\ 1\ "\fP. You could even call \fBjumper(big\ string)\fP to give $1 the value \fB"big\ string"\fP. .PP If you want to pass in a coordinate pair, you can avoid getting tripped up by the comma by wrapping the pair in parentheses. .PP Macros persist through pictures. To undefine a macro, say \fBundef\fP \fIname\fR; for example, .DS \f(CWundef jumper\fP \f(CWundef jumperblock\fP .DE .LP would undefine the two macros in the jumper block example. .NH 1 Import/Export Commands .PP Commands that import or export data between \fBpic\fR and its environment are described here. .NH 2 File and Table Insertion .PP The statement .DS \f(CWcopy\fP \fIfilename\fR .DE .LP inserts the contents of \fIfilename\fR in the \fBpic\fP input stream. Any \fB.PS\fP/\fB.PE\fP pair in the file will be ignored. This, you can use this to include pre-generated images. .PP A variant of this statement replicates the \fBcopy thru\fP feature of \fIgrap\fP(1). The call .DS \f(CWcopy\fP \fIfilename\fR \f(CWthru\fP \fImacro\fP .DE .LP calls \fImacro\fP (which may be either a name or replacement text) on the arguments obtained by breaking each line of the file into blank-separated fields. The macro may have up to 9\~arguments. The replacement text may be delimited by braces or by a pair of instances of any character not appearing in the rest of the text. .PP If you write .DS \f(CWcopy\fP \f(CWthru\fP \fImacro\fP .DE .LP omitting the filename, lines to be parsed are taken from the input source up to the next \fB.PE\fP. .PP In either of the last two \fBcopy\fP commands, GNU \fBgpic\fP permits a trailing `\fBuntil\fP \fIword\/\fP' clause to be added which terminates the copy when the first word matches the argument (the default behavior is therefore equivalent to \fBuntil .PE\fP). .PP Accordingly, the command .RS .KS .IP .ft CW .nf \&.PS copy thru % circle at ($1,$2) % until "END" 1 2 3 4 5 6 END box \&.PE .R .fi .KE .RE .LP is equivalent to .RS .KS .IP .ft CW .nf \&.PS circle at (1,2) circle at (3,4) circle at (5,6) box \&.PE .R .fi .KE .RE .NH 2 Debug Messages .PP The command \fBprint\fR accepts any number of arguments, concatenates their output forms, and writes the result to standard error. Each argument must be an expression, a position, or a text string. .NH 2 Escape to Post-Processor .PP If you write .DS \fBcommand\fR \fIarg\fR\|.\|.\|. .DE .LP \fBpic\fP concatenates the arguments and pass them through as a line to troff or \*[tx]. Each .I arg must be an expression, a position, or text. This has a similar effect to a line beginning with .B . or \fB\e\fR\|, but allows the values of variables to be passed through. .NH 2 Executing Shell Commands .PP The command .DS \f(CWsh\fP \f(CW{\fP \fIanything.\|.\|.\fP \f(CW}\fP .DE .LP macro-expands the text in braces, then executes it as a shell command. This could be used to generate images or data tables for later inclusion. The delimiters shown as {} here may also be two copies of any one character not present in the shell command text. In either case, the body may contain balanced {} pairs. Strings in the body may contain balanced or unbalanced braces in any case. .NH 1 Control-flow constructs .PP The \fBpic\fP language provides conditionals and looping. For example, .KS .DS .CW pi = atan2(0, -1); for i = 0 to 2 * pi by 0.1 do { "-" at (i/2, 0); "." at (i/2, sin(i)/2); ":" at (i/2, cos(i)/2); } .R .DE .KE .LP which yields this: .KS .PS pi = atan2(0, -1); for i = 0 to 2 * pi by 0.1 do { "-" at (i/2, 0); "." at (i/2, sin(i)/2); ":" at (i/2, cos(i)/2); } .PE .CE "1: Plotting with a \fBfor\fP loop" .LP The syntax of the \fBfor\fP statement is: .DS \fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\/\fR \fBto\fR \fIexpr2\/\fR \ [\fBby\fR [\fB*\fR]\fIexpr3\/\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR .DE The semantics are as follows: Set .I variable to \fIexpr1\fR. While the value of .I variable is less than or equal to \fIexpr2\fR, do .I body and increment .I variable by \fIexpr3\fR; if .B by is not given, increment .I variable by\~1. If .I expr3 is prefixed by\~\c .B * then .I variable will instead be multiplied by \fIexpr3\fR. .I X can be any character not occurring in \fIbody\fR; or the two \fIX\/\fPs may be paired braces (as in the \fBsh\fR command). .PP The syntax of the \fBif\fP statement is as follows: .DS \fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \ [\fBelse\fR \fIY\fR \fIif-false\fR \fIY\/\fR] .DE Its semantics are as follows: Evaluate \fIexpr\fR; if it is non-zero then do \fIif-true\fR, otherwise do \fIif-false\fR. .I X can be any character not occurring in \fIif-true\fR. .I Y can be any character not occurring in \fIif-false\fR. .PP Eithe or both of the .I X or .I Y pairs may instead be balanced pairs of braces ({ and\~}) as in the \fBsh\fR command. In either case, the \fIif-true\fR may contain balanced pairs of braces. None of these delimiters will be seen inside strings. .PP All the usual relational operators my be used in conditional expressions; \fB!\&\fP (logical negation, not factorial), \fB&&\fP, \fB|\||\fP, \fB==\fP, \fB!=\fP, \fB>=\fP, \fB<=\fP, \fB<\fP, \fB>\fP. .PP String comparison is also supported using \fB==\fP and \fB!=\fP. String comparisons may need to be parenthesized to avoid syntactic ambiguities. .NH 1 Interface To [gt]roff .PP The output of \fBpic\fP is \fB[gt]roff\fP drawing commands. The GNU \fIgpic\/\fP(1) command warns that it relies on drawing extensions present in \fIgroff\/\fP(1) that are not present in \fItroff\/\fP(1). .NH 2 Scaling Arguments .PP The DWB \fIpic\/\fP(1) program will accept one or two arguments to \&\fB.PS\fP, which is interpreted as a width and height in inches to which the results of \fIpic\/\fP(1) should be scaled (width and height scale independently). If there is only one argument, it is interpreted as a width to scale the picture to, and height will be scaled by the same proportion. .PP GNU \fBgpic\fP is less general; it will accept a single width to scale to, or a zero width and a maximum height to scale to. With two non-zero arguments, it will scale to the maximum height. .NH 2 How Scaling is Handled .PP When \fBpic\fP processes a picture description on input, it passes \fB.PS\fP and \fB.PE\fP through to the postprocessor. The \fB.PS\fP gets decorated with two numeric arguments which are the X and Y\~dimensions of the picture in inches. The post-processor can use these to reserve space for the picture and center it. .PP The GNU incarnation of the \fBms\fP macro package, for example, includes the following definitions: .KS .DS .ps -1 .vs -1 .CW \&.de PS \&.br \&.sp \e\en[DD]u \&.ie \e\en[.$]<2 .@error bad arguments to PS (not preprocessed with pic?) \&.el \e{\e \&. ds@need (u;\e\e$1)+1v \&. in +(u;\e\en[.l]-\e\en[.i]-\e\e$2/2>?0) \&.\e} \&.. \&.de PE \&.par@reset \&.sp \e\en[DD]u+.5m \&.. .R .DE .ps .vs .KE .LP Equivalent definition will be supplied by GNU \fIpic\/\fP(1) if you use the \-mpic option; this should make it usable with macro pages other than \fIms\/\fR(1). .PP If \fB.PF\fP is used instead of \fB.PE\fP, the \fBtroff\fP position is restored to what it was at the picture start (Kernighan notes that the\~F stands for \[lq]flyback\[rq]). .PP The invocation .DS \&\fB.PS <\,\fP\fIfile\fP .DE .LP causes the contents of \fIfile\fP to replace the \fB.PS\fP line. This feature is deprecated; use `\fBcopy\fP \fIfile\fR' instead). .PP By default, input lines that begin with a period are passed to the postprocessor, embedded at the corresponding point in the output. Messing with horizontal or vertical spacing is an obvious recipe for bugs, but point size and font changes will usually be safe. .PP Point sizes and font changes are also safe within text strings, as long as they are undone before the end of string. .PP The state of \fB[gt]roff\fP's fill mode is preserved across pictures. .PP The Kernighan paper notes that there is a subtle problem with complicated equations inside \fBpic\fR pictures; they come out wrong if \fIeqn\/\fP(1) has to leave extra vertical space for the equation. If your equation involves more than subscripts and superscripts, you must add to the beginning of each equation the extra information \fBspace\~0\fP. He gives the following example: .KS .DS .CW arrow box "$space 0 {H( omega )} over {1 - H( omega )}$" arrow .R .DE .KE .EQ delim @@ .EN .KS .PS arrow box "@space 0 {H( omega )} over {1 - H( omega )}@" arrow .PE .CE "1: Equations within pictures" .NH 1 Interface to TeX .PP .PP \*[tx] mode is enabled by the .B \-t option. In \*[tx] mode, pic will define a vbox called .B \egraph for each picture. You must yourself print that vbox using, for example, the command .RS .LP .CW \ecenterline{\ebox\egraph} .RE .LP Actually, since the vbox has a height of zero this will produce slightly more vertical space above the picture than below it; .RS .LP .CW \ecenterline{\eraise 1em\ebox\egraph} .RE .LP would avoid this. .PP You must use a \*[tx] driver that supports the .B tpic specials, version\~2. .PP Lines beginning with .B \e are passed through transparently; a .B % is added to the end of the line to avoid unwanted spaces. You can safely use this feature to change fonts or to change the value of \fB\ebaselineskip\fR. Anything else may well produce undesirable results; use at your own risk. Lines beginning with a period are not given any special treatment. .PP The \*[tx] mode of \fIpic\/\fP(1) will \fInot\fP translate \fBtroff\fP font and size changes included in text strings! .NH 1 Obsolete Commands .PP GNU \fIgpic\/\fP(1) has a command .DS \fBplot\fR \fIexpr\fR [\fB"\fItext\fB"\fR] .DE This is a text object which is constructed by using .I text as a format string for sprintf with an argument of \fIexpr\fP. If .I text is omitted a format string of \fB"%g"\fP is used. Attributes can be specified in the same way as for a normal text object. Be very careful that you specify an appropriate format string; \fBpic\fP does only very limited checking of the string. This is deprecated in favour of \fBsprintf\fP. .NH 1 Some Larger Examples .PP Here are a few larger examples, with complete source code. One of our earlier examples is generated in an instructive way using a for loop: .KS .DS .ps -1 .vs -1 .CW \&.PS # Draw a demonstration up left arrow with grid box overlay define gridarrow { move right 0.1 [ {arrow up left $1;} box wid 0.5 ht 0.5 dotted with .nw at last arrow .end; for i = 2 to ($1 / 0.5) do { box wid 0.5 ht 0.5 dotted with .sw at last box .se; } move down from last arrow .center; [ if ( $1 == boxht ) \e then { "\efBline up left\efP" } \e else { sprintf("\efBarrow up left %g\efP", $1) }; ] ] move right 0.1 from last [] .e; } gridarrow(0.5); gridarrow(1); gridarrow(1.5); gridarrow(2); undef gridarrow \&.PE .R .DE .ps .vs .KE .KS .PS # Draw a demonstration up left arrow with grid box overlay define gridarrow { move right 0.1 [ {arrow up left $1;} box wid 0.5 ht 0.5 dotted with .nw at last arrow .end; for i = 2 to ($1 / 0.5) do { box wid 0.5 ht 0.5 dotted with .sw at last box .se; } move down from last arrow .center; [ if ( $1 == boxht ) \ then { "\fBline up left\fP" } \ else { sprintf("\fBarrow up left %g\fP", $1) }; ] ] move right 0.1 from last [] .e; } gridarrow(0.5); gridarrow(1); gridarrow(1.5); gridarrow(2); undef gridarrow .PE .CE "1: Diagonal arrows (dotted boxes show the implied 0.5-inch grid)" .PP Here's an example concocted to demonstrate layout of a large, multiple-part pattern: .KS .DS .ps -1 .vs -1 .CW \&.PS define filter {box ht 0.25 rad 0.125} lineht = 0.25; Top: [ right; box "\efBms\efR" "sources"; move; box "\efBHTML\efR" "sources"; move; box "\efBlinuxdoc-sgml\efP" "sources" wid 1.5; move; box "\efBTexinfo\efP" "sources"; line down from 1st box .s lineht; A: line down; line down from 2nd box .s; filter "\efBhtml2ms\efP"; B: line down; line down from 3rd box .s; filter "\efBformat\efP"; C: line down; line down from 4th box .s; filter "\efBtexi2roff\efP"; D: line down; ] move down 1 from last [] .s; Anchor: box wid 1 ht 0.75 "\efBms\efR" "intermediate" "form"; arrow from Top.A.end to Anchor.nw; arrow from Top.B.end to 1/3 of the way between Anchor.nw and Anchor.ne; arrow from Top.C.end to 2/3 of the way between Anchor.nw and Anchor.ne; arrow from Top.D.end to Anchor.ne { # PostScript column move to Anchor .sw; line down left then down ->; filter "\efBpic\efP"; arrow; filter "\efBeqn\efP"; arrow; filter "\efBtbl\efP"; arrow; filter "\efBgroff\efP"; arrow; box "PostScript"; # HTML column move to Anchor .se; line down right then down ->; A: filter dotted "\efBpic2img\efP"; arrow; B: filter dotted "\efBeqn2html\efP"; arrow; C: filter dotted "\efBtbl2html\efP"; arrow; filter "\efBms2html\efP"; arrow; box "HTML"; # Nonexistence caption box dashed wid 1 at B + (2, 0) "These tools" "don't yet exist"; line chop 0 chop 0.1 dashed from last box .nw to A.e ->; line chop 0 chop 0.1 dashed from last box .w to B.e ->; line chop 0 chop 0.1 dashed from last box .sw to C.e ->; } \&.PE .R .DE .ps .vs .KE .KS .PS define filter {box ht 0.25 rad 0.125} lineht = 0.25; Top: [ right; box "\fBms\fR" "sources"; move; box "\fBHTML\fR" "sources"; move; box "\fBlinuxdoc-sgml\fP" "sources" wid 1.5; move; box "\fBTexinfo\fP" "sources"; line down from 1st box .s lineht; A: line down; line down from 2nd box .s; filter "\fBhtml2ms\fP"; B: line down; line down from 3rd box .s; filter "\fBformat\fP"; C: line down; line down from 4th box .s; filter "\fBtexi2roff\fP"; D: line down; ] move down 1 from last [] .s; Anchor: box wid 1 ht 0.75 "\fBms\fR" "intermediate" "form"; arrow from Top.A.end to Anchor.nw; arrow from Top.B.end to 1/3 of the way between Anchor.nw and Anchor.ne; arrow from Top.C.end to 2/3 of the way between Anchor.nw and Anchor.ne; arrow from Top.D.end to Anchor.ne { # PostScript column move to Anchor .sw; line down left then down ->; filter "\fBpic\fP"; arrow; filter "\fBeqn\fP"; arrow; filter "\fBtbl\fP"; arrow; filter "\fBgroff\fP"; arrow; box "PostScript"; # HTML column move to Anchor .se; line down right then down ->; A: filter dotted "\fBpic2img\fP"; arrow; B: filter dotted "\fBeqn2html\fP"; arrow; C: filter dotted "\fBtbl2html\fP"; arrow; filter "\fBms2html\fP"; arrow; box "HTML"; # Nonexistence caption box dashed wid 1 at B + (2, 0) "These tools" "don't yet exist"; line chop 0 chop 0.1 dashed from last box .nw to A.e ->; line chop 0 chop 0.1 dashed from last box .w to B.e ->; line chop 0 chop 0.1 dashed from last box .sw to C.e ->; } .PE .CE "2: Hypothetical production flow for dual-mode publishing" .LP .\"%%REFERENCE%% .NH 1 PIC Reference .PP This is an annotated grammar of \fBpic\fP. .NH 2 Lexical Items .PP In general, \fBpic\fP is a free-format, token-oriented language that ignores whitespace outside strings. But certain lines and contructs are specially interpreted at the lexical level: .PP A comment begins with \fB#\fP and continues to \fB\en\fP (comments may also follow text in a line). A line beginning with a period or backslash may be interpreted as text to be passed through to the post-processor, depending on command-line options. An end-of-line backslash is interpreted as a request to continue the line; the backslash and following newline are ignored. .PP .RS Here are the grammar terminals: .IP \s[-1]INT\s[0] A positive integer. .IP \s[-1]NUMBER\s[0] A floating point numeric constant. May contain a decimal point or be expressed in scientific notation in the style of \fIprintf\/\fP(3)'s %e escape. A trailing `i' or `I' (indicating the unit `inch') is ignored. .IP \s[-1]TEXT\s[0] A string enclosed in double quotes. A double quote within \s[-1]TEXT\s[0] must be preceded by a backslash. Instead of \s[-1]TEXT\s[0] you can use .DS .CW sprintf ( TEXT [, ...] ) .R .DE .IP except after the `until' and `last' keywords, and after all ordinal keywords (`th' and friends). .IP \s[-1]VARIABLE\s[0] A string starting with a character from the set [a-z], optionally followed by one or more characters of the set [a-zA-Z0-9_]. (Values of variables are preserved across pictures.) .IP \s[-1]LABEL\s[0] A string starting with a character from the set [A-Z], optionally followed by one or more characters of the set [a-zA-Z0-9_]. .IP \s[-1]COMMAND-LINE\s[0] A line starting with a command character (`.' in groff mode, `\e' in \*[tx] mode). .IP \s[-1]BALANCED-TEXT\s[0] A string either enclosed by `{' and `}' or with \fIX\fP and \fIX\fP, where \fIX\fP doesn't occur in the string. .IP \s[-1]BALANCED-BODY\s[0] Delimiters as in \s[-1]BALANCED-TEXT\s[0]; the body will be interpreted as `\fB\[la]command\[ra].\|.\|.\fP'. .IP \s[-1]FILENAME\s[0] The name of a file. This has the same semantics as \s[-1]TEXT\s[0]. .IP \s[-1]MACRONAME\s[0] Either \s[-1]VARIABLE\s[0] or \s[-1]LABEL\s[0]. .RE .NH 2 Semi-Formal Grammar .PP Tokens not enclosed in \[la]\|\[ra] are literals, except: .IP 1. \fB\en\fP is a newline. .IP 2. Three dots is a suffix meaning `replace with 0 or more repetitions of the preceding element(s). .IP 3. An enclosure in square brackets has its usual meaning of `this clause is optional'. .IP 4. Square-bracket-enclosed portions within tokens are optional. Thus, `h\^[eigh]\^t' matches either `height' or `ht'. .LP If one of these special tokens has to be referred to literally, it is surrounded with single quotes. .PP The top-level \fBpic\fP object is a picture. .DS .CW ::= .PS [NUMBER [NUMBER]]\en ... .PE \en .R .DE .PP The arguments, if present, represent the width and height of the picture, causing \fBpic\fR to attempt to scale it to the given dimensions in inches. In no case, however, will the X and Y\~dimensions of the picture exceed the values of the style variables \fBmaxpswid\fP and \fBmaxpsheight\fP (which default to the normal 8.5\^i by 11\^i page size). .PP If the ending `.PE' is replaced by `.PF', the page vertical position is restored to its value at the time `.PS' was encountered. Another alternate form of invocation is `.PS\ <\s[-1]FILENAME\s[0]', which replaces the `.PS' line with a file to be interpreted by \fBpic\fR (but this feature is deprecated). .PP The `.PS', `.PE', and `.PF' macros to perform centering and scaling are normally supplied by the post-processor. .PP In the following, either `|' or a new line starts an alternative. .DS .CW ::= ; \en .R .DE .DS .CW ::= [] LABEL : [;] LABEL : [;] [] { ... } VARIABLE [:] = up | down | left | right COMMAND-LINE command ... print ... sh BALANCED-TEXT copy FILENAME copy [FILENAME] thru MACRONAME [until TEXT] copy [FILENAME] thru BALANCED-BODY [until TEXT] for VARIABLE = to [by [*] ] do BALANCED-BODY if then BALANCED-BODY [else BALANCED-BODY] reset [VARIABLE [[,] VARIABLE ...]] .R .DE .DS .CW ::= TEXT .R .DE .PP The current position and direction are saved on entry to a `{\ .\|.\|.\ }' construction and restored on exit from it. .PP Note that in `if' constructions, newlines can only occur in \s[-1]BALANCED-BODY\s[0]. This means that .DS .CW if { ... } else { ... } .R .DE .PP will fail. You have to use the braces on the same line as the keywords: .DS .CW if { \&... } else { \&... } .R .DE .PP This restriction doesn't hold for the body after the `do' in a `for' construction. .DS .CW ::= ! .R .DE .DS .CW ::= == | != | && | '||' .R .DE .DS .CW ::= TEXT == TEXT TEXT != TEXT .R .DE .PP Logical operators are handled specially by \fBpic\fP since they can deal with text strings also. \fBpic\fP uses \%\fIstrcmp\/\fP(3) to test for equality of strings; an empty string is considered as `false' for `&&' and `|\||'. .DS .CW ::= box \fR# closed object \[em] rectangle\fP circle \fR# closed object \[em] circle\fP ellipse \fR# closed object \[em] ellipse\fP arc \fR# open object \[em] quarter-circle\fP line \fR# open object \[em] line\fP arrow \fR# open object \[em] line with arrowhead\fP spline \fR# open object \[em] spline curve\fP move TEXT TEXT ... \fR# text within invisible box\fP plot TEXT \fR# formatted text\fP '[' ... ']' .R .DE .PP Drawn objects within `[\ .\|.\|.\ ]' are treated as a single composite object with a rectangular shape (that of the bounding box of all the elements). Variable and label assignments within a block are local to the block. Current direction of motion is restored to the value at start of block upon exit. Position is \fInot\fR restored (unlike `{\ }'); instead, the current position becomes the exit position for the current direction on the block's bounding box. .DS .CW ::= h[eigh]t \fR# set height of closed figure \fP wid[th] \fR# set width of closed figure \fP rad[ius] \fR# set radius of circle/arc \fP diam[eter] \fR# set diameter of circle/arc \fP up [] \fR# move up \fP down [] \fR# move down \fP left [] \fR# move left \fP right [] \fR# move right \fP from \fR# set from position of open figure\fP to \fR# set to position of open figure\fP at \fR# set center of open figure\fP with \fR# fix corner/named point at specified location\fP with \fR# fix position of object at specified location\fP by \fR# set object's attachment point\fP then \fR# sequential segment composition\fP dotted [] \fR# set dotted line style\fP dashed [] \fR# set dashed line style\fP thick[ness] \fR# set thickness of lines\fP chop [] \fR# chop end(s) of segment\fP '->' | '<-' | '<->' \fR# decorate with arrows\fP invis[ible] \fR# make primitive invisible\fP solid \fR# make closed figure solid\fP fill[ed] [] \fR# set fill density for figure\fP colo[u]r[ed] TEXT \fR# set fill and outline color for figure\fP outline[d] TEXT \fR# set outline color for figure\fP shaded TEXT \fR# set fill color for figure\fP same \fR# copy size of previous object\fP cw | ccw \fR# set orientation of curves\fP ljust | rjust \fR# adjust text horizontally\fP above | below \fR# adjust text vertically\fP aligned \fR# align parallel to object\fP TEXT TEXT ... \fR# text within object\fP \fR# motion in the current direction\fR .R .DE .PP Missing attributes are supplied from defaults; inappropriate ones are silently ignored. For lines, splines, and arcs, height and width refer to arrowhead size. .PP The `at' primitive sets the center of the current object. The `with' attribute fixes the specified feature of the given object to a specified location. (Note that `with' is incorrectly described in the Kernighan paper.) .PP The `by' primitive is not documented in the tutorial portion of the Kernighan paper, and should probably be considered unreliable. .PP The primitive `arrow' is a synonym for `line\ ->'. .PP Text is normally an attribute of some object, in which case successive strings are vertically stacked and centered on the object's center by default. Standalone text is treated as though placed in an invisible box. .PP A text item consists of a string or sprintf-expression, optionally followed by positioning information. Text (or strings specified with `sprintf' may contain [gtn]roff font changes, size changes, and local motions, provided those changes are undone before the end of the current item. .PP A position is an (x,y) coordinate pair. There are lots of different ways to specify positions: .DS .CW ::= .R .DE .DS .CW ::= + - ( , ) [of the way] between and '<' , '>' .R .DE .DS .CW ::= , ( expr-pair ) .R .DE .DS .CW ::=