engManual/004077500630510000012000000000000564060453500136465ustar00ousterstaff377777770000002engManual/proto.c010066400630510000012000000026550564060375500151650ustar00ousterstaff377777770000002/* * module.c -- * * Description. * * Copyright (c) 1994 The Regents of the University of California. * All rights reserved. * * Permission is hereby granted, without written agreement and without * license or royalty fees, to use, copy, modify, and distribute this * software and its documentation for any purpose, provided that the * above copyright notice and the following two paragraphs appear in * all copies of this software. * * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. */ static char sccsid[] = "%Z% %M% %I% %E% %U%"; /* *---------------------------------------------------------------------- * * -- * * * * Results: * None. * * Side effects: * None. * *---------------------------------------------------------------------- */ void Routine() { } engManual/proto.h010066400630510000012000000024050564060375500151630ustar00ousterstaff377777770000002/* * header.h -- * * Declarations of ... * * Copyright (c) 1994 The Regents of the University of California. * All rights reserved. * * Permission is hereby granted, without written agreement and without * license or royalty fees, to use, copy, modify, and distribute this * software and its documentation for any purpose, provided that the * above copyright notice and the following two paragraphs appear in * all copies of this software. * * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. * * SCCS: %Z% %M% %I% %E% %U% */ #ifndef _HEADER #define _HEADER /* constants */ /* data structures */ /* procedures */ #endif /* _HEADER */ engManual/prochead010066400630510000012000000004170564060375500153600ustar00ousterstaff377777770000002 /* *---------------------------------------------------------------------- * * -- * * * * Results: * None. * * Side effects: * None. * *---------------------------------------------------------------------- */ void Routine() { } engManual/engManual.ps010066400630510000012000004344550564060376400161400ustar00ousterstaff377777770000002%! %%BoundingBox: (atend) %%Pages: (atend) %%DocumentFonts: (atend) %%EndComments % % FrameMaker PostScript Prolog 3.0, for use with FrameMaker 3.0 % Copyright (c) 1986,87,89,90,91 by Frame Technology Corporation. % All rights reserved. % % Known Problems: % Due to bugs in Transcript, the 'PS-Adobe-' is omitted from line 1 /FMversion (3.0) def % Set up Color vs. Black-and-White /FMPrintInColor systemdict /colorimage known systemdict /currentcolortransfer known or def % Uncomment this line to force b&w on color printer % /FMPrintInColor false def /FrameDict 195 dict def systemdict /errordict known not {/errordict 10 dict def errordict /rangecheck {stop} put} if % The readline in 23.0 doesn't recognize cr's as nl's on AppleTalk FrameDict /tmprangecheck errordict /rangecheck get put errordict /rangecheck {FrameDict /bug true put} put FrameDict /bug false put mark % Some PS machines read past the CR, so keep the following 3 lines together! currentfile 5 string readline 00 0000000000 cleartomark errordict /rangecheck FrameDict /tmprangecheck get put FrameDict /bug get { /readline { /gstring exch def /gfile exch def /gindex 0 def { gfile read pop dup 10 eq {exit} if dup 13 eq {exit} if gstring exch gindex exch put /gindex gindex 1 add def } loop pop gstring 0 gindex getinterval true } def } if /FMVERSION { FMversion ne { /Times-Roman findfont 18 scalefont setfont 100 100 moveto (FrameMaker version does not match postscript_prolog!) dup = show showpage } if } def /FMLOCAL { FrameDict begin 0 def end } def /gstring FMLOCAL /gfile FMLOCAL /gindex FMLOCAL /orgxfer FMLOCAL /orgproc FMLOCAL /organgle FMLOCAL /orgfreq FMLOCAL /yscale FMLOCAL /xscale FMLOCAL /manualfeed FMLOCAL /paperheight FMLOCAL /paperwidth FMLOCAL /FMDOCUMENT { array /FMfonts exch def /#copies exch def FrameDict begin 0 ne dup {setmanualfeed} if /manualfeed exch def /paperheight exch def /paperwidth exch def /yscale exch def /xscale exch def currenttransfer cvlit /orgxfer exch def currentscreen cvlit /orgproc exch def /organgle exch def /orgfreq exch def setpapername manualfeed {true} {papersize} ifelse {manualpapersize} {false} ifelse {desperatepapersize} if end } def /pagesave FMLOCAL /orgmatrix FMLOCAL /landscape FMLOCAL /FMBEGINPAGE { FrameDict begin /pagesave save def 3.86 setmiterlimit /landscape exch 0 ne def landscape { 90 rotate 0 exch neg translate pop } {pop pop} ifelse xscale yscale scale /orgmatrix matrix def gsave } def /FMENDPAGE { grestore pagesave restore end showpage } def /FMFONTDEFINE { FrameDict begin findfont ReEncode 1 index exch definefont FMfonts 3 1 roll put end } def /FMFILLS { FrameDict begin array /fillvals exch def end } def /FMFILL { FrameDict begin fillvals 3 1 roll put end } def /FMNORMALIZEGRAPHICS { newpath 0.0 0.0 moveto 1 setlinewidth 0 setlinecap 0 0 0 sethsbcolor 0 setgray } bind def /fx FMLOCAL /fy FMLOCAL /fh FMLOCAL /fw FMLOCAL /llx FMLOCAL /lly FMLOCAL /urx FMLOCAL /ury FMLOCAL /FMBEGINEPSF { end /FMEPSF save def /showpage {} def FMNORMALIZEGRAPHICS [/fy /fx /fh /fw /ury /urx /lly /llx] {exch def} forall fx fy translate rotate fw urx llx sub div fh ury lly sub div scale llx neg lly neg translate } bind def /FMENDEPSF { FMEPSF restore FrameDict begin } bind def FrameDict begin /setmanualfeed { %%BeginFeature *ManualFeed True statusdict /manualfeed true put %%EndFeature } def /max {2 copy lt {exch} if pop} bind def /min {2 copy gt {exch} if pop} bind def /inch {72 mul} def /pagedimen { paperheight sub abs 16 lt exch paperwidth sub abs 16 lt and {/papername exch def} {pop} ifelse } def /papersizedict FMLOCAL /setpapername { /papersizedict 14 dict def papersizedict begin /papername /unknown def /Letter 8.5 inch 11.0 inch pagedimen /LetterSmall 7.68 inch 10.16 inch pagedimen /Tabloid 11.0 inch 17.0 inch pagedimen /Ledger 17.0 inch 11.0 inch pagedimen /Legal 8.5 inch 14.0 inch pagedimen /Statement 5.5 inch 8.5 inch pagedimen /Executive 7.5 inch 10.0 inch pagedimen /A3 11.69 inch 16.5 inch pagedimen /A4 8.26 inch 11.69 inch pagedimen /A4Small 7.47 inch 10.85 inch pagedimen /B4 10.125 inch 14.33 inch pagedimen /B5 7.16 inch 10.125 inch pagedimen end } def /papersize { papersizedict begin /Letter {lettertray letter} def /LetterSmall {lettertray lettersmall} def /Tabloid {11x17tray 11x17} def /Ledger {ledgertray ledger} def /Legal {legaltray legal} def /Statement {statementtray statement} def /Executive {executivetray executive} def /A3 {a3tray a3} def /A4 {a4tray a4} def /A4Small {a4tray a4small} def /B4 {b4tray b4} def /B5 {b5tray b5} def /unknown {unknown} def papersizedict dup papername known {papername} {/unknown} ifelse get end /FMdicttop countdictstack 1 add def statusdict begin stopped end countdictstack -1 FMdicttop {pop end} for } def /manualpapersize { papersizedict begin /Letter {letter} def /LetterSmall {lettersmall} def /Tabloid {11x17} def /Ledger {ledger} def /Legal {legal} def /Statement {statement} def /Executive {executive} def /A3 {a3} def /A4 {a4} def /A4Small {a4small} def /B4 {b4} def /B5 {b5} def /unknown {unknown} def papersizedict dup papername known {papername} {/unknown} ifelse get end stopped } def /desperatepapersize { statusdict /setpageparams known { paperwidth paperheight 0 1 statusdict begin {setpageparams} stopped pop end } if } def /savematrix { orgmatrix currentmatrix pop } bind def /restorematrix { orgmatrix setmatrix } bind def /dmatrix matrix def /dpi 72 0 dmatrix defaultmatrix dtransform dup mul exch dup mul add sqrt def /freq dpi 18.75 div 8 div round dup 0 eq {pop 1} if 8 mul dpi exch div def /sangle 1 0 dmatrix defaultmatrix dtransform exch atan def /DiacriticEncoding [ /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /space /exclam /quotedbl /numbersign /dollar /percent /ampersand /quotesingle /parenleft /parenright /asterisk /plus /comma /hyphen /period /slash /zero /one /two /three /four /five /six /seven /eight /nine /colon /semicolon /less /equal /greater /question /at /A /B /C /D /E /F /G /H /I /J /K /L /M /N /O /P /Q /R /S /T /U /V /W /X /Y /Z /bracketleft /backslash /bracketright /asciicircum /underscore /grave /a /b /c /d /e /f /g /h /i /j /k /l /m /n /o /p /q /r /s /t /u /v /w /x /y /z /braceleft /bar /braceright /asciitilde /.notdef /Adieresis /Aring /Ccedilla /Eacute /Ntilde /Odieresis /Udieresis /aacute /agrave /acircumflex /adieresis /atilde /aring /ccedilla /eacute /egrave /ecircumflex /edieresis /iacute /igrave /icircumflex /idieresis /ntilde /oacute /ograve /ocircumflex /odieresis /otilde /uacute /ugrave /ucircumflex /udieresis /dagger /.notdef /cent /sterling /section /bullet /paragraph /germandbls /registered /copyright /trademark /acute /dieresis /.notdef /AE /Oslash /.notdef /.notdef /.notdef /.notdef /yen /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /ordfeminine /ordmasculine /.notdef /ae /oslash /questiondown /exclamdown /logicalnot /.notdef /florin /.notdef /.notdef /guillemotleft /guillemotright /ellipsis /.notdef /Agrave /Atilde /Otilde /OE /oe /endash /emdash /quotedblleft /quotedblright /quoteleft /quoteright /.notdef /.notdef /ydieresis /Ydieresis /fraction /currency /guilsinglleft /guilsinglright /fi /fl /daggerdbl /periodcentered /quotesinglbase /quotedblbase /perthousand /Acircumflex /Ecircumflex /Aacute /Edieresis /Egrave /Iacute /Icircumflex /Idieresis /Igrave /Oacute /Ocircumflex /.notdef /Ograve /Uacute /Ucircumflex /Ugrave /dotlessi /circumflex /tilde /macron /breve /dotaccent /ring /cedilla /hungarumlaut /ogonek /caron ] def /ReEncode { dup length dict begin { 1 index /FID ne {def} {pop pop} ifelse } forall 0 eq {/Encoding DiacriticEncoding def} if currentdict end } bind def /graymode true def /bwidth FMLOCAL /bpside FMLOCAL /bstring FMLOCAL /onbits FMLOCAL /offbits FMLOCAL /xindex FMLOCAL /yindex FMLOCAL /x FMLOCAL /y FMLOCAL /setpattern { /bwidth exch def /bpside exch def /bstring exch def /onbits 0 def /offbits 0 def freq sangle landscape {90 add} if {/y exch def /x exch def /xindex x 1 add 2 div bpside mul cvi def /yindex y 1 add 2 div bpside mul cvi def bstring yindex bwidth mul xindex 8 idiv add get 1 7 xindex 8 mod sub bitshift and 0 ne {/onbits onbits 1 add def 1} {/offbits offbits 1 add def 0} ifelse } setscreen {} settransfer offbits offbits onbits add div FMsetgray /graymode false def } bind def /grayness { FMsetgray graymode not { /graymode true def orgxfer cvx settransfer orgfreq organgle orgproc cvx setscreen } if } bind def /HUE FMLOCAL /SAT FMLOCAL /BRIGHT FMLOCAL /Colors FMLOCAL FMPrintInColor { /HUE 0 def /SAT 0 def /BRIGHT 0 def % array of arrays Hue and Sat values for the separations [HUE BRIGHT] /Colors [[0 0 ] % black [0 0 ] % white [0.00 1.0] % red [0.37 1.0] % green [0.60 1.0] % blue [0.50 1.0] % cyan [0.83 1.0] % magenta [0.16 1.0] % comment / yellow ] def /BEGINBITMAPCOLOR { BITMAPCOLOR} def /BEGINBITMAPCOLORc { BITMAPCOLORc} def /BEGINBITMAPTRUECOLOR { BITMAPTRUECOLOR } def /BEGINBITMAPTRUECOLORc { BITMAPTRUECOLORc } def /K { Colors exch get dup 0 get /HUE exch store 1 get /BRIGHT exch store HUE 0 eq BRIGHT 0 eq and {1.0 SAT sub setgray} {HUE SAT BRIGHT sethsbcolor} ifelse } def /FMsetgray { /SAT exch 1.0 exch sub store HUE 0 eq BRIGHT 0 eq and {1.0 SAT sub setgray} {HUE SAT BRIGHT sethsbcolor} ifelse } bind def } { /BEGINBITMAPCOLOR { BITMAPGRAY} def /BEGINBITMAPCOLORc { BITMAPGRAYc} def /BEGINBITMAPTRUECOLOR { BITMAPTRUEGRAY } def /BEGINBITMAPTRUECOLORc { BITMAPTRUEGRAYc } def /FMsetgray {setgray} bind def /K { pop } def } ifelse /normalize { transform round exch round exch itransform } bind def /dnormalize { dtransform round exch round exch idtransform } bind def /lnormalize { 0 dtransform exch cvi 2 idiv 2 mul 1 add exch idtransform pop } bind def /H { lnormalize setlinewidth } bind def /Z { setlinecap } bind def /fillvals FMLOCAL /X { fillvals exch get dup type /stringtype eq {8 1 setpattern} {grayness} ifelse } bind def /V { gsave eofill grestore } bind def /N { stroke } bind def /M {newpath moveto} bind def /E {lineto} bind def /D {curveto} bind def /O {closepath} bind def /n FMLOCAL /L { /n exch def newpath normalize moveto 2 1 n {pop normalize lineto} for } bind def /Y { L closepath } bind def /x1 FMLOCAL /x2 FMLOCAL /y1 FMLOCAL /y2 FMLOCAL /rad FMLOCAL /R { /y2 exch def /x2 exch def /y1 exch def /x1 exch def x1 y1 x2 y1 x2 y2 x1 y2 4 Y } bind def /RR { /rad exch def normalize /y2 exch def /x2 exch def normalize /y1 exch def /x1 exch def newpath x1 y1 rad add moveto x1 y2 x2 y2 rad arcto x2 y2 x2 y1 rad arcto x2 y1 x1 y1 rad arcto x1 y1 x1 y2 rad arcto closepath 16 {pop} repeat } bind def /C { grestore gsave R clip } bind def /FMpointsize FMLOCAL /F { FMfonts exch get FMpointsize scalefont setfont } bind def /Q { /FMpointsize exch def F } bind def /T { moveto show } bind def /RF { rotate 0 ne {-1 1 scale} if } bind def /TF { gsave moveto RF show grestore } bind def /P { moveto 0 32 3 2 roll widthshow } bind def /PF { gsave moveto RF 0 32 3 2 roll widthshow grestore } bind def /S { moveto 0 exch ashow } bind def /SF { gsave moveto RF 0 exch ashow grestore } bind def /B { moveto 0 32 4 2 roll 0 exch awidthshow } bind def /BF { gsave moveto RF 0 32 4 2 roll 0 exch awidthshow grestore } bind def /G { gsave newpath normalize translate 0.0 0.0 moveto dnormalize scale 0.0 0.0 1.0 5 3 roll arc closepath fill grestore } bind def /A { gsave savematrix newpath 2 index 2 div add exch 3 index 2 div sub exch normalize 2 index 2 div sub exch 3 index 2 div add exch translate scale 0.0 0.0 1.0 5 3 roll arc restorematrix stroke grestore } bind def /x FMLOCAL /y FMLOCAL /w FMLOCAL /h FMLOCAL /xx FMLOCAL /yy FMLOCAL /ww FMLOCAL /hh FMLOCAL /FMsaveobject FMLOCAL /FMoptop FMLOCAL /FMdicttop FMLOCAL /BEGINPRINTCODE { /FMdicttop countdictstack 1 add def /FMoptop count 4 sub def /FMsaveobject save def userdict begin /showpage {} def FMNORMALIZEGRAPHICS 3 index neg 3 index neg translate } bind def /ENDPRINTCODE { count -1 FMoptop {pop pop} for countdictstack -1 FMdicttop {pop end} for FMsaveobject restore } bind def /gn { 0 { 46 mul cf read pop 32 sub dup 46 lt {exit} if 46 sub add } loop add } bind def /str FMLOCAL /cfs { /str sl string def 0 1 sl 1 sub {str exch val put} for str def } bind def /ic [ 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0223 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0223 0 {0 hx} {1 hx} {2 hx} {3 hx} {4 hx} {5 hx} {6 hx} {7 hx} {8 hx} {9 hx} {10 hx} {11 hx} {12 hx} {13 hx} {14 hx} {15 hx} {16 hx} {17 hx} {18 hx} {19 hx} {gn hx} {0} {1} {2} {3} {4} {5} {6} {7} {8} {9} {10} {11} {12} {13} {14} {15} {16} {17} {18} {19} {gn} {0 wh} {1 wh} {2 wh} {3 wh} {4 wh} {5 wh} {6 wh} {7 wh} {8 wh} {9 wh} {10 wh} {11 wh} {12 wh} {13 wh} {14 wh} {gn wh} {0 bl} {1 bl} {2 bl} {3 bl} {4 bl} {5 bl} {6 bl} {7 bl} {8 bl} {9 bl} {10 bl} {11 bl} {12 bl} {13 bl} {14 bl} {gn bl} {0 fl} {1 fl} {2 fl} {3 fl} {4 fl} {5 fl} {6 fl} {7 fl} {8 fl} {9 fl} {10 fl} {11 fl} {12 fl} {13 fl} {14 fl} {gn fl} ] def /sl FMLOCAL /val FMLOCAL /ws FMLOCAL /im FMLOCAL /bs FMLOCAL /cs FMLOCAL /len FMLOCAL /pos FMLOCAL /ms { /sl exch def /val 255 def /ws cfs /im cfs /val 0 def /bs cfs /cs cfs } bind def 400 ms /ip { is 0 cf cs readline pop { ic exch get exec add } forall pop } bind def /wh { /len exch def /pos exch def ws 0 len getinterval im pos len getinterval copy pop pos len } bind def /bl { /len exch def /pos exch def bs 0 len getinterval im pos len getinterval copy pop pos len } bind def /s1 1 string def /fl { /len exch def /pos exch def /val cf s1 readhexstring pop 0 get def pos 1 pos len add 1 sub {im exch val put} for pos len } bind def /hx { 3 copy getinterval cf exch readhexstring pop pop } bind def /h FMLOCAL /w FMLOCAL /d FMLOCAL /lb FMLOCAL /bitmapsave FMLOCAL /is FMLOCAL /cf FMLOCAL /wbytes { dup 8 eq {pop} {1 eq {7 add 8 idiv} {3 add 4 idiv} ifelse} ifelse } bind def /BEGINBITMAPBWc { 1 {} COMMONBITMAPc } bind def /BEGINBITMAPGRAYc { 8 {} COMMONBITMAPc } bind def /BEGINBITMAP2BITc { 2 {} COMMONBITMAPc } bind def /COMMONBITMAPc { /r exch def /d exch def gsave translate rotate scale /h exch def /w exch def /lb w d wbytes def sl lb lt {lb ms} if /bitmapsave save def r /is im 0 lb getinterval def ws 0 lb getinterval is copy pop /cf currentfile def w h d [w 0 0 h neg 0 h] {ip} image bitmapsave restore grestore } bind def /BEGINBITMAPBW { 1 {} COMMONBITMAP } bind def /BEGINBITMAPGRAY { 8 {} COMMONBITMAP } bind def /BEGINBITMAP2BIT { 2 {} COMMONBITMAP } bind def /COMMONBITMAP { /r exch def /d exch def gsave translate rotate scale /h exch def /w exch def /bitmapsave save def r /is w d wbytes string def /cf currentfile def w h d [w 0 0 h neg 0 h] {cf is readhexstring pop} image bitmapsave restore grestore } bind def /proc1 FMLOCAL /proc2 FMLOCAL /newproc FMLOCAL /Fmcc { /proc2 exch cvlit def /proc1 exch cvlit def /newproc proc1 length proc2 length add array def newproc 0 proc1 putinterval newproc proc1 length proc2 putinterval newproc cvx } bind def /ngrayt 256 array def /nredt 256 array def /nbluet 256 array def /ngreent 256 array def /gryt FMLOCAL /blut FMLOCAL /grnt FMLOCAL /redt FMLOCAL /indx FMLOCAL /cynu FMLOCAL /magu FMLOCAL /yelu FMLOCAL /k FMLOCAL /u FMLOCAL /colorsetup { currentcolortransfer /gryt exch def /blut exch def /grnt exch def /redt exch def 0 1 255 { /indx exch def /cynu 1 red indx get 255 div sub def /magu 1 green indx get 255 div sub def /yelu 1 blue indx get 255 div sub def /k cynu magu min yelu min def /u k currentundercolorremoval exec def nredt indx 1 0 cynu u sub max sub redt exec put ngreent indx 1 0 magu u sub max sub grnt exec put nbluet indx 1 0 yelu u sub max sub blut exec put ngrayt indx 1 k currentblackgeneration exec sub gryt exec put } for {255 mul cvi nredt exch get} {255 mul cvi ngreent exch get} {255 mul cvi nbluet exch get} {255 mul cvi ngrayt exch get} setcolortransfer {pop 0} setundercolorremoval {} setblackgeneration } bind def /tran FMLOCAL /fakecolorsetup { /tran 256 string def 0 1 255 {/indx exch def tran indx red indx get 77 mul green indx get 151 mul blue indx get 28 mul add add 256 idiv put} for currenttransfer {255 mul cvi tran exch get 255.0 div} exch Fmcc settransfer } bind def /BITMAPCOLOR { /d 8 def gsave translate rotate scale /h exch def /w exch def /bitmapsave save def colorsetup /is w d wbytes string def /cf currentfile def w h d [w 0 0 h neg 0 h] {cf is readhexstring pop} {is} {is} true 3 colorimage bitmapsave restore grestore } bind def /BITMAPCOLORc { /d 8 def gsave translate rotate scale /h exch def /w exch def /lb w d wbytes def sl lb lt {lb ms} if /bitmapsave save def colorsetup /is im 0 lb getinterval def ws 0 lb getinterval is copy pop /cf currentfile def w h d [w 0 0 h neg 0 h] {ip} {is} {is} true 3 colorimage bitmapsave restore grestore } bind def /BITMAPTRUECOLORc { gsave translate rotate scale /h exch def /w exch def /bitmapsave save def /is w string def ws 0 w getinterval is copy pop /cf currentfile def w h 8 [w 0 0 h neg 0 h] {ip} {gip} {bip} true 3 colorimage bitmapsave restore grestore } bind def /BITMAPTRUECOLOR { gsave translate rotate scale /h exch def /w exch def /bitmapsave save def /is w string def /gis w string def /bis w string def /cf currentfile def w h 8 [w 0 0 h neg 0 h] { cf is readhexstring pop } { cf gis readhexstring pop } { cf bis readhexstring pop } true 3 colorimage bitmapsave restore grestore } bind def /BITMAPTRUEGRAYc { gsave translate rotate scale /h exch def /w exch def /bitmapsave save def /is w string def ws 0 w getinterval is copy pop /cf currentfile def w h 8 [w 0 0 h neg 0 h] {ip gip bip w gray} image bitmapsave restore grestore } bind def /ww FMLOCAL /r FMLOCAL /g FMLOCAL /b FMLOCAL /i FMLOCAL /gray { /ww exch def /b exch def /g exch def /r exch def 0 1 ww 1 sub { /i exch def r i get .299 mul g i get .587 mul b i get .114 mul add add r i 3 -1 roll floor cvi put } for r } bind def /BITMAPTRUEGRAY { gsave translate rotate scale /h exch def /w exch def /bitmapsave save def /is w string def /gis w string def /bis w string def /cf currentfile def w h 8 [w 0 0 h neg 0 h] { cf is readhexstring pop cf gis readhexstring pop cf bis readhexstring pop w gray} image bitmapsave restore grestore } bind def /BITMAPGRAY { 8 {fakecolorsetup} COMMONBITMAP } bind def /BITMAPGRAYc { 8 {fakecolorsetup} COMMONBITMAPc } bind def /ENDBITMAP { } bind def end /ALDsave FMLOCAL /ALDmatrix matrix def ALDmatrix currentmatrix pop /StartALD { /ALDsave save def savematrix ALDmatrix setmatrix } bind def /InALD { restorematrix } bind def /DoneALD { ALDsave restore } bind def %%EndProlog %%BeginSetup (3.0) FMVERSION /newdict /Courier findfont length 1 add dict def /Courier findfont { 1 index /FID ne {newdict 3 1 roll put} {pop pop} ifelse } forall newdict /StrokeWidth 60 put /Courier newdict definefont pop /newdict /Courier-Oblique findfont length 1 add dict def /Courier-Oblique findfont { 1 index /FID ne {newdict 3 1 roll put} {pop pop} ifelse } forall newdict /StrokeWidth 60 put /Courier-Oblique newdict definefont pop 1 1 612 792 0 1 15 FMDOCUMENT 0 0 /Times-Roman FMFONTDEFINE 1 0 /Times-Bold FMFONTDEFINE 2 0 /Times-Italic FMFONTDEFINE 3 0 /Helvetica-Bold FMFONTDEFINE 4 0 /Courier FMFONTDEFINE 5 0 /Helvetica FMFONTDEFINE 6 0 /Courier-Oblique FMFONTDEFINE 32 FMFILLS 0 0 FMFILL 1 .1 FMFILL 2 .3 FMFILL 3 .5 FMFILL 4 .7 FMFILL 5 .9 FMFILL 6 .97 FMFILL 7 1 FMFILL 8 <0f1e3c78f0e1c387> FMFILL 9 <0f87c3e1f0783c1e> FMFILL 10 FMFILL 11 FMFILL 12 <8142241818244281> FMFILL 13 <03060c183060c081> FMFILL 14 <8040201008040201> FMFILL 16 1 FMFILL 17 .9 FMFILL 18 .7 FMFILL 19 .5 FMFILL 20 .3 FMFILL 21 .1 FMFILL 22 0.03 FMFILL 23 0 FMFILL 24 FMFILL 25 FMFILL 26 <3333333333333333> FMFILL 27 <0000ffff0000ffff> FMFILL 28 <7ebddbe7e7dbbd7e> FMFILL 29 FMFILL 30 <7fbfdfeff7fbfdfe> FMFILL %%EndSetup %%Page: "1" 1 %%BeginPaperSize: Letter %%EndPaperSize 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (1) 536 42.62 T 1 18 Q -0.36 (T) 248.86 636 S -0.36 (cl/Tk Engineering Manual) 258.85 636 S 2 12 Q (John K. Ouster) 303.97 586 T (hout) 376.71 586 T 0 F (Sun Microsystems, Inc.) 294.37 558 T (john.ousterhout@eng.sun.com) 277.68 544 T 3 F (1.) 141.2 507 T (Introduction) 162 507 T 0 10 Q (This is a manual for people who are developing C code for T) 162 486.33 T (cl, Tk, and their extensions and) 405.01 486.33 T (applications. It describes a set of conventions for writing code and the associated test scripts.) 162 474.33 T -0.04 (There are two reasons for the conventions. First, the conventions ensure that certain important) 162 462.33 P -0.18 (things get done; for example, every procedure must have documentation that describes each of) 162 450.33 P (its ar) 162 438.33 T (guments and its result, and there must exist test scripts that exercise every line of code.) 181.53 438.33 T (Second, the conventions guarantee that all of the T) 162 426.33 T (cl and Tk code has a uniform style. This) 364.21 426.33 T (makes it easier for us to use, read, and maintain each other) 162 414.33 T (\325) 396.35 414.33 T (s code.) 399.13 414.33 T (Most of the conventions originated in the Sprite operating system project at U.C. Berke-) 180 402.33 T -0.11 (ley) 162 390.33 P -0.11 (. At the beginning of the Sprite project my students and I decided that we wanted a uniform) 173.56 390.33 P -0.03 (style for our code and documentation, so we held a series of meetings to choose the rules. The) 162 378.33 P (result of these meetings was a document called) 162 366.33 T 2 F (The Sprite Engineering Manual) 352.42 366.33 T 0 F (. None of us) 479.29 366.33 T -0.14 (was completely happy with all the rules, but we all managed to live by them during the project) 162 354.33 P -0.13 (and I think everyone was happy with the results. When I started work on T) 162 342.33 P -0.13 (cl and Tk, I decided) 458.48 342.33 P -0.34 (to stick with the Sprite conventions. This document is based heavily on) 162 330.33 P 2 F -0.34 (The Sprite Engineering) 445.24 330.33 P (Manual) 162 318.33 T 0 F (.) 193.09 318.33 T (There are few things that I consider non-negotiable, but the contents of this manual are) 180 306.33 T (one of them. I don\325) 162 294.33 T (t claim that these conventions are the best possible ones, but the exact con-) 238.71 294.33 T (ventions don\325) 162 282.33 T (t really make that much dif) 216.51 282.33 T (ference. The most important thing is that we all do) 324.31 282.33 T (things the same way) 162 270.33 T (. Given that the core T) 242.69 270.33 T (cl and Tk code follows the conventions, changing) 331.92 270.33 T (the rules now would cause more harm than good.) 162 258.33 T (Please write your code so that it conforms to the conventions from the very start. For) 180 246.33 T (example, don\325) 162 234.33 T (t write comment-free code on the assumption that you\325ll go back and put the) 219 234.33 T (comments in later once the code is working. This simply won\325) 162 222.33 T (t happen. Regardless of how) 411.38 222.33 T (good your intentions are, when it comes time to go back and put in the comments you\325ll \336nd) 162 210.33 T (that you have a dozen more important things to do; as the body of uncommented code builds) 162 198.33 T (up, it will be harder and harder to work up the ener) 162 186.33 T (gy to go back and \336x it all. One of the fun-) 365.55 186.33 T (damental rules of software is that its structure only gets worse over time; if you don\325) 162 174.33 T (t build it) 499.64 174.33 T (right to begin with, it will never get that way later) 162 162.33 T (. When I write code I typically write the pro-) 360.49 162.33 T (cedure headers for a whole \336le before I \336ll in any of the bodies.) 162 150.33 T (The rest of this document consists of 8 major parts. Section) 180 138.33 T (2 discusses the overall struc-) 419.85 138.33 T (ture of a package and how to or) 162 126.33 T (ganize header \336les. Section) 288.1 126.33 T (3 describes the structure of a C) 399.96 126.33 T (code \336le and how to write procedure headers. Section) 162 114.33 T (4 desribes the T) 379.05 114.33 T (cl/Tk naming conven-) 441.92 114.33 T -0.23 (tions. Section) 162 102.33 P -0.23 (5 presents low-level coding conventions, such as how to indent and where to put) 218.69 102.33 P (curly braces. Section) 162 90.33 T (6 contains a collection of rules and suggestions for writing comments.) 248.04 90.33 T (Section) 162 78.33 T (7 describes how to write and maintain test suites. Section) 194.48 78.33 T (8 describes how to make) 425.73 78.33 T FMENDPAGE %%EndPage: "1" 2 %%Page: "2" 2 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (2) 536 42.62 T 0 10 Q -0.32 (code portable without making it unreadable too. Section 9 contains a few miscellaneous topics,) 162 713.33 P (such as keeping a change log.) 162 701.33 T 3 12 Q (2.) 141.2 665 T (Packages and header \336les) 162 665 T 0 10 Q (T) 162 644.33 T (cl applications consist of collections of) 167.41 644.33 T 2 F (packages) 325.64 644.33 T 0 F (. Each package provides code to implement) 362.83 644.33 T -0.01 (a related set of features. For example, T) 162 632.33 P -0.01 (cl itself is a package, as is Tk; various extensions such) 320.26 632.33 P (as T) 162 620.33 T (cl-DP) 178.23 620.33 T (, T) 200.44 620.33 T (clX, Expect, and BL) 210.84 620.33 T (T are also packages. Packages are the units in which code is) 291.81 620.33 T -0.06 (developed and distributed: a single package is typically developed by a single person or group) 162 608.33 P -0.18 (and distributed as a unit. One of the best things about T) 162 596.33 P -0.18 (cl is that it is possible to combine many) 380.86 596.33 P -0.38 (independently-developed packages into a single application; packages should be designed with) 162 584.33 P (this in mind. This section describes the \336le structure of packages with an emphasis on header) 162 572.33 T -0.2 (\336les; later sections discuss conventions for code \336les. Y) 162 560.33 P -0.2 (ou may also wish to review Chapter 31) 382.84 560.33 P (of the T) 162 548.33 T (cl book for additional information on packages, such as how to interface them to the) 192.94 548.33 T (rest of an application.) 162 536.33 T 3 F (2.1) 137.31 506.33 T (Package pre\336xes) 162 506.33 T 0 F -0.11 (Each package has a unique short) 162 490.33 P 2 F -0.11 (pr) 294 490.33 P -0.11 (e\336x) 302.52 490.33 P 0 F -0.11 (. The pre\336x is used in \336le names, procedure names, and) 316.39 490.33 P -0.17 (variable names in order to prevent name con\337icts with other packages. For example, the pre\336x) 162 478.33 P (for T) 162 466.33 T (cl is) 181.56 466.33 T 4 F (tcl) 200.44 466.33 T 0 F (; T) 218.43 466.33 T (cl\325) 229.11 466.33 T (s exported header \336le is called) 239.11 466.33 T 4 F (tcl.h) 362.9 466.33 T 0 F ( and exported procedures and vari-) 392.88 466.33 T (ables have names like) 162 454.33 T 4 F (Tcl_Eval) 251.93 454.33 T 0 F (.) 299.9 454.33 T 3 F (2.2) 137.31 424.33 T (V) 162 424.33 T (ersion numbers) 168.12 424.33 T 0 F (Each package has a two-part version number such as 7.4. The \336rst number \0507\051 is called the) 162 408.33 T -0.23 (major version number and the second \0504\051 is called the minor version number) 162 396.33 P -0.23 (. The version num-) 464.62 396.33 P (ber changes with each public release of the package. If a new release contains only bug \336xes,) 162 384.33 T (new features, and other upwardly compatible changes, so that code and scripts that worked) 162 372.33 T -0.09 (with the old version will also work with the new version, then the minor version number incre-) 162 360.33 P (ments and the major version number stays the same \050e.g., from 7.4 to 7.5\051. If the new release) 162 348.33 T -0.35 (contains substantial incompatibilities, so that existing code and scripts will have to be modi\336ed) 162 336.33 P (to run with the new version, then the major version number increments and the minor version) 162 324.33 T (number resets to zero \050e.g., from 7.4 to 8.0\051.) 162 312.33 T 3 F (2.3) 137.31 282.33 T (Overall structure) 162 282.33 T 0 F -0.18 (A package typically consists of several code \336les, plus at least two header \336les, plus additional) 162 266.33 P (\336les for building and con\336guring the package, such as a) 162 254.33 T 4 F (Makef) 387.68 254.33 T (ile) 417.66 254.33 T 0 F ( and a) 435.65 254.33 T 4 F (conf) 462.02 254.33 T (igure.in) 486 254.33 T 0 F (\336le for the) 162 242.33 T 4 F (autoconf) 206.14 242.33 T 0 F ( program. The header \336les for a package generally fall into the follow-) 254.11 242.33 T (ing categories:) 162 230.33 T 0 12 Q (\245) 162 215.33 T 0 10 Q (A) 172.8 215.33 T 2 F (package header \336le) 182.51 215.33 T 0 F (, which is named after the package, such as) 260.78 215.33 T 4 F (tcl.h) 435.92 215.33 T 0 F ( or) 465.9 215.33 T 4 F (tk.h) 479.22 215.33 T 0 F (. This) 503.21 215.33 T -0.38 (header \336le describes all of the externally-visible features of the package, such as procedures,) 172.8 203.33 P (global variables, and structure declarations. The package header \336le is eventually installed) 172.8 191.33 T (in a system directory such as) 172.8 179.33 T 4 F (/usr/local/include) 290.49 179.33 T 0 F (; it is what clients of the package) 398.44 179.33 T 4 F (#include) 172.8 167.33 T 0 F ( in their C code. As a general rule of thumb, the package header \336le should) 220.77 167.33 T (de\336ne as few things as possible: it\325) 172.8 155.33 T (s very hard to change an exported feature since it breaks) 312.16 155.33 T (client code that uses the package, so the less you export, the easier it will be to make) 172.8 143.33 T (changes to the package. Thus, for example, try not to make the internal \336elds of structures) 172.8 131.33 T (visible in package header \336les.) 172.8 119.33 T 0 12 Q (\245) 162 104.33 T 0 10 Q (An) 172.8 104.33 T 2 F (internal header \336le) 187.51 104.33 T 0 F (, which is typically) 264.13 104.33 T 4 F (#include) 342.7 104.33 T 0 F (d by all of the C \336les in the package.) 390.67 104.33 T (The internal header \336le has a name like) 172.8 92.33 T 4 F (tclInt.h) 332.67 92.33 T 0 F ( or) 380.65 92.33 T 4 F (tkInt.h) 393.97 92.33 T 0 F (, consisting of the the) 435.95 92.33 T -0.12 (package pre\336x followed by) 172.8 80.33 P 4 F -0.29 (Int.h) 283.9 80.33 P 0 F -0.12 (. The internal header \336le describes features that are used) 313.89 80.33 P -0.32 (in multiple \336les within the package but aren\325) 172.8 68.33 P -0.32 (t exported out of the package. For example, key) 349.42 68.33 P FMENDPAGE %%EndPage: "2" 3 %%Page: "3" 3 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (3) 536 42.62 T 0 10 Q -0.12 (package structures and internal utility procedures are de\336ned in the internal header \336le. The) 172.8 713.33 P (internal header \336le should also contain) 172.8 701.33 T 4 F (#include) 329.91 701.33 T 0 F (s for other headers that are used widely) 377.89 701.33 T (within the package, so they don\325) 172.8 689.33 T (t have to be included over and over in each code \336le. As) 302.53 689.33 T (with the package header) 172.8 677.33 T (, the internal header \336le should be as small as possible: structures) 269.26 677.33 T (and procedures that are only used in a single C \336le in the package should not appear in it.) 172.8 665.33 T 0 12 Q (\245) 162 650.33 T 0 10 Q (A) 172.8 650.33 T 2 F (porting header \336le) 182.51 650.33 T 0 F (, which contains de\336nitions that hide the dif) 256.91 650.33 T (ferences between the sys-) 432.19 650.33 T -0.34 (tems on which the package can be used.The name of the porting header should consist of the) 172.8 638.33 P (package pre\336x follwed by) 172.8 626.33 T 4 F (Port.h) 279.38 626.33 T 0 F (, such as) 315.36 626.33 T 4 F (tclPort.h) 352 626.33 T 0 F (.) 405.97 626.33 T 0 12 Q (\245) 162 611.33 T 0 10 Q (Other internal header \336les for various subpackages within the package. For example, there) 172.8 611.33 T -0.03 (is a \336le) 172.8 599.33 P 4 F -0.08 (tkText.h) 204.07 599.33 P 0 F -0.03 ( in Tk that is shared among all the \336les that implement text widgets and) 252.05 599.33 P (another \336le) 172.8 587.33 T 4 F (tkCanvas.h) 220.54 587.33 T 0 F ( that is shared among all the widgets implementing canvases.) 280.51 587.33 T -0.23 (I recommend having as few header \336les as possible in each package. In almost all cases a pack-) 162 572.33 P (age header \336le, a single internal header \336le, and a porting header \336le will be suf) 162 560.33 T (\336cient, and in) 480.18 560.33 T (many cases the porting header \336le may not be necessary) 162 548.33 T (. The internal header \336le should auto-) 385.9 548.33 T -0.24 (matically) 162 536.33 P 4 F -0.57 (#include) 201.46 536.33 P 0 F -0.24 ( the package header \336le and perhaps even the porting header \336le, so each) 249.43 536.33 P (C \336le in the package only needs to) 162 524.33 T 4 F (#include) 302.46 524.33 T 0 F ( one or at most two header \336les. I recommend) 350.44 524.33 T (keeping the porting header separate from the internal header \336le in order to maintain a clean) 162 512.33 T -0.26 (separation between porting code and the rest of the module. Other internal headers should only) 162 500.33 P -0.31 (be necessary in unusual cases, such as the Tk text and canvas widgets \050each of) 162 488.33 P 4 F -0.74 (tkText.h) 473.21 488.33 P 0 F -0.31 ( and) 521.19 488.33 P 4 F -0.01 (tkCanvas.h) 162 476.33 P 0 F -0.01 ( is many hundred lines long, due to the complexity of the widgets, and they are) 221.97 476.33 P (needed only in the source \336les that implement the particular widgets, so I thought it would be) 162 464.33 T -0.06 (easier to manage these headers separately from) 162 452.33 P 4 F -0.15 (tkInt.h) 352.24 452.33 P 0 F -0.06 (\051. If you have lots of internal header) 394.22 452.33 P -0.08 (\336les, such as one for each source \336le, then you will end up with lots of) 162 440.33 P 4 F -0.19 (#include) 444.99 440.33 P 0 F -0.08 ( statements) 492.96 440.33 P (in each C \336le and you\325ll \336nd that either \050a\051 you) 162 428.33 T 4 F (#include) 352.7 428.33 T 0 F ( every header in every C \336le \050in) 400.68 428.33 T (which case there\325) 162 416.33 T (s not much advantage to having the separate) 231.38 416.33 T 4 F (.h) 410.69 416.33 T 0 F ( \336les\051 or \050b\051 you are con-) 422.69 416.33 T (stantly adding and deleting) 162 404.33 T 4 F (#include) 272.49 404.33 T 0 F ( statements as you modify source \336les.) 320.46 404.33 T 3 F (2.4) 137.31 374.33 T (Header \336le structure) 162 374.33 T 0 F (Figure) 162 358.33 T (1 illustrates the format of a header \336le. Y) 190.59 358.33 T (our header \336les should follow this structure) 354.19 358.33 T -0.12 (exactly: same indentation, same order of information, and so on. T) 162 346.33 P -0.12 (o make this as easy as possi-) 426.33 346.33 P (ble, the directory) 162 334.33 T 4 F (engManual) 232.5 334.33 T 0 F ( in the T) 286.47 334.33 T (cl source tree contains templates for various pieces of) 319.36 334.33 T -0.33 (source \336les. For example, the \336le) 162 322.33 P 4 F -0.8 (proto.h) 295.47 322.33 P 0 F -0.33 ( contains a template for a header \336le; there are also) 337.45 322.33 P (templates for code \336les and procedure headers. Y) 162 310.33 T (ou should be able to set up your editor to) 358.61 310.33 T (incorporate the templates when needed, then you can modify them for the particular situation) 162 298.33 T -0.33 (in which they are used. This should make it easy for you to conform to the conventions without) 162 286.33 P (a lot of typing overhead.) 162 274.33 T (Each header \336le contains the following parts, which are labelled in Figure) 180 262.33 T (1:) 477.84 262.33 T 1 F (Abstract) 172.8 247.33 T 0 F (: the \336rst few lines give the name of the \336le plus a short description of its overall) 209.99 247.33 T (purpose.) 172.8 235.33 T 1 F -0.03 (Copyright notice) 172.8 220.33 P 0 F -0.03 (: this protects the ownership of the \336le and controls distribution; dif) 244.67 220.33 P -0.03 (ferent) 514.23 220.33 P -0.04 (notices may be used on dif) 172.8 208.33 P -0.04 (ferent \336les, depending on whether the \336le is to be released freely) 279.29 208.33 P (or restricted. The wording in copyright notices is sensitive \050e.g. the use of upper case is) 172.8 196.33 T (important\051 so don\325) 172.8 184.33 T (t make changes in notices without checking with a legal authority) 247.02 184.33 T (.) 508.42 184.33 T 1 F (Revision string:) 172.8 169.33 T 0 F ( the contents of this string are managed automatically by the source code) 240.26 169.33 T -0.21 (control system for the \336le, such as RCS or SCCS \050RCS is used in the example in the \336gure\051.) 172.8 157.33 P (It identi\336es the \336le\325) 172.8 145.33 T (s current revision, date of last modi\336cation, and so on.) 250.82 145.33 T 1 F -0.35 (Multiple include #ifdef) 172.8 130.33 P 0 F -0.35 (: when a lar) 269.27 130.33 P -0.35 (ge application is developed with many related packages,) 314.94 130.33 P (it is hard to arrange the) 172.8 118.33 T 4 F (#include) 267.73 118.33 T 0 F ( statements so that each include \336le is included exactly) 315.7 118.33 T (once For example, \336les) 172.8 106.33 T 4 F (a.h) 268.57 106.33 T 0 F ( and) 286.56 106.33 T 4 F (b.h) 305.99 106.33 T 0 F ( might both include) 323.98 106.33 T 4 F (c.h) 404.49 106.33 T 0 F (, and a particular code \336le) 422.48 106.33 T (might include both) 172.8 94.33 T 4 F (a.h) 250.82 94.33 T 0 F ( and) 268.81 94.33 T 4 F (b.h) 288.24 94.33 T 0 F (. This will cause) 306.23 94.33 T 4 F (c.h) 374.24 94.33 T 0 F ( to be processed twice, and could) 392.23 94.33 T (potentially result in compiler errors such as multiply-de\336ned symbols. W) 172.8 82.33 T (ith the recursion) 465 82.33 T 4 F (#ifdef) 172.8 70.33 T 0 F (, plus the matching) 208.78 70.33 T 4 F (#endif) 287.35 70.33 T 0 F ( at the end of the \336le, the header \336le can be) 323.33 70.33 T FMENDPAGE %%EndPage: "3" 4 %%Page: "4" 4 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (4) 536 42.62 T 43.2 68.4 540 720 C 108 75.6 540 716.4 R 7 X 0 K V 4 9 Q 0 X (/*) 126 710.4 T ( * tcl.h --) 126 701.4 T ( *) 126 692.4 T ( * This header f) 126 683.4 T (ile describes the externally-visible facilities) 239.24 683.4 T ( * of the Tcl interpreter.) 126 674.4 T ( *) 126 665.4 T ( * Copyright \050c\051 1987-1994 The Regents of the University of California.) 126 656.4 T ( * All rights reserved.) 126 647.4 T ( *) 126 638.4 T ( * Permission is hereby granted, without written agreement and without) 126 629.4 T ( * license or royalty fees, to use, copy, modify, and distribute this) 126 620.4 T ( * software and its documentation for any purpose, provided that the) 126 611.4 T ( * above copyright notice and the following two paragraphs appear in) 126 602.4 T ( * all copies of this software.) 126 593.4 T ( *) 126 584.4 T ( * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR) 126 575.4 T -0.66 ( * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT) 126 566.4 P -0.8 ( * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF) 126 557.4 P ( * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.) 126 548.4 T ( *) 126 539.4 T ( * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,) 126 530.4 T ( * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY) 126 521.4 T ( * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS) 126 512.4 T -0.08 ( * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO) 126 503.4 P ( * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.) 126 494.4 T ( *) 126 485.4 T -1.2 ( * $Header: /user6/ouster/tcl/RCS/tcl.h,v 1.139 94/05/26 14:40:43 ouster Exp $) 126 476.4 P (SPRITE \050Berkeley\051) 126 467.4 T ( */) 126 458.4 T (#ifndef _TCL) 126 440.4 T (#def) 126 431.4 T (ine _TCL) 147.57 431.4 T (#def) 126 413.4 T (ine TCL_VERSION "7.4") 147.57 413.4 T (#def) 126 404.4 T (ine TCL_MAJOR_VERSION 7) 147.57 404.4 T (#def) 126 395.4 T (ine TCL_MINOR_VERSION 4) 147.57 395.4 T (...) 126 377.4 T (/*) 126 359.4 T ( * The structure returned by Tcl_GetCmdInfo and passed into) 126 350.4 T ( * Tcl_SetCmdInfo:) 126 341.4 T ( */) 126 332.4 T (typedef struct Tcl_CmdInfo {) 126 314.4 T -0.62 ( Tcl_CmdProc *proc; /* Procedure that implements command. */) 126 305.4 P ( ClientData clientData; /* ClientData passed to proc. */) 126 296.4 T ( Tcl_CmdDeleteProc *deleteProc; /* Procedure to call when command) 126 287.4 T ( * is deleted. */) 126 278.4 T -0.48 ( ClientData deleteData; /* Value to pass to deleteProc \050usually) 126 269.4 P ( * the same as clientData\051. */) 126 260.4 T (} Tcl_CmdInfo;) 126 251.4 T (...) 126 233.4 T (EXTERN int tcl_AsyncReady;) 126 215.4 T (...) 126 197.4 T -0.35 (EXTERN int Tcl_Eval _ANSI_ARGS_\050\050Tcl_Interp *interp, char *cmd\051\051;) 126 179.4 P (...) 126 161.4 T (#endif /* _TCL */) 126 143.4 T 1 F -0.67 (Figur) 162 124.4 P -0.67 (e 1.) 183.31 124.4 P 0 F -0.67 (An example of a header \336le. The \336le) 200.36 124.4 P 4 F -1.6 (engManual/proto.h) 329.05 124.4 P 0 F -0.67 ( contains a template for) 420.72 124.4 P (header \336les.) 162 114.4 T 122.4 716.4 118.8 716.4 118.8 673.2 122.4 673.2 4 L 0.5 H 2 Z N 5 F (Abstract) 78.6 691.52 T 122.4 662.4 118.8 662.4 118.8 493.2 122.4 493.2 4 L N 122.4 482.4 118.8 482.4 118.8 464.4 122.4 464.4 4 L N 122.4 446.4 118.8 446.4 118.8 428.4 122.4 428.4 4 L N 122.4 421.2 118.8 421.2 118.8 392.4 122.4 392.4 4 L N 122.4 367.2 118.8 367.2 118.8 244.8 122.4 244.8 4 L N (Structure) 66.1 308.21 T (V) 81.09 409.01 T (ersion) 86.59 409.01 T (Multiple) 80.6 444.11 T (Revision) 77.1 475.61 T (Copyright) 73.1 574.52 T (String) 77.1 466.61 T 122.4 223.2 118.8 223.2 118.8 212.4 122.4 212.4 4 L N 122.4 187.2 118.8 187.2 118.8 176.4 122.4 176.4 4 L N 122.4 151.2 118.8 151.2 118.8 140.4 122.4 140.4 4 L N (De\336nes) 81.09 400.01 T (Declaration) 66.1 299.21 T (V) 66.1 220.01 T (ariable) 71.43 220.01 T (Declaration) 66.1 211.01 T (Procedure) 70.09 184.01 T (Prototype) 70.09 175.01 T (Multiple) 80.6 152.51 T (Include) 80.6 435.11 T (#ifdef) 80.6 426.11 T (Include) 80.6 143.51 T (#endif) 80.6 134.51 T 0 0 612 792 C FMENDPAGE %%EndPage: "4" 5 %%Page: "5" 5 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (5) 536 42.62 T 4 10 Q (#include) 172.8 713.33 T 0 F (d multiple times without problems. The symbol) 220.77 713.33 T 4 F (_TCL) 413.46 713.33 T 0 F ( is de\336ned the \336rst time) 437.45 713.33 T -0.1 (the header \336le is included; if the header is included again the presence of the symbol causes) 172.8 701.33 P -0.34 (the body of the header \336le to be skipped. The symbol used in any given header \336le should be) 172.8 689.33 P (the same as the name of the header \336le except with the) 172.8 677.33 T 4 F (.h) 393.74 677.33 T 0 F ( stripped of) 405.73 677.33 T (f, a) 451.08 677.33 T 4 F (_) 466.34 677.33 T 0 F ( prepended, and) 472.33 677.33 T (everything else capitalized.) 172.8 665.33 T 1 F (V) 172.8 650.33 T (ersion de\336nes) 179.1 650.33 T 0 F (: for each package, three symbols related to the current version number) 237.12 650.33 T (should be de\336ned. The \336rst gives the full version number as a string, and the second and) 172.8 638.33 T -0.28 (third give the major and minor numbers separately as integers. The names for these symbols) 172.8 626.33 P (should be derived from the package pre\336x as in Figure) 172.8 614.33 T (1.) 393.75 614.33 T 1 F (Declarations) 172.8 599.33 T 0 F (: the rest of the header \336le consists of declarations for the things that are) 226.65 599.33 T (exported from the package to its clients. Most of the conventions for coding these declara-) 172.8 587.33 T -0.25 (tions will be discussed later) 172.8 575.33 P -0.25 (. When declaring variables and procedures, use) 281.74 575.33 P 4 F -0.6 (EXTERN) 471.21 575.33 P 0 F -0.25 ( instead) 507.19 575.33 P -0.32 (of) 172.8 563.33 P 4 F -0.78 (extern) 183.3 563.33 P 0 F -0.32 ( to declare them external. The symbol) 219.28 563.33 P 4 F -0.78 (EXTERN) 370.78 563.33 P 0 F -0.32 ( can then be) 406.76 563.33 P 4 F -0.78 (#def) 455.97 563.33 P -0.78 (ine) 479.96 563.33 P 0 F -0.32 (d to either) 497.95 563.33 P 4 F -0.19 (extern) 172.8 551.33 P 0 F -0.08 ( or) 208.78 551.33 P 4 F -0.19 (extern "C") 221.95 551.33 P 0 F -0.08 ( to allow the header \336le to be used in both C and C++ programs.) 281.73 551.33 P -0.09 (The header \336le) 172.8 539.33 P 4 F -0.22 (tcl.h) 234.97 539.33 P 0 F -0.09 ( contains code to) 264.95 539.33 P 4 F -0.22 (#def) 334.53 539.33 P -0.22 (ine) 358.52 539.33 P 0 F -0.09 ( the) 376.51 539.33 P 4 F -0.22 (EXTERN) 393.54 539.33 P 0 F -0.09 ( symbol; if your header \336le) 429.52 539.33 P (doesn\325) 172.8 527.33 T (t) 199.26 527.33 T 4 F (#include) 204.54 527.33 T (tcl.h) 255.01 527.33 T 0 F (, you can copy the code from) 285 527.33 T 4 F (tcl.h) 403.79 527.33 T 0 F ( to your header \336le.) 433.78 527.33 T 3 F (2.5) 137.31 497.33 T (_ANSI_ARGS_ prototypes) 162 497.33 T 0 F (Procedure prototypes should use the) 162 481.33 T 4 F (_ANSI_ARGS_) 309.4 481.33 T 0 F ( macro as shown in Figure) 375.36 481.33 T (1.) 483.62 481.33 T 4 F -0.85 (_ANSI_ARGS_) 162 469.33 P 0 F -0.35 ( makes it possible to write full procedure prototypes for the normal case where) 227.96 469.33 P (an ANSI C compiler will be used, yet it also allows the \336le to be used with older non-ANSI) 162 457.33 T (compilers. T) 162 445.33 T (o use) 211.82 445.33 T 4 F (_ANSI_ARGS_) 235.14 445.33 T 0 F (, specify the entire ar) 301.1 445.33 T (gument list, including parentheses, as) 385.02 445.33 T (an ar) 162 433.33 T (gument to the) 181.52 433.33 T 4 F (_ANSI_ARGS_) 238.99 433.33 T 0 F ( macro;) 304.95 433.33 T 4 F (_ANSI_ARGS_) 337.7 433.33 T 0 F ( will evaluate to either this ar) 403.67 433.33 T (gu-) 520.07 433.33 T (ment list or) 162 421.33 T 4 F (\050\051) 210.03 421.33 T 0 F (, depending on whether or not an ANSI C compiler is being used. The) 222.03 421.33 T 4 F (_ANSI_ARGS_) 162 409.33 T 0 F ( macro is de\336ned in) 227.96 409.33 T 4 F (tcl.h) 309.3 409.33 T 0 F (.) 339.28 409.33 T (In the ar) 180 397.33 T (gument lists in procedure prototypes, be sure to specify names for the ar) 213.12 397.33 T (guments) 501.34 397.33 T -0.01 (as well as their types. The names aren\325) 162 385.33 P -0.01 (t required for compilation \050for example, the declaration) 316.63 385.33 P (for) 162 373.33 T 4 F (Tcl_Eval) 176.15 373.33 T 0 F ( could have been written as) 224.13 373.33 T 4 9 Q -0.31 (EXTERN int Tcl_Eval _ANSI_ARGS_\050\050Tcl_Interp *, char *\051\051;) 189 359 P 0 10 Q (in Figure) 162 345.33 T (1\051 but the names provide additional information about the ar) 200.87 345.33 T (guments.) 441.92 345.33 T 3 12 Q (3.) 141.2 309 T (How to organize a code \336le) 162 309 T 0 10 Q -0.19 (Each source code \336le should contain a related set of procedures, such as the implementation of) 162 288.33 P (a widget or canvas item type, or a set of procedures to implement hash tables. Before writing) 162 276.33 T (any code you should think carefully about what functions are to be provided and divide them) 162 264.33 T -0.16 (up into \336les in a logical way) 162 252.33 P -0.16 (. In my experience, the most manageable size for \336les is usually in) 273.66 252.33 P (the range of 500-2000 lines. If a \336le gets much lar) 162 240.33 T (ger than this, it will be hard to remember) 361.95 240.33 T (everything that the \336le does. If a \336le is much shorter than this, then you may end up with too) 162 228.33 T (many \336les in a directory) 162 216.33 T (, which is also hard to manage.) 258.51 216.33 T (Code \336les are divided into pages separated by formfeed \050control-L\051 characters. The \336rst) 180 204.33 T (page of the \336le is a header page containing information that is used throughout the \336le. Each) 162 192.33 T (additional page of the \336le contains one procedure. This approach has two advantages. First,) 162 180.33 T -0.15 (when you print a code \336le each procedure header will start at the top of the page, which makes) 162 168.33 P -0.02 (for easier reading. Second, you can browse through all of the procedures in a \336le by searching) 162 156.33 P (for the formfeed characters.) 162 144.33 T 3 F (3.1) 137.31 114.33 T (The \336le header page) 162 114.33 T 0 F (The \336rst page of a code \336le is a) 162 98.33 T 2 F (header page) 289.96 98.33 T 0 F (. It contains overall information that is relevant) 339.64 98.33 T (throughout the \336le, which consists of everything but the de\336nitions of the \336le\325) 162 86.33 T (s procedures.) 473.77 86.33 T (The header page typically has six parts, as shown in Figure) 162 74.33 T (2:) 400.72 74.33 T FMENDPAGE %%EndPage: "5" 6 %%Page: "6" 6 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (6) 536 42.62 T 1 10 Q (Abstract) 172.8 184.13 T 0 F (: the \336rst few lines give the name of the \336le and a brief description of the overall) 209.99 184.13 T (functions provided by the \336le, just as in header \336les.) 172.8 172.13 T 1 F (Copyright notice) 172.8 157.13 T 0 F (: protects ownership of the \336le, just as in header \336les.) 244.7 157.13 T 1 F -0.28 (Revision string) 172.8 142.13 P 0 F -0.28 (: similar to the revision strings in header \336les, except that its value is used to) 236.65 142.13 P (initialize a string variable. This allows the revision information to be checked in the execut-) 172.8 130.13 T (able object \336le.) 172.8 118.13 T 1 F (Include statements) 172.8 103.13 T 0 F (: all of the) 253.03 103.13 T 4 F (#include) 296.33 103.13 T 0 F ( statements for the \336le should appear on the) 344.31 103.13 T (header \336le just after the version string. In general there should be very few) 172.8 91.13 T 4 F (#include) 473.39 91.13 T 0 F (statements in a given code \336le, typically just for the package\325) 172.8 79.13 T (s internal header \336le and port-) 417.36 79.13 T 43.2 190.8 540 720 C 4 9 Q 0 X 0 K (/*) 126 710.4 T ( * tclLink.c --) 126 701.4 T ( *) 126 692.4 T ( * This f) 126 683.4 T (ile implements linked variables \050a C variable that is) 201.49 683.4 T ( * tied to a Tcl variable\051. The idea of linked variables was) 126 674.4 T ( * f) 126 665.4 T (irst suggested by Andreas Stolcke and this implementation is) 174.53 665.4 T ( * based heavily on a prototype implementation provided by) 126 656.4 T ( * him.) 126 647.4 T ( *) 126 638.4 T ( * Copyright \050c\051 1993 The Regents of the University of California.) 126 629.4 T ( * All rights reserved.) 126 620.4 T ( *) 126 611.4 T ( * Permission is hereby granted, without written agreement and without) 126 602.4 T ( * license or royalty fees, to use, copy, modify, and distribute this) 126 593.4 T ( * software and its documentation for any purpose, provided that the) 126 584.4 T ( * above copyright notice and the following two paragraphs appear in) 126 575.4 T ( * all copies of this software.) 126 566.4 T ( *) 126 557.4 T ( * ...) 126 548.4 T ( */) 126 539.4 T -1.5 (static char rcsid[] = "$Header: /user6/ouster/tcl/RCS/tclLink.c,v 1.5 94/04/23) 126 521.4 P (16:12:30 ouster Exp $ SPRITE \050Berkeley\051";) 126 512.4 T (#include "tclInt.h") 126 494.4 T (/*) 126 473.4 T ( * For each linked variable there is a data structure of the following) 126 464.4 T ( * type, which describes the link and is the clientData for the trace) 126 455.4 T ( * set on the Tcl variable.) 126 446.4 T ( */) 126 437.4 T (typedef struct Link {) 126 419.4 T ( Tcl_Interp *interp; /* Interpreter containing Tcl variable. */) 126 410.4 T ( char *addr; /* Location of C variable. */) 126 401.4 T ( int type; /* Type of link \050TCL_LINK_INT, etc.\051. */) 126 392.4 T ( int writable; /* Zero means Tcl variable is read-only. */) 126 383.4 T ( union {) 126 374.4 T ( int i;) 126 365.4 T ( double d;) 126 356.4 T ( } lastValue; /* Last known value of C variable; used to) 126 347.4 T ( * avoid string conversions. */) 126 338.4 T (} Link;) 126 329.4 T (/*) 126 311.4 T ( * Prototypes for procedures referenced only in this f) 126 302.4 T (ile:) 417.19 302.4 T ( */) 126 293.4 T (static char * LinkTraceProc _ANSI_ARGS_\050\050ClientData clientData,) 126 275.4 T ( Tcl_Interp *interp, char *name1, char *name2,) 126 266.4 T ( int f) 126 257.4 T (lags\051\051;) 303.95 257.4 T (static char * StringValue _ANSI_ARGS_\050\050Link *linkPtr,) 126 248.4 T ( char *buffer\051\051;) 126 239.4 T 1 F (Figur) 162 220.4 T (e 2.) 183.31 220.4 T 0 F (An example of a header page. Part of the text of the copyright notice has been) 203.03 220.4 T (omitted. The \336le) 162 210.4 T 4 F (engManual/proto.c) 223.91 210.4 T 0 F ( contains a template for a header page.) 315.59 210.4 T 122.4 633.6 118.8 633.6 118.8 547.2 122.4 547.2 4 L 0.5 H 2 Z N 122.4 529.2 118.8 529.2 118.8 507.6 122.4 507.6 4 L N 122.4 716.4 118.8 716.4 118.8 644.4 122.4 644.4 4 L N 122.4 504 118.8 504 118.8 489.6 122.4 489.6 4 L N 122.4 478.8 118.8 478.8 118.8 327.6 122.4 327.6 4 L N 122.4 316.8 118.8 316.8 118.8 237.6 122.4 237.6 4 L N 5 F (Abstract) 78.6 677.12 T (Copyright) 73.1 587.12 T (Revision) 77.1 520.61 T (String) 77.1 511.61 T (Includes) 78.09 493.52 T (Declarations) 61.6 399.92 T (Prototypes) 68.59 273.92 T 0 0 612 792 C FMENDPAGE %%EndPage: "6" 7 %%Page: "7" 7 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (7) 536 42.62 T 0 10 Q (ing header \336le. If additional) 172.8 403.73 T 4 F (#includes) 286.61 403.73 T 0 F ( are needed they should appear in the package\325) 340.58 403.73 T (s) 527.09 403.73 T (internal header \336le or porting header \336le.) 172.8 391.73 T 1 F (Declarations) 172.8 376.73 T 0 F (: any structures used only in this \336le should be declared on the header page) 226.65 376.73 T (\050exported structures must be declared in header \336les\051. In addition, if the \336le de\336nes any) 172.8 364.73 T (static or global variables then they should be declared on the header page. This makes it) 172.8 352.73 T (easy to tell whether or not a \336le has static variables, which is important if the \336le is ever) 172.8 340.73 T -0.05 (used in a multi-threaded environment. Static variables are generally undesirable and should) 172.8 328.73 P (be avoided as much as possible.) 172.8 316.73 T 1 F (Pr) 172.8 301.73 T (ototypes) 183.16 301.73 T 0 F (: procedure prototypes for procedures referenced only in this \336le should appear) 218.7 301.73 T (at the very end of the header page \050prototypes for exported procedures must appear in the) 172.8 289.73 T (package header \336le\051. Use the _ANSI_ARGS_ macro described in Section) 172.8 277.73 T (2.5.) 469.52 277.73 T (Please structure your header pages in exactly the order given above and follow the syntax of) 162 262.73 T (Figure) 162 250.73 T (2 as closely as possible. The \336le) 190.59 250.73 T 4 F (engManual/proto.c) 321.62 250.73 T 0 F ( provides a template for a) 423.57 250.73 T (header page.) 162 238.73 T (Source \336les should never contain) 180 226.73 T 4 F (extern) 315.19 226.73 T 0 F ( statements. Instead, create header \336les to hold) 351.17 226.73 T (the) 162 214.73 T 4 F (extern) 176.71 214.73 T 0 F ( statements and) 212.69 214.73 T 4 F (#include) 276.82 214.73 T 0 F ( the header \336les. This makes code \336les easier to read) 324.79 214.73 T (and makes it easier to manage the) 162 202.73 T 4 F (extern) 299.39 202.73 T 0 F ( statements, since they\325re centralized in) 335.38 202.73 T 4 F (.h) 495.53 202.73 T 0 F ( \336les) 507.52 202.73 T (instead of spread around dozens of code \336les. For example, the internal header \336le for a pack-) 162 190.73 T (age has) 162 178.73 T 4 F (extern) 194.19 178.73 T 0 F ( statements for all of the procedures that are used by multiple \336les within the) 230.17 178.73 T (package but aren\325) 162 166.73 T (t exported outside it.) 232.86 166.73 T 3 F (3.2) 137.31 136.73 T (Procedure headers) 162 136.73 T 0 F (Each page after the \336rst one in a \336le should contain exactly one procedure. The page should) 162 120.73 T -0.33 (begin with a) 162 108.73 P 2 F -0.33 (pr) 212.93 108.73 P -0.33 (ocedur) 221.44 108.73 P -0.33 (e header) 248.83 108.73 P 0 F -0.33 ( that gives overall documentation for the procedure, followed by) 283.19 108.73 P (the declaration and body for the procedure. See Figures 3 and 4 for examples. The header) 162 96.73 T (should contain everything that a caller of the procedure needs to know in order to use the pro-) 162 84.73 T (cedure, and nothing else. It consists of three parts:) 162 72.73 T 108 63 540 720 C 108 410.4 540 720 C 4 9 Q 0 X 0 K (/*) 126 714 T ( *----------------------------------------------------------------------) 126 705 T ( *) 126 696 T ( * Tcl_GetInt --) 126 687 T ( *) 126 678 T ( * Given a string, produce the corresponding integer value.) 126 669 T ( *) 126 660 T ( * Results:) 126 651 T ( * The return value is normally TCL_OK; in this case *intPtr) 126 639 T ( * will be set to the integer value equivalent to string. If) 126 630 T ( * string is improperly formed then TCL_ERROR is returned and) 126 621 T ( * an error message will be left in interp->result.) 126 612 T ( *) 126 603 T ( * Side effects:) 126 594 T ( * None.) 126 585 T ( *) 126 576 T ( *----------------------------------------------------------------------) 126 567 T ( */) 126 558 T (int) 126 540 T (Tcl_GetInt\050interp, string, intPtr\051) 126 531 T -0.06 ( Tcl_Interp *interp; /* Interpreter to use for error reporting. */) 126 522 P ( char *string; /* String containing a \050possibly signed\051) 126 513 T -0.03 ( * integer in a form acceptable to strtol. */) 126 504 P ( int *intPtr; /* Place to store converted result. */) 126 495 T ({) 126 486 T ( ...) 126 477 T (}) 126 468 T 1 F (Figur) 162 449 T (e 3.) 183.31 449 T 0 F (The header comments and declaration for a procedure. The \336le) 203.03 449 T 4 F (engManual/prochead) 162 439 T 0 F ( contains a template for this information.) 259.06 439 T 108 63 540 720 C 0 0 612 792 C FMENDPAGE %%EndPage: "7" 8 %%Page: "8" 8 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (8) 536 42.62 T 1 10 Q (Abstract) 172.8 378.53 T 0 F (: the \336rst lines in the header give the procedure\325) 209.99 378.53 T (s name, followed by a brief) 400.68 378.53 T -0.18 (description of what the procedure does. This should not be a detailed description of how the) 172.8 366.53 P (procedure is implemented, but rather a high-level summary of its overall function. In some) 172.8 354.53 T -0.34 (cases, such as callback procedures, I recommend also describing the conditions under which) 172.8 342.53 P (the procedure is invoked and who calls the procedure, as in Figure) 172.8 330.53 T (4.) 440.65 330.53 T 1 F -0.13 (Results) 172.8 315.53 P 0 F -0.13 (: this portion of the header describes describes how the procedure af) 203.89 315.53 P -0.13 (fects things that) 474.59 315.53 P -0.07 (are immediately visible to its caller) 172.8 303.53 P -0.07 (. This includes the return value of the procedure and any) 312.63 303.53 P (modi\336cations made to the caller) 172.8 291.53 T (\325) 301.42 291.53 T (s variables via pointer ar) 304.2 291.53 T (guments, such as) 402.27 291.53 T 4 F (intPtr) 472.79 291.53 T 0 F ( in) 508.77 291.53 T (Figure) 172.8 279.53 T (3.) 201.39 279.53 T 1 F (Side Effects) 172.8 264.53 T 0 F (: the last part of the header describes changes the procedure makes to its inter-) 223.04 264.53 T -0.15 (nal state, which may not be immediately visible to the caller but will af) 172.8 252.53 P -0.15 (fect later calls to this) 454.96 252.53 P -0.32 (or other procedures. This section should not describe every internal variable modi\336ed by the) 172.8 240.53 P -0.06 (procedure. It should simply provide the sort of information that users of the procedure need) 172.8 228.53 P (in order to use the procedure correctly) 172.8 216.53 T (. See Figure) 324.8 216.53 T (4 for an example.) 375.32 216.53 T -0.08 (The \336le) 162 201.53 P 4 F -0.18 (engManual/prochead) 195.16 201.53 P 0 F -0.08 ( contains a template for a procedure header) 303.1 201.53 P -0.08 (, which you can) 474.52 201.53 P (include from your editor to save typing. Follow the syntax of Figures 3 and 4 exactly \050same) 162 189.53 T (indentation, double-dash after the procedure name, etc.\051.) 162 177.53 T 3 F (3.3) 137.31 147.53 T (Procedure declarations) 162 147.53 T 0 F (The procedure declaration should also follow exactly the syntax in Figures 3 and 4. The \336rst) 162 131.53 T -0.27 (line gives the type of the procedure\325) 162 119.53 P -0.27 (s result. All procedures must be typed: use) 304.15 119.53 P 4 F -0.65 (void) 474.36 119.53 P 0 F -0.27 ( if the pro-) 498.35 119.53 P (cedure returns no result. The second line gives the procedure\325) 162 107.53 T (s name and its ar) 407.92 107.53 T (gument list. If) 474.91 107.53 T (there are many ar) 162 95.53 T (guments, they may spill onto additional lines \050see Sections 5.1 and 5.5 for) 231.47 95.53 T (information about indentation\051. After this come the declarations of ar) 162 83.53 T (gument types, one ar) 438.29 83.53 T (gu-) 521.38 83.53 T (ment per line, indented, with a comment after each ar) 162 71.53 T (gument giving a brief description of the) 375.26 71.53 T 108 63 540 720 C 108 385.2 540 720 C 4 9 Q 0 X 0 K (/*) 126 714 T ( *--------------------------------------------------------------) 126 705 T ( *) 126 696 T ( * ScaleBitmap --) 126 687 T ( *) 126 678 T ( * This procedure is invoked to rescale a bitmap item in a) 126 669 T ( * canvas. It is one of the standard item procedures for) 126 660 T ( * bitmap items, and is invoked by the generic canvas code,) 126 651 T ( * for example during the "scale" widget command.) 126 642 T ( *) 126 633 T ( * Results:) 126 624 T ( * None.) 126 615 T ( *) 126 606 T ( * Side effects:) 126 597 T ( * The item referred to by itemPtr is rescaled so that the) 126 588 T ( * following transformation is applied to all point coordinates:) 126 579 T ( * x' = originX + scaleX*\050x-originX\051) 126 570 T ( * y' = originY + scaleY*\050y-originY\051) 126 561 T ( *) 126 552 T ( *--------------------------------------------------------------) 126 543 T ( */) 126 534 T (static void) 126 516 T (ScaleBitmap\050canvasPtr, itemPtr, originX, originY, scaleX, scaleY\051) 126 507 T ( Tk_Canvas *canvasPtr; /* Canvas containing rectangle. */) 126 498 T ( Tk_Item *itemPtr; /* Rectangle to be scaled. */) 126 489 T -0.48 ( double originX, originY; /* Origin about which to scale rect. */) 126 480 P -0.04 ( double scaleX; /* Amount to scale in X direction. */) 126 471 P -0.04 ( double scaleY; /* Amount to scale in Y direction. */) 126 462 P ({) 126 453 T ( ...) 126 444 T (}) 126 435 T 1 F (Figur) 162 416 T (e 4.) 183.31 416 T 0 F (The header for a procedure with side ef) 203.03 416 T (fects.) 344.36 416 T 108 63 540 720 C 0 0 612 792 C FMENDPAGE %%EndPage: "8" 9 %%Page: "9" 9 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (9) 536 42.62 T 0 10 Q (ar) 162 713.33 T (gument. Every ar) 169.59 713.33 T (gument must be explicitly declared, and every ar) 238.52 713.33 T (gument must have a com-) 433.19 713.33 T (ment.) 162 701.33 T -0.37 (This form for ar) 180 689.33 P -0.37 (gument declarations is the old form that predates ANSI C. It\325) 242.82 689.33 P -0.37 (s important to) 483.09 689.33 P -0.06 (use the old form so that your code will compile on older pre-ANSI compilers. Hopefully there) 162 677.33 P -0.02 (aren\325) 162 665.33 P -0.02 (t too many of these compilers left, and perhaps in a few years we can switch to the ANSI) 182.35 665.33 P (form, but for now let\325) 162 653.33 T (s be safe. Every procedure should also have an ANSI-style prototype) 248.33 653.33 T (either on the \336le\325) 162 641.33 T (s header page or in a header \336le, so this approach still allows full ar) 230.01 641.33 T (gument) 499.36 641.33 T (checking.) 162 629.33 T 3 F (3.4) 137.31 599.33 T (Parameter order) 162 599.33 T 0 F (Procedure parameters may be divided into three categories.) 162 583.33 T 2 F (In) 401.53 583.33 T 0 F ( parameters only pass informa-) 409.85 583.33 T -0 (tion into the procedure \050either directly or by pointing to information that the procedure reads\051.) 162 571.33 P 2 F (Out) 162 559.33 T 0 F ( parameters point to things in the caller) 176.99 559.33 T (\325) 333.65 559.33 T (s memory that the procedure modi\336es.) 336.42 559.33 T 2 F (In-out) 492.71 559.33 T 0 F (parameters do both. Below is a set of rules for deciding on the order of parameters to a proce-) 162 547.33 T (dure:) 162 535.33 T 1 F (1.) 162 520.33 T 0 F (Parameters should normally appear in the order in, in/out, out, except where overridden by) 172.8 520.33 T (the rules below) 172.8 508.33 T (.) 233.22 508.33 T 1 F (2.) 162 493.33 T 0 F -0.2 (If there is a group of procedures, all of which operate on structures of a particular type, such) 172.8 493.33 P (as a hash table, the token for the structure should be the \336rst ar) 172.8 481.33 T (gument to each of the proce-) 422.99 481.33 T (dures.) 172.8 469.33 T 1 F (3.) 162 454.33 T 0 F -0.11 (When two parameters are the address of a callback procedure and a) 172.8 454.33 P 4 F -0.26 (ClientData) 443.44 454.33 P 0 F -0.11 ( value to) 503.41 454.33 P -0.39 (pass to that procedure, the procedure address should appear in the ar) 172.8 442.33 P -0.39 (gument list immediately) 441.48 442.33 P (before the) 172.8 430.33 T 4 F (ClientData) 215.54 430.33 T 0 F (.) 275.5 430.33 T 1 F (4.) 162 415.33 T 0 F (If a callback procedure takes a) 172.8 415.33 T 4 F (ClientData) 297.12 415.33 T 0 F ( ar) 357.09 415.33 T (gument \050and all callbacks should\051, the) 367.17 415.33 T 4 F (ClientData) 172.8 403.33 T 0 F ( ar) 232.77 403.33 T (gument should be the \336rst ar) 242.85 403.33 T (gument to the procedure. T) 356.77 403.33 T (ypically the) 464.6 403.33 T 4 F (Cli-) 514.01 403.33 T -0.27 (entData) 172.8 391.33 P 0 F -0.11 ( is a pointer to the structure managed by the callback, so this is really the same as) 214.78 391.33 P (rule 2.) 172.8 379.33 T 3 F (3.5) 137.31 349.33 T (Procedure bodies) 162 349.33 T 0 F -0.21 (The body of a procedure follows the declaration. See Section) 162 333.33 P -0.21 (5 for the coding conventions that) 406.89 333.33 P (govern procedure bodies. The curly braces enclosing the body should be on separate lines as) 162 321.33 T (shown in Figures 3 and 4.) 162 309.33 T 3 12 Q (4.) 141.2 273 T (Naming conventions) 162 273 T 0 10 Q -0.23 (Choosing names is one of the most important aspects of programming. Good names clarify the) 162 252.33 P -0.22 (function of a program and reduce the need for other documentation. Poor names result in ambi-) 162 240.33 P (guity) 162 228.33 T (, confusion, and error) 181.9 228.33 T (. For example, in the Sprite operating system we spent four months) 267.11 228.33 T (tracking down a subtle problem with the \336le system that caused seemingly random blocks on) 162 216.33 T -0.12 (disk to be overwritten from time to time. It turned out that the same variable name was used in) 162 204.33 P (some places to refer to physical blocks on disk, and in other places to logical blocks in a \336le;) 162 192.33 T (unfortunately) 162 180.33 T (, in one place the variable was accidentally used for the wrong purpose. The bug) 215.2 180.33 T (probably would not have occurred if dif) 162 168.33 T (ferent variable names had been used for the two kinds) 321.14 168.33 T (of block identi\336ers.) 162 156.33 T (This section gives some general principles to follow when choosing names, then lists spe-) 180 144.33 T (ci\336c rules for name syntax, such as capitalization, and \336nally describes how to use package) 162 132.33 T (pre\336xes to clarify the module structure of your code.) 162 120.33 T FMENDPAGE %%EndPage: "9" 10 %%Page: "10" 10 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (10) 532 42.62 T 3 10 Q (4.1) 137.31 713.33 T (General considerations) 162 713.33 T 0 F (The ideal variable name is one that instantly conveys as much information as possible about) 162 697.33 T -0.1 (the purpose of the variable it refers to. When choosing names, play devil\325) 162 685.33 P -0.1 (s advocate with your-) 453.96 685.33 P (self to see if there are ways that a name might be misinterpreted or confused. Here are some) 162 673.33 T (things to consider:) 162 661.33 T 1 F (1.) 162 646.33 T 0 F -0.26 (Are you consistent? Use the same name to refer to the same thing everywhere. For example,) 172.8 646.33 P (in the T) 172.8 634.33 T (cl implementation the name) 203.19 634.33 T 4 F (interp) 317.01 634.33 T 0 F ( is used consistently for pointers to the user) 352.99 634.33 T (-) 526.02 634.33 T -0.31 (visible) 172.8 622.33 P 4 F -0.75 (Tcl_Interp) 201.64 622.33 P 0 F -0.31 ( structure. W) 261.61 622.33 P -0.31 (ithin the code for each widget, a standard name is always) 312.49 622.33 P (used for a pointer to the widget record, such as) 172.8 610.33 T 4 F (butPtr) 362.38 610.33 T 0 F ( in the button widget code and) 398.36 610.33 T 4 F (menuPtr) 172.8 598.33 T 0 F ( in the menu widget code.) 214.78 598.33 T 1 F (2.) 162 583.33 T 0 F (If someone sees the name out of context, will they realize what it stands for) 172.8 583.33 T (, or could they) 474.12 583.33 T (confuse it with something else? For example, in Sprite the procedure for doing byte-swap-) 172.8 571.33 T (ping and other format conversion was originally called) 172.8 559.33 T 4 F (Swap_Buffer) 394.31 559.33 T 0 F (. When I \336rst saw) 459.72 559.33 T (that name I assumed it had something to do with I/O buf) 172.8 547.33 T (fer management, not reformatting.) 398.32 547.33 T (W) 172.8 535.33 T (e subsequently changed the name to) 181.43 535.33 T 4 F (Fmt_Convert) 327.99 535.33 T 0 F (.) 393.96 535.33 T 1 F (3.) 162 520.33 T 0 F -0.35 (Could this name be confused with some other name? For example, it\325) 172.8 520.33 P -0.35 (s probably a mistake to) 446.54 520.33 P -0.3 (have two variables) 172.8 508.33 P 4 F -0.72 (s) 249.34 508.33 P 0 F -0.3 ( and) 255.34 508.33 P 4 F -0.72 (string) 274.17 508.33 P 0 F -0.3 ( in the same procedure, both referring to strings: it will be) 310.14 508.33 P (hard for anyone to remember which is which. Instead, change the names to re\337ect their) 172.8 496.33 T (functions. For example, if the strings are used as source and destination for a copy opera-) 172.8 484.33 T (tion, name them) 172.8 472.33 T 4 F (src) 239.98 472.33 T 0 F ( and) 257.97 472.33 T 4 F (dst) 277.4 472.33 T 0 F (.) 295.39 472.33 T 1 F (4.) 162 457.33 T 0 F (Is the name so generic that it doesn\325) 172.8 457.33 T (t convey any information? The variable) 316.68 457.33 T 4 F (s) 477.11 457.33 T 0 F ( from the pre-) 483.11 457.33 T (vious paragraph is an example of this; changing its name to) 172.8 445.33 T 4 F (src) 412.92 445.33 T 0 F ( makes the name less) 430.91 445.33 T (generic and hence conveys more information.) 172.8 433.33 T 3 F (4.2) 137.31 403.33 T (Basic syntax rules) 162 403.33 T 0 F (Below are some speci\336c rules governing the syntax of names. Please follow the rules exactly) 162 387.33 T (,) 533.03 387.33 T (since they make it possible to determine certain properties of a variable just from its name.) 162 375.33 T 1 F (1.) 162 360.33 T 0 F -0.14 (V) 172.8 360.33 P -0.14 (ariable names always start with a lower) 178.91 360.33 P -0.14 (-case letter) 335.49 360.33 P -0.14 (. Procedure and type names always start) 378.36 360.33 P (with an upper) 172.8 348.33 T (-case letter) 227.56 348.33 T (.) 270.58 348.33 T 4 9 Q (int counter;) 189 334 T (extern char *FindElement\050\051;) 189 324 T (typedef int Boolean;) 189 314 T 1 10 Q (2.) 162 300.33 T 0 F (In multi-word names, the \336rst letter of each trailing word is capitalized. Do not use under-) 172.8 300.33 T -0.34 (scores as separators between the words of a name, except as described in rule 5 below and in) 172.8 288.33 P (Section) 172.8 276.33 T (4.3.) 205.28 276.33 T 4 9 Q (int numWindows;) 189 262 T 1 10 Q (3.) 162 248.33 T 0 F (Any name that refers to a pointer ends in) 172.8 248.33 T 4 F (Ptr) 338.51 248.33 T 0 F (. If the name refers to a pointer to a pointer) 355.95 248.33 T (,) 527.35 248.33 T -0.25 (then it ends in) 172.8 236.33 P 4 F -0.61 (PtrPtr) 230.64 236.33 P 0 F -0.25 (, and so on. There are two exceptions to this rule. The \336rst is for vari-) 266.22 236.33 P (ables that are opaque handles for structures, such as variables of type) 172.8 224.33 T 4 F (Tk_Window) 451.19 224.33 T 0 F (. These) 504.51 224.33 T -0.28 (variables are actually pointers, but they are never dereferenced outside Tk \050clients can never) 172.8 212.33 P (look at the structure they point to except by invoking Tk macros and procedures\051. In this) 172.8 200.33 T (case the) 172.8 188.33 T 4 F (Ptr) 207.21 188.33 T 0 F ( is omitted in variable names. The second exception to the rule is for strings.) 225.2 188.33 T (W) 172.8 176.33 T (e decided in Sprite not to require) 181.43 176.33 T 4 F (Ptr) 314.95 176.33 T 0 F ( suf) 332.94 176.33 T (\336xes for strings, since they are always refer-) 347.47 176.33 T (enced with pointers. However) 172.8 164.33 T (, if a variable holds a pointer to a string pointer) 292.3 164.33 T (, then it must) 479.83 164.33 T (have the) 172.8 152.33 T 4 F (Ptr) 208.88 152.33 T 0 F ( suf) 226.87 152.33 T (\336x \050there\325) 241.4 152.33 T (s just one less level of) 280.54 152.33 T 4 F (Ptr) 371.04 152.33 T 0 F ( for strings than for other structures\051.) 389.03 152.33 T 4 9 Q (TkWindow *winPtr;) 189 138 T (char *name;) 189 128 T (char **namePtr;) 189 118 T 1 10 Q (4.) 162 104.33 T 0 F (V) 172.8 104.33 T (ariables that hold the addresses of procedures should have names ending in) 178.91 104.33 T 4 F (Proc) 481.46 104.33 T 0 F (.) 505.45 104.33 T 4 F (typedefs) 172.8 92.33 T 0 F ( for these variables should also have names ending in) 220.77 92.33 T 4 F (Proc) 436.17 92.33 T 0 F (.) 460.16 92.33 T 4 9 Q (typedef void \050Tk_ImageDeleteProc\051\050ClientData clientData\051;) 189 78 T (Tk_ImageDeleteProc *deleteProc;) 189 68 T FMENDPAGE %%EndPage: "10" 11 %%Page: "11" 11 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (1) 532.3 42.62 T (1) 536 42.62 T 1 10 Q (5.) 162 713.33 T 4 F (#def) 172.8 713.33 T (ine) 196.79 713.33 T 0 F (d constants and macros have names that are all capital letters, except for macros) 214.78 713.33 T (that are used as replacements for procedures, in which case you should follow the naming) 172.8 701.33 T -0.02 (conventions for procedures. If names in all caps contain multiple words, use underscores to) 172.8 689.33 P (separate the words.) 172.8 677.33 T 4 9 Q (#def) 189 663 T (ine NULL 0) 210.57 663 T (#def) 189 653 T (ine BUFFER_SIZE 1024) 210.57 653 T (#def) 189 643 T (ine Min\050a,b\051 \050\050\050a\051 < \050b\051\051 ? \050a\051 : \050b\051\051) 210.57 643 T 1 10 Q (6.) 162 629.33 T 0 F (Names of programs, T) 172.8 629.33 T (cl commands, and keyword ar) 262.03 629.33 T (guments to T) 382.04 629.33 T (cl commands \050such as Tk) 434.09 629.33 T -0.15 (con\336guration options\051 are usually entirely in lower case, in spite of the rules above. The rea-) 172.8 617.33 P -0.15 (son for this rule is that these names are likely to typed interactively) 172.8 605.33 P -0.15 (, and I thought that using) 438.47 605.33 P (all lower case would make it easier to type them. In retrospect I\325m not sure this was a good) 172.8 593.33 T (idea; in any case, T) 172.8 581.33 T (cl procedure and variable names should follow the same rules as C pro-) 249.54 581.33 T (cedures and variables.) 172.8 569.33 T 3 F (4.3) 137.31 539.33 T (Names re\337ect package structure) 162 539.33 T 0 F (Names that are exported outside a single \336le must include the package pre\336x in order to make) 162 523.33 T (sure that they don\325) 162 511.33 T (t con\337ict with global names de\336ned in other packages. The following rules) 236.49 511.33 T (de\336ne how to use package pre\336xes in names:) 162 499.33 T 1 F (1.) 162 484.33 T 0 F -0.25 (If a variable or procedure or type is exported by its package, the \336rst letters of its name must) 172.8 484.33 P (consist of the package pre\336x followed by an underscore. Only the \336rst letter of the pre\336x is) 172.8 472.33 T -0 (ever capitalized, and it is subject to the capitalization rules from Section) 172.8 460.33 P -0 (4.2. The \336rst letter) 463.39 460.33 P (after the pre\336x is always capitalized. The \336rst example below shows an exported variable,) 172.8 448.33 T (and the second shows an exported type and exported procedure.) 172.8 436.33 T 4 9 Q (extern int tk_numMainWindows;) 189 422 T (extern Tcl_Interp *Tcl_CreateInterp\050void\051;) 189 412 T 1 10 Q (2.) 162 398.33 T 0 F -0.35 (If a module contains several \336les, and if a name is used in several of those \336les but isn\325) 172.8 398.33 P -0.35 (t used) 514.61 398.33 P (outside the package, then the name must have the package pre\336x but no underscore. The) 172.8 386.33 T -0.24 (pre\336x guarantees that the name won\325) 172.8 374.33 P -0.24 (t con\337ict with a similar name from a dif) 319.38 374.33 P -0.24 (ferent package;) 476.65 374.33 P (the missing underscore indicates that the name is private to the package.) 172.8 362.33 T 4 9 Q (extern void TkEventDeadWindow\050TkWindow *winPtr\051;) 189 348 T 1 10 Q (3.) 162 334.33 T 0 F (If a name is only used within a single procedure or \336le, then it need not have the module) 172.8 334.33 T (pre\336x. T) 172.8 322.33 T (o avoid con\337icts with similar names in other \336les, variables and procedures) 206.52 322.33 T (declared outside procedures must always be declared) 172.8 310.33 T 4 F (static) 387.34 310.33 T 0 F ( if they have no module pre-) 423.32 310.33 T (\336x.) 172.8 298.33 T 4 9 Q (static int initialized;) 189 284 T 3 10 Q (4.4) 137.31 255.33 T (Standard names) 162 255.33 T 0 F (The following variable names are used consistently throughout T) 162 239.33 T (cl and Tk. Please use these) 421.68 239.33 T (names for the given purposes in any code you write, and don\325) 162 227.33 T (t use the names for other pur-) 408.3 227.33 T (poses.) 162 215.33 T 4 F (clientData) 189 200.33 T 0 F (Used for variables of type) 262.8 200.33 T 4 F (ClientData) 369.1 200.33 T 0 F (, which are associ-) 429.07 200.33 T (ated with callback procedures.) 262.8 190.33 T 4 F (interp) 189 177.33 T 0 F (Used for variables of type) 262.8 177.33 T 4 F (Tcl_Interp) 369.1 177.33 T 0 F (: these are the) 429.07 177.33 T (\050mostly\051 opaque handles for interpreters that are given to T) 262.8 167.33 T (cl) 498.31 167.33 T (clients. These variables should really have a) 262.8 157.33 T 4 F (Ptr) 441.55 157.33 T 0 F ( extension,) 459.54 157.33 T (but the name was chosen at a time when interpreters were) 262.8 147.33 T (totally opaque to clients.) 262.8 137.33 T 4 F (iPtr) 189 124.33 T 0 F (Used for variables of type) 262.8 124.33 T 4 F (Interp *) 369.1 124.33 T 0 F (, which are pointers to) 417.08 124.33 T (T) 262.8 114.33 T (cl\325) 268.21 114.33 T (s internal structures for interpreters. T) 278.2 114.33 T (cl procedures often) 429.05 114.33 T (have an ar) 262.8 104.33 T (gument named) 303.69 104.33 T 4 F (interp) 365.31 104.33 T 0 F (, which is copied into a) 401.29 104.33 T (local variable named) 262.8 94.33 T 4 F (iPtr) 348.56 94.33 T 0 F ( in order to access the contents of) 372.55 94.33 T (the interpreter) 262.8 84.33 T (.) 318.59 84.33 T FMENDPAGE %%EndPage: "11" 12 %%Page: "12" 12 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (12) 532 42.62 T 3 12 Q (5.) 141.2 600 T (Low-level coding conventions) 162 600 T 0 10 Q -0.06 (This section describes several low-level syntactic rules for writing C code. The reason for hav-) 162 579.33 P -0.26 (ing these rules is not because they\325re better than all other ways of structuring code, but in order) 162 567.33 P (to make all our code look the same.) 162 555.33 T 3 F (5.1) 137.31 525.33 T (Indents are 4 spaces) 162 525.33 T 0 F (Each level of indentation should be four spaces. There are ways to set 4-space indents in all) 162 509.33 T (editors that I know of. Be sure that your editor really uses four spaces for the indent, rather) 162 497.33 T (than just displaying tabs as four spaces wide; if you use the latter approach then the indents) 162 485.33 T (will appear eight spaces wide in other editors.) 162 473.33 T 3 F (5.2) 137.31 443.33 T (Code comments occupy full lines) 162 443.33 T 0 F (Comments that document code \050as opposed to declarations\051 should occupy full lines, rather) 162 427.33 T (than being tacked onto the ends of lines containing code. The reason for this is that side-by-) 162 415.33 T (side comments are hard to see, particularly if neighboring statements are long enough to over-) 162 403.33 T (lap the side-by-side comments. Comments must have exactly the structure shown in Figure) 162 391.33 T (5,) 528.99 391.33 T -0.23 (including a leading) 162 379.33 P 4 F -0.56 (/*) 240.41 379.33 P 0 F -0.23 ( line, a trailing) 252.41 379.33 P 4 F -0.56 (*/) 312.26 379.33 P 0 F -0.23 ( line, and additional blank lines above and below) 324.26 379.33 P -0.23 (. The) 517.43 379.33 P -0.29 (leading blank line can be omitted if the comment is at the beginning of a block, as is the case in) 162 367.33 P (the second comment in Figure) 162 355.33 T (5. Each comment should be indented to the same level as the) 285.53 355.33 T (surrounding code. Use proper English in comments: write complete sentences, capitalize the) 162 343.33 T (\336rst word of each sentence, and so on.) 162 331.33 T 3 F (5.3) 137.31 301.33 T (Declaration comments are side-by-side) 162 301.33 T 0 F (When documenting the ar) 162 285.33 T (guments for procedures and the members of structures, place the) 265.35 285.33 T -0.26 (comments on the same lines as the declarations. Figures 3 and 4 show comments for procedure) 162 273.33 P (ar) 162 261.33 T (guments and Figure) 169.59 261.33 T (6 shows a simple structure declaration. The format for comments is the) 251.48 261.33 T (same in both cases. Place the comments to the right of the declarations, with all the left edges) 162 249.33 T (of all the comments lined up. When a comment requires more than one line, indent the addi-) 162 237.33 T -0.18 (tional lines to the same level as the \336rst line, with the closing) 162 225.33 P 4 F -0.44 (*/) 406.14 225.33 P 0 F -0.18 ( on the same line as the end of) 418.13 225.33 P (the text. For structure declarations it is usually useful to have a block of comments preceding) 162 213.33 T (the declaration, as in Figure) 162 201.33 T (6. This comments before the declaration use the format given in) 275.81 201.33 T (Section) 162 189.33 T (5.2.) 194.48 189.33 T 3 F (5.4) 137.31 159.33 T (Curly braces: { goes at the end of a line) 162 159.33 T 0 F (Open curly braces should not appear on lines by themselves. Instead, they should be placed at) 162 143.33 T -0.16 (the end of the preceding line. Close curly braces always appear as the \336rst non-blank character) 162 131.33 P (on a line. Figure) 162 119.33 T (5 shows how to use curly braces in statements such as) 230.01 119.33 T 4 F (if) 448.47 119.33 T 0 F ( and) 460.47 119.33 T 4 F (while) 479.89 119.33 T 0 F (, and) 509.88 119.33 T (Figure) 162 107.33 T (6 shows how curly braces should be used in structure declarations. If an) 190.59 107.33 T 4 F (if) 480.38 107.33 T 0 F ( statement) 492.37 107.33 T (has an) 162 95.33 T 4 F (else) 189.76 95.33 T 0 F ( clause then) 213.74 95.33 T 4 F (else) 263.42 95.33 T 0 F ( appears on the same line as the preceding) 287.41 95.33 T 4 F (}) 458.11 95.33 T 0 F ( and the following) 464.1 95.33 T 4 F -0.69 ({) 162 83.33 P 0 F -0.29 (. Close curly braces are indented to the same level as the outer code, i.e., four spaces less than) 168 83.33 P (the statements they enclose.) 162 71.33 T 4 F (nextPtr) 189 711.33 T 0 F -0.35 (A \336eld with this name is used in structures to point to the next) 262.8 711.33 P (structure in a linked list. This is usally the last \336eld of the) 262.8 701.33 T (structure.) 262.8 691.33 T 4 F (tkwin) 189 678.33 T 0 F (Used for variables of type) 262.8 678.33 T 4 F (Tk_Window) 369.1 678.33 T 0 F (, which are opaque) 422.42 678.33 T (handles for the window structures managed by Tk.) 262.8 668.33 T 4 F (winPtr) 189 655.33 T 0 F -0.14 (Used for variables of type) 262.8 655.33 P 4 F -0.34 (TkWindow *) 368.4 655.33 P 0 F -0.14 (, which are pointers) 428.03 655.33 P (to Tk\325) 262.8 645.33 T (s internal structures for windows. Tk procedures often) 286.96 645.33 T (take an ar) 262.8 635.33 T (gument named) 301.47 635.33 T 4 F (tkwin) 363.09 635.33 T 0 F ( and immediately copy the) 393.08 635.33 T (ar) 262.8 625.33 T (gument into a local variable named) 270.39 625.33 T 4 F (winPtr) 413.62 625.33 T 0 F ( in order to) 449.6 625.33 T (access the contents of the window structure.) 262.8 615.33 T FMENDPAGE %%EndPage: "12" 13 %%Page: "13" 13 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (13) 532 42.62 T 0 10 Q (The only case where a { appears on a line by itself is the initial { for the body of a proce-) 180 234.53 T (dure \050see Figures 3 and 4\051.) 162 222.53 T -0.12 (Always use curly braces around compound statements, even if there is only one statement) 180 210.53 P (in the block. Thus you shouldn\325) 162 198.53 T (t write code like) 288.97 198.53 T 4 9 Q (if \050f) 189 184.2 T (ilePtr->numLines == 0\051 return -1;) 215.96 184.2 T 0 10 Q (but rather) 162 170.53 T 4 9 Q (if \050f) 189 156.2 T (ilePtr->numLines == 0\051 {) 215.96 156.2 T ( return -1;) 189 146.2 T (}) 189 136.2 T 0 10 Q (This approach makes code less dense, but it avoids potential mistakes when adding additional) 162 122.53 T -0.13 (lines to an existing single-statement block. It also makes it easier to set breakpoints in a debug-) 162 110.53 P (ger) 162 98.53 T (, since it guarantees that each statement on is on a separate line and can be named individu-) 174.36 98.53 T (ally) 162 86.53 T (.) 176.34 86.53 T 108 63 540 720 C 108 442.8 540 720 C 4 9 Q 0 X 0 K ( if \050searchPtr->linesLeft <= 0\051 {) 126 714 T ( goto searchOver;) 126 705 T ( }) 126 696 T ( /*) 126 678 T ( * The outermost loop iterates over lines that may potentially contain) 126 669 T ( * a relevant tag transition, starting from the current segment in) 126 660 T ( * the current line.) 126 651 T ( */) 126 642 T ( segPtr = searchPtr->nextPtr;) 126 624 T ( while \0501\051 {) 126 615 T ( /*) 126 606 T ( * Check for more tags on the current line.) 126 597 T ( */) 126 588 T ( for \050 ; segPtr != NULL; segPtr = segPtr->nextPtr\051 {) 126 567 T ( if \050segPtr == searchPtr->lastPtr\051 {) 126 558 T ( goto searchOver;) 126 549 T ( }) 126 540 T ( ...) 126 531 T ( }) 126 522 T ( }) 126 513 T 1 F -0.1 (Figur) 162 494 P -0.1 (e 5.) 183.31 494 P 0 F -0.1 (Comments in code have the form shown above, using full lines, with lined-up stars,) 202.62 494 P (the) 162 484 T 4 F (/*) 175.23 484 T 0 F ( and) 186.01 484 T 4 F (*/) 203.49 484 T 0 F ( symbols on separate lines, and blank separator lines around each comment) 214.27 484 T (\050except that the leading blank line can be omitted if the comment is at the beginning of a code) 162 474 T (block\051.) 162 464 T 108 63 540 720 C 0 0 612 792 C 108 63 540 720 C 108 241.2 540 442.8 C 4 9 Q 0 X 0 K (/*) 126 436.8 T ( * The following structure def) 126 427.8 T (ines a variable trace, which is used to) 287.77 427.8 T ( * invoke a specif) 126 418.8 T (ic C procedure whenever certain operations are performed) 223.06 418.8 T ( * on a variable.) 126 409.8 T ( */) 126 400.8 T (typedef struct VarTrace {) 126 382.8 T ( Tcl_VarTraceProc *traceProc;/* Procedure to call when operations given) 126 373.8 T ( * by f) 126 364.8 T (lags are performed on variable. */) 336.31 364.8 T ( ClientData clientData; /* Argument to pass to proc. */) 126 355.8 T ( int f) 126 346.8 T (lags; /* What events the trace procedure is) 174.53 346.8 T ( * interested in: OR-ed combination of) 126 337.8 T ( * TCL_TRACE_READS, TCL_TRACE_WRITES, and) 126 328.8 T ( * TCL_TRACE_UNSETS. */) 126 319.8 T ( struct VarTrace *nextPtr; /* Next in list of traces associated with) 126 310.8 T ( * a particular variable. */) 126 301.8 T (} VarTrace;) 126 292.8 T 1 F (Figur) 162 273.8 T (e 6.) 183.31 273.8 T 0 F (Use side-by-side comments when declaring structure members and procedure) 203.03 273.8 T (ar) 162 263.8 T (guments.) 168.82 263.8 T 108 63 540 720 C 0 0 612 792 C FMENDPAGE %%EndPage: "13" 14 %%Page: "14" 14 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (14) 532 42.62 T 0 10 Q (There is one exception to the rule about enclosing blocks in) 180 572.93 T 4 F ({}) 420.67 572.93 T 0 F (. For) 432.66 572.93 T 4 F (if) 454.04 572.93 T 0 F ( statements with) 466.03 572.93 T (cascaded) 162 560.93 T 4 F (else) 200.57 560.93 T (if) 227.05 560.93 T 0 F ( clauses, you may use a form like the following:) 239.05 560.93 T 4 9 Q (if \050strcmp\050argv[1], "delete"\051 == 0\051 {) 189 546.6 T ( ...) 189 536.6 T (} else if \050strcmp\050argv[1], "get"\051 == 0\051 {) 189 526.6 T ( ...) 189 516.6 T (} else if \050strcmp\050argv[1], "set"\051 == 0\051 {) 189 506.6 T ( ...) 189 496.6 T (} else {) 189 486.6 T ( ...) 189 476.6 T (}) 189 466.6 T 3 10 Q (5.5) 137.31 437.93 T (Continuation lines are indented 8 spaces) 162 437.93 T 0 F (Y) 162 421.93 T (ou should use continuation lines to make sure that no single line exceeds 80 characters in) 168.22 421.93 T (length. Continuation lines should be indented 8 spaces so that they won\325) 162 409.93 T (t be confused with an) 451.09 409.93 T (immediately-following nested block \050see Figure) 162 397.93 T (7\051. Pick clean places to break your lines for) 356.59 397.93 T -0.23 (continuation, so that the continuation doesn\325) 162 385.93 P -0.23 (t obscure the structure of the statement. For exam-) 338.34 385.93 P -0.11 (ple, if a procedure call requires continuation lines, make sure that each ar) 162 373.93 P -0.11 (gument is on a single) 453.08 373.93 P -0.1 (line. If the test for an) 162 361.93 P 4 F -0.25 (if) 247.7 361.93 P 0 F -0.1 ( or) 259.7 361.93 P 4 F -0.25 (while) 272.81 361.93 P 0 F -0.1 ( command spans lines, try to make each line have the same) 302.8 361.93 P (nesting level of parentheses if possible. I try to start each continuation line with an operator) 162 349.93 T (such as) 162 337.93 T 4 F (*) 193.64 337.93 T 0 F (,) 199.64 337.93 T 4 F (&&) 204.64 337.93 T 0 F (, or) 216.63 337.93 T 4 F (||) 232.45 337.93 T 0 F (; this makes it clear that the line is a continuation, since a new statement) 244.45 337.93 T (would never start with such an operator) 162 325.93 T (.) 319.66 325.93 T 3 F (5.6) 137.31 295.93 T (A) 162 295.93 T (void macros except for simple things) 168.85 295.93 T 4 F -1.01 (#def) 162 279.93 P -1.01 (ine) 185.99 279.93 P 0 F -0.42 ( statements provide a \336ne mechanism for specifying constants symbolically) 203.98 279.93 P -0.42 (, and you) 501.84 279.93 P (should always use them instead of embedding speci\336c numbers in your code. However) 162 267.93 T (, it is) 509.41 267.93 T -0.39 (generally a bad idea to use macros for complex operations; procedures are almost always better) 162 255.93 P (\050for example, you can set breakpoints inside procedures but not in the middle of macros\051. The) 162 243.93 T (only time that it is OK to use) 162 231.93 T 4 F (#def) 280.27 231.93 T (ine) 304.26 231.93 T 0 F (\325) 322.25 231.93 T (s for complex operations is if the operations are criti-) 325.03 231.93 T (cal to performance and there is no other way to get the performance \050have you measured the) 162 219.93 T (performance before and after to be sure it matters?\051.) 162 207.93 T (When de\336ning macros, remember always to enclose the ar) 180 195.93 T (guments in parentheses:) 413.8 195.93 T 4 9 Q (#def) 189 181.6 T (ine Min\050a,b\051 \050\050\050a\051 < \050b\051\051 ? \050a\051 : \050b\051\051) 210.57 181.6 T 0 10 Q -0.03 (Otherwise, if the macro is invoked with a complex ar) 162 167.93 P -0.03 (gument such as) 374.22 167.93 P 4 F -0.06 (a*b) 438.27 167.93 P 0 F -0.03 ( or) 456.26 167.93 P 4 F -0.06 (small||red) 469.53 167.93 P 0 F -0.03 ( it) 529.49 167.93 P (may result in a parse error or) 162 155.93 T (, even worse, an unintended result that is dif) 277.06 155.93 T (\336cult to debug.) 453.42 155.93 T 3 12 Q (6.) 141.2 119.6 T (Documenting code) 162 119.6 T 0 10 Q (The purpose of documentation is to save time and reduce errors. Documentation is typically) 162 98.93 T (used for two purposes. First, people will read the documentation to \336nd out how to use your) 162 86.93 T (code. For example, they will read procedure headers to learn how to call the procedures. Ide-) 162 74.93 T 108 63 540 720 C 108 579.6 536.4 720 C 4 9 Q 0 X 0 K (if \050\050linePtr->position.lineIndex > position.lineIndex\051) 126 714 T ( || \050\050linePtr->position.lineIndex == position.lineIndex\051) 126 705 T ( && \050\050linePtr->position.charIndex + linePtr->length\051) 126 696 T ( > position.charIndex\051\051\051 {) 126 687 T ( return;) 126 678 T (}) 126 669 T (line = Mx_GetLine\050newPtr->f) 126 660 T (ileInfoPtr->f) 271.6 660 T (ile,) 341.7 660 T ( linePtr->position.lineIndex, \050int *\051 NULL\051;) 126 651 T (XDrawImageString\050mxwPtr->display, mxwPtr->f) 126 642 T (ileWindow,) 357.88 642 T ( mxwPtr->textGc, x, y + mxwPtr->fontPtr->ascent,) 126 633 T ( control, 2\051;) 126 624 T 1 F (Figur) 162 605 T (e 7.) 183.31 605 T 0 F (Continuation lines are indented 8 spaces.) 203.03 605 T 108 63 540 720 C 0 0 612 792 C FMENDPAGE %%EndPage: "14" 15 %%Page: "15" 15 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (15) 532 42.62 T 0 10 Q -0.33 (ally) 162 713.33 P -0.33 (, people should have to learn as little as possible about your code in order to use it correctly) 176.34 713.33 P -0.33 (.) 535.33 713.33 P -0.38 (Second, people will read the documentation to \336nd out how your code works internally) 162 701.33 P -0.38 (, so they) 505.05 701.33 P (can \336x bugs or add new features; again, good documentation will allow them to make their) 162 689.33 T (\336xes or enhancements while learning the minimum possible about your code. More documen-) 162 677.33 T (tation isn\325) 162 665.33 T (t necessarily better: wading through pages of documentation may not be any easier) 202.08 665.33 T (than deciphering the code. T) 162 653.33 T (ry to pick out the most important things that will help people to) 275.73 653.33 T (understand your code and focus on these in your documentation.) 162 641.33 T 3 F (6.1) 137.31 611.33 T (Document things with wide impact) 162 611.33 T 0 F (The most important things to document are those that af) 162 595.33 T (fect many dif) 385.85 595.33 T (ferent pieces of a pro-) 438.96 595.33 T -0.14 (gram. Thus it is essential that every procedure interface, every structure declaration, and every) 162 583.33 P -0.32 (global variable be documented clearly) 162 571.33 P -0.32 (. If you haven\325) 312.74 571.33 P -0.32 (t documented one of these things it will be) 370.45 571.33 P (necessary to look at all the uses of the thing to \336gure out how it\325) 162 559.33 T (s supposed to work; this will) 418.51 559.33 T (be time-consuming and error) 162 547.33 T (-prone.) 277.55 547.33 T (On the other hand, things with only local impact may not need much documentation. For) 180 535.33 T (example, in short procedures I don\325) 162 523.33 T (t usually have comments explaining the local variables. If) 303.93 523.33 T (the overall function of the procedure has been explained, and if there isn\325) 162 511.33 T (t much code in the) 454.64 511.33 T (procedure, and if the variables have meaningful names, then it will be easy to \336gure out how) 162 499.33 T -0 (they are used. On the other hand, for long procedures with many variables I usually document) 162 487.33 P -0.04 (the key variables. Similarly) 162 475.33 P -0.04 (, when I write short procedures I don\325) 271.15 475.33 P -0.04 (t usually have any comments) 421.67 475.33 P (in the procedure\325) 162 463.33 T (s code: the procedure header provides enough information to \336gure out what) 229.72 463.33 T (is going on. For long procedures I place a comment block before each major piece of the pro-) 162 451.33 T (cedure to clarify the overall \337ow through the procedure.) 162 439.33 T 3 F (6.2) 137.31 409.33 T (Don\325t just repeat what\325) 162 409.33 T (s in the code) 268.81 409.33 T 0 F (The most common mistake I see in documentation \050besides it not being there at all\051 is that it) 162 393.33 T -0.38 (repeats what is already obvious from the code, such as this trivial \050but exasperatingly common\051) 162 381.33 P (example:) 162 369.33 T 4 9 Q (/*) 189 355 T ( * Increment i.) 189 345 T ( */) 189 335 T (i += 1;) 189 315 T 0 10 Q -0.29 (Documentation should provide higher) 162 301.33 P -0.29 (-level information about the overall function of the code,) 312.78 301.33 P -0.22 (helping readers to understand what a complex collection of statements really means. For exam-) 162 289.33 P (ple, the comment) 162 277.33 T 4 9 Q (/*) 189 263 T ( * Probe into the hash table to see if the symbol exists.) 189 253 T ( */) 189 243 T 0 10 Q (is likely to be much more helpful than) 162 229.33 T 4 9 Q (/*) 189 215 T ( * Mask off all but the lower 8 bits of x, then index into table) 189 205 T ( * t, then traverse the list looking for a character string) 189 195 T ( * identical to s.) 189 185 T ( */) 189 175 T 0 10 Q (Everything in this second comment is probably obvious from the code that follows it.) 162 161.33 T (Another thing to consider in your comments is word choice. Use dif) 180 149.33 T (ferent words in the) 451.86 149.33 T (comments than the words that appear in variable or procedure names. For example, the com-) 162 137.33 T (ment) 162 125.33 T 4 9 Q (/*) 189 111 T ( * VmMapPage --) 189 101 T ( *) 189 91 T ( * Map a page.) 189 81 T ( * ...) 189 71 T FMENDPAGE %%EndPage: "15" 16 %%Page: "16" 16 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (16) 532 42.62 T 0 10 Q (which appears in the header for the Sprite procedure VmMapPage, doesn\325) 162 713.33 T (t provide any new) 457.97 713.33 T -0.02 (information. Everything in the comment is already obvious from the procedure\325) 162 701.33 P -0.02 (s name. Here) 482.64 701.33 P (is a much more useful comment:) 162 689.33 T 4 9 Q (/*) 189 675 T ( * VmMapPage --) 189 665 T ( *) 189 655 T ( * Make the given physical page addressable in the kernel\325s) 189 645 T ( * virtual address space. This procedure is used when the) 189 635 T ( * kernel needs to access a user\325s page.) 189 625 T ( * ...) 189 615 T 0 10 Q (This comment tells) 162 601.33 T 2 F (why) 241.13 601.33 T 0 F ( you might want to use the procedure, in addition to) 257.23 601.33 T 2 F (what) 466.54 601.33 T 0 F ( it does,) 485.98 601.33 T (which makes the comment much more useful.) 162 589.33 T 3 F (6.3) 137.31 559.33 T (Document each thing in exactly one place) 162 559.33 T 0 F -0.28 (Systems evolve over time. If something is documented in several places, it will be hard to keep) 162 543.33 P (the documentation up to date as the system changes. Instead, try to document each major) 162 531.33 T -0.23 (design decision in exactly one place, as near as possible to the code that implements the design) 162 519.33 P (decision. For example, put the documentation for each structure right next to the declaration) 162 507.33 T -0.32 (for the structure, including the general rules for how the structure is used. Y) 162 495.33 P -0.32 (ou need not explain) 460.22 495.33 P (the \336elds of the structure again in the code that uses the structure; people can always refer) 162 483.33 T -0.18 (back to the structure declaration for this. The principal documentation for each procedure goes) 162 471.33 P (in the procedure header) 162 459.33 T (. There\325) 255.53 459.33 T (s no need to repeat this information again in the body of the) 286.61 459.33 T -0.11 (procedure \050but you might have additional comments in the procedure body to \336ll in details not) 162 447.33 P (described in the procedure header\051. If a library procedure is documented thoroughly in a man-) 162 435.33 T -0.17 (ual entry) 162 423.33 P -0.17 (, then I may make the header for the procedure very terse, simply referring to the man-) 196.43 423.33 P (ual entry) 162 411.33 T (. For example, I use this terse form in the headers for all T) 196.6 411.33 T (cl command procedures,) 428.78 411.33 T (since there is a separate manual entry describing each command.) 162 399.33 T (The other side of this coin is that every major design decision needs to be documented) 180 387.33 T 2 F (at) 527.54 387.33 T -0.15 (least) 162 375.33 P 0 F -0.15 ( once. If a design decision is used in many places, it may be hard to pick a central place to) 180.88 375.33 P (document it. T) 162 363.33 T (ry to \336nd a data structure or key procedure where you can place the main body) 220.23 363.33 T -0.17 (of comments; then reference this body in the other places where the decision is used. If all else) 162 351.33 P -0.22 (fails, add a block of comments to the header page of one of the \336les implementing the decision.) 162 339.33 P 3 F (6.4) 137.31 309.33 T (W) 162 309.33 T (rite clean code) 171.26 309.33 T 0 F (The best way to produce a well-documented system is to write clean and simple code. This) 162 293.33 T (way there won\325) 162 281.33 T (t be much to document. If code is clean, it means that there are a few simple) 223.99 281.33 T (ideas that explain its operation; all you have to do is to document those key ideas. When writ-) 162 269.33 T (ing code, ask yourself if there is a simple concept behind the code. If not, perhaps you should) 162 257.33 T (rethink the code. If it takes a lot of documentation to explain a piece of code, it is a sign that) 162 245.33 T (you haven\325) 162 233.33 T (t found an elegant solution to the problem.) 206.51 233.33 T 3 F (6.5) 137.31 203.33 T (Document as you go) 162 203.33 T 0 F (It is extremely important to write the documentation as you write the code. It\325) 162 187.33 T (s very tempting) 472.35 187.33 T (to put of) 162 175.33 T (f the documentation until the end; after all, the code will change, so why waste time) 195.69 175.33 T (writing documentation now when you\325ll have to change it later? The problem is that the end) 162 163.33 T -0.22 (never comes \320 there is always more code to write. Also, the more undocumented code that you) 162 151.33 P (accumulate, the harder it is to work up the ener) 162 139.33 T (gy to document it. So, you just write more) 350.01 139.33 T -0.23 (undocumented code. I\325ve seen many people start a project fully intending to go back at the end) 162 127.33 P (and write all the documentation, but I\325ve never seen anyone actually do it.) 162 115.33 T (If you do the documentation as you go, it won\325) 180 103.33 T (t add much to your coding time and you) 367.48 103.33 T -0.1 (won\325) 162 91.33 P -0.1 (t have to worry about doing it later) 182.36 91.33 P -0.1 (. Also, the best time to document code is when the key) 320.2 91.33 P (ideas are fresh in your mind, which is when you\325re \336rst writing the code. When I write new) 162 79.33 T (code, I write all of the header comments for a group of procedures before I \336ll in any of the) 162 67.33 T FMENDPAGE %%EndPage: "16" 17 %%Page: "17" 17 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (17) 532 42.62 T 0 10 Q -0.36 (bodies of the procedures. This way I can think about the overall structure and how the pieces \336t) 162 713.33 P (together before getting bogged down in the details of individual procedures.) 162 701.33 T 3 F (6.6) 137.31 671.33 T (Document tricky situations) 162 671.33 T 0 F (If code is non-obvious, meaning that its structure and correctness depend on information that) 162 655.33 T -0.16 (won\325) 162 643.33 P -0.16 (t be obvious to someone reading it for the \336rst time, be sure to document the non-obvious) 182.36 643.33 P -0.18 (information. One good indicator of a tricky situation is a bug. If you discover a subtle property) 162 631.33 P (of your program while \336xing a bug, be sure to add a comment explaining the problem and its) 162 619.33 T (solution. Of course, it\325) 162 607.33 T (s even better if you can \336x the bug in a way that eliminates the subtle) 251.67 607.33 T (behavior) 162 595.33 T (, but this isn\325) 196.57 595.33 T (t always possible.) 248.59 595.33 T 3 12 Q (7.) 141.2 559 T (T) 162 559 T (esting) 168.44 559 T 0 10 Q -0.13 (One of the environments where T) 162 538.33 P -0.13 (cl works best is for testing. If all the functionality of an appli-) 295.29 538.33 P (cation is available as T) 162 526.33 T (cl commands, you should be able to write T) 252.9 526.33 T (cl scripts that exercise the) 427.36 526.33 T -0.01 (application and verify that it behaves correctly) 162 514.33 P -0.01 (. For example, T) 347.25 514.33 P -0.01 (cl contains a lar) 412.85 514.33 P -0.01 (ge suite of tests) 475.64 514.33 P -0.32 (that exercise nearly all of the T) 162 502.33 P -0.32 (cl functionality) 283.74 502.33 P -0.32 (. Whenever you write new code you should write) 343.57 502.33 P (T) 162 490.33 T (cl test scripts to go with that code and save the tests in \336les so that they can be re-run later) 167.41 490.33 T (.) 526.61 490.33 T (W) 162 478.33 T (riting test scripts isn\325) 171.04 478.33 T (t as tedious as it may sound. If you\325re developing your code carefully) 254.98 478.33 T (you\325re already doing a lot of testing; all you need to do is type your test cases into a script \336le) 162 466.33 T (where they can be re-used, rather than typing them interactively where they vanish into the) 162 454.33 T (void after they\325re run.) 162 442.33 T 3 F (7.1) 137.31 412.33 T (Basics) 162 412.33 T 0 F -0.19 (T) 162 396.33 P -0.19 (ests should be or) 167.41 396.33 P -0.19 (ganized into script \336les, where each \336le contains a collection of related tests.) 233.55 396.33 P -0 (Individual tests should be based on the procedure) 162 384.33 P 4 F -0.01 (test) 361.83 384.33 P 0 F -0 (, just like in the T) 385.82 384.33 P -0 (cl and Tk test suites.) 455.62 384.33 P (Here are two examples:) 162 372.33 T 4 9 Q (test expr-3.1 {f) 189 358 T (loating-point operators} {) 275.28 358 T ( expr 2.3*.6) 189 348 T (} 1.38) 189 338 T (test expr-3.2 {f) 189 328 T (loating-point operators} {) 275.28 328 T ( list [catch {expr 2.3/0} msg] $msg) 189 318 T (} {1 {divide by zero}}) 189 308 T 4 10 Q -0.17 (test) 162 294.33 P 0 F -0.07 ( is a procedure de\336ned in a script \336le named) 185.99 294.33 P 4 F -0.17 (defs) 364.58 294.33 P 0 F -0.07 (, which is) 388.56 294.33 P 4 F -0.17 (source) 429.43 294.33 P 0 F -0.07 (d by each test \336le.) 465.41 294.33 P 4 F (test) 162 282.33 T 0 F ( takes four ar) 185.99 282.33 T (guments: a test identi\336er) 238.26 282.33 T (, a string describing the test, a test script, and the) 336.41 282.33 T (expected result of the script.) 162 270.33 T 4 F (test) 277.47 270.33 T 0 F ( evaluates the script and checks to be sure that it produces) 301.45 270.33 T (the expected result. If not, it prints a message like the following:) 162 258.33 T 4 9 Q (==== expr-3.1 f) 189 244 T (loating-point operators) 269.89 244 T (==== Contents of test case:) 189 234 T ( expr 2.3*.6) 189 214 T (==== Result was:) 189 194 T (1.39) 189 184 T (---- Result should have been:) 189 174 T (1.38) 189 164 T (---- expr-2.1 FAILED) 189 154 T 0 10 Q (T) 162 140.33 T (o run a set of tests, you start up the application and) 167.41 140.33 T 4 F (source) 373.1 140.33 T 0 F ( a test \336le. If all goes well no) 409.08 140.33 T (messages appear; if errors are detected, a message is printed for each one.) 162 128.33 T (The test identi\336er) 180 116.33 T (, such as) 250.11 116.33 T 4 F (expr-3.1) 286.75 116.33 T 0 F (, is printed when errors occur) 334.73 116.33 T (. It can be used to) 451.3 116.33 T (search a test script to locate the source for a failed test. The \336rst part of the identi\336er) 162 104.33 T (, such as) 498.57 104.33 T 4 F (expr) 162 92.33 T 0 F (, should be the same as the name of the test \336le, except that the test \336le should have a) 185.59 92.33 T 4 F (.test) 162 80.33 T 0 F ( extension, such as) 191.98 80.33 T 4 F (expr.test) 269.43 80.33 T 0 F (. The two numbers allow you to divide your tests into) 323.4 80.33 T -0.03 (groups. The tests in a particular group \050e.g., all the) 162 68.33 P 4 F -0.06 (expr) 366.05 68.33 P -0.06 (-) 390.04 68.33 P -0.06 (3.) 396.04 68.33 P 2 F -0.03 (n) 408.03 68.33 P 0 F -0.03 ( tests\051 relate to a single sub-fea-) 413.03 68.33 P FMENDPAGE %%EndPage: "17" 18 %%Page: "18" 18 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (18) 532 42.62 T 0 10 Q -0.27 (ture, such as a single C procedure or a single option of a T) 162 713.33 P -0.27 (cl command. The tests should appear) 390.91 713.33 P (in the test \336le in the same order as their numbers.) 162 701.33 T (The test name, such as) 180 689.33 T 4 F (f) 272.71 689.33 T (loating-point operators) 278.71 689.33 T 0 F (, is printed when errors occur) 416.63 689.33 T (.) 533.21 689.33 T (It provides human-readable information about the general nature of the test.) 162 677.33 T -0.26 (Before writing tests I suggest that you look over some of the test \336les for T) 180 665.33 P -0.26 (cl and Tk to see) 475.51 665.33 P (how they are structured. Y) 162 653.33 T (ou may also want to look at the) 267.3 653.33 T 4 F (README) 395 653.33 T 0 F ( \336les in the T) 430.98 653.33 T (cl and Tk test) 483.03 653.33 T -0.35 (directories to learn about additional features that provide more verbose output or restrict the set) 162 641.33 P (of tests that are run.) 162 629.33 T 3 F (7.2) 137.31 599.33 T (Organizing tests) 162 599.33 T 0 F (Or) 162 583.33 T (ganize your tests to match the code being tested. The best way to do this is to have one test) 172.36 583.33 T -0.18 (\336le for each source code \336le, with the name of the test \336le derived from the name of the source) 162 571.33 P (\336le in an obvious way \050e.g.) 162 559.33 T 4 F (textWind.test) 273.04 559.33 T 0 F ( contains tests for the code in) 351 559.33 T 4 F (tkTextWind.c) 162 547.33 T 0 F (\051. W) 233.96 547.33 T (ithin the test \336le, have one group of tests for each procedure \050for exam-) 251.32 547.33 T (ple, all the) 162 535.33 T 4 F (textWind-2.) 206.42 535.33 T 2 F (n) 272.38 535.33 T 0 F ( tests in) 277.38 535.33 T 4 F (textWind.test) 310.42 535.33 T 0 F ( are for the procedure) 388.38 535.33 T 4 F (TkTextWindowCmd) 162 523.33 T 0 F (\051. The order of the tests within a group should be the same as the order) 251.95 523.33 T (of the code within the procedure. This approach makes it easy to \336nd the tests for a particular) 162 511.33 T (piece of code and add new tests as the code changes.) 162 499.33 T -0.07 (The T) 180 487.33 P -0.07 (cl test suite was written a long time ago and uses a dif) 203.38 487.33 P -0.07 (ferent style where there is one) 417.75 487.33 P (\336le for each T) 162 475.33 T (cl command or group of related commands, and the tests are grouped within the) 217.64 475.33 T -0.1 (\336le by sub-command or features. In this approach the relationship between tests and particular) 162 463.33 P (pieces of code is much less obvious, so it is harder to maintain the tests as the code evolves. I) 162 451.33 T (don\325) 162 439.33 T (t recommend using this approach for new tests.) 180.14 439.33 T 3 F (7.3) 137.31 409.33 T (Coverage) 162 409.33 T 0 F (When writing tests, you should attempt to exercise every line of source code at least once.) 162 393.33 T (There will be occasionally be code that you can\325) 162 381.33 T (t exercise, such as code that exits the applica-) 355.55 381.33 T (tion, but situations like this are rare. Y) 162 369.33 T (ou may \336nd it hard to exercise some pieces of code) 314.52 369.33 T (because existing T) 162 357.33 T (cl commands don\325) 235.69 357.33 T (t provide \336ne enough control to generate all the possible) 309.35 357.33 T -0.03 (execution paths \050for example, at the time I wrote the test suite for T) 162 345.33 P -0.03 (cl\325) 430.73 345.33 P -0.03 (s dynamic string facility) 440.73 345.33 P -0.37 (there were very few T) 162 333.33 P -0.37 (cl commands using the facility; some of the procedures were not called at) 248.07 333.33 P (all\051. In situations like this, write one or more new T) 162 321.33 T (cl commands just for testing purposes. For) 367.28 321.33 T (example, the \336le) 162 309.33 T 4 F (tclTest.c) 230.84 309.33 T 0 F ( in the T) 284.81 309.33 T (cl source directory contains a command) 317.7 309.33 T 4 F -0.53 (testdstring) 162 297.33 P 0 F -0.22 (, which provides a number of options that allow all of the dynamic string code) 227.96 297.33 P (to be exercised.) 162 285.33 T 4 F (tclTest.c) 226.94 285.33 T 0 F ( is only included in a special testing version of) 280.92 285.33 T 4 F (tclsh) 469.13 285.33 T 0 F (, so the) 499.11 285.33 T 4 F (testdstring) 162 273.33 T 0 F ( command isn\325) 227.96 273.33 T (t present in normal T) 287.19 273.33 T (cl applications. Use a similar approach in) 370.33 273.33 T (your own code, where you have an extra \336le with additional commands for testing.) 162 261.33 T -0.16 (It\325) 180 249.33 P -0.16 (s not suf) 188.88 249.33 P -0.16 (\336cient just to make sure each line of code is executed by your tests. In addition,) 222.25 249.33 P (your tests must discriminate between code that executes correctly and code that isn\325) 162 237.33 T (t correct.) 497.13 237.33 T -0.07 (For example, write tests to make sure that the) 162 225.33 P 4 F -0.17 (then) 345.7 225.33 P 0 F -0.07 ( and) 369.68 225.33 P 4 F -0.17 (else) 388.98 225.33 P 0 F -0.07 ( branches of each) 412.96 225.33 P 4 F -0.17 (if) 484.84 225.33 P 0 F -0.07 ( statement) 496.83 225.33 P (are taken under the correct conditions. For loops, run dif) 162 213.33 T (ferent tests to make the loop execute) 387.49 213.33 T -0.17 (zero times, one time, and two or more times. If a piece of code removes an element from a list,) 162 201.33 P -0 (try cases where the element to be removed is the \336rst element, last element, only element, and) 162 189.33 P -0.27 (neither \336rst element nor last. T) 162 177.33 P -0.27 (ry to \336nd all the places where dif) 283.57 177.33 P -0.27 (ferent pieces of code interact in) 413.38 177.33 P (unusual ways, and exercise the dif) 162 165.33 T (ferent possible interactions.) 298.93 165.33 T 3 F (7.4) 137.31 135.33 T (Memory allocation) 162 135.33 T 0 F (T) 162 119.33 T (cl and Tk use a modi\336ed memory allocator that checks for several kinds of memory alloca-) 167.41 119.33 T (tion errors, such as freeing a block twice, failing to free a block, or writing past the end of a) 162 107.33 T (block. In order to use this allocator) 162 95.33 T (, don\325) 301.22 95.33 T (t call) 324.36 95.33 T 4 F (malloc) 346.57 95.33 T 0 F (,) 382.55 95.33 T 4 F (free) 387.55 95.33 T 0 F (, or) 411.53 95.33 T 4 F (realloc) 427.35 95.33 T 0 F ( directly) 469.33 95.33 T (. Call) 501.71 95.33 T 4 F (ckalloc) 162 83.33 T 0 F ( instead of) 203.98 83.33 T 4 F (malloc) 248.11 83.33 T 0 F (,) 284.09 83.33 T 4 F (ckfree) 289.09 83.33 T 0 F ( instead of) 325.07 83.33 T 4 F (free) 369.21 83.33 T 0 F (, and) 393.19 83.33 T 4 F (ckrealloc) 415.12 83.33 T 0 F ( instead of) 469.09 83.33 T 4 F -0.98 (realloc) 162 71.33 P 0 F -0.41 (. These procedures behave identically to) 203.98 71.33 P 4 F -0.98 (malloc) 365.01 71.33 P 0 F -0.41 (,) 400.99 71.33 P 4 F -0.98 (free) 405.58 71.33 P 0 F -0.41 (, and) 429.56 71.33 P 4 F -0.98 (realloc) 450.67 71.33 P 0 F -0.41 ( except that) 492.65 71.33 P FMENDPAGE %%EndPage: "18" 19 %%Page: "19" 19 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (19) 532 42.62 T 0 10 Q (they monitor memory usage.) 162 713.33 T 4 F (Ckalloc) 279.42 713.33 T 0 F (,) 321.4 713.33 T 4 F (ckfree) 326.4 713.33 T 0 F (, and) 362.38 713.33 T 4 F (ckrealloc) 384.31 713.33 T 0 F ( are actually macros that) 438.28 713.33 T (can be con\336gured with a compiler switch: if) 162 701.33 T 4 F (TCL_MEM_DEBUG) 340.76 701.33 T 0 F ( is de\336ned, they perform the) 418.72 701.33 T (checks but run more slowly and use more memory; if) 162 689.33 T 4 F (TCL_MEM_DEBUG) 377.96 689.33 T 0 F ( is not de\336ned, then) 455.92 689.33 T (the macros are just) 162 677.33 T 4 F (#def) 239.72 677.33 T (ine) 263.7 677.33 T 0 F (d to) 281.69 677.33 T 4 F (malloc) 299.46 677.33 T 0 F (,) 335.45 677.33 T 4 F (free) 340.44 677.33 T 0 F (, and) 364.43 677.33 T 4 F (realloc) 386.36 677.33 T 0 F ( so there is no penalty in) 428.33 677.33 T (ef) 162 665.33 T (\336ciency) 169.59 665.33 T (. I always run with) 200.58 665.33 T 4 F (TCL_MEM_DEBUG) 277.75 665.33 T 0 F ( in my development environment and you) 355.7 665.33 T (should too. Of) 162 653.33 T (\336cial releases typically do not have) 219.29 653.33 T 4 F (TCL_MEM_DEBUG) 362.52 653.33 T 0 F ( set.) 440.48 653.33 T (If you set) 180 641.33 T 4 F (TCL_MEM_DEBUG) 220.25 641.33 T 0 F ( anywhere in your code then you must set it everywhere) 298.2 641.33 T (\050including the T) 162 629.33 T (cl and Tk libraries\051; the memory allocator will get hopelessly confused if a) 225.71 629.33 T -0.05 (block of memory is allocated with) 162 617.33 P 4 F -0.12 (malloc) 301.06 617.33 P 0 F -0.05 ( and freed with) 337.04 617.33 P 4 F -0.12 (ckfree) 399.57 617.33 P 0 F -0.05 (, or allocated with) 435.55 617.33 P 4 F -0.12 (ckal-) 510.02 617.33 P (loc) 162 605.33 T 0 F ( and freed with) 179.99 605.33 T 4 F (free) 242.72 605.33 T 0 F (.) 266.7 605.33 T -0.05 (There is nothing equivalent to) 180 593.33 P 4 F -0.12 (calloc) 302.17 593.33 P 0 F -0.05 ( in the debugging memory allocator) 338.15 593.33 P -0.05 (. If you need a) 480.31 593.33 P (new block to be zeroed, call) 162 581.33 T 4 F (memset) 276.63 581.33 T 0 F ( to clear its contents.) 312.61 581.33 T -0.28 (If you compile with) 180 569.33 P 4 F -0.67 (TCL_MEM_DEBUG) 260.5 569.33 P 0 F -0.28 (, then an additional T) 338.45 569.33 P -0.28 (cl command named) 421.86 569.33 P 4 F -0.67 (memory) 501.8 569.33 P 0 F (will appear in your application \050assuming that you\325re using the standard T) 162 557.33 T (cl or Tk main pro-) 457.49 557.33 T (gram\051. The) 162 545.33 T 4 F (memory) 208.9 545.33 T 0 F ( command has the following options:) 244.88 545.33 T (The debugging memory allocator is inferior in many ways to commercial products like) 180 223.33 T (Purify) 162 211.33 T (, so its worth using one of the commercial products if possible. Even so, please use) 186.34 211.33 T 4 F (ckalloc) 162 199.33 T 0 F ( and) 203.98 199.33 T 4 F (ckfree) 223.41 199.33 T 0 F ( everywhere in your code, so that other people without access to the) 259.39 199.33 T (commercial checkers can still use the T) 162 187.33 T (cl debugging allocator) 318.95 187.33 T (.) 407.79 187.33 T 3 F (7.5) 137.31 157.33 T (Fixing bugs) 162 157.33 T 0 F (Whenever you \336nd a bug in your code it means that the test suite wasn\325) 162 141.33 T (t complete. As part of) 447.73 141.33 T -0.12 (\336xing the bug, you should add new tests that detect the presence of the bug. I recommend writ-) 162 129.33 P -0.17 (ing the tests after you\325ve located the bug but) 162 117.33 P 2 F -0.17 (befor) 340.66 117.33 P -0.17 (e) 361.39 117.33 P 0 F -0.17 ( you \336x it. That way you can verify that the) 365.83 117.33 P (bug happens before you implement the \336x and goes away afterwards, so you\325ll know you\325ve) 162 105.33 T (really \336xed something. Use bugs to re\336ne your testing approach: think about what you might) 162 93.33 T (be able to do dif) 162 81.33 T (ferently when you write tests in the future to keep bugs like this one from) 226.77 81.33 T (going undetected.) 162 69.33 T 4 9 Q (memory active) 177 518 T 6 F (f) 252.49 518 T (ile) 257.89 518 T 0 F -0.21 (Dumps a list of all allocated blocks \050and where they were allocated\051 to) 213 509 P 6 F -0.5 (f) 466.15 509 P -0.5 (ile) 471.54 509 P 0 F -0.21 (. Memory) 487.72 509 P (leaks can be tracked down by comparing dumps made at dif) 213 500 T (ferent times.) 428.49 500 T 4 F (memory break_on_malloc) 177 481 T 6 F (number) 301.03 481 T 0 F (Enter the debugger after) 213 472 T 6 F (number) 302.34 472 T 0 F ( calls to) 334.7 472 T 4 F (ckalloc) 364.9 472 T 0 F (.) 402.65 472 T 4 F (memory info) 177 453 T 0 F -0.12 (Prints a report containing the total allocations and frees since T) 213 444 P -0.12 (cl began, the number of) 438.27 444 P (blocks currently allocated, the number of bytes currently allocated, and the maximum) 213 435 T (number of blocks and bytes allocated at any one time.) 213 426 T 4 F (memory init) 177 407 T 6 F (onoff) 241.71 407 T 0 F (If) 213 398 T 6 F (onoff) 221.23 398 T 0 F ( is) 248.2 398 T 4 F (on) 258.68 398 T 0 F (, new blocks of memory are initialized with a strange value to help) 269.47 398 T (locate uninitialized uses of the block. Any other value for) 213 389 T 6 F (onoff) 421.92 389 T 0 F ( turns initialization) 448.88 389 T (of) 213 380 T (f. Initialization is on by default.) 220.32 380 T 4 F (memory trace) 177 361 T 6 F (onoff) 247.1 361 T 0 F -0.17 (If) 213 352 P 6 F -0.42 (onoff) 221.06 352 P 0 F -0.17 ( is) 248.02 352 P 4 F -0.42 (on) 258.16 352 P 0 F -0.17 (, one line will be printed to stderr for each call to) 268.95 352 P 4 F -0.42 (ckalloc) 444.84 352 P 0 F -0.17 (. Any other) 482.59 352 P (value for) 213 343 T 6 F (onoff) 247.44 343 T 0 F ( turns tracing of) 274.4 343 T (f. T) 331.4 343 T (racing is of) 344.06 343 T (f by default.) 384.34 343 T 4 F (memory trace_on_at_malloc) 177 324 T 6 F (number) 317.2 324 T 0 F (Arranges for tracing to be turned on after) 213 315 T 6 F (number) 363.24 315 T 0 F ( calls to) 395.6 315 T 4 F (ckalloc) 425.8 315 T 0 F (.) 463.55 315 T 4 F (memory validate) 177 296 T 6 F (onoff) 263.28 296 T 0 F -0.22 (If) 213 287 P 6 F -0.53 (onoff) 221.01 287 P 0 F -0.22 ( is) 247.98 287 P 4 F -0.53 (on) 258.02 287 P 0 F -0.22 (, guard zones around every allocated block are checked on every call to) 268.81 287 P 4 F -1.87 (ckalloc) 213 278 P 0 F -0.78 ( or) 250.75 278 P 4 F -1.87 (ckfree) 261.17 278 P 0 F -0.78 ( in order to detect memory overruns as soon as possible. If) 293.52 278 P 6 F -1.87 (onoff) 496.57 278 P 0 F -0.12 (is anything other than) 213 269 P 4 F -0.29 (on) 292.89 269 P 0 F -0.12 (, checks are made only during) 303.68 269 P 4 F -0.29 (ckfree) 413.01 269 P 0 F -0.12 ( calls and only for the) 445.36 269 P -0.03 (block being freed. Memory validation has a very lar) 213 260 P -0.03 (ge performance impact, so it is of) 399.56 260 P -0.03 (f) 519.79 260 P (by default.) 213 251 T FMENDPAGE %%EndPage: "19" 20 %%Page: "20" 20 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (20) 532 42.62 T 3 10 Q (7.6) 137.31 713.33 T (T) 162 713.33 T (ricky features) 167.56 713.33 T 0 F (I also use tests as a way of illustrating the need for tricky code. If a piece of code has an) 162 697.33 T (unusual structure, and particularly if the code is hard to explain, I try to write additional tests) 162 685.33 T (that will fail if the code is implemented in the obvious manner instead of using the tricky) 162 673.33 T (approach. This way) 162 661.33 T (, if someone comes along later) 239.9 661.33 T (, doesn\325) 361.63 661.33 T (t understand the documentation for) 393.09 661.33 T (the code, decides the complex structure is unnecessary) 162 649.33 T (, and changes the code back to the sim-) 379.51 649.33 T (ple \050but incorrect\051 form, the test will fail and the person will be able to use the test to under-) 162 637.33 T (stand why the code needs to be the way it is. Illustrative tests are not a substitute for good) 162 625.33 T (documentation, but they provide a useful addition.) 162 613.33 T 3 F (7.7) 137.31 583.33 T (T) 162 583.33 T (est independence) 167.37 583.33 T 0 F (T) 162 567.33 T (ry to make tests independent of each other) 167.76 567.33 T (, so that each test can be understood in isolation.) 336.39 567.33 T (For example, one test shouldn\325) 162 555.33 T (t depend on commands executed in a previous test. This is) 285.35 555.33 T (important because the test suite allows tests to be run selectively: if the tests depend on each) 162 543.33 T (other) 162 531.33 T (, then false errors will be reported when someone runs a few of the tests without the oth-) 182.14 531.33 T (ers.) 162 519.33 T -0.02 (For convenience, you may execute a few statements in the test \336le to set up a test con\336gu-) 180 507.33 P (ration and then run several tests based on that con\336guration. If you do this, put the setup code) 162 495.33 T -0 (outside the calls to the) 162 483.33 P 4 F -0 (test) 253.89 483.33 P 0 F -0 ( procedure so it will always run even if the individual tests aren\325) 277.87 483.33 P -0 (t) 534.72 483.33 P -0.05 (run. I suggest keeping a very simple structure consisting of setup followed by a group of tests.) 162 471.33 P (Don\325) 162 459.33 T (t perform some setup, run a few tests, modify the setup slightly) 182.36 459.33 T (, run a few more tests,) 434.05 459.33 T (modify the setup again, and so on. If you do this, it will be hard for people to \336gure out what) 162 447.33 T (the setup is at any given point and when they add tests later they are likely to break the setup.) 162 435.33 T 3 12 Q (8.) 141.2 399 T (Porting issues) 162 399 T 0 10 Q (The X W) 162 378.33 T (indow System, ANSI C, and POSIX provide a standard set of interfaces that make it) 198.79 378.33 T (possible to write highly portable code. However) 162 366.33 T (, some additional work will still be needed if) 353.96 366.33 T (code is to port among all of the UNIX platforms. As T) 162 354.33 T (cl and Tk move from the UNIX world) 378.93 354.33 T (onto PCs and Macintoshes, porting issues will become even more important. This section con-) 162 342.33 T (tains a few tips on how to write code that can run on many dif) 162 330.33 T (ferent platforms.) 409.42 330.33 T 3 F (8.1) 137.31 300.33 T (Stick to standards) 162 300.33 T 0 F (The easiest way to make your code portable is to use only library interfaces that are available) 162 284.33 T (everywhere \050or nearly everywhere\051. For example, the ANSI C library procedures, POSIX sys-) 162 272.33 T -0.16 (tem calls, and Xlib windowing calls are available on many platforms; if you code to these stan-) 162 260.33 P (dards your packages will be quite portable. A) 162 248.33 T (void using system-speci\336c library procedures,) 342.79 248.33 T (since they will introduce porting problems.) 162 236.33 T 3 F (8.2) 137.31 206.33 T (Minimize #ifdefs) 162 206.33 T 0 F (Although there will be situations where you have to do things dif) 162 190.33 T (ferently on dif) 421.94 190.33 T (ferent) 478.94 190.33 T (machines,) 162 178.33 T 4 F (#ifdef) 204.75 178.33 T 0 F (s are rarely the best way to deal with these problems. If you load up your) 240.73 178.33 T -0.34 (code with) 162 166.33 P 4 F -0.8 (#ifdef) 202.97 166.33 P 0 F -0.34 ( statements based on various machines and operating systems, the code will) 238.95 166.33 P -0.25 (turn into spaghetti.) 162 154.33 P 4 F -0.6 (#ifdef) 238.98 154.33 P 0 F -0.25 (s make code unreadable: it is hard to look at) 274.96 154.33 P 4 F -0.6 (#ifdef) 451.21 154.33 P 0 F -0.25 (-ed code and) 487.19 154.33 P (\336gure out exactly what will happen on any one machine. Furthermore,) 162 142.33 T 4 F (#ifdef) 445.96 142.33 T 0 F (s encourage a) 481.94 142.33 T -0.35 (style where lots of machine dependencies creep all through the code; it is much better to isolate) 162 130.33 P (machine dependencies in a few well-de\336ned places.) 162 118.33 T (Thus you should almost never use) 180 106.33 T 4 F (#ifdef) 318.8 106.33 T 0 F (s. Instead, think carefully about the ways in) 354.78 106.33 T (which systems dif) 162 94.33 T (fer and de\336ne procedural interfaces to the machine-dependent code. Then) 234 94.33 T (provide a dif) 162 82.33 T (ferent implementation of the machine-dependent procedures for each machine.) 212.89 82.33 T (When linking, choose the version appropriate for the current machine. This way all of the) 162 70.33 T FMENDPAGE %%EndPage: "20" 21 %%Page: "21" 21 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (21) 532 42.62 T 0 10 Q (machine dependencies for a particular system are located in one or a few \336les that are totally) 162 713.33 T (separate from the machine-dependent code for other systems and from the main body of your) 162 701.33 T (code. The only \322conditional\323 code left will be the code that selects which version to link with.) 162 689.33 T (Y) 180 677.33 T (ou won\325) 186.22 677.33 T (t be able to eliminate) 219.07 677.33 T 4 F (#ifdef) 305.4 677.33 T 0 F (s completely) 341.38 677.33 T (, but please avoid them as much as) 391.53 677.33 T (possible. If you end up with code that has a lot of) 162 665.33 T 4 F (#ifdef) 361.59 665.33 T 0 F (s, this should be a warning to you) 397.57 665.33 T (that something is wrong. See if you can \336nd a way to re-or) 162 653.33 T (ganize the code \050perhaps using the) 396.38 653.33 T (techniques described later in this section\051 to reduce the number of) 162 641.33 T 4 F (#ifdef) 427.63 641.33 T 0 F (s.) 463.61 641.33 T 3 F (8.3) 137.31 611.33 T (Organize by feature, not by system) 162 611.33 T 0 F -0.27 (Don\325) 162 595.33 P -0.27 (t think about porting issues in terms of speci\336c systems. Instead, think in terms of speci\336c) 182.36 595.33 P 2 F (featur) 162 583.33 T (es) 185.51 583.33 T 0 F ( that are present or absent in the systems. For example, don\325) 193.83 583.33 T (t divide your code up) 433.76 583.33 T -0.05 (according to what is needed in HP-UX versus Solaris versus W) 162 571.33 P -0.05 (indows. Instead, consider what) 414.2 571.33 P -0.07 (features are present in the dif) 162 559.33 P -0.07 (ferent systems; for example, some systems have a) 277.74 559.33 P 4 F -0.18 (waitpid) 478.95 559.33 P 0 F -0.07 ( pro-) 520.92 559.33 P -0.23 (cedure, while others don\325) 162 547.33 P -0.23 (t yet provide one, and some systems have ANSI C compilers that sup-) 262.7 547.33 P (port procedure prototypes, while some systems do not.) 162 535.33 T (The feature-based approach has a number of advantages over the system-based approach.) 180 523.33 T (First, many systems have features in common, so you can share feature-based porting code) 162 511.33 T (among dif) 162 499.33 T (ferent systems. Second, if you think in terms of features then you can consider each) 202.63 499.33 T (feature separately \050\322what do I do if there is no) 162 487.33 T 4 F (waitpid) 348.51 487.33 T 0 F (?\323\051; this replaces one lar) 390.48 487.33 T (ge problem) 487.44 487.33 T (with several smaller problems that can be dealt with individually) 162 475.33 T (. Lastly) 420.35 475.33 T (, the) 449.68 475.33 T 4 F (autoconf) 469.39 475.33 T 0 F ( pro-) 517.36 475.33 T -0.31 (gram can be used to check for the presence or absence of particular features and con\336gure your) 162 463.33 P -0.18 (code automatically) 162 451.33 P -0.18 (. Once you\325ve gotten your code running on several dif) 236.95 451.33 P -0.18 (ferent systems, you\325ll) 451.7 451.33 P (\336nd that many new systems can be handled with no additional work: their features are similar) 162 439.33 T (to those in systems you\325ve already considered, so) 162 427.33 T 4 F (autoconf) 362.14 427.33 T 0 F ( can handle them automatically) 410.11 427.33 T (.) 534.38 427.33 T 3 F (8.4) 137.31 397.33 T (Use emulation) 162 397.33 T 0 F (One of the cleanest ways to handle porting problems is with emulation: assume the existence) 162 381.33 T (of certain procedures, such as those in the POSIX standard, and if they don\325) 162 369.33 T (t exist on a given) 465.2 369.33 T (system then write procedures to emulate the desired functionality with the facilities that are) 162 357.33 T (present on the system. For example, when T) 162 345.33 T (cl \336rst started being used widely I discovered that) 338.12 345.33 T -0.16 (many systems did not support the) 162 333.33 P 4 F -0.37 (waitpid) 297.66 333.33 P 0 F -0.16 ( kernel call, even though it was part of the POSIX) 339.64 333.33 P (standard. So, I wrote a) 162 321.33 T 4 F (waitpid) 254.43 321.33 T 0 F ( procedure myself, which emulated the functionality of) 296.41 321.33 T 4 F (waitpid) 162 309.33 T 0 F ( using the) 203.98 309.33 T 4 F (wait) 245.34 309.33 T 0 F ( and) 269.33 309.33 T 4 F (wait3) 288.76 309.33 T 0 F ( kernel calls. The best way to emulate) 318.74 309.33 T 4 F (waitpid) 472.24 309.33 T 0 F ( was) 514.22 309.33 T (with) 162 297.33 T 4 F (wait3) 182.27 297.33 T 0 F (, but unfortunately) 212.25 297.33 T 4 F (wait3) 288.87 297.33 T 0 F ( wasn\325) 318.85 297.33 T (t available everywhere either) 345.04 297.33 T (, so the emulation) 460.37 297.33 T (worked dif) 162 285.33 T (ferently on systems that had) 205.4 285.33 T 4 F (wait3) 320.04 285.33 T 0 F ( and those that supported only) 350.03 285.33 T 4 F (wait) 472.73 285.33 T 0 F (. The) 496.72 285.33 T 4 F (autoconf) 162 273.33 T 0 F ( program checks to see which of the kernel calls are available, includes the emula-) 209.97 273.33 T (tion for) 162 261.33 T 4 F (waitpid) 194.2 261.33 T 0 F ( if it isn\325) 236.18 261.33 T (t available, and sets a compiler \337ag that indicates to the emulation) 270.15 261.33 T (code whether or not) 162 249.33 T 4 F (wait3) 244.15 249.33 T 0 F ( is available.) 274.14 249.33 T (Y) 180 237.33 T (ou can also emulate using) 186.22 237.33 T 4 F (#def) 291.98 237.33 T (ine) 315.96 237.33 T 0 F (s in a header \336le. For example, not all systems sup-) 333.95 237.33 T (port symbolic links, and those that don\325) 162 225.33 T (t support symbolic links don\325) 320.34 225.33 T (t support the) 437.33 225.33 T 4 F (lstat) 489.8 225.33 T 0 F ( ker-) 519.78 225.33 T (nel call either) 162 213.33 T (. For these systems T) 215.85 213.33 T (cl uses) 299.82 213.33 T 4 F (stat) 329.25 213.33 T 0 F ( to emulate) 353.23 213.33 T 4 F (lstat) 400.15 213.33 T 0 F ( with the following) 430.13 213.33 T (statement in) 162 201.33 T 4 F (tclUnix.h) 213.08 201.33 T 0 F (:) 267.05 201.33 T 4 9 Q (#def) 189 187 T (ine lstat stat) 210.57 187 T 0 10 Q -0.09 (If a header \336le is missing on a particular system, write your own version of the header \336le) 180 173.33 P -0 (to supply the de\336nitions needed by your code. Then you can) 162 161.33 P 4 F -0 (#include) 405.7 161.33 P 0 F -0 ( your version in your) 453.68 161.33 P (code if the system doesn\325) 162 149.33 T (t have a version of its own. For example, here is the code in) 263.41 149.33 T 4 F (tclUnix.h) 162 137.33 T 0 F ( that handles) 215.97 137.33 T 4 F (unistd.h) 268.99 137.33 T 0 F (, which isn\325) 316.96 137.33 T (t yet available on all UNIX systems:) 363.7 137.33 T 4 9 Q (#ifdef HAVE_UNISTD_H) 189 123 T (#include ) 189 113 T (#else) 189 103 T (#include "compat/unistd.h") 189 93 T (#endif) 189 83 T FMENDPAGE %%EndPage: "21" 22 %%Page: "22" 22 612 792 0 FMBEGINPAGE 108 54 540 54 2 L 0.25 H 2 Z 0 X 0 K N 0 8 Q (T) 108 42.62 T (cl/Tk Engineering Manual) 112.33 42.62 T (September 1, 1994) 293.91 42.62 T (22) 532 42.62 T 0 10 Q (The) 162 713.33 T 4 F (conf) 180.04 713.33 T (igure) 204.03 713.33 T 0 F ( script generated by) 234.01 713.33 T 4 F (autoconf) 315.06 713.33 T 0 F ( checks for the existence of) 363.03 713.33 T 4 F (unistd.h) 474.6 713.33 T 0 F ( in) 522.57 713.33 T (the system include directories and sets) 162 701.33 T 4 F (HAVE_UNISTD_H) 318 701.33 T 0 F ( if it is present. If it isn\325) 395.96 701.33 T (t present,) 490.17 701.33 T 4 F (tclUnix.h) 162 689.33 T 0 F ( includes a version from the T) 215.97 689.33 T (cl source tree.) 335.18 689.33 T 3 F (8.5) 137.31 659.33 T (Use autoconf) 162 659.33 T 0 F (The GNU) 162 643.33 T 4 F (autoconf) 204.19 643.33 T 0 F ( program provides a powerful way to con\336gure your code for dif) 252.16 643.33 T (ferent) 510.39 643.33 T (systems. W) 162 631.33 T (ith) 207.68 631.33 T 4 F (autoconf) 220.74 631.33 T 0 F ( you write a script called) 268.71 631.33 T 4 F (conf) 369.75 631.33 T (igure.in) 393.73 631.33 T 0 F ( that describes the port-) 441.71 631.33 T (ing issues for your software in terms of particular features that are needed and what to do if) 162 619.33 T -0.08 (they aren\325) 162 607.33 P -0.08 (t present. Before creating a release of your software you run) 201.97 607.33 P 4 F -0.2 (autoconf) 443.62 607.33 P 0 F -0.08 (, which pro-) 491.59 607.33 P (cesses) 162 595.33 T 4 F (conf) 189.48 595.33 T (igure.in) 213.46 595.33 T 0 F ( and generates a shell script called) 261.43 595.33 T 4 F (conf) 400.49 595.33 T (igure) 424.48 595.33 T 0 F (. Y) 454.46 595.33 T (ou then include) 465.67 595.33 T 4 F (conf) 162 583.33 T (igure) 185.99 583.33 T 0 F ( with your distribution.) 215.97 583.33 T (When it is time to install the distribution on a particular system, the installer runs the) 180 571.33 T 4 F (conf) 162 559.33 T (igure) 185.99 559.33 T 0 F ( script.) 215.97 559.33 T 4 F (conf) 245.67 559.33 T (igure) 269.66 559.33 T 0 F ( pokes around in the system to \336nd out what features are) 299.64 559.33 T (present, then it modi\336es the) 162 547.33 T 4 F (Makef) 275.27 547.33 T (ile) 305.25 547.33 T 0 F ( accordingly) 323.24 547.33 T (. The modi\336cations typically consist of) 372.27 547.33 T (compiling additional \336les to substitute for missing procedures, or setting compiler \337ags that) 162 535.33 T (can be used for conditional compilation in the code.) 162 523.33 T 3 F (8.6) 137.31 493.33 T (Porting header \336le) 162 493.33 T 0 F -0.25 (In spite of all the above advice, you will still end up needing some conditional compilation, for) 162 477.33 P (example to include alternate header \336les where standard ones are missing or to) 162 465.33 T 4 F (#def) 479.26 465.33 T (ine) 503.24 465.33 T 0 F (symbols that aren\325) 162 453.33 T (t de\336ned on the system. Put all of this code in the porting header \336le for the) 235.66 453.33 T (package, then) 162 441.33 T 4 F (#include) 219.45 441.33 T 0 F ( this header \336le in each of the source \336les of the package. W) 267.42 441.33 T (ith this) 507.94 441.33 T -0.08 (approach you only need to change a single place if you have to modify your approach to porta-) 162 429.33 P -0.05 (bility) 162 417.33 P -0.05 (, and you can see all of the porting issues in one place. Y) 182.46 417.33 P -0.05 (ou can look at) 408.08 417.33 P 4 F -0.13 (tclPort.h) 466.71 417.33 P 0 F -0.05 ( and) 520.68 417.33 P 4 F (tkPort.h) 162 405.33 T 0 F ( for examples of porting header \336les.) 209.97 405.33 T 3 12 Q (9.) 141.2 369 T (Miscellaneous) 162 369 T 3 10 Q (9.1) 137.31 338.33 T (Changes \336les) 162 338.33 T 0 F -0.23 (Each package should contain a \336le named) 162 322.33 P 4 F -0.56 (changes) 330.51 322.33 P 0 F -0.23 ( that keeps a log of all signi\336cant changes) 372.49 322.33 P (made to the package. The) 162 310.33 T 4 F (changes) 266.91 310.33 T 0 F ( \336le provides a way for users to \336nd out what\325) 308.89 310.33 T (s new in) 492.66 310.33 T -0 (each new release, what bugs have been \336xed, and what compatibility problems might be intro-) 162 298.33 P (duced by the new release. The) 162 286.33 T 4 F (changes) 285.5 286.33 T 0 F ( \336le should be in chronological order) 327.48 286.33 T (. Just add short) 474.61 286.33 T (blurbs to it each time you make a change. Here is a sample from the Tk) 162 274.33 T 4 F (changes) 449.84 274.33 T 0 F ( \336le:) 491.82 274.33 T 4 9 Q (5/19/94 \050bug f) 189 260 T (ix\051 Canvases didn't generate proper Postscript for) 264.49 260 T (stippled text.) 189 250 T -2.65 (5/20/94 \050new feature\051 Added "bell" command to ring the display's bell.) 189 230 P (5/26/94 \050feature removed\051 Removed support for "f) 189 210 T (ill" justify mode) 447.84 210 T (from Tk_GetJustify and from the TK_CONFIG_JUSTIFY conf) 189 200 T (iguration) 480.19 200 T (option. None of the built-in widgets ever supported this mode) 189 190 T (anyway.) 189 180 T (*** POTENTIAL INCOMPATIBILITY ***) 189 170 T 0 10 Q (The entries in the) 162 156.33 T 4 F (changes) 234.17 156.33 T 0 F ( \336le can be relatively terse; once someone \336nds a change that is) 276.15 156.33 T -0.06 (relevant, they can always go to the manual entries or code to \336nd out more about it. Be sure to) 162 144.33 P (highlight changes that cause compatibility problems, so people can scan the) 162 132.33 T 4 F (changes) 467.35 132.33 T 0 F ( \336le) 509.33 132.33 T (quickly to locate the incompatibilities.) 162 120.33 T FMENDPAGE %%EndPage: "22" 23 %%Trailer %%BoundingBox: 0 0 612 792 %%Pages: 22 1 %%DocumentFonts: Times-Roman %%+ Times-Bold %%+ Times-Italic %%+ Helvetica-Bold %%+ Courier %%+ Helvetica %%+ Courier-Oblique %%EOF r each) 202.63 499.33 T (feature separately \050\322what do I do if there is no) 162 487.33 T 4 F (waitpid) 348.51 487.33 T 0 F (?\323\051; this replaces one lar) 390.48 487.33 T (ge problem) 487.44 487.33 T (wiengManual/engManual010066400630510000012000004340000564060431700154740ustar00ousterstaff377777770000002  AaO)33HH33$d    dFootnote TableFootnotet**. .  - 3^x ^LOT TableTitleLOFmFigureTOC1Heading2Heading3Heading   =ar   ium egu    egu  ue tal      >  ! N  ?   @  A  B  C  D  E  F  G   H  I  J  ! K  " L  # M  ) X $ N  O  P  Q  % RrFi 0F> Z & SO  T  U H W33  X  ` ' Y  ( Z  ) [  * \  ]  +Fo ^e Foo ,t _*  - `.  t . a 3 b^  c  d LO e Ta tle /LO fFi  0 gadi Hea 13H hg   * iar   = 2  iump17740: Figure: Figure 1. An example of a header page. Part of the text of the copyright notice has been omitted.!  NV21885: Figure: Figure 2. The header comments and declaration for a procedure. The file  k33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.J 016212: 1Heading: 4. Low-level coding conventions ! h18388: Step: 5. #defined constants and macros have names that are all capital letters, except for macros % " 338044: 2Heading: 3.3 Names reflect module structure # U'29175: 2Heading: 3.2 Basic syntax rules $ i33919: Figure: Figure 4. Comments in code should have the form shown above, using full lines, with lined- % +418146: 2Heading: 4.2 Code comments occupy full lines` & a28098: Figure: Figure 5. Use side-by-side comments when declaring structure members and proceduree ' LOB10536: Figure: Figure 6. Continuation lines are indented 8 spaces. ( i-27489: 1Heading: 2. Packages and header filesg ) . A/40835: 1Heading: 3. How to organize a code filehe * igh&32724: 1Heading: 4. Naming conventions + Fig$17535: 1Heading: 6. Documenting code d , ati17997: 1Heading: 7. Testing - k33"38346: 1Heading: 8. Porting issues . a h41303: Figure: Figure 1. An example of a header file. The file engManual/proto.h contains a template fordi / nve+42488: 2Heading: 2.5 _ANSI_ARGS_ prototypesnst 0 and)16885: 2Heading: 5.1 Indents are 4 spacest 1 exc=34687: 2Heading: 5.5 Continuation lines are indented 8 spacesd   U 5: in  B yn=mV,= p17740: Figure: Figure 1. An example of a header page. Part of the text of the copyright notice has been omitted.18> dinp17740: Figure: Figure 1. An example of a header page. Part of the text of the copyright notice has been omitted.ru? berV21885: Figure: Figure 2. The header comments and declaration for a procedure. The file@ -27k33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.i32A dink33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects. B 46:V21885: Figure: Figure 2. The header comments and declaration for a procedure. The fileC engk33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.8HeD 1 IV21885: Figure: Figure 2. The header comments and declaration for a procedure. The fileE  k33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.apaF of V21885: Figure: Figure 2. The header comments and declaration for a procedure. The fileG mplk33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.rigH e h016212: 1Heading: 4. Low-level coding conventionsleI V21885: Figure: Figure 2. The header comments and declaration for a procedure. The fileJ idek33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.pduK ideh18388: Step: 5. #defined constants and macros have names that are all capital letters, except for macrose L C 338044: 2Heading: 3.3 Names reflect module structure ocM der'29175: 2Heading: 3.2 Basic syntax rulescN i33919: Figure: Figure 4. Comments in code should have the form shown above, using full lines, with lined-O re:i33919: Figure: Figure 4. Comments in code should have the form shown above, using full lines, with lined-P FigV21885: Figure: Figure 2. The header comments and declaration for a procedure. The fileQ Figk33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects. hR 1He418146: 2Heading: 4.2 Code comments occupy full lines21S re:a28098: Figure: Figure 5. Use side-by-side comments when declaring structure members and proceduregT . Aa28098: Figure: Figure 5. Use side-by-side comments when declaring structure members and procedureeU : 5a28098: Figure: Figure 5. Use side-by-side comments when declaring structure members and procedureW 44:V21885: Figure: Figure 2. The header comments and declaration for a procedure. The fileX ulek33525: Figure: Figure 3. Another example of a procedure header, this one for a procedure with side effects.l, Y d-B10536: Figure: Figure 6. Continuation lines are indented 8 spaces.Z sho-27489: 1Heading: 2. Packages and header files[ 85:/40835: 1Heading: 3. How to organize a code filea f\ edu&32724: 1Heading: 4. Naming conventions] . A016212: 1Heading: 4. Low-level coding conventionsro^ th $17535: 1Heading: 6. Documenting codeHe_ 2 C17997: 1Heading: 7. Testings21` re:"38346: 1Heading: 8. Porting issuesa ntsh41303: Figure: Figure 1. An example of a header file. The file engManual/proto.h contains a template formmb  deh41303: Figure: Figure 1. An example of a header file. The file engManual/proto.h contains a template forhec ng h41303: Figure: Figure 1. An example of a header file. The file engManual/proto.h contains a template for fd eduh41303: Figure: Figure 1. An example of a header file. The file engManual/proto.h contains a template forroe th h41303: Figure: Figure 1. An example of a header file. The file engManual/proto.h contains a template forf 89:+42488: 2Heading: 2.5 _ANSI_ARGS_ prototypes[g 35:)16885: 2Heading: 5.1 Indents are 4 spacesh edu=34687: 2Heading: 5.5 Continuation lines are indented 8 spaces:i  Loi33919: Figure: Figure 4. Comments in code should have the form shown above, using full lines, with lined-: <$paratext[Title]>e: <$paratext[1Heading]> is <$curpagenum>h41<$lastpagenum> A<$monthname> <$daynum>, <$year>g<$monthname> <$daynum>, <$year>;<$monthname> <$daynum>, <$year> <$hour>:<$minute00> <$ampm>i"<$monthnum>/<$daynum>/<$shortyear>te (Continued)+ (Sheet <$tblsheetnum> of <$tblsheetcount>)hPagepage <$pagenum>o Number Onlyp<$paranumonly> FigureFigure<$paranumonly>ASectionaSection<$paranumonly>ngTableoTable<$paranumonly> % @ge: $$@xpl OO@i. JJ@u/p KK@ te LL@ MM@:He PP@IRG QQ@ RR@65: SS@Ien TT@ %%P47: &&QCAi ((Prin ))Q:A **P39: ,,P C 55Q TOCd h 88QoIX ;;QlLOFs, >>QLOT AQeAT UU@pa YY@]is ]]@gum ^^@apa __@mo aa@u, uu@mo u, ;mo u, :mi i /da a U u 8 Utin V+3.tb Wtnu3.1eet X>)h Y3.2<$p Zm>o3.3Onl [$pa3.4 \ure4.$p ]mon4.1tio ^ect4.2onl _4.3le `anu a5. b ce: d$ e fO@i g h/p iK j kL@ l mHe nP o pQ@ q r5: sS t uT@ v1.7: w5.1 x(5.2 y)Q:5.3* z9:5.4,P {5.5TO | }8Qo ~1.LO  >Q Figure 3. A AT U  Y@]  um ^  _@  , u  u 6.mo  , 6.2: 6.3  da  u 8 tin6.1 tb 7.4X 8. 3.28.3 3.3 $pa8.4 ure 9.$p mon7.5tio ect 9.1onl  4.3 anu         Figure 2. K j k l m n o p q r s t Figure 4.  7:    1. 5.32.9: 8.1 3.| 4. 3.5    3. AT1.U 2. 3. um4.^  _@2.  u3. 4. mo  5.:  6. da4.4 u 81.tin  tb2.  3. 3.2                     Figure 6.     ure         Figure 7. r5.6 t ure  Figure 5.  6.5  6.62.    3.          2.7. 3.6.4 ^  _@   u7.7  7.1   :     7.21.   7.3   ! " # $7.6 % & ' ( )8.2 * + ,8.5 - . / 6. 0 1 2 38.6 4 5 6 7 9 : ;2.re < =2.3 > ? @ A 5.2.4 B C6.52.2 D2.12. E F G3. H I J K Figure 1. L M N  O  P7 R3.2.5 S^ T U_@ V W Xu Y7.7 Z [ \7.1 ] d m%(d m),d m  lH n .6lHC t3UU G6.2`package structures and internal utility procedures are defined in the internal header file. The UU G6binternal header file should also contain J#include6s for other headers that are used widely UU G6reZwithin the package, so they dont have to be included over and over in each code file. As *UU G6]with the package header, the internal header file should be as small as possible: structures 6UU@ G6]and procedures that are only used in a single C file in the package should not appear in it. EUU H6dA ]porting header file6, which contains definitions that hide the differences between the sysQUU H6[tems on which the package can be used.The name of the porting header should consist of the ]UU@ H6Epackage prefix follwed by JPort.h6, such as JtclPort.h6. lUU I6[Other internal header files for various subpackages within the package. For example, there xUU I6agdis a file JtkText.h6 in Tk that is shared among all the files that implement text widgets and UUUU@ I6 h\another file JtkCanvas.h6 that is shared among all the widgets implementing canvases. UU J6in_I recommend having as few header files as possible in each package. In almost all cases a pack GUU J6kaeage header file, a single internal header file, and a porting header file will be sufficient, and in nUU J6ar^many cases the porting header file may not be necessary. The internal header file should autoUU J6 fematically J#include6 the package header file and perhaps even the porting header file, so each eêUU J6ckbC file in the package only needs to J#include6 one or at most two header files. I recommend ϪUU J6y _keeping the porting header separate from the internal header file in order to maintain a clean va۪UU J6wi_separation between porting code and the rest of the module. Other internal headers should only at 窘UU J6l dbe necessary in unusual cases, such as the Tk text and canvas widgets (each of JtkText.h6 and iUU JJ t^tkCanvas.h6 is many hundred lines long, due to the complexity of the widgets, and they are UU J6ch`needed only in the source files that implement the particular widgets, so I thought it would be ea UU J6rteeasier to manage these headers separately from JtkInt.h6). If you have lots of internal header yUU J6 Tgfiles, such as one for each source file, then you will end up with lots of J#include6 statements ile#UU J6thein each C file and youll find that either (a) you J#include6 every header in every C file (in /UU J6twbwhich case theres not much advantage to having the separate J.h6 files) or (b) you are con;UU@ J6 oTstantly adding and deleting J#include6 statements as you modify source files. thYUU` A[leHeader file structure iUU( B6m Figure1  illustrates the format of a header file.  Your header files should follow this structure 6uUU B6UU_exactly: same indentation, same order of information, and so on. To make this as easy as possiey UU B6 Jeble, the directory JengManual6 in the Tcl source tree contains templates for various pieces of aUU B6rtjsource files. For example, the file Jproto.h6 contains a template for a header file; there are also UU B6fi\templates for code files and procedure headers. You should be able to set up your editor to emUU B6UU]incorporate the templates when needed, then you can modify them for the particular situation vUU B6_in which they are used. This should make it easy for you to conform to the conventions without or UU@ B6a lot of typing overhead. ɪUUh L6[Each header file contains the following parts, which are labelled in 6 Figure1 : uctتUU MC BdAbstract6: the first few lines give the name of the file plus a short description of its overall is䪅UU@ M6 purpose. UUU NCdecCopyright notice6: this protects the ownership of the file and controls distribution; different eblUU N6J_notices may be used on different files, depending on whether the file is to be released freely 6rt UU N6r \or restricted. The wording in copyright notices is sensitive (e.g. the use of upper case is UU@ N6laUimportant) so dont make changes in notices without checking with a legal authority. m&UU OCUU^Revision string:6 the contents of this string are managed automatically by the source code 2UU O6]control system for the file, such as RCS or SCCS (RCS is used in the example in the figure). t>~UU@ O6 BQIt identifies the files current revision, date of last modification, and so on. M}UU PChi_Multiple include #ifdef6: when a large application is developed with many related packages, es Y|UU P6hedit is hard to arrange the J#include6 statements so that each include file is included exactly Coe{UU P6: oonce For example, files Ja.h6 and Jb.h6 might both include Jc.h6, and a particular code file beqzUU P6 fmmight include both Ja.h6 and Jb.h6. This will cause Jc.h6 to be processed twice, and could g}yUU P6ce[potentially result in compiler errors such as multiply-defined symbols. With the recursion e cxUU PJwi\#ifdef6, plus the matching J#endif6 at the end of the file, the header file can be s d mice lHn emlHtt  ut+3,H33n" # Hifdmat, lHn MulH# pl/UU PJa#include6d multiple times without problems. The symbol J_TCL6 is defined the first time UU P6de_the header file is included; if the header is included again the presence of the symbol causes 6UU P6de^the body of the header file to be skipped. The symbol used in any given header file should be *UU P6Thlthe same as the name of the header file except with the J.h6 stripped off, a J_6 prepended, and er6UU@ P6lteverything else capitalized. rEUU 5C[Version defines6: for each package, three symbols related to the current version number fiQUU 56[should be defined. The first gives the full version number as a string, and the second and H]UU 56[third give the major and minor numbers separately as integers. The names for these symbols diUUH 56Fshould be derived from the package prefix as in 6 Figure1 . xUU TC_Declarations6: the rest of the header file consists of declarations for the things that are symUU T6s [exported from the package to its clients. Most of the conventions for coding these declaranclUU T6sections will be discussed later. When declaring variables and procedures, use JEXTERN6 instead ol UU T6hemof Jextern6 to declare them external. The symbol JEXTERN6 can then be J#define6d to either rUU TJaextern6 or Jextern "C"6 to allow the header file to be used in both C and C++ programs. oUU T6 enThe header file Jtcl.h6 contains code to J#define6 the JEXTERN6 symbol; if your header file UU@ T6ulfdoesnt J#include6 Jtcl.h6, you can copy the code from Jtcl.h6 to your header file. ުUUh R[y  _ANSI_ARGS_ prototypes eseUU( @6\Procedure prototypes should use the J_ANSI_ARGS_6 macro as shown in  Figure1 . UUUU @Jio__ANSI_ARGS_6 makes it possible to write full procedure prototypes for the normal case where UUUU @6 f\an ANSI C compiler will be used, yet it also allows the file to be used with older non-ANSI UUUU @6llccompilers. To use J_ANSI_ARGS_6, specify the entire argument list, including parentheses, as UUUU @6xtdan argument to the J_ANSI_ARGS_6 macro; J_ANSI_ARGS_6 will evaluate to either this argu*UU @6ex[ment list or J()6, depending on whether or not an ANSI C compiler is being used. The . o6UU@ @J e3_ANSI_ARGS_6 macro is defined in Jtcl.h6. #deBUU U6XTZIn the argument lists in procedure prototypes, be sure to specify names for the arguments NUU U6 t`as well as their types. The names arent required for compilation (for example, the declaration seZUU@ U60for JTcl_Eval6 could have been written as GSh` V8wnCEXTERN int Tcl_Eval _ANSI_ARGS_((Tcl_Interp *, char *)); t pvUUh W6ul[in 6 Figure1 ) but the names provide additional information about the arguments. wilh VDal  How to organize a code file oUU }6`Each source code file should contain a related set of procedures, such as the implementation of ngUU }6UU^a widget or canvas item type, or a set of procedures to implement hash tables. Before writing ǪUU }6is\any code you should think carefully about what functions are to be provided and divide them omӪUU }6d.cup into files in a logical way. In my experience, the most manageable size for files is usually in 6XTߪUU }6li_the range of 500-2000 lines. If a file gets much larger than this, it will be hard to remember wel몉UU }6Thaeverything that the file does. If a file is much shorter than this, then you may end up with too UU@ }6ld9many files in a directory, which is also hard to manage. UU 6NSZCode files are divided into pages separated by formfeed (control-L) characters. The first UU 6io`page of the file is a header page containing information that is used throughout the file. Each UU 6Ea]additional page of the file contains one procedure. This approach has two advantages. First, g'UU 6UU`when you print a code file each procedure header will start at the top of the page, which makes 3UU 6an`for easier reading. Second, you can browse through all of the procedures in a file by searching ?UU@ 6ntfor the formfeed characters. ]UU` W[stThe file header page lmUU X6XTiThe first page of a code file is a ]header page6. It contains overall information that is relevant yUU X6`throughout the file, which consists of everything but the definitions of the files procedures. u~UUH X6KThe header page typically has six parts, as shown in  Figure2  : @ey @e -L7ac 8/* UU 8th * tclLink.c -- p 8or * n t! 8hoD * This file implements linked variables (a C variable that is co* 8reC * tied to a Tcl variable). The idea of linked variables was n y3 8leF * first suggested by Andreas Stolcke and this implementation is < 8an@ * based heavily on a prototype implementation provided by ocE 8y * him. N 8fo * foW 8 C * Copyright (c) 1993 The Regents of the University of California. fi` 8 f * All rights reserved. 6i 8al * ormr 8vaG * Permission is hereby granted, without written agreement and without ng { 8s F * license or royalty fees, to use, copy, modify, and distribute this  8 aE * software and its documentation for any purpose, provided that the  8E * above copyright notice and the following two paragraphs appear in  8nk * all copies of this software. t 8ho *  8en * ... va 8bl */ i 8  e 8a Ostatic char rcsid[] = "$Header: /user6/ouster/tcl/RCS/tclLink.c,v 1.5 94/04/23 fi 8nd*16:12:30 ouster Exp $ SPRITE (Berkeley)";  8 *  8 a#include "tclInt.h" io@ 8  8 /* .  8foG * For each linked variable there is a data structure of the following ive 8a.F * type, which describes the link and is the clientData for the trace  8 * set on the Tcl variable. eb 8 w */ a  8ut ) 8s typedef struct Link { 2 8, K Tcl_Interp *interp; /* Interpreter containing Tcl variable. */ tat; 8e,> char *addr; /* Location of C variable. */ D 8inI int type; /* Type of link (TCL_LINK_INT, etc.). */ tM 8L int writable; /* Zero means Tcl variable is read-only. */ V 8 e union { _ 8rc int i; /uh 8S/ double d; q 8L } lastValue; /* Last known value of C variable; used to z 8#i@ * avoid string conversions. */ /* 8 } Link; or 8bl h 8ct/* f t 8; * Prototypes for procedures referenced only in this file: e c 8tr */  8 * t 8leJstatic char * LinkTraceProc _ANSI_ARGS_((ClientData clientData,  8inJ Tcl_Interp *interp, char *name1, char *name2,  8le) int flags)); r 8@static char * StringValue _ANSI_ARGS_((Link *linkPtr, @ 8yp, char *buffer)); ( FwrS An example of a header page. Part of the text of the copyright notice has been 8 e@ FSomitted. The file HengManual/proto.cF contains a template for a header page. #e $Q!P0o Df[*b#e *bTuAbstractiaKGw#i O38KKKO38Kf|ver!`0o } !d!dTStringKVfXVfXwO38VfXKVfXK̰O38̰f|fd onK̭w trO38̭K̭KfCO38fCf|v̹8leKfdwePc O38KKf@O38f@f| K3 3wTcInO383 K3 Kf%O38f%f|~K2O3&w inO382K2KfO38ff|Gc !`"`0mk ~Q&0o Df[SSTh Copyright)!`"`0o xa!d!dTPRevision t"@!0o enDf[z"zTIncludes Te920o  coDf[@ge@gT Declarationsck+0 o Df[RckRTu PrototypeslH5Z!nD#i$$E Rd"m##lH#n" StlHE  UU C38cAbstract6: the first few lines give the name of the file and a brief description of the overall v̹#UU@ 69functions provided by the file, just as in header files. 82UU` COCopyright notice6: protects ownership of the file, just as in header files. ~AUU C2gRevision string6: similar to the revision strings in header files, except that its value is used to MUU 6_initialize a string variable. This allows the revision information to be checked in the executYUU@ 6dable object file. hUU CoaInclude statements6: all of the J#include6 statements for the file should appear on the tUU 6ar`header file just after the version string. In general there should be very few J#include6 nUU 6`statements in a given code file, typically just for the packages internal header file and portnGc$q! Gc UU38 8e /* fe 8amI *----------------------------------------------------------------------  8ed * he ! 8ea * Tcl_GetInt -- * 8ri * oti3 8wnA * Given a string, produce the corresponding integer value. < 86 * milE@ 8 * Results: erQ 8t C * The return value is normally TCL_OK; in this case *intPtr iabZ 8e C * will be set to the integer value equivalent to string. If 6dc 8. C * string is improperly formed then TCL_ERROR is returned and 6l 8he9 * an error message will be left in interp->result. lu 8er * str~ 8er * Side effects: w 8n * None.  8n  * en  8lyI *---------------------------------------------------------------------- q 8 */  8  8int  8#Tcl_GetInt(interp, string, intPtr) --- 8--N Tcl_Interp *interp; /* Interpreter to use for error reporting. */  8 I char *string; /* String containing a (possibly signed) r 8ndN * integer in a form acceptable to strtol. */  8 G int *intPtr; /* Place to store converted result. */ iab 8e {  8to ... er@ 8to} ( FB The header comments and declaration for a procedure. The file @ HAengManual/procheadF contains a template for this information. rH J K%s& trH J K UTUTh lENo: #  September 1, 1994  Running H/F 1  HH&s%' --HH UU` `6 H't&( Hrp,H$1'(s' H$1' nterUTUT` bEre tlH)n* chlH nipoUU` c6 l$1'*n)+ l$1' l.UTUT` dE  l+u*, /*laliabl J K,n+ l J K } UTUTh eEThG Tcl/Tk Engineering Manual  September 1, 1994  22  @ d-min.2inH$@3N `@.n/- &H-H-DFootnoteH2/n.1-UT00Footnotept 0u/1 --J sq<Q `@1v/2- J szJ szD TableFootnoteHA2n1-33 TableFootnote;~3u2 ;;d4mre56nl 5n64 l  UU` f51'"<$paranum><$paratext><$pagenum> UU` m6"<$paranum><$paratext><$pagenum> "UU` n6"<$paranum><$paratext><$pagenum> l arl `@6n54 l l DTable of Contents Specificationd7mTh89ngl u8n97 l u in` gF Level2IX ` oF Level1IX ` pF 1, 23 %` qFn$<$symbols><$numerics><$alphabetics> Fo:` rGLSymbols[\ ];Numerics[0];A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U;V;W;X;Y;Z `@E` sF <$pagenum> zR` t5tn lmV `@9n87 llDaIndex Specification~d:m;;<l ;n<: l  6` h5"<$paranum><$paratext><$pagenum> l ar `@<n;: ral l DnList of Figures Specificationad=m>?m>l >n?= ll  Ta` i5ec"<$paranum><$paratext><$pagenum> l arq `@?n>= ngl l D9List of Tables Specificationd@mAAl2lIAn@ lIC )n ` j9riTcl/Tk Engineering Manual > uKolJohn K. Ousterhout ;C;L@ uKM; ;Z k5Y;Sun Microsystems, Inc. <$h@ k5john.ousterhout@eng.sun.com `@` vD Introduction UU 6ec\This is a manual for people who are developing C code for Tcl, Tk, and their extensions and <UU 6bapplications. It describes a set of conventions for writing code and the associated test scripts. UU 6n`There are two reasons for the conventions. First, the conventions ensure that certain important ŪUU 6?]things get done; for example, every procedure must have documentation that describes each of ѪUU 6 ibits arguments and its result, and there must exist test scripts that exercise every line of code. ݪUU 6pe\Second, the conventions guarantee that all of the Tcl and Tk code has a uniform style. This 骤UU@ 6Emakes it easier for us to use, read, and maintain each others code. kUU U6l XMost of the conventions originated in the Sprite operating system project at U.C. BerkeSuUU U6c._ley. At the beginning of the Sprite project my students and I decided that we wanted a uniform  UU U6 i_style for our code and documentation, so we held a series of meetings to choose the rules. The UUUU U6ioaresult of these meetings was a document called ]The Sprite Engineering Manual6. None of us U%UU U6e _was completely happy with all the rules, but we all managed to live by them during the project UU1UU U6et^and I think everyone was happy with the results. When I started work on Tcl and Tk, I decided =UU U6mecto stick with the Sprite conventions. This document is based heavily on ]The Sprite Engineering IUU@ U]co Manual6. anUUU 6e YThere are few things that I consider non-negotiable, but the contents of this manual are aUU 6nt`one of them. I dont claim that these conventions are the best possible ones, but the exact conramUU 6t \ventions dont really make that much difference. The most important thing is that we all do anyUU 6e [things the same way. Given that the core Tcl and Tk code follows the conventions, changing serUU@ 6 c/the rules now would cause more harm than good. ultUU 6 wWPlease write your code so that it conforms to the conventions from the very start. For 6e UU 6apYexample, dont write comment-free code on the assumption that youll go back and put the UUU 6inXcomments in later once the code is working. This simply wont happen. Regardless of how UU 6ti\good your intentions are, when it comes time to go back and put in the comments youll find UU 6coZthat you have a dozen more important things to do; as the body of uncommented code builds ͪUU 6 taup, it will be harder and harder to work up the energy to go back and fix it all. One of the funt٪UU 6t bdamental rules of software is that its structure only gets worse over time; if you dont build it 媏UU 6t cright to begin with, it will never get that way later. When I write code I typically write the proe cUU@ 6ngDcedure headers for a whole file before I fill in any of the bodies. d.UU( 6 gThe rest of this document consists of 8 major parts. 6 Section2  discusses the overall strucUU UU 6 diture of a package and how to organize header files. 6 Section3  describes the structure of a C nUU 6hefcode file and how to write procedure headers. 6 Section4  desribes the Tcl/Tk naming conven!UU 6mektions. 6 Section5  presents low-level coding conventions, such as how to indent and where to put rta-UU 6s icurly braces. 6 Section6  contains a collection of rules and suggestions for writing comments. n9UU 6d o Section7  describes how to write and maintain test suites. 6 Section8  describes how to make e odBmCCt lHCnB halHA w.heUU 6UU_code portable without making it unreadable too. Section 9 contains a few miscellaneous topics, 6 UU@ 6 dsuch as keeping a change log. 6h ;D2 Packages and header files KUU <6 eTcl applications consist of collections of ]packages6. Each package provides code to implement WUU <6UUca related set of features. For example, Tcl itself is a package, as is Tk; various extensions such ingcUU <6UU\as Tcl-DP, TclX, Expect, and BLT are also packages. Packages are the units in which code is ndoUU <6ut_developed and distributed: a single package is typically developed by a single person or group sug{UU <6ngcand distributed as a unit. One of the best things about Tcl is that it is possible to combine many 6UU <6 d]independently-developed packages into a single application; packages should be designed with UU <6_this in mind. This section describes the file structure of packages with an emphasis on header ut UU <6leafiles; later sections discuss conventions for code files. You may also wish to review Chapter 31 nUU <6]of the Tcl book for additional information on packages, such as how to interface them to the cUU@ <6gerest of an application. esժUU` D[ Package prefixes U媝UU E6 fgEach package has a unique short ]prefix6. The prefix is used in file names, procedure names, and \asUU E6ec_variable names in order to prevent name conflicts with other packages. For example, the prefix eloUU E6d:lfor Tcl is Jtcl6; Tcls exported header file is called Jtcl.h6 and exported procedures and varias UU@ E6e (ables have names like JTcl_Eval6. le'UU` C[6Version numbers d7UU S6ve[Each package has a two-part version number such as 7.4. The first number (7) is called the 6CUU S6is\major version number and the second (4) is called the minor version number. The version num <OUU S6 s_ber changes with each public release of the package. If a new release contains only bug fixes, <[UU S6ooZnew features, and other upwardly compatible changes, so that code and scripts that worked gUU S6an^with the old version will also work with the new version, then the minor version number incresUU S6pr^ments and the major version number stays the same (e.g., from 7.4 to 7.5). If the new release UU S6toccontains substantial incompatibilities, so that existing code and scripts will have to be modified isUU S6s \to run with the new version, then the major version number increments and the minor version EUU@ S6am/number resets to zero (e.g., from 7.4 to 8.0). VeUU` =[Overall structure ŪUU >6wodA package typically consists of several code files, plus at least two header files, plus additional rsѪUU >6 sffiles for building and configuring the package, such as a JMakefile6 and a Jconfigure.in6 ݪUU >6 oefile for the Jautoconf6 program. The header files for a package generally fall into the followe骋UU@ >6bling categories: cUU F6mA ]package header file6, which is named after the package, such as Jtcl.h6 or Jtk.h6. This nUU F6aheader file describes all of the externally-visible features of the package, such as procedures, UU F6UU^global variables, and structure declarations. The package header file is eventually installed UU F6\in a system directory such as J/usr/local/include6; it is what clients of the package e (UU FJY#include6 in their C code. As a general rule of thumb, the package header file should v4UU F6_define as few things as possible: its very hard to change an exported feature since it breaks les@UU F6rsYclient code that uses the package, so the less you export, the easier it will be to make eLUU F6fi]changes to the package. Thus, for example, try not to make the internal fields of structures XUU@ F6fa!visible in package header files. >gUU G6eslAn ]internal header file6, which is typically J#include6d by all of the C files in the package. 6sUU G6ThdThe internal header file has a name like JtclInt.h6 or JtkInt.h6, consisting of the the sUU G6 dpackage prefix followed by JInt.h6. The internal header file describes features that are used ll~UU G6^in multiple files within the package but arent exported out of the package. For example, key dDm#iEEcolHEnD e lH!!#G FNUU 6 p]description of what the procedure does. This should not be a detailed description of how the tmw=UU 6it[procedure is implemented, but rather a high-level summary of its overall function. In some ne yw<UU 6on[cases, such as callback procedures, I recommend also describing the conditions under which heaw;UUH 6 oRthe procedure is invoked and who calls the procedure, as in 6 Figure4 . w:UU CUUbResults6: this portion of the header describes describes how the procedure affects things that w9UU 6ld_are immediately visible to its caller. This includes the return value of the procedure and any w8UU 6re^modifications made to the callers variables via pointer arguments, such as JintPtr6 in w7UUH 6 Figure3 . w6UU CaSide Effects6: the last part of the header describes changes the procedure makes to its interhw5UU 6cebnal state, which may not be immediately visible to the caller but will affect later calls to this w4UU 6 d^or other procedures. This section should not describe every internal variable modified by the w3UU 6 i]procedure. It should simply provide the sort of information that users of the procedure need ow2UUH 6inRin order to use the procedure correctly. See 6 Figure4  for an example. w1UU 6du^The file JengManual/prochead6 contains a template for a procedure header, which you can w0UU 6hotinclude from your editor to save typing. Follow the syntax of Figures 6 3  and 6 4  exactly (same urw/UU@ 6ce:indentation, double-dash after the procedure name, etc.). have an argument named Jinterp6, which is copied into a &UU 6 Elocal variable named JiPtr6 in order to access the contents of .0UU@ 6 the interpreter. i XhI̡Rn_Sb ouhI̡ c   UU` J tkwin ̡hSnRTb ct̡h c  UU 6/*?Used for variables of type JTk_Window6, which are opaque UU@ 6..1handles for the window structures managed by Tk. hI̡4TnSUb eI̡4 c  *UU` JwinPtr i̡4UnTb ̡4 c ̡UU 6BUsed for variables of type JTkWindow *6, which are pointers UU 6 w=to Tks internal structures for windows. Tk procedures often rUU 6re>take an argument named Jtkwin6 and immediately copy the &UU 6p@argument into a local variable named JwinPtr6 in order to am0UU@ 6 o-access the contents of the window structure. dVm̡WWoulHWnV clHI\ n 3̡UU` ][TGeneral considerations UU 6c\The ideal variable name is one that instantly conveys as much information as possible about op"UU 6UU_the purpose of the variable it refers to. When choosing names, play devils advocate with your e.UU 6]self to see if there are ways that a name might be misinterpreted or confused. Here are some :UU@ 6things to consider: cIUU 6ZAre you consistent? Use the same name to refer to the same thing everywhere. For example, UUU 6k`in the Tcl implementation the name Jinterp6 is used consistently for pointers to the user-edaUU 6 iavisible JTcl_Interp6 structure. Within the code for each widget, a standard name is always dmUU 6UU^used for a pointer to the widget record, such as JbutPtr6 in the button widget code and yUU@ J%menuPtr6 in the menu widget code. cUU 6]If someone sees the name out of context, will they realize what it stands for, or could they UU 6riYconfuse it with something else? For example, in Sprite the procedure for doing byte-swapUUU 6os]ping and other format conversion was originally called JSwap_Buffer6. When I first saw UU 6 tYthat name I assumed it had something to do with I/O buffer management, not reformatting. UU@ 6th9We subsequently changed the name to JFmt_Convert6. tǪUU 6e ZCould this name be confused with some other name? For example, its probably a mistake to ӪUU 6Jmhave two variables Js6 and Jstring6 in the same procedure, both referring to strings: it will be rߪUU 6 cWhard for anyone to remember which is which. Instead, change the names to reflect their to 몘UU 6 s[functions. For example, if the strings are used as source and destination for a copy operamenUU@ 6-tion, name them Jsrc6 and Jdst6. oUU 6eycIs the name so generic that it doesnt convey any information? The variable Js6 from the pre exUU 6he\vious paragraph is an example of this; changing its name to Jsrc6 makes the name less giUU@ 6wa,generic and hence conveys more information. <UUh ^[as Basic syntax rules doLUU 6an^Below are some specific rules governing the syntax of names. Please follow the rules exactly, XUU@ 6^since they make it possible to determine certain properties of a variable just from its name. gUU ~6UU\Variable names always start with a lower-case letter. Procedure and type names always start g sUU@ ~6l with an upper-case letter. d f 8be int counter; h 8thextern char *FindElement(); @ 8futypedef int Boolean; fUU 6se]In multi-word names, the first letter of each trailing word is capitalized. Do not use under6UU 6 oiscores as separators between the words of a name, except as described in rule 6 5  below and in UUH 66 Section4.3 . a` 8e int numWindows; itתUU 66eAny name that refers to a pointer ends in JPtr6. If the name refers to a pointer to a pointer, U㪊UU 6c hthen it ends in JPtrPtr6, and so on. There are two exceptions to this rule. The first is for varifo憎UU 6ctaables that are opaque handles for structures, such as variables of type JTk_Window6. These UU 6. _variables are actually pointers, but they are never dereferenced outside Tk (clients can never mesUU 6Zlook at the structure they point to except by invoking Tk macros and procedures). In this UU 6rndcase the JPtr6 is omitted in variable names. The second exception to the rule is for strings. d UU 6etbWe decided in Sprite not to require JPtr6 suffixes for strings, since they are always refer+UU 6ds^enced with pointers. However, if a variable holds a pointer to a string pointer, then it must 7UU@ 6 aphave the JPtr6 suffix (theres just one less level of JPtr6 for strings than for other structures). .E 8s TkWindow *winPtr; O 8UU char *name; iY@ 8trchar **namePtr; hegUU 6onZVariables that hold the addresses of procedures should have names ending in JProc6. sUU@ JchPtypedefs6 for these variables should also have names ending in JProc6. e  8 b:typedef void (Tk_ImageDeleteProc)(ClientData clientData); @ 8 Tk_ImageDeleteProc *deleteProc; oilH2XnZd aYYe Rs .f4YqX P.f4 ecce 8is% if (searchPtr->linesLeft <= 0) { e 8 n goto searchOver; u 8,  } ! 8r * 8en /* poi3 8K * The outermost loop iterates over lines that may potentially contain 6 a< 8G * a relevant tag transition, starting from the current segment in r oE 8. * the current line. dN 8 */ UUW 8 ` 8 *! segPtr = searchPtr->nextPtr; ai 8th while (1) { cer 8na /* { 84 * Check for more tags on the current line. al 8ng */ 6@ 8  b 8_I< for ( ; segPtr != NULL; segPtr = segPtr->nextPtr) { Tk 8de0 if (segPtr == searchPtr->lastPtr) {  8s ! goto searchOver; P 8 }  8 ...  8in } @ 8  } ( FveW Comments in code have the form shown above, using full lines, with lined-up stars, 3 F gthe H/*F and H*/F symbols on separate lines, and blank separator lines around each comment a r Fti`(except that the leading blank line can be omitted if the comment is at the beginning of a code @ F *block). l]2əxZnXd *]]e Rtrd[m \\lH\n[ lHJQWc gs^RT&UU( Ja #define6d constants and macros have names that are all capital letters, except for macros UU 6PtYthat are used as replacements for procedures, in which case you should follow the naming UU 6 \conventions for procedures. If names in all caps contain multiple words, use underscores to *UU@ 6separate the words. } 8 8 #define NULL 0 B 8en#define BUFFER_SIZE 1024 oL@ 8ll+#define Min(a,b) (((a) < (b)) ? (a) : (b)) ZUU 6FSNames of programs, Tcl commands, and keyword arguments to Tcl commands (such as Tk entfUU 6 `configuration options) are usually entirely in lower case, in spite of the rules above. The reaodrUU 6 bson for this rule is that these names are likely to typed interactively, and I thought that using ~UU 6]all lower case would make it easier to type them. In retrospect Im not sure this was a good sUU 6Zidea; in any case, Tcl procedure and variable names should follow the same rules as C proUU@ 6 cedures and variables. t aUUh _[me$ Names reflect package structure shĪUU 6mi_Names that are exported outside a single file must include the package prefix in order to make , uЪUU 6 _sure that they dont conflict with global names defined in other packages. The following rules ܪUU@ 6ER-define how to use package prefixes in names: ,몜UU 6bIf a variable or procedure or type is exported by its package, the first letters of its name must UU 6nt`consist of the package prefix followed by an underscore. Only the first letter of the prefix is ulUU 6odkever capitalized, and it is subject to the capitalization rules from  Section4.2 . The first letter thaUU 6UU\after the prefix is always capitalized. The first example below shows an exported variable, s UU@ 6UU>and the second shows an exported type and exported procedure. ) 8meextern int tk_numMainWindows; 3@ 8va+extern Tcl_Interp *Tcl_CreateInterp(void); eflAUU 6urcIf a module contains several files, and if a name is used in several of those files but isnt used ix MUU 6 uWoutside the package, then the name must have the package prefix but no underscore. The ckaYUU 6 r]prefix guarantees that the name wont conflict with a similar name from a different package; eUU@ 6 pJthe missing underscore indicates that the name is private to the package. s` 8 1extern void TkEventDeadWindow(TkWindow *winPtr); uUU 6e [If a name is only used within a single procedure or file, then it need not have the module theUU 6leWprefix. To avoid conflicts with similar names in other files, variables and procedures alUU 6Th^declared outside procedures must always be declared Jstatic6 if they have no module preUU@ 6d fix. d` 8static int initialized; k_ЪUU` [Standard names +ex઎UU 6cl[The following variable names are used consistently throughout Tcl and Tk. Please use these me 쪍UU 6 oZnames for the given purposes in any code you write, and dont use the names for other purUUH 6 p poses.  und3]qZ r3 nfit 8ro/* iff 8F * The following structure defines a variable trace, which is used to  8. K * invoke a specific C procedure whenever certain operations are performed ! 8 n * on a variable. * 8du */ fi3 8ot v< 8typedef struct VarTrace { E 8itK Tcl_VarTraceProc *traceProc;/* Procedure to call when operations given 6ThN 8 pJ * by flags are performed on variable. */ W 8d @ ClientData clientData; /* Argument to pass to proc. */ UU` 8 nF int flags; /* What events the trace procedure is i 8t H * interested in: OR-ed combination of pur 8 yJ * TCL_TRACE_READS, TCL_TRACE_WRITES, and { 88 * TCL_TRACE_UNSETS. */  8J struct VarTrace *nextPtr; /* Next in list of traces associated with  8ac= * a particular variable. */ C@ 8r } VarTrace; io( FM Use side-by-side comments when declaring structure members and procedure @ F arguments. tyHI̡ ^n_b HI̡ c /*duUU` JernextPtr en h̡H _n^Rb ̡H c d iaUU 6BA field with this name is used in structures to point to the next UU 6Astructure in a linked list. This is usally the last field of the pUU@ 6 structure. H  lHf fC`nfesaag Rtifaq` f DS TR 87if ((linePtr->position.lineIndex > position.lineIndex) TRA 8@ || ((linePtr->position.lineIndex == position.lineIndex) of 8 w< && ((linePtr->position.charIndex + linePtr->length) p! 8. " > position.charIndex))) { * 8 return; si3 8s } < 8re-line = Mx_GetLine(newPtr->fileInfoPtr->file, rE 84 linePtr->position.lineIndex, (int *) NULL); N 86XDrawImageString(mxwPtr->display, mxwPtr->fileWindow, W 8 8 mxwPtr->textGc, x, y + mxwPtr->fontPtr->ascent, `@ 8el control, 2); dsh Fpo. Continuation lines are indented 8 spaces. dbmhecclHcnb  lH^U\e ^RTXZ%wh aDq! Low-level coding conventions UU 6`This section describes several low-level syntactic rules for writing C code. The reason for havUU 6 ding these rules is not because theyre better than all other ways of structuring code, but in order ->UU@ 6 +$to make all our code look the same. . ªUUh w[on Indents are 4 spaces ҪUU 6rn^Each level of indentation should be four spaces. There are ways to set 4-space indents in all ުUU 6`editors that I know of. Be sure that your editor really uses four spaces for the indent, rather PtꪚUU 6->_than just displaying tabs as four spaces wide; if you use the latter approach then the indents UU@ 6 0will appear eight spaces wide in other editors. tiUUh x[te$ Code comments occupy full lines $UU 6cZComments that document code (as opposed to declarations) should occupy full lines, rather 0UU 6^than being tacked onto the ends of lines containing code. The reason for this is that side-by-<UU 6 s^side comments are hard to see, particularly if neighboring statements are long enough to overHUU 6reclap the side-by-side comments. Comments must have exactly the structure shown in  Figure5 , coTUU 6. qincluding a leading J/*6 line, a trailing J*/6 line, and additional blank lines above and below. The e`UU 6tocleading blank line can be omitted if the comment is at the beginning of a block, as is the case in alllUU 6 fathe second comment in  Figure5 . Each comment should be indented to the same level as the xUU 6ro[surrounding code. Use proper English in comments: write complete sentences, capitalize the tiUUH 6te,first word of each sentence, and so on.  UU` y[en&Declaration comments are side-by-side UU 6ocWWhen documenting the arguments for procedures and the members of structures, place the ntaUU 6aslcomments on the same lines as the declarations. Figures  3  and  4  show comments for procedure taʪUU 6noharguments and  Figure6  shows a simple structure declaration . The format for comments is the sh֪UU 65asame in both cases. Place the comments to the right of the declarations, with all the left edges a⪉UU 6neZof all the comments lined up. When a comment requires more than one line, indent the addiUU 6nimtional lines to the same level as the first line, with the closing J*/6 on the same line as the end of sUU 6to`the text. For structure declarations it is usually useful to have a block of comments preceding itUU 6esjthe declaration, as in 6 Figure6 . This comments before the declaration use the format given in UUH 6en Section5.2 . 0UU` z[Wh*Curly braces: { goes at the end of a line @UU 6 s^Open curly braces should not appear on lines by themselves. Instead, they should be placed at LUU 6d athe end of the preceding line. Close curly braces always appear as the first non-blank character aXUU 6deron a line.  Figure5  shows how to use curly braces in statements such as Jif6 and Jwhile6, and dUU 6ram Figure6  shows how curly braces should be used in structure declarations. If an Jif6 statement epUU 6deshas an Jelse6 clause then Jelse6 appears on the same line as the preceding J}6 and the following e s|~UU Jd h{6. Close curly braces are indented to the same level as the outer code, i.e., four spaces less than me}UU@ 6the statements they enclose. oddms eecllHend lHXZcg XZ zwUU 6: ]The only case where a { appears on a line by itself is the initial { for the body of a procebwUUH 6ea4dure (see Figures 6 3  and 6 4 ). enwUU 6 lXAlways use curly braces around compound statements, even if there is only one statement de wUU@ 6ig1in the block. Thus you shouldnt write code like tm` 86'if (filePtr->numLines == 0) return -1; 6ra%wUU` 6 s but rather y b3l 8edif (filePtr->numLines == 0) { =l 8me return -1; Gl@ 8ls} UwUU 6el]This approach makes code less dense, but it avoids potential mistakes when adding additional awUU 6 cclines to an existing single-statement block. It also makes it easier to set breakpoints in a debugUUmwUU 6em`ger, since it guarantees that each statement on is on a separate line and can be named individunywUU@ 6ally. dfmXgg lHgnf arlH``ei t%y UU 6hThere is one exception to the rule about enclosing blocks in J{}6. For Jif6 statements with bUU@ 6unQcascaded Jelse6 Jif6 clauses, you may use a form like the following: ofA 8dn&if (strcmp(argv[1], "delete") == 0) { fA 8Li ... refA 8*} else if (strcmp(argv[1], "get") == 0) { fA 8>n ... 0fA 8 *} else if (strcmp(argv[1], "set") == 0) { fA 8  ... afA 8 l } else { bfA 8ti ... s fA@ 8on} UUh {[ c- Continuation lines are indented 8 spaces I*UU |6si\You should use continuation lines to make sure that no single line exceeds 80 characters in ta6UU |6se^length. Continuation lines should be indented 8 spaces so that they wont be confused with an BUU |6giimmediately-following nested block (see  Figure7  ). Pick clean places to break your lines for NUU |6e acontinuation, so that the continuation doesnt obscure the structure of the statement. For exambZUU |6unbple, if a procedure call requires continuation lines, make sure that each argument is on a single fUU |6rgnline. If the test for an Jif6 or Jwhile6 command spans lines, try to make each line have the same rUU |6anesting level of parentheses if possible. I try to start each continuation line with an operator ~UU |6fAysuch as J*6, J&&6, or J||6; this makes it clear that the line is a continuation, since a new statement lUU@ |68 )would never start with such an operator. eUU` [s &Avoid macros except for simple things UU Jta_#define6 statements provide a fine mechanism for specifying constants symbolically, and you e cUU 6Zshould always use them instead of embedding specific numbers in your code. However, it is UU 6ur_generally a bad idea to use macros for complex operations; procedures are almost always better ctuUU 6t.^(for example, you can set breakpoints inside procedures but not in the middle of macros). The UU 6ntgonly time that it is OK to use J#define6s for complex operations is if the operations are critilinUU 6ch[cal to performance and there is no other way to get the performance (have you measured the staUU@ 6on6performance before and after to be sure it matters?).  UU` 6,OWhen defining macros, remember always to enclose the arguments in parentheses: staf.` 8UU+#define Min(a,b) (((a) < (b)) ? (a) : (b)) ato(UU 6 hOtherwise, if the macro is invoked with a complex argument such as Ja*b6 or Jsmall||red6 it ch4UU@ 6ng]may result in a parse error or, even worse, an unintended result that is difficult to debug. eXf,h Dbe Documenting code rmUU 6UU[The purpose of documentation is to save time and reduce errors. Documentation is typically wayyUU 6]used for two purposes. First, people will read the documentation to find out how to use your mUU 6]code. For example, they will read procedure headers to learn how to call the procedures. Ide dhmUUiirmlHinh gelHgk ta4UU 6orfally, people should have to learn as little as possible about your code in order to use it correctly. UU 6 a_Second, people will read the documentation to find out how your code works internally, so they (UU 6OtZcan fix bugs or add new features; again, good documentation will allow them to make their *UU 6Xfixes or enhancements while learning the minimum possible about your code. More documenfi6UU 6f,]tation isnt necessarily better: wading through pages of documentation may not be any easier oBUU 6uc^than deciphering the code. Try to pick out the most important things that will help people to NUU@ 6oc?understand your code and focus on these in your documentation. e. lUU` [wi!Document things with wide impact h|UU 6ce[The most important things to document are those that affect many different pieces of a proUU 6bgram. Thus it is essential that every procedure interface, every structure declaration, and every UU 6bl`global variable be documented clearly. If you havent documented one of these things it will be dUU 6ndbnecessary to look at all the uses of the thing to figure out how its supposed to work; this will UU@ 6cu#be time-consuming and error-prone. ir UU 6VOn the other hand, things with only local impact may not need much documentation. For ĪUU 6 ^example, in short procedures I dont usually have comments explaining the local variables. If ЪUU 6 ^the overall function of the procedure has been explained, and if there isnt much code in the ܪUU 6 ^procedure, and if the variables have meaningful names, then it will be easy to figure out how 誙UU 6 w]they are used. On the other hand, for long procedures with many variables I usually document aUU 6s ^the key variables. Similarly, when I write short procedures I dont usually have any comments UU 6ra]in the procedures code: the procedure header provides enough information to figure out what u UU 6e \is going on. For long procedures I place a comment block before each major piece of the proguUU@ 6pp:cedure to clarify the overall flow through the procedure. 6UU` [e.%Dont just repeat whats in the code hFUU 6nl^The most common mistake I see in documentation (besides it not being there at all) is that it RUU 6al`repeats what is already obvious from the code, such as this trivial (but exasperatingly common) th^UU@ 6en example: l H m/* odev 8UU * Increment i. e, 8  */ m 8he t@ 8igi += 1; w UU 6 w^Documentation should provide higher-level information about the overall function of the code, UU 6s ]helping readers to understand what a complex collection of statements really means. For exam UU@ 6raple, the comment s 8re/* er  8fo: * Probe into the hash table to see if the symbol exists. @ 8ur */ laꪍUU` 6 b'is likely to be much more helpful than  8re/* lar 8owA * Mask off all but the lower 8 bits of x, then index into table t  8< * t, then traverse the list looking for a character string on 8ei * identical to s. hat @ 8  */ re.UU` 6adUEverything in this second comment is probably obvious from the code that follows it. U:UU 6 VAnother thing to consider in your comments is word choice. Use different words in the FUU 6Ycomments than the words that appear in variable or procedure names. For example, the comiRUU@ 6foment ` 8fu/* n oj 8 * VmMapPage -- int 8st * hat~ 8io * Map a page. m@ 8 * ... @ djmkklHknj shlHim 2 UU 6Xwhich appears in the header for the Sprite procedure VmMapPage, doesnt provide any new UU 6as\information. Everything in the comment is already obvious from the procedures name. Here raUU@ 6kiis a much more useful comment: , 8de/* l t6 8 * VmMapPage -- @ 8Ev * ingJ 8mmA * Make the given physical page addressable in the kernels UT 8th@ * virtual address space. This procedure is used when the ds^ 8UU. * kernel needs to access a users page. h@ 8du * ... FovUU 6iiThis comment tells ]why6 you might want to use the procedure, in addition to ]what6 it does, UU@ 6*which makes the comment much more useful. UU` [ *)Document each thing in exactly one place UU 6`Systems evolve over time. If something is documented in several places, it will be hard to keep UU 6h Xthe documentation up to date as the system changes. Instead, try to document each major ȪUU 6rmadesign decision in exactly one place, as near as possible to the code that implements the design UԪUU 6h ^decision. For example, put the documentation for each structure right next to the declaration ઠUU 6 *cfor the structure, including the general rules for how the structure is used. You need not explain 쪟UU 6vi`the fields of the structure again in the code that uses the structure; people can always refer tUU 6pa`back to the structure declaration for this. The principal documentation for each procedure goes wUU 6ce]in the procedure header. Theres no need to repeat this information again in the body of the mUU 6_procedure (but you might have additional comments in the procedure body to fill in details not tiUU 6s ]described in the procedure header). If a library procedure is documented thoroughly in a man (UU 6sy`ual entry, then I may make the header for the procedure very terse, simply referring to the manly4UU 6r ]ual entry. For example, I use this terse form in the headers for all Tcl command procedures, ,@UU@ 6ti@since there is a separate manual entry describing each command. LUU 6ct^The other side of this coin is that every major design decision needs to be documented ]at XUU ]figleast6 once. If a design decision is used in many places, it may be hard to pick a central place to dUU 6st]document it. Try to find a data structure or key procedure where you can place the main body UpUU 6robof comments; then reference this body in the other places where the decision is used. If all else |UU@ 6utafails, add a block of comments to the header page of one of the files implementing the decision. UU` [ tWrite clean code )UU 6ceYThe best way to produce a well-documented system is to write clean and simple code. This eUU 6oc\way there wont be much to document. If code is clean, it means that there are a few simple I ªUU 6m _ideas that explain its operation; all you have to do is to document those key ideas. When writanuΪUU 6g `ing code, ask yourself if there is a simple concept behind the code. If not, perhaps you should ioڪUU 6mecrethink the code. If it takes a lot of documentation to explain a piece of code, it is a sign that be檌UU@ 6nt6you havent found an elegant solution to the problem. UU` [ctDocument as you go wheUU 6he_It is extremely important to write the documentation as you write the code. Its very tempting th UU 6. _to put off the documentation until the end; after all, the code will change, so why waste time fi,UU 6he[writing documentation now when youll have to change it later? The problem is that the end duc8UU 6d \never comes there is always more code to write. Also, the more undocumented code that you toDUU 6 i[accumulate, the harder it is to work up the energy to document it. So, you just write more opePUU 6ve_undocumented code. Ive seen many people start a project fully intending to go back at the end if \UU@ 6coLand write all the documentation, but Ive never seen anyone actually do it. inhUU 6taUIf you do the documentation as you go, it wont add much to your coding time and you UtUU 6n_wont have to worry about doing it later. Also, the best time to document code is when the key UUUU 6tr\ideas are fresh in your mind, which is when youre first writing the code. When I write new UU 6ut_code, I write all of the header comments for a group of procedures before I fill in any of the dlmn mmo lHmnl atlHko me2erUU 6odbbodies of the procedures. This way I can think about the overall structure and how the pieces fit UU@ 6thMtogether before getting bogged down in the details of individual procedures. u0UU` [seDocument tricky situations t f@UU 6go^If code is non-obvious, meaning that its structure and correctness depend on information that LUU 6it_wont be obvious to someone reading it for the first time, be sure to document the non-obvious tiXUU 6binformation. One good indicator of a tricky situation is a bug. If you discover a subtle property dUU 6\of your program while fixing a bug, be sure to add a comment explaining the problem and its I pUU 6asolution. Of course, its even better if you can fix the bug in a way that eliminates the subtle n|UU@ 6*behavior, but this isnt always possible. h D  Testing UU 6bOne of the environments where Tcl works best is for testing. If all the functionality of an appliUU 6 o_cation is available as Tcl commands, you should be able to write Tcl scripts that exercise the inͪUU 6dicapplication and verify that it behaves correctly. For example, Tcl contains a large suite of tests is٪UU 6in`that exercise nearly all of the Tcl functionality. Whenever you write new code you should write io媝UU 6indTcl test scripts to go with that code and save the tests in files so that they can be re-run later. gUU 6 t`Writing test scripts isnt as tedious as it may sound. If youre developing your code carefully whUU 6beeyoure already doing a lot of testing; all you need to do is type your test cases into a script file  UU 6 c\where they can be re-used, rather than typing them interactively where they vanish into the snUU@ 6. void after theyre run. Te3UU` [UUBasics bOnCUU 6nteTests should be organized into script files, where each file contains a collection of related tests. nOUU 6cliIndividual tests should be based on the procedure Jtest6, just like in the Tcl and Tk test suites. n[UU@ 6ehHere are two examples: le,i 8rg+test expr-3.1 {floating-point operators} { t es 8 o expr 2.3*.6 al} 8wr} 1.38 ode 8io+test expr-3.2 {floating-point operators} { wit 8 ' list [catch {expr 2.3/0} msg] $msg e-r@ 8} {1 {divide by zero}} t sUU Jdiqtest6 is a procedure defined in a script file named Jdefs6, which is Jsource6d by each test file. UU Jeegtest6 takes four arguments: a test identifier, a string describing the test, a test script, and the er UU 6nthexpected result of the script. Jtest6 evaluates the script and checks to be sure that it produces UUͪUU@ 6Ethe expected result. If not, it prints a message like the following: i 8ec'==== expr-3.1 floating-point operators 6cl 8 s==== Contents of test case: e  8 l  8te expr 2.3*.6  8 a t  8==== Result was: e 8in1.39 ! 8---- Result should have been: + 8 1.38 5@ 8---- expr-2.1 FAILED CUU 6erhTo run a set of tests, you start up the application and Jsource6 a test file. If all goes well no viOUU@ 6Lmessages appear; if errors are detected, a message is printed for each one. ef[UU 6J`The test identifier, such as Jexpr-3.16, is printed when errors occur. It can be used to figUU 6ibgsearch a test script to locate the source for a failed test. The first part of the identifier, such as evsUU J acexpr6, should be the same as the name of the test file, except that the test file should have a a mUU Jlld.test6 extension, such as Jexpr.test6. The two numbers allow you to divide your tests into teUU 6e ogroups. The tests in a particular group (e.g., all the Jexpr3.]n6 tests) relate to a single sub-fea= Rdnm1.oolHonn lHmq 1 eUU 6`ture, such as a single C procedure or a single option of a Tcl command. The tests should appear leUU@ 6 n5in the test file in the same order as their numbers. eUU 6geWThe test name, such as Jfloating-point operators6, is printed when errors occur. .1*UU@ 6enMIt provides human-readable information about the general nature of the test. t6UU 6e _Before writing tests I suggest that you look over some of the test files for Tcl and Tk to see houBUU 6thfhow they are structured. You may also want to look at the JREADME6 files in the Tcl and Tk test NUU 6eddirectories to learn about additional features that provide more verbose output or restrict the set teZUU@ 6r of tests that are run. expxUU` [tsOrganizing tests eUU 6`Organize your tests to match the code being tested. The best way to do this is to have one test UU 6qcfile for each source code file, with the name of the test file derived from the name of the source TclUU 6s Rfile in an obvious way (e.g. JtextWind.test6 contains tests for the code in UU >UUcJtkTextWind.c6). Within the test file, have one group of tests for each procedure (for exam*UU 6It[ple, all the JtextWind-2.]n6 tests in JtextWind.test6 are for the procedure 6e ĪUU Jes]TkTextWindowCmd6). The order of the tests within a group should be the same as the order ЪUU 6 saof the code within the procedure. This approach makes it easy to find the tests for a particular UܪUU@ 6ie5piece of code and add new tests as the code changes. v誙UU 6es]The Tcl test suite was written a long time ago and uses a different style where there is one gUU 6UU]file for each Tcl command or group of related commands, and the tests are grouped within the eUU 6`file by sub-command or features. In this approach the relationship between tests and particular o UU 6bpieces of code is much less obvious, so it is harder to maintain the tests as the code evolves. I UU@ 6UU3dont recommend using this approach for new tests. one6UU` [r Coverage uFUU 6\When writing tests, you should attempt to exercise every line of source code at least once. tRUU 6`There will be occasionally be code that you cant exercise, such as code that exits the applicaas^UU 6^tion, but situations like this are rare. You may find it hard to exercise some pieces of code jUU 6]because existing Tcl commands dont provide fine enough control to generate all the possible hvUU 6ascexecution paths (for example, at the time I wrote the test suite for Tcls dynamic string facility r eUU 6 g_there were very few Tcl commands using the facility; some of the procedures were not called at -coUU 6 Iaall). In situations like this, write one or more new Tcl commands just for testing purposes. For eUU 6ouSexample, the file JtclTest.c6 in the Tcl source directory contains a command 3doUU Jg _testdstring6, which provides a number of options that allow all of the dynamic string code g tUU 6ttjto be exercised. JtclTest.c6 is only included in a special testing version of Jtclsh6, so the UU Jca\testdstring6 command isnt present in normal Tcl applications. Use a similar approach in lʪUU@ 6 YRyour own code, where you have an extra file with additional commands for testing. ֪UU 6s `Its not sufficient just to make sure each line of code is executed by your tests. In addition, th⪆UU 6 t_your tests must discriminate between code that executes correctly and code that isnt correct. ereUU 6ansFor example, write tests to make sure that the Jthen6 and Jelse6 branches of each Jif6 statement is,UU 6`are taken under the correct conditions. For loops, run different tests to make the loop execute t.UU 6ou`zero times, one time, and two or more times. If a piece of code removes an element from a list, r UU 6lo`try cases where the element to be removed is the first element, last element, only element, and lyUU 6cifneither first element nor last. Try to find all the places where different pieces of code interact in *UU@ 6ic@unusual ways, and exercise the different possible interactions. cHUU` [e Memory allocation X~UU 6 fZTcl and Tk use a modified memory allocator that checks for several kinds of memory allocad}UU 6tebtion errors, such as freeing a block twice, failing to free a block, or writing past the end of a p|UU 6harblock. In order to use this allocator, dont call Jmalloc6, Jfree6, or Jrealloc6 directly. Call |{UU Jh pckalloc6 instead of Jmalloc6, Jckfree6 instead of Jfree6, and Jckrealloc6 instead of tszUU Jexrrealloc6. These procedures behave identically to Jmalloc6, Jfree6, and Jrealloc6 except that dpmtrqqenlHqnp ntlHos  UU 6t kthey monitor memory usage. JCkalloc6, Jckfree6, and Jckrealloc6 are actually macros that @unUU 6er`can be configured with a compiler switch: if JTCL_MEM_DEBUG6 is defined, they perform the UU 6se^checks but run more slowly and use more memory; if JTCL_MEM_DEBUG6 is not defined, then *UU 6h tthe macros are just J#define6d to Jmalloc6, Jfree6, and Jrealloc6 so there is no penalty in to6UU 6r,Zefficiency. I always run with JTCL_MEM_DEBUG6 in my development environment and you BUU@ 6inOshould too. Official releases typically do not have JTCL_MEM_DEBUG6 set. cNUU 6zWIf you set JTCL_MEM_DEBUG6 anywhere in your code then you must set it everywhere frZUU 6al](including the Tcl and Tk libraries); the memory allocator will get hopelessly confused if a fUU 6ntkblock of memory is allocated with Jmalloc6 and freed with Jckfree6, or allocated with JckallocrUU@ J6%loc6 and freed with Jfree6. c~UU !6_There is nothing equivalent to Jcalloc6 in the debugging memory allocator. If you need a peUU@ !6Cnew block to be zeroed, call Jmemset6 to clear its contents. TCLUU 6no_If you compile with JTCL_MEM_DEBUG6, then an additional Tcl command named Jmemory6 frUU 6al\will appear in your application (assuming that youre using the standard Tcl or Tk main proL_UUH 6y Agram). The Jmemory6 command has the following options:  fUU "6 TThe debugging memory allocator is inferior in many ways to commercial products like CLUU "6wh[Purify, so its worth using one of the commercial products if possible. Even so, please use andUU "Je cckalloc6 and Jckfree6 everywhere in your code, so that other people without access to the d wUU@ "6 a?commercial checkers can still use the Tcl debugging allocator. 2UU` [6 Fixing bugs thBUU #6^Whenever you find a bug in your code it means that the test suite wasnt complete. As part of NUU #6pe_fixing the bug, you should add new tests that detect the presence of the bug. I recommend writZUU #6ouking the tests after youve located the bug but ]before6 you fix it. That way you can verify that the 6alfUU #6ouYbug happens before you implement the fix and goes away afterwards, so youll know youve rUU #6J]really fixed something. Use bugs to refine your testing approach: think about what you might a~UU #6or]be able to do differently when you write tests in the future to keep bugs like this one from eUU@ #6 pgoing undetected. drmUUssanlHsnr r lHq to. wUU` $[ aTricky features erUU %6e ^I also use tests as a way of illustrating the need for tricky code. If a piece of code has an "UU %6oudunusual structure, and particularly if the code is hard to explain, I try to write additional tests yo.UU %6es\that will fail if the code is implemented in the obvious manner instead of using the tricky s :UU %6ed[approach. This way, if someone comes along later, doesnt understand the documentation for 6ouFUU %6re]the code, decides the complex structure is unnecessary, and changes the code back to the simeRUU %6ngbple (but incorrect) form, the test will fail and the person will be able to use the test to under^UU %6y _stand why the code needs to be the way it is. Illustrative tests are not a substitute for good ndejUU@ %63documentation, but they provide a useful addition. HUU` [Test independence UU 6_Try to make tests independent of each other, so that each test can be understood in isolation. s aUU 6atXFor example, one test shouldnt depend on commands executed in a previous test. This is ctUU 6rlaimportant because the test suite allows tests to be run selectively: if the tests depend on each UU 6s _other, then false errors will be reported when someone runs a few of the tests without the othhisȪUU@ 6omers. gԪUU '6de\For convenience, you may execute a few statements in the test file to set up a test configuisચUU '6chbration and then run several tests based on that configuration. If you do this, put the setup code 쪙UU '6 bjoutside the calls to the Jtest6 procedure so it will always run even if the individual tests arent UU '6 aarun. I suggest keeping a very simple structure consisting of setup followed by a group of tests. UU '6\Dont perform some setup, run a few tests, modify the setup slightly, run a few more tests, eUU '6deamodify the setup again, and so on. If you do this, it will be hard for people to figure out what eUU@ '6s bthe setup is at any given point and when they add tests later they are likely to break the setup. @h Ds  Porting issues UUU (6r,YThe X Window System, ANSI C, and POSIX provide a standard set of interfaces that make it saUU (6om^possible to write highly portable code. However, some additional work will still be needed if mUU (6coXcode is to port among all of the UNIX platforms. As Tcl and Tk move from the UNIX world n.yUU (6ut[onto PCs and Macintoshes, porting issues will become even more important. This section conillUU@ (6f Ptains a few tips on how to write code that can run on many different platforms. mpUU` [stStick to standards byUU &6 `The easiest way to make your code portable is to use only library interfaces that are available feUU &6Yeverywhere (or nearly everywhere). For example, the ANSI C library procedures, POSIX syso˪UU &6wh_tem calls, and Xlib windowing calls are available on many platforms; if you code to these stanlikתUU &6et\dards your packages will be quite portable. Avoid using system-specific library procedures, I 㪊UU@ &6de,since they will introduce porting problems. UU` )[poMinimize #ifdefs hUU *6HoWAlthough there will be situations where you have to do things differently on different amUU *6X cmachines, J#ifdef6s are rarely the best way to deal with these problems. If you load up your ort)UU *6coccode with J#ifdef6 statements based on various machines and operating systems, the code will de 5UU *6nylturn into spaghetti. J#ifdef6s make code unreadable: it is hard to look at J#ifdef6-ed code and akAUU *6leafigure out exactly what will happen on any one machine. Furthermore, J#ifdef6s encourage a MUU *6xabstyle where lots of machine dependencies creep all through the code; it is much better to isolate YUU@ *6e 3machine dependencies in a few well-defined places. eUU +6s ]Thus you should almost never use J#ifdef6s. Instead, think carefully about the ways in qUU +6e Zwhich systems differ and define procedural interfaces to the machine-dependent code. Then }UU +6 tYprovide a different implementation of the machine-dependent procedures for each machine. U~UU +6, ZWhen linking, choose the version appropriate for the current machine. This way all of the +34H!tn Ju Hba@Jupwt in@J *Btu ?8 /* fde ?8nr * tcl.h -- h ?8# * 6! ?8E * This header file describes the externally-visible facilities e* ?8# * of the Tcl interpreter. UU3 ?8er * s o< ?8ciH * Copyright (c) 1987-1994 The Regents of the University of California. *E ?8nd * All rights reserved. edN ?8 * +W ?8ulG * Permission is hereby granted, without written agreement and without ys ` ?8 +F * license or royalty fees, to use, copy, modify, and distribute this i ?8 TE * software and its documentation for any purpose, provided that the hr ?8edE * above copyright notice and the following two paragraphs appear in v{ ?8 f * all copies of this software. ll ?8 * tn ?8M * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR  ?8 *O * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT  ?8P * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF ti ?8 ?B * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  ?8ci * Cop ?894G * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, All ?8edL * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY te ?8 aM * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS e ?8d N * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO  ?8thJ * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.  ?8r  * { ?8 *O * $Header: /user6/ouster/tcl/RCS/tcl.h,v 1.139 94/05/26 14:40:43 ouster Exp $ M * ?8 TSPRITE (Berkeley)  ?8TO */ AR  ?8 ? ?8ND #ifndef _TCL  ?8SE #define _TCL S& ?8 / ?8F #define TCL_VERSION "7.4" 8 ?8, #define TCL_MAJOR_VERSION 7 A ?8 *#define TCL_MINOR_VERSION 4 F J ?8 S S ?8... ci\ ?8 ?e ?8RS/* F Cn ?8AL< * The structure returned by Tcl_GetCmdInfo and passed into DIw ?8D  * Tcl_SetCmdInfo: NTI ?8IT */  ?8 * D ?8TItypedef struct Tcl_CmdInfo { O ?8 eQ Tcl_CmdProc *proc; /* Procedure that implements command. */ N ?8I ClientData clientData; /* ClientData passed to proc. */ R ?8J Tcl_CmdDeleteProc *deleteProc; /* Procedure to call when command  ?894: * is deleted. */  ?8P ClientData deleteData; /* Value to pass to deleteProc (usually  ?8#dG * the same as clientData). */ SIO ?8} Tcl_CmdInfo; TC ?8  ?8#d... TC ?8F   ?8 (EXTERN int tcl_AsyncReady; ? ?8 ? ?8... ? ?8tu r ?8CmOEXTERN int Tcl_Eval _ANSI_ARGS_((Tcl_Interp *interp, char *cmd)); ?" ?8 + ?8... ?4 ?8ct l=@ ?8#endif /* _TCL */ P( KF \ An example of a header file. The file HengManual/proto.hF contains a template for liZ@ KF header files. dvm ?ePK+3,wwuxt tcaO3&KK.O3&.fj #e a!P0xowyt leDf[z#e zT?AbstractClK93ywxzt/*alO3&9K9ĶO3&̧fj ?Krzwy{t  O3&rKrKoO3&ofj~Kl{wz|tO3&lKlK#iO3&#ifjəxK*̛|w{}tEXRNO3&*̛K*̛KGcO3&Gcfj̧ ?K`̒zfR}w|t ?O3&`̒K`̒K2O3&2fj̞intM&0~ot ((Df[zzTr Copyright?;$0o}t @@T Structuret%0n0ot * %6%6TKVersionAn%g+ UR00ot e %g+%g+TFMultiple a!X"`0o~t !d!dTRevisionmlHnv lHs UU2UU +63&`machine dependencies for a particular system are located in one or a few files that are totally UU +6zZseparate from the machine-dependent code for other systems and from the main body of your UU@ +63&acode. The only conditional code left will be the code that selects which version to link with. *UU 26i\You wont be able to eliminate J#ifdef6s completely, but please avoid them as much as fj6UU 26epossible. If you end up with code that has a lot of J#ifdef6s, this should be a warning to you 0BUU 26((^that something is wrong. See if you can find a way to re-organize the code (perhaps using the NUU@ 26nUtechniques described later in this section) to reduce the number of J#ifdef6s. lUU` [#Organize by feature, not by system "`|UU -6cDont think about porting issues in terms of specific systems. Instead, think in terms of specific UU -] "_features6 that are present or absent in the systems. For example, dont divide your code up w fUU -6ll[according to what is needed in HP-UX versus Solaris versus Windows. Instead, consider what thUU -6r dfeatures are present in the different systems; for example, some systems have a Jwaitpid6 proonUU -6\cedure, while others dont yet provide one, and some systems have ANSI C compilers that supthUU@ -66port procedure prototypes, while some systems do not. ĪUU .6#iVThe feature-based approach has a number of advantages over the system-based approach. ЪUU .6fiYFirst, many systems have features in common, so you can share feature-based porting code bܪUU .6ec^among different systems. Second, if you think in terms of features then you can consider each 誙UU .6ffeature separately (what do I do if there is no Jwaitpid6?); this replaces one large problem UU .6dwith several smaller problems that can be dealt with individually. Lastly, the Jautoconf6 proodUU .6UU`gram can be used to check for the presence or absence of particular features and configure your at UU .6 -^code automatically. Once youve gotten your code running on several different systems, youll UU .6^find that many new systems can be handled with no additional work: their features are similar $UU@ .6bto those in systems youve already considered, so Jautoconf6 can handle them automatically. BUU` [asUse emulation RUU 06ys\One of the cleanest ways to handle porting problems is with emulation: assume the existence ca^UU 06se_of certain procedures, such as those in the POSIX standard, and if they dont exist on a given eatjUU 06co_system then write procedures to emulate the desired functionality with the facilities that are 6?vUU 06on_present on the system. For example, when Tcl first started being used widely I discovered that duaUU 06Jcmany systems did not support the Jwaitpid6 kernel call, even though it was part of the POSIX rtiUU 06 c^standard. So, I wrote a Jwaitpid6 procedure myself, which emulated the functionality of UU 0Jt owaitpid6 using the Jwait6 and Jwait36 kernel calls. The best way to emulate Jwaitpid6 was atuUU 06iwith Jwait36, but unfortunately Jwait36 wasnt available everywhere either, so the emulation tUU 06UUeworked differently on systems that had Jwait36 and those that supported only Jwait6. The tUU 0Je _autoconf6 program checks to see which of the kernel calls are available, includes the emula anʪUU 06isition for Jwaitpid6 if it isnt available, and sets a compiler flag that indicates to the emulation h֪UU@ 06at0code whether or not Jwait36 is available. m.⪆UU /6 -_You can also emulate using J#define6s in a header file. For example, not all systems supt sUU /6tpeport symbolic links, and those that dont support symbolic links dont support the Jlstat6 ker UU /6prenel call either. For these systems Tcl uses Jstat6 to emulate Jlstat6 with the following tUU@ /6 statement in JtclUnix.h6: mu` 786#define lstat stat 0"UU 66t3^If a header file is missing on a particular system, write your own version of the header file .UU 66wobto supply the definitions needed by your code. Then you can J#include6 your version in your :UU 66e Wcode if the system doesnt have a version of its own. For example, here is the code in e eFUU@ 6JUU\tclUnix.h6 that handles Junistd.h6, which isnt yet available on all UNIX systems: teT 98 h#ifdef HAVE_UNISTD_H o^ 98#include leh 98 /#else r 98 u#include "compat/unistd.h" ade|@ 98e,#endif sys!X0o~t po!d!dTtString!X"`0mtt%9n0ot %?%?TeDefinesr tKz wt temO3&zKzKEO3&Efj̆UUKt wt.h6O3&tKtK?O3&?fj̀"K8n wt imiO3&8nK8nKC9O3&C9fjzion%0n0mt 6;-0ot b@@Ta Declaratione%g+UR0ot UU%g+%g+TyIncludent%g+UR0ot am%g+%%g+%Tn#ifdefn V0ot atddT6Variablesnn-0ot msddTh Declaration_UN;-0mtlu+n)00ot -+^+^Tu Procedure"+n&0ot 9+ ^+ ^TX Prototypeon-0mt+n)00mtdm%g+000ot %g+7~X%g+7~XTmMultiple%g+90ot %g+@~X%g+@~XTwInclude%g+B0ot 3&%g+I~X%g+I~XT#endiflHn 3&lH ,UU :6kThe Jconfigure6 script generated by Jautoconf6 checks for the existence of Junistd.h6 in oUU :6g+ethe system include directories and sets JHAVE_UNISTD_H6 if it is present. If it isnt present, UU@ :J;tclUnix.h6 includes a version from the Tcl source tree. 0<UU` ,[ms Use autoconf dLUU 16io^The GNU Jautoconf6 program provides a powerful way to configure your code for different XUU 16e"fsystems. With Jautoconf6 you write a script called Jconfigure.in6 that describes the portdUU 160_ing issues for your software in terms of particular features that are needed and what to do if 0pUU 16dthey arent present. Before creating a release of your software you run Jautoconf6, which proIn|UU 16dcesses Jconfigure.in6 and generates a shell script called Jconfigure6. You then include UU@ 1J&configure6 with your distribution. UU 6ehen it is time to install the distribution on a particular system, the installer runs the UU Jthaconfigure6 script. Jconfigure6 pokes around in the system to find out what features are UU 6cpresent, then it modifies the JMakefile6 accordingly. The modifications typically consist of LUU 6Th`compiling additional files to substitute for missing procedures, or setting compiler flags that ĪUU@ 6em5can be used for conditional compilation in the code. c⪛UU` 3[atPorting header file UU 46inbIn spite of all the above advice, you will still end up needing some conditional compilation, for UU 46th`example to include alternate header files where standard ones are missing or to J#define6 In UU 46csymbols that arent defined on the system. Put all of this code in the porting header file for the UU 46fpackage, then J#include6 this header file in each of the source files of the package. With this "UU 46sy]approach you only need to change a single place if you have to modify your approach to portao.UU 46syfbility, and you can see all of the porting issues in one place. You can look at JtclPort.h6 and :UU@ 4Jmo3tkPort.h6 for examples of porting header files. 6Th^` DonMiscellaneous }UU` [ pChanges files UU 6eEach package should contain a file named Jchanges6 that keeps a log of all significant changes tUU 6ilamade to the package. The Jchanges6 file provides a way for users to find out whats new in iUU 6, \each new release, what bugs have been fixed, and what compatibility problems might be introssUU 6indduced by the new release. The Jchanges6 file should be in chronological order. Just add short orUU@ 6or]blurbs to it each time you make a change. Here is a sample from the Tk Jchanges6 file: u 8acA5/19/94 (bug fix) Canvases didn't generate proper Postscript for n 8ifstippled text. fy  8or o 8syG5/20/94 (new feature) Added "bell" command to ring the display's bell. lo 8h  8 4B5/26/94 (feature removed) Removed support for "fill" justify mode  8el@from Tk_GetJustify and from the TK_CONFIG_JUSTIFY configuration Ea 8co?option. None of the built-in widgets ever supported this mode ica 8anyway. il%@ 8ag"*** POTENTIAL INCOMPATIBILITY *** 3UU 6o eThe entries in the Jchanges6 file can be relatively terse; once someone finds a change that is p?UU 6 marelevant, they can always go to the manual entries or code to find out more about it. Be sure to iKUU 6deahighlight changes that cause compatibility problems, so people can scan the Jchanges6 file eWUU@ 6ha)quickly to locate the incompatibilities. 9Fh.np teFh. q ifpl  ]H memory info o ]FsyZPrints a report containing the total allocations and frees since Tcl began, the number of  ]FUblocks currently allocated, the number of bytes currently allocated, and the maximum '@ ]FGe6number of blocks and bytes allocated at any one time. h%np th% q de  XHanmemory trace Wonoff 8ag XFCOsIf WonoffF is HonF, one line will be printed to stderr for each call to HckallocF.Z Any other ind@ XZ pJvalue for WonoffZ turns tracing off.F Tracing is off by default. eh@np e h@ q s au  YHromemory validate Wonoff  YFfifIf WonoffF is HonF, guard zones around every allocated block are checked on every call to  YHgckallocF or HckfreeF in order to detect memory overruns as soon as possible. If WonoffF co' YF aeis anything other than HonF, checks are made only during HckfreeF calls and only for the h0 YFcuWblock being freed. Memory validation has a very large performance impact, so it is off cat9@ YF. by default. hnp h q  X  ZH %memory trace_on_at_malloc Wnumber W@ ZFonTArranges for tracing to be turned on after WnumberF calls to HckallocF. er d*hnp W*h q s  d  [H"memory break_on_malloc Wnumber @ [FBEnter the debugger after WnumberF calls to HckallocF. th.np th. q  aed  \H omemory init Wonoff  \FlofIf WonoffF is HonF, new blocks of memory are initialized with a strange value to helZp  \Zis_locate uninitialized uses of the block. Any other value for WonoffZ turns initialization e h'@ \Zcu&off. Initialization is on by default. ah%np ih% q   Hnmemory active Wfile h F]Dumps a list of all allocated blocks (and where they were allocated) to WfileF. Memory Z@ F tFleaks can be tracked down by comparing dumps made at different times. d%g+000mtWR0ot !d!dT [%g+ UR00mtumd e Leftd caRightcd- Referencend4TOCd7 aIXedd:meLOFid=LOTFd@dBmod std dnid"ckdDondFondHofdV dd[ db dd qdf dhWdjdlcadn wdpdr dv dde 1A@6f=SEo T@UR 01Stepm Step Number S:.\tStep66fD 6 O FirstBodyBody a@  Jmo ^?| rV tl     ni CodeInFigure ExampleOutput66fTQ 6 Table Caption Rule Caption Rule Step NumberT:Table .. Body@6fS  w@ Step Step Number S:.\t 66 fE EquationEquation Number E:(EQ )6fA +33 6 Note \tNote:\tBody6Hf AuthorHHf  Extract6fA +33 6 CNote\t\tBody 6Hfn Body@@f \tCStep@6fSE @um 1Step Step Number S:.\tStep@6f=S  @ tStep Step Number S:.\tHf H CellCmd6fHQ  +33 f6 2HeadingH:\t.\t FirstBody6 fHQ  f+33 6 3HeadingH:\t..\t FirstBodyf H CellBody f  TableFootnote fTf   TableTitleT:TABLE . f  CellHeading66$ f?FA 6 Figure Caption Rule Caption Rule Step NumberF:Figure . 6Body66$ fFA 6 Figure Caption Rule Caption Rule Step Number6F:Figure . gBody$fF H CellListCmdsQQ8@   f+| TaeF/eE O f&(~Code TclResultfIT   TableTitleT:Table : $f FH CellListCmds66f7@N 6 Title Step Number FirstBody@Eere n y left footer@ElLi  header right@ETae   right header@E  right footer$5 $ . 1HeadingTOCH$6 H . 2HeadingTOClH@6 el . 3HeadingTOC @F Level2IX$@F Level1IX@F SpecIX@F oot SortSpecIX @G   GroupTitlesIXi@F IndexIX@5  ParagraphH5n FH . FigureLOFH5 H . TableTitleLOT66f@  Title Step Number FirstBody6Hf5 Author66f6D 6 FirstBodyBody6HfU Authorf6  CellHeadingf6 H CellBodyfF . CellHeading@@f6 CStepefF H CellBody8@  J ^?| rV  ily Bo    CodeInFigure ExampleOutput Hf F H  CellListCmds@@f  CBulletQQ @   f+| /E.OHein &(~Code TclResultf V H CellBody66f Footnote@6f| Bo@ Bullet Bullet Symbolo\ti6fHQ  +33 6 1Heading 1Heading Rulem H:\t.\t FirstBody6Hf6 Body6f[HQ  +33 6 2HeadingH:\t.\t FirstBody@6fB @ Bullet Bullet Symbol\t6fDHQ  +33 6 1Heading 1Heading Ruleo H:\t.\t FirstBody5e?& zV5 zV67 let Step Numberi _89  : Symbol  ;:\t Subscripti < Run-In Heading =  Step Number _>Code ? H Step Number @Code A tܧengManual/README010066400630510000012000000004730564060453500145270ustar00ousterstaff377777770000002This directory contains information related to the Tcl/Tk Engineering Manual. It includes the following files: engManual - Framemaker source for the manual (Frame 3.x). engManual.ps - Postscript for the manual. proto.c, proto.h, prochead - Templates for use in implementing the Tcl/Tk coding conventions.