Return to program.me CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / dipress / doc

Annotation of 43BSD/contrib/dipress/doc/program.me, revision 1.1

1.1     ! root        1: .bp
        !             2: .sh 1 "Creating \*(IP masters from C Programs"
        !             3: .lp
        !             4: A series of C macros and subroutines have been incorporated into a flexible
        !             5: software interface for use in the creation of Interpress masters.  This
        !             6: interface provides a facility for higher level software to create Interpress
        !             7: masters and eliminates the need for knowledge of the actual encoding of
        !             8: the file.  The set of routines resembles the proposal for an Interpress
        !             9: procedural interface outlined in the
        !            10: .i
        !            11: Introduction to Interpress,
        !            12: .r
        !            13: \s8XSIG\s0 038404 Section 7 "Creating masters: procedural interfaces".
        !            14: .lp
        !            15: Since this document makes references to the actual Interpress
        !            16: encoding form, it is assumed that the reader has knowledge of
        !            17: the encoding of Interpress within a file as described in the
        !            18: .i
        !            19: Interpress Electronic Printing Standard,
        !            20: .r
        !            21: \s8XSIS\s0 048404, Section 2.5.
        !            22: .sh 2 Basics
        !            23: .lp
        !            24: The Interpress procedure interface described is organized as that described
        !            25: in Section 7 of the
        !            26: .i
        !            27: Introduction to Interpress,
        !            28: .r
        !            29: \s8XSIG\s0 038404.
        !            30: .lp
        !            31: There are two levels of interfaces:
        !            32: .RS
        !            33: .ip \(bu
        !            34: The
        !            35: .i Literal
        !            36: interface which provides procedures for creating the various Interpress tokens
        !            37: (i.e., operators, numbers, identifiers, etc.)
        !            38: .ip \(bu
        !            39: The
        !            40: .i Operator
        !            41: interface which provides procedures for the creation of specific operators
        !            42: with an associated value or values.
        !            43: .RE
        !            44: .lp
        !            45: The following conventions are used in the descriptions of these interfaces:
        !            46: .RS
        !            47: .RS
        !            48: .ip n:
        !            49: floating point numbers represented by the C type double (32 bits)
        !            50: .ip i:
        !            51: integers represented by the C type long (32 bits)
        !            52: .ip s:
        !            53: character strings which are null terminated
        !            54: .RE
        !            55: .RE
        !            56: .sh 2 "Literal Interface"
        !            57: .lp
        !            58: The literal interface is a series of routines which append
        !            59: the various Interpress types to the output file.  These routines
        !            60: perform the actual encoding dependent upon the literal type. 
        !            61: .lp
        !            62: The routines which comprise the literal interface are:
        !            63: .RS
        !            64: .ip \fIip_select\fR(i:\ fd) 45
        !            65: select the output file represented by the file descriptor fd and append the
        !            66: Interpress header
        !            67: .ip \fIip_raw_select\fR(i:\ fd) 45
        !            68: select the output file represented by the file descriptor fd (does not append
        !            69: an Interpress header)
        !            70: .ip \fIip_close\fR() 45
        !            71: close an output file
        !            72: .ip \fIip_flush\fR() 45
        !            73: flush current output buffer to the file
        !            74: .pp
        !            75: .pp
        !            76: .ip \fIAppendOp\fR(i:\ operator) 45
        !            77: append operator in its proper form (either a Short Op or a Long Op)
        !            78: .ip \fIOp\fR(s:\ name) 45
        !            79: a macro which will call \fIAppendOp\fR with "OP_`name'" as the operator 
        !            80: .ip \fIAppendNumber\fR(n:\ number) 45
        !            81: append the number in its proper form (either as a Short Number, a sequence of
        !            82: type sequenceInteger or a sequence of type sequenceRational)
        !            83: .ip \fIAppendInteger\fR(i:\ integer) 45
        !            84: append the integer in its proper form (either as a Short Number or a sequence
        !            85: of type sequenceInteger)
        !            86: .ip \fIAppendRational\fR(n:\ numerator,\ n:\ denominator) 45
        !            87: append value and divisor as a sequence of type sequenceRational
        !            88: .ip \fIAppendIdentifier\fR(s:\ string) 45
        !            89: append string as a sequence of type sequenceIdentifier
        !            90: .ip \fIAppendComment\fR(s:\ string) 45
        !            91: append string as a sequence of type sequenceComment
        !            92: .ip \fIAppendString\fR(s:\ string) 45
        !            93: append string as a sequence of type sequenceString
        !            94: .ip \fIAppendInsertFile\fR(s:\ string) 45
        !            95: append string as a sequence of type sequenceInsertFile
        !            96: .RE
        !            97: .sh 2 "Operator Interface"
        !            98: .lp
        !            99: Many of the common Interpress primitive operators have a corresponding routine
        !           100: in the operator interface which allows the operator and a series of value(s) 
        !           101: to be appended to the output file.
        !           102: .lp
        !           103: Interpress operators vary in their use in that several options are available:
        !           104: .RS
        !           105: .ip \(bu
        !           106: the operators may not require any values to be associated with it
        !           107: .ip \(bu
        !           108: values may be provided explicitly and a resulting value left on the stack
        !           109: .ip \(bu
        !           110: any or all values may be taken from the stack (left by a previous operation)
        !           111: and the result of the operator may then be left on the stack in place of 
        !           112: the values
        !           113: .ip \(bu
        !           114: the values provided may in fact be a larger body of values composed of many
        !           115: numbers or integers
        !           116: .RE
        !           117: .lp
        !           118: .i
        !           119: Operators with no values:
        !           120: .r
        !           121: Operators which require no values may be output with the literal interface 
        !           122: routines \fIAppendOp\fR or \fIOp\fR.
        !           123: .lp
        !           124: .i
        !           125: Operators with explicit values:
        !           126: .r
        !           127: The following routines will append the named operator along with the values
        !           128: specified:
        !           129: .RS
        !           130: .lp
        !           131: .b
        !           132: Arithmetic Operators
        !           133: .RS
        !           134: .ip \fIAbs\|(n:\ value)\fR
        !           135: .ip \fIAdd\|(n:\ value1,\ n:\ value2)\fR
        !           136: .ip \fICeiling\|(n:\ value)\fR
        !           137: .ip \fIDiv\|(n:\ dividend,\ n:\ divisor)\fR
        !           138: .ip \fIFloor\|(n:\ value)\fR
        !           139: .ip \fIMod\|(n:\ value,\ n:\ divisor)\fR
        !           140: .ip \fIMul\|(n:\ value1,\ n:\ value2)\fR
        !           141: .ip \fINeg\|(n:\ value)\fR
        !           142: .ip \fIRem\|(n:\ value,\ n:\ divisor)\fR
        !           143: .ip \fIRound\|(n:\ value)\fR
        !           144: .ip \fISub\|(n:\ minuend,\ n:\ subtrahend)\fR
        !           145: .ip \fITrunc\|(n:\ value)\fR
        !           146: .RE
        !           147: .lp
        !           148: .b
        !           149: Color Operators
        !           150: .RS
        !           151: .ip \fIMakegray\|(n:\ colorshade)\fR
        !           152: .ip \fIMakesampledblack\|(i:\ clear)\fR
        !           153: .ip \fISetgray\|(n:\ colorshade)\fR
        !           154: .RE
        !           155: .lp
        !           156: .b
        !           157: Correction Operators
        !           158: .RS
        !           159: .ip \fICorrectspace\|(n:\ x,\ n:\ y)\fR
        !           160: .ip \fISetcorrectmeasure\|(n:\ x,\ n:\ y)\fR
        !           161: .ip \fISetcorrecttolerance\|(n:\ x,\ n:\ y)\fR
        !           162: .ip \fISpace\|(n:\ x)\fR
        !           163: .RE
        !           164: .lp
        !           165: .b
        !           166: Font Operators
        !           167: .RS
        !           168: .ip \fISetfont(i:\ font)\fR
        !           169: .RE
        !           170: .lp
        !           171: .b
        !           172: Frame Operators
        !           173: .RS
        !           174: .ip \fIFget\|(i:\ framevariable)\fR
        !           175: .RE
        !           176: .lp
        !           177: .b
        !           178: Imager Operators
        !           179: .RS
        !           180: .ip \fIIget\|(i:\ imagervariable)\fR
        !           181: .ip \fISetamplifyspace\|(n:\ value)\fR
        !           182: .ip \fISetcorrectpass\|(i:\ value)\fR
        !           183: .ip \fISetcorreectshrink\|(n:\ number)\fR
        !           184: .ip \fISetnoimage\|(i:\ integer)\fR
        !           185: .ip \fISetpriorityimportant\|(i:\ integer)\fR
        !           186: .ip \fISetstrokeend\|(i:\ integer)\fR
        !           187: .ip \fISetstrokewidth\|(n:\ number)\fR
        !           188: .ip \fISetunderlinestart\|(n: number)\fR
        !           189: .RE
        !           190: .lp
        !           191: .b
        !           192: Mask Operators
        !           193: .r
        !           194: .RS
        !           195: .ip \fIMaskrectangle\|(n:\ x,\ n:\ y,\ n:\ width,\ n:\ height)\fR
        !           196: .ip \fIMasktrapezoidx\|(n:\ x1,\ n:\ y1,\ n:\ x2,\ n:\ x3,\ n:\ y3,\ n:\ x4)\fR
        !           197: .ip \fIMasktrapezoidy\|(n:\ x1,\ n:\ y1,\ n:\ y2,\ n:\ x3,\ n:\ y3,\ n:\ y4)\fR
        !           198: .ip \fIMaskunderline\|(n:\ dy,\ n:\ h)\fR
        !           199: .ip \fIMaskvector\|(n:\ x1,\ n:\ y1,\ n:\ x2,\ n:\ y2)\fR
        !           200: .RE
        !           201: .lp
        !           202: .b
        !           203: Position Operators
        !           204: .RS
        !           205: .ip \fISetxy\|(n:\ x,\ n:\ y)\fR
        !           206: .ip \fISetxyrel\|(n:\ dx,\ n:\ dy)\fR
        !           207: .ip \fISetxrel\|(n:\ dx)\fR
        !           208: .ip \fISetyrel\|(n:\ dy)\fR
        !           209: .RE
        !           210: .lp
        !           211: .b
        !           212: Test Operators
        !           213: .RS
        !           214: .ip \fIAnd\|(i:\ value1,\ i:\ value2)\fR
        !           215: .ip \fIGe\|(n:\ value1,\ n:\ value2)\fR
        !           216: .ip \fIGt\|(n:\ value2,\ n:\ value2)\fR
        !           217: .ip \fINot\|(i:\ value)\fR
        !           218: .ip \fIOr\|(i:\ value1,\ i:\ value2)\fR
        !           219: .RE
        !           220: .lp
        !           221: .b
        !           222: Transform Operators
        !           223: .RS
        !           224: .ip \fIRotate\|(n:\ angle)\fR
        !           225: .ip \fIScale\|(n:\ s)\fR
        !           226: .ip \fIScale2\|(n:\ sx,\ n:\ sy)\fR
        !           227: .ip \fITranslate\|(n:\ x,\ n:\ y)\fR
        !           228: .RE
        !           229: .RE
        !           230: .lp
        !           231: .i
        !           232: Operators with implicit values:
        !           233: .r
        !           234: The following routines append the named operator along with the values
        !           235: specified, with the assumption that other values have been appended through
        !           236: previous calls to the literal interface:
        !           237: .RS
        !           238: .lp
        !           239: .b
        !           240: Mask Operators
        !           241: .RS
        !           242: .ip \fILineto\|(n:\ x,\ n:\ y)\fR
        !           243: .ip \fILinetox\|(n:\ x)\fR
        !           244: .ip \fILinetoy\|(n:\ y)\fR
        !           245: .ip \fIMakeoutline\|(i:\ count)\fR
        !           246: .RE
        !           247: .lp
        !           248: .b
        !           249: Stack Operators
        !           250: .RS
        !           251: .ip \fICopy\|(i:\ count)\fR
        !           252: .ip \fIRoll\|(i:\ depth,\ i:\ movefirst)\fR
        !           253: .ip \fIMark\|(i:\ count)\fR
        !           254: .ip \fIUnmark\|(i:\ count)\fR
        !           255: .RE
        !           256: .lp
        !           257: .b
        !           258: Vector Operators
        !           259: .RS
        !           260: .ip \fIGet\|(n:\ index)\fR
        !           261: .ip \fIMakevec\|(I:\ upper)\fR
        !           262: .ip \fIMakeveclu\|(i:\ lower,\ i:\ upper)\fR
        !           263: .RE
        !           264: .RE
        !           265: .lp
        !           266: .i
        !           267: Templates:
        !           268: .r
        !           269: Several procedures are provided for common Interpress operations which may
        !           270: logically combine groups of operators and values.  Those procedures are:
        !           271: .RS
        !           272: .ip \fISetupFont\|(s:\ name,\ i:\ size,\ i:\ fontnumber)\fR
        !           273: .ip \fIShowString\|(s:\ string)\fR
        !           274: .RE
        !           275: .sh 2 "Using the Program Interface"
        !           276: .lp
        !           277: The software which uses these Interpress interfaces can find the
        !           278: the desired subroutines in the Interpress library
        !           279: .i libip.a
        !           280: which exists in the directory
        !           281: .i ${SRC}/lib
        !           282: as distributed.
        !           283: .lp
        !           284: There are also several include files in the directory
        !           285: .i ${SRC}/include
        !           286: which contain the following utilities:
        !           287: .RS
        !           288: .ip iptokens.h
        !           289: definitions for the Interpress encoding of tokens, sequence types and operators
        !           290: .ip literal.h
        !           291: macro definitions for portions of the literal interface 
        !           292: .ip operator.h
        !           293: macro definitions for most of the operator interface
        !           294: .RE
        !           295: .lp
        !           296: .i
        !           297: Note that ${SRC} above denotes the path in which the Interpress software was
        !           298: loaded on the host system.
        !           299: .r
        !           300: .sh 3 "An example using the program interfaces"
        !           301: .lp
        !           302: The following short C program demonstrates an Interpress
        !           303: generation facility. This will produce an Interpress master on the file
        !           304: descriptor stdout which will print the line "This is an Interpress test"
        !           305: across the top of the page.
        !           306: .in +5n
        !           307: .lp
        !           308: #include "iptokens.h"
        !           309: .br
        !           310: #include "literal.h"
        !           311: .br
        !           312: #include "operator.h"
        !           313: .br
        !           314: main()
        !           315: .br
        !           316: {
        !           317: .in +5n
        !           318: ip_select(1);  /* open stdout */
        !           319: .br
        !           320: Op(beginBlock);
        !           321: .br
        !           322: Op(beginBody);
        !           323: .br
        !           324: SetupFont("Xerox/XC1-1-1/Classic",100.,1);     /* establish default font */
        !           325: .br
        !           326: AppendRational(353,10000000);  /* scale of 1/10 point */
        !           327: .br
        !           328: Op(scale);
        !           329: .br
        !           330: AppendInteger(2);
        !           331: .br
        !           332: Op(fset);      /* save in frame variable 2 */
        !           333: .br
        !           334: Op(endBody);   /* end preamble */
        !           335: .br
        !           336: Op(beginBody); /* start page 1 */
        !           337: .br
        !           338: Fget(2);       /* retrieve scale */
        !           339: .br
        !           340: Setfont(1);    /* retrieve default font */
        !           341: .br
        !           342: Setxy((double)1440,(double)7200);
        !           343: .br
        !           344: ShowString("This is an Interpress test");
        !           345: .br
        !           346: Op(endBody);
        !           347: .br
        !           348: Op(endBlock);
        !           349: .br
        !           350: ip_close();    /* close file */
        !           351: .in -5n
        !           352: }
        !           353: .in -5n

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.