; TeX output 1994.04.15:1504)<;ĠݻeˍqBK`yG cmr10BF9unnelWebKUser'sManOualNύ 9DtGGcmr17Ross7tN.Williams.s獒34K`yff cmr10V1.0forFunnelWebV3.0yMay1992*)<;Ġݻ*۟ƶ ffʕǍK`y cmr10CopyrightrcUU!", cmsy10 1992UURossN.Williams.Permission+isgrantedtomakeanddistributeverbatimcopiesofthismanualprovidedthatthe copyrightUUnoticeandthispGermissionnoticearepreservedonallcopies.X-ffʕK%1=)<;ĠݻK%2)<;ĠݻǦ*H"VG cmbx10HCon4tentsD*"V cmbx10Preface9*Ac9knowledgements?11*Presen9tationTNotes>"13*19ATT utorialIn9troQduction(15덍91.1PWhatUUisLiterateProgramming?x  b> cmmi10:::::::::::::::::::::::::::::!d1591.2PWhatUUisF*unnelWeb?[㍑:::::::::::::::::::::::::::::::::::!d1891.3PTheUUNameF*unnelWebͣ::::::::::::::::::::::::::::::::::!d1991.4PAUUF*unnelWebTutoriali::::::::::::::::::::::::::::::::::!d1991.5PAUUHelloW*orldDoGcumentY::::::::::::::::::::::::::::::::!d2091.6PMacroUUF*acilities::::::::::::::::::::::::::::::::::::::!d22P1.6.1pSimpleUUMacrosl::::::::::::::::::::::::::::::::::!d22P1.6.2pNumbGerUUofTimesCalled_:::::::::::::::::::::::::::::!d23P1.6.3pIndentation ::::::::::::::::::::::::::::::::::::!d25P1.6.4pAdditiveUUMacrosxG:::::::::::::::::::::::::::::::::!d26P1.6.5pParameterizedUUMacros::::::::::::::::::::::::::::::!d28P1.6.6pMacroUUExpansionq(:::::::::::::::::::::::::::::::::!d30P1.6.7pIncludeUUFilesxY:::::::::::::::::::::::::::::::::::!d3091.7PTypGesettingUUF*acilities[㍑:::::::::::::::::::::::::::::::::::!d32P1.7.1pOverview;:::::::::::::::::::::::::::::::::::::!d32P1.7.2pTypGesetterUUIndependenceۮ::::::::::::::::::::::::::::!d34P1.7.3pHierarchicalUUStructureT::::::::::::::::::::::::::::::!d34P1.7.4pUnderstandingUUthePrintedDoGcumentation::::::::::::::::::!d35P1.7.5pLiteralsUUandEmphasisi::::::::::::::::::::::::::::::!d37P1.7.6pAddingUUaHeaderPageT::::::::::::::::::::::::::::::!d37P1.7.7pComments8h:::::::::::::::::::::::::::::::::::::!d3791.8PAUUCompleteExample17:::::::::::::::::::::::::::::::::::!d3891.9PSummary:::::::::::::::::::::::::::::::::::::::::!d39K%36)<;Ġݻ_"E*29F unnelWebTHin9ts841Q92.1PMacroUUNames:::::::::::::::::::::::::::::::::::::::!d4192.2PQuickUUNames:::::::::::::::::::::::::::::::::::::::!d4292.3PF*unnelWebUUtheMartinet:::::::::::::::::::::::::::::::::!d4292.4PFiddlingUUWithEndofLinesi:::::::::::::::::::::::::::::::!d4392.5PF*udgingUUConditionals4:::::::::::::::::::::::::::::::::::!d4492.6PChangingUUtheStrengthofHeadings֍:::::::::::::::::::::::::::!d4692.7PEciencyUUNotesR::::::::::::::::::::::::::::::::::::::!d4792.8PInteractiveUUMoGde1J:::::::::::::::::::::::::::::::::::::!d4792.9PSettingUUUpDefaultOptionsM:::::::::::::::::::::::::::::::!d4992.10PF*unnelWebUUandMake::::::::::::::::::::::::::::::::::!d4992.11PTheUUDangersofF*unnelWebn:::::::::::::::::::::::::::::::!d5092.12PWholisticUUDebugging:::::::::::::::::::::::::::::::::::!d5392.13PExamplesUUofF*unnelWebUUApplications8::::::::::::::::::::::::::!d53P2.13.1pAnalyzingUUtheMonsterPostscriptHeaderFile4:::::::::::::::::!d54P2.13.2pMakingUUAdaADTsmoreAN:::::::::::::::::::::::::::!d55P2.13.3pMultipleUULanguageSystems:::::::::::::::::::::::::::!d55P2.13.4pTheUUCaseoftheSmallF*unction:::::::::::::::::::::::::!d56P2.13.5pWhenUUCommentsareBadbȍ::::::::::::::::::::::::::::!d57P2.13.6pDoGcumentsUUThatShareT*extFG::::::::::::::::::::::::::!d58P2.13.7pGenerics::::::::::::::::::::::::::::::::::::::!d5992.14PSummary:::::::::::::::::::::::::::::::::::::::::!d62R*39F unnelWebTDe nition"/6393.1PIntroGduction::::::::::::::::::::::::::::::::::::::::!d6393.2PNotation*T::::::::::::::::::::::::::::::::::::::::::!d6393.3PT*erminology ::::::::::::::::::::::::::::::::::::::::!d6393.4PAnUUArchitecturalOverview:::::::::::::::::::::::::::::::!d6493.5PDiagnostics\ ::::::::::::::::::::::::::::::::::::::::!d6593.6PTypGesetterUUIndependence[::::::::::::::::::::::::::::::::!d6593.7PCommandUULineInterface`:::::::::::::::::::::::::::::::::!d66P3.7.1pInvokingUUF*unnelWebx4:::::::::::::::::::::::::::::::!d66P3.7.2pCommandUULineArguments⾍:::::::::::::::::::::::::::!d67P3.7.3pOptionsc::::::::::::::::::::::::::::::::::::::!d6893.8PFileUUNameInheritanceT::::::::::::::::::::::::::::::::::!d7093.9PF*unnelWebUUStartup[::::::::::::::::::::::::::::::::::::!d7093.10PScannerM卑::::::::::::::::::::::::::::::::::::::::::!d71P3.10.1pBasicUUInputFileProGcessingb:::::::::::::::::::::::::::!d71P3.10.2pSpGecialUUSequencesA::::::::::::::::::::::::::::::::!d72K%4!6)<;Ġݻ_"EP3.10.3pSettingUUtheSpGecialCharacter)::::::::::::::::::::::::::!d74P3.10.4pInsertingUUtheSpGecialCharacterintotheT*ext6:::::::::::::::::!d74P3.10.5pInsertingUUArbitraryCharactersintotheT*ext𧍑:::::::::::::::::!d74P3.10.6pComments8h:::::::::::::::::::::::::::::::::::::!d75P3.10.7pQuickUUNames捑:::::::::::::::::::::::::::::::::::!d76P3.10.8pInsertingUUEndofLineMarkersw:::::::::::::::::::::::::!d76P3.10.9pSuppressingUUEndofLineMarkers?::::::::::::::::::::::::!d77P3.10.10pIncludeUUFilesxY:::::::::::::::::::::::::::::::::::!d77P3.10.11pPragmas::::::::::::::::::::::::::::::::::::::!d78p3.10.11.1Indentationi:::::::::::::::::::::::::::::::!d78p3.10.11.2MaximumUUInputLineLength 0:::::::::::::::::::::!d79p3.10.11.3MaximumUUOutputFileLineLength>Ս:::::::::::::::::!d79p3.10.11.4TypGesetterM:::::::::::::::::::::::::::::::!d80P3.10.12pF*reestandingUUTypGesetterDirectivesL:::::::::::::::::::::::!d81p3.10.12.1NewUUPage::::::::::::::::::::::::::::::::!d81p3.10.12.2T*ableUUofContents:::::::::::::::::::::::::::!d81p3.10.12.3V*erticalUUSkip ::::::::::::::::::::::::::::::!d81p3.10.12.4Title⍑:::::::::::::::::::::::::::::::::::!d82P3.10.13pScanner/ParserUUInterface?D:::::::::::::::::::::::::::::!d8293.11PParser?:::::::::::::::::::::::::::::::::::::::::::!d82P3.11.1pHighUULevelStructureS:::::::::::::::::::::::::::::::!d82P3.11.2pF*reeUUTextݍ:::::::::::::::::::::::::::::::::::::!d83P3.11.3pTypGesetterUUDirectivesx2::::::::::::::::::::::::::::::!d83p3.11.3.1Sectionэ:::::::::::::::::::::::::::::::::!d83p3.11.3.2LiteralUUDirective::::::::::::::::::::::::::::!d84p3.11.3.3EmphasisUUDirective::::::::::::::::::::::::::!d85P3.11.4pMacrosj9::::::::::::::::::::::::::::::::::::::!d85p3.11.4.1Names:::::::::::::::::::::::::::::::::!d86p3.11.4.2F*ormalUUParameterLists::::::::::::::::::::::::!d86P3.11.5pExpressionsF::::::::::::::::::::::::::::::::::::!d86P3.11.6pMacroUUCalls::::::::::::::::::::::::::::::::::::!d86P3.11.7pF*ormalUUParameters::::::::::::::::::::::::::::::::!d87P3.11.8pMacrosUUareStaticH:::::::::::::::::::::::::::::::::!d8793.12PAnalyser\::::::::::::::::::::::::::::::::::::::::::!d8893.13PT*angle :::::::::::::::::::::::::::::::::::::::::::!d8893.14PW*eave}:::::::::::::::::::::::::::::::::::::::::::!d89P3.14.1pT*argetUUTypGesetter::::::::::::::::::::::::::::::::!d89P3.14.2pCrossUUReferenceNumbGering5:::::::::::::::::::::::::::!d8993.15PF*unnelWebUUShell1I:::::::::::::::::::::::::::::::::::::!d90K%5OI)<;Ġݻ_"EP3.15.1pIntroGductionxV:::::::::::::::::::::::::::::::::::!d90QP3.15.2pReturnUUStatusese:::::::::::::::::::::::::::::::::!d90P3.15.3pCommandUULineLength@:::::::::::::::::::::::::::::!d91P3.15.4pStringUUSubstitution::::::::::::::::::::::::::::::::!d91P3.15.5pHowUUaCommandLineisProGcessed齍:::::::::::::::::::::::!d92P3.15.6pOptionsc::::::::::::::::::::::::::::::::::::::!d92P3.15.7pShellUUCommandsb:::::::::::::::::::::::::::::::::!d93p3.15.7.1Absent* :::::::::::::::::::::::::::::::::!d93p3.15.7.2CoGdifyύ:::::::::::::::::::::::::::::::::!d93p3.15.7.3Compare::::::::::::::::::::::::::::::::!d93p3.15.7.4De ne[ڍ::::::::::::::::::::::::::::::::::!d94p3.15.7.5Di S:::::::::::::::::::::::::::::::::::!d94p3.15.7.6Di summaryC::::::::::::::::::::::::::::::!d95p3.15.7.7Di zeroC:::::::::::::::::::::::::::::::::!d95p3.15.7.8Eneo1/::::::::::::::::::::::::::::::::::!d95p3.15.7.9Execute :::::::::::::::::::::::::::::::::!d96p3.15.7.10Exists[ٍ::::::::::::::::::::::::::::::::::!d96p3.15.7.11Fixeols{:::::::::::::::::::::::::::::::::!d96p3.15.7.12FwxT:::::::::::::::::::::::::::::::::::!d97p3.15.7.13Help7:::::::::::::::::::::::::::::::::::!d97p3.15.7.14Here:::::::::::::::::::::::::::::::::::!d98p3.15.7.15Quit8R:::::::::::::::::::::::::::::::::::!d98p3.15.7.16SetTƍ:::::::::::::::::::::::::::::::::::!d98p3.15.7.17Show/::::::::::::::::::::::::::::::::::!d98p3.15.7.18Skipto,::::::::::::::::::::::::::::::::::!d98p3.15.7.19Status*::::::::::::::::::::::::::::::::::!d99p3.15.7.20T*olerate :::::::::::::::::::::::::::::::::!c100p3.15.7.21T*raceͣ::::::::::::::::::::::::::::::::::!c100p3.15.7.22W*rite::::::::::::::::::::::::::::::::::!c100p3.15.7.23W*riteu`:::::::::::::::::::::::::::::::::!c10093.16PConcludingUURemarks*:::::::::::::::::::::::::::::::::::!c100R*49F unnelWebTInstallationO10194.1PObtainingUUaCopyofF*unnelWeb::::::::::::::::::::::::::::!c10194.2PEstablishingUUTheDirectoryT*ree[::::::::::::::::::::::::::::!c102P4.2.1pAdminUUDirectoryj :::::::::::::::::::::::::::::::::!c102P4.2.2pAnswersUUDirectory ::::::::::::::::::::::::::::::::!c102P4.2.3pHackmanUUDirectory::::::::::::::::::::::::::::::::!c103P4.2.4pResultsUUDirectory8I:::::::::::::::::::::::::::::::::!c103K%6~})<;Ġݻ_"EP4.2.5pScriptsUUDirectory :::::::::::::::::::::::::::::::::!c103P4.2.6pSourcesUUDirectoryF:::::::::::::::::::::::::::::::::!c103P4.2.7pT*estsUUDirectoryo::::::::::::::::::::::::::::::::::!c104P4.2.8pUsermanUUDirectory8?::::::::::::::::::::::::::::::::!c10594.3PCompilingUUF*unnelWeb::::::::::::::::::::::::::::::::::!c10594.4PT*estingUUFunnelWebЍ::::::::::::::::::::::::::::::::::::!c10594.5PInstallingUUF*unnelWebS:::::::::::::::::::::::::::::::::::!c10694.6PPrintingUUManuals:::::::::::::::::::::::::::::::::::::!c10794.7PInstallationUUProblems?b::::::::::::::::::::::::::::::::::!c107*59F unnelWebTAdministration10995.1PIntroGduction::::::::::::::::::::::::::::::::::::::::!c10995.2PTheUUUser'sCommitmentT*oFunnelWeb5::::::::::::::::::::::::!c10995.3PDoGcumentation::::::::::::::::::::::::::::::::::::::!c11095.4PRegistrationƷ::::::::::::::::::::::::::::::::::::::::!c11095.5PSuppGortx::::::::::::::::::::::::::::::::::::::::::!c11095.6PCopyrightM:::::::::::::::::::::::::::::::::::::::::!c11295.7PNowarranty*F::::::::::::::::::::::::::::::::::::::::!c11295.8PDistribution ҍ::::::::::::::::::::::::::::::::::::::::!c11395.9PMoGdi cationT퍑::::::::::::::::::::::::::::::::::::::::!c11395.10PV*ersionsʍ::::::::::::::::::::::::::::::::::::::::::!c11495.11PFTPUUArchiveandAuthorʍ::::::::::::::::::::::::::::::::!c114*A9Glossary_h115*B9ReferencesT117*Index}117K%7b)<;ĠݻK%8 A)<;Ġݻ"E*HPreface:*When,#int1986,IJ rstreadDonaldKnuth'stechnicalrepGortonW*eb[Kn9uth83],#andtriedWeb *out,IZwasusimultaneouslyexcitedbyKnuth'sideaofliterateprogramming,anddisappGointedby*hisHyimplementationofit.m~IHvwasexcitedbGecauseIHvcouldsensethepotentialfortheliteratestyleto*transform~thestateofmindoftheprogrammer,butwasdisappGointedbyW*eb'srigidityandlack*ofpracticality*,whichseemedtobGetraythispGotential.nTheW*ebIusedwasPascal-spGeci c,TU>'ExX-*spGeci c,$andWappliedtoomanyconstraintstotheprogrammingproGcess.6Inparticular,$itinsistedon*taking9Gcontroloftheprogramtext,>manglingthecoGdeinthePascaloutput les,>andimpGosingits*ownratherrigidideasabGoutindentingintheTU>'ExXoutput.[Allthis,combinedwiththecomplexity*ofUUthetoGol,ledmetocometoperceiveW*ebasproblemratherthansolution.*Despiteallthis,IwaswellandtrulyhoGokedontheideaofliterateprogramming.Theinevitable*resultUUwasthatIdesignedandimplementedmyownversionofW*eb|FunnelWeb!*F*unnelWeb.isnotthemostsophisticatedliterateprogrammingtoGolavqailable,butitisanextremely*': cmti10pr}'actical wtoGol,strivingforsimplicityandportabilityinallareas.YNotonlyisF*unnelWeb wlanguage-*indepGendent,9andضtosomeextenttypGesetterindependent,9butitsimplementationalsostresses*pGortability*,ӏbeingPwritteninC,andcurrentlyopGeratingonfourma8jorplatforms(Sun,ӏV*ax,PC,*Mac).hF*unnelWeb9allowstheprogrammertotalcontrolovertheoutput le,?pmakingitsuitablefor*usewithallsortsofformat-sensitivelanguages.*ItalsoallowscontroloveritsownsourcecoGde,*whichhasbGeenreleasedunderaGNUlicense.3F*unnelWebisquitesolid,havingtopassaregression*testingsuiteofover200testsbGeforebeingreleased.TFinally*,5PFunnelWebiswelldocumentedby*thisUUmanualwhichprovidesatutorial,advqancedhints,andalanguagede nition.*IWwouldliketodedicateF*unnelWebandthismanualtoDonaldKnuthandhisliterateprogramming*toGolW*eb..AlthoughthismanualissomewhatcriticalofsomeaspectsofW*eb,thiscriticismisreally*a!OproGductofdi eringdesigngoals.`pKnuthdesignedaparadigm(literateprogramming)andatool*(W*eb)۩aimedatthehighestpitchofprogrampresentationandtypGesetting. F*unnelWeb۩aims*lower,+relaxing!constraints,and!makingcompromisesinordertoachieve!simplicity*, exibility*,and*pGortability*.@ThecresultisapracticaltoolwhichI=hopewillattractmorepeopletotheliteratestyle.*RossTN.Williams*Adelaide,TAustralia*Ma9yT1992K%9 ȍ)<;ĠݻK%10 *)<;Ġݻ"E*HAc4knowledgements;Vx*Many/thankstoDa9vidHulse(].eYAll0 referencescitedinthetextappGearinthereferencelistandtheindex.*SpQecial&terms:%NewOorimpGortantterminologyhasbeensetinboldfaceandappearsintheindex.*AUUglossaryappGearsasanappendix.*T9ypQesetting:>LThis doGcumentwaspreparedbytheauthorusingAndrewT*revor-*row's(akt150@cscgpo.anu.edu.au)implementation(OzT*eX)oftheTU>'ExX/LffUI- cmcsc10IaTU>EX[Kn9uth84]*[LampQort86]UUtypGesettingsystemrunningonaMacintosh-SE.*Graphics:!7All5diagramshave5bGeenconstructedoutoftextusingtheLffUIaTU>ExX verbatimenvironment*soastoallowthisdoGcumenttobGedisseminatedelectronicallyandprintedusingLffUIaTU>ExXwithout*accessUUtotheauthor'sdrawingtoGols.*Kno9wn)typQesettingproblems:'ExXtosuppressblankpagesatthestartofchapters.K%13ݳ)<;ĠݻK%14#)<;Ġݻ!U*J"Vp cmbx10JChapterF17*HA TutorialIn4trovduction?*7"Vff cmbx101.1PfWhatisLiterateProgramming?+*A traditionalacomputerprogramconsistsofatext lecontainingprogramcoGde.sScatteredin *amongstUUtheprogramcoGdearecommentswhichdescribGethevqariouspartsofthecode.*InliterateVprogrammingtheemphasisisreversed.M InsteadofwritingcoGdecontainingdoGcumen-*tation,theZliterateprogrammerwritesdoGcumentationcontainingcoGde.HNolongerdoestheEnglish*commentaryinjectedintoaprogramhavetobGehiddenincommentdelimitersatthetopofthe le,*orvRunderproGcedureheadings,~orattheendoflines.ԿInstead,itiswrenchedintothedaylightand*madethemainfoGcus.vThe\program"thenbecomesprimarilyadocumentdirectedathumans,*withthecoGdebeingherdedbetween\codedelimiters"fromwhereitcanbeextractedandshued*outUUsidewaystothelanguagesystembyliterateprogrammingtoGols.*The;e ectofthissimpleshiftofemphasiscanbGesoprofoundastochangeone'swholeapproach*torprogramming.tUndertheliterateprogrammingparadigm,ythecentralactivityofprogramming*bGecomesthatofconveyingmeaningtootherintelligentbeingsratherthanmerelyconvincingthe*computertobGehaveinaparticularway*.Itisthedi erencebetweenperformingandexposinga*magicUUtrick.*InEXordertoprograminaliteratestyle,XparticulartoGolsarerequired.AThetraditionalapproach*(used\+intheF*unnelWeb\+system)istohave\+somesortoftext- le-in/text- le-oututilitythatreads*a)literateprogram(containingaprogramcommentarypGeppered)withscrapsofprogramtext)*andwritesouta lecontainingalltheprogramcoGdeanda lecontainingtypGesettercommands*representingUUtheentireinputdoGcument,doGcumentation,coGde,andall(FigureT1).*GivenGthecomingageofhypGertextsystems,Dthisisprobablynotthebestapproach.However,Dit*doGesmeshbeautifullywithcurrenttext lesandcommandlineinterfaces,ڭtheexpGectationoflinear*presentationsYinthedoGcumentsweread,Zandtheparticularrequirementsofcurrentprogramming*languagesUUandtypGesettingsystems.qItiscertainlynotabadapproach.*Withthisstructureinplace,Gtheliterateprogrammingsystemcanprovidefarmorethanjusta*reversalqofthepriorityofcommentsandcoGde.Initsfullblownform,D7agoGodqliterateprogram-*mingfacilitycanprovidetotalsuppGortfortheessentialthrustofliterateprogramming,־whichis*that/computerprogramsshouldbGewrittenmoreforthehumanreaderthanforthecompiler.mVIn*particular,UUaliterateprogrammingsystemcanprovide:G!Re-orderingofcoQde:ProgrammingmUlanguagesoftenforcetheprogrammertogiveG!thevqariouspartsofacomputerprograminaparticularorder.ZJF*orexample,thePas-G!cal&programminglanguage[BSI82]impGosestheordering:Zmconstants,/types,/vqariables,G!proGcedures,ncode.PascalialsorequiresthatproGceduresappearinanorderconsistentG!with]thepartialorderingimpGosedbythestaticcallgraph(butforwarddeclarationsG!allowthistobGebypassed).Incontrast,5theliteratestylerequiresthattheprogram-G!merчbGefreetopresentthecomputerprograminanyorderwhatsoGever.EThefacilitytoK%15p)<;ĠݻX 9~+-----------------------------------------+ ~|?Filecontainingtheprogramdescription|~|?pepperedwithscrapsofprogramcode.|~|?Thisiswhattheprogrammerworkson.|~|4(e.g.?sloth.web)N|~+-----------------------------------------+o|ov-o---------------------------o-|?LiterateProgrammingTool|-o---------------------------oo|~+-------------------+-------------------+~|̿|~v̿vOm+------------------+9+----------------------------------+Om|Traditional|9|?Documentationfilesuitablefor |Om|?ComputerProgram|9|inputintoatypesettingprogram|Om| (e.g.?sloth.c)|9|)(e.g.sloth.tex)4|Om+------------------+9+----------------------------------+"R |{Ycmr8LiterateprogrammingtobecausetheliterateG!programmingzutilityseesallthecoGde,itcanuseitsknowledgeoftheprogrammingG!languageandthefeaturesofthetypGesettinglanguagetotypGesettheprogramcodeasG!ifUUitwereappGearinginatechnicaljournal.qItisthedi erencebGetween:zJ?while?slothitsUc}'apacitytotransformthestateofmindoftheprogrammer.It'>isnowlegendthattheact*ofexplainingsomethingcantransformone'sunderstandingofit.3Thisisoneofthejusti cations*bGehindthepowerfulcombinationofresearchandteachinginuniversities[Roso9vsky90].:Simi-*larly*,HbyE\constantlyexplainingtheunfoldingprogramcoGdeinEnglishtoanimaginaryreader,Hthe*programmerUUtransformshispGerceptionofthecode,layingitopen,prone,tothecriticaleye.*TheresultofthisexpGosureisahigherqualityofprogramming.DGWhenexposedtotheharshlightof*the literateeye,bugscrawlout,spGecialcasesvqanish,andsloppycoGdeevqaporates.CAsaruleliterate*programstakelongertowritethanordinaryprograms,butthetotaldevelopmenttimeisthe*sameEorlessbGecausethetimetakentowriteanddocumenttheprogramcarefullyiscompensated*for&byareduceddebuggingandmaintenancetime.?;ThusliterateprogrammingdoGesnotmerely*assistcinthepreparationofdoGcumentation,butalsomakessigni cantcontributestotheproGcessof*programming]itself.sInpracticethishasturnedouttobGeacontributionfarmoreimportantthan*theUUmerecapacitytoproGducetypGesetdocumentation.*F*ormoreinformationonliterateprogramming,kthereaderisdirectedtoKnuth'searlyfounding*work[Kn9uth83]and[Knuth84].+3F*ormorerecentinformationreferto[Smith91],whichprovides*aUUcomprehensivebibliographyupto1990.K%17q)<;Ġݻ_"E*1.2PfWhatisFunnelWeb?$*F*unnelWebisaparticularliterateprogrammingsystemthatisimplementedbyasingleCdprogram. *F*unnelWebtakesasinputasingle.fwinput; leandwritesoneormoreproQduct lesanda*doQcumen9tationT leUU(Figure2).?'9-+-----------+-|?sloth.fw |-+-----------+o|ov-o-------------------o-|?FUNNELWEBProgram|-o-------------------oo|~+-------------------+----------------+~||~vv5-+-----------------------------++--------------------------------+5-|?ProductFile(e.g.sloth.c)||DocumentationFile(sloth.tex)|5-+-----------------------------++--------------------------------+RܸFJunnelWebXfolloÎwsthetraditionalarchitectureofliterateprogrammingto'ExXtypGe-G!settinglanguage[Kn9uth84],F*unnelWebstrivestobGelanguageandtypGesetterinde-G!pGendent.`The!currentversionofF*unnelWebiscompletelylanguageindepGendent,,$butG!isUUstillsomewhatdepGendentontheTU>'ExXtypGesetterlanguage.G!P9ortability:VF*unnelWebrhasbGeenwrittenintheCExXsource* leforthischapterortheF*unnelWebtestsuite.@{Hello?World@+@}*T*oUU\run"this\program",invokeUUFunnelWebusingthe\fw"commandasfollows.*fw?hello*Ifa+thisc}'ommanddoesnP'twork,{thenchancesarethatF;unnelWebhasnotbeeninstalledonyour *machine.R}'efertoChapter4forfulldetailsonhowtoobtainandinstallac}'opyofF;unnelWeb.*ThereshouldbGenoerrors.RIfthereare,havealookatthelisting lehello.lis,whichshould*containanexplanationoftheerror,andcomparetheareainthe lewheretheerroroGccurredwith*theUUtextabGove.qIfUUtherearenoerrors,youwill ndthatthefollowingtwo leshavebGeencreated. ΍*hello.lis-?TheLISTINGfile.*hello.txt-?ThePRODUCTfile.*T*akealoGokathello.txt.ItshouldcontainasinglelinewiththetextHello?World.Let'stake*anotherUUloGokattheinput le.*@O@@{Hello?World@+@}*Thewholestructureoftheinput leiscontrolledby\@",2calledthespQecialc9haracter,which*introGducesUUspQecialTsequences.qAscanner's-eyeviewofthecommandlineloGokslikethis:*@O @<"hello.txt"@>@{"Hello?World"@+@}*Thej@charactercontrolseverything.#Inthis lewehavesixdi erentspGecialsequencesthattogether*formUasinglemacrode nition.s5The@delimitthenameofthemacro.The@Osignalsthe*startHofthemacrode nitionandindicatesthatthemacroistobGeconnectedtoaproduct lewith*theZsamenameasthemacro(ThisisiswhywegotaproGduct lewhenweranF*unnelWeb).The*@fլand@gdelimitthebGodyլofthemacro.Finally*,the@+instructsthatanendoflinesequence*shouldUUbGeinsertedatthatpointintheproduct le.*IflyouthinkthissyntaxloGoksmessy*,thenyou'reright.$Itismessy*.FunnelWeblc}'ouldhavelemployed*aUU\simpler"notationinwhichmoreofthe@sequenceswereeliminated.qF*orexample:*Warning:?ThisexampleisNOTlegalFunnelWeb.*#hello.txt{Hello?World+}*However,JgifGsuchasyntaxwereused,Jgtheuser(you!)m9wouldhavetoremembGerthat#startsanew*macro.Y*ouswouldalsohavetoremembGerthatthecharactersgand+cannotbGeusedinamacro*bGody withoutafuss.MAndsoon.F*unnelWeb ismessier,87butprovidesonesimplerule:Nothing*sp}'ecialhappensunlessthespecialcharacter@appears.*This4meansthatinF*unnelWeb,;you4canloGokatlargeblocksoftextinthecon dencethat(unlike*for.theCpre-proGcessor)therearenomacrocallshiddeninthere.^Iftherewere,&therewouldbGean*@UUcharacter!^ٓRcmr71*Let'sUUtakeanotherloGokatthehelloworldprogram.*۟7Cffğ J= "5-:Aacmr61LܸTheonlyexceptiontothisruleo@{Hello?World@+@} ؍*InE@{Hello?World@+@}*It?writesoutafilecalledhello.txtcontainingthestring``HelloWorld''.*NowUUrunitthroughF*unnelWeb,UUbutthistime,adda+ttothecommandline.*fw?hello+t*IfUUallgoGeswell,youshould ndthatyounowhave*hello.lis-?ALISTING$file. *hello.tex-?ADOCUMENTATIONfile(inTeXformat).*hello.txt-?APRODUCT$file.*T*ake;HaloGokathello.txt.iYouwill ndthatitisidenticaltothehello.txtofthepreviousrun.*Onlypmacrode nitionsa ecttheproGduct lesthatF*unnelWebpproduces(asaresultof@Opmacro*de nitions).(TheusurroundingdoGcumentationhasnoe ect.Incontrast,ɽthenew le,hello.tex*(haveJaloGokatitnow)whichwascreatedasaresultofyouraddingthe+toptioncontainsa*fairly0fullrepresentationoftheinput le.$XWhereashello.txtisthepr}'oduct+ le0ofF*unnelWeb,*hello.tex|isthedo}'cumentationg le.'ExX*typGesettingprogram.\Thenprintit.\Thefollowingcommandsareanexampleofthesortof*commandsUUyouwillhavetogivetodothis.*tex?hello^!Typesetthedocumentation.*lpr?-Pcslw-dhello.dvi!Printthetypesetdocumentation.*The%resultshouldbGeasinglepagecontainingthetwolinesofdoGcumentationalongwithatypGeset*representation3ofthemacro.CAtthispGoint,youhaveexercisedthetwomainaspGectsofF*unnelWeb.*Startingwithaninput lecontainingmacros(orinthiscasemacro)anddoGcumentation,Syouhave*successfullyKTgeneratedaproGduct lebasedonthemacros,MTandadocumentation le,MTbasedonthe*entireUUdoGcument.qCongratulations!*Theaxremainderofthistutorialisdividedintotwoparts,>whichfoGcusonF*unnelWeb'saxmacrofacilities*anditstypGesettingfacilities.Bytradition,͢thegenerationofprogram lesfromaliteratetextis*calledUUT angling,andthegenerationoftypGesetdocumentationiscalledW ea9ving.^2*۟ ffğ J= "5-:2LܸIn.\FJunnelWeb,OthesetÎwofunctionsareasp@{Hello?World@+@}*Infact,Rthisisaratherexceptionalmacro,asitcausesitsexpansiontobGewrittentoaproduct * le.ǝThe@Oi(forOutput)signalsthis.InF*unnelWeb,Nnmostmacrosarede nedusing@$.This*resultsxinamacrothatdoGesnotgenerateaproduct le,ebutwhichcanbecalledinothermacros*(includingUU@Omacros).qLetusexpandthehelloworldprogramtoincludesomeothermacros.4*@O@@{@@+@}*@$@==@{Hello@}*@$@==@{World@}*@$@==@{@?@@}4*TypGeUUinthe leandrunitthroughF*unnelWebUUusingthecommand:*fw?hello*TheUUproGduct le(result.out)shouldlooklikethis:*Hello?World*ThisishortprogramillustratessomeofthefeaturesofordinarymacrosinF*unnelWeb.1Consider *theS@OSmacro.q/Insteadofcontainingstraighttext(\HelloW*orld"),Sitnowcontainsthemacrocall*@.qAuF*unnelWebmacrocanbGecalledfromwithinthebodyofanothermacrojust*byUUgivingthemacronamedelimitedin@.3*AtߏthebGottomofthe leisthede nitionofthe@macro.JThede nitionissimilarto*theGde nitionofhello.txtexceptthatitstartswith@$toindicatethatnoproGduct leisdesired*fromQthismacro(directly).p^Italsoemploystheoptional==syntaxwhichhasnosemanticimpact,*butcanbGeusedtomakede nitionsclearer..Thebodyofthe@macroconsistsof*callsUUtotheHandWmacroswhicharede nedimmediatelyabGove.*NotethatthemacrosarenotconstrainedtobGede nedinanyparticularorder.fOneofthemain*featuresofliterateprogrammingtoGolsisthattheyallowthedi erentpartsofthetextdoGcument*bGeingV5developed(usuallyacomputerprogram)tobelayedoutinanyorder.tgSolongasthereisa*de nitionUUsomewhereintheinput leforeverymacrocall,F*unnelWebUUwillsortitallout.*Inhfact,mF*unnelWeb'smacrofacilityisverysimple.UnlikemanymacropreproGcessorswhichallow*macros%tode neothermacros,F*unnelWeb%completely nishesparsingandanalysingthemacrosin*thePinput lebGeforeitstartsexpandingthemintoproduct les.[Otherpreprocessorsallowmacros*to4bGerede nedlikevqariables(asin,ksay*,TU>'ExX)"taking4onmanydi erentvqaluesasthemacropre-*proGcessortravelsthroughtheinput le.2Incontrast,\F*unnelWebhasnoconceptof\di erenttimes"*andtreatstheinputasonehugestaticorderless,[timeless,collectionofde nitions.Z InF*unnelWeb,*thereUUisonlyeveronetime,andsotherecanonlyeverbGeonevqalue/de nitionforeachmacro.K%22K)<;Ġݻ_"E*1.6.2SNumb`erofTimesCalled*Sofarwehaveseenonlytiny*,degenerateinput les.`[Thenextexamplemovesuptothelevelof *\trivial",سbutstartstoconveythe avourofthewayF*unnelWebcanbGeusedinpractice.=Normally,*therewouldbGedocumentationtextappearingbetweenthemacros,butthishasbeenomittedso*as"tokeepthefoGcusonthemacrosthemselves.-Althoughthenextexampleismuchlongerthan*thepreviousexample,%theonlynewconstructis@-whichcanappGearonlyattheendofaline,*and\suppressesit,^Rpreventing\itfromappGearinginthetext.ZThe@-constructallowsthetextofa*macroItobGealignedattheleftmargin,K|ratherthanhavingthe rstlinehangingattheendofthe*@f. F*unnelWebcouldhavebGeensetupsothatthisendoflinemarkerwassuppressed. However,*itw}wouldhavebGeenaspecialcasethatwouldhavebrokentheverymemorablerule\thetextofa*macroUUisthetextappGearingbetweenUUthe@fand@g".=*TypGeËthefollowingtextintothe lehello.fwandrunitthroughF*unnelWeb.jTheË lecontains*somemintentionalerrorssobGesuretotypGeitinexactlyandworryonlyifF*unnelWebdo}'esnP'tgenerate*someUUerrors.W*@O@==@{@-*@*@*@*@}*@$@==@{@-*main()*{/doit();*}*@}*@$@==@{@-*void?doit()*{/int?i;/for?(i=0;i<10;i++):m{?@?@:m}*}@}*@$@==@{@-*printf("Hello?World!");*printf("\n");@}*@$@==@{scanf@}*@$@==@{@-*#include?*#include?@}W*WhatxwhappGened?-W*ell,?ifyouhaven'ttypGedthe leinproperly*,?youmaygetsomemiscellaneous*syntaxferrors.DxFixthesebGeforecontinuing.DxIfthe lehasbGeencorrectlytypGed,youshouldbGefaced*withUUsomeerrormessagestodowiththenumbGerUUoftimessomeofthemacrosarecalled.=*ByZdefault,F*unnelWebinsiststhateachmacrode nedisinvokedexactlyonce.However,the le*abGovede nesmacrosthatareusedmorethanonceandamacrothatisnotusedatall.Letus*examineUUtheerrors.K%23[m)<;Ġݻ_"E*First,}weseethatF*unnelWebhasalertedustothefactthattheInclude?FilesmacrohasbGeen *calledtwice.VOncealertedtothis,aquickloGokattheprogramconvincesusthatcallingthemacro*twiceUUisamistake,andthatoneofthecallsshouldbGeeliminated.M<*Second, weRnotethatF*unnelWebRhasalertedustothefactthatthe@macroisnever*called.gAgain,macroshouldbGeinsertedjust*abGoveUUthecalltothe@macrointhede nitionof@.*ThesetwocasesdemonstratewhythesecheckshavebGeenplacedinF*unnelWeb.JUItisnearlyalways*acceptablePforamacrotobGecalledonce.4However,ifPamacroisnotcalledatall,orcalledmore*thanUUonce,thisisoftenasignthattheuserhasmadeamistake.*These-checkshaveadarksidetoGo.InadditiontotheerrorsmentionedabGove,dF*unnelWebhas*generatedUUtwosimilarerrorsthatdonothelpus.*First,xweqarealertedtothefactthatthe@macrohasbGeencalledtwice.ƌClearly*,xinthis*case,UUthisisnotaproblem,andsohereF*unnelWeb'sUUfussinessisanuisance.*Second,weIarealertedtothefactthatthe@macrohasneverbGeencalled.Likethe*@nmacro,Gthismacrowasde nedasanotationalconvenience,GandclearlyitdoGesnot*matterUUhereifitisnotused.qAgain,F*unnelWebUUisbGeinganuisance.*ThemfourcasesabGovemdemonstratethelightanddarksideofF*unnelWeb'sminsistencethateach*macrobGecalledexactlyonce.==@{@-*@*@*@*@}*@$@==@{@-*main()*{/doit();*}*@}*@$@==@{@-*void?doit()*{/int?i;/for?(i=0;i<10;i++):m{?@?@:m}*}@}*@$@@M==@{@-*printf("Hello?World!");*printf("\n");@}K%24f)<;Ġݻk"E*@$@@Z==@{scanf@}*@$@==@{@- *#include?*#include?@}&*1.6.3SIndentation*TheKbGodyoftheprintmacroofthepreviousexamplecontainstwolinesoftext.n]AKliteralsubsti-*tutionUUofthismacro'sbGodyUUinitscontextwouldresultin::m{?printf("Hello?World!");*printf("\n");?printf("Hello?World!");*printf("\n");:m}*ButUUinstead,itcomesoutas(haveUUaloGokatthispartofhello.cnow)::m{?printf("Hello?World!");?printf("\n");?printf("Hello?World!");?printf("\n");:m}*TheZexplanationisthatF*unnelWebZindentseachlineofmultilinemacrosbythelevelofindentation*atthepGointofcall.J Thismeansthat,asinthecaseabove,programtexts,whichareusuallyhighly*indented,UUcomeoutloGoking\right".mҍ*Inhothercircumstances,mWwherethemoGdelofthetextisonedimensional,F*unnelWeb'shindentation*could==@{@-*program?adt(input,output);*@*@*@*begin?startproc;end.*@}*@!*******************************@$@+=@{@-*type?buffer_type=:mrecord:mlength?:integer;:mbuf?:array[1..100]ofchar;:mend;*@}*@$@+=@{@-*bigbuf?:buffer_type;*@}*@$@+=@{@-*procedure?buf_init(varb:buffer_typeN){Bodyofbuf_init}*procedure?buf_add (varb:buffer_type;?ch:char){Bodyofbuf_add}*procedure?buf_get (varb:buffer_type;varch:char){Bodyofbuf_get}*@}*@!******************************K%26}/)<;Ġݻ_"E*@$@+=@{@- *type?complex_type=recordr,i:real;end;*@}*@$@+=@{@-*procedure?cm_set(varc:complex_type;a,b:real)/?{Bodyofcm_set}*procedure?cm_add(a,b:complex_type;varc:complex_type){Bodyofcm_add}*{Other?proceduresandfunctions}*@}*@!*******************************{...more?piecesofprogram...}*@!*******************************It1isimpGortanttoremembGerthatthede nitionofeachmacrodoGesnotchangethroughoutthe*input9H le.hmF*unnelWebparsestheentireinput leandassemblesallthemacrode nitionsbGeforeit*evenlstartstoexpandmacros.Asaresult,rbeachadditivemacrocanonlyhaveonede nition,rband*thatUUde nitionistheconcatenationofallitsparts.۷*ThePVexampleabGovePVshowshowadditivemacroscanbGeusedtorearrangethepresentationofa*computerM)programintheorderinwhichtheuserwishestodiscussitratherthantheorderin*whichzthecompilerrequiresthatitbGeconsumed.7Itiseasy*,Dhowever,tozabusethefeatureof*additivemacros.Inmanycases,1thesamee ectcanbGeobtainedmoreclearlybyreplacingeach*part@ofanadditivemacroin-situusinguniquelynamednon-additivemacros,ӫandthencollectthem*togetherBasagroupatthepGointwheretheadditivemacroiscalled.kDoingthisismorework,Fand*is)moreerrorprone,butcanresultinaclearerexpGosition.BThefollowingprogramillustratesthis*alternativeUUapproach.*@!*******************************@O@==@{@-*program?adt(input,output);*@*@*@*begin?startproc;end.*@}*@$@==@{@-*@*@*@}*@$@==@{@-*@*@}*@$@==@{@-*@*@*@}*@!*******************************@$@==@{@-K%27)<;Ġݻ_"E*type?buffer_type=record mlength?:integer;mbuf?:array[1..100]ofchar;mend;*@}*@$@==@{@-*bigbuf?:buffer_type;*@}*@$@==@{@-*procedure?buf_init(varb:buffer_type){Bodyofbuf_init}*procedure?buf_add(varb:buffer_type;ch:char){Bodyofbuf_add}*procedure?buf_get(varb:buffer_type;varch:char){Bodyofbuf_get}*@}*@!*******************************@$@==@{@-*type?complex_type=recordr,i:real;end;*@}*@$@+=@{@-*procedure?cm_set(varc:complex_type;a,b:real) {Bodyofcm_set}*procedure?cm_add(a,b:complex_type;varc:complex_type){Bodyofcm_add}*{Other?proceduresandfunctions}*@}*@!*******************************{...more?piecesofprogram...}*@!******************************J3*OneofadvqantagesofF*unnelWeb(andliterateprogrammingingeneral)isthat(asshownabGove)*itallowstheusertolayouttheprograminwhateverorderisdesiredwithneartotalindepGendence*fromUUtheorderingrequirementsofthetargetprogramminglanguage.ꍑ*Additive8macrosareallowedtobGetaggedwith@Z&and@Mjustasothermacroscan,1butthetags*mustrappGearonlyonthe rstde nitionofthemacro.&GAdditivemacroscannotbGeconnecteddirectly*toUUproGduct les.!KE*1.6.5SParameterizedMacros>*No))self-respGectingmacropreprocessorwouldbecompletewithoutsomeformofmacroparameter-*ization,randmF*unnelWebisnoexception.FunnelWeballowseachmacrotohavefromzerotonine*formalUUparametersnamed@1,@2,@3,@4,@5,@6,@7,@8,and@9.ꍑ*T*o de neamacrowithoneormoreparameters,^insertaformalparameterlistjustafterthemacro*namexinthemacrode nition.lBecausemacroparametershavex xednames(@1::: @9),Zthereisno*need.tospGecifythenamesofformalparametersintheformalparameterlist.-Allthatneedbe*conveyedHishowmanyparametersthemacrohas.mHereisanexampleofthede nitionofamacro*havingUUthreeparameters:J3*@$@@(@3@)@M==@{@-*@1*while?(@2)K%28Ƞ)<;Ġݻ_"E5-{ :m@35-}*@}*T*oʲcallaparameterizedmacro,lanactualparameterlistmustbGesuppliedthatcontainsexactlythe*samenumbGerofactualparametersasthereareformalparametersinthede nitionofthemacro*bGeingcalled.hAnactualparameterlistisdelimitedby@(and@),&andparametersaresep}'arated*by'z\@,".b~TheactualparametersthemselvesaregeneralF*unnelWeb'zexpressions(seeChapter3for*theexactsyntax)andcanbGeinsertedintothelistdirectlyorcanbGedelimitedby@"soastoallow*somewhitespacetoassistinformattingtheactualparameters.nHerearesomeexamplesofcalls*ofUUtheWhile?loopmacrode nedabGove.*@!?Firstformofactualparameterswithoutwhitespaceanddoublequotes.*@@(x=1;@,x<=10@,printf("X=%u\n",x);@)*@!?Secondformofactualparameters.Thedoublequotesallownon-active*@!?whitespacethathelpstolayouttheactualparametersneatly.*@!?Thiscallisfunctionallyidenticaltotheoneabove.*@@(:m@"x:=1;@"?@,:m@"x<=10@"?@,:m@"printf("X=%u\n",x);@"?@)*@!?Thetwoformscanbemixedinasinglecall.*@@(x=1;@,x<=10@,t-@"printf("X=%u\n",x);@"?@)*A{ few{UrulesabGoutparameterizedmacrosareworthmentioning.Macrosthatdonothaveany*parametersQmusthavenoformaloractualparameterlists.pAdditivemacroscanhaveparameters,*butUUtheformalparameterlistmustappGearinthe rstde nitionpartonly*.B*Heresisanotherexampleoftheuseofparameterizedmacros.m"Thistime,(parametersandmacro*calls==@{@-*The?TwelveBugsofChristmas*----------------------------*@@(@"first@"@,@<1@>@)*@@(@"second@"@,@<2@>@)*@@(@"third@"@,@<3@>@)*@@(@"fourth@"@,@<4@>@)*@@(@"fifth@"@,@<5@>@)*@@(@"sixth@"@,@<6@>@)*@@(@"seventh@" @,@<7@>@)*@@(@"eighth@"@,@<8@>@)*@@(@"ninth@"@,@<9@>@)*@@(@"tenth@"@,@@)*@@(@"eleventh@"?@,@@)*@@(@"twelfth@" @,@@)*This?songappearedintheinternetnewsgrouprec.humor.funnyon24-Dec-1991.*It?wascontributedbyPatScannell(scannell@@darkstar.ma30.bull.com).*@}K%29 )<;Ġݻk"E*@$@@(@2@)@M==@{@- *For?the@1bugofChristmas,mymanagersaidtomeD@2*@}*@$@<1@>@M==@{See?iftheycandoitagain.@}*@$@<2@>@M==@{Ask?themhowtheydiditand@+@<1@>@}*@$@<3@>@M==@{Try?toreproduceit@+@<2@>@}*@$@<4@>@M==@{Run?withthedebugger@+@<3@>@}*@$@<5@>@M==@{Ask?foradump@+@<4@>@}*@$@<6@>@M==@{Reinstall?thesoftware@+@<5@>@}*@$@<7@>@M==@{Say?theyneedanupgrade@+@<6@>@}*@$@<8@>@M==@{Find?awayaroundit@+@<7@>@}*@$@<9@>@M==@{Blame?itonthehardware@+@<8@>@}*@$@@M==@{Change?thedocumentation@+@<9@>@}*@$@@M==@{Say?it'snotsupported@+@@}*@$@@M==@{Tell?themit'safeature@+@@}!*1.6.6SMacroExpansion*Ǎ*OneZofthestrengthsofF*unnelWebZisthat, whenwritingproGduct les,itdoGesnotattemptto*evqaluate+anytextexpression(e.g.textbloGck,.parameter,macro+call)inmemoryandthenwrite*theresultout.8Instead,3italwayswritesoutwhatitisexpandingdynamicallyanddirectly*.This*meansRthattheuserneednotfearde ningmacrosthatexpandtohugeamountsoftextandthen*callingthosemacrosinothermacros,.orpassingthosehugemacrosasparameterstoothermacros.*Inuallcases,nF*unnelWebuexpandsdirectlytotheproGduct le,andtherecanbGenodangerinrunning*outofmemoryduringexpansion(exceptforrunningoutofstackspaceandothermarginallyused*resourcesUUinpathologicalcases).s*TheconlythingtoremembGerinthisregardisthatF*unnelWebcalwaysstorestheentireinput le*andUUallincluded les,intheirentiretyUUinmemory*,forthedurationoftherun.*HereUUisanexample,thatillustrateshowrobustF*unnelWebUUis:*@!?FunnelWebcopeswellwiththefollowingmacrodefinitions.*@!?(Providingthatithasalittleovertenmegabytesofmemory).*@O@==@{@@(@@)@+@}*@$@@(@1@)==@{"@1"@}*@$@==@{@- *...Ten?MegabytesofText...*@}!*1.6.7SIncludeFiles*Ǎ*F*unnelWebܪprovidesanestedinclude lefacilitythatcanbGeusedforanumbGerofpurposes.*WhenF*unnelWebrunsintoasinglelinecontainingthespGecialsequence@ifollowedbyablank,*followedbya lename,itreadsinthedesignated leandreplacesthelinecontainingthecommand*(including,theendoflinemarkerattheendoftheline)withtheentirecontentsofthedesignated* le.qF*orUUexample,iftherewasa lecalledcamera.txtcontainingthetwolines:*'Cos?Ishootwithacamerainsteadofagun.*The?animalsflocktobepettedandfed,K%30~)<;Ġݻ_"E*andUUanother lecalledpoem.fwcontainingthefollowingfourlines*I?liketogoshooting,it'sawholelotoffun, *@i?camera.txt*Cos?theyknowmycameraisn'tloadedwithlead.*-?RNW,04-Jan-1991.*Then,UUifF*unnelWebUUweretoproGcesspoem.fw,theresultwouldbGeasifF*unnelWebUUhadreadin:*I?liketogoshooting,it'sawholelotoffun,*'Cos?Ishootwithacamerainsteadofagun.*The?animalsflocktobepettedandfed,*'Cos?theyknowmycameraisn'tloadedwithlead.*-?RNW,04-Jan-1991.*F*unnelWebexpandsinclude lesbGeforeitstartsscanningandparsingtheincludedtext.5Theresult*isjthatinclude lescancontainanythingthatcanbGefoundinaF*unnelWebj le.jThefollowing*exampleUUillustratesthelevelatwhichtheincludemechanismopGerates.qIfmain.fwcontains*@O@==@{@-*@i?inc.fw*This?isthetextoftheslothmacro.*@}*andUUinc.fwcontains*@*@}*@$@==@{@-*ThenUUifF*unnelWebUUwereappliedtomain.fw,itwouldsee:*@O@==@{@-*@*@}*@$@==@{@-*This?isthetextoftheslothmacro.*@}*which 4itwouldproGcessinthenormalmanner.eTheonlyspecialsequenceprocessingthattakes*placeӏatalevellowerthaninclude lesistheproGcessingofthe=sequence*whichUUchangesthespGecialcharacter.J*A3Lfew3UotherfactsabGoutinclude lesareworthmentioninghere.frInclude lesinheritthedirectory*spGeci cation08suppliedusingthe+I0commandlineoption.qThespecialcharacterissavedatthe*startV5ofeachinclude leandrestoredtoitspreviousvqalueattheendofeachinclude le.thInclude* lesBcanbGenesteduptotenlevels.kRecursiveBincluded leswillalwaysBcauseanin niterecursion*asthereisnobGottomingoutmechanismavqailable.UInclude lesmustcontainanintegernumbGerof*lines0(i.e.thelastlinemustbGeterminatedwithanendoflinemarker).eOnceF*unnelWeb0hasseen*\@i?"_Ratthestartofaline,aitwillgrabtherestofthelinerawandtreatitasa lename.There*isUUnoplaceonthelineforthingslikeF*unnelWebUUcomments(seelater)orextraneoustext.J*Include҄ lescanbGeusedformanypurposes,1butareparticularlyusefulforhaulinginmacro*libraries.K%31 )<;Ġݻ_"E*1.7PfT=ypuesettingFacilitiesٍ*The$* rsthalfofthistutorialfoGcusessolelyonthemacrofacilitiesofF*unnelWeb$*(whichitmoreor *less]Ncoverscompletely).Asaresult,_MtheexampledoGcumentsyouhaveseensofarhavebGeengross*distortionscof\normal"F*unnelWebcdoGcumentswhichoftencontainasmuchdoGcumentationas*coGde.^3}WhilethereareapplicationswhereF*unnelWebcanbeusedsolelyasamacropreprocessor,*mostUUapplicationswilluseitstypGesettingfacilitiesaswell.*ThisUUsectionrestoresthebalanceinthistutorialbypresentingF*unnelWeb'sUUtypGesettingfacilities."9&*1.7.1SOverview*Themacrode nitionsdiscussedinthemacrotutorialcompletelyde nethecontentsoftheproGduct* lesUthatF*unnelWebUwillgenerate.sThesemacrode nitionscanbGearrangedinanyorderand*nothingcWexternaltothemcana ectthecontentscWoftheproGduct les.Themacroscanbethought*ofUUasagroupofself-containedislands.*Although)oF*unnelWebwillcanproGcessthemacrosallontheirown,27thefullpowerofF*unnelWebis*realizedaonlywhenthemacrosaresurroundedbyaseaofdoGcumentation."Thisseacantaketwo*forms:directivesoandfreetext.Someofthedirectivescontrolthingssuchasthemaximuminput*lineJYlength.However,mostofthemaretypGesettingdirectivesthata ecttheprinteddoGcumentation.*ThusaF*unnelWebdoGcumentcanbGeviewedasasequenceofmacroM^de nitions,directiv9es,and*freeTtext.*UnliketheproGduct leswhichconsistofunscrambledmacrocalls,thedoGcumentation leismoreor*less='adirectrepresentationoftheinput le.cEachpartoftheinput leappGearsinthedocumentation* leintheorderinwhichitappGearsintheinput le.0However,eachdi erentkindofpartistypGeset^4*in>adi erentmanner.jMacrosaretypGesetinaparticularstyle,BwiththemacrobGody>appearingin*tt?fontl(seesomeF*unnelWeblprinteddoGcumentationforanexample).KTypGesetterdirectiveshave*spGeci cVde nede ects(morelater).vF*reetextistypesetexactlyasitis,Weexceptthateachblockof*textUUbGetweenblanklinesis lledandjusti edasaparagraph.*Thefollowingexampledemonstrateshowallthisworks.WTypGeinthefollowingasexample.fwand*runitthroughF*unnelWebwiththecommand\fw?example+t". The\+t"instructsF*unnelWeb*to=generateadoGcumentation lecalledexample.tex..Runthe lethroughTU>'ExXandprintit.*ExamineUUthe lesexample.outandexample.tex..*You?arereadingsomefreetextbeforethemacro.Freetextcanconsist*of?anytext(notcontainingtheFunnelWebspecialcharacter)including*typesetter?commands*such?as$,%,#,and\TeX{}which*will?betypesettoappearexactlyastheydointheinputfile!*Look?out!Herecomesamacro!*@O@==@{@-*This?textispartof*a?macrodefinition.*@}*This?isfreetextfollowingthemacro.Thissentencecontains*two?@{inline@}typesetter@/directives@/.*Now?hereisanon-inlinetypesettingdirective.*۟ĭffğ J= "5-:3LܸAsanexample,theauthorusedFJunnelWebtodevÎelopalargishcomputerprogramandfoundthatonaverage hisstÎyleofusingFJunnelWebresultedinab "5-:4LܸHerek}theterm\tÎyp'ExX.macrode nitions.GTheTU>'EX *coGdecorrespondingtotheinputaboveappGearsattheendofthe le.RZItshouldlooksomethinglike*this.*You?arereadingsomefreetextbeforethemacro.Freetextcanconsist*of?anytext(notcontainingtheFunnelWebspecialcharacter)including*typesetter?commands*such?as\$,\%,\#,and$\backslash$TeX$\{$$\}$which*will?betypesettoappearexactlyastheydointheinputfile!*Look?out!Herecomesamacro!*\fwbeginmacro*\fwfilename{example.out}{1}\fwequals?\fwodef\fwbtx[Thistextispartof*a?macrodefinition.*]fwetx=%*\fwcdef*\fwbeginmacronotes*\fwisafile{This?macroisattachedtoanoutputfile.}*\fwendmacronotes*\fwendmacro*This?isfreetextfollowingthemacro.Thissentencecontains*two?\fwlit{inline}typesetter\fwemp{directives}.*Now?hereisanon-inlinetypesettingdirective.*\fwnewpage*This?sentencewillappearonthenextpage./*TheUUfollowingpGointsexplaintheexample.tex le.y9G!Y oudon'tha9vetokno9wTeX:EIfyoudon'tknowTU>'ExX,don'tpaytoGomuchattentionG!toUUthissection.qY*oudon'tneedtoknowTU>'ExXtouseFunnelWeb.G!InTorder:qF*unnelWebUUhasmerelytransformedtheinput.Ithasn'trearrangedit.G!F reeEtext:54Most ofthefreetexthasbGeensimplycopiedover.The TU>'ExXtypesetterG!justi es%and llsallparagraphsfedtoitbydefault,/\somostofthetexthasjustbGeenG!copiedUUverbatim.G!T eXcoQdes:ThecharactersandsequenceswhichTU>'ExXtreatsasspGecialhavebGeenG!neutralizedhinthedoGcumentation le.3xF*orexample,\$"hasbecome\\$".3xBydefault,G!F*unnelWeballowstheusertowriteanytextasfreetextandnothavetoworryabGoutG!accidentallyUUinvokingtypGesetterfeatures.G!fw4sequences:Thefwsequences(e.g.\fwbeginmacro)invokeTU>'ExXmacrosde nedG!earlierUUinthedoGcumentation le(andnotshownhere).G!The,macro:)ThemacroistypGesetusingasetofprede nedTU>'ExXmacros.hSeetheG!printedUUdoGcumentationtoseewhatthisloGokslikeonpapGer.G!T9ypQesetterVMdirectives:RUnlike{theTU>'ExX^commandsequences(whichwereneutral-G!ized),>thevF*unnelWebtypGesetterdirectivesturnintoTU>'ExXamacrocalls.k*F*orexample,G!\@finline@g"UUbGecame\\fwlitfinlineg".K%33"ϐ)<;Ġݻ_"E*In^summary*,ɡFunnelWebproGducestypesetdocumentationthattransforms,ɡbutdoesnotreorder, *the:input le.hMacrosaretypGesetinaspeci cstyle.hF*unnelWeb:typGesetterdirectiveshavepartic-*ularwell-de nede ects.?F*reetextis lledandjusti ed,butwillotherwiseappGearintheprinted*doGcumentationUUexactlyasitappearsintheinput le."P卍*1.7.2STyp`esetterIndependenceٍ*AlthoughKthecurrentversionofF*unnelWebKcanonlygeneratedoGcumentation lesinTU>'ExX%form,*itrencouragestypGesetterindependencebyneutralizingallTU>'ExXqcontrolsequencesbGeforewriting*themout.fTheresultisthatyoudon'thaveworryabGoutupsettingordependingonTU>'ExXby*accidentallyhincludingsomespGecialcharacterorsequence.F#Bydefaultyourinput leist9ypQesetter*indepQenden9t.:*This^schemedi ersfromotherliterateprogrammingtoGols,#includingallearlierversionsofF*unnel-*W*eb,5which.copytheirfreetextdirectlytothedoGcumentation le,5thejusti cationbGeingthatthe*programmerXcanusethefullpGowerXofthetypesetterlanguagetodescribetheprogram.PsThedisad-*vqantagesT!ofdoingthisare rstthattheprogrammerisrequiredtoknowthetypGesettinglanguage*andsecondthattheinput lebGecomestypesetterdependent.ؔF*unnelWebavoidstheseproblems*byUUknobblingthefreetextbGedefault.:*However,,F*unnelWeb"doGesprovideatrapdoorforthosewhowant"theirfreetexttobefeddirectly*toS(TU>'ExX.T*oopGenthetrapdoor,Ssimplyincludethefollowingpragmasomewhereinyourinput le.A*@p?typesetter=tex*SeeUUSection3.11.2formoreinformation.*F*unnelWeb4leavesthedegreetowhichtheuserwishestobindaparticulardoGcumenttoaparticular *typGesetteruptotheuser.XInsomecases,{theextratypGesettingpowermaycompGensateforthelack*ofy(pGortability*.AHowever,asarule,itisbGesttoavoidtypGesetter-speci ccommands,soastoallow*your ginput lestobGeformattedatalaterdatefordi erenttypGesetters.F*unnelWeb gincludesa*numbGer}`ofitsowntypGesettercommandssoastosupporttypesetter-independent}`input les.The*followingwsectionsdescribGesomeofthesecommands.&Inparticular,thenextsectiondescribesthe*mostpGowerfulF*unnelWebtypGesettingdirectiveswhichallowtheusertostructurethedoGcument*hierarchically*."P卍*1.7.3SHierarchicalStructureٍ*Themtreestructureisoneofthemoste ectivestructuringtoGolsthatexists,derivingitspower*fromtheprincipalofdivideandconquor.xSoe ectiveisitthattheinternalorganizationofmost*technicalbGooksaretreestructureswhichareconciselysummarizedinthetableofcontents.fIn*contrast,+computer!programsareusuallypresentedas atsequencesoftexttobGeconsumedbyan*anonymousUUcompiler.*InŚordertobringprogramdoGcumentationuptothestructuralsophisticationcommonplacein*technicalbGooks,4F*unnelWebprovides velevelsofsectionheadingsimplementedbythe vespGecial*sequences@A,@B,@C,@D,and@E.ThesemustalwaysappGearatthestartofaline.N @Aisthehighest*level"section(e.g.likeLffUIaTU>ExX's\chapter)and@Eisthelowestlevelsection(e.g.likeLffUIaTU>ExX's*\subsubsubsection).XSectionheadingscanappGearanywhereinthefreetextofaF*unnelWeb*inputUU le(i.e.anywhereexceptinsideamacrode nition).*Each sectionheadinginaF*unnelWeb doGcumenthasanassoGciatedname.~Thenameofasection*canbGeprovidedexplicitlybysupplyingitdelimitedby@immediatelyafterthesection*sequence(e.g.@A),orimplicitlybynotprovidinganexplicitname,(inwhichcasethesectiontakes*themnameofthe rstmacrode nedbGetweenmthesectionheaderinquestionandthefollowingsection*header.BAnWerrorisgeneratedifasectionhasnotbGeengivenanexplicitnameanddoesnotcontain*anyUUmacrode nitions.qHerearesomeexampleheadings:K%34#)<;Ġݻ_"E*@A@ *@B@*@C@*@C@*@B@*@C@*@C@*@C?Thisheadinghasn'tbeengivenanexplicitname,butwillinheritthe*name?\p{Savetherestoftheworld}fromthemacrodefinitionbelow.*@$@@Z==@{...@}*Thefeatureofhavingunnamedsectionsinheritthenameofthe rstmacrode nedwithintheir*scopGe ispresentbecauseacommonstyleofwritinginF*unnelWeb istohaveonesectionpGermacro*de nition.lBecause,(Bunderthisstyle,eachsectiondescribGesasinglemacro,itusuallyturnsout*that^themacronamemakesagoGod^nameforthesectiontoGo.OuTheinheritancemechanismprevents*duplicationUUofthename.ߍ*ApartfromtherequirementthateachsectionhaveanexplicitorimplicitnameandthatitsspGecial*sequencepappGearatthestartofaline,theonlyotherrestrictiononsectionheadingsisthata*section=headingatlevelncannotappGearimmediatelyafterasectionheadingatleveln1=orless.*Innotherwords,4thehierarchycannotbGebroken.CF*orexample,4an@CFcannotappGearafteran@A*headingUUunlessthereisaninterveningUU@Bheading.*@A@*@C@*Thisaruleextendstothestartofthe le;gifthereareanyheadingsatall,dthe rstonemustbGean*@AUUheading.qThefollowing le,whileshort,isinerror.*This?FunnelWebinputfileisinerrorbecauseitsfirstsectionheading*is?atlevelCratherthanlevelA.*@C@<2@>"*1.7.4SUnderstandingthePrintedDo`cumentation}*TypGehinthefollowing le,[anduseF*unnelWebhandTU>'ExXhFtogeneratethecorrespGondingprinted*doGcumentation.*@A@*@t?table_of_contents*@A@*The?followingmacrocontaincommentsthatprovidemoralsupportinthe *output?code.*@$@@M==@{*--?Shifttotheleft!*--?Shifttotheright!*--?Popup,pushdown!*--?Byte!Byte!Byte!*--?(From"TheNewHacker'sDictionary").K%35$)<;Ġݻ_"E*@}*The?nextmacroissimilarbutisdistributedthroughouttheprogram. *@$@+=@{@+--Pointertotheleft@+@}*@A@*@B@*@$@+=@{--Pointertotheright@+@}*@$@@Z==@{typestack=record...end;@}*@B@*@$@+=@{--Hackthatcode@+@}*@$@@Z==@{@-*procedure?push(varb:stack;v:value);@{...}@}*@B@*@$@+=@{--Tight!Tight!Tight!@+@}*@$@@Z==@{@-*procedure?pop(varb:stack);@{...}@}*@B@*@$@+=@{--(RNW,04-Jan-1991).@+@}*@$@@Z==@{@-*procedure?rough(varb:stack);@{...}@}*@O@==@{dummy@+@}-A*AnexaminationoftheprinteddoGcumentationrevealsalotabGouthowF*unnelWeb'spresentation*works. *First,$tnotice'ExXYhmacros,butuseofthe(more*general)F*unnelWebtypGesettingdirectivestodothesameworkhastheaddedbGene tofkeeping*theUUdoGcumentportabletoothertypesetters.,*F*unnelWeb{providestwoin-texttypGemodi cationconstructs:@f...@gand@/...@/where:::ois*rawtext.0The@f...@gconstructsetstheenclosedtextinthesamemannerasthetextofmacro*de nitionsqisset.%The@/...@/constructemphasisesitsenclosedtextinsometypGesetter-dependent*fashion.qTypicallyUUtheemphasisedtextissetinitalics.*HereUUisanexampleofhowtheseconstructsmightbGeused:o*The?followingprocedure@{put_sloth@}writesthe@{sloth@}variableto*the?outputfile.Note:@/Theoutputfilemustbeopenedforwriting*at?thispointortheprogramwillcrash!@/"*1.7.6SAddingaHeaderPage3*F*unnelWebprovidesafewtypGesetter-independenttypesettingconstructswhicharespGeci cally*designed%pfortheconstructionofheaderpages.aTheseconstructsareusuallybGestplacedatthetop*ofyourinput le,jbutcanbGeplacedanywherethedoGcumentifdesiredtocreateheaderpagesright*through.dTheƉtwomainrestrictionsontheseconstructsisthatthe@tmuststartatthestartof*aline(whichcannotcontaincomments),1andthattheconstructscannotappGearinsideamacro*de nition.qHereUUiswhatthetopofaninput lemightloGoklike:o*@t?vskip40mm*@t?titletitlefontcentre"HairyWombat"*@t?titletitlefontcentre"Simulation"*@t?vskip10mm*@t?titlesmalltitlefontcentre"APrograminSixParts"*@t?titlesmalltitlefontcentre"SimulatingtheLifeofSomeHairyWombats"*@t?vskip20mm*@t?titlenormalfontleft"ByZqitzypbuswapzraYpongtatoslrtzz"*@t?new_page*@t?table_of_contents*@t?new_pageo*The#@tatthestartofeachlineindicatesthateachentirelineisatypGesetterdirective.aLThevskip*directiveinstructsF*unnelWebtoskipsomeverticalspace(measuredinmillimetres).Thetitle*directive instructsF*unnelWeb topGositionastringoftextonasinglelineofitsown.Optionsare*providedܜforfontandalignment.The rstwordaftertitleisthefontwhichcanbGeoneof(in*decreasingCorderofsize)titlefont,smalltitlefont,andCnormalfont.6Thesecondwordafter*titlenisthedesiredalignmentofthetext.Theoptionshereareleft,uright,andncentre.The*newEff&fǫpage2directiveinstructsF*unnelWeb2toskiptoanewpage.^Finally*,)thetableEff&fofEff&fcontents*directiveUUinstructsF*unnelWebUUtoinsertatableofcontentsatthatpGointinthetext."*1.7.7SComments3*AWF*unnelWebcommentcommenceswiththe@!xsequenceandcontinuesupto,XSbutnotincluding,*theaendoflinemarkerattheendofthelinethatthecommentsequenceison.CommentscanbGe*placedUUonanylineexcept@iinclude,@ppragma,and@ttypGesetterdirectivelines.K%37&)<;Ġݻ_"E*ThetextfollowingtheF*unnelWebcommentsequence@!willnotappGearintheproduct lesor *the!doGcumentation le.MaItisonlyfortheeyesofthosewhobGothertolookattheoriginal.fwinput* le.pTypicallyR$F*unnelWebcommentsareusedtodescribGethewayinwhichparticularF*unnelWeb*constructsUUarebGeingused.qExample:7荑*@!?Thismacroisreallyrevolting.Pleaseforgiveme.Ihadtodoit!*@$@==@{@-*@#X@(@#Y@(@#Z@,@"@#Z@"@)=6@,Teapot@,@"@#Q@(45@)@"@,Tiger@)@}&*1.8PfACompleteExample*T*o nisho thechapter,$4acompleteexampleofaFunnelWebinput leispresented.bEAlthough*unrealisticallyUUshort,itgivesabGetterideaofwhatatypicalF*unnelWebUU.fw leloGokslike.7荑*@!---------------------------------------!*@! Start?ofFunnelWebExample.fwFile!*@!---------------------------------------!*@t?vskip40mm*@t?titletitlefontcentre"Powers:"*@t?titletitlefontcentre"AnExampleof"*@t?titletitlefontcentre"AShort"*@t?titletitlefontcentre"FunnelWeb.fwFile"*@t?vskip10mm*@t?titlesmalltitlefontcentre"byRossWilliams"*@t?titlesmalltitlefontcentre"26January1992"*@t?vskip20mm*@t?table_of_contents*@A@*This program?writesouteachofthefirst@{p@}powersofthefirst@{n@}*integers.?These constantparametersarelocatedheresothattheyareeasyto*change.*@$@==@{@-*n?:constantnatural:=10;?--Howmanynumbers?(Ans:[1,n]).*p?:constantnatural:= 5;?--Howmanypowers?(Ans:[1,p]).@}*@B?Hereis theoutlineoftheprogram.ThisFunnelWebfilegeneratesasingle*Ada?outputfile called@{Power.ada@}.Themainprogramconsistsofaloopthat*iterates?onceforeachnumbertobewrittenout.*@O@==@{@-*@*procedure?exampleis:m@*begin?--example:mfor?iin1..nloopJ-@:mend?loop;*end?example;*@}K%38')<;Ġݻ_"E*@B?Inthissection, wepullinthepackagesthatthisprogramneedstorun.In *fact,?allweneedistheIOpackagesothatwecanwriteouttheresults.Touse*the?IOpackage,wefirstofallneed tohaulitin(@{withtext_io@})andthen*we?needtomakeallitsidentifiersvisibleatthetoplevel(@{usetext_io@}).*@$@==@{withtext_io;usetext_io;@}*@B?Hereis thebitthatwritesoutthefirst@{p@}powersof@{i@}.Thepower *values arecalculatedincrementallyin@{ip@}toavoidtheuseofthe*exponentiation?operator.*@$@==@{@-*declare:mip?:natural:=1;*begin:mfor?powerin1..ploopJ-ip:=ip*i;J-put(natural'image(ip)?&"");:mend?loop;:mnew_line;*end;@}*@!---------------------------------------!*@!End?ofFunnelWebExample.fwFile!*@!---------------------------------------!'č*1.9PfSummary*ThischapterhasprovidedanintroGductiontoF*unnelWebandatutorialthatcoversmostofits*features.<}F*unnelWeb'svfunctionalitycanbGesplitintotwoparts:!amacropreproGcessor,oandsupport*fortypGesetting.JThereadershouldbeawarethattheexamplesinthischapter,Tconstructedasthey*wereHtodemonstrateparticularfeaturesofF*unnelWeb,doHnotpresentarealisticpictureofthebGest*usevVofthetoGol.Onlythe nalexampleofthischaptercomesclose.Thereadershouldstudythis*lastZexamplecarefullyandthenwritesomerealprogramsusingF*unnelWebZbGeforeproceedingto*Chapter`2whichprovidesmoreadvqancedinformation.8AtthisstageitdoGesnotparticularlymatter*exactlyhowyouuseF*unnelweb,Ҹaseveryonedevelopstheirownstyleanyway*.;[TheimpGortantthing*isUUtotryit.K%39(")<;ĠݻK%40)+1)<;Ġݻ*JChapterF26z*HFunnelWeb Hin4ts8z*WhereasChapter1providesanintroGductiontoF*unnelWebandChapter3ade nition,thischapter *containshintsabGouthowF*unnelWebcanbGeused.Z Thischapterprobablyshouldnotbereaduntil*theJreaderhasalreadycommencedusingF*unnelWeb,GorJattheveryleast,triedoutsomeofthe*examplesinChapter1.JThosewho ndthemselvesusingF*unnelWebfrequentlyshouldreadthis*chapterUUatsomestagesoastoensurethattheyaregettingthemostoutofit.z*Most|moftheexamplesinthischapterhavebGeenplacedintheF*unnelWeb|mregressiontestsuite*whichTshouldbGeavqailableinadirectorycalled/fwdir/tests/.qUThe lestoexaminearehi01.fw*throughUUhi10.fw.%~*2.1PfMacroNamesܕ*WhenusingF*unnelWeb,thechoiceofmacronamescanbGeasimportanttothereadabilityofa*programqasthechoiceofprogramidenti ers,xanditisimpGortantthattheuserknowtherangeof*optionsUUavqailable.G!Namesŷarecasesensitiv9eandexactmatching:jMacroGnamesarecasesensitiveG!and|arematchedexactly*.S)ThestringsusedasamacronameatthepGointofde nitionG!andUUcallmustbGeidentic}'alfortheconnectiontobemade.G!Namesecancon9tainanyprintablecharacter:F*unnelWebcislessrestrictiveabGoutG!itsaKmacronamesthanmostprogramminglanguagesareabGouttheiridenti ers.AG!F*unnelWebmacronamecancontainanysequenceofprintablecharacters,includingG!blanks>andpunctuation.FjNamescanstartandendwithanycharacter.FjNamescannotG!crossUUlinebGoundaries.qThefollowingarealllegalmacronames:[*T@T@<@>T@<453?#$%&#--===~~1">>>@>T@<<@>T@<<>@>T@T@<$!?@>T@T@<"Who's?beenhackingMYprogram"saidFatherBear.@>T@G!Namesrm9ustbQenomorethanamaximumlimitinlength:`pNames2canbGenoG!longerthanaprede nedmaximumlength.SCurrentlythislengthcannotbGemodi ed.z*Typically*,+macro]nameswillconsistofashortEnglishphraseorsentencethatdescribGesthecontents*ofUUthemacro.K%41*+~)<;Ġݻ_"E*2.2PfQuic=kNames*SometimesmaparticularmacromustbGeusedextremelyoften.1Whenthishappensitisdesirable *tolmakethemacro'snameasshortaspGossible.aTheshortestordinaryF*unnelWeblmacronameis*theKemptyname\@<@>",Mwhichisfourcharacterslong.nZSingle-characternamesare vecharacters*long.ߍ*T*o`caterforthecaseswherereallyshortnamesareneeded,cFunnelWebprovidesaquic9kQname*syntax,thatallowsone-charactermacronamestobGespeci edintwo,lesscharacters.d,Quick,names*taketheformofthespGecialcharacter,3followedbyahash(#)followedbyasinglecharacter.*Examples:*@#A?@#|@#&@#m*ThisformofmacronamehasthesamesyntacticfunctionalityasanordinarynameandcanbGe *substitutedIwhereveranordinarynamecanbGe.Infactquicknamesliveinthesamenamespace*asordinarymacronames..ߍ*BecausequicknamesloGoksyntactically\opGen"(i.e.theydonothaveaclosing@>asordinarynames*do),UUitisbGesttoavoidUUthemexceptwhereamacromustbecalledveryoften.'*2.3PfFunnelWebtheMartinet*TherearemanywaysinwhichamacropreproGcessorcancauseunexpecteddiculties.MF*unnelWeb*seekstoavoidmanyoftheseproblemsbypGerforminganumbGerofchecks./ThissectiondescribGes*someUUofthechecksUUthatF*unnelWebUUpGerforms.ߍG!T railingpblanksintheinput le:T*railingsblanksareusuallynotdangerous,{butG!F*unnelWeb]disallowsthemanyway*.Alltrailingblanksintheinput(.fw le)areG! aggedcaserrorsbyF*unnelWeb.!FunnelWebcdoGesnot agtrailingblanksinanyofG!itsUUoutput les.G!Inputlinelength:=F*unnelWeb;Ehasamaximuminputlinelength.#IfF*unnelWebG!readsaninputlinelongerthanthislength,'it agsthelinewithanerrormessage.G!TheUUmaximumlengthcanbGechangedusingapragma(seeChapter3).G!ProQductĬ lelinelength:F*unnelWeb%uwatchesthelengthofoutputlinesandallG!output,lineslongerthanthelimitare aggedwitherrormessages.%ThemaximumG!lengthycanbGechangedusingapragma(seeChapter3).2ThatF*unnelWebypolicesG!output9linesisveryimpGortant.hSomeprogramscanbGehaveverystrangelyiftheygetG!aninputlinethatistoGolong(e.g.F*ortrancompilerscansimplyignoretextpastaG!certain`column!)_andonceF*unnelWeb`startsexpandingmacrosusingindentation,citG!isUUsometimesnotobvioushowwidetheproGduct lewillbe.G!Con9trol+characters:dThepresenceofcontrolcharactersinatext lecanresultinG!someconfusingbGehaviourdownstreamwhenthe leispresentedtovqariousprograms.G!Unfortunately*,>!some8StexteditorsallowcontrolcharacterstobGeinsertedintothetextG!rathertoGoeasily*,anditisalltooeasytobetrippedup.}F*unnelWebpreventstheseG!problemsby aggingwithdiagnosticsallnon-end-of-linecontrolcharactersdetectedG!inxtheinput(.fw) le(evenT*ABs).C1TheresultisthattheuserisguaranteedthatG!proGductN lesgeneratedfromF*unnelWebNcontainnounintentionalcontrolcharacters.G!This!said,+F*unnelWebdoGesallowtheinsertionofcontrolcharactersintheoutput leG!byUUexplicitlyspGecifyingtheminthetextusinga@^controlsequence.G!Num9bQerDofinvoQcations:iF*unnelWeb~&checksthenumbGeroftimesthateachmacroG!is6calledandissuesanerrorifthetotalisnotone.The@Z6(forzero)and@M(forG!many)UUmacroattributescanbGeusedtobypassthesechecks.K%42+6N)<;Ġݻ_"EG!Recursion:(BecauseF*unnelWebdoGesnotprovideanyconditionalconstructs,all G!recursivelyde nedmacrosmust, byde nition, expandin nitely*,^1handarethereforeG!unacceptable.F*unnelWebpGerformsstaticcheckstodetectrecursion,#$detectingitG!bGeforemacroexpansioncommences.F TheuserneednotfearthatF*unnelWebwilllockG!upUUorspGewforthifarecursivemacroisaccidentallyspGeci ed.&*2.4PfFiddlingWithEndofLines:O*Oneofthe ddlyaspGectsofprogrammingwithF*unnelWebiscopingwithendoflines.TIfyouwant*your proGduct letobewellindentedwithoutmultipleblanklinesorcoGderun-ons,9$youhaveto*spGendUUalittletimeworkingouthowtheendoflinemarkersgetmovedaround.S4*TheruletoremembGeristhat,ͭdisregardingthee ectsofspecialsequenceswithinamacrobody*,*theub}'odyofamacroconsistsofexactlythetextbetweentheopening@fandtheclosing@g.TThis*textUUincludesendoflinemarkers.*IfUUforexampleyoucallamacroinasequenceofcoGde:::5*while?the_walrus_is_sleepydo:mbegin:mwriteln('zzzzzzz');:m@:mwriteln('Umpharumpha...');:mend;*whereUUisde nedasfollows*@$@==@{*wake_up_the_walrus(the_walrus);*@}*thenUUwhenUUisexpandedyouwillget*while?the_walrus_is_sleepydo:mbegin:mwriteln("zzzzzzz");:mwake_up_the_walrus(the_walrus);:mwriteln("Umpharumpha..."); :mend;*The blanklineswereintroGducedbytheendonlinemarkersincludedinthede nitionof.,AgoGodsolutiontothisproblemistosuppresstheendoflinemarkersbyde ning*theUUmacroasfollows*@$@==@{@-*wake_up_the_walrus(the_walrus);@}*ThisUUistheusualformofmacrode nitionsinF*unnelWebUU les.S4*InZadditivemacros,\&thisformatdoGesnotworkpropGerlybecausetheendoflinethatissuppressed*by'(thetrailing@gdoGesnotgetreplacedbytheendoflineattheendofthemacroinvoGcation.bcF*or*exampleUUthede nition*۟affğ J= "5-:1LܸA5&sp+=@{@- *wake_up_the_walrus_once(the_walrus);@}Z*laterUUfollowedby*@$@+=@{@-*wake_up_the_walrus_again(the_walrus);@}*isUUequivqalenttothesinglede nition*@$@==@{@-*wake_up_the_walrus_once(the_walrus);wake_up_the_walrus_again(the_walrus);@}*Puttingq3thetrailing@gonanewlineattheendofthemacro(exceptforthelastde nitionpart)*solvesUUtheproblem.*@$@+=@{@-*wake_up_the_walrus_once(the_walrus);*@}*laterUUfollowedby*@$@+=@{@-*wake_up_the_walrus_again(the_walrus);@}*isUUequivqalenttothesinglede nition*@$@==@{@-*wake_up_the_walrus_once(the_walrus);*wake_up_the_walrus_again(the_walrus);@}*Managing;oendoflinemarkersistricky*,@butonceyouestablishaconventionforcopingwiththem,*theUUproblemdisappGearsintothebackground.&1*2.5PfFudgingConditionalsލ*AsamacropreproGcessor,thefacilitythatF*unnelWebmostobviouslylacksisaconditionalfacility*(such>+asC's#ifdef).,HItmight,x`therefore,come>+asasurprisetoknowthatthe rstversionof*F*unnelWeb75actuallyhadabuiltinconditionalfacility*.hThefacilityallowedtheprogrammerto*spGecifyaconstructthatwouldselectfromoneofanumbGerofmacroexpressionsdependingonthe*vqalueUUofacontrollingmacroexpression.Í*InUUthreeyearstheconstructwasneverused.*ThemreasonwasthatconditionalconstructscouldbGefudgednearlyaseasilyastheycouldbeused.*Because` ofthis,btheinbuiltconditionalfeaturewasremovedinthecurrentversionofF*unnelWeb.*Notonlydidthissimplifytheprogram,٤butisalsoallowedrecursivemacrostobGedetectedthrough*staticUUanalysisratherthanduringmacroexpansion.*Therearetwobasicwaystofudgeaconditional.First,C>thecommentfacilityofthetargetpro-*grammingalanguagemaybGeemployed.F*orexample,einAda,commentscommencewith\--"and*terminate[attheendoftheline.QUsingthisfact,]yitiseasytoconstructmacrosthatcanbGecalled*atthestartofeachtargetlineandwhichturnonando thelinessomarkedbyde ningthemacro*toUUbGetheemptystring(ON)orthecommentsymbGol(--)(OFF).F*orexample:K%44-S)<;Ġݻ_"E*@A@*The?followingmacrodetermineswhetherdebugcodewillbeincludedinthe *program.?Alllinesofdebugcodecommencewithacalltothismacroandso*we?canturnallthatcodeonoroffherebydefiningthismacrotobeeither*empty?orthesingle-linecommentsymbol(\p{--}).Notetheuseofa*quick?macroname.*@$@#D@M==@{@}?@!?TurnsthedebugcodeON.*@!?UsethisdefinitiontoturnthedebugcodeOFF:@$@#D==@{--@}*...?thenlaterinthefile...*@$@==@{@-*while?sloth=walrus!!!!!!!");:m@#D?assert(timer=timermax!!!");:minc(sloth);*end?loop@}.ꍑ*Thezotherwayztofudgeaconditionalistode neamacrowithasingleparameter./5Ajcalltothe*macrogisthenwrappGedaroundalltheconditionalcodeintheprogram.Themacrocanthenbe*de nedUUtopresentorignorethecoGdeofitsargument.qF*orexample:*@A@*The?followingmacrodetermineswhetherdebugcodewillbeincludedinthe*program.?Alldebugcodeiswrappedbyacalltothismacroandso*we?canturnallthedebugcodeonoroffherebydefiningthismacrotobe*either?emptyoritsparameter.*@$@#D@(@1@)@M==@{@1@}?@!?TurnsthedebugcodeON.*@!?UsethisdefinitiontoturnthedebugcodeOFF:@$@#D@(@1@)==@{@}*...?thenlaterinthefile...*@$@==@{@-*while?sloth=walrus!!!!!!!");Tassert(timer=timermax!!!");@):minc(sloth);*end?loop@}.ꍑ*Inlanguagesthatallowmulti-linecomments(e.g.Cqwith/*and*/),commentscanbGeusedto*eliminateUUtheconditionedcoGderatherthanabsence.qF*orexample:*@$@#D@(@1@)@M==@{/*?@1*/@}@!Commentsoutthedebugcode*(Note:CIf;thisexamplewereeveractuallyused,utheprogrammerwouldhavetobGecarefulnotto*placeUUcommentsintheargumentcoGde.qNestedcommentsinCarenon-pGortable.)C*TheparameterizedmacroideacanbGegeneralizedtosupportthechoiceofmorethanonemutually*exclusiveUUalternative.qF*orexample:*@A?Thismodulecontainsnon-portablecodethatmustexecuteonHewlett*Packard,?Sun,andDECworkstations.ThefollowingFunnelWebmacroisK%45.^)<;Ġݻ_"E*defined?tochoosebetweenthesethree.ThefirstparameteristheHPcode, *the?secondistheSuncode,andthethirdistheDECcode.Whichever*parameter?constitutesthebodyofthismacrodetermineswhich*machine?thecodeisbeingtargeted\note{Dictionarysaysonlyonet*in?targeted.}for.*@$@@(@3@)@M==@{@1@} @!ConfigureforHP.*...then?laterinthefile...*@@( *@"get_command_line(comline)@"9@,?@!HP.*@"scan_command_line(128,comline);@"?@,?@!Sun.*@"dcl_get_command_line(comline,256);@" @)?@!DEC.^*Of course,thiscouldalsobGeperformedusingthreeseparatemacros.VThemainadvqantageofusing*asinglemacroisthatthemutualexclusivityisenforced.5Also,bGecauseF*unnelWebensuresthat*thenumbGerofformalandactualparametersarethesame,thismethodlessensthechancethata*machineUUwillbGeforgotteninsomeplaces.%Щ*2.6PfChangingtheStrengthofHeadings*F*unnelWebU"provides veheadinglevels:q`@A,@B,@C,@D,and@ETtowhichitbinds vedi erent*typGographical1strengths.i\Thesebindingsarestatic;Q alevel@AheadingwillalwaysbGetypGesetin*aparticularfontsizeregardlessofthesizeofthedoGcument.9 ThefontsizeshavebGeenpresetto*bGe`\reasonable"forarangeofdocumentsizes,butmaybGeinappropriateforverysmallorlarge*doGcuments.*F*unnelWeb2doGesnotcurrentlyprovidean\ocial"way(e.g.apragma)tochangethetypGesetting*strengthofheadings.IThisfeaturemightbGeaddedinlaterversions.IMeanwhile,ahackisavqailable*that4willdothejob,*providingthatyoudonotmindthehackbGeingTU>'ExX-speci candprobably*F*unnelWeb-versionUUspGeci c.*InsideK!thesetofTU>'ExXKmacrode nitionsthatF*unnelWebK!writesatthetopofeverydoGcumentation* leeare ve\library"de nitionsfwliba::: fwlibewhichprovide vedi erenttypGesettingstrengths*forheadings.Neartheendofthesetofde nitions,ըF*unnelWebbindsthesemacrosto veother*macrosFfwseca::: fwsecewhichareinvokeddirectlyinthegeneratedTU>'ExXcoGdetotypGesetthe*headings.^*\def\fwseca#1#2{\fwliba{#1}{#2}}*\def\fwsecb#1#2{\fwlibb{#1}{#2}}*\def\fwsecc#1#2{\fwlibc{#1}{#2}}*\def\fwsecd#1#2{\fwlibd{#1}{#2}}*\def\fwsece#1#2{\fwlibe{#1}{#2}}*ThisEmeansthatthetypGesettingstrengthoftheheadingsinaF*unnelWebEdocumentcanbechanged*byUUrede ningthesemacrosatthetopofaF*unnelWebUUdoGcument.qForUUexample:*@p?typesetter=tex*\def\fwseca#1#2{\fwlibc{#1}{#2}}*would|set@A|Theadingsatthesamestrengthasthedefaultstrengthof@Cheadings.)Thetypesetter*directiveNisnecessarytoensurethattheTU>'ExXNcontrolsequencesgetthroughtothedoGcumentation* leUUun ltered.*The9followingwilltonedownallheadingsbytwolevels(withthe@D9and@ElevelsbGeingallocated*theUUdefault@EtypGesettingstrengthbecausethereisnothingweaker).K%46/i)<;Ġݻ_"E*@p?typesetter=tex *\def\fwseca#1#2{\fwlibc{#1}{#2}}*\def\fwsecb#1#2{\fwlibd{#1}{#2}}*\def\fwsecc#1#2{\fwlibe{#1}{#2}}*\def\fwsecd#1#2{\fwlibe{#1}{#2}}*\def\fwsece#1#2{\fwlibe{#1}{#2}}[*Thesede nitionsa ectonlytheheadingsthatfollowthem,ՕandsotheyshouldbGeplacedatthe*topUUoftheF*unnelWebUUinput le.'*2.7PfEciencyNotes-*TheUUfollowingnotesareworthkeepinginmindwhenusingF*unnelWeb.$fG!Memory:"WhenQF*unnelWebproGcessesaninput le,itreadstheentireinput le,andG!alltheincluded lesintomemory*.^2 ThisorganizationdoGesnotposeaconstraintonG!machinesOwithlargememories,PbutcouldpresentaproblemonthesmallermachinesG!suchUUasthePC.G!SpQeed:A%F*unnelWebisnotaslowprogram.Q[However,itisnotparticularlyfasteither.G!IfthespGeedatwhichF*unnelWebrunsisimportanttoyou,4thenthethingtokeepG!inmindisthatF*unnelWebhasbGeenoptimizedtodealecientlywithlargeslabsofG!text.f7F*unnelWebtreatsinput lesasasequenceoftextslabsandspGecialsequencesG!(e.g.>2@+)andwheneverithitsaspGecialsequence,xiithastostopandthink.,^Thus,G!while^atenmegabytetextslabwouldbGemanipulatedasasingletoken, inafewG!milliseconds,0&a&similartenmegabytechunk lledwithspGecialsequenceswouldtakeaG!lotlonger.#IfF*unnelWebisrunningslowly*, "loGoktoseeiftheinputcontainsahighG!densityDOofspGecialsequences.lThiscansometimeshappenifF*unnelWebDOisbeingusedG!asabackendmacroproGcessoranditsinputisbeinggeneratedautomaticallybysomeG!otherUUprogram.G!Macro expansion:ΕWhentangling(expandingmacros),VF*unnelWebneverexpandsG!amacroexpressionintomemory;?italwayswritesittotheproGduct leasitgoes.5-?Displayscurrentlyactiveoptions.DTRACE?ON)-TurnscommandtracingON.DQUIT>-?QuitsFunnelWeb.圍*T*o OdistinguishherebGetween Oinvocations OoftheF*unnelWeb OprogramandF*unnelWeb Orunsinside*theKshell,MwecallthelatterF unnelWeb,propQer.nTheK\FW"KcommandinvokesF*unnelWebKpropGer*withNthespGeci edoptionswhichtakethesamesyntaxastheydoonthecommandline.oTheonly*restriction[bisthatnoneoftheactionoptionscanbGeturnedonexcept\+F"[awhichmustbGeturned*on. *The\SET"commandhasthesamesyntaxasthe\FW"commandexceptthatitdoGesnotallowany*action0optionstobGespeci ed.eIt'ssolee ectistosetdefaultoptionvqaluesfortherestoftherun.*TheUU\SHOW"commanddisplaysthecurrentdefaultoptions.*Bydefault,$F*unnelWebdoGesnotechothecommandsthatitprocessesinascript.JThe\TRACE?ON"*commandUUturnsonsuchtracing.*ThesecommandscanbGecombinedtostreamlinetheuseofF*unnelWeb.VForexample,youmight*wishUUtocreateascriptcalledtypeset.fwstoproGcessawholegroupof les.圍*trace?on*!This?scripttypesetsthewholeprogram.*!?Setnolistingfile,noproductfiles,butspecifyadocumentationfile*!?andspecifythedirectoryintowhichitshouldbeplaced.*set?-L-O+T/usr/ross/typeset/*fw?prog1*fw?prog2*fw?prog3*fw?prog4*TherewareafewwayswinwhichthisscriptcanbGerun.'Thesimplestissimplytospecifyitinthe\+X"*optionofaF*unnelWebinvoGcation."and*\.fws".*fw?+xtypeset*TheUUsecondalternativeistoenterinteractivemoGde.*fw?+k*F*romUUthere,youcanexecutethescriptusing:*execute?typeset*Interactive moGdecouldbeveryusefultothosewithmultiple-windowworkstations.MZTheusercould*createawindowcontaininganinteractivesessionofF*unnelWeb,5andthenswitchbGetweenwindows,*editing,UUandexecutingF*unnelWebUUpropGerandotherprograms. *Ifyou ndyourselfusingthecommandinterpreteralot,PbGesuretoreadabouttheothercommands*thatUUareavqailableinChapter3.K%481)<;Ġݻ_"E*2.9PfSettingUpDefaultOptionsER*IfyoudonotlikeF*unnelWeb'sdefaultsettingsforitscommandlineoptions,}thereareanumbGer *ofUUwaysinwhichyoucanchangethem.A܍G!De ne;an\alias":/UseyouropGeratingsystem\alias"facilitytocreateanaliasforG!F*unnelWeb containingthedesiredoptions.`8F*unnelWeb proGcessesoptionsfromlefttoG!right,UUsoyoucanoverridethesedefaultslaterifyouwish.G!Create3asingle.fw lemayhavemanymacrode nitionsconnectedtoproGduct* lessothatwhentheF*unnelWeb.fw leisproGcessedbyF*unnelWeb,7several lesarecreated.TF*or*example,!thisSfacilityhasbGeenusedtogreate ecttoplacethedescriptionofanAdapackqage's*packqageUUspGeci cation leandpackqagebGodyUU leinthesameF*unnelWebUU.fw le.*TheluseofmultipleproGduct les,.however,provokeslaproblemwithdepGendencies.| Supposelfor*examplelthataF*unnelWeblprog.fwproGducestwolproduct lesproc.spec(apackqagespeci cation)*andnprog.body(apackqagebGody)."Ifnthepackqageisaccessedinthewaythatpackqagesnormally*are,lit4FwillbGequitecommonfortheprogrammertowant4Ftomodifythepackqagebodywithout*moGdifyingztheprogramspeci cation.hSotheprogrammerwilledittheprog.fw letochangethe*packqageNbGody*.the* leUUx.datwouldbGeuntouchedand,asaresult,nofurtherMakepropagationswouldtakeplace.*F*unnelWeb.implementsthisfeaturebywritingeachproGduct letoatemporary lewithatempo-*raryt lename.k#ItthencomparesthetempGorary lewiththetarget le.Ifthetwotareidentical,K%492)<;Ġݻ_"E*itB deletesthetempGorary le.7IfthetwoB aredi erentitdeletesthetarget leandrenamesthe *tempGoraryUU letothetarget le.إ*UseuoftheDuUfacilitymeansthattheprogrammerneednotbGepunished(byextraMakepropagations)*forUUdescribingmorethanoneproGduct leinthesameF*unnelWebUU le.&w*2.11XTheDangersofFunnelWeb*LikemanytoGolsthataregeneraland exible,F*unnelWebcanbGeusedinavqarietyofways,bGoth*goGodandbad.|cOneoftheoriginalappGealsoftheliterateapproachtoprogrammingforKnuth,*the!inventorofliterateprogramming,TwasthatitallowstheprogrammertodescribGethetarget*program3bGottomup,:{topdown,sizetoside,orchaoticallyifdesired.fThe exibilitythatthisstyle*ofeprogrammingleavesemuchroGomforbaddocumentationaswellasgoGoddocumentation.:Y*ears*of3expGeriencewithF*unnelWeb3hasrevealedthefollowingstylisticpitfallswhichtheexpGerienced*F*unnelWebUUusershouldtakecaretoavoid.^3إG!Spaghettiitismainlytheauthor'soÎwnmistakesthathaveresultedinthislistb==@{@-*--?LISTPACKAGE*--?============*--?*ALISTconsistsofzeroormoreITEMS.*--?*Theitemsarenumbered1toNwhereNisthenumberofitemsinthelist.*--?*Ifthelistisnon-empty,item1iscalledtheHEADofthelist.*--?*Ifthelistisnon-empty,itemNiscalledtheTAILofthelist.*--?...*@}G!Ov9erdoQcumenting: AnotherNevilthatcanarisewhenusingF*unnelWebNistoover-G!doGcumentethetargetprogram.InsomeofKnuth'searlier(e.g.1984)examplesofG!literate&programming,ceachvqariableisgivenitsowndescriptionandeachpieceofcoGdeG!hasadetailedexplanation.Thislevelofanalysis,>whilejusti edfortrickytractsofG!coGde,isprobablynotwarrantedformostofthecodethatconstitutesmostprograms.G!Such8(over-commentingcanevenhavethedetrimentala ectofobscuringthecoGde,G!makingithardtounderstandbGecauseitissoscattered(see\spaghettiorganization"G!earlier).LDItisuptotheusertodecidewhenastretchofjustafewlinesofcoGdeshouldG!bGeUUpulledtobitsandanalysedandwhenitisclearertoleaveUUitalone.G!InTthecasewherethereareafewrathertrickylinesofcoGde,TadetailedexplanationG!may!bGeappropriate.GThefollowingexamplecontainsasolutiontoaproblemoutlinedG!inNjsection16.3ofthebGookNj\TheScienceofProgramming"byDavidGries[Gries81]G!.*۟"ffğ J= "5-:4LܸNote: ThisXisnotacriticismof2167A,onlyofthewÎayXitissometimesused.K%514)<;Ġݻ_"E*@C@*This?sectioncontainsasolutiontoaproblemoutlinedinsection16.3of *the?book@/TheScienceofProgramming@/byDavidGries[Gries81].*@D?Givenasortedarray@{b[1..N]@}ofintegers,wewishtodeterminethe*@/length@/?ofthelongestrunofidenticallyvaluedelementsinthearray.*This?problemisdefinedbythefollowingpreconditionandpostcondition.*@$@==@{/*?Pre:sorted(b).*/@}*@$@==@{@-*/*?Post:sorted(b)andpisthelengthofthelongestruninb[1..N].*/@}*@D?Weapproachasolutiontotheproblembydecidingtotrytheapproachof*scanning?throughthearrayoneelementatatimemaintainingauseful*invariant?througheachiteration.Aloopvariable*array?index@{i@}iscreatedforthispurpose.Theboundfunctionis*@{N-i@}.?Hereistheinvariant.*@$@==@{@-*/*?Invariant:sorted(b)and1<=i<=Nand9*/*/*>p?islenoflongestruninb[1..i].*/@}*@D?Establishingtheinvariantaboveintheinitial,degeneratecaseiseasy.*@$@==@{i=1;p=1;@}*@D?Atthisstage,wehavethefollowingloopstructure.Notethatwhenboth*the?invariantand@{i!=N@}aretrue,thepostconditionholdsandtheloop*can?terminate.*@$@==@{@-*@*@*while?(i!=N)5-{:m@:m@5-}*@*@}*@D?Nowthereremainsonlytheloopbodywhosesoletaskistoincrease@{i@}*(and?sodecreasethevalueoftheboundfunction)whilemaintainingthe*invariant.?If@{p@}isthelengthofthelongestrun*seen?sofar(i.e.inb[1..i]),then,becausethearrayissorted,*the?extensionofourarrayrangeto*@{b[1..i+1]@}?canonlyresultinanincreasein@{p@}ifthenewelement*terminates?arunoflength@{p+1@}.Theincreasecanbeatmost1.Because*the?arrayissorted,weneed*only?comparetheendpointsofthispossibleruntoseeifitexists.This*is?performedasshownbelow.*@$@==@{i++;if(b[i]!=b[i-p])p++;@}uG!WhereUUthecoGdeismoreobvious,itisoftenbettertoletthecodespeakforitself.K%525)<;Ġݻ_"E*@C?ThefollowingfunctioncomparestwoC~stringsandreturnsTRUEiffthey *are?identical.*@$@==@{@-*bool?comp(p,q)*char?*p,*q;*{/while?(TRUE):m{?if?(*p!=*q )returnFALSE;?if?(*p=='\0')returnTRUE;?p++;?q++;:m}*}*@}.b*2.12XWholisticDebuggingM*SurprisingmthoughitmaybGe,F*unnelWebmhasakeyroletoplayinthedebuggingofprograms.*LongexpGerienceinprogramminghasledmetotheconceptofwholisticgdebugging.R Whenmost*programmerssKdetectabug,ztheir rstreactionseemstobGetojumpintothedebuggerwherethey*often`spGendmanyhourssteppingthroughendlessstretchesofcoGdeandgenerallywastingalotof*time.`*Inscontrast,:my rstreactionwhenI\detectabugistorealizethatthec}'odemustnotbeingood*enoughWDshap}'eifsuchabugcanarise.The)presenceofthebugistakenassymptomaticofthe*lackFofgeneralhealthofthecoGde.ϛIfthatbugoccurred,Qwhynotanother?ϛInresponsetothis*realization,#myreactionisnottoenterthedebugger,#butrathertoreturntotheoriginalcoGdeand*tend;itlikeagarden,Auaddingmorecomments,Aureworkingthegrottybits,Auaddingassertions,and*loGokingforfaults.UzInmanycases,thesearchforfaultsdoGesnotevencentreonthespGeci cbug*thatUUarose,butdoGestendtofocusontheareaofcodewherethebugislikelytobe.`*Theo1resultisoftenthattheoriginalbugisloGcatedmorequicklythanitwouldhavebGeenhadthe*debuggerRbGeeninvolved.vButRevenifitisn't,thereareotherbGene ts.vA;programmerwhoenters*theWFdebuggermaystaythereforhoursandstillnot ndthebug.wTheresultisfrustrationandno*pGositivexgainatall.(4Incontrast,bytendingtothecoGde,theprogrammerismakingforwardprogress*atualltimes(thecoGdeisconstantlyimproving)evenifthebugisnotimmediatelyfound.z'Atthe*endoftenhours,theprogrammercanatleastfeelthatthecoGdeis\tenhoursbetter",whereas*thezmdebuggerfreakwilllikelyfeeldefeated.AllthismakescoGdetendingbetterpsychologicallyas*wellUUasamoreecientapproachtodebugging.`*I~callthistechniquewholisticdebugging,lforitislikethedi erencebGetweenconventionaland*wholisticmedicine.N-GotoaconventionaldoGctorwithaheadacheandhemightsendo forhead*X-rays,pGerformallergytestsandperformmanyotherdebuggingactivities.Gotoawholistic*doGctorwiththesameproblemandhemightlooktoseeifyouare t, assessyourmentalhealth,*andaskyouifyourmarriageisworking.>Bothapproachesareappropriateatdi erenttimes.>In*programming,UUthewholisticapproachisnotusedenough..b*2.13XExamplesofFunnelWebApplicationsM*Despite_(orpGerhapsbecauseof)its exibilityandsimplicity*,΢FunnelWeb_canbGeappliedtoquite*anumbGerofdi erenttextproGcessinganddocumentingproblems.ZBThissectiondescribessomeof*theUUmoreinterestingrealproblemsthatF*unnelWebUUhassolved.K%536٣)<;Ġݻ_"E*2.13.1ZAnalyzingtheMonsterPostscriptHeaderFileI*During_)myPh.D.candidature,aI_'determinedatonepGointthatitwouldbGeverydesirabletoauto- *maticallyinsertdiagramsfromtheMacDr}'awprogramonmyMacintoshintoTU>'ExXinsertionsin*myZthesis.Thiswouldallowdiagramsto oataroundwiththetextandbGeprintedautomatically*rather"thanhavingtobGeprintedseparatelyandstuckinwithrealglue.ڏOnthefaceofit,VSthe*problemzseemedinherentlysolvqableastheMacintoshcouldgeneratePostScriptforeachdiagram*andUUthisPostScriptcouldpresumablybGeinsertedintothePostScriptgeneratedusingTU>'ExX.y*TheXeonlytroublewasthattheMacintoshPostScriptcoGdeforthediagramsreliedonanApple*PostScriptLheader le.nThismeantthattheheader lehadtobGeincludedatthestartoftheTU>'ExX*PostScriptiftheinsertedPostScriptforthediagramswastowork..Unfortunately*,Bmerelyincluding*theDheader leatthetopdidn'twork,anditturnedoutthataratherdetailedanalysisofsome*partsoftheAppleheader lewasrequiredinordertopGerformthenecessarysurgeryontheheader* le?Itomakeitwork.jnThisanalysiswasseverelyaggravqatedbythefactthatthePostScriptheader* leNwasvirtuallyunreadable.oUBasicallyitwasabGout50KMofinterwovende nitions,OwthatloGokedas*ifithadbGeenrunthroughawordprocessor.TTherewasnowaythatthecoGdecouldbeunderstood*clearlyPhwithoutsomekindofreformatting.p#TwootheraspGectsoftheproblemfurthercomplicated*theUUanalysis:*ۍ9CThede nitionsofinterest(i.e.theonescausingtheproblems)werescatteredthroughouttheC le.y9CManyPde nitionscouldnotbGemoved.b F*oroneormorereasons(e.g.tokeepade nitionCwithintheactivqationofaparticulardictionarybeginandend)itwouldhavebGeenunwiseCtoUUmovethede nitionsofinteresttothesamepGointinthe le.*In#factthe lewassomessyandcomplicatedthat,-asarule,ithadtobGehandledwithkidgloves.*ItUUwouldhavebGeenunwisetore-arrangethede nitionsortoinsertcomments.y*T*o{Vmysurprise,FunnelWebprovidedanunexpGectedsolutiontotheproblem.FirstI{ replaced*all==@{@-*Unreadable?Postscriptcode*@*Unreadable?Postscriptcode*@*Unreadable?Postscriptcode*@}*@A?Thisroutinelooksasifitdoesthis,butreallyisdoesthat,*blah,?blahblah.*@$@==@{@-*/print?{pushpoppoppushturnaroundandjumpupanddownandprintit}def*@}*@A?Thisroutinezapsthe...*@$@==@{@-*/zap?{pushpoppoppushturnaroundandjumpupanddownandprintit}def*@}K%547{)<;Ġݻ_"E*Used/ofF*unnelWebd/meantthatIcwasabletopluckoutthede nitionsofinterest(averysmall *partjzofthewhole le)andcollectthemasagroupattheendofthe lewheretheycouldbGe*studied.9Becauseeachde nitionwassafelycontainedinamacro,NitwaspGossibletowriteadetailed*commentarymofeachroutinewithoutfearofa ectingthe nalPostScriptcoGdeinanywayatall.*Oncezthisanalysiswascompleted,DitwaspGossibletoperformsurgeryontheo endingPostScript*de nitionsEXinanextremelycontrolledway*.AInparticular,XtheFunnelWebinput leservedasa*repGositoryforallthedi erentversionsofparticularroutinesthatweretriedinordertogetthe*de nitions+towork.HAnew(Zero)macrowascreatedforeachversionofeachde nition,>anda*commentaryUUofhowitpGerformedaddedaboveUUit.M*This5casedemonstratesthatF*unnelWeb5isanextremelypGowerful5toolfordissectinganddocument-*inglcryptictext les.z Throughtheuseofmacros,rparticularpartsofthe lecanbGeisolatedand*discusseddwithouta ectingthe nalproGduct leinanyway*.aIntheexampleabGove,gonlyasmall*partofthe lewasanalysed,~therestbGeingleftasablob,butinthegeneralcase,acryptictext le*could)bGeinsertedintoF*unnelWeb)andthenincrementallydissected(andpGossiblymodi ed)until*the,resultisafullydoGcumentedliterateprogram.`Thatthiscanbedonewithouta ectingthe*actualUUproGduct ledemonstratesthehighdegreeofdescriptivecontrolthatF*unnelWebUUprovides.",*2.13.2ZMakingAdaADTsmoreA㒍*Like8manymoGdernprogramminglanguages,=Adaprovidesmechanismsforhidinginformationand*structure.InKparticular,Adaprovidesapac9k\ragefacilitythatallowstheprogrammertodeclare*ob8jectsC4inapackqagede nitionandde netheminacorrespGondingpackqagebGody*.kThisC4workswell*for[functionsandproGcedures.However,]in[thecaseoftypes,]implementation[issues(inparticular,*the>needtoknowthesizeofexpGortedtypGes)haveledthedesignersofAdatoforcetheplacement*of%privqatetypGede nitionsinthede nitionpackqageratherthantheimplementationpackqage.aThis*means|thatsomeimplementationdetailsarepresentinthepackqagede nitionforalltosee._While*notactuallydangerous(theuserofthepackqagecannotmakeuseoftheinformationwithout*recourse Pto\Chapter13"oftheAdaLanguageReferenceManual[DOD83]),thisaspGectofAdais*certainlyUUunpleasant.M*Duringe-thedevelopmente-ofsomeAdaprograms,5F*unnelWebe-wasusedtosolvethisproblem.!Instead*ofcreatingaseparate leforthepackqagespGeci cationandpackqagebGody*,]asingleFunnelWeb* lejwascreatedcontainingtwosections,^onefortheeachpackqagepart.The\private"partof*the\&packqagespGeci cationwasthenmoved(usingaF*unnelWeb\¯ode nition)tothesection*describingfacilitatedtheuseofsharedinformation..F*orexample,undersomeconditions,each* le}tobGeprintedwouldbGerenamedandcopiedtotheremotesystemusingaparticularconstant* lenameO(e.g.\printfile.tmp").F*unnelWebOallowedthisconstant lenametobGeincludedina*singleXmacrode nitionwhichwasinvokedinthede nitionofeachofthescripts.Thisensured*thatUUthetwoUUscriptsusedthesamename.6[*@A?Thefollowingmacrocontainsthetemporaryfilenameusedtoallowthe*two?shellscriptstotransfereachfiletobeprinted.*@$@@M==@{printme.txt@}*@A?HerearethescriptsforthelocalVMSnodeandtheremoteUNIXnode.*@O@==@{@- *DCL?commands*copy?@unixnode::*DCL?commands*@}*@O@==@{@-*unix?commands*print?@*unix?commands*@}6[*In"thecaseoftheprintingsystem,,theentiresystemwasdescribGedandde nedinasingleF*unnel-*W*ebp.fw le.þInlargersystemscontainingmanyF*unnelWebp.fw lesformanydi erentmoGdules*inmanydi erentlanguages,$thesametrickcanbGepulledbyplacingF*unnelWebmacrode nitions*forvsharedvqaluesintoF*unnelWebvinclude les.J(F*orexample,followingexampleshowshowthiscanbGedone.Thecodeiscluttered,gbutthisclutter*wouldUUnotbGeaproblemifthelumpsoftextweremoGderatelylarge.{*@O@==@{@@+@}*@O@==@{@@+@}*@$@+=@{@@}*@$@+=@{@@}*@$@@M==@{First?lumpoftextsharedbybothdocuments.@+@}*@$@+=@{Text?forfirstdocument@+@}*@$@+=@{Text?forseconddocument@+@}*@$@+=@{@@}*@$@+=@{@@}*@$@@M==@{Second?lumpoftextsharedbybothdocuments.@+@}{*Analternativeapproach,whichmightworkbGetterinsituationswheretherearemanysmalldif-*ferencesbGetweenthetwodoGcumentsratherthanafewlargeones,istode neamacrowithtwo*arguments,one"foreachproGduct ledocument.AW*ritethedocumentfromtoptobottom,butplace*allUUstretchesthatdi erbGetweenthetwodoGcumentsinamacrocall.*@!?Setthedefinitionof@#Dto*@!@1?tocreatetheshareholdersreport.*@!@2?tocreatethecustomersreport.*@$@#D@(@2@)@M==@{@1@}*@O@==@{@-*1992?ANNUALREPORTTO@#D@(Shareholders@,Customers@)*======================@#D@(============@,=========@)*This?hasbeenaverygoodyearforTheVeryBigCorporationofAmerica.*With?yourhelp,wehavebeenabletosuccessfully*@#D@(@"screw?thecustomersforeverycenttheyhave@"@,D@"knock?theshareholdersintosubmissiontobringyoulowerprices@"@).*With?grossearningsapproachingsixtrilliondollars,wehavebeenableto*@#D@(@"increase?dividends@"@,D@"lower?prices@"@).*We?expecttohaveanevenbetteryearnextyear.*@}*OneapplicationwheretextsharingcanbGeparticularlyusefulisinthepreparationofcomputer*doGcumentationcontainingexamples.'ExX.`*@O@==@{@#B@}*@$@#B+=@{@-*The?firststeptolearningtheobjectorientedAdaCgol++languageistoexamine*a?helloworldprogram.*\start{verbatim}*@*\finish{verbatim}*@}*@$@==@{read?iopack@+Enter!World~!!Hello~!exprfluX[1]@}*@O@==@{@@}*@$@#B+=@{@-*To?understandtheprogram,thinkoftheexecutionstateasaplateofcheese...*@}`*Mostofthe lewillconsistofpartde nitionsoftheadditivemacro@#B.Thede nitionis\broken"*toUUallowamacrode nition,whereveranexampleappGears.&p*TheNqexampleabGoveNqisalittlemessybecauseF*unnelWebNqdoesnotallowmacrosconnectedtoproduct* les#DtobGecalled,Vanditdoesnothave#Dtextexpressionsthatwritetoanproduct leaswellas*evqaluatingtotext.PNevertheless,Sitpresentsafairlycleansolutiontotheproblemofkeepingthe*exampleUUprogramsinacomputingtextuptodate."we*2.13.7ZGenericsP*Itiswellknownthatgenericsinprogramminglanguagesarecloselyalignedwithtextualsubstitu-*tion.)In{5fact,agoGod{5waytounderstandthegenericfacilityofanewprogramminglanguageistoask*oneselfwthequestion\InwhatwaywdoGesthisgenericfacilitydi erfromsimpletextsubstitution?"*The:di erences,s0ifany*,typically:havetodowiththedi erenceinscopingbGetweentextualand*intelligentsubstitutionandwhetherthegenericcoGdeissharedorcopiedbytheimplementation.*InUUmostcasesthedi erencesarequiteminor.&p*Because0genericfacilitiesaresocloselyalignedwithtextsubstitution,7itispGossibletouseF*unnel-*W*eb'suparameterizedmacrostoprovidegenericsinprogramminglanguagesthatdonotsuppGort*generics.@(@2@)==@{@-K%59<=,)<;Ġݻ_"E*@!?@1isthebasetype,@2isthesettype. *[inherit?('@1'),environment('@2')]*module?@2;*type @2?=^@2Record;J-@2Record?=recordYMember:?@1;YNext:?@2;Yend;*procedure?Null@2(varResult:@2);*begin?new(Result);*Result^.Member?:=(-MaxInt)::@1;*Result^.Next?:=nilend;*function?IsNull@2(S:@2):boolean;*begin?IsNull@2:=S^.Member::integer=-MaxIntend;*procedure?ForEach@1(S:@2;procedureDoIt(i:@1));*varThisS,?NextS:@2;*begin?ThisS:=S;*while?ThisS^.Member::integer<>-MaxIntdo:mbegin?NextS:=ThisS^.Next;:mDoIt?(ThisS^.Member);:mThisS?:=NextSend;*end;*function?First@1(S:@2):@1;*begin?First@1:=S^.Memberend;*function?Is@1InSet(i:@1;S:@2):boolean;:mprocedure?TestEquals(j:@1);:mbegin?ifEqual@1(i,j)thenIs@1InSet:=true;end;*begin?Is@1InSet:=false;ForEach@1(S,TestEquals);end;*function?Includes@2(S1,S2:@2):boolean;*var?Result:boolean;:mprocedure?TestIfInS1(i:@1);:mbegin?ifResultthenifnotIs@1InSet(i,S1)thenResult:=false;end;*begin?Result:=true;*ForEach@1?(S2,TestIfInS1);*Includes@2?:=Resultend;*function?Disjoint@2s(S1,S2:@2):boolean;*var?Result:boolean;:mprocedure?TestIfInS1(i:@1);:mbegin?ifResultthenifIs@1InSet(i,S1)thenResult:=false;end;*begin?Result:=true;*ForEach@1?(S2,TestIfInS1);*Disjoint@2s?:=Resultend;*function?Equal@2(S1,S2:@2):boolean;*begin*Equal@2?:=Includes@2(S1,S2)andIncludes@2(S2,S1);*end;K%60=L*)<;Ġݻ_"E*procedure?Insert@1(i:@1;varS:@2); *varThis,?Pred,Succ:@2;*begin*if?notIs@1InSet(i,S)then:mbegin:mPred?:=nil;Succ:=S;:mwhile?Succ^.Member::integer>i::integerdobeginJ-Pred?:=Succ;Succ:=Succ^.Nextend;:mif?Succ^.Member::integernilthenPred^.Next:=ThiselseS:=This;J-end;:mend;*end;*procedure?Insert@1s(S1:@2;varS2:@2);*varThis,?Pred,Succ:@2;:mprocedure?Add@1(i:@1);:mbegin?Insert@1(i,S2)end;*begin*ForEach@1?(S1,Add@1);*end;*procedure?Remove@1(i:@1;varS:@2);*varPred,?This:@2;*begin*Pred?:=nil;This:=S;*while?notEqual@1(This^.Member,i)dobegin:mPred?:=This;This:=This^.Nextend;*if?Pred<>nilthenPred^.Next:=This^.NextelseS:=This^.Next;*Dispose?(This);*end;*procedure?Dispose@2(varS:@2);*varOld:?@2;*begin*while?S<>nildobeginOld:=S;S:=S^.Next;Dispose(Old)end;*end;*end.*@}*@O@==@{@-5-@@(@"NaryTree@"@,@"NaryTreeSet@"@)@}*@O@==@{@-5-@@(@"NaryTreeSet@"@,@"NaryTreeSetSet@"@)@} *Agreatadvqantageoftheapproachre ectedintheabGoveexampleisthatitallowstheprogrammer*toconstructagenericob8jectinalanguagethatdoGesnotsupplygenerics,with)c}'ompletetypesafety.*ThiscontraststotheapproachthatmightbGeusedinalanguagesuchasCwheretheprogrammer*mightchoGosetoconstructa\generic"packqagebyparameterizingapackqagewithpGointerstovoid.*The'resultingpackqageispGowerfulbutextremelyuntypGesafe.bSuchagenericlistpackqageisusedin*the 6coGdeofF*unnelWeb 6itselfandcausednoendofproblems,pasthecompilerhadnoway 6oftelling*ifdpGointerstothecorrectlytypGedob8jectwerebGeinghandedtothecorrectlist-ob8ject/function*combination.ѣ*Thema8jordisadvqantageofthetextgenericapproachisthatitcausesthecoGdeofthegenericK%61>S)<;Ġݻ_"E*ob8jectZ tobGeduplicatedonceforeachinstantiation.)DepGendingonthenumbGerandsizeofthe *instantiations,UUthismayormaynotbGeacceptable.*WheretheduplicationofcoGdeisunacceptable,aahybridapproachmaybGetaken. \Asinthe*C6example,theprogrammercouldwriteasinglegenericpackqageusingpGointerstovoidorsome*otheruntypGesafemechanism.`}ThentheprogrammercreatesaF*unnelWebgenericpackqagewhose*functionsrdonothingmorethancallthefunctionsoftheuntypGesaferpackqage,zRandwhosetypGesdo*nothing{morethancontainthetypGesoftheuntypGesafepackqage.Thissolutioninvolvestheuseof*untypGesafeprogramming,+butthisisaone-o andifdonecarefullyandcorrectly*,theresultcan*bGeUUatypesafegenericpackqageinvolvingminimalcoGdeduplication.'č*2.14XSummary*ThischapterhasdescribGedsomeofthe neraspectsoftheuseofF*unnelWeb.VThroughout,the*pGowerf3anddangerofF*unnelWebf3asageneraltext-rearrangingpreprocessorhasbeenemphasised.*F*unnelWebcanbGeusedbothtomakeprogramsmorereadableormoreobscure.Itisuptothe*programmerUUtoensurethatF*unnelWebUUisusedpropGerly*.K%62?])<;Ġݻ*JChapterF36*HFunnelWeb De nition>*3.1PfIn=trouduction|ԍ*ThispurpGoseofthischapteristoprovideacompleteandconsistentde nitionoftheF*unnelWeb *inputlanguageandthebGehaviouroftheF*unnelWebprogram.Usually,achaptersuchasthisis*calledEa\referencemanual",butthischapterisintendedtogofurtherbyactuallyde ningthelan-*guageiandprogram.EyThischaptertakesprecedenceoverallotherchaptersandallimplementations*ofUUF*unnelWeb.qIfanimplementationcontradictsthischapter,thentheimplementationiswrong.*This%listhechapterthatyoushouldturnifyou ndyourselfaskingaspGeci cquestionabouta*spGeci caspectofF*unnelWeb.XInmanycasesitwillbGeconvenienttoaccessthischapterthrough*theUUindex.% *3.2PfNotation|ԍ*AparticularvqariantofEBNF(ExtendedBachusNaurF*orm)willbGeusedtodescribetheF*un-*nelW*ebgsyntax.Inthisvqariant,Wliteralstringsaredelimitedbydoublequotes(e.g."string"),*optionalconstructsbysquarebrackets(e.g.[optional]),?andconstructsrepGeatedzeroormore*times7bybraces(e.g.fzeroormoreg).lConstructstobGerepeateda xednumber7oftimesare*enclosedinbracesfollowedbyadecimalnumbGerindicatingthenumbGeroftimestoberepeated*(e.g.5fsixtimesg6).7gConstructstobGerepeatedoneormoretimesareenclosedinbracesandfol-*lowedPbya+(e.g.foneormoreg+).p ThetraditionalBNFP\::="isreplacedbythevisuallysimpler*\=".qTheUUtraditionalBNFanglebracketsUUareabandoned.*Although}F*unnelWeballowsthespGecialcharactertobGechangedusingtheconstruct\=",*useh of\"torefertoF*unnelWeb'sh specialcharacteriscumbGersomeandabstract.T*o*simplifythepresentation,thedefaultspGecialcharacter\@"isusedthroughoutthischapterto*representUUthespGecialcharacter.% *3.3PfTerminology|ԍ*AfspGeci cfterminologyhasarisenfordealingwithF*unnelWeb.JSomefparticularlyusefulexamples*are:G!Journalf le:vAnoutput lecontainingacopyoftheoutputsenttotheuser'sconsoleG!during|aninvoGcation|ofF*unnelWeb.In|othersystems,this leissometimescalledaG!\logUU le".G!ProQduct le:6An7output le,pgeneratedbytheT*anglecompGonentofF*unnelWeb,G!thatUUcontainstheexpansionofthemacrosintheinput le.^1*۟ffğ J= "5-:1LܸOtherXnamesconsideredforthiswÎere: generated le,expanded le,result le,program le,andtangle le.K%63@cԠ)<;Ġݻ_"E*AEcompleteElistofallthespGecialF*unnelWebEterminologyappearsintheglossary*.lBesuretorefer *toUUitifanyofthetermsusedareunclear.&6a*3.4PfAnArc=hitecturalOverviewM*An$ understandingoftheinternalsofF*unnelWeb$ assistswithunderstandingitsopGeration(Fig-*ureT3).f*Duringasinglerun,CF*unnelWebreadsandproGcessesasingleinput lecalledtheinput leor*theBF unnelWeb le.kThe leisproGcessedbypassingitthroughaseriesofstagescalledphases.*TheVresultisthatsomeoutput lesaregenerated.sAUjournal leisgeneratedcontaininga*copyVofthemessagesthatappGearontheconsoleduringtheF*unnelWebVrun.vAVlisting leis*createdcontainingasummaryoftherun, Dincludinganyerrormessages.[AdoQcumen9tation leis*generatedkwcontainingtypGesettercommandsthatwhenfedintoatypGesetterprogramwillresultin*printed-doGcumentation.dFinally*,5oneormoreproQduct lesaregeneratedcontainingtheresultof*unscramblingUUthemacrode nitionsoftheinput le.f*These] lesneednotallbGegeneratedonanyparticularF*unnelWeb]run.uWhethereachoutput le*appGearsUUiscontrolledbycommandlineoptions.hJ29Y.fw?InputFile(FunnelWebfile)V~+---------+^\~|?Scanner|^|~+---------+^|Vx|~+--------+c|~|?Parser|c|~+--------+c|Vx|~+----------+Y?>-------+------------+~|?Analyser|Y?|$|>|~+----------+Y?|$|>|Vx|$|>|Y+-----------+------------+4|$V>VYV}V4|$|>|D+--------+N+-------+|$|>|D|?Tangle|N|Weave||$|>|D+--------+N+-------+/$|>|Y|}|^|>|YV}V^V>V:mProduct?Files/?DocumentationFileListingFile JournalFile"RܸFJunnelWebtpro'ExX,*butwithamoregeneric,N}F*unnelWeb-spGeci csyntax.Thiswasunfeasibleinthetimeavqailable,*andUUundesirableaswell.*The4 compromisestruckintheF*unnelWeb4 designistoprovideasetofprimitivetypGesetter-*indepGendent=typesetting=featuresthatareimplementedbyF*unnelWeb.iThese=arethet9ypQesetter*directiv9es.VIf/theuserispreparedtorestricttothesedirectives,&thentheuser'sF*unnelWeb*doGcumentJwillbebothtarget-languageandtypesetterindependent.However,ifJtheuserwishes*tobusethemoresophisticatedfeaturesofthetargettypGesettingsystem,%theusercanspecifythe*typGesetterIauserinvokes>F*unnelWebattheopGeratingsystemcommandlevel,Crtheusermustprovidea*command#lineinstructingF*unnelWeb#whattodo.0TypicallyanopGeratingsystemcommandline*consistsofaverbindicatingthataparticularprogramshouldbGerun,%followedbyalistofoptions.*F*orUUexample: 5*$?renamefile1file2*Inthiscase,ptheverbisrenameandthecommandlineoptionsarefile1?file2.'ExXformat.'ThestringargumentcontributestothenameoftheG!doGcumentation letobecreated.*?Bydefaultthisoptionisturnedo ,1asexperienceG!hasfshownthatmostF*unnelWebfrunsaremadeduringprogramdevelopment;o.doGcu-G!mentationUUrunsoGccurfarmorerarely*.qExamples:-T,UU+Tsloth.tex.Default:?-T.G!W:(/WidthofProQductFiles:Ifathisoptionisturnedon,dalimitisplacedontheG!lengthkoflinesinproGduct lesgeneratedduringtherun.DLinesthatbreachthelimitG!are$ aggedwitherrormessages.KThisoptionhasasinglenumericalattributethatG!can[bGespeci edasadecimalstringinthestringcomponentoftheW[argument.TheG!numbGer Fisthespeci edmaximumwidth.ThisoptionisoneoftwolimitsthatareG!placed`onthewidthofproGduct les.~TheotherlimitisanattributeoftheinputG! lethatdefaultsto80characters,vbutcanbGeraisedorloweredusinganoutputlineG!length8pragma.hThewidththatisenforcedisthelower8ofthisvqalueandthevalueofG!theUUWoption(ifturnedon).qExamples:-W,UU+W100.Default:?-W80.G!X:OExecute:FIfthisoptionisturnedon,ږF*unnelWebexecutestheF*unnelWebshellG!scriptUU lespGeci edbythestringattribute.qExamples:+Xmaster,UU-X.Default:?-X.*۟#cffğ J= "5-:3LܸThis7[optionisconÎtrolledbytheKT7commandlineargumentb[fdͤ ff͟fdScript 1 ff0Input  ffXcInclude͟ ffUSJournal͟ ffG ListO ffGDoGcument͟ ff#ProGduct͟ ffff>[͟ ff* ffR0U ffXc@i> ff ff ff[ ff#@o ff ͤ ff͟fd+xLɡ ff0+fe ffXc+i> ffUS+j> ffG +lLɟ ffG+t()K ff#+o ffͤ ff͟fd\.fws" ff0\.fw"pf ffXc\.fwi" ffUS\.jrn" ffG \.lis"͟ ffG\.tex"O ff>b( ff͟ ff* ffR0U ffXc+f> ffUS+f> ffG +fLɟ ffG+f()K ff>b( ffͤ ff͟fdDefDirSܡ ff0Defdir͟ ffXcDefdir [ ffUSDefdir [ ffG Defdir i1 ffGDefdirE ff#Defdir  ffff>[9*Thectableisarrangedwithitemsofhighestpriorityatthetop.V!The\+"cellsrefertothe* le+YspGeci cationsuppliedinthegivencommandlineargument.c\+F"+Nisthenameoftheinput le.*\Defdir">referstothedefaultdirectoryspGeci cationprovidedbytheopGeratingsystem.-Empty*cellsUUdonotcontribute.*TheHfollowingexampleshowshowthetableisused.mSuppGosethattheuserinvokedF*unnelWebHas*follows:L*fw?/usr/ross/work/sloth.fw+twalrus*T*odworkoutwhatthedoGcumentation leshouldbGecalled,F*unnelWebdstartswiththeempty *stringandthenworksdowntheDoGcumentcolumnofthetable.$Thetopentryisemptysowe*ignore?itandproGceedtothesecondentrywhichconsistsof\+T".TheuserspGeci edthestring*\walrus">asthevqalueofthisoption,yitdoesn'traiseanyerror.=IfitdoesG! nd one,itexecutesitasaF*unnelWeb shellscript.XInitializationscriptsareusefulforG!settingנupF*unnelWebנoptions(e.g.usingthe\set"commandwithouthavingtotypGeG!themUUeachtime).G!Execute$argumen9tscript:$If"ashellscripthasbGeenspeci edusingthe\+X"option,G!F*unnelWebUUexecutesit.G!ProQcessinput le:=If;QtheuserhasspGeci edaninput leusingthe\+F";option,G!thenUUthisisproGcessednext(byF*unnelWebUUproper).G!Displa9yhelpmessage:ǪIfGtheuserrequested,+usingthe\+H"option,thatahelpG!messageUUbGedisplayed,UUthemessageisdisplayedUUatthistime.G!In9teractivemoQde:^ZIf.ztheuserspGeci edthe\+K".poption,6@F*unnelWeb.zentersinterac-G!tiveUU(keybGoard)mode.*F*unnelWebproGcessestheseactionsintheaboveorderregardlessoftheorderinwhichtheyappear*onUUthecommandline.*ItmaybGehardtoseehowsomeoftheseactionsmightbGecombined.Nevertheless,0F*unnelWeb*allowsb#this.2F*orexample,WausermightwishtoproGcessabatchof lesasspGeci edinascript*(\+Xscript.fws"),bGe*remindedoftheinteractive*commandsavqailable(\+Hcommand"),andthen*enterninteractivemoGdesoastobeabletoreprocess lesforwhichF*unnelWebrepGortederrors(after*correctingUUtheerrorsinadi erentworkstationwindow).$ *3.10XScanner[*Thegscannerreadsintheinput leandproGducesalistoftokenswhichithandsontotheparser.*In-addition,someinputconstructsmaycausethescannertomoGdifysomeofF*unnelWeb's-options.}*3.10.1ZBasicInputFilePro`cessingލ*Injordertoreadinaninput leorinclude le,pZthescannercallsasubmoGdulecalledthemappQer*thatijreadsa leinandcreatesacontiguouscopyofitinmemory*.AThescannerthenpGerformsthree*checksonthe le,the rst( letermination)ofwhichispGerformedbeforescanningcommences,*andUUtheothertwoUUofwhichtakeplaceduringscanningbGeforeeachlineisscanned.G!FilerT ermination: TheG rstcheckGthescannermakesiswhetherthe leisterminatedG!propGerly*.Ac lec isconsideredtobeproperlyterminatedifiteithercontainsnolines,G!orifthelastlineinthe leisterminatedbyanend-of-linemarker.IfthescannerG!detectsQthataninput leisnotpropGerlyterminated,(itaddsanend-of-linemarkerG!itselfUU(tothecopyinmemoryonly).G!Unprin9tableDCharacters:3yThe.secondcheck.thescannermakesisforunprintableG!characters(ASCIGIs0{31and127{255(exceptforEOL(10)))whichit agsaserrorsG!andUUreplacesbyquestionmarks.G!LineLengths:TheIthirdcheckIthescannermakesisinputlinelength. fWhenG!F*unnelWebJUstartsup,adefaultmaximuminputlinelengthof80isset.PThiscanG!bGechangeddynamicallyduringscanningusinga@p?maximumEff&fǫinputEff&flineEff&flengthG!pragma.{IfXthenumbGerXofcharactersonaline(notincludingtheendoflinemarker)G!exceedsUUthislimit,F*unnelWebUUgeneratesanerror.K%71Hꆠ)<;Ġݻ_"E*3.10.2ZSp`ecialSequencesٍ*Theg"scannerscanstheinput lefromtoptobGottom,lefttoright,treatingtheinputasordinarytext *(to;bGehandeddirectlytotheparserasatexttoken)unlessitencountersthespQecial+c9haracter^4*whichڝintroGducesaspQecialnsequence.Thus,thescannerpartitionstheinput leintoordinary*textUUandspGecialsequences.bƍ*input_file?={ordinary_text|special_sequence}*UpGon(startup,thespecialcharacteris@,butitcanbechangedusingthe= *spGecialzsequence.6Ratherthanusingwheneverthespecialcharacterappears,thisdoc-*umentusesthedefaultspGecialcharacter\@"torepresentthecurrentspGecialcharacter.BMore*impGortantly*,FunnelWeb'serrormessagesallusethedefaultspecialcharacterintheirerrormes-*sagesUUevenifthespGecialcharacterhasbGeenchanged.'*AnZoGccurrenceofthespecialcharacterintheinput leintroGducesaspecialsequence.*Thekind*ofcspGecialsequenceisdeterminedbythecharacterfollowingthespGecialcharacter.Onlyprintable*charactersUUcanfollowthespGecialcharacter.*ThefollowinglistgivesallthepGossiblecharactersthatcanfollowthespGecialcharacter,yandthe*legality#ofeachsequence.a6The rstcolumngivestheASCIGI#number#ofeachASCIGI#character.a6The*secondcolumngivesthespGecialsequenceforthatcharacter.6RThenextcolumncontainsoneofthree*characters:\-":meansthatthesequenceisillegal.fv\S"indicatesthatthesequenceisasimple*sequence`(withnoattributesorsidee ects)thatappGearsexactlyasshownandisconverted*directlyeintoatokenandfedtotheparser. Finally*,\C"dindicatesthatthespGecialsequenceis*complex,UUpGossiblyhavingafollowingsyntaxorproGducingfunnysidee ects.bƍ*ASC SEQCOMMENT*-----------------*000$\*016)|?Unprintablecharactersandhenceillegalspecials.*031$/*032 @-?Illegal(space).*033 @!C?Comment.*034 @"S?Parameterdelimeter.*035 @#C?Shortnamesequence.*036 @$S?Startofmacrodefinition.*037 @%-?Illegal.*038 @&-?Illegal.*039 @'-?Illegal.*040 @(S?Openparameterlist.*041 @)S?Closeparameterlist.*042 @*-?Illegal.*043 @+C?Insertnewline.*044 @,S?Parameterseparator.*045 @-C?Suppressendoflinemarker.*046 @.-?Illegal.*047 @/S?Openorcloseemphasisedtext.*048 @0-?Illegal.*049 @1S?Formalparameter1.*050 @2S?Formalparameter2.*051 @3S?Formalparameter3.*052 @4S?Formalparameter4.*۟Offğ J= "5-:4LܸThissortofcÎharacterisoftenreferredtoasthe\escapS?Closemacroname.*063 @?-?Illegal.Reservedforfutureuse.*064 @@C?Insertspecialcharacterintotext.*065 @AS?Newsection(level1).*066 @BS?Newsection(level2).*067 @CS?Newsection(level3).*068 @DS?Newsection(level4).*069 @ES?Newsection(level5).*070 @F-?Illegal.*071 @G-?Illegal.*072 @H-?Illegal.*073 @IC?Includefile.*074 @J-?Illegal.*075 @K-?Illegal.*076 @L-?Illegal.*077 @MS?Tagmacroasbeingallowedtobecalledmanytimes.*078 @N-?Illegal.*079 @OS?Newmacroattachedtoproductfile.Hastobeatstartofline.*080 @PC?Pragma.*081 @Q-?Illegal.*082 @R-?Illegal.*083 @S-?Illegal.*084 @TC?Typesetterdirective.*085 @U-?Illegal.*086 @V-?Illegal.*087 @W-?Illegal.*088 @X-?Illegal.*089 @Y-?Illegal.*090 @ZS?Tagsmacroasbeingallowedtobecalledzerotimes.*091 @[-?Illegal.Reservedforfutureuse.*092 @\-?Illegal.*093 @]-?Illegal.Reservedforfutureuse.*094 @^C?Insertcontrolcharacterintotext*095 @_-?Illegal.*096 @`-?Illegal.*097 @a\*109 @m|?Identicalto@A..@Z.*122 @z/*123 @{S?Openmacrobody/Openliteraldirective.*124 @|-?Illegal.*125 @}S?Closemacrobody/Closeliteraldirective.*126 @~-?Illegal.*127?to255arenotstandardprintableASCIIcharactersandareillegal.ݻ*Thev+mostimpGortantthingtoremembGeraboutthescanneristhatnothingƘhapp}'ensunlessthespecial*char}'acter,isseen.cThere^arenofunnysequencesthatwillcausestrangethingstohappGen.The*bGestwaytoviewaF*unnelWebdoGcumentatthescannerlevelisasabGodyoftextpunctuatedby*spGecialUUsequencesthatservetostructurethetextatahigherlevel.K%73J ͠)<;Ġݻ_"E*The)remainingdescriptionofthescannerconsistsofadetaileddescriptionofthee ectofeach *complexUUspGecialsequence.$z*3.10.3ZSettingtheSp`ecialCharacter *ThespGecialcharactercanbesetusingthesequence=.-F*orexample,*@=#RwouldchangethespGecialcharactertoahash(#)character.pThespGecialcharactermaybGeset*toanyprintableASCIGIcharacterexcepttheblankcharacter(i.e.anycharacterintheASCIGIrange*[33;126]).RIn|normaluse, itshouldnotbGenecessarytochangethespecialcharacterofF*unnelWeb,*anditisprobablybGesttoavoidchangingthespGecialcharactersoasnottoconfuseF*unnelWeb*readers>conditionedtothe@character.However,8the>featureisveryusefulwherethetextbGeing*preparedUUcontainsmany@characters(e.g.alistofinternetelectronicmailaddresses).$z*3.10.4ZInsertingtheSp`ecialCharacterintotheText *ThespGecialsequence@insertsthespecialcharacterintothetextasifitwerenotspGecial*atball.The@ofthissequencehasnothingtodowiththecurrentspGecialcharacter.Ifthecurrent*spGecialȦcharacterisPȂthenthesequenceP@willinsertaPintothetext.BExample:+o@@#@=#@#@#=@@@*translatesUUto@#@#@.$z*3.10.5ZInsertingArbitraryCharactersintotheText*While_F*unnelWebdoGesnottolerateunprintablecharactersintheinput le(exceptfortheendof*line!character),"itdoGesallowtheusertospGecifythatunprintablecharactersappGearintheproduct* le.l\TheE@^sequenceinsertsasinglecharacteroftheuser'schoGosingintothetext.l\Thecharacter*can3bGespeci edbygivingitsASCII~number3inoneoffourbases:Ńbinary*,ɪoctal,decimal,and*hexadecimal.qHereUUisthesyntax:*control_sequence?="@^"char_spec*char_spec)=?binary|octal|decimal|hexadecimal*binary9=?("b"|"B")D?"("{binary_digit}8 ")"*octal>=?("o"|"O"|"q"|"Q")"("{octal_digit}3")"*decimal4=?("d"|"D")D?"("{decimal_digit}3")"*hexadecimal=?("h"|"H"|"x"|"X")"("{hex_digit}2?")"*binary_digit?=?"0"|"1"*octal_digit=?binary_digit|"2"|"3"|"4"|"5"|"6"|"7"*decimal_digit=?octal_digit|"8"|"9"*hex_digit)=?decimal_digit|"A"|"B"|"C"|"D"|"E"|"F"x|?"a"|"b"|"c"|"d"|"e"|"f"*Example:*@!?UnixMakerequiresthatproductionscommencewithtabcharacters. *@^D(009)prog.o?<-prog.c*Notethatthedecimal\9"isexpressedwithleadingzerosas\009".UF*unnelWebrequiresa xed*numbGerCofdigitsforeachbase.kEightdigitsforbasetwo,Gathreedigitsforbaseten,threedigitsfor*baseUUeightandtwodigitsforbasesixteen.Ӎ*F*unnelWebtreatsthecharacterresultingfroma@^sequenceasordinarytextineverysense.1If*your?input lecontainsmanyinstancesofaparticularcontrolcharacter,D7youcanpackqageitupin*aUUmacrolikeanyothertext.qInparticular,quicknamescanbGeusedtogreate ect:K%74Kʠ)<;Ġݻ_"E*@!?Unix"Make"requiresthatproductionscommencewithtabcharacters. *@!?Sowedefineamacrowithaquicknameasatabcharacter.*$@#T@{@^D(009)@}*@!?Anduseitinourproductions.*@#Tprog.o?<-prog.c*@#Ta.out?<-prog.o*W*arning:rIfpyouinsertaUnixnewlinecharacter(decimal10)intothetext,wF*unnelWebpwilltreat*thisasanendoflinesequenceregardlessofwhatthecharactersequenceforendoflineisonthe*machine7upGonwhichitisrunning.ZlUnixEOL isF*unnelWeb's7internalrepresentationforendof*line.pSThus,QinPthecurrentversionofF*unnelWeb,QinsertingPcharacter10intothetextisimpGossible*unlessthisalsohappGenstobethecharacterusedbytheopGeratingsystemtomarktheendofline.!08*3.10.6ZCommentsU*WhenF*unnelWebencountersthe@!aTsequenceduringitsleft-to-rightscanoftheline,#itthrows*away4therestoftheline(includingtheEOL)4withoutanalysingitfurther.fCommentscanappGear*inUUanylineexcept\@i",\@t",and\@p"lines.p*F*unnelWebGcommentscanbGeusedtoinsertcommentsintoyourinput lethatwillneitherappGear*in@theproGduct lesnorinthedocumentation le,wbutwillbesolelyforthebene tofthosereading*andUUeditingtheinput ledirectly*.qExample:*@!?Ihaveusedaquickmacroforthisdefinitionasitwillbeusedoften.*@$@#C@{--@}*Becausecommentsarede nedtoincludetheend-of-linemarker,_caremustbGetakenwhenthey*areUUbGeingaddedorremovedUUwithinthetextofmacrobodies.qF*orexamplethetextfragment*for?(i=0;ivcombinetheinsert*endUUoflineconstruct@+withthecommentconstruct@!qasin*for?(i=0;i).0A~quicknamesequence*consistsUUof@#xwherex,thenameofthemacro,canbGeanyprintablecharacterexceptspace.F*quick_name?="@#"non_space_printable*The'resultisidenticaltotheequivqalentordinarynamesyntax,0butisshorter.bF*orexample,@#X'is *equivqalent;to@.yThisshorterwayofwritingone-charactermacronamesismoreconvenient*whereamacromustbGeusedveryoften.^NF*orexample,&themacrocallsinthefollowingfragmentof*anUUAdaprogramarealittleclumsy*.F*@!?Define@as""toturnondebugcodeand"--"toturnitoff.*@$@@{--@}*@assert(b>3);*@if?x>7thenwrite("error")endif*TheUUcallscanbGeshortenedusingthealternativesyntax.*@!?Define@#|as""toturnondebugcodeand"--"toturnitoff.*@$@#|@{--@}*@#|assert(b>3);*@#|if?x>7thenwrite("error")endif$*3.10.8ZInsertingEndofLineMarkers³*Anendoflinemarker/charactercanbGeinsertedintothetextusingthe@+sequence./@{@-*I?amthewalrus!@}*isUUequivqalentto*@$@@{I?amthewalrus!@}*The(Xcommentconstruct(@!)bcanalsobGeusedtosuppressendoflines.However,1Wthe(X@-construct*shouldGbGepreferredforthispurposeasitmakesexplicittheprogrammer'sintenttosuppressthe*endUUofline. Ӎ*3.10.10amIncludeFiles *F*unnelWebprovidesaninclude lefacilitywithamaximumdepthof10.Z5WhenF*unnelWebseesa*line^oftheform@i?,aFitreplacestheentireline(includingtheEOL)^withthecontents*ofthespGeci edinclude le.@F*unnelWeb'sinclude lefacilityisintendedtoopGerateatthelinelevel.*If>thelastlineoftheinclude leisnotterminatedbyanEOL,F*unnelWeb>issuesawarningand*intertsUUone(inthecopyinmemory).*They@iconstructisillegalifitappGearsanywhereexceptatthestartofaline.[Theconstructmust*bGefollowedbyasingleblank.R@The lenameisde nedtobGeeverythingbGetweentheblankandthe*endUUoftheline(nocomments(@!)qplease!).Example:IfUUtheinput leis*"Uh?Oh,It'stheFuzz.We'rebusted!"saidBabyBear.*@i?mr_plod.txt*"Quick!?Flushthestashdownthedunnyandlet'ssplit."saidFatherBear.*andUUthereisa lecalledmrEff&fǫplod.txtcontaining*"'Ello,?'Ello,'Ello!What'sallthis'erethen?"MrPlodexclaimed.*thenUUthescannertranslatestheinput leinto*"Uh?Oh,It'stheFuzz.We'rebusted!"saidBabyBear.*"'Ello,?'Ello,'Ello!What'sallthis'erethen?"MrPlodexclaimed.*"Quick!?Flushthestashdownthedunnyandlet'ssplit."saidFatherBear.*AsI,apGointofterminology*,KFunnelWebI,callstheoriginalinput letheinputX leandcallsinclude* lesUUandtheirincluded lesincludeT les.*The9include leconstructopGeratesataverylowlevel.OAnincludelinecanappGearanywhereinthe*inputUU leregardlessofthecontextofthesurroundinglines.*F*unnelWebsetsthespGecialcharactertothedefault(@)atthestartofeachinclude leandrestores*ittoitspreviousvqalueattheendoftheinclude le.^IThisallowsmacrolibrariestobGeconstructed*andóincludedthatareindepGendentoftheprevqailingspecialcharacteratthepointofinclusion.A@{@-*i=1;*while?(i<=N):m@*endwhile*@}*@$@@{@-*a[i]:=0;*i:=i+1;@}*UnderUUtheregimeofnoTinden9tationtheloGopstructuremacroexpandsto:*i=1;*while?(i<=N):ma[i]:=0;*i:=i+1;*endwhile*UnderUUtheregimeofblankTinden9tationtheloGopstructuremacroexpandsto:K%78OK)<;Ġݻ_"E*i=1; *while?(i<=N):ma[i]:=0;:mi:=i+1;*endwhile}*TheindentationpragmadetermineswhichofthesetworegimeswillbGeusedtoexpandthemacros*whenUUconstructingtheproGduct les.qThesyntaxofthepragmais:*pragma_ident?=ps"indentation"s"="s("blank"|"none")*ItsUUtwoformsloGoklikethis:*@p?indentation=blank*@p?indentation=none*In0thecurrentversionofF*unnelWeb,7the0indentationregimeisanattributethatisattachedtoan*entirerunofT*angle;itisnotpGossibletobindittoparticularproduct lesortoparticularmacros.*Asޖaresult,VitdoGesn'tmatterwhereindentationpragmasoccurintheinput leorhowmanythere*areUUsolongastheyareallthesame.qBydefaultF*unnelWebUUusesblankindentation.!Ӎ*3.10.11.2bCMaxim9umTInputLineLengthOg*F*unnelWebgeneratesanerrorforeachinputlinethatexceedsacertainmaximumnumbGerof*characters.gDAt5thestartoftheproGcessingofeachinput leandeachinclude le,<thismaximumis*setkLtoadefaultvqalueof80.However,pthekLmaximumcanbGechangedusingamaximuminputline*lengthUUpragma.*pragma_mill?=ps"maximum_input_line_length"s"="snumorinf*ThefmaximuminputlinelengthcanbGevqarieddynamic}'allythroughouttheinput le.Eachmaxi-*mumMinputlinelengthpragma'sscopGecoversthelinefollowingthepragmathroughtoandincluding*theBnextmaximuminputlinelengthpragma,}butnotcoveringanyinterveninginclude les.'ExX,G!thenif$(theTU>'ExX\mathematicsmoGde"character)appearsintheinput le,CitwillG!bGeUUbewrittentothedocumentation leas\$.Z&G!Restrictionsonthetargett9ypQesetter:$Atwalaterdate,di erentweavemoGdulesG!mightlbGeincorporatedintoF*unnelWebltocaterforavqarietyofdi erenttypGesetters.G!IfthishappGens,itwillbeimportanttoensurethattypGesetter-speci csource lesG!(i.e.ltypesetter6=none)arenotproGcessedwithdi erenttargettypGesetters.-F*orG!example,a\usermightinnoGcentlyattempttogenerateatroffdoGcumentation leG!from,aF*unnelWeb,source lecontainingatypesetter?=tex,(andbyimplicationG!TU>'ExXCcontrolsequences).MThepragmacouldalsobGeusefulforcatchingtypGesetterG!clashesEinsourceandinclude les.7ThesettingnoneisspGecialbecauseitisguaranteedG!toUUworkwithanyfuturetargettypGesetter.Z&*TheyaimofallthisistoensurethatanytypGesetterdependencyiscorrectlyproclaimed.J4Because*none(isthedefaulttypGesetter,1auserwhocreatesasource lewithoutatypesetter?=x(pragma*willԚsoGon ndthatthecontrolsequencestheyareinsertingintothesourcedoGcumentareappGearing*verbatimintheprinteddoGcumentation!bInordertoactivqatethesesequences,theywillbGeforced*toUUaddatypesetterpragma,thusmakingthedepGendencyexplicit.*It{Smayseemstrangetoplacethetypesettersettingfacilitywithinapragma(@p)whenthereis*aseparatetypGesettingconstruct(@t).Thishasbeendonetosustaintheruleofthumbthatsays*thatUUpragmasdonotparticipateintheparser-levelsyntax,buttypGesetterdirectivesdo.K%80Qc٠)<;Ġݻ_"E*3.10.12amFreestandingTyp`esetterDirectives *F*unnelWebprovidestwokindsoftypGesetterdirectivetoassisttheusertoproGducedocumentation. *Thesei=areinlineandfreestanding.~Unlikepragmas,n7eachofthesecategoriesofdirectivepartic-*ipatesintheparser-levelsyntaxandcanappGearonlyincertaincontexts(seetheparsersection).*Inline}directivesaredesignedtobGeusedwithinparagraphstoalterthelookoftheenclosedtext.*F*reestandingtypGesetterdirectivesaredesignedtoappGearonlinesoftheirownandhaveabigger*typGographicalUUimpact.Y*The 4syntaxoffreestandingtypGesetterdirectivesisalmostidenticaltothatofpragmas.dAllthe*samesyntaxrulesapply(exceptthattheactualkeywordsaredi erent).NThefollowingsubsections*describGeUUthefourtypesetterdirectivesavqailable.7*ftd?=ftd_newpage|ftd_toc|ftd_vskip|ftd_title*ts =?"@t"g*3.10.12.1bCNewTP9age *TheUUnewpagepragmaisatypGesettingpragmawiththefollowingsyntax.*ftd_newpage?=ts"new_page"*ItUUonlyformloGokslikethis.*@t?new_page*Itsmsolee ectistocausea\skiptoanewpage"commandtobGeinsertedintothedocumentation* le."TheInewpagecommandissuchthatifthetypGesetterisalreadyatthetopofapage,itwill*skipUUtothetopofthenextpage.g*3.10.12.2bCT ableTofCon9tents *TheUUnewpagepragmaisatypGesettingpragmawiththefollowingsyntax.*ftd_toc?=ts"table_of_contents"*ItUUonlyformloGokslikethis.*@t?table_of_contents*Itssolee ectistoinstructW*eavetoinsertatableofcontentsatthispGointintheprinteddoGcu-*mentation.qThisUUpragmadoGesnotskiptoatopofanewpage rst.g*3.10.12.3bCV erticalTSkip *ThezverticalskippragmaisatypGesettingpragmathatinstructsW*eavetoinsertaspGeci edamount*ofUUverticalspaceintothedoGcumentation.qThepragmahasthefollowingsyntax.*ftd_vskip?=ts"vskip"snumbers"mm"*F*orUUexample:*@t?vskip26mmK%81RtN)<;Ġݻ_"E*3.10.12.4bCTitleR*TheUUtitlepragmaisatypGesettingpragmawiththefollowingsyntax.*ftd_title?=ts"title"sfontsalignmenttext *font=?"normalfont"|"titlefont"|"smalltitlefont"*alignment?="left"|"centre"|"right"*text=?""""{printable_char}""""*It'se ectistoinstructW*eavetoinsertasinglelineintotheprinteddoGcumentationcontaining*theDcspGeci edtextsetinthespeci edfontandalignedinthespeci edmanner.l!Thedoublequotes*delimitingthetextareforshowonly;bifyouwanttoputadoublequoteinthestring,5youdon't*needUUtodoublethem.*HereUUisanexampleofthepragma.*@t?titlesmalltitlefontcentre"HowtoFlipaBit"#*3.10.13amScanner/ParserInterfaceR*Ifthescannerterminateswithoutanyerrors,controlispassedtotheparser.ITheparserparsesthe*tokenJ6listgeneratedbythescanner.nThetokenlistconsistsoftextscraps,LpfreestandingtypGesetter*directives,UUandspGecialsequencetokens.*TheausershouldbGearinmindthatthesc}'anner nishesrunningbeforetheparserstartsrunning.*ThismeansthatthescannercannotbGein uencedinanywaybyhigherorderstructuressuchas*thevparsermightparse.LF*orexample,itisimpGossibletowriteaFunnelWebmacrotoincludea le,*orUUinsertavskippragmaintotheinputtext.(P*3.11XP=arserS*By^thetimetheparserstarts,thescannerhascompletelyterminated.AtthispGoint,itisnot*pGossibleu{foranymore lestobeincluded,}andspecialcharactersarenolongerpresenttoconfuse*things.$All;thatremainsisalistoftexttok9ens,u$spQecialtokens,u$and;typQesetterdirective*tok9ens.o]T*extNtokensconsistentirelyofsequencesofprintablecharactersandendoflinemarkers.*SpGecial#rtokensrepresentthespGecialsequencesthatthescannerfoundintheinput le.a&TypGesetter*directivetokensrepresentthefreestandingtypGesetterdirectivesthatthescannerencountered.DThe*parser԰consumesthetokenlistandbuildsamacrotablethatislaterusedtogenerateproGduct les.*ItUUalsoconstructsadoGcumentlistthatisusedtogeneratethedocumentation le.*TheUUsyntaxrulesappGearinginthefollowingsectionsrefertothetokenlist.#*3.11.1ZHighLevelStructureR*Atthehighestlevel,theF*unnelWebparserparsestheinput le(tokenlist)intoasequenceoftext*scraps,UUmacrode nitions,andtypGesetterdirectives.*input_file?={text|macro|directive}*All?threeofthesekindsofcompGonentscontributetothedoGcumentation le,^zbutonlymacro*de nitions}kcontributetotheproGduct les.Ifallthefreetextanddirectiveswereremovedfroma*F*unnelWebUUinput le,theproGduct leswouldnotbea ected.K%82S~h)<;Ġݻ_"E*3.11.2ZFreeText"N*F reeztext=isanytextthatisnotpartofamacrode nitionoradirective.!~Ascrapoffreetext *consistsiaofasequenceofitemsdrawnfromthefollowinglist:non-spGecialprintablecharacters,*insert-eolspGecialsequences,,insertspecialcharacterspecialsequences,,insertarbitrarycharacter*spGecialUUsequence.l*free_text=?ordinary_text*ordinary_text =?{ordinary_char|eol|text_special}+*text_special=?"@+"|"@@"|"@^"char_spec*ordinary_char =?"".."~"-special*AnUUexampleofsomerathermessyfreetextisasfollows:*This@@?isavery@+messy*@^D(009)chunk?oftextindeed.*But?FunnelWebstillviewsitas*a?singlechunkoftext.*F*unnelWebneverseestwotextchunksnexttoeachotherintheinput;Btheyarealwaysmerged*intoUUasingletexttoken.*TheExXchapter)*tothelowestlevelofE(likeaLffUIaTU>ExXsubsubsubsection).F*unnelWebinput lesneednotcontain*anyAsectionsatall,Ebutiftheydo,the rstsectionmustbGeatlevelA,andfollowingsectionsmust*not"qskiphierarchicallevels(e.g.an@D"=cannotfollowan@C).F*unnelWeb"qgeneratesanerrorifa*levelUUisskippGed.*Alle>sectionmusthavee>namesassoGciatedwiththem,Cbutforconvenience,thee>sectionnameisoptional*if0thesectioncontainsoneormoremacrode nitions(i.e.atleastonemacrode nitionappGears*bGetween+thesectionconstructinquestionandthenextsectionconstructintheinput le.).In*thiseVcase,Vthesectioninheritsthenameofthe rstmacrode nedinthesection.Thisfeature*streamlinesUUtheinput le,avoidingUUduplicatenameinconsistencies.*AnysequenceofprintablecharacterscanbGeusedinthesectionname,eventhetargettypGesetter's*escapGeUUsequence(e.g.inTU>'ExX,\\").*TheUUfollowingexampledemonstratesthesectionconstruct.*@A@*This?isthemainsimulationmoduleforplanetearth,simulateddowntothe*molecular?level.ThisisaREALLYbigprogram.Imeanreallybig.Imean,*if?youthoughttheX-Windowssourcecodewasbig,you'reinforashock...*@B?Westartbylookingatthecodeforsixleggedstickinsectsasthey*form?agoodexampleofatypicalobject-orientedanimalimplementation.*@$@@{@-*slsi.creep;?slsi.crawl;slsi.creep;@}*InstheabGovesexample,zthenameforthelevelA`sectionisprovidedexplicitly*,zwhilethenamefor*theUUlevelBsectionwillbGeinheritedfromthemacroname.!*3.11.3.2\LiteralTDirectiv9eR6*ExpGerience@hasshownthatoneofthemostcommontypGesettingrequirementisthatofbGeingable*tomtypGesetsmallprogramfragmentsinthemiddleofthedoGcumentingfreetext.Typicallythere*iseafrequentneedtorefertoprogramidenti ers,ianditassiststhereadertohavesuchidenti ers*typGesetninthesamemannerastheprogramtextinthemacrode nition._%F*unnelWebnV1de neda*TU>'ExXmacroforthis(calledp)thatsimplytypGesetitsargumentintt?font._Thisprovedsouseful,*thatUUthefacilityhasbGeenmadetypGesetter-independentUUinF*unnelWebUUV3.h*T*o8KspGecifythatsometextbetypesetintt?font,>enclosethetextincurlybracespecialsequences*asUUfollows.*literal?="@{"ordinary_text"@}"*AsSinmacronames,Ksectionnames,andmacrobGodies,theStextcontainedwithintheliteralconstruct *isprotectedbyF*unnelWebfromanynon-literalinterpretationbythetypGesetterandtheuseris*freeBtoencloseanytextcoveredBbythede nitionordinaryEff&fǫtext.k_F*unnelWebguaranteesthat,Eno*matterwhatthetextis,itwillbGetypesetintt?fontexactlyasitappears.W@However,thetextwill*bGeUU lledandjusti edintoaparagraphasusual.h*HereUUisanexampleoftheuseoftheconstruct:K%84Uܠ)<;Ġݻ_"E*@C?The@{WOMBAT@}(WasteOfMoney,Brains,AndTime)function *calls?the@{kangaroo@}inputfunctionwhichhasbeen*known?tocausekeybounce.*This?keybouncecanbedampenedusingthe@{wet_sloth@}subsystem.**3.11.3.3\EmphasisTDirectiv9e$5*The/Qemphasisdirectiveisverysimilartotheliteraldirectiveexceptthatitcausesitsargumentto*bGe gtypesetinanemphasisedmanner(e.g.italics).Y#Liketheliteraldirective,0theemphasisdirective*protectsUUitstextargument.*emphasise?="@/"ordinary_text"@/"*Example:*@C?Whatyou@/really@/need,ofcourse,isa@/great@/,@/big@/, *network?withpacketsjustflying@/everywhere@/.*This?sectionimplementsaninterface*to?sucha@/humungeous@/network.!**3.11.4ZMacros$5*The]/thirdcategoryofconstructappGearingatthehighestsyntacticlevelinaF*unnelWeb]/input* letisthemacrode nition.$A[macrode nitionbindsauniquemacroF+nametoamacrobQody*containinganexpressionconsistingoftext,ژcallstoothermacros,andformalparameters.The*syntaxUUforamacrode nitionisasfollows:*macro?=("@O"|"@$")name[formal_parameter_list]T["@Z"]?["@M"]["=="|"+="]"@{"expression"@}"*The̋complexityofthemacrode nitionsyntaxismostlytoenabletheusertoattachvqarious*attributestothemacro.IftheuserchoGoses@O,thenthemacrocannotbecalled,butisinstead*attachedlhtoaproGduct le.IftheuserchoGoses@$,r-thenthemacroisanordinarymacrode nition*thatUUisnotattachedtoa le.ፑ*Bydefault, Ranon- lemacromustbGeinvokedexactlyoncebyoneothermacro.RMacrosthataren't*areU aggedwitherrorsbytheF*unnelWebUanalyser.sHowever,iftheuserusesthe@ZUsequence*in%themacrode nition,YthemacroisthenpGermittedtobeinvoked%zerotimes,Yaswellasonce.*Similarly*,iftheuserusesthe@Msequenceinthemacrode nition,themacroispGermittedtobe*called1manytimesaswellasonce.7[IfbGoth@Z and@MarepresentthenthemacroispGermittedto*bGeUUinvokedzero,one,ormanytimes.ፑ*Theb(purpGoseofenforcingthedefault\exactlyonecall"ruleisto agpiecesofcodethattheuser*mayKhavede nedinamacrobutnothoGokedintotherestoftheprogram.nExpGerienceshowsthat*this0isacommonerror.DSimilarly*,gIitcanbGedangeroustomultiplyinvokeamacrointendedto*bGe^.invokedonlyonce.QF*orexample,ditmaybGedangeroustoinvokeascrapofnon-idempGotent*initializationgcoGdeintwogdi erentpartsofthemainfunctionofaprogram!However,lF*unnelWeb*willnotgenerateanerrorifamacrowithout@Miscalledbyanothermacrothatiscalledmore*thanUUonce.ፑ*If;thetextstring==(ornothing)followsthemacroname,@theexpressionthatfollowsistheentire*textىofthemacrobGody*.bIfىthetextstring+=followsthemacroname,thenmorethanonesuch*de nition isallowed (butnotrequired)inthedoGcumentandthebodyofthemacroconsistsofthe*concatenation ofallsuchexpressionsintheorderinwhichtheyoGccurintheinput le.~Sucha*macro issaidtobGeadditiveandisadditiv9elyde ned.YThusamacrobGody caneitherbGede ned*in{oneplaceusingonede nition(using==)oritcanbGedistribute}'dthroughouttheinput leinaK%85Vo)<;Ġݻ_"E*sequenceofoneormoremacrode nitions(using+=).OIfneither==and+=arepresent,/F*unnelWeb *assumesUUadefaultof==.z*MacrosattachedtoproGduct lescannotbeadditivelyde ned.NPAdditivelyde nedmacroscanhave*parameterGlistsand@Z8and@Mattributes,&butthesemustbGespeci edonlyinthe rstde nitionof*theUUmacro.qHowever,+=mustappGearineachde nition.!ȍ*3.11.4.1\NamesN*Names:areusedtoidentifymacrosandsections.*wAnameconsistsofasequenceoffromzeroto*80qprintablecharacters,includingtheblankcharacter.[{EndoflinecharactersarenotpGermittedin*names.]Namesoarecasesensitive;|twoodi erentmacrosarepGermittedtohavenamesthatdi erin*case@oonly*.jLikefreetext,DnamesaretypGesetbyF*unnelWeb@oandaresafefrommisinterpretationby*theݤtargettypGesetter. F*orexample,itisquiteacceptabletousethemacroname@<\medskip@>*evenUUifthetargettypGesetterisTU>'ExX.z*name=?"@<"name_text"@>"*name_text?={ordinary_char|text_special}!ȍ*3.11.4.2\F ormalTP9arameterListsN*F*unnelWeballowsmacrostohaveuptoninemacroparameters,'\named@1,@2,:::,@9.^Ifamacro*doGes+nothave+aformalparameterlist,4itisde nedtohave+noparameters,andanactualparameter*list=?name[actual_parameter_list] *actual_parameter_list?="@("actpar{"@,"actpar}"@)"*actparS=?expression|(?whitespace"@"""expression"@"""whitespace)*whitespace>=?{""|eol}Ə*F*unnelWeb6allowsparameterstobGepasseddirectly*,/ordelimitedbyspGecialdoublequotes.ykEach*formTisusefulunderdi erentcircumstances.$DirectspGeci cationisusefulwheretheparameters*are=nshortandcanbGeallplacedononeline.iDoublequotedparametersallowwhitespaceoneither*side(thatisnotconsideredpartoftheparameter)andareusefulforlayingoutrathermessy*parameters.qHereUUareexamplesofthetwoUUforms.Ə*@@(:m@"x:=1;@" @,:m@"x<=10;@"?@,:m@"print?"x=%u,x^2=%u",x,x*x;:mx:=x+1;@+@"*@)*@@(red@,green@,blue@,yellow@)*AsUUshown,thetwoformsmaybGemixedwithinthesameparameterlist.*ExpGerienceUUhasshownthatthevqastma8jorityofmacroshavenoparameters.ې*3.11.7ZFormalParameters4*F*ormal+wparameterscanappGearintheexpressionsformingmacrobodiesinaccordancewiththe*syntax rulesde nedabGove. eAformalparameterexpandstothetextoftheexpansionofits*correspGondingactualparameter.GThereisnothingpreventingaformalparameterbeingprovided*as3partofanexpressionthatformsanactualparameter.X`InthathappGens,jtheformalparameter*isbGoundtotheactualparameterofthecallingmacro,?notthecalledmacro.oAfterthefollowing*de nitions,*@$@@(@1@)=@{A?walrusin@1isawalrusinvain.@}*@$@@(@1@)=@{@@(S@1n@)@}*theUUcall*@@(pai@)*willUUresultintheexpansion*A?walrusinSpainisawalrusinvain.ې*3.11.8ZMacrosareStatic4*InK F*unnelWeb,ytheactionsofmacr}'oude nitionandmacrouexpansionoGccurduringtwoseparate*phases(parserandtangle)andcannotbGeinterleaved.NAsaresult,theF*unnelWebmacrofacilityis*completelyT:static.qiItisnotpGossibleforonemacrotode neanotherwhilethe rstmacroisbeing*expanded;?)each7mustbGede nedstatically*.EnItisnotpossibletode neamacrotoevenassistin*the_de nitionofothermacros.Becausethescanner,parser,analyser,and_tanglerphasesareall*invokedosequentially*,vthereisnoroGomforfeedbackofde nitionsbGetweendi erentlevels(e.g.the*userUUcannotde neamacroforthevskippragma).*ThislackofpGowerisfullyintentional.jdBytotallyexcludingthemoreincomprehensiblewaysin*which6ageneralpurpGosemacropreprocessorcanbeused,@(@@(Walrus@)@)?@!?LEGALrecursiveinvocation.*@$@==@{@@}/?@!?ILLEGALrecursivedefinition.'*3.13XTangleN*Ifthescanner,A%parser,andanalyserhavesuccessfully(i.e.withnoerrors,A%severeerrors,orfatal*errors)tcompleted,dandtheT*angleoption(+O)tKisturnedon(itisbydefault),thentheT*angle*compGonentRofF*unnelWebRisinvokedtogeneratetheproGduct lesspeci edinthe@OBmacrosofthe*inputUU le.*TheopGerationofT*angleisverysimple.Each@Omacroisexpandedandwrittentoa leofthe*samename.)Astherearea nitenumbGerofmacros,andtheanalyserguaranteesthatthemacro*structureUUisnon-recursive,T*angleisguaranteedtoterminate.*ThreeUUremainingpGointsareworthdiscussing.K%88Y*)<;Ġݻ_"E61.CT*angleexpandsmacrosusingblankindentationunlesstheuserhasspGeci edotherwiseinan CindentationUUpragmaintheinput le(seeSection3.10.11.1).)62.CT*anglelkeepstrackofthelengthofthelinesthatitiswritingandissuesanerrorifanyClinecWofanyproGduct lethatitgeneratesislongerthanthemaximum.ThemaximumistheCminimum%ofavqaluedefaultedorspGeci edintheinput le(Section3.10.11.3),/tandthevalueC(ifUUany)providedbythe+wcommandlineargument(Section3.7.3).)63.CIt>isworththeuserobtainingsomeunderstandingoftheresourcesthatF*unnelWeb>requiresCtoUUpGerformitstask.*WhencF*unnelWeb'sscannerexecutes,&itreadseach leintomemorywhereitiskeptfortheduration*ofbtherun.A!Thus,theremustbGeroominmemoryfortheentireinput le,includingallinclude les.*WhilethisapproachmayseemexpGensiveinmemory*,?itisalmostnecessaryinordertosuppGort*forward8references.[T*omerelyscantheinput le, qrecordingthemacronames,butleavingthetext*onUUdisk,wouldrequiremanyrandomaccessdiskseeks.)*In>contrast,8F*unnelWebneverbuildsaninternalrepresentationoftheproGduct le.UInstead,8each*pieceofoutputiswrittenimmediatelytotheproGduct le.CThismeansthataslongastheinput le* ts[inmemory*,\theproGduct lecanbearbitrarilylarge.Italsomeansthatusersneednotfearto*de ne|orcallmacrosthattheyknowwillexpandtomegabytesoftext.[Norneedtheyfearplacing*acalltosuchamacroaspartofanactualparameter.%F*unnelWebdoGesnoteverexpandactual*parameterszinternally*.Infact,itdoGesnotexpandthemuntilithitsthecorrespGondingformal*parameter)duringitsexpansionofthecalledmacro.cQAtthatpGoint,2itloGoksuptheexpr}'ession(not*theUUexpansionoftheexpression)forthecorrespGondingactualparameter,andstartsexpandingit.$q *3.14XWea=ve؍*Ifthescanner,A%parser,andanalyserhavesuccessfully(i.e.withnoerrors,A%severeerrors,orfatal*errors)jcompleted,andtheW*eavejoption(+T)Risturnedon(itiso bydefault),thentheW*eave*compGonent4ofF*unnelWeb4isinvokedtogenerateatext leintheformatofaparticulartypGesetter.*The?result,DwhenfedthroughtheparticulartypGesetterandprinted,DisafullytypGesetrepresentation*ofUUtheentireinput lecompletewithcrossreferencinginformation.]{*3.14.1ZTargetTyp`esetter*Currently*,|FunnelWebtproGducesdocumentation lesintheformatofonlyonetypGesetter|TU>'ExX.*However,%+the!W*eavepackqageofF*unnelWebisfairlysmall,%+anditishopGedthatitcanberewritten*so+astoprovideacollectionoftypGesettermodulesfromwhichtheuserwillbeabletochooseusing*aUUcommandlineargument.]{*3.14.2ZCrossReferenceNumb`ering*WhenZF*unnelWebproGducesitstypesetdocumentation,J[itnumb}'erseachsectionandeachmacro*de nitionandcrossreferencesthemacrode nitions.yTheexactschemeusedhasbGeencarefully*thoughtUUout.qHowever,asitcanbGealittleconfusingtothebeginner,itisexplainedhereinfull.)*ThekmostimpGortantthingisthatthereisnor}'elationbetweenkthemacronumberingkandthesection*numbGering.In7nKnuth'sW*ebthereareonlysectionnumbGers.InF*unnelWeb,othenumbGeringof*sectionsUUandmacrosisseparated.*InF*unnelWeb,se}'ctionsarenumbGeredhierarchicallyinascendingorder.0F*orexample,thesecond*level-CsectionDofthethirdlevel-Bsectionofthe rstlevel-AsectionisnumbGered\1.3.2".In*contrast,macr}'oude nitionsΗarenumbGeredsequentiallyinascendingorder.݌F*orexample,the rst*macro#de nitionisnumbGer#1,-thesecondisnumber#2,-andsoon.aNNotethatitismacr}'ofqde nitions*that8arenumbGered,qnot8macr}'os.DThisdistinctionisnecessarybecauseadditivemacros(i.e.the*oneswith+=)canbGede nedbyacollectionofpartialde nitionsscatteredthroughouttheinput* le.qAUUsingleadditivemacromaybGede nedinde nitions5,67,128,and153.K%89Z)<;Ġݻ_"E*3.15XFunnelWebShell%*3.15.1ZIntro`ductionT*One_kofthegoalsofF*unnelWeb_kisthatitmustbGeextremelyportable.Hugee orts,desperate *actions,sand:agreatsacri cesweremadeinthenameofpGortability*. For:aexample,sFunnelWebis*writtenUUinC.+W*Anz6equallyimpGortantgoalwasthatofcorrectnessandreliability*.jToz6thisend,nitwasdetermined*thatalargeautomatedsuiteoftestprogramsbGepreparedtoassistinregressiontesting.>Preparing*theUUtestsuitewastedious,butachievqable.qAutomatingitpGortablywasmoredicult.*The)/dicultyfacedwasthatifF*unnelWeb)/wasimplementedintheformofautilitythatcouldbGe*invokedkfromtheopGeratingsystemcommandlanguage,theonlywayktosetupregressiontesting*was~inthecommandlanguageoftheopGeratingsystemofthetargetmachine(shellscriptsforUNIX,*DCLdforƈVMS,batch lesforMSDOS,andnothingontheMacintosh).B.Thehugevqariationinthese*commandlanguagesledtotheconclusionthateithertheautomationofregressiontestingwould*haveqtobGerewrittenoneachtargetmachine, orasmallcommandlanguagewouldhavetobGe*createdwithinF*unnelWeb.=Intheend,pthetwingoalsofpGortabilityandregressiontestingwere*consideredsoimpGortantthatasmallcommandshellwasconstructedinsideF*unnelWeb.Thisis*calledUUtheF unnelWebTcommandshell,UUorjust\theshell"forshort.*Byʼndefault,whenF*unnelWebʼnisinvoked,itʼndoGesnotenteritsshell.cIfjustgiventhenameofan*input le,itwillsimpleproGcesstheinput leinthenormalmannerandthenterminate.,T*oinstruct*F*unnelWebftoinvokefitsshell,Vthe+KfYor+XcommandlineoptionmustbGespeci edwhenF*unnelWeb*isinvokedfromtheopGeratingsystem.SItisalsoinvokedupGonstartupifthe lefwinit.fwsexists.*MostF*unnelWebuserswillneverneedtousetheshellandneednotevenknowabGoutit.lThere*areUUfourmainusesoftheshell:lZ61.CAsUUatoGoltosupportautomatedregressiontesting.V62.CAsmadevelopmentmtoGolonmachinesthatdonothaveabuiltinshell(e.g.theMacintosh).CTheUUshellcanbGeusedtoprocesswholegroupsof lesautomatically*.63.CAsaconvenience.gAuserworkingonamulti-tasking,multi-windowworkstationmaywishCtoh keepaninteractivesessionofF*unnelWebh goinginonewindowratherthanhavingtorunCupUUtheutilityeachtimeitisrequired.64.CAsaconvenientvehicleforenclosingutilities.0TheF*unnelWebshellcontainsusefulgeneralCpurpGoseUUcommandssuchasthedi erencescommanddiff."ڍ*3.15.2ZReturnStatusesT*TheOhierarchyofdiagnosticsdescribGedinSection3.5isalsousedintheshellcommands.̶Each*shellUUcommandreturnsastatuswhichcana ectfurtherproGcessing.+WG!SuccessUUstatusisthenormalcommandreturnstatus.G!W arningĸstatusisreturnedifsomeminorproblemarosewiththeexecutionofthe G!command.G!Errorstatusisreturnedifasigni cantproblemarisesduringtheexecutionoftheG!command.PHowever,unlikeasevereerror,itdoGesnotcauseterminationoftheen-G!closingUUshellscript.G!Sev9ereMerrorestatusisreturnedifaproblemarisesduringtheexecutionoftheG!commandxthatpreventsxthecommandfromdeliveringonits\promise".KAxsevereG!error~causesF*unnelWeb~toabGortthescript(andanystackedscripts)totheinteractiveG!level.q(However,UUthetoleratecommandallowsthistobGetemporarilyoverridden).K%90[&)<;Ġݻ_"EG!F atalerror"statusisreturnedifaproblemarisesthatissoseriousthatexecutionof G!F*unnelWebdcannotcontinue.!AdfatalderrorcausesF*unnelWebdtoabGorttotheoperatingG!systemUUlevel.DG!Assertion\errorstatusisneverreturned.IfanassertionerroroGccurs,tF*unnelWebG!bGombsxoutungracefullytotheoperatingsystem.9Assertionerrorsshouldneverhap-G!pGen.qIfUUtheydo,thenthereisabuginF*unnelWeb.*T*oRybGeprecise,thestatusreturnedbyeachcommandisavectorofnumbGersbeingthenumber*ofeachofthedi erentkindsofdiagnosticgeneratedbythecommand.Usuallyonlyonekindof*diagnosticisgenerated.THowever,{thefwcommandandafewoftheothercommandscangenerate*morethanonekindofdiagnostic.eThesestatusvectorsaresummedinternallywheretheymay*laterbGeaccessedusingthestatuscommand.^However,'#thecurrentdiagnosticstateevqapGoratesas*soGonUUasthenextcommandisencountered.$*3.15.3ZCommandLineLengthՍ*TheUUmaximumlengthofashellcommandlineisguaranteedtobGeatleast300characters.*3.15.4ZStringSubstitution*Most/'commandshellsprovidesomeformofstringsubstitutionsoastoprovidesomedegreeof *parameterization.zTheF*unnelWebshellprovides36di erentstringvqariablesnamed$0..$9and*$A..$Z(caseinsensitive).rEachvqariablecanholdastringcontaininganysequenceofprintable*charactersUUandcanbGeaslongasacommandline.D*Thebdefinecommandallowstheusertoassignavqaluetothesevariables.Thedefinecommand*takes]twoarguments.AThe rstisthedigitorletterofthevqariabletobGede ned.Thesecondisa*double4quotedelimitedstringbGeingthestringvqaluetobeassignedtothevqariable.fIfyouwantto*includeUUadoublequotecharacterwithinthestring,youdon'tneedtodoubleit.*Examples:**define?3"/root/usr/usrs/users/users5/thisuser/workdir/fwdir/testdir"*define?M"/user/local/rubbish/bin/fw"*define?Q"Youdon'tneedtodouble"doublequotes"*Only#stheidentifyingcharacterofthevqariablebGeingassignedisusedinthede nition.a'Thissyntax*is]asimpleway]ofpreventing]thevqariablefrombGeingsubstitutedbeforeithasachancetobe*de ned!D*TheUUfollowingpGointscleanuptheremainingsemanticdetails:9CThereqisonlyonesetofvqariablesandtheyareglobaltoallshellscripts._Therearenoܯlo}'calCvariables.9CWhenashellscriptisinvokedusingtheexecutecommand,Guthesubstitutionvqariables0CthroughUU9area ected.qSeeSection3.15.7.9formoredetails.9CIfUUyouwanttoincludeadollarsigncharacterinacommanduse\$$".9CF*unnelWebualsode nes\$/"whichtranslatestothecharacterthatseparatesdirectoryandC le'&name eldsin lenamesonthehostmachine. ;F*orexample:jSun=\/",Vax=\]",CMac=\:",UUPC=\\".9CSubstitutionUUisnotpGerformedrecursively*.K%91\e)<;Ġݻ_"E*3.15.5ZHowaCommandLineisPro`cessedq*WhengF*unnelWebreadsinacommandline(fromtheconsoleorascript le),itproGcessesitinthe *followingUUsequence:"M961.CThe6commandlineischecked6fornon-printablecharacters.gIfthereareany*,!OriginalinvocationofFunnelWebfromOS.-!?Shelloptionsarenowdefaultwith"+t".*FunnelWeb>fw?sloth!Equivalenttofwsloth+t.*FunnelWeb>set?-l!Changethelshelloption.*FunnelWeb>fw?sloth+q!Equivalenttofwsloth+t-l+q.*FunnelWeb>fw?sloth!Equivalenttofwsloth+t-l.*The"existenceoftheshelloptionsetmeansthattheusercansetupasetofdefaultstobGeapplied*toUUallfwcommandsissuedwithintheshell.K%92])<;Ġݻ_"E*3.15.7ZShellCommandsQ*ThisUUsectiondescribGeseachoftheF*unnelWebUUshellcommands.qThesyntaxis:u*shell_command?=absent|codify|compare|define|diff|diffsummary| ~diffzero?|eneo|execute|exists|fixeols|help)|~here?|?quit|set|show|skipto |status|~tolerate?|trace |write|writeu*s?={""}+*AsU arule,F*unnelWebU shellcommandsreturnseverestatusiftheirargumentsaresyntactically*incorrectUUoriftheyareunabletosuccessfullyopGerateonargument les.sL*3.15.7.1\Absen9tQ*TheXabsentcommandpGerformsnoactionexcepttoreturnastatus.{Ifthe lespeci edinits*argumentUUdoGesn'texistitreturnssuccessstatus,otherwiseitreturnsseverestatus.*Syntax?:absent="absent"sfilename*Example:?absentresult.out*ThiscommandisusefulinregressiontestingformakingsurethatF*unnelWebhasnP'tproGduceda*particularUUoutput le.sL*3.15.7.2\CoQdifyQ*TheMvcodifycommandtakestwoarguments:maninput leandanoutput le.o'Itreadseachlineof*the input leandwritesacorrespGondinglinetotheoutput le.XThecorrespondinglineconsistsof*awCJmacrocallcontainingastringcontainingtheinputline.6}Thecommandconvertsallbackslashes*in'ExXde nitionsthatappGearsatthetopofevery*doGcumentation5 lewascodifiedandinsertedintotheF*unnelWeb5coGdesothatF*unnelWeb5would*notUUhavetoloGokfora lecontainingthede nitionsatruntime.sL*3.15.7.3\CompareQ*Thecomparecommandtakestwo lenameargumentsandpGerformsabinarycomparisonofthe*twogY les.Ifthe lesareidentical,ksuccessstatusisreturned.Iftheyaredi erent,kseveregYstatusis*returned.qNoUUinformationabGoutthemannerinwhichthe lesdi erisconveyed.*Syntax?:compare="compare"sfilenamesfilename*Example:?compareresult.txtanswer.txt*TheAncomparecommandwascreatedasthemaincheckingmechanismforregressiontesting.k%How-*ever,itsCbinaryoutputwassoGonfoundtobeunworkqableCandthemoresophisticateddiffcommand*wasUUaddedsothattheactualdi erencesbGetweenthe lescouldbGeexamined.K%93^!L)<;Ġݻ_"E*3.15.7.4\De ney*Thedefinecommandassignsavqaluetoashellstringsubstitutionvariable.X)<;Ġݻ_"E*3.15.7.9\Execute/*TheexecutecommandcausesaspGeci edtext letobeexecutedasaF*unnelWebshellscript. *The rstargumentisthenameofthescript le.wTheremainingargumentsareassignedtothe*substitution1vqariables$1,h$2,:::,$9.`Substitution1variablesintherange$1to$9thatdonot*correspGondtoanargumentaresettotheemptystring"".N$0issettotheemptystringregardless.*TheexecutecommandcanbGeusedrecursively*,|allowingshellscriptstoinvokeeachother.]XA le*extensionUUdefaultof\.fws"(F*unnelWebUUScript)appliestoscript les.*Syntax :?execute="execute"sfilename{argument_string}*Examples:?executemegatest.fws/usr/users/ross/fwtest!_-execute?sloth*TheUU rstexampleabGoveUUwillresultinthefollowingsubstitutionvqariableassignments.*$0?=""*$1?="/usr/users/ross/fwtest"*$2?="!"*$3?=""*...*$9?=""*ItkshouldbGestressedthattherearenolocalvqariablesintheF*unnelWebkcommandlanguage;the*vqariablesUUabGovearegloballymoGdi ed.E*The!executecommandwasaddedtoallowthecreationofsub-scriptstotestF*unnelWeb!inpar-*ticularUUways.,=*3.15.7.10bCExists/*TheXexistscommandpGerformsnoactionexcepttoreturnastatus.{Ifthe lespeci edinits*argumentUUexistsitreturnssuccessstatus,otherwiseitreturnsseverestatus.*Syntax?:exists="exists"sfilename*Example:?existstest6.fw*ThisdcommandisusefulinregressiontestingforensuringthatF*unnelWebdhasproGducedaparticular*outputUU le.,=*3.15.7.11bCFixeols/*Thefixeolscommandtakestwo lenamearguments:Naninput leandanoutput le.Z]Itreadsin*theEinput leandwritesittotheoutput lechangingalltheendoflinecontrolcharactersequences*totheloGcalformat.1Itcanalsotakeone lenameargument,inwhichcaseitreplacesthetarget* leUUwithitstransformation.*Syntax :?fixeols="fixeols"sfilename[sfilename]*Examples:?fixeolsimported.hakresult.kln_-fixeols?sloth.dat*Thefixeolscommandworksbyparsingtheinput leintoalternatingrunsofprintablecharacters*(ASCIGI20toASCII126)andrunsofnon-printablecharacters(alltheothers).RItthenparseseach*run ofnon-printablecharactersfromlefttorightintosubrunsofnon-printablesnotcontainingthe*same~charactertwice.)CItthenreplaceseachsubrunwithanativeEOL.^6F*orexample,ifanative*EOLUUisX,andABCDarenon-printablecharacters,andthe letobGeconvertedis*۟rffğ J= "5-:6LܸNote:~eA0nativÎe0EOLcanbfixeolscommandwasdevisedtosolvetheproblemcreatedsometimeswhentext lesare *moveddfromonemachinetoanother(e.g.withthekermitprogram)usingabinarytransfermoGde*rather OthanatexttransfermoGde.ҴIfsuchatransferismade,S andthetext lelinetermination*conventionsTdi eronthetwoTmachines,Tonecanwindupwithasetoftext leswithimpropGerly*terminatedilines.#ThiscancauseproblemsonanumbGerioffronts,Vbutinparticulara ectsregression*testingHwhichreliesheavilyonexactcomparisonsbGetween les.PnThefixeolscommandprovidesa*solution#TtothisproblembyprovidingapGortablewayto\purify"text leswhoseendoflineshave*bGecome_incorrect.Theregressiontestingscriptsallapplyfixeolstotheirinputandoutput les*bGeforeUUeachtest.$u*3.15.7.12bCFw*ThefwcommandallowsF*unnelWebpropGertobeinvokedfromashellscript.GWThesyntaxisalmost*identicalUUtothesyntaxwithwhichF*unnelWebUUisinvokedfromtheopGeratingsystem.x*Syntax :?fw="fw"sordinary_funnelweb_command_line*Examples:?fwsloth+t+d_-fw?-lwalrus*SomeUUimpGortantpointsaboutthisfwcommandare:9COptionsUUareinheritedfromthedefaultshelloptions.۔9CTheUUF(input leoption)mustbGeturnedon.9CTheUUK,H,andXoptionsmustbGeturnedo .9CTheUUJoptionmustbGeturnedo .9CTheUUoptionsspGeci edinafwcommanddonota ectthedefaultshelloptions.9CThisUUcommandpGerformsnoactionintheVAXVMSversionofF*unnelWeb.$u*3.15.7.13bCHelp*ThehelpcommandprovidesonlinehelpfromwithintheF*unnelWebshell.hItprovidesaccessto *allUUofthesamemessagesthatthe+HcommandlineoptiondoGes.*Syntax :?help="help"[shelp_message_name]*Examples:?help_-help?commands*Ifnomessagenameisgiven,thedefaultmessageisdisplayed.}Itcontainsalistoftheotherhelp*messagesUUandtheirnames.qTheactualmessagesthemselvesarenotlistedhere.K%97bWʠ)<;Ġݻ_"E*3.15.7.14bCHere*TheMherecommandactsasatargetfortheskiptocommand.ZWhentheshellinterpreteren- *counterssaskiptocommand,itignoresallthefollowingcommandsuntilitencountersahere*command.h*Syntax?:here="here"*Example:?here*The$Oskipto/heremechanismwascreatedtoallowgroupsofregressionteststobGeskippedduring*debuggingUUwithouthavingtocommentthemout.qF*ormoreinformation,seeSection3.15.7.18."Y*3.15.7.15bCQuit*TheCquitcommandterminatesF*unnelWebCimmediatelyandreturnscontroltotheopGeratingsys-*tem.qThisUUappliesregardlessofthedepthofthescriptbGeingexecuted.*Syntax?:quit="quit"*Example:?quit"Y*3.15.7.16bCSet*TheiQsetcommandmoGdi esthedefaultshelloptions.F*orexample,nQset?+tsetsthe+toptionfor*allUUsubsequentF*unnelWebUUrunswithintheshelluntilanothersetcommandsets-t.*Syntax :?set="set"sordinary_funnelweb_command_line*Examples:?setsloth+t+d_-set?-lwalrus*The2restrictionsonthesetcommandareidenticaltothoseonthefwcommandexceptthat,*in*addition,UUthe+FoptioncannotbGeturnedoninthesetcommand.]*The׶setcommandisusefulforsettingoptiondefaultsbGeforealongrunofregressiontests.GItcould*also'KbGeusefultosetdefaultoptionsinaF*unnelWeb'Kshellkeptbyauserinaworkstationwindow."Y*3.15.7.17bCSho9w*ThePshowcommanddisplaysthecurrentdefaultshelloptions.pCTheseoptionsaretheoptionsthat*subsequentUUfwcommandswillinherit.*Syntax?:show="show"*Example:?show"Y*3.15.7.18bCSkipto*TheQskiptocommandcausestheshelltoignoreallsubsequentcommandsuntilaherecommand*isUUencountered.*Syntax :?skipto="skipto"*Examples:?skiptoK%98cb)<;Ġݻ_"E*The$Oskipto/heremechanismwascreatedtoallowgroupsofregressionteststobGeskippedduring *debuggingg(withouthavingtocommentthemout."cItislikeacutpricegoto."cF*orexample,suppGosing*thattherewereeighttestsandthatyouhaddebuggedthe rst ve.#Y*oumightwanttoskipthe* rst vetestssothatyoucanconcentrateonthenextthree.9 ThefollowingcoGdeshowshowthis*canUUbGedone.G*skipto*execute?testinfile1*execute?testinfile2*execute?testinfile3*execute?testinfile4*execute?testinfile5*here*execute?testinfile6*execute?testinfile7*execute?testinfile8*ItvgshouldbGestressedthatF*unnelWebvgperformsfullcommandlineprocessingincludingthedollar*substitutionsbGeforetestingthelinetoseeifitishere.Thiscanleadtonon-obviousproblems.*F*orUUexample.*skipto*!?TesttheParser*!?---------------*define?X"executeparsertest.fws"*$X?infile1*$X?infile2*$X?infile3*$X?infile4*$X?infile5*here*TheabGoveloGokscorrect,'but,bGecausethedefinecommandisn'texecuted(and$X isnotde ned)*thesubsequent$Xlinesresultinaleadingblankserror.]TheproblemcanbGecorrectedbyde ning*$XUUbGeforetheskiptocommand. **3.15.7.19bCStatus㍑*Thestatuscommandtakestwoforms.ezInits rstforminwhichnoargumentsaregiven,it*writesoutthenumbGerofwarnings,Terrorsandsevereerrorsthat1)weregeneratedbytheprevious*commandIand2)haveIbGeengeneratedduringtheentireshellinvoGcation.O8Initssecondformit*takes fromonetothreeargumentseachofwhichspGeci esadiagnosticseverityandanumbGer.O`The*statuscommandcompareseachofthesenumbGerswiththenumbGerofthatdiagnosticgenerated*byUUthepreviouscommandandgeneratesasevereerroriftheydi er.*Syntax :?status="status"{s("w"|"e"|"s")num}0..3*Examples:?status_-status?w1e5s1_-status?w4_-status?s1e2*The[statuscommandwasintroGducedtotestthestatusresultsofcommandsduringtheirdebug-*ging.`$It kisalsousefulforchecking ktoseethattherightnumbGerofdiagnosticshavebGeengenerated*atUUparticularpGointsintestscripts.K%99dkX)<;Ġݻ_"E*3.15.7.20bCT olerate *The{toleratecommandinstructstheshellnottoabGortprocessingofthescriptifthenextcom- *mandgeneratesoneormorewarnings,$errors,orsevereerrors.]FF*orthepurpGosesofthiscommand,*a blanklinecountsasacommand,+asobGesuretoplacethetoleratecommandimmediatelyabove*theUUcommandabGoutwhichyouwishtobGetolerant.9*Syntax?:tolerate="tolerate"*Example:?tolerate*TheWtoleratecommandwasintroGducedtoallowF*unnelWebW(i.e.thefwcommand)tobGetestedin*aUUscriptunderconditionswhichwouldnormallycauseittoabGortthescript.hM*3.15.7.21bCT race *The tracecommandturnsonoro commandtracingduringscriptexecution.LBydefault,Ntracing*isUUturnedo .*Syntax :?trace="trace"[s("on"|"off")]*Examples:?traceon_-trace?off*TheUUtracecommandwasintroGducedtoassistinthedebuggingofregressiontestscripts.hM*3.15.7.22bCW rite *Thex*writecommandacceptsadouble-quotedargumentandwritesitfollowedbyanEOLx!tothe*console04(standardoutput).dThereisnoneedtodoubleanydoublequotesoGccurringwithinthe*string.*Syntax :?write="write"sstring*Examples:?write"Nowabouttostartthenexttest."_-write?"Youdon'tneedto"doubleencloseddoublequotes."*Thewritecommandwasaddedsoastoallowregressiontestingscriptstoinformtheuseroftheir*progress.hM*3.15.7.23bCW riteu *The-writeucommandisidenticaltothewritecommandexceptthatitunderlinesthetextonan*additionalUUfollowingoutputline.*Syntax :?writeu="writeu"sstring*Examples:?writeu"Test6"&{ۍ*3.16XConcludingRemarks~P*Thischapterde nesthesemanticsoftheF*unnelWebprogram.PzAsstatedatthestartofthis*chapter,nRthis6 doGcumenttakesprecedenceovertheF*unnelWebprogram.'Whilethede nitionof*F*unnelWebinthischapterisreasonablysolid,.itisfarfromwatertight,.anditishopGedthatitcan*bGetightenedfurtherinfutureversions.SHAllconstructivecriticismwillbGegratefullyreceivedbythe*authorUURossWilliams(ross@spam.adelaide.edu.au).K$100ev`)<;Ġݻ,*JChapterF47獑*HFunnelWeb Installation9獑*ThisUUchapterdescribGeshowtoobtain,compile,andinstallF*unnelWeb.qYouUUwillneed:w9CFTPUUaccesstotheinternetoraF*unnelWebUUdistributionkitondisk.荍9CAaSun,yVMSVAX,b?Macintosh,orPCaorlotsofextratimetopGortF*unnelWebb?toanew Cplatform.9CAbGoutzfourmegabytesoffreediskspace.Y*oumightbGeabletoinstallitwithless,BbutfourCmegabytesissafe.ThedistributionkititselfisabGouttwoandahalfmegabytes.IfyouareCshortonspace,4youcanthrowawayeverythingafterinstallationexceptthebinaryexecutableCwhichUUwillconsumeabGouthalfamegabyte.9CAUUCcompiler.9CAnacquaintancewiththeCprogramminglanguageandtheabilitytocompileandlinkCCprogramsUUonyourmachine.9CElementaryUUsystemsprogrammingknowledegeforyourmachine.9CAbGoutUUanhour.w*Y*ou;pwillnotneedanysortofsystemprivilegestoinstallFunnelWeb,@unlessyouwanttheF*unnel-*W*ebUUcommandfwtobGeautomaticallyavqailabletoeveryoneonyourmachineaswellasyourself.&qh*4.1PfObtainingaCop=yofFunnelWebw*TheUUsimplestwayUUtoobtainacopyofF*unnelWebUUisbyanonymousFTPfrom::mMachine:?sirius.itd.adelaide.edu.au[IP=129.127.40.3].:mDirectory?:~pub/funnelweb/(oradirectoryofsimilarname).*It,isnotclearatthetimeofwritingwhetherF*unnelWeb,willbGepresentedasa\.tar" le,blor*asىadirectorytree,orbGoth.bJustsni aroundanduseyourcommonsense.TwopGointsdeserve*attentionUUhowever:61.CBe`LsuretousethetexttransfermoGdewheneveryoutransferrawF*unnelWeb`L les.However,CyouUUshouldusebinarymoGdeforT*AR lesandotherconglomeraterepresentations.荍62.CIf5youhavetotransferthe lesindividually*,;don'tlumpalltheFunnelWeb lesintoasingleCdirectory*.ReferrmtothesectionsthatfollowforinformationonthedirectorytreeyoushouldCcreateUUtoreceivetheF*unnelWebUU les.K$101f۠)<;Ġݻ_"E*If1anonymousFTP1isnotavqailabletoyou,9contacttheauthorforup-to-dateinformationonother *channelsUUofdistribution.u:mName: Dr?RossN.Williams:mEmail:?ross@spam.adelaide.edu.au:mSnail:?16LerwickAvenue,HazelwoodPark5066,Australia.'2*4.2PfEstablishingTheDirectoryTreeۆ*AtSthisstage,wewillassumethatyouhavesomehowobtainedasetof lesthataresuppGosedto*bGe F*unnelWeb,andthattheyaresittingonadiskonthemachineonwhichyouwishtocompile*andUUinstallF*unnelWeb.k*The+ rstthingyouhavetodoistomakesurethattheF*unnelWeb+directorytreehasbGeencorrectly*unpacked.qTheUUdirectorytreeshouldloGoklikethis.u:mfwdir$-?RootFunnelWebdirectory.J-admin-?Administrativefiles.J-answers -?Answerstotestsuite.J-hackman -?FunnelWebHacker'sManual.J-results -?Fortestresults.J-scripts -?Testscripts.J-sources -?Sourcecode.J-tests-?Testsuite.J-userman -?FunnelWebUser'sManual.*The0followingsectionsdescribGethecontentsofeachdirectoryinalphabGeticalorder.Checkthe*contentstomakesurethatyouhaveeverything.DonotbGecomefussedifyourcon gurationis*not=quiteasspGeci edasitisveryeasyforinstallationguidessuchasthisonetogooutofdateas*minorlastminutechangesandupGdatesaremadetothedistributionkit.GCheckthesourcefrom*whichUUyouobtainedthekit,andifitisdi erenttoGo,proceed.!*4.2.1SAdminDirectoryi*The,admindirectorycontainsadministrative lestodowithlicensingandsuch.d?Itisalsoacatch-*alldirectoryfor lesthatdon'tbGelonganywhereelse.IAtthetimeofwriting,itisnotclearexactly*whatUUwillbGeintheadmindirectory*.qWhynottakealoGok?*4.2.2SAnswersDirectoryi*TheAanswersdirectorycontainsthe\correctanswers"toalltheregressiontestinginput les.ZThe*regressionUUtestscriptscomparethese lestothe lesgeneratedintheresultsdirectory*.u*an01.lis?...an04.lis*ex01.lis?...ex16.lis*ex01.out?...ex10.out*ex11.tex?...ex16.tex*generate.lis*hi01.lis?...hi10.lis*hi01.out?...hi05.out*hi06a.out*hi06b.out*hi07a.outK$102g=)<;Ġݻ_"E*hi07b.out *hi08.out?...hi10.out*pr01.lis?...pr10.lis*sc01.lis?...sc29.lis*tg01.lis?...tg09.lis*tg01.out?...tg09.out*wv01.lis?...wv06.lis*wv01.tex?...wv06.tex"*4.2.3SHackmanDirectoryύ*TheUUhackmandirectorycontainsthe.tex lesthatmakeuptheF;unnelWebHacker'sManual.M*h_ch0.tex?-?Preface,etc.*h_ch1.tex?-?Design.*h_ch2.tex?-?Implementation.*h_ch3.tex?-?Modification.*h_ch4.tex?-?Future.*h_cha.tex?-?Appendices.*h_manual.tex -?MainTeXfile.*SeeM#thecommentatthetopofhEff&fǫmanual.tex leforinstructionsonhowtotypGesetandprintthe*F;unnelWebHacker'sManual. *ThereisnoneedtoreadorprinttheF;unnelWeb/Hacker'sManualunlessyouintendtomoGdify*F*unnelWeb."*4.2.4SResultsDirectoryύ*Theresultsdirectoryexistsasatargetdirectoryfortheoutput lesgeneratedbyF*unnelWeb*during3Tregressiontesting.fqThisdirectoryisdistributedemptyandshouldbGeemptyatthestartof*regressiontesting.&However,itispGermissiblefortheresultsdirectorytocontain lesgenerated*during aprevioustestrun,:astheregressiontestingscriptsdeletespGeci cunwanted lesbefore*eachUUtestanyway*."*4.2.5SScriptsDirectoryύ*ThescriptsdirectorystorestheF*unnelWebcommandshellscriptsthatareusedtopGerform*regressionUUtesting.*master.fws-?Themastertestscript.Thisistheoneyourun.*test_gen.fws -?Scripttogeneratecertaintrickyinputfiles.*test_l.fws-?TestFunnelWebwith+L.*test_ld.fws-?TestFunnelWebwith+L+B...*test_lo.fws-?TestFunnelWebwith+L+O.*test_lo2.fws -?TestFunnelWebwith+L+O(twooutputfiles).*test_lot.fws -?TestFunnelWebwith+L+O+T.*test_lt.fws-?TestFunnelWebwith+L+T."*4.2.6SSourcesDirectoryύ*TheOsourcesdirectorycontainsalloftheCOrsource lesrequiredtobuildaF*unnelWebObinary*executable.qInUUthefollowinglist, lesgivenwithoutanextensionrepresentbGoth.cand.h les.K$103h)<;Ġݻ_"E*analyse$-?Theanalyser. *as>-?Assertions.*clock/?-?Aclockabstraction.*command$-?Theshellcommandinterpreter.*data4-?Shareddatastructuresandglobalvariables.*dump4-?Functionstodumpinternaldatastructures.*environ.h?-?Lightweightmachine-dependent,program-independentheader.*help4-?Moduletowriteouthelpmessages.*help_gnu-?FunctiontowriteouttheGNUlicense.*help_gnu.txt -?TheGNUlicenseintextform.*help_gnu.ctx -?TheGNUlicenseinCcodeform.*list4-?Alistabstraction.*lister)-?Moduletomanagethelistingfile.*machin)-?Moduletoholdmachine-dependent,program-dependentstuff.*main.c)-?Themain()program.*mapper)-?Moduletoreadfilesintomemory.*memory)-?Memorymanagement.*misc4-?Miscellaneousfunctions.*option)-?Commandlineoptionprocessing.*parser)-?Theparser.*scanner$-?Thescanner.*section$-?Asectionnumberabstraction.*style.h$-?Amachine-independent,program-independentheaderfile.*table/?-?Atableabstraction.*tangle)-?Thetangler.*texhead$-?ModuletowriteoutTeXheaderindocumentationfiles.*texhead.ctx-?TheTeXheaderinCcodeform.*texhead.tex-?TheTeXheaderinTeXform.*weave/?-?Theweaver.*writfile-?Outputabstraction.Z*The\.txt", Cand\.tex" lesdonotparticipateinthecompilation,butareconsideredpartofthe*sourceɊcoGdeastheywereusedtogeneratethe\.ctx" les.eThe\.ctx" lesareincludedby.c* lesUUofthesamename.qTheydonotneedtobGecompiledthemselves.!%R*4.2.7STestsDirectoryݷ*Thetestsdirectorystoresalltheinput lesoftheregressiontestsuite.UThesecomeintwokinds:*F*unnelWebinput leswithextensionsof\.fw",andF*unnelWebinclude leswithextensionsof*\.fwi".Z*FunnelWeb?InputFiles::man01.fw?...an04.fw-Analysertests.:mex01.fw?...ex16.fw-Examplesfromthetutorialinusermanual.:mgenerate.fw>-?Generatesafewothertrickyinputfiles.:mhi01.fw?...hi10.fw-Examplesfromthehintschapterinusermanual.:mpr01.fw?...pr10.fw-Parsertests.:msc01_note.fw9-?Anoteexplainingabsenceofsc01.fw:msc02.fw?...sc29.fw-Scannertests.:mtg01.fw?...tg09.fw-Tanglertests.:mwv01.fw?...wv06.fw-Weavertests.*FunnelWeb?IncludeFiles::mex09a.fwi:msc13a.fwi?...sc13f.fwi:msc15a.fwiK$104i8)<;Ġݻ_"E:mtg08a.fwi!K*4.2.8SUsermanDirectory*TheUUusermandirectorycontainsthe.tex lesthatmakeuptheF;unnelWebUser'sManual.KЍ*u_ch0.tex?-?Preface,etc. *u_ch1.tex?-?Tutorial.*u_ch2.tex?-?Hints.*u_ch3.tex?-?Definition.*u_ch4.tex?-?Installation.*u_ch5.tex?-?Administration.*u_cha.tex?-?Appendices.*u_manual.tex -?MainTeXfile.*SeeM#thecommentatthetopofuEff&fǫmanual.tex leforinstructionsonhowtotypGesetandprintthe*F;unnelWebUser'sManual.&_|*4.3PfCompilingFunnelWebj{*TheF*unnelWebsourcecoGdeisentirelycontainedwithinthesourcesdirectory*.However,3some*simpleUUscript lesandmake lescanbGefoundintheadmindirectory*.`*F*unnelWebcontainssomemachine-depGendentcompGonents,(JsobGeforecompilingF*unnelWeb,you*needtospGecifyyourmachineinthesource leenviron.h.WT*odothis,sedittheenviron.h leand*setUUexactlyoneofthemachinename#definesto1.qF*orexample,ontheSunyoushouldset:*#define?MAC0*#define?SUN1*#define?VMS0*#define?PC 0*TherePshouldbGelittledicultycompilingF*unnelWebPforanyoftheseplatforms.Ifthemachine*onwhichyouarecompilingF*unnelWebisnotoneoftheoneslistedintheenviron.h le,%then*choGosetheclosestoneyoucan.T*rytheSUN{ifyouarerunninganon-SunUnix.Ifyouruninto*seriousfdiculties,jyouwillhavetocustomizemachin.handmachin.cforyourmachine.Seethe*commentsUUinthese lesforinstructionsonhowtodothis.`*OnceWiyouhavespGeci edatargetmachine,WcompileF*unnelWebWibypGointingyourCcompileratall*the\.c" lesinthesourcesdirectory*.aThe\.txt",$and\.tex" lesdonotparticipateinthe*compilation,ebutbappGearinthesourcesdirectorybecausetheywereusedtogeneratethe\.ctx"* les.The=\.ctx" lesareincludedby.c lesofthesamenameanddonotneedtobGecompiled*separately*.qLinkUUtheresults.*The0resultofallthisshouldbGeabinaryexecutablecalledfw,8orfw.exe,orfw.xxxwhere.xxxis*whatevero leextensionisappropriateonthetargetmachine.Cleanupthesourcesdirectoryby*deletingUUallthelistingandob8ject les.&_|*4.4PfTestingFunnelWebj{*Onceyouhaveobtainedabinaryexecutable,θyoushouldtestF*unnelWebbGeforemakingitavqailable*toUUusers.qT*odothis:Kύ61.CSetUUthedefaultdirectorytobGethescriptsdirectory*.K$105j)<;Ġݻ_"E62.CCopy.theF*unnelWeb.executableintothescriptsdirectory(orbGeabletoinvokeitfromthe CscriptsUUdirectory).첍63.CEdit+_thescriptmaster.fws.LoGcatethesectioncalled\De neSymbolF*ortheRootT*estCDirectory"andde netheRsymbGoltopointtotheF*unnelWebrootdirectoryfwdir.!TheCexamplesUUinthecommentsinthescriptshouldmakeitclearwhatisrequired.64.CInvokeUUF*unnelWebtoexecutethemastertestscriptwiththecommandlinefw?+xmasterp*The˹master.fwsscriptshouldrunforafewminutes.IfallgoGeswell,Ryouwill ndadi erences*repGort]onyourscreenreportingzerodi erences.RIfthishappens,thenF*unnelWeb]hasbeenfully*testedoandisreadytobGemadeavqailabletousers.Y*oushoulddeleteallthe lesintheresults*directoryUUandproGceedtothenextsectiononinstallingF*unnelWebUUforusers.첍*If?therewereoneormoredi erences,youcaneithergiveupandcontacttheauthor,orattemptto* xbthecoGdeyourself.Ifyoudecideto xthecoGdeyourself,startwiththedi erenceslog leand*followUUyournose.qGoGodluck!&&*4.5PfInstallingFunnelWeb͍*At thisstageyoushouldhaveafwdirdirectorytreesomewhereinyour lesystem.Itscontents*should8bGealmostidenticaltothedirectorycontentsspGeci edearlierinthischapterexceptthere*shouldUUnowbGeanadditionalbinaryexecutable lesittinginthescriptsdirectory*.첍*T*oUUmakeFunnelWebavqailabletousers,youshould:p61.CMakeUUtheentiredirectorytreereadabletoallusers.62.CMovejthebinaryexecutablefromthescriptsdirectorytotheadmindirectoryorcopyittoCsomewhereUUconvenientsuchasa/bindirectory*.63.CSetupasymbGol,Dpath,orcommandofsomekindbythenameoffwthat\pGoints"totheCbinary9executable.TIfpGossible,rsetthisupsothatthefwsymbolisavqailabletoallusers.CAlternatively*,`you^caninforminterestedusersofhowtheycanaddacommandtotheirCloginUUcommand letomakethecommandavqailabletothem.p*Ifeyouareshortofdiskspaceorhaveasystemthatisstressedinsomeotherway*, )itmaybGeof*assistancetoyoutoknowthatF*unnelWebhasbGeenconstructedsothatitsbinaryexecutableis*totally{$selfc}'ontained.hThe:jbinaryexecutabledoGesnotrelyonanyother lestooperate.hNordoes*it*careabGoutitspositioninthe lesystem.cInfact,3HallthatisreallyrequiredtouseF*unnelWeb*is*thebinaryexecutableandtheF;unnelWeb&User'sManual.JJThus,ifyouareshortofdiskspace,you*can1movethebinaryexecutabletoyour\/bin"directoryanddeletetheentireF*unnelWebtree.*However,UUmakingthetreeavqailabletousersisencouragedbGecause:p9CItUUallowsuserstocopythetreeandinstallitonanothermachinewithoutbGotheringyou.9CItallowsusersaccesstotheTU>'ExXcoGdefortheF;unnelWeb?User'sManualandtheFunnelWebCHacker'sManual.9CItallowsusersaccesstotheregressiontestsuite.UXThismaynotseemimpGortant,butitcouldCbGeveryconvenientfortheuserastheex*andhi* lesoftheregressiontestsuitecontainCmostoftheexamplesfromtheF;unnelWebUser'sManual.BymakingthemavqailableyouCwillUUsaveusersthetroubleoftypingthemin.p*Finally*,3you0should llinandsendo aFunnelWebregistrationform.XThisallowsmetogeta*handle onthesizeandneedsoftheuserbase,CandyoutobGekeptinformedofnewF*unnelWeb*releasesUU(optional).qSeeSection5.4formoreinformation.K$106k)<;Ġݻ_"E*4.6PfPrin=tingManuals*F*unnelWeb.comeswithtwo.manuals,aF;unnelWebUser'sManualandaF;unnelWebHacker's *Manual.InstructionsОforhowtotypGesetandprintthesemanualsappGearatthetopofthemain*TU>'ExXUU lesforthesemanualsuEff&fǫmanual.texandhEff&fmanual.tex.*ThereisnoneedtoprinttheF;unnelWebHacker'sManualunlessyouintendtomoGdifyF*unnelWeb.*However,5=you-7shouldmakeafewcopiesoftheF;unnelWebnUser'sManual-7avqailableforusers,5=orat*leastgletthemknowwheretheTU>'ExXgsourcefortheF;unnelWebUser'sManualgiskeptsothatthey*canUUtypGesetandprintitthemselves.'č*4.7PfInstallationProblems?*IfyourunintoanyproblemsinstallingF*unnelWeb,pleasewriteashortrepGortdescribingthe*problemandmailittotheauthorRossWilliams(ross@spam.adelaide.edu.au).ImaynotbGe*able2tohelpyouwithitimmediately*,jbutI"certainlywanttoknowthataproblemexistssothat*itUUcanbGecorrectedinfuturereleasesofF*unnelWeb.K$107lݠ)<;ĠݻK$108mr)<;Ġݻt*JChapterF58b/*HFunnelWeb Administration@b/*5.1PfIn=trouductions*WhetherxacomputerprogramisusefuldepGendsnotjustonthefunctionalityprovidedbythe *program,but-alsoonthetotalityofthecultureandservicessurroundingitsuchaslicensecosts,*thefqualityofdoGcumentation,presenceofastandardandsoon.Thischapteraddressesthese*issuesUUfromauserpGerspective.(GQ*5.2PfTheUser'sCommitmen=tToFunnelWeb*OneoftheproblemsthatmightpreventpGotentialusersfromusingF*unnelWebisthelevelof*commitmentthatitrequires.jAssoGonastheuserstartscreatingF*unnelWeb.fw les,'theuser*bGecomes8dependentontheF*unnelWebprogram,>masthe lessocreatedwillbGecomeunmanageable*ifhtheF*unnelWebhprogramweretobGecomeunavqailableforsomereason.XThereareanumbGerof*wayszinwhichcomputerprogramscanbGecomeunavqailable,PincludingopGeratingsystemupgrades,*copyright'problems,dinabilityto xbugs,dorjusttheinabilityoftheprogramtobGeportedtoanew*targetUUplatform.b/*The&mfactisthatF*unnelWeb&mde nesaninputlanguageandthatcurrentlythereisonlyoneim-*plementationofthelanguage.Userswillonlywriteprogramsusingthatlanguageiftheyfeel*comfortableUUabGouttheavqailabilityUUofitsimplementation.*IhavebGeencriticallyawareoftheseissuesthroughoutthedevelopmentofF*unnelWebandhave*takenAreverypGossiblesteptomakeF*unnelWebasolidbaseontowhichtobuildprograms.6The*followingUUpGointsdescribGetheactionsIhavetaken.G!GNUKlicense:UF*unnelWeb'sCsourcecoGdehasbeenreleasedunderGNUGeneralG!PublicLicenseV*ersion2._ThismeansthatthesourcecoGdetoFunnelWebwillalwaysG!bGeavqailabletoanyonewhowantsit.XTheF*unnelWebprogramcanneverbGetakenG!awayUUfromyou.G!P9ortability:F*unnelWeb VhasbGeendesignedandwrittentobeextremelyportable.G!First, allF*unnelWebreallydoGesisreadandwritetext les.EThismakesiteasytoG!makelvpGortable.$(Second, F*unnelWebiswrittenintheCl;programminglanguage[ANSI]G!with(pGortabilityasama8jordesigngoal.AThird,F*unnelWeb(hasalreadybeenportedG!to4CfourpGopularplatforms:a>SunOS,VAX4:VMS,PC,andMacintoshanditshouldnotG!provehardtomoveittoothers.F*ourth,&FunnelWebcomeswithahugeautomatedG!regressionlItestsuite.ThismakesiteasytopinpGointproblemswhenitismovedtoaG!new (platform.YPortabilityisimpGortantbGecause,evenifyouarenotusingF*unnelWebG!onsomefunnyplatform,!youmaywanttosendacomputerprogramwrittenusingG!F*unnelWebUUtosomeonewhodoGes.K$109n)<;Ġݻ_"EG!Qualit9y:TheF*unnelWebsourcecoGdeishighqualitycode.E)Althoughithasnot G!bGeenǡformallydevelopedunderanyparticularcodingstandard,itiswelldesignedandG!doGcumented.qDesignUUdecisionshavenotbGeentakenlightly*.bG!DoQcumen9tation:F*unnelWebiswelldoGcumentedbythismanualandbytheF;un-G!nelWebVHacker'sManual.This)GisimpGortantbecauseitmeansthatifyouwanttoG!sendBsomeoneaprogramwrittenusingF*unnelWeb,FyouBcansimplypGointthemtothisG!manualratherthanhavingtoexplainitallyourself..ItisalsocomfortingformanagersG!whoearecontrollingsourcecoGdetoknowthattheformatinwhichthesourcecoGdeisG!writtenUUiswell-doGcumented.bG!Standardization:[Users)whocreatesource lesusingF*unnelWeb)arenotonlycom-G!mitting,totheF*unnelWeb,program;theyarealsoinvesting,intheF*unnelWeb,lan-G!guage.LIf@F*unnelWeb'slanguagechangesradicallyforsomereason,{thenthisinvest-G!mentbyuserswillbGeundermined. xT*oprotectthisinvestment,IintendtomaintainG!anb\ocial"versionofF*unnelWebbwhoselanguagewillnotchangeradically*,eatleastG!notUUinanonbackwardUUcompatiblemanner.*ItismyhopGethatthecombinationofthesefactorswillalleviateanyfearsthatusersmayhave*abGoutUUcommittingtheirsource lestoF*unnelWeb.'N*5.3PfDoucumen=tationՍ*TheUUfollowingF*unnelWebUUdoGcumentationisavqailable:0u?"FunnelWeb?User'sManual":Tutorial,Hints,ReferenceManual.?"FunnelWeb?Hacker'sManual":NotesonDesignandImplementation.*Everyone'qinvolvedwithF*unnelWebshouldreadtheF;unnelWebiUser'sManual.b{Itcontainsevery-*thingUUyouneedtoknowabGouthowtouseF*unnelWeb.qInUUfact,youarereadingitnow!b*The(IF;unnelWebUHacker'sManualisforthosewhowanttoinstall,]moGdify*, x, ddlewith,and*generallyUUhacktheF*unnelWebUUCsourcecoGde.*BothgofthesemanualsareshippGedwiththeF*unnelWebgdistributionkit,andshouldbeavqailable*onyourmachineintheformofLaT*eXtext les.!Ifyoucannot ndthem,youcanobtainthem*fromUUtheF*unnelWebUUFTParchiveUU(seeSection5.11).'N*5.4PfRegistrationՍ*If?|youinstalloruseF*unnelWeb,Cplease?|registerby llinginandreturningtheregistrationformin*FigureT4.qF*eelUUfreetoexpandtheformifthereisnotenoughroGom.*Email/&theformtoross@spam.adelaide.edu.au,eorsnailmailittoRossWilliams,16Lerwick*Avenue,LHazelwoGod Park5066,Australia.8Y*oumaywishtomakeacontributionwhenyouregister.*SeeUUSection5.5formoreinformation.'N*5.5PfSuppuortՍ*F*unnelWebP%isreleased\asis"underaGNUP$license,Q/andnoformalsuppGortisavqailable.p Y*ouhave*therighttomakechangestoF*unnelWebandtousethemoGdi edversionscreatedbyrandom*programmers.qHowever,UUthisisdiscouraged(seeSection5.9).*In=factthesuppGortthatismostneededisyour nancialsupportfortheF*unnelWeb=developers!*Ithastakenmonthsoffull-timeunp}'aidworktobringF*unnelWebtoyouinitscurrentform.IK$110o>)<;Ġݻ?g9?+----------------------FunnelWeb?RegistrationForm----------------------+ ?|?1.Date:EF|?|t+|?|?2.Titleandname:d|?|t+|?|?3.Internetemailaddress:||?|t+|?|?4.Snailmailaddress:p|?|t+|?|?5.Workphonenumber(country,area,number):|?|t+|?|?6.WhichcategoryofFunnelWebuserbestdescribesyou?N|?|$Latent-?InstalledFunnelWeb,butdon'tintendtouseit.|?|$Beginner -?Haven'tusedFunnelWebmuchyet;haveanopenmind.|?|$Casual-?UseFunnelWeboccasionally.?|?|$Convert-?UseFunnelWebtodomostprogramming.N|?|$Fanatic-?FunnelWebhasbecomeawayoflife.Y?|?|t+|?|?7.WhatchangesornewfeatureswouldyouliketoseeinFunnelWeb?|?|t+|?|t+|?|t+|?|t+|?|t+|?|t+|?|?8.DoyouwanttobekeptinformedofnewFunnelWebdevelopments??|?|t+|?+-----------------------------------------------------------------------+RܸTJohDregisterasaCFJunnelWebuser,please llinthisformandemailittoKross@spam.adelaide.edu.au,orsnailmailCit'[toRossWilliams,;16LerwicÎkAvenue,;HazelwoHowever,thereZaregoodreasonswhyyoushouldavoid*doingUUthis.61.CIf0youdistributemoGdi edversionsofF*unnelWeb,7you0runtheriskofcreatingaversionthatCwillUUdivergefromthe\ocial"versionofF*unnelWebUUthatIintendtomaintain.462.CIfByoureleaseaversionofF*unnelWebBwithachangedinputlanguage,*usersofyourmoGdi edCversionwillcreatesource lesthatwillnolongerworkonotherversionsofF*unnelWeb._TheCresultUUwouldbGechaos.*F*orthesereasonsIƳrequestthatyoudonotdistributemoGdi edversionsofF*unnelWeb,Wparticularly*versionswithamoGdi edlanguage.However,ɌifyoumustdistributeaversionwithamoGdi ed*language,}ple}'asechangeitsnameu(i.e.from\F*unnelWeb"utosomethingelse).PleasealsoalloGcate*anew leextensiontoreplace\.fw"astheextensionforsource leswritteninthemoGdi ed*language.ؚ*F*orUUmoreinformation,refertotheF;unnelWebHacker'sManual.K$113r>)<;Ġݻ_"E*5.10XVersions*F*unnelWebiwas *createdDin1986andwasusedextensivelybyRossWilliams(ross@spam.adelaide.edu.au)for*three.)years.BHowever,d]V*ersion1.0waswritteninAdaandwasnotverypGortable(itwasfairly*VAX/VMSspGeci c).wDavidHulse(dave@cs.adelaide.edu.au)tookthe rststeptowardsare-*lease bytranslatingtheAdacoGdeintoC.RossWilliamsthenextensivelyreworkedtheC mcoGde,*makingUUitrobustandpGortable,addingnewfeatures,andpolishingittoitscurrentform./Vers LangCreatedReleasedAuthor4CopyrightLicensing/---- -------------------------------------------------------/V1.0 Ada1986?NeverRossWilliamsRoss?Williams/V2.0 C?1989NeverDavid?HulsePublicdomain Norestriction./V3.0 C?1992May-1992RossWilliamsRoss?WilliamsGNUrelease.*ThisUUmanualwasreleasedfor:D*?FunnelWeb$V3.0.D*?User'sManualV1.0.D*?Hacker'sManualV1.0.D*?TeXDefinitionsV1.0.'č*5.11XFTPArc=hiveandAuthor*TheUUF*unnelWebFTParchiveis::mMachine:?sirius.itd.adelaide.edu.au[IP=129.127.40.3].:mDirectory?:~pub/funnelweb/(oradirectoryofsimilarname).*TheUUauthorofF*unnelWebUUandthismanualis::mName: Dr?RossN.Williams:mEmail:?ross@spam.adelaide.edu.au:mSnail:?16LerwickAvenue,HazelwoodPark5066,Australia.*I*intendZtomaintainan\ocial"versionofF*unnelWebZwhichI*willreleaseunderGNUlicensefrom*timeetotime.!Ie[amhappytoreceiveconstructivecriticismabGoutF*unnelWebeanditsdocumentation.*I>:will>@alwaysbGehappytoreceivemailabGoutF*unnelWeb,BbutcannotguaranteethatI>:willbGeable*toUUreplytoitimmediately*.K$114s)<;ĠݻYA*JAppendixFA86*HGlossary:6*Analyser:UA compGonentoftheF*unnelWebprogramthatchecksthemacrotablecreatedbythe *parserUforerrors.rEF*orexample,UtheanalyserchecksUtoseeifanymacrowithouta@ZhasnotbGeen*called.6*Argumen9t:&AstringdelimitedbyblanksappGearingontheF*unnelWebcommandline.?Arguments*areUUusedtocontroloptions.*Directiv9e:AtF*unnelWebtspGecialsequenceorcooperatinggroupofspecialsequencesthatdonot*formUUpartofamacrode nition.qAdirectivecantaketheformofapragma.*DoQcumen9tation:qDescriptiveUUtext.*DoQcumen9tation? le:]AnKYoutput le,proGducedbytheW*eavecompGonentofF*unnelWeb,that*containsWtypGesettercommands.ykWhenfedintotheappropriatetypGesetterprogram,Xtheresultisa*typGesetUUimageoftheinput le.*F reeYtext:TheOtextinaninput lethatremainsifoneweretoremovemacrode nitionsand*directives.*F unnelWeb:ThiswordhasanumbGerofdi erentmeaningsallpGertainingtotheF*unnelWeb*systemofprogramming.X1)Theentiresystemofprogrammingasin\MaybGeF*unnelWebcan*help."d2)4Thecomputerprogramthatimplementsthesystemasin\RunitthroughF*unnelWeb*andVseewhatcomesout."H3)ThelanguageimplementedbytheF*unnelWebVprogramasin\I7wrote*theUUprograminF*unnelWeb."qorUU\IwrotetheprograminAdausingF*unnelWeb.".*F unnelWebT le:qAUU lewhosecontentsUUarewrittenintheF*unnelWebUUlanguage.*F unnelWebTlanguage:qTheUUlanguageinwhichF*unnelWebUUinput lesarewritten.*F unnelWebpropQer:TUsually*,H-whenFunnelWebisinvoked,H-itproGcessesasingleinput leand*thenL'terminates.nHowever,MitalsohasacommandlanguagemoGdeinwhichitispGossibletoinvoke*\F*unnelWeb"umanytimes.zThisleadstoconfusionbGetween\F*unnelWeb"utheouterprogramand*\F*unnelWeb"theinnerprogram.eT*oavoidthisconfusion,theinnerFunnelWebissometimes*referredUUtoas\F*unnelWebUUpropGer".*FW:UUAnabbreviationfor\F*unnelWeb"UUthatisusedwhereverappropriate.*IncludeT le:qAUU lereadinbyF*unnelWebUUastheresultofanincludepragma(@i?filename).*Input@ le:,Any lereadinbyF*unnelWeb. Thephrase\theinput le"referstotheroGotinput* leUU(spGeci edusingthe+Foption).*Journal le:An\output lecontainingacopyoftheoutputsenttotheuser'sconsoleduringan*invoGcationUUofF*unnelWeb.qInUUothersystems,this leissometimescalleda\log le".*ListingT le:qAnUUoutput lesummarizingtheresultofproGcessinganinput le.*Macro:qAUUbindingofanametoastring.K$115t)<;Ġݻ_"E*MacroZde nition:<)AconstructappGearinginaF*unnelWeb lethatbindsanametoatextstring. *AUUF*unnelWeb leconsistsofaseriesofmacrode nitionssurroundedbydoGcumentarytext.*MappQer:O{AcompGonentoftheF*unnelWebprogramthatreadsintheinput leandcreatesacopy*ofUUitinmemory*.*Option:_#An0 parameterinternaltotheF*unnelWeb0 programwhichcanbGecontrolledbycommand*lineUUargumentsorpragmas.*Output? le:*Any lewrittenbyF*unnelWeb.$Thisincludeslisting,journal,proGduct,anddocu-*mentation les.L(W*arning:HDuringmostofFunnelWeb'sdevelopmenttheterm\output le"was*alsousedtorefertowhatarenowcalled\proGduct les".4Thisturnedouttobeextremelyconfusing*and-`sotheterm\proGduct le"wasinventedtodistinguishthegenericfromthespGeci c.dvHowever,*asUUthiswasalatemoGdi cation,youmay ndsomeoGccurrencesoftheolduseof\output le".).*P9arser:cAcompGonent#oftheF*unnelWeb#programthatprocessesthetokenlistgeneratedbythe*scannereandproGducesamacrotableandadocumentlist.Theparsermainlyanalysestheinput* leUUatthesyntacticlevel,butalsodoGessomelightweightsemanticcheckingtoGo.*Pragma:>>Single-lineCdirectivesthatappGearsinF*unnelWebC les.OlPragmascontroleverythingfrom*maximumUUinputlinelengthtotypGesetterdependence.qApragmalinestartswith\@p".*Prin9ted5+doQcumentation:լSheetsGofpapGerresultingfromactuallytypesettingandprintinga*doGcumentationUU le.*ProQduct le:Anoutput le,7generatedbytheT*anglecompGonentofF*unnelWeb,7thatcontainsthe*expansionk6ofthemacrosintheinput le.kNote:Othernamesconsideredforthiswere:generated* le,UUexpanded le,result le,program le,andtangle le.*Scanner:dwA:compGonent:oftheF*unnelWeb:programthatscansacopyoftheinput leinmemory*andgpgeneratesalinelistandatokenlisttobGefedtotheparser.Thescannerprocessestheinput*atUUthelexicallevel.*Script:qAUU lecontainingF*unnelWebUUshellcommands.*Shell:pAycommandlanguageinterpreterbuiltintotheF*unnelWebprogram.5Theinterpreterallows*theFTusertoinvokeFTF*unnelWebpropGermanytimesduringasingleinvoGcationoftheF*unnelWeb*program.*SpQecialfLc9haracter:AAdistinguishedcharacterinaF*unnelWebinput lethatintroGducesaspecial*sequence.YByMadefaultthespGecialcharacteris\@".However,ditMacanbGechangedusingthe\@="*spGecialUUsequence.*SpQecialysequence:JAspGecialsequenceisaconstructintroducedbythespecialcharacter.WCSpecial*sequencesvNareusedtode neastructureinaF*unnelWebvNinput lethatexistsatahigherlevelto*the*surroundingtext.\A*F*unnelWeb*input lemaybGeconsideredtobeasequenceoftextand*spGecialUUsequences.*T angle:;This5isthenameforthecompGonentofF*unnelWeb5thatgeneratesoneormoreproduct* lesUUcontainingtheexpansionofmacrosintheinput le.*T9ypQesetting-directive:5AF*unnelWebdirectivewhosesolee ectistomoGdifythewayinwhich*theUUinput leisrepresentedinthedoGcumentation le.*W ea9ve:nThisisthenameforthecompGonentofF*unnelWebthatgeneratesadocumentation le*containingUUtypGesettingcommandsrepresentingtheinput le.K$116u%)<;Ġݻ"E*JAppendixFB8*HReferences:*[ANSI]AustralianStandardAS3955-1991,J*\ProgrammingLanguages|C",(ISBN:0-7262- *6970-0),S*12 fJuly1991.Identicalto:InternationalStandardISO/IEC 29899:1990Programming*LanguagesUU|C.*[ANZE]̺\Australia,NewZealandEncyclopGedia",Entry:`\F*unnel-webspiders",V*ol7,pp.564{*565,UUBayBoGoks,Sydney*,(ISBN:85835{127{7),1975.*[BSI82])BritishStandardsInstitute,\SpGeci cationforComputerProgrammingLanguagePascal",*PublicationBS6192:1982,9BritishStandardsInstitute,P*.O.Box372,MiltonKeynes,MK146LO,*1982.*[Gries81]MAGriesD.,\TheScienceofProgramming",Springer-V*erlag,(ISBN:0-387-90641-X),1981.*[Humphries91]HumphriesB,\NeglectedPoGemsandOtherCreatures",AngusandRobertson,*Sydney*,UU(ISBN:0-207-17212-9),1991.*[Kernighan88]5KernighanB.W.,>RitchieD.M.,\TheCProgrammingLanguage",(secondedi-*tion,\ANSIUUC"),PrenticeHall,(ISBN:0-13-110362-8),1988.*[Kn9uth83]KnuthD.E.,\TheWEBSystemofStructuredDoGcumentation",(W*ebUserManual,*V*ersionUU2.5,NovembGer,UU1983),StanfordUniversity,UU1983.*[Kn9uth84]UUKnuthD.E.,\TheTU>'ExXbGook",UUAddison-W*esley,(ISBN:0-201-13448-9),1984.*[Kn9uth84]8KnuthD.E.,>Q\LiterateProgramming",TheypComputerJournal,V*ol.827,No.2,pp.97-*111,UU1984.qNote:TheauthorofthismanualhasnotyetobtainedthispapGer.*[LampQort86]LampGortL., \LffUIaTU>ExX:ADocumentPreparationSystem", Addison-W*esley,(ISBN:*0-201-15790-X),UU1986.*[Roso9vsky90]RosovskyH.,\TheUniversity:AnOwner'sManual",W.W.Norton&Company*,*Inc.,UU(ISBN:0-393-02782-1),1990.*[Smith91]fESmithL.M.C.,\AnAnnotatedBibliographyofLiterateProgramming",ACMeSIG-*PLANUUNotices,V*ol.26,No.1,January1991.*[Strunk79](StrunkW.,1WhiteE.B.,\TheElementsofStyle",1ThirdEdition,MacMillanPublish-*ingUUCompany*,NewYork,(ISBN:0-02-418200-1),1979.*[USDOD83]os\TheProgrammingLanguageAdaReferenceManual",AmericanNationalStan-*dardsUUInstituteInc,ANSI/MIL-STD-1815A-1983,1983.K$117v5)<;Ġݻia*HIndexSia*+=UUtutorial26 *+=UU85*2167AUU51*==UUtutorial26*==UU85*@!UU37*@!UU75*@"UU29*@(UU29*@)UU29*@+UU20*@+UU76*@,UU29*@-UU23*@-UU77*@1...UU28*@1...UU86*@<UU20*@=UU20*@>UU20*@A...UU34*@bracesUU20*@bracesUU37*@circum exUU74*@dollarUU22*@hashUU76*@iUU30*@iUU77*@MUUtutorial24*@MUU85*@OUU20*@OUU22*@slashUU37*@ZUUtutorial24*@ZUU85*absentUUcommand93*abstractUUdatatypGe55*abstractionUUcoGde56*abstractionUUdata26*abstractionUUset59*abuseUUcomments57*accessUUrandom50*acknowledgementsUU11*actionUUexecutionorder71*ActionUUoptions70*actualUUparameters29*AdaUU11*AdaUU44ia'AdaUU49 'AdaUU51'AdaUU55'additiveUUmacros26'additiveUUmacro26'additivelyUUde ned85'AdelaideUUUniversity59'adminUUdirectory102'administrationUUF*unnelWeb109'ADTUU55'aliasUU49'AnalyserUU115'analyserUU65'analyserUU88'analysisUUstatic88'AndrewUUT*revorrow13'animalUUpGoem30'annualUUrepGort58'anonymousUUftp101'ANSIUU109'ANSIUU117'answersUUcorrect102'answersUUdirectory102'ANZEUU117'ANZEUU19'applicationsUUF*unnelWeb53'arbitraryUUcharactersinsertingintotext74'architectureUUsemantic64'archiveUUftp114'archiveUUF*unnelWeb114'argumentUUcommandline67'argumentsUU67'ArgumentUU115'assertionUUseverity65'assertionUUstatus90'AtraxUUrobustus19'attributesUUmacro85'authorUUcontacting114'BUUoption68'BarryUUDwyer11'BarryUUDwyer59'BarryUUHumphries19'BASICUU57'BeggUUJeremy11'bindingUUproblems57'bindingsUUmacro22'blankUUindentation78'blankUUindentation78K$118w@+)<;Ġݻ_"E*blanksUUtrailing42 *bGoringUUorganization50*BrissendenUURoger11*BSI82UU117*BSI82UU15*BSI82UU18*CUUheader57*CUUoption68*CUUpreproGcessor20*CUUpreproGcessor57*callsUUmacro86*callsUUnumbGer23*cameraUUpGoem30*caseUUdepGendence67*changingUUspGecialcharacter31*charactersUUcontrol42*charactersUUnon-printable96*charactersUUunprintable71*checksUUmacro88*cheerUUhacker's35*cheerUUprogrammer's35*coGdeUUabstraction56*coGdeUUexplaining17*coGdeUUgardening53*coGdeUUvsdocumentation32*coGdifyUUcommand93*commandUUabsent93*commandUUcoGdify93*commandUUcompare93*commandUUde ne91*commandUUde ne94*commandUUdi summary95*commandUUdi zero95*commandUUdi 94*commandUUeneo95*commandUUexecute96*commandUUexists96*commandUU xeols96*commandUUfw97*commandUUhelp97*commandUUhere98*commandUUinterpreter47*commandUUlength91*commandUUlineargument67*commandUUlineinterface66*commandUUlineoptionssyntax67*commandUUlineparsing66*commandUUlineproGcessing66*commandUUlineproGcessing92*commandUUlinesyntax67*commandUUoptions92*commandUUquit98*commandUUset48*commandUUset98*commandUUshellF*unnelWebUU90*commandUUshow48*commandUUshow98_"E'commandUUskipto98 'commandUUstatus99'commandUUtolerate100'commandUUtraceon48'commandUUtrace100'commandUUverbfw66'commandUUwriteu100'commandUUwrite100'commandsUUF*unnelWeb90'commandsUUshell93'commandsUUuseful47'commentsUUabuse57'commentsUUeliminating57'commentsUUF*unnelWeb75'commentsUU37'commitmentUUF*unnelWeb109'compareUUcommand93'compilersUUF*ortran42'compilingUUF*unnelWeb105'completeUUexample38'conditionalsUUfudging44'consoleUUoutputsuppress69'constructsUUsection83'contactingUUauthor114'contentsUUtableof81'contextUUin nite68'contextUUlisting le68'contextUU69'controlUUcharactersinsertingintotext74'controlUUcharacters42'controllabilityUU18'copyrightUUF*unnelWeb112'copyrightUUnotice1'correctUUanswers102'crossUUreferencenumbGeringUU89'crossUUreferencing17'crossUUreferencing89'crypticUUtext les55'DUUoption49'DUUoption68'dangersUUF*unnelWeb50'dataUUabstraction26'DavidUUHulse11'debuggerUU53'debuggingUUwholistic53'defaultUUoptions49'defaultUUoptions92'defaultUUspGecialcharacter72'de neUUcommand91'de neUUcommand94'de nitionUUF*unnelWeb63'de nitionUUmacro85'de nitionUUmacro87'deleteUUoutput les49'deleteUUoutputoption68'delimitingUUmacroparameter87'depGendenceUUcase67K$119xI)<;Ġݻ_"E*depGendenciesUU le49 *developmentUUtime17*diagnosticsUUlevelsof65*diagnosticsUU65*dictionaryUUhacker's35*di UUcommand94*di erencesUU le94*di summaryUUcommand95*di zeroUUcommand95*directiveUUemphasis85*directiveUUliteral84*directiveUUnewpage37*directiveUUtableofcontents37*directiveUUtitle37*directiveUUvskip37*directivesUUtypGesetter81*directivesUU32*directivesUU83*DirectiveUU115*directoryUUadmin102*directoryUUanswers102*directoryUUhackman103*directoryUUresults103*directoryUUscripts103*directoryUUsources103*directoryUUtests104*directoryUUtree102*directoryUUuserman105*directoryUU70*DistributionUUF*unnelWeb113*doGcumentUUlistdump68*doGcumentUUlist64*doGcumentationUUduplicate51*doGcumentationUUexamples58*DoGcumentationUU le115*doGcumentationUU le18*doGcumentationUUF*unnelWeb110*doGcumentationUUinterdependentUU50*doGcumentationUUover51*doGcumentationUUpavlov51*doGcumentationUUvscode32*DoGcumentationUU115*doGcumentationUU64*DOD83UU55*DonaldUUKnuth11*DonaldUUKnuth50*DonaldUUKnuth9*dumpUUdoGcumentlist68*dumpUUgloballinelist68*dumpUUmacrotable68*dumpUUmappGed le68*dumpUUoption68*dumpUUtimes68*dumpUUtokenlist68*duplicateUUdoGcumentation51*DwyerUUBarry11*DwyerUUBarry59_"E'EBNFUUsyntax63 'editorsUUtext42'EdnaUUEverage19'eciencyUUF*unnelWeb47'eciencyUUnotes47'eliminatingUUcomments57'emphasisUUconstruct37'emphasisUUdirective85'emptyUUname42'end-of-lineUU ddlingwith43'eneoUUcommand95'EOLUU ddlingwith43'EOLUUmarkersinserting76'EOLUUmarkerssuppressing77'EOLUUsuppression23'errorUUseverity65'errorUUstatus90'errorsUUshell90'EverageUUEdna19'exampleUUapplicationsF*unnelWebUU53'exampleUUcomplete38'exampleUU lenameinheritance70'ExampleUUF*unnelWeb38'examplesUUdoGcumentation58'executableUUF*unnelWeb106'executeUUcommand96'executeUUscriptoption69'executionUUphases64'existsUUcommand96'expansionUUmacro30'expansionUUmacro47'expansionUUmacro87'explainingUUcoGde17'expressionsUUmacro86'expressionUU85'extensionUU70'FUUoption68'fatalUUseverity65'fatalUUstatus90' ddlingUUwithend-of-line43' ddlingUUwithEOL43' eldsUU lename70' leUUdepGendencies49' leUUdi erences94' leUUinclude69' leUUjournal69' leUUlisting69' leUUsuppression49' leUUtermination71' leUUtypGeset69' lenameUU elds70' lenameUUinheritanceexample70' lenameUUinheritance70' lesUUheader57' lesUUinclude30' lesUUinclude77' lesUUinput47K$120yX^)<;Ġݻ_"E* xeolsUUcommand96 *fontUUsize46*formalUUparameterlists86*formalUUparameters28*formalUUparameters28*formalUUparameters87*F*ortranUUcompilers42*F*reeUUtext115*freeUUtext32*F*reeUUtext83*freeUUtext83*freestandingUUtypGesetterdirectives83*freestandingUU81*ftpUUanonymous101*ftpUUarchive114*fudgingUUconditionals44*fudgingUUgenerics59*functionsUUsmall56*F*unnel-webUUspider19*F*unnelWebUUadministration109*F*unnelWebUUapplications53*F*unnelWebUUarchive114*F*unnelWebUUcommandshell90*F*unnelWebUUcommandshell90*F*unnelWebUUcommands90*F*unnelWebUUcomments75*F*unnelWebUUcommitment109*F*unnelWebUUcompiling105*F*unnelWebUUcopyright112*F*unnelWebUUdangers50*F*unnelWebUUde nition63*F*unnelWebUUDistribution113*F*unnelWebUUdoGcumentation110*F*unnelWebUUeciency47*F*unnelWebUUexampleapplications53*F*unnelWebUUExample38*F*unnelWebUUexecutable106*F*unnelWebUU le115*F*unnelWebUU le64*F*unnelWebUUhints41*F*unnelWebUUinitialization70*F*unnelWebUUinstallation101*F*unnelWebUUinstalling106*F*unnelWebUUinvoking66*F*unnelWebUUlanguage115*F*unnelWebUUlicense112*F*unnelWebUUmartinet42*F*unnelWebUUname19*F*unnelWebUUobtaining101*F*unnelWebUUoverview18*F*unnelWebUUoverview64*F*unnelWebUUpitfalls50*F*unnelWebUUprogram65*F*unnelWebUUpropGer115*F*unnelWebUUpropGer48*F*unnelWebUUpropGer65*F*unnelWebUUregistration110_"E'F*unnelWebUUrules42 'F*unnelWebUUrunning66'F*unnelWebUUshell90'F*unnelWebUUstartup70'F*unnelWebUUsuppGort110'F*unnelWebUUtesting105'F*unnelWebUUtwomainaspGects21'F*unnelWebUUversions114'F*unnelWebUU115'fwUUcommandverb66'fwUUcommand97'fwinit.fwsUU49'fwinit.fwsUU71'FWUU115'gardeningUUcoGde53'genericsUUfudging59'genericsUUtypGesafe61'globalUUlinelistdump68'glossaryUU115'GNUUUlicense112'GNUUUlicense18'GNUUUlicense9'goGodUUolddays57'Gries81UU117'Gries81UU51'HUUoption68'hacker'sUUcheer35'hacker'sUUdictionary35'HackettUUSimon11'hackmanUUdirectory103'headerUUC57'headerUU lepGostscript54'headerUU les57'headerUUpage37'headingsUUsection34'headingsUUstrength46'HelloUUNorthernHemisphereProgram21'helloUUworlddoGcument20'helpUUcommand97'helpUUoption68'hereUUcommand98'hierarchicalUUstructure34'highUUlevelsyntax82'hintsUUF*unnelWeb41'HulseUUDavid11'HumphriesUUBarry19'Humphries91UU117'Humphries91UU19'hypGertextUU15'IUUoption69'identi ersUUmacro41'includeUU leoption69'includeUU lesrecursive31'includeUU les30'includeUU les77'includeUU les77'IncludeUU le115K$121zf)<;Ġݻ_"E*includeUU le69 *indentationUUblank78*indentationUUmacrocalls25*indentationUUmacroexpansion78*indentationUUnone78*indepGendenceUUlanguage18*indepGendenceUUtypesetter18*indepGendenceUUtypesetter34*indepGendenceUUtypesetter65*indepGendenceUUtypesetter80*in niteUUcontext68*inheritanceUU lename70*inheritanceUUsectionname35*initializationUUF*unnelWeb70*initializationUUscript49*initializationUUscript71*inlineUUtypGesetterdirectives83*inlineUU81*inputUU leoption68*inputUU les47*InputUU le115*inputUU le18*inputUU le64*inputUU le77*inputUUlinelengthmaximum79*inputUUlinelengthpragma79*inputUUlinelength42*inputUUlinelength79*insertingUUEOLmarkers76*insertingUUintotextarbitrarycharacters74*insertingUUintotextcontrolcharacters74*insertingUUintotextspGecialcharacter74*installationUUF*unnelWeb101*installationUUproblems107*installingUUF*unnelWeb106*interactiveUUmoGde47*interactiveUUoption69*interdepGendentUUdocumentationUU50*interfaceUUcommandline66*interpreterUUcommand47*introGductionUUtutorial19*invisibleUUpragmas78*invoGcationUUnumberUU23*invoGcationsUUnumberUU42*invokingUUF*unnelWeb20*invokingUUF*unnelWeb66*JUUoption69*JeremyUUBegg11*journalUU leoption69*JournalUU le115*journalUU le64*journalUU le69*KUUoption69*Kernighan88UU117*Kernighan88UU65*keybGoardUUmode47*keybGoardUUoption69_"E'KnuthUUDonald11 'KnuthUUDonald50'KnuthUUDonald9'Knuth83UU117'Knuth83UU17'Knuth83UU25'Knuth83UU25'Knuth83UU9'Knuth84UU117'Knuth84UU117'Knuth84UU13'Knuth84UU17'Knuth84UU18'LUUoption69'LampGort86UU117'LampGort86UU13'languageUUindepGendence18'languagesUUmultiple55'laserUUprinter55'LaT*eXUU13'LaT*eXUU84'layoutUUprogram22'layoutUUprogram28'lengthUUcommand91'lengthUUinputline42'lengthUUline71'lengthUUoutputline42'letterUU67'levelsUUofdiagnostics65'librariesUUmacro31'licenseUUF*unnelWeb112'licenseUUGNU112'licenseUUGNU18'licenseUUGNU9'lineUUlengthinput79'lineUUlength71'lineUUtermination71'listUUdoGcument64'listUUoptions68'listUUshellcommands93'listingUU lecontext68'listingUU leoption69'ListingUU le115'listingUU le64'listingUU le69'literalUUconstruct37'literalUUdirective84'literateUUprogrammingtoGols15'literateUUprogramming,facilities15'literateprogramming,mostsigni cantbGene- 9' tUU17'literateUUprogramming15'literateUUprogramming15'literateUUprogramming50'MacDrawUU54'MacintoshUU13'MacintoshUU54K$122{v )<;Ġݻ_"E*macroUUattributes85 *macroUUbindings22*macroUUbGody85*macroUUcallsindentation25*macroUUcalls86*macroUUchecks88*macroUUde nitions32*MacroUUde nition116*macroUUde nition85*macroUUde nition87*macroUUexpansionindentation78*macroUUexpansion30*macroUUexpansion47*macroUUexpansion87*macroUUexpressions86*macroUUfacilitiestutorial22*macroUUidenti ers41*macroUUlibraries31*macroUUnames41*macroUUnames86*macroUUname85*macroUUparameterdelimiting87*macroUUrecursion43*macroUUrecursion88*macroUUtabledump68*macroUUtable64*macrosUUadditive26*macrosUUparameterized28*macrosUUsimpletutorial22*macrosUUstatic87*MacroUU115*magicUUtrick15*maintenanceUUprogrammer50*makeUUutility49*manualsUUprinting107*mappGedUU ledump68*MappGerUU116*mappGerUU71*martinetUUF*unnelWeb42*maximumUUinputlinelength79*maximumUUoutput lelinelengthpragma79*maximumUUoutput lelinelength79*maximumUUproGduct lelinelengthpragma79*maximumUUproGduct lelinelength79*medicineUUwholistic53*memoryUUuseof30*memoryUU47*MIL-STD-2167AUU51*monsterUU lepGostscript54*multipleUUlanguages55*nameUUempty42*nameUUF*unnelWeb19*nameUUsection34*nameUUsection84*namesUUmacro41*namesUUmacro86*namesUUquick42_"E'namesUUquick76 'namesUUsection86'namesUU86'nameUU70'newUUpagepragma81'newUUpage81'newpageUUdirective37'noUUindentation78'non-determinismUU68'non-printableUUcharacters96'noneUUindentation78'notationUU63'notesUUeciency47'noticeUUcopyright1'novelsUU50'numbGerUUcalls23'numbGerUUinvocationsUU42'numbGerUUinvocationUU23'numbGerUUoftimescalled23'numbGeringUUcrossreference89'numbGeringUUsection89'ob8jectUUcoGde26'obtainingUUF*unnelWeb101'opGenUUsystems55'optionUUB68'optionUUC68'optionUUdeleteoutput68'optionUUdump68'optionUUD49'optionUUD68'optionUUexecutescript69'optionUUF68'optionUUhelp68'optionUUH68'optionUUinclude le69'optionUUinput le68'optionUUinteractive69'optionUUI69'optionUUjournal le69'optionUUJ69'optionUUkeybGoard69'optionUUK69'optionUUlisting le69'optionUUL69'optionUUquiet69'optionUUQ69'optionUUscreen69'optionUUS69'optionUUtypGeset69'optionUUT69'optionUUwidth69'optionUUW69'optionUUX69'optionsUUcommand92'optionsUUdefault49'optionsUUdefault92'optionsUUlist68K$123|)<;Ġݻ_"E*optionsUUsettingdefaults49 *optionsUUsyntax67*optionsUUtracedump68*optionsUU67*optionsUU68*OptionUU116*orderUUactionexecution71*orderUUprogram22*orderingUUprogram15*OrdinaryUUoptions70*organizationUUbGoring50*organizationUUspaghetti50*outputUU lelinelengthmaximum79*outputUU lesdelete49*outputUU les18*outputUU les64*OutputUU le116*outputUUlinelength42*outputUUWEB25*overUUdoGcumentation51*overheadUUproGcedurecall57*overviewUUF*unnelWeb18*overviewUUF*unnelWeb64*overviewUUtypGesetting32*OzT*eXUU13*packqageUU55*parameterUUlist,absent29*parameterUUlistsformal86*parameterizedUUmacros28*parametersUUactual29*parametersUUformal28*parametersUUformal28*parametersUUformal87*ParserUU116*parserUU64*parserUU82*parsingUUcommandline66*PascalUU15*PascalUU25*PascalUU26*PascalUU57*PascalUU59*PatUUScannel29*pavlovUUdoGcumentation51*phasesUUexecution64*phasesUU64*PhDUUthesis54*pitfallsUUF*unnelWeb50*pGoemUUanimal30*pGoemUUcamera30*pGortabilityUU18*pGostscriptUUheader le54*pGostscriptUUmonster le54*PostScriptUU54*pGostscriptUU57*pragmaUUinputlinelength79*pragmaUUmaximumoutput lelinelength79_"E'pragmaUUmaximumproGduct lelinelength79 'pragmaUUnewpage81'pragmaUUtableofcontentsUU81'pragmaUUtitle82'pragmaUUtypGesetter80'pragmaUUvskip81'pragmasUUinvisible78'pragmasUUvisible78'pragmasUU78'PragmaUU116'pragmaUU25'pragmaUU78'prefaceUU9'preproGcessorUUC20'preproGcessorUUC57'presentationUUnotes13'PrintedUUdoGcumentation116'printerUUlaser55'printingUUmanuals107'printingUUsystem55'problemsUUbinding57'problemsUUinstallation107'proGcedureUUcalloverheadUU57'proGcessingUUcommandline66'proGcessingUUcommandline92'proGductUU lelinelengthmaximum79'proGductUU lewidth69'proGductUU les18'proGductUU les64'ProGductUU le116'proGductionUUtool19'programUUlayout22'programUUlayout28'programUUordering15'programUUorder22'programmerUUmaintenance50'programmer'sUUcheer35'programmingUUliterate50'QUUoption69'quickUUnames42'quickUUnames76'quickUUname42'quickUUname76'quietUUoption69'quitUUcommand98'randomUUaccess50'rec.humor.funnyUU29'recursionUUmacro43'recursionUUmacro88'recursiveUUinclude les31'referencesUU117'referencingUUcross89'registrationUUF*unnelWeb110'regressionUUtesting103'regressionUUtesting47'reliabilityUU18'REMUUstatement57K$124}^)<;Ġݻ_"E*repGortUUannual58 *resultsUUdirectory103*returnUUstatus65*RogerUUBrissenden11*Rosovsky90UU117*Rosovsky90UU17*RossUUWilliams1*ruleUUsimple20*rulesUUF*unnelWeb42*runningUUF*unnelWeb66*SUUoption69*ScannelUUPat29*ScannerUU116*scannerUU64*scannerUU71*screenUUoption69*scriptUUinitialization49*scriptUUinitialization71*scriptUUstartup49*scriptsUUdirectory103*ScriptUU116*sectionUUconstructs83*sectionUUheadings34*sectionUUnameinheritance35*sectionUUnames86*sectionUUname34*sectionUUname84*sectionUUnumbGering89*sectionUUstrength46*semanticUUarchitecture64*sequencesUUspGecial72*setUUabstraction59*setUUcommand48*setUUcommand98*settingUUdefaultsoptions49*settingUUspGecialcharacter74*severeUUseverity65*severeUUstatus90*severityUUassertion65*severityUUerror65*severityUUfatal65*severityUUsevere65*severityUUwarning65*severityUU65*sharingUUinformation56*sharingUUtext58*sharkUUwhitepGointer19*shellUUcommandslist93*shellUUcommands93*shellUUerrors90*shellUUF*unnelWeb90*shellUUuses90*ShellUU116*shoGotingUU31*showUUcommand48*showUUcommand98*signUU67_"E'SimonUUHackett11 'simpleUUmacrostutorial22'simpleUUrule20'simpleUUsequence72'simplicityUU18'sizeUUfont46'skipUUvertical81'skiptoUUcommand98'smallUUfunctions56'Smith91UU117'Smith91UU17'snakeUUtiger19'songUU29'sourcesUUdirectory103'spacingUU43'spaghettiUUorganization50'spGecialUUcharacterchanging31'spGecialUUcharacterdefault72'spGecialUUcharacterinsertingintotext74'spGecialUUcharactersetting74'SpGecialUUcharacter116'spGecialUUcharacter20'spGecialUUcharacter72'spGecialUUsequences72'SpGecialUUsequence116'spGecialUUsequence20'spGecialUUsequence72'spGecialUUtokens82'spGeedUU47'spiderUUF*unnel-web19'startupUUF*unnelWeb70'startupUUscript49'statementUUREM57'staticUUanalysis88'staticUUmacros87'statusUUassertion90'statusUUcommand99'statusUUerror90'statusUUfatal90'statusUUreturn65'statusUUsevere90'statusUUsuccess90'statusUUwarning90'streamUUofconsciousness50'strengthUUheadings46'strengthUUsection46'strengthUUtypGesetting46'stringUUsubstitution91'stringUUsubstitution94'stringUU67'structureUUhierarchical34'structureUUtree83'Strunk79UU117'Strunk79UU51'substitutionUUstring91'substitutionUUstring94'successUUstatus90K$125~)<;Ġݻ_"E*suppGortUUF*unnelWeb110 *suppressUUconsoleoutput69*suppressingUUEOLmarkers77*suppressionUUEOL23*suppressionUU le49*SydneyUU19*syntaxUUcommandlineoptions67*syntaxUUcommandline67*syntaxUUEBNF63*syntaxUUhighlevel82*syntaxUUoptions67*systemUUprinting55*TUUoption69*tableUUmacro64*tableUUofcontentsUUdirective37*tableUUofcontentsUUpragma81*tableUUofcontentsUU81*tabsUU42*T*angleUU116*tangleUU65*tangleUU88*T*anglingUU21*targetUUtypGesetter89*terminationUU le71*terminationUUline71*terminologyUU63*testingUUF*unnelWeb105*testingUUregression103*testingUUregression47*testsUUdirectory104*textUUeditors42*textUU lescryptic55*textUUfree83*textUUsharing58*textUUtokens82*T*eXUU13*T*eXUU18*T*eXUU22*T*eXUU54*thesisUUPhD54*tigerUUsnake19*timeUUdevelopment17*timesUUdump68*titleUUdirective37*titleUUpragma82*titleUU82*tokenUUlistdump68*tolerateUUcommand100*toGolsUUliterateprogramming15*traceUUcommand100*traceUUoncommand48*tracedumpUUoptions68*trailingUUblanks42*treeUUdirectory102*treeUUstructure83*T*revorrowUUAndrew13*tutorialUU+=26_"E'tutorialUU==26 'tutorialUU@M24'tutorialUU@Z24'tutorialUUintroGduction19'tutorialUUmacrofacilities22'tutorialUUmacrossimple22'tutorialUUsimplemacros22'tutorialUUtypGesetting32'tutorialUU15'tutorialUU19'twelveUUbugsofchristmas29'twoUUmainaspGectsF*unnelWebUU21'typGesafeUUgenerics61'typGesetUU le69'typGesetUUoption69'typGesetterUUdirectivetokens82'typGesetterUUdirectives66'typGesetterUUdirectives81'typGesetterUUindependence18'typGesetterUUindependence34'typGesetterUUindependence65'typGesetterUUindependence80'typGesetterUUindependentUU34'typGesetterUUpragma80'typGesetterUUtarget89'TypGesettingUUdirective116'typGesettingUUoverview32'typGesettingUUstrength46'typGesettingUUtutorial32'typGesettingUU13'typGesettingUU89'universitiesUU17'UniversityUUAdelaide59'UnixUUnewline75'UnixUU67'unprintableUUcharacters71'USDOD83UU117'useUUofmemory30'usefulUUcommands47'usermanUUdirectory105'usesUUshell90'versionsUUF*unnelWeb114'verticalUUskip81'visibleUUpragmas78'vskipUUdirective37'vskipUUpragma81'WUUoption69'warningUUseverity65'warningUUstatus90'warrantyUU112'W*eaveUU116'weaveUU65'weaveUU89'W*eavingUU21'WEBUUoutput25'WEBUU21'WEBUU25K$126I)<;Ġݻ_"E*W*ebUU9 *whiteUUpGointershark19*wholisticUUdebugging53*wholisticUUdebugging53*wholisticUUmedicine53*widthUUoption69*widthUUproGduct le69*WilliamsUURoss1*workstationsUU48*workstationUU90*writeUUcommand100*writeuUUcommand100*XUUoption69K$127v;)<xpL2@cmbx8KCscmtt8J"Vp cmbx10I- cmcsc10H"VG cmbx10BK`yG cmr109DtGGcmr177"Vff cmbx104K`yff cmr100N cmbx12 cmmi10K`y cmr10#fcmti82cmmi8 |{Ycmr8ٓRcmr7Aacmr6A