1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284 |
- ." $Header$
- .LL 6.5i
- .MS T E
- \!.TL `\\n(S1``PUBMAC user's guide`
- .ME
- .MS T O
- \!.TL `PUBMAC user's guide``\\n(S1`
- .ME
- .MS B E
- \!.TL '%'''
- .ME
- .MS B O
- \!.TL '''%'
- .ME
- .SM S1 B S
- .IN 5
- .N
- .AD R
- Report no. 4
- .N
- second revision
- .N
- .AD B
- .N 10
- .CS
- .SS 14
- .BS
- PUBMAC
- .BE
- .N 1
- .US
- .SS 12
- A Set of NROFF/TROFF-Macros
- to Format Publications
- .UE
- .N 1
- User's Guide
- .N 2
- Third, revised edition
- March 1980
- .N 11
- .SS 10
- Katholieke Universiteit Nijmegen
- Informatics Department
- Nijmegen, The Netherlands.
- .CE
- .N 8
- .U ABSTRACT
- .N 1
- A set of NROFF/TROFF macros is presented, intended to facilitate the
- formatting of a paper for publication purposes.
- Predefined macros are supplied for the most frequent activities.
- Sectioning, section-numbering, construction
- of a table of contents and some other important
- facilities are automated.
- .S1 Introduction
- The UNIX text formatting program NROFF/TROFF
- .RS "NROFF/TROFF"
- J.F. Ossanna, NROFF/TROFF User's Manual, Bell Laboratories, Murray Hill,
- New Jersey
- .RE
- allows the user to define his own commands via a macro mechanism.
- The present paper describes PUBMAC, a set of macros for a set
- of very often repeated activities encountered in the text formatting
- process for a paper to be published.
- .P
- These activities comprise e.g. the division of a paper into
- sections, the automatic generation of a table of contents, footnote
- handling etc.
- PUBMAC is intended to simplify the user-interface of NROFF/TROFF in such a way
- that it is suitable for use by personnel with little formal training
- and no special talent for informatics.
- The macro set described in this Guide is designed
- by Thijs Zoethout
- after the
- .RS PUBMAC
- H.M. Stahl, PUBMAC User's Guide, Report no.4 revised, Informatica Department,
- Nijmegen University
- .RE
- macro set written by Hans-Michael Stahl for a previous version of NROFF.
- The set was later adapted for use on a high-quality laser printer
- allowing use of the full range of
- .U troff's
- capabilities
- by E. G. Keizer.
- .N
- The construction of the macro set was influenced by the SYSPUB macro
- set developed for SCRIPT at the University of Waterloo and described
- in
- .RS "SYSP77" "."
- SYSPUB User's Guide, University of Waterloo Computing Centre,
- 1977
- .RE
- .P
- However, in contrast to SCRIPT, NROFF/TROFF only allows two characters as name for commands,
- so that it is quite difficult to select mnemonic command names.
- We tried our best to make full use of the expressive power
- of two characters...
- .P
- PUBMAC can be obtained from the author.
- Prerequisites for its use are:
- .PS
- .PT
- a machine with the UNIX operating system,
- with NROFF or TROFF,
- .PT
- an output device e.g. a daisywheel printer or laser printer.
- .PE
- .S2 Invoking PUBMAC
- calling NROFF/TROFF with the option
- .B -mkun,
- e.g.
- .DS I 6
- .BS
- \&troff -mkun file....
- .BE
- .DE
- The reader who desires to make use of further options may consult
- [NROFF/TROFF].
- Output from the preprocessors
- .UW tbl ,
- .U eqn
- and
- .U refer
- is recognized by PUBMAC.
- .N 1
- The commands needed to print the formatted text differ between
- installations.
- .S2 PUBMAC Input
- As for NROFF/TROFF, each line of
- the input files for PUBMAC either contains text to be formatted
- or is a command line.
- A command line begins with a control
- character (under PUBMAC ".") followed by the name of a
- PUBMAC command or of a NROFF/TROFF request.
- Command lines which do not contain a known PUBMAC or NROFF/TROFF
- command are ignored without complaints.
- .S2 Form of the PUBMAC commands
- All PUBMAC commands have a name consisting of one or two capital letters
- or a capital letter followed by a digit.
- Most commands embedding some text, i.e. a start and an end command,
- have a capital
- .B S
- (for start) and a capital
- .B E
- (for end)
- as second letter to gain at least a bit of systematics.
- .P
- Some commands may have operands; these have to be enclosed
- in double quotes ("), if they contain blanks.
- The number of operands is restricted to 9, but operands can
- be grouped into one operand by enclosing them in double quotes.
- .P
- Operands may be optional; this is indicated in the description by surrounding the
- operand by square brackets (\ [\ and\ ]\ ).
- A sequence of one or more operands is indicated by
- one operand followed by ellipses, e.g
- .B title... .
- .S2 NROFF/TROFF Commands under PUBMAC
- As PUBMAC does a lot of administration, NROFF/TROFF commands changing
- global values (e.g. linelength, current indentation) nearly
- always disturb this administration.
- Therefore it is recommended not to use NROFF/TROFF commands
- if not stated otherwise.
- Also, a NROFF/TROFF command can be renamed and thus not available
- any more under the old name.
- .N
- The renamed commands are:
- .DS I
- .TS 0
- l l s
- l l l.
- PUBMAC NROFF/TROFF
- \&.PO .po set page offset
- \&.TL .tl define title line
- .TE 0
- .DE
- .S2 PUBMAC Output
- Input text to PUBMAC is subject to two formatting processes:
- filling and adjusting.
- Filling means that output lines are about equally filled
- within the current line length;
- it is achieved
- by taking words from input lines as long until
- a complete output line is formed.
- A word, in the context of formatting, is any text
- surrounded by blanks.
- Adjusting means that all output lines are adjusted
- to some uniformity.
- This is achieved by expanding the blank spaces between
- output words as necessary or leaving one or both margins ragged.
- .P
- Under PUBMAC normally filling and adjusting
- are switched on by default, but both may be turned off separately
- (within certain limits).
- .N 5
- .U Acknowledgement
- .N
- I wish to thank all PUBMAC users,
- for their help in finding
- errors, and their proposals for correcting them.
- .S1 Global Structure
- This section describes the basic PUBMAC commands necessary to
- divide a paper into sections, paragraphs etc.
- If you are using PUBMAC for the first
- time, you are recommended to experiment with the commands described
- herein on a small document.
- .DS I
- .TS 0
- l l.
- \&.RP select report layout
- \&.S1 to create first level sections
- \&.S2 to create second-level sections
- \&.S3 to create third-level sections
- \&.S4 to create fourth-level sections
- \&.AP to start an appendix
- \&.SN to set the start value for section numbers
- \&.P to start a paragraph
- \&.A to start an alinea
- \&.PS to start a list of points
- \&.PT to start a point
- \&.PE to end a list of points
- .TE 0
- .DE
- .S2 Selecting a Layout
- PUBMAC offers two kinds of layout:
- .PS
- .PT
- the
- .U report layout
- which is suited for short papers and technical notes.
- .PT
- the
- .U manual layout
- which is thought for larger publications
- .FS * .
- This PUBMAC user's guide is an example of the
- manual layout.
- .FE
- .PE
- When the manual layout is selected, the first page is reserved
- as a title page and not counted for page numbering purposes,
- no headers and footers are printed on it,
- and new sections appear on a new page.
- .A
- For the report layout no title page is reserved, thus the
- output text immediately starts on the first page.
- A new section is not forced to appear on a new page.
- .A
- The manual layout is selected by default;
- to select the report layout, use the command
- .DS I 6
- .BS
- \&.RP
- .BE
- .DE
- .UW ( R e P ort).
- This command has to appear in the input text before the first
- .B .S1
- (see below).
- .S2 Sections
- PUBMAC offers commands
- to divide a paper into sections and subsections.
- Sections are numbered automatically and their
- numbers, titles and page numbers are collected for the table of contents
- which can be put out at the end of the report.
- .P
- To start a new section, use the command
- .DS I 6
- .BS
- \&.S1 title...
- .BE
- .DE
- where
- .B title...
- is the title of the section.
- If the manual report is selected, the section will appear on a new page and the title will be
- translated to capital letters and centered.
- If the report layout is chosen, the title only will be underlined and PUBMAC
- takes care that the title and the first 6 lines of the section
- text
- will appear on the same page.
- The text of a section immediately follows the
- .B .S1
- command.
- .P
- A section may be divided further into subsections, which again
- may be divided further etc, up to the level 4:
- .DS I 6
- .BS
- \&.S2 title...
- \&.S3 title...
- \&.S4 title...
- .BE
- .DE
- All subsections will be numbered automatically and their titles
- collected for the table of contents.
- The title of second-,
- third- and fourth-level subsections will be underlined;
- to make the underlining continuous,
- blanks separating the single words of
- .B title...
- will be translated to underscores.
- PUBMAC takes care, that the title and the first 5 lines of the text
- of subsections
- will appear on the same page.
- .P
- As an example, the next section was prefixed by
- .B .S2
- .BW Appendices .
- .S2 Appendices
- To start an appendix, use the command
- .DS I 6
- .BS
- \&.AP title...
- .BE
- .DE
- .UW ( AP pendix).
- This command acts like
- .B .S1
- with the exception, that appendices are numbered with capital letters instead of
- arabic numbers.
- .P
- To divide an appendix into further sections, use the
- .B .S2, .S3
- and
- .B .S4
- commands as explained above.
- .S2 Setting the Section Numbers
- Sometimes the need is felt to format a large paper not as a
- whole but in parts, especially when the final state
- of the paper has not yet been reached. Nevertheless the parts of
- the paper should contain consecutive section numbers
- and the correct page numbers.
- To achieve this, use the command
- .DS I 6
- .BS
- \&.SN s1 [s2 [s3 [s4 [ap]]]]
- .BE
- .DE
- .UW ( S ection
- .UW N umbers).
- The operands
- .B s1, s2, s3, s4
- determine the start value for the numbering of following sections and subsections.
- The operand
- .B ap
- serves to set the appendix number to the desired start value.
- .P
- To get the full table of contents and a complete
- bibliography list, the paper must be formatted as a whole.
- .S2 Paragraphs
- Two commands are supplied to start a new paragraph.
- They take care, that at least the first two
- lines of a paragraph are not split across a page boundary.
- .P
- To start a new paragraph, use the
- .DS I 6
- .BS
- \&.P [count [indent]]
- .BE
- .DE
- .UW ( P aragraph)
- command. The first line of the paragraph will be indented
- by
- .B indent
- (default is 3) columns and it will be separated from the previous paragraph by
- .B count
- (default is 1) blank line(s).
- .P
- If a paragraph should not be preceded by a blank line, use the command
- .DS I 6
- .BS
- \&.A [count [indent]]
- .BE
- .DE
- .UW ( A linea),
- which has the same effect as
- .B .P
- except that the operand
- .B count
- has the default 0.
- .S2 Lists of Points
- It is often desired to present a number of related items
- as a list of points. The PUBMAC commands
- .B .PS, .PT
- simplify the creation of such list.
- .P
- The command
- .DS I 6
- .BS
- \&.PS [style] [indentation] [ [prefix] suffix ]
- .BE
- .DE
- .UW ( P oint
- list
- .UW S tart)
- starts a list of points.
- The text of each point is indented from the current left margin and
- preceded by a label.
- .P
- .NE 13
- The operand
- .B style
- selects the labeling style of the points following the
- .B .PS
- command.
- The following styles are available:
- .PS
- .PT a:
- the points are labeled with small letters (a,b,..aa,bb,...);
- .PT A:
- the points are labeled with capital letters (A,B,..AA,BB...);
- .PT i:
- the points are labeled with small roman numbers (i,ii,iii...);
- .PT I:
- the points are labeled with capital roman numbers (I,II,III...);
- .PT 1:
- the points are labeled with arabic numbers (1,2,3...);
- .PE
- If
- .B style
- is not any of these then each point is labeled with the operand
- .BW style .
- .A
- The default is
- .DS I 6
- .BS
- \&.PS -
- .BE
- .DE
- The operand
- .B indentation
- determines how many columns from the
- current left margin the text of the points in the list is to be
- indented.
- If this operand is not specified, the default value 3 will be used.
- All operands remain valid for all points in the list.
- .P
- If you want the label selected by
- .B .PS
- to be followed
- by an additional string, for instance for labels as
- .B 1)
- and
- .B 2),
- use
- the operand
- .BW suffix .
- It determines the string to follow
- the point-label selected by
- .BW .PS .
- The default
- .B suffix
- is the empty string "".
- The operand
- .B prefix
- determines the string to be inserted before each point label.
- .P
- To start a point in such a list, use
- .DS I 6
- .BS
- \&.PT [label]
- .BE
- .DE
- .UW ( P oin T ).
- The text of the point has to follow on the next
- input lines.
- The optional operand
- .B label
- allows the replacement of the label selected
- by the
- .B .PS
- command ("-" or numbers as selected by "style")
- for a single point.
- If the text of the label is longer than the indentation selected
- by
- .B .PS,
- the text of the point in the output will appear on a new line.
- .P
- To continue the list of points, simply repeat the
- .B .PT
- command for every new point.
- .P
- A list of points is terminated by the command
- .DS I 6
- .BS
- \&.PE
- .BE
- .DE
- .UW ( P oint
- list
- .UW E nd).
- The command returns to the indentation level being
- actual when the last
- .B .PS
- was encountered by PUBMAC.
- .P
- Lists of points may be nested up to a maximum level of nine.
- A
- .B .PS
- command
- inside the actual list will create a new, nested list of
- points.
- A new numbering style and indentation value
- can be selected for this nested list of points.
- To return to the previous list of points, use the
- .B .PE
- command, which also will restore the old operand values.
- After being returned to the old list, the numbering
- of further points will continue as selected when this list was started.
- .P
- To give an impression how the
- .B .PT
- command can be used, the following example is given. The input text:
- .DS B
- .BS
- \&The .PT command can be used
- \&.PS a 5 )
- \&.PT
- \&to construct a list of points which appear marked and
- \&properly indented in the output file
- \&.PT
- \&to give a summary of information related to one point of view
- \&.PT
- \&to give more detailed information
- \&for a given statement in a top-down way
- \&.PS i 4 [ ]
- \&.PT
- \&this is possible in a nested way
- \&.PT
- \&the maximum level of nesting is nine, which
- \&in general will be enough
- \&.PE 0
- \&.PT
- \&in all respects, the .PT command
- \&is very useful to construct a "structured" paper.
- \&.PE
- \&Here the normal text processing continues on the
- \&indentation level as it was before the first .PT
- \&in this section.
- .BE
- .DE
- produces the following output:
- .N 1
- The .PT command can be used
- .PS a 5 )
- .PT
- to construct a list of points which appear marked and properly
- indented in the output file
- .PT
- to give a summary of information
- related to one point of view
- .PT
- to give more detailed information
- for a given statement in a top-down
- way
- .PS i 4 [ ]
- .PT
- this is possible in a nested way
- .PT
- the maximum level of nesting is nine, which
- in general will be enough
- .PE 0
- .PT
- in all respects, the .PT command
- is very useful to construct a "structured"
- paper.
- .PE
- Here the normal text processing continues on the
- indentation level as it was before the first .PS
- in this section.
- .P
- Another application for points are lists like the
- command summary in appendix B.
- The whole summary is a list of points preceded by
- .B .PS 1 8,
- every item in the list is a point started with
- .B .PT xx,
- where
- .B xx
- is the command name.
- .S1 Local Layout
- Two groups of commands are provided to determine the
- local layout:
- commands working on lines or groups of lines
- (to create empty lines, for indenting, centering, etc),
- and commands working on words (underlining, marking etc).
- .DS I
- .TS 0
- l l.
- \&.N [count] Begin new line, preceded by count blank lines
- \&.BP Begin new page
- \&.IS [count] Start indentating by count columns
- \&.IE End indentation
- \&.UN Undent temporarily
- \&.CS Start centering
- \&.CE End centering
- \&.US Start underlining
- \&.UE End underlining
- \&.BS Start bold type face
- \&.BE End bold type face
- \&.NE [count] Need count lines on the current page
- \&.U word... Underline word...
- \&.CU word... Continuous underline word...
- \&.B word... Bold face word...
- .TE 0
- .DE 0
- .S2 Line Oriented Commands
- The command
- .DS I 6
- .BS
- \&.N [count]
- .BE
- .DE
- .UW ( N ewline)
- starts a new output line,
- preceded by
- .B count
- blank lines.
- If
- .B count
- is omitted, no blank lines are generated but only a new line is begun.
- The command
- .DS I 6
- .BS
- \&.BP
- .BE
- .DE
- .UW ( B egin
- .UW P age)
- causes PUBMAC to put out the current page and start a new one.
- .NE 6
- .P
- The command
- .DS I 6
- .BS
- \&.IS [left indent [right indent [count]]]
- .BE
- .DE
- .UW ( I ndentation
- .UW S tart)
- indents the output by
- .B left indent
- (default is 3) columns at the left margin.
- Indents the output by
- .B right indent
- (default is 0) columns at the right margin,
- after generating
- .B count
- (default 0) blank lines.
- .DS I 6
- .BS
- \&.UN
- .BE
- .DE
- .UW ( UN dent)
- undents the next line temporarily, and the command
- .DS I 6
- .BS
- \&.IE [count]
- .BE
- .DE
- .UW ( I ndentation
- .UW E nd)
- undents the text permanently and
- generates
- .B count
- (default 0) blank lines.
- .P
- Indentations can not be nested.
- All three commands act as a break, i.e. put out a partially filled line.
- .P
- To center a piece of text, use the commands
- .DS I 6
- .BS
- \&.CS [count]
- \&.CE [count]
- .BE
- .DE
- .UW ( C enter
- .UW S tart,
- .UW C enter
- .UW E nd).
- All input lines between the two commands will
- appear centered, line for line without filling, in the output.
- The operand
- .B count
- specifies the number of blank lines preceding and following the centered text
- (default 0).
- Both commands act as a break.
- For instance, the title page of this report was formatted with the
- commands
- .DS I 6
- .BS
- \&.CS
- \&PUBMAC
- \&.N 1
- \&A Set of NROFF/TROFF-Macros
- \&to Format Publications
- \&.N 1
- \&User's Guide
- \&.N 2
- \&Third, revised edition
- \&March 1980
- \&.N 11
- \&.CE
- .BE
- .DE
- .P
- To underline a piece of text, use the commands
- .DS I 6
- .BS
- \&.US [C]
- \&.UE
- .BE
- .DE
- The text between the two commands will appear underlined.
- If no operand is specified, only letters and digits will be underlined and
- filling will take place.
- The optional operand C stands for Continuous underline.
- In this mode all characters and spaces will be underlined,
- no filling will occur.
- .P
- To print a piece of text in boldface, use the commands
- .DS I 6
- .BS
- \&.BS
- \&.BE
- .BE
- .DE
- .UW ( B old
- .UW S tart,
- .UW B old
- .UW E nd).
- The text between the two commands will appear in boldface.
- The result highly depends on the output device.
- In some cases the effect will be nil.
- .P
- Normally an input line starting with the control
- character "." or "\'" is interpreted as a command.
- To consider such lines as normal input,
- precede each of them by "\e&".
- .NE 5
- .P
- To assure that a certain piece of text is not split across a page boundary,
- use the command
- .DS I 6
- .BS
- \&.NE count
- .BE
- .DE
- .UW ( NE ed)
- which has no visible effect if there are still
- .B count
- lines left on the current output page,
- but causes a page eject if not.
- .S2 Word Oriented Commands
- The following commands all take a list of words as operands
- which are subject to a special treatment.
- None of the commands causes a break.
- .P
- To underline a sequence of words, use
- .DS I 6
- .BS
- \&.U word...
- .BE
- .DE
- .UW ( U nderline).
- The letters and digits in the operands
- .B word...
- will appear underlined in the output text.
- The command
- .P
- .DS I 6
- .BS
- \&.CU word....
- .BE
- .DE
- .UW ( C ontinuous
- .UW U nderline)
- will underline
- .U all
- characters,
- including the separating spaces.
- .P
- The command
- .DS I 6
- .BS
- \&.B word...
- .BE
- .DE
- .UW ( B old)
- will print the operands
- .B word...
- in bold face.
- The result highly depends on the output device.
- .S1 Tables, Figures and Formulas
- PUBMAC provides commands which allow the user to
- do his own formatting for figures, examples and so on.
- Another related group of commands allows the user
- to lay special stress on a piece of text.
- For these purposes, the following commands are available:
- .DS I
- .TS 0
- l l.
- \&.DS start a display
- \&.DS M start a marked display
- \&.DS X start a boxed display
- \&.DE end a display
- \&.DB allow breaking of following display
- .TE 0
- .DE
- A
- .U display
- is a text which should be kept together, i.e., if possible,
- should not be split across a page
- boundary, but moved as a whole to the next page
- (however, see
- .B .DB
- below).
- Provisions for several display types are made in PUBMAC.
- To start a display, use
- .DS I 6
- .BS
- \&.DS [mode]
- .BE
- .DE
- .UW ( D isplay
- .UW S tart),
- where
- .B mode
- determines the kind of display.
- To return to normal text processing, invoke the command
- .DS I 6
- .BS
- \&.DE [count]
- .BE
- .DE
- .UW ( D isplay
- .UW E nd).
- Where the operand
- .B count
- specifies the number of blank lines following the display (default 1).
- .N
- All text between both commands is subject to the formatting chosen
- by the operands of the selected display.
- Restrictions in the use of displays are discussed below.
- .S2 Simple Displays
- To start a simple display, use the command
- .DS I 6
- .BS
- \&.DS
- .BE
- .DE
- .UW ( D isplay
- .UW S tart).
- PUBMAC switches to no-format mode
- i.e. input text lines are neither filled nor
- adjusted.
- The user himself has to take care for the formatting, especially that
- the input text does not exceed the current linelength.
- Other PUBMAC commands may be used inside the display to do
- the formatting.
- .S2 Marked and Boxed Displays
- To lay special stress on a display,
- e.g. to achieve more contrast between examples and running text,
- it can be
- .UW M arked
- or
- .UW bo X ed.
- Optional operands specify the distance of the boundary of the display
- from the left and right margin.
- To start this kind of display, use the command
- .DS I 6
- .BS
- \&.DS [mark] M [left-indentation]
- \&.DS [mark] X [left-indentation] [right-indentation]
- .BE
- .DE
- .UW ( D isplay
- .UW S tart
- .UW M arked,
- .UW D isplay
- .UW S tart
- .UW bo X ed)
- The boundary of the display will be
- indented by
- .B left-indentation
- (default 3) columns from the current left margin.
- .N
- In the case of a marked display the left hand boundary of the display
- will be represented by the
- .B mark
- character on each line.
- .N
- In the case of a boxed display the whole boundary of the display will
- be indicated by the
- .B mark
- character.
- The right hand boundary of the display will by indented by
- .B right-indentation
- (default 0) columns from the right margin.
- .N
- For instance, the input text
- .DS I 6
- .BS
- \&.DS M
- \&The marked display can be used
- \&to make programming examples, formulae and similar text
- \&distinguishable from the running text.
- \&.DE
- .BE
- .DE
- produces the output
- .DS M
- .BS
- The marked display can be used
- to make programming examples, formulae and similar text
- distinguishable from the running text.
- .BE
- .DE
- .S2 Inside the display
- Inside simple and marked displays the text will be unformatted,
- that is neither filled nor adjusted.
- Inside boxed displays the text will be formatted.
- .P
- Appending
- .B I
- or
- .B Q
- operands after the before mentioned operands, allows the user
- to control the formatting of the text and specify indentation
- inside the boundary of the display.
- .N
- The possibilities are
- .DS I 6
- .BS
- \&.DS [....] I [left-indentation]
- \&.DS [....] Q [left-indentation] [right-indentation]
- .BE
- .DE
- Use of the Q operand
- .UW ( Q uoted)
- causes
- the text inside the display to be formatted.
- Use of the I operand
- .UW ( I ndent)
- causes
- the text to be unformatted.
- The default for the
- .B left-indentation
- is 3 columns.
- .N
- The default for the
- .B right-indentation
- is
- .BW left-indentation .
- .P
- As an example, the input lines
- .DS
- .BS
- \&This is the sentence preceding the quotation; to start the
- \"ation use the command ".DS Q".
- \&.DS Q 15
- \&This is the quoted material.
- \&Note that it is automatically indented from both margins.
- \&To terminate the quotation, use ".DE"
- \&.DE
- \&This is the first sentence following the quoted text.
- .BE
- .DE
- produce the following output:
- .NE 7
- This is the sentence preceding the quotation; to start the
- quotation use the command ".DS Q".
- .DS Q 15
- This is the quoted material.
- Note that it is automatically indented from both margins.
- To terminate the quotation, use ".DE"
- .DE
- This is the first sentence following the quoted text.
- .P
- The box
- .DS X 10 Q 5
- The text within the box display is subject
- to the normal PUBMAC formatting, but other PUBMAC commands
- can be used to get the desired layout.
- .CS
- Text for instance can appear
- centered
- within a box display
- .CE
- .DE
- was created with the input text:
- .DS I 6
- .BS
- \&.DS X 10 Q 5
- \&The text within a box display is subject
- \&to the normal PUBMAC formatting, but other PUBMAC commands
- \&can be used to get the desired layout.
- \&.CS
- \&Text for instance can appear
- \¢ered
- \&within a box display
- \&.CE
- \&.DE
- .BE
- .DE
- .S2 Breaking up a Display
- Normally a display is moved to the next page, if there is
- not enough space left on the current page to hold it completely.
- Especially when a display is long,
- this can lead to an annoyingly large amount of white paper
- caused by the page eject.
- .NE 5
- The command
- .DS I 6
- .BS
- \&.DB
- .BE
- .DE
- .UW ( D isplay
- .UW B reak
- allowed),
- .B .DS
- allows all following displays to be split if necessary.
- The same effect for one display only,
- can be obtained by appending the operand
- .B B
- to the
- .B .DS
- request.
- .S2 Restrictions with Displays
- .PS
- .PT
- As already mentioned, the user has to take care in unformatted
- displays that the length of the input lines does not exceed
- the current output line length;
- .ig
- especially in multi-column mode too long display text can lead to overprinting
- of columns.
- ..
- .PT
- To prevent ugly output,
- the text of a box display should not be longer than a page.
- .PT
- It is not possible to nest displays.
- .PE
- .S2 Tables
- The program
- .B tbl
- can be used to configure complicated tables.
- A description of how to use it can be found in
- the
- .B tbl
- user's manual.
- .[
- %A M. E. Lesk
- %T T\s-2BL\s0\(emA program to format tables
- %I Bell laboratories
- %C Murray Hill, New Jersey
- .]
- PUBMAC will handle multiple page tables correctly.
- To repeat the table's heading on each page it is necessary to
- surround the heading with
- .B ".TS H
- and
- .BW .TH .
- The
- .B ".TS H
- command replaces the normal
- .B .TS
- command.
- .S2 Formulas
- The program
- .B eqn
- allows you to express formulas in a rather natural syntax.
- For more documentation about how to use
- .B eqn
- see [UPM75].
- .A
- The program
- .B eqn
- converts formula descriptions into NROFF/TROFF commands.
- Typical usage is
- .DS I 6
- .BS
- \&eqn file | troff
- .BE
- .DE
- where file contains both the
- .B eqn
- and PUBMAC requests.
- .P
- In PUBMAC the requests
- .DS I 6
- .BS
- \&.EQ [I/C] [indent] [L/R number] [R/L number] [count]
- \&.EN [count]
- .BE
- .DE
- .UW ( EQ uation,
- .UW E quation
- .UW e N d)
- are recognized.
- The first operand of
- .B .EQ
- can be
- .B I
- or
- .B C
- \&, C has the effect of centering the formula on the line and is
- the default, I has the
- effect of indenting the display by the value of the operand following the
- .B I
- (default 0).
- .P
- The following operands allow the formula to be numbered in one or
- both margins.
- .B L
- or
- .B R
- specify the the formula should be numbered at the Left or Right margin.
- The number to be placed in that margin should follow the
- .B L
- or
- .BW R .
- .P
- The operand
- .B count
- of
- .B .EQ
- and
- .B .EN
- specifies the amount of blank lines to be inserted at the
- before and after the
- formula.
- .S1 Page Format
- If you want to use another format than the standard format
- which is described below, you only may do this with special PUBMAC
- commands:
- .DS I
- .TS 0
- l l.
- \&.IN set standard indentation
- \&.PO set page offset
- \&.PN set page number
- \&.PL set page length
- \&.LL set line length
- \&.MS T define top margin titles
- \&.MS B define bottom margin titles
- \&.ME end titles
- \&.IN set default indent
- \&.AD adjust rigth margin
- \&.NA do not adjust right margin
- \&.HY switch hyphenation on
- \&.NH switch hyphenation off
- \&.HC set hyphenation indicator character
- .TE 0
- .DE
- .S2 The Standard Format
- PUBMAC uses the following standard values for the page format:
- .DS I
- the width of 3 digits for the standard indentation
- 16.02 cm of text per line
- pages of 29.7 cm
- 25.7 cm of text per page, including the margin titles
- 2 cm of blank on top of page
- the page offset is 0
- bottom title of page is "-- % --"
- where % is the current page number in arabic numerals
- adjust both margins, fill output lines
- hyphenation enabled
- .DE
- .S2 Setting the Page Offset
- If you want to have a larger
- blank margin on the left hand side of your paper (e.g. for binding
- purposes),
- use the command
- .DS I 6
- .BS
- \&.PO offset
- .BE
- .DE
- .UW ( P age
- .UW O ffset).
- The output will be moved as a whole by
- .B offset
- columns to the right.
- This command should precede all input text.
- The default offset is zero, i.e. printing starts at the leftmost
- position of the output device.
- .NE 10
- .S2 Changing the Page Format
- To change the length of the page, use the command
- .DS I 6
- .BS
- \&.PL paperlength [textlength [top offset]]
- .BE
- .DE
- .UW ( P age
- .UW L ength).
- The operand
- .B paperlength
- determines the physical length of the page (the number of lines
- which fit on one sheet of paper);
- the operand
- .B textlength
- determines the number of lines used by PUBMAC (excluding top and bottom margin)
- for text output.
- If
- .B textlength
- is not specified it is defaulted to
- .BW 26.03cm .
- The default value for
- .B paperlength
- is 29.7cm, which is
- the right value A4 paper.
- .A
- The offset of the text from the top of the paper is given by the operand
- .B top offset
- (default is 1.8cm).
- The sum of
- .B textlength
- and
- .B "top offset"
- must be smaller then or equal to
- .BW paperlength .
- .A
- This command must precede all other input text, as it is not
- possible to change the page length during the text processing.
- .P
- To change the linelength, use the command
- .DS I 6
- .BS
- \&.LL length [footnote length]
- .BE
- .DE
- .UW ( L ine
- .UW L ength).
- The default line length 16.02cm.
- The default footnote line length is 10/11 of the line length.
- .S2 Head and Foot Titles
- To define a head title, to appear at the start of each page, or to change
- the standard foot title ("\-\-~%~\-\-") at the bottom of each page,
- the commands
- .DS I
- .TS 0
- l l.
- \&.MS T define Top Margin titles
- \&.MS B define Bottom Margin titles
- \&.ME Title End
- .TE 0
- .DE
- are supplied.
- As with NROFF/TROFF, the current page number is represented by "%" in the
- .B .TL
- request.
- .P
- To define a head title, use the command
- .DS I 6
- .BS
- \&.MS T [E/O] [count]
- .BE
- .DE
- .UW ( M argin
- .UW T op text).
- The first optional operand allows the definition of different
- titles for even and odd numbered pages;
- specify
- .B E
- for titles to appear on even numbered, and
- .B O
- for titles to appear on odd numbered pages.
- If the second operand is omitted, the title defined will
- appear on all pages, regardless whether the page number
- is even or odd.
- The operand
- .B count
- specifies the number of blank lines between the top margin text
- and the start of further text
- (default 2).
- .A
- The text defining the head title
- follows on the next input lines. If you want to enter PUBMAC
- commands into the title which have to be executed each time the
- head title is processed (e.g.
- .B .TL
- commands), precede the command lines with the character
- sequence "\e!".
- Commands that affect the general layout,
- like
- .BW .SS
- and
- .BW .IN ,
- should be used with care.
- In general it is wise to reset the altered environment to its
- original state at the end of the title definition.
- .P
- To terminate the title definition, use
- .DS I 6
- .BS
- \&.ME
- .BE
- .DE
- .UW ( M argin
- text
- .UW E nd).
- .P
- Equivalent to head titles, foot titles can be defined. Use
- .DS I 6
- .BS
- \&.MS B [E/O] [count]
- .BE
- .DE
- .UW ( M argin
- .UW B ottom
- text) to start the input of the foot title. Use
- the command
- .B .ME
- to terminate the foot title definition, too.
- .P
- The foot titles of this manual, for instance, have been
- defined by:
- .DS I 6
- .BS
- \&.MS B E
- \&\e!.TL \'%\'\'\'
- \&.ME
- \&.MS B O
- \&\e!.TL \'\'\'%\'
- \&.ME
- .BE
- .DE
- This example also shows the usage of the escape sequence
- "\e!",
- which prevents both
- .B .TL
- commands from being executed during the definition
- of the titles, and causes them to be executed every time a new page
- is processed.
- This is essential to get the current page number
- and not the page number being actual when the title is defined.
- .NE 4
- .P
- To delete the standard foot title, simply define an empty foot title:
- .DS I 6
- .BS
- \&.MS B 0
- \&.ME
- .BE
- .DE
- .S2 Setting the Standard Indentation
- The value used for indenting paragraphs, after section start,
- indented and quoted displays, and for the command
- .B .IS,
- by default is set to 3.
- This value can be changed by invoking the command
- .DS I 6
- .BS
- \&.IN [indent]
- .BE
- .DE
- .UW ( IN dentation).
- After this command, further sections, paragraphs etc. are indented by
- the number of columns specified by
- .BW indent .
- If no indentation at all is desired, specify
- .B 0
- as operand.
- .B Indent
- has as default value 3.
- .S2 "Page Number"
- Sometimes a paper is formatted in parts.
- The number of the first page of a certain part will not
- always be 1.
- The command
- .DS I 6
- .BS
- \&.PN number [style]
- .BE
- .DE
- .UW ( P age
- .UW N umber)
- allows you to use a different start value for page numbers.
- The
- .B style
- operand
- can have one of the values: a, A, i, I and 1.
- These letters have the same meaning as for the
- .B style
- operand of the
- .B .PS
- request.
- The new number ( and format ) becomes valid at the next printed page,
- or at the first page if given before any text.
- .S2 Adjusting
- As already has been mentioned, the default mode for formatting
- is filling and adjusting.
- .A
- Adjusting can be switched off
- by the command
- .DS I 6
- .BS
- \&.NA
- .BE
- .DE
- .UW ( N o
- .UW A djust).
- All text following will not be aligned to a uniform right margin,
- until a
- .DS I 6
- .BS
- \&.AD [type]
- .BE
- .DE
- .UW ( AD just)
- is encountered, which switches on adjusting again.
- The operand
- .B type
- can be one of the following,
- .PS i 5
- .PT "~~R"
- Right adjusted: uniform right margin, ragged left margin
- .PT "~~L"
- Left adjusted: uniform left margin, ragged right margin
- .PT "~~C"
- Centered: both margins ragged by the same amount
- .PT "~~B"
- Both adjusted (default): uniform left and right margin
- .PE
- .S2 Hyphenation
- Hyphenation can be switched off globally by using the command
- .DS I 6
- .BS
- \&.NH
- .BE
- .DE
- .UW ( N o
- .UW H yphenation).
- .NE 6
- .N
- The command
- .DS I 6
- .BS
- \&.HY
- .BE
- .DE
- .UW ( HY phenation)
- enables hyphenation again.
- .P
- A second possibility is to use the command
- .DS I 6
- .BS
- \&.HC character
- .BE
- .DE
- (set
- .UW H yphenation
- .UW C haracter),
- which determines the operand
- .B character
- to be the indicator character for hyphenation.
- I.e. a word will be hyphenated
- at the points indicated by this character.
- The character itself will not appear in the
- output, even if the word is not hyphenated.
- Example:
- .DS I 6
- .BS
- \&.HC `
- \& .....
- \& ... Algo`rithmus ...
- .BE
- .DE
- This occurence of
- .B Algorithmus
- will now, if necessary, be hyphenated as
- .BS
- Algo-rithmus.
- .BE
- .A
- To prevent a word to be hyphenated at all,
- it has to be preceded by the hyphenation indicator character, e.g.
- .BW `Algorithmus .
- .S1 Footnotes, Table of Contents, Bibliography
- PUBMAC provides commands for the creation of
- footnotes, a table of contents and a list of bibliograpy.
- .P
- The following commands are available:
- .DS I
- .TS 0
- l l.
- \&.FS start a footnote
- \&.FN start numbered footnote
- \&.FE end a footnote
- \&.CT put out the table of contents
- \&.RS start a bibliography reference
- \&.RF start a reference
- \&.RE end a bibliography reference
- \&.RT give list of bibliography
- .TE 0
- .DE
- .S2 Footnotes
- Three commands are provided to create a footnote.
- Footnotes appear on the bottom of the page where they are
- defined; if the remaining place on the page is too small
- for the text of a footnote it will be shifted to the bottom of the next page.
- .P
- To start a footnote text, use the PUBMAC command
- .DS I 6
- .BS
- \&.FS [prefix] indicator [ suffix ]
- \&.FN [prefix] [suffix]
- .BE
- .DE
- .UW ( F ootnote
- .UW S tart,
- .UW F ootnote
- start
- .UW N umbered).
- .B indicator
- allows to identify the footnote:
- it will appear in the output text at the place where
- .B .FS
- was encountered in the input text, and it will appear at the start
- of the footnote text.
- .P
- The
- .B .FN
- request has as default indicator a number.
- This number is automaticaly incremented at each occurence of a
- .B .FN
- request.
- The footnote counter is reset to one for each new section, when
- in manual mode.
- .A
- The operand
- .B suffix
- is meant for the special case that
- a full stop, comma, semicolon etc. immediately has to follow
- the footnote indicator in the output text (otherwise the special
- character and the indicator would be separated by a blank, or even worse,
- by a newline).
- The operand
- .B prefix
- serves a similar purpose.
- .A
- If only two of the three operands are specified, the last is
- interpreted as the prefix.
- .P
- To end the text of a footnote, the command
- .DS I 6
- .BS
- \&.FE
- .BE
- .DE
- .UW ( F ootnote
- .UW E nd)
- is used. If the footnote is referenced in the middle of a sentence,
- the rest of the sentence has to follow the
- .B .FE
- on the next line.
- .NE 5
- .P
- As an example
- .FS (*) ,
- this is an example of a footnote
- .FE
- the footnote at the bottom of this page was created by the following
- input lines:
- .DS I 6
- .BS
- \&As an example
- \&.FS (*) ,
- \&this is an example of a footnote
- \&.FE
- \&the footnote at the .....
- .BE
- .DE
- This example also shows the usage of the operand
- .B suffix
- of the
- .B .FS
- command, you see that the indicator "(*)"
- is followed by "," immediately without a separating space.
- .S2 Table of Contents
- As mentioned above, all titles of sections are saved for a table
- of contents.
- To put out the table of contents,
- at the end of the input text invoke the command
- .DS I 6
- .BS
- \&.CT
- .BE
- .DE
- .UW ( C ontents
- .UW T able).
- The table of contents collected up to now is put out and then deleted.
- No headers or new page commands are generated.
- This gives one the flexibility to put out the table of contents
- for example at
- the end of each chapter on a separate page or at the end of the
- text in an appendix.
- To have the pages on which the table of contents is printed, numbered
- with roman numbers starting
- with "i", use the command
- .B .PN 1 i
- before the
- .B .CT
- command.
- The table of contents can then be inserted
- before the front page of your paper instead of at the end.
- In report mode the table of contents is also entered in the table of contents.
- .S2 Bibliography
- Besides supporting the
- .U refer
- utility PUBMAC provides
- commands to collect literature references and
- to print them at the desired place.
- .A
- To generate an entry in the bibliography and to refer to it, use
- .DS I 6
- .BS
- \&.RS [prefix] refname [suffix]
- .BE
- .DE
- .UW ( R eference
- .UW S tart).
- The text following this command is saved for the bibliography.
- Similar to the operands of the footnote command ,
- .B refname
- is placed in the running output text and at the start of the
- bibliography entry.
- .B refname
- will be enclosed in square brackets
- (\ [ and\ ]\ ).
- .B suffix
- and
- .B prefix
- have the same meaning as with the footnote command.
- PUBMAC commands for formatting the bibliography text have to be escaped
- by "\e!", as the layout of the bibliography is determined
- when the
- .B .RT
- command is invoked.
- .P
- .NE 8
- If you want to create an entry without referring to it
- in the text explicitely, use the command
- .DS I 6
- .BS
- \&.RF refname
- .BE
- .DE
- .UW ( R e F erence
- start).
- The result is the same as with
- .B .RS,
- but
- .B refname
- will not appear in the running text.
- .P
- To terminate a bibliography entry, use the command
- .DS I 6
- .BS
- \&.RE
- .BE
- .DE
- .UW ( R eference
- entry
- .UW E nd),
- which will switch back to normal text
- processing.
- .P
- To put out the collected bibliography, invoke the command
- .DS I 6
- .BS
- \&.RT
- .BE
- .DE
- .UW ( R eference
- .UW T able).
- The bibliography collected up to now is put out and then deleted,
- so that it is possible to start a new bibliography.
- In this way, bibliographies can be made either per section
- or for the whole paper.
- The bibliography is put out in the format being chosen the
- point at which the
- .B .RT
- command is invoked.
- .S2 Using refer
- The program
- .B refer
- can be used to add references to articles mentioned in a
- systemwide database, a private database or in the text.
- It places an indicator in the text and the reference in a footnote
- on the same page.
- If the
- .I \-e
- option of
- .B refer
- is used the references will appear at the appropiate place.
- The
- collected references have to be surrounded by appropiate
- PUBMAC commands.
- .S2 Indeces
- Commands are provided to collect index words accompanied by the number
- of the page they occur.
- Another command causes the list of collected index words to be printed
- on NROFF/TROFF's error output.
- .A
- To add an index entry to the list use
- .DS I 6
- .BS
- \&.IX index-word ...
- \&.IW [prefix] index-word [suffix]
- \&.IR index-word ...
- .BE
- .DE
- The arguments of the
- .B .IX
- .UW ( I nde\c
- .UW X )
- and
- .B .IW
- .UW ( I ndex
- .UW W ord)
- commands appear in the running text,
- as opposed to
- .B .IR
- .UW ( I ndex
- .UW R ference)
- whose arguments only appear in the index list.
- .B Suffix
- and
- .B prefix
- have the same meaning as with the footnote command.
- .A 1
- The collected references can be produced
- on NROFF/TROFF's error output with the command
- .DS I 6
- .BS
- \&.IT
- .BE
- .DE
- .UW ( I ndex
- .UW T able).
- By redirecting the error output of NROFF/TROFF
- one can save this list for further processing.
- .DS I
- .BS
- troff -mkun files .... 2>indeces
- awk -f .... indeces | troff -mkun
- .BE
- .DE
- .A
- The index entries are produced on one line each with the index words
- enclosed in square brackets and
- inmediatly followed by the appropiate page number.
- An example:
- .DS I 6
- .BS
- [indeces]\n%
- .BE
- .DE
- .S1 Special Considerations
- This section discusses
- the use of the tabulator, special characters and some other special
- facilities in PUBMAC.
- .S2 Tabulator
- The tabulator stops in PUBMAC are set to
- .DS I 6
- .BS
- 9,17,25,33,....
- .BE
- .DE
- by default.
- To set the tabulator positions to your needs, use
- .DS I 6
- .BS
- \&.ta pos...
- .BE
- .DE
- (set
- .UW TA bulator),
- which will set the tabulator stops to the
- positions indicated by
- .B pos...
- If pubmac is used in conjuction with
- .B tbl
- the tab stops will be heavily used by tbl and thereby rendered
- almost unusable outside the tables.
- .S2 Special characters
- .SP
- The character
- "~"
- is replaced by the unpaddable space character,
- which permits tying two or more words together so that
- they will neither be moved apart nor split across two lines.
- For example, if you want the words
- "integral number denotation" not to be separated by more
- than one blank, enter them as
- .BW integral~number~denotation .
- .P
- The command
- .DS I 6
- .BS
- \&.SP [character]
- .BE
- .DE
- allows you to use any other character as indicator for the unpaddable space.
- If you specify no operand, you will have no single character to
- indicate a unpaddable space.
- .SP ~
- .P
- Since the backslash character "\e" is used heavily by NROFF/TROFF as escape
- character,
- it has to be written twice if one wants to see it back in the output.
- As the text of displays is processed several times,
- even a doubled backslash will be lost.
- Therefore a backslash in a display should be entered
- either eight or a higher power of 2 times (which is a nuisance) or as "\ee".
- .S2 Halfline Motions
- NROFF/TROFF, thus also PUBMAC, provides the
- possibility for half line motions, e.g. for formatting
- mathematical formulas.
- The sequence
- .B \ed
- moves down half a line, and the sequence
- .B \eu
- moves up half a line.
- The output
- .N 1
- (i\d1\u - i\d2\u)\u2\d
- .N 1
- was produced with the input
- .DS I 6
- .BS
- (i\ed1\eu - i\ed2\eu)\eu2\ed
- .BE
- .DE
- Usage of
- .B \ed
- and
- .B \eu
- can result in messy output on devices
- not capable of performing half line motions; messy output
- also will result if not the same number of "ups" and "downs" is
- used.
- .P
- Typically lineprinters and display terminals can not perform half line
- motions, whereas the HyPrint devices are capable of doing so.
- .P
- See also the section describing the use of
- .B eqn
- with PUBMAC.
- .S2 The Actual Section Number
- The actual section numbers are stored in registers named
- .B Sn,
- where
- .B n
- stands for any of the digits 1, 2, 3, 4 and 5.
- If you want to refer to it, access it in the input text through
- .B \en(Sn,
- which will be replaced in the output text by the current section
- number of the corresponding section depth.
- For example if you wish to insert the number of the current chapter
- use
- .BW \en(S1 .
- The register named S5 is used for the numbering of appendices.
- .A
- To use it in a page title definition, two backslashes have to be written:
- .BW \e\en(Sn .
- The first line of the page header of
- this manual, for instance, has been produced by entering the
- command
- .DS I 6
- .BS
- \&\e!.TL \'PUBMAC users guide\'\'\e\en(S1\'
- .BE
- .DE
- when defining the head title with the commands
- .B .MS T
- and
- .B .ME
- (see previous chapter).
- .SM AP A
- .AP "Error messages"
- Besides error messages issued by NROFF/TROFF,
- messages from PUBMAC may be written to the users terminal
- (Unix error output file 2).
- The messages have the following form:
- .DS I 6
- .BS
- Error (p=.., l=..): message
- .BE
- .DE
- .B message
- gives information about the kind of error encountered.
- The location of the error is described between the parentheses
- in the order
- .DS I
- p = page number
- l = line number on the page
- .DE
- Additionally, errors are marked by three plus signs (\(pl\(pl\(pl) or a \(lh
- .DS I 6
- .BS
- \&\(lh Error
- .BE
- .DE
- appearing on the right margin of the output text.
- Since many errors are detected much too late,
- the actual error is always located before the location stated.
- .LL
- .AP "Command Summary"
- In the summary, the following abbreviations are used for operands:
- .VS 0.8 0.2
- .PS - 6
- .PT n
- denotes a number (e.g. '1', '5', '231')
- .PT c
- denotes a single character (e.g. 'i', 'F', 'O')
- .PT w
- denotes a word (e.g. 'NROFF', 'pubmac')
- .PT w...
- denotes a sequence of 1 or more words
- (e.g. 'Table of Contents')
- .PE
- .VS
- .N 4
- .PS 1 14
- .PT Command
- Explanation
- .PT .A [n]
- .B Alinea.
- .N
- First line of alinea will be indented.
- .N
- The alinea will be preceded by n (default 0) blank lines.
- .PT .AD [c]
- .B Adjust mode.
- .N
- Left, Right, Centered or Both.
- .NE 3+1
- .PT ".AP w..."
- .B Appendix.
- .N
- Same as .S1.
- .NE 6+1
- .PT ".B w..."
- .B Boldface.
- .N
- Write the words given as operands w... in
- bold face letters (this is done in a output device dependant way).
- .PT .BE
- .B Bold end.
- .N
- End of bolt text.
- .PT .BP
- .B Begin page.
- .PT ".BS"
- .B Bold start.
- .N
- All following text is printed in bold face up to .BE.
- .N
- The way bold face is printed depends on the output device.
- .NE 10
- .PT .CE
- .B Centering end.
- .N
- The centered text will be followed by n blank lines.
- .NE 3
- .PT .CS
- .B Centering start.
- .N
- Following input lines up to .CE will be centered.
- .N
- The centered text will be preceded by n blank lines.
- .NE 10+1
- .PT ".CT"
- .B Table of contents.
- .N
- All titles collected from previous .S1, .S2, .S3, .S4 and .AP commands
- are put out.
- .PT ".CU w..."
- .B Continuous underline.
- .N
- Like .U only all characters are underlined.
- .NE 4+1
- .PT .DB
- .B Display break.
- .N
- Allow the following displays to be broken
- up, if necessary.
- .PT .DE [n]
- .B Display end.
- .N
- The display will be followed by n (default 1) blank lines.
- .NE 6+1
- .PT ".DS "
- .B Display.
- .N
- A display is text
- which is kept together and not spread over a page boundary.
- .N
- The operands determine the kind of display.
- The first few operands are:
- .N
- .PS - 4
- .PT B
- .B box display
- .N
- the text between .DS B and .DE
- will be surrounded by a box, the text will be formatted and adjusted
- .PT M
- .B marked display
- .N
- the text will be marked by |
- on the left hand side, not adjusted and not filled
- .PT no
- .N 1
- not adjusted, not filled
- .PE
- These operands can be followed by:
- .PS - 4
- .PT I
- .B indented display
- .N
- not adjusted, not filled
- .PT Q
- .B quoted display
- .N
- indented from both margins,
- adjusted and filled
- .PE
- .PT .FE
- .B Footnote end.
- .NE 3
- .PT ".FN [[w2] w1]"
- .B Numbered footnote start
- .N
- As with .FS, but the indicator is defaulted to a number in parenthesis.
- .NE 17+1
- .PT ".FS [w3] w1 [w2]"
- .B Footnote start.
- .N
- The footnote will be moved to the bottom of the page.
- Operands: w1=indicator, w2=suffix and w3=prefix.
- The indicator (w1) appears in the output text and
- at the start of the footnote text as well to identify the footnote.
- Prefix and suffix are for the special case that the indicator
- has to be preceded or followed by e.g. comma, full stop etc.
- The running text will contain w3w1w2.
- .NE 10+1
- .PT ".HC c"
- .B Hyphenation character.
- .N
- The hyphenation control character is set to c.
- It can be imbedded in words to indicate where they should be
- hyphenated. If it precedes a word, this word will not be
- hyphenated. The hyphenation character itself will not appear in
- the output.
- .PT .HY
- .B Hyphenation.
- .PT .IE
- .B Indentation end.
- .N
- Return to the indentation level before the last .IS.
- .NE 4+1
- .PT ".IN n"
- .B Set Indentation.
- .N
- The indentation used for paragraphs, section start etc
- is set to n.
- .NE 4+1
- .PT .IR w...
- .B Index Reference
- add the words to the index list, do not
- insert them in the running text.
- .NE 4+1
- .PT .IS [n]
- .B Indentation start.
- .N
- Indent following text by n (default three) columns until
- a .IE is encountered.
- .NE 4+1
- .PT .IT
- .B Index Table
- Produce the index table on file descriptor 2.
- .NE 4+1
- .PT .IW [w3] w1 [w2]
- .B Index word
- Insert w1, w2 and w3 in the running text as with
- .B .FS
- and add w1 to the index list.
- .NE 4
- .PT IX w...
- .B Index
- Insert the words in the running text and the index list.
- .NE 5+1
- .PT ".LL n"
- .B Linelength.
- .N
- The line length is set to n.
- The default line length is 66.
- Must occur before any input text.
- .NE 6+1
- .PT .ME
- .B Margin input end
- .NE 13+1
- .PT ".MS c1 c2"
- .B Title input start.
- .N
- Operands: c1=T for T title, c1=B for bottom title,
- c2=E for even pages, c2=O for odd pages.
- The text between .MS and .ME will appear
- as top and bottom margin text on each page.
- Defaults: no top margin text, bottom margin text= ".TL \'\'-- % --\'\'".
- Attention: NROFF/TROFF commands to be executed every time
- (e.g. .TL \'\'-%-\'\')
- a title is processed, have to be preceded by "\e!".
- .PT ".N [n]"
- .B New line.
- .N
- The new line will be preceded by n (default 0) blank lines.
- .PT .NA
- .B No adjust mode.
- .N
- The right margin will be ragged.
- .NE 4+1
- .PT ".NE n"
- .B Need lines.
- .N
- If no n lines are left on the current page, a new page is begun.
- .PT .NH
- .B No hyphenation.
- .NE 5+1
- .PT ".P [n]"
- .B Paragraph.
- .N
- The paragraph is separated from the preceding text
- by n (default 1) blank lines and its first line is indented.
- .PT .PE [n]
- .B End list of points.
- .NE 5+1
- .N
- The list will be followed by n (default 1) blank lines.
- .NE 9+1
- .PT ".PL n m"
- .B Set pagelength.
- .N
- The first operand determines the physical length of the
- page, the second one the number of lines printed per physical page.
- The default value for n is 66, for m 59.
- Must occur before any input text.
- .PT ".PN n c"
- .B Page number.
- .N
- The firts operand specifies the number of the next printed page.
- The second operand specifies the format of the page number when printed.
- (see .PS, but only a,A,i,I and 1).
- .PT ".PO [n] "
- .B Set page offset.
- .N
- The left margin is moved n columns to the
- right.
- .NE 12+1
- .PT ".PS [c [n]] [[w2] w1]"
- .B List of points start.
- .N
- Operands:
- c=numbering style, n=indentation of points (default=3).
- If c=- or empty, points are labeled with "-", if c=1
- numbering of points will be arabic, if c=a with small letters,
- if c=A with capital letters, if c=i with small roman numbers, if c=I
- with capital roman numbers.
- w1 is a suffix that will follow each point, w2 is a point prefix.
- .NE 4+1
- .PT ".PT w... "
- .B Point.
- .N
- The operands w... replace the label chosen by .PS
- for this point only.
- .NE 4+1
- .NE 2
- .PT .RE
- .B Reference entry end
- .N
- To close the text of the reference entry started by .RF or .RS.
- .NE 12+1
- .PT ".RF [w3] w1 [w2]"
- .B Reference.
- .N
- Operands: w1=reference abbreviation,
- w2=suffix, w3=prefix.(see .FS)
- The reference abbreviation is embedded in square brackets
- and inserted to the output text and to the start of the reference
- entry as well for identification purposes.
- References are collected to be put out
- with .RT.
- .PT .RP
- .B Report layout.
- .NE 4+1
- .PT ".RS w"
- .B Reference start.
- .N
- Same as .RF, but the reference w will not appear in the running output
- text.
- .NE 7+1
- .PT .RT
- .B Give bibliography.
- .N
- Via .RF and .RS collected bibliography is put out and then deleted.
- .PT ".S1 w..."
- .B Section.
- .N
- t is the section title, also saved for the table of contents.
- Sections and subsections (see below) are numbered automatically.
- .NE 5+1
- .PT ".S2 w..."
- .B Subsection.
- .N
- The title will be saved for the table of contents, as for
- the following commands .S3 and .S4
- .PT ".S3 w..."
- .B Subsubsection.
- .PT ".S4 w..."
- .B Subsubsubsection.
- .NE 6+1
- .PT ".SN n n n n n"
- .B Section numbers.
- .N
- The first, second, third and fourth operands
- set the start values for section numbers, subsection numbers and so on.
- The last operands sets the start value for the appendix number.
- .NE 4+1
- .PT ".ta n..."
- .B Set tabulator.
- .N
- The tabulator stops are set to the positions n...
- given in the operand list.
- Usage conflicts with use of
- .B tbl.
- .NE 4+1
- .PT ".TL x"
- .B Title.
- .N
- To define a three part title; x is of the
- form \'left\'center\'right\'.
- .PT ".U w..."
- .B Underline.
- .N
- The words given as operands w... are underlined.
- .PT .UE
- .B Underlining end.
- .PT .UN
- .B Undent temporarily.
- .PT ".US [c]"
- .B "Underlining start"
- .N
- All following text up to .UE is underlined.
- Operand: c=C then the input text is non-filled and continuously underlined,
- normaly only letters and digits are underlined.
- .PE
- .AP Bibliography
- .N 2
- .RT
- .PN 1 A
- .MS T E
- \!.TL ```PUBMAC user's guide`
- .ME
- .MS T O
- \!.TL `PUBMAC user's guide```
- .ME
- .BP
- .N 0.5
- .CS
- Table of Contents
- .CE
- .N 1.5
- .CT
|