Home

Groff and Friends HOWTO

1. July 2001 Groff and Friends HOWTO Revision 1 28 16 Functional Listing of ms Macros Type Macro Description Text Format Text Format Text Format Text Format Text Format Text Format Text Format Text Format Text Format Text Format Text Format Text Format Text Highlight Text Highlight Text Highlight B text trail precede BI text trail precede C text trail precede I text trail precede LG NL RE RS SM UL text UX text B1 B2 BX text Print text in bold face Multiple words should be sur rounded by quotes i e B some text If text is omitted then the font used for rendering subsequent text is bold Optional trailing and preceding punctua tion is suffixed and prefixed to the text in the normal format See also BI I and C Print text in bold italic See also B I and C Print text in constant width font See also B BI and I Print text in italic See also B BI and C Increase the point size of the text by 2 Set point size to the default 10 pts if not specified via the number register PS at the beginning of the document Return to Roman font Note that there is no argu ment for this macro Compare to B BI and C all of which accept arguments Retreat one level of relative indentation See also RS Indent by one level of relative indentation The amount of indentation may be alt
2. The only possibility to avoid name clashes is to check all macro definitions in the standard macro packages which come with groff There is a small tool which might help you in debug ging name clashes groff mtrac man Tlatinl 2 gt groff log gt groff txt This will get a trace of all macro calls definitions in tmac an You can for example get an ordered list of all used macros with cut d f 5 groff log sort unig gt man log macrolist Note that 1f errors occur these will be included in the list You will have to weed these out yourself Let me add that it might be prudent to avoid two letter upper case macro names when modifying or adding to the ms package Since groff accepts long names any string longer than two characters whether upper or lower case is recommended Anyone reading to this point will have observed that I did not follow my own advice see the earlier section on macro customization The macros developed and exhibited earlier were created while I was still a novice I have no doubt that someday I ll be changing them to reflect my advice to you 15 15 How Can I Get a List of All My References Unless you write your own shell script or perhaps a Perl program thereby allowing yourself the luxury of being selective there is only one way of getting such a list that I know of The following sed script is an example n A script used in the command cat home uc sed f sed script gt al
3. sy touch output so output ds references Sy rm f output NJ ie NAS1 A ds QN 2 Ch nl eq sy echo ds QN NN 2 Ch n eq gt gt output SN el N N ie S1 R ie d QN NN 2 S 4 EQUATION ON 2 3 GL NA E tm NO LABEL named QN 2 was defined 4 B 2 UNDEFINED f P 3 el ie S1 N E nr eq 2 4 EQUATION Ch Nn eq NN 3 nr eq NN 2 ds Eq Ch n eq el 2 EQUATION Ch n eq 1 July 2001 Groff and Friends HOWTO Revision 1 28 40 mae de DO macro to redefine headers and footers Sif NNS LEGEAN shift ds LF SEES NXNSIACEU AHA shift ds CF NN if S1 RE shift ds RF s OF LF CF RF EE INNA REINAN CET NN LEE Ie ds do FALSE GUESUNNSTEBHZS WIN shift ds LH s ds do TRUE sito ENVSIACHE A shift ds CH ds do TRUE if NNSI RH shift ds RH ds do TRUE Nt N Need the following test as PN is not defined if this is onvked too soon Xe if do TRUE OH NNA LH NN CH NN RH EH NX RH NV CH NN LH 10 6 Small Caps Ted Harding provided a macro to create small capitals in a recent Email message to the groff mail list The following is a direct quote from his Email Since I mentioned the small caps issue in a previous mail s
4. N MUST appear in the order AT SN NT Note that after a paragraph reset LP IP PP QP AE etc a following EQ delim EN will insert a blank numbered equation in the text eM EQ delim define left define right define left define right define lett Te define left define right define ab above define ov over define fr from define pa partial define inf inf define lc fR fP define rc fR f P Revision 1 28 Groff and Friends HOWTO July 2001 43 define Fourier s 4 f ZCMI F fP s0 define Laplace st 4 f ZCMI L f P s0 define Comp st4 f ZCMI C fP s0 define 1 left define r right define prime aa vow n define sup define _ sub define prop pt define iv i vec define jv j vec define kv k vec define perp pp define eval s 8 fR fP so EN Occasionally you might want some ad hoc expression to be abbreviated Say for example you expect to type sin theta many times and it isn t in your default list it isn t in mine Simply define it at the begin ning of the first equation in which it appears or any equation prior to that first appearance and then use the abbreviation thereafter For example you might define it and use it immediately as EQ define st sin theta x sqrt st ov x sup 2 EN which would result in
5. Type Macro Description Page Format Page Format Cover Page Cover Page Cover Page Text Format Cover Page Text Format Text Highlight Text Highlight Page Format Text Format Bibliography Page Format Text Highlight Page Format Text Format Page Format Page Format AC AC AB no AE AI AM AU B text trail precede B1 B2 BD BI text trail precede BR BT text BX text CD C text trail precede DA text DE Set single column mode causes a page break Set two column mode Return to single column with LC Begin the abstract on the cover page ending it with AE no means do not label the abstract End the abstract Print the name of the author s institution which should appear on the next line Multiple line entries should be separated by br in column 1 Create better accent mark definitions Print the author s name which should appear on the next line This macro normally follows TL and pre cedes AI Print text in bold face Multiple words should be sur rounded by quotes i e B some text If text is omitted then the font used for rendering subsequent text is bold Optional trailing and preceding punctua tion is suffixed and prefixed to the text in the normal format See also BI I and C Enclose the following text in a box End with B2 End the boxed text which was begun with B1 Commence block display of t
6. equation 42 macro 30 D DB 30 define 23 42 DESC 61 dictionary order MS macro number registers 17 MS macros 7 DM 30 DO 30 document style 17 dot 23 dotdot 23 double quotes 22 macros 64 doublebox 21 ds 6 dvi format 61 dyad 23 E emacs 6 encapsulated PostScript 25 28 encapsulated Postscript 52 eps files 25 figures 25 EQ 43 eqn 21 42 key words 23 math symbols 25 token separators 22 equation ad hoc definition 43 customization 42 equation reference example 38 equations 21 example equation reference 38 QN 38 F FI 35 figure box 27 figure caption 26 Groff and Friends HOWTO Index figures 25 captions 35 eps files 25 floating keep page numbers 68 footnote format 17 footnotes 19 automatically numbered 19 paragraph bug 64 format 50 scripts 50 from 22 23 G GIF 25 52 gnu groff bug 69 gnuplot 52 Greek letters 23 grep 1 67 groff 1 groff gems 68 groff request ffii org 69 groffGffii org 69 grops 26 GSview 65 gv 42 67 H hat 23 HOWTO source setting format 61 HTML 3 25 html 52 61 http groff ffii org 69 http www cs vu nl tmgil miscwingroff html 65 I ImageMagick 52 import 52 index 48 creation 45 scripts 48 inf 23 int 23 ISO Latin 1 61 K KE 27 keeps 27 key words eqn 23 KF 27 page numbers 68 KS 27 L landscape 53 latin1 61 Icol 22 23 left 23 left margin 18 lengt
7. gt txt 2 nul GS SCRIPTS error script lt nul echo Text file txt created Run groff source through geqn gtbl and tpic to check for errors S p echo Picture check echo S SOELIM lt S PIC gt dev null echo s t echo Table check echo S SOELIM lt S TBL gt dev null echo s e echo Equation check echo S SOELIM lt EQN gt dev null Add Table of Contents and Index entries 8 COC echo echo Adding Table of Contents and Index entries to a groff source file echo sed f S SCRIPTS tec script lt gt toc gecho 2 2 2 New file toc created Format mgs groff source file for processing the TOC and Index Loc mult echo echo Processing groff source for Table of Contents and Index entries echo gt var tmp x cat sed f S SCRIPTS refer script sed f S SCRIPTS eqn2 script i 5 SOELIM X S REFER S REFER OPTS p DATABASE Revision 1 28 Groff and Friends HOWTO July 2001 59 S TROFF S TROFF OPTS MACRO Tps gt dev null 2 nul GS SCRIPTS error script lt nul Ggcho Necesse Index file nul created Process the groff source to make up an index index to var tmp x which is read via so inserted by toc script nul x echo echo Reading index file nul and formatting for groff echo sed e s N
8. txt toc nul gvx sp lpr2 pic eps psx gz egz pgz html TMAC DIR names the directory in which to search for local macro definitions or the re definitions of macros defined in the standard macro packages such as the ms package sometimes called gs DIR home provinsd docs s TMAC names the local macro file that is to be included on the command line Groff looks for it in TMAC DIR Our local macro file is named tmac ds MS IMAC DIR mds MACRO names the macro packages to be read from the standard location which is usr lib groff tmac or from the user s own library of macros As of Debian 2 0 the macros are in usr share groff tmac and the ms macro which WAS called gs is again called ms MACRO ms TMAC HB dE db dk July 2001 SOELIM names the processor that precedes the execution of GROFF and include the contents of so filename statements in the input stream Note that PREPROCESSOR commands intended for TBL or EQN will NOT be processes unless soelim or some other processor Groff and Friends HOWTO Revision 1 28 56 expands the so filename statements SOELIM cat Version 1 11 of groff from Debian at least is in usr bin The current version 1 15 Dec 20 1999 is in usr local bin PREFIX usr bin PREFIX usr local bin SOELIM PREFIX soelim TROFF PREFIX groff PIC PREFIX pic EQN PREFIX eqn TBL PREFIX tbl groff
9. NT 2 3 side by side then there is only one caption for all Sv if n fin 0 br di ie n fin 1 ie n dn lt n v ce el QP fig el nf in u indent QP indent is 5n 11 is 5 25i ds indent fig fi lil in nr fin 0 NE m EX Where Dean s changes end UM par start 0 O0 nr n ev ai n n ev PI July 2001 Groff and Friends HOWTO Revision 1 28 38 10 5 Equation Numbering and References QN This last macro sets me up for referencing historical i e those we ve already formatted and future equa tion references To get the latter to work you have to run groff twice The first time it complains and inserts a note into the text for equations that it couldn t find As equations are found however their refer ences are added to a text file which is read by the second groff run automatically Thus the second time through the macro locates the future reference and inserts the correct equation number in the text This is a little more sophisticated than the figure macro and someday soon I ll probably make FI work more like QN As an illustration I might code an equation and give it a label with the QN macro Then I can refer to it later as follows a b c 1 In equation 1 we saw that we could add two variables to assign a value to the third This was coded as ON A sample EQ ON R sample we saw that we could add two variables to assign a value to the thir
10. and DVI devdvi Inside each of subdirectories corresponding to the supported devices all are found in usr share groff font is a file named DESC The DESC file contains name and values such as print and paperlength This latter name indicates the length of a page in points per inch times sizescale units On my machine here in Canada the default paper size is US letter On machines in Europe and elsewhere A4 is commonly used Since A4 is longer than US letter the value of 792000 which is 11 inches multiplied by 72 points per inch times 1000 the value of sizescale A4 would use a value of 841890 which corresponds to a paperlength of 297 mm To account for a different paperwidth US letter is 216 mm or 8 5 inches and A4 is 210 mm or 8 27 inches macro calls for page offset line length and other parameters should be made For the ms macros July 2001 Groff and Friends HOWTO Revision 1 28 62 see the table listed earlier in this document 15 4 How Do I Convert PostScript to ASCII or HTML PostScript to ASCII conversions may be performed via ps2ascii This program is a Ghostscript translator from PostScript or PDF to ASCII i e plain text Apart from first converting PostScript to ASCII and then adding suitable formatting commands to generate HTML I have no idea how one can convert directly to HTML 15 5 How Do I Convert groff Source to HTML From Gaius Mulley comes the following answer Use the Thtml devic
11. indent Start displayed text with keep of type block centered B same as BD centered C same as CD indented I same as ID left centered L same as LD or right aligned R same as RD Type I is the default Note that DS tries to keep all the text on a single page while the macros similar to DS do not Thus if all the text cannot appear on the current page a page break occurs if DS is used Place the specified text left center or right in the footers for all evenly numbered pages One or more of the text strings may be omitted but all single quote marks must be given Place the specified text left center or right in the headers for all evenly numbered pages One or more of the text strings may be omitted but all single quote marks must be given End an equation which was begun with EQ LT Commence an equation x may be L I or C corre sponding to left indented or centered alignment y is an optional equation label use quotes to enclose multi word labels End a footnote Create a numbered footnote paragraph Commence a footnote which is terminated by FE Optional label label will appear as a superscript at the beginning of the footnote The user should cause the same label to appear in his text as a superscript possibly by enclosing it as label An alterna tive is to use the automatic numbering scheme afforded by the V macro place this macro at the appropriate place in your
12. 1 11 now calls grefer refer Note that as refer is a pre processor it isn t controlled by if or ie constructs REFER PREFIX refer TROFF OPTS etpU n P o 0 HTML OPTS S TROFF_OPTS P a VPATH RCS CO co The refer options are e accumulate references to the end or until I SLISTS is encountered S set default bracket labelling and label contents REFER OPTS e S Where my bibliography is stored File refer is the index into the actual bibliography refer will complain but find the text file it needds anyway as the path is stored in the index DATABASE home provinsd bibtex refer Various scripts that I use to clean up or modify the groff input or ouput are contained in this directory SCRIPTS home provinsd docs s scripts Send output to the printer via lpr2 double sided printing Invoke it for groff file file s as make file lpr2 This will generate a PostScript file and then run the shell script lpr2 Revision 1 28 Groff and Friends HOWTO July 2001 57 onthe output ps lpr2 5 lpr2 lt Check spelling in the source file sS 8ps Sus ispell Format mgs groff source file and send to ghostview ps gv s gv ps Format mgs groff source file and send to Postscript printer lpr Se Ipis 5 8 lpr ps Wocho fesesoneseue Print job for file ps spooled H Format mgs g
13. KF and KS for a description of the types of keeps available Begin a collection of lines of text which will be kept together as a keep This keep is known as a floating keep in that if there is insufficient room on the current page for the entire block then it will be placed at the top of the next page See also KS Begin a collection of lines of text which will be kept together as a keep This keep is known as a fixed keep IF there is at least one line of room available for output text on the present page then this collec tion will be added to the current page Begin a left justified display without a keep Com pare with DS L Increase the point size of the text by 2 Commence a left justified paragraph Begin outputting multiple columns of width width The width parameter should be specified in units like inches such as MC 21 Prevent the placing of the date in each page footer see DA Place text on the cover page Place a numbered chapter or section header in the output the header text follows on the next line or lines until a LP or other paragraph macro is encoun tered A level of zero or one or if none is specified causes a section header of the highest level to be cre ated Levels 2 through 4 are subordinate i e level 0 would appear as 1 Title and level 2 would appears as 1 1 Section If start level is specified and level equals S then the current section number is set to that value such as NH S 3 wou
14. This document then will describe how one can profit by the use of groff to generate high quality articles reports and even books many of which have been written using groff or troff See for example Dougherty 1987 Kernighan 1974 Kernighan 1976 and Sequin 1975 to name a few 2 Disclaimer This document is intended to be one that assists new users by introducing them to groff and friends It is not intended to be a definitive reference manual Other documents cover these subjects very well and are available either with the current distribution or at a web site identified in the sequel groff comes with well written man pages that describe the differences between groff and troff These with the aforementioned reference documents are all that have been available for some time Under development however are com plete reference documents for the groff suite Given the nature of this document and the availability of other documentation please do not hold me responsible for any damages that you or your organization may incur as a result of using the groff suite or this HOWTO As with other free software you use it at your own risk No one associated with this soft ware this document or any others mentioned herein has intended that you incur any damages All prod ucts described here are made available freely with the hope that they benefit you as much as they have ben efited us 3 Credits and Copyright The groff document preparation sui
15. blank line unnumbered and at line 9 I have given a tbl command T amp which says that I wish to restate the format of the columns which I define on the next line ending it in a period Just for fun and to illustrate how one can enter long strings of text although mine is very short I have illustrated the use of the text block entry commands T and T These must appear as follows Enter the T as the first two characters immediately following the tab or the first two characters if the text block belongs in the first column Place the T on the line immediately following the last line of text in the block If another column follows enter the tab and continue with that column s text The tbl program will wrap blocks of text into a single column for you As you can see tbl wraps the text where it likes not necessarily where you would like nevertheless text wrap especially in the last column can be very useful 7 Equations groff has excellent support for mathematics Virtually all the math symbols that you might like to use are available You can code sums integrals matrices simple or complex algebraic statements in near English For example a matrix is identified by the same word matrix Columns of the matrix are identified as left 13 In my documents for historical reasons I set these as the equation delimiters More typically you would use two symbols or any character that you would never use in your equa
16. completeness and not necessarily because they are good I include them here with some short explanation I have no doubt that long time users of groff have even methods of accompishing their goals and I dully expect to be able to include their implementations in future versions of this document If you have some preferably robust methods of customizing groff please contact me so that I can include them and give you the credit that you deserve In the mean time here are mine 12 1 Scripts to Strip Redundant Customizations The first three I call refer script eqn script and eqn2 script They are used to generate PostScript output without a table of contents or index being included Here is refer script n A sed script to remove all references to ref s or L references s after the first refN s x s refN s t already there x h p already there d p Here is eqn script n A sed script to remove all references to eqn s after the first eqn s x s eqn s t already_there x h P already there d Revision 1 28 Groff and Friends HOWTO July 2001 45 Line must be OK print it p Here is eqn2 script n L A sed script to remove all references to second and subsequent EQ delim EN invocations N EQ I N N s delim n EN 1 t got_it p b end got_it x s delim n EN 1 t end end 12 2 Creating
17. in groff and so may be defined by the user Cover Page AB no Begin the abstract on the cover page ending it with AE no means do not label the abstract Cover Page AE End the abstract Cover Page AI Print the name of the author s institution which should appear on the next line Multiple line entries should be separated by br in column 1 Cover Page AU Print the author s name which should appear on the next line This macro normally follows TL and pre cedes AI Cover Page TL Set the title which is all following text up to the next macro command generally AU in bold text two points larger than the default font size Document Format RP no Format the document in released paper format If no is used as the argument then suppress the title on the first page Document Format TM This macro is not implemented in groff but was used Index Mathematics Mathematics Page Format Page Format Page Format Page Format Page Format IX a b c d EN EQ x y AC AC BD BT text CD to set documents in the University of California thesis format It may be defined by users for their own pur pose Place up to 4 index words or phrases if surrounded by quote marks in the error output file after append ing the arguments to IX with the current page num ber It is up to another program or script to format these additional data for inclusion into the final docu men
18. lines of text are not processed by the UL macro Place the word UNIX in the text the first time the macro is used but only the word UNIX on subse quent invocations If text multiple words allows if enclosed in quotes appears on the macro command the text will be appended to the word UNIX This is useful for adding punctuation Add an entry to the table of contents If no appears as the first argument then do not include the page number The indent determines the relative horizon tal position of the entry in the generated table Terminate the addition of a single or multiple entry to the table of contents Compare to XS and XA Commence a paragraph with the first line having no indent but with subsequent lines having an indent equal to the value of number register PI default is 5n Subsequent paragraphs will all be indented Add an entry to the table of contents if no appears then the page number will not be included If page i e a page number appears then that page number will be used for the entry The indent determines the relative horizontal position of the entry in the gener ated table July 2001 Groff and Friends HOWTO Revision 1 28 The following is a listing sorted by macro type 25 Functional Listing of ms Macros Type Macro Description Bibliography BR In some version of the ms macros commence the bib liographic format i e precede a bibliographic record This is not used
19. man groff_char you will see what characters and math symbols you can use This man page lists input codes from 33 to 255 with a few omitted To employ any of these other than those that you can type directly on the keyboard numbers 33 to 96 and 123 to 126 inclusive simply code them as N num where num is the numeric input code For example to print ydieresis number 255 code it as W 255 to yield y Symbols that lack numeric input codes all after number 255 have textual codes like D whose PostScript name is Eth the symbol immediately following code number 255 Using the given coding an Eth would look like D 7 4 Equations and Comments You should know that the equation processor doesn t seem to recognize comments That is if you place the sequence before some text that you wish to comment out then eqn will happily interpret it if inside an EQ EN pair Furthermore the pair ig doesn t work within an EQ EN pair Either will pre vent the equation processor from interpreting inline equations though 8 Figures Figures may be used in groff documents with limited positioning capability The default position of a fig ure is in the center of the page assuming a single column of text One may also place a figure as a left jus tified or right justified object Unless you take care to use certain troff macros which I will explain in a moment no text can appear nor can multiple images appear at
20. say that you read the dependencies such as S ps s as a file ending in ps depends on one depending on s and that file is named something like name s The word name in make speak is the name without a suffix of the current prerequisite that has been July 2001 Groff and Friends HOWTO Revision 1 28 54 modified more recently than the current target Please refer to Oram 1991 for all you might want to know about make This generic makefile for GROFF source using the gs macro package which is the equivalent of the ms macros will generate from a file name file s the following Starting output page number is defined by Make Environment variable P To set it from Make s command line use Fur gt make file P n where n is the page 4 To output selected pages use Make Environment variable O To set it from Make s command line use an optionally comma delimited list make file O n n m m n where n is a specific page n m is a range m is UP TO page m and n is FROM page n gt make file gvx output groff to ghostview with TOC INDEX gt make file psx output groff to PS file with TOX IDX gt make file gv output groff to ghostview without TOC IDX gt make file lpr output groff to PS printer without TOX IDX gt make file ps output groff to PS file without TOX IDX gt make file lp output groff to more without TOC IDX gt make file txt output groff to text file without TOC IDX
21. sqrt c d which yields a b c l c and r represent left center and right Vo d P alignment of the expressions Notice that braces are required to identify all the terms in the pile matrix lcol ccol rcol These are used to construct matrices such as left matrix lcol a above b c ccol d e above f rcol eqn 1 above eqn 2 right which yields a d e eqn 1 b c f eqn 2T required to identify all the terms in both the matrix and each of the columns Notice that braces are July 2001 Groff and Friends HOWTO Revision 1 28 24 Key Words for Describing Equations Term Description dot dotdot hat tilde bar vec These terms which follow the expression to which dyad under they apply provide diacritical marks For example a dot b under c vec d dyad looks like b c d mark lineup If mark is used in an equation then the position at which the next mathematical symbol in the expres sion is remembered Subsequent equations which include lineup will cause that equation to be aligned with the previous equation If not used and EQ and EN have no alignment specification on the macro invocation then each equation will be centered define Keywords may be aliased by means of a define state ment within a EQ and EN pair For example one could tire of writing cos theta many times so one could say define ct cos theta Subsequent uses of the term ct would be replace b
22. symbols before indented paragraphs but optionally numbers of letters This one I called BU and I use it frequently For something as simple as double spacing I created DB and for a draft version of a document I created DM which calls DB It also prevents all images from appearing and consequently renders faster on my screen To specify headers and footers easily I added DO which takes as its first argument your specification of which of 3 headers or footers you wish to set and as its subsequent arguments the text you wish to place there If you write mathematical text then you ll soon want equation numbering to be automatic and for that mat ter you ll probably also want your tables and figures to be numbered For these I created created table and figure numbering macros and altered the equation macro EQ to automatically number all my equations The following illustrate most of my macros They aren t elegant I can t even guarantee that they are bug free but they work for me most of the time If you use them and run into difficulties please feel free to contact me and I ll try to assist If you have a suggested fix so much the better 10 1 The Bullet Macro BU The macro creates bulleted indented paragraphs by default The symbol can be changed at will Given one of 6 option letters plus a number i e two arguments numbered lists can be created The syntax is BU nI IN i lllalA num symbol The list must b
23. table exceeds a single page This requires the use of option H on the TS invocation Table Format TS H Begin a table to be formatted by the tbl processor generally invoked with the t option to groff If H is specified then the table will have a multi page header see TH Table of Contents PX no Print the table of contents If no is used as the argu ment then no title is added Normally this is invoked by the TC macro Table of Contents TC no Print a table of contents page with the first page hav ing page number one set in Roman numerals Com pare to PX which does not alter the page numbers in any way If no is specified then the title Table of Contents is not printed Table of Contents XA no indent Add an entry to the table of contents If no appears as the first argument then do not include the page number The indent determines the relative horizon tal position of the entry in the generated table Table of Contents XE Terminate the addition of a single or multiple entry to the table of contents Compare to XS and XA Table of Contents XS page no indent Add an entry to the table of contents if no appears then the page number will not be included If page i e a page number appears then that page number will be used for the entry The indent determines the relative horizontal position of the entry in the gener ated table Text Format AM Create better accent mark definitions
24. text and then use FS FE without any label Place the specified header text below the normal page header Print text in italic See also B BI and C Begin an indented display without a keep meaning that the display will commence immediately and carry onto the next page if necessary Compare with DSI Commence a new paragraph with an optional hang ing word or phrase if surrounded by quote marks The amount of indentation may also be specified such as IP Label 1 li which will add the text Label 1 to the output and indent all following lines by 1 inch Revision 1 28 Groff and Friends HOWTO July 2001 Alphabetical Listing of ms Macros Type Macro Description Index Page Format Page Format Page Format Page Format Text Format Paragraph Format Page Format Page Format Section Header Text Format Page Format IX a b c d KE KF KS LD LG LP MC width ND text NH level start level NL OF left center right Place up to 4 index words or phrases if surrounded by quote marks in the error output file after append ing the arguments to IX with the current page num ber It is up to another program or script to format these additional data for inclusion into the final docu ment See elsewhere in this HOWTO for a possible script End a collection of lines of text which together will be kept together as a keep See
25. the Cyrillic PostScript font Some of these may coincide with the iso 8859 5 encoding others may be different In that case what you need to do is to define a translation for the anomalous codes as above so that you can type the characters normally using the keyboard they will print correctly and you will also see them on the screen correctly In the first place this is a lot of work but once it has been done you will have an easy life The best of luck Ted 15 9 What is the Meaning of Double Quotes in Macro Arguments Ted Harding answers this curious question The special meaning of the double quote character in macro arguments is to group space sepa rated elements into a single argument However in that context the opening should be pre ceded by a space and the closing should be followed by a space 15 10 Footnotes and Indented Paragraphs An unfortunate bug exists in groff in that attempting to set an automatically numbered footnote on the hanging text of an indented paragraph exists Specifically trying the following IP word some text will result in the correct footnote number in the footnote but an incorrect number in the text it is incre mented by one From that point on the footnote numbers in the text are in error Revision 1 28 Groff and Friends HOWTO July 2001 65 15 11 Where can I get Windows binaries of groff Thor M Gil has ported groff to Microsoft s most recent operating system
26. the Index I create table of contents entries and index entries in a rather convoluted manner The process involves 4 scripts and 3 other invocations of sed plus uniq and sort These last 5 processes are shown in the makefile so I will not repeat them here The other four scripts follow The first is a shell script that adds table of contents entries to the source file It looks for numbered and unnumbered chapter and section headings and adds the appropriate source lines Here is toc script n toc script A sed script to add Table of Contents entries to a groff file intended for use with the gs Gnu s version of ms macro package The n on the first comment line inhibits printing This script also searches for BOLD and ITALIC invocations B I and uses these to create INDEX entries Search for the Numbered Heading command NH n July 2001 Groff and Friends HOWTO Revision 1 28 46 NH gt p n P s N SN iN XSN if n nh hl lt 2 NON ps n s 4 n nh hl N SNIN ti m n nh h1 1 p a ps XE Search for the Section Heading command SH Note that the dummy substitution is needed for the final test to avoid printing the section header line twice SH gt p n P S N N N1 iN XSN ti n n nh hl p a XE Watch for refer invocations save the last invocation in the hold space FON 2 FNAL AONE ENTER Append the commands to read th
27. the notes for an approximation course that I took recently Notice the naming structure for the chapters in approximation The first is app 00 s and it corresponds to the cover page i e the title author and abstract Chapter one is in app 01 s and succeeding chapters have higher numbers For running through my Makefile this makes sorting easy For figures I usually use xfig but there are other programs that you may wish to use gnuplot comes to mind for numerical data Anything that can generate encapsulated Postscript files is suitable except if you plan to create an html file with groff This requires a PNG or GIF file I create the former when needed for html output with the convert program that comes with the ImageMagick package It does a satisfactory job and also has a screen capture program import that can be useful at times Revision 1 28 Groff and Friends HOWTO July 2001 53 home provinsd docs lee sS other document types ci E e tmac ds Makefile scripts odds ends approximation more subjects hee ae RCS linked to Makefile Makefile app 00 s app O0Ls m more chapters app 99 s app Ol eps app 01 fig app 02 eps app 02 fig more figures Figure 3 How documents are organized on my system Files are underlined and the Makefile in the exploded subdirectory is linked to the Makefile in the parent directory The file named tmac ds contains my personal macro
28. the same vertical place as a figure This is not overly restrictive as centered figures stand out well on a printed page Both the figures of example printed pages seen earlier are typical groff accepts encapsulated PostScript as the only figure format when using the ms macros When using the HTML macro packages both GIF and PNG format images are acceptable Encapsulated PostScript is simply a PostScript file that contains a BoundingBox comment near the begin ning of the file This box describes the x and y limits of all ink which is to be placed on the page To introduce a figure to a document the PSPIC macro is employed It takes several arguments as July 2001 Groff and Friends HOWTO Revision 1 28 26 described in the man page for grops To summarize the macro command has the format PSPIC L R I n file width height The graphic is indicated by file e g my pict eps and the width and height that you wish the illustration to have is indicated by width and height which may have scale indicators attached The default scale is inches i Other units include points p and centimeters cm For the complete list please see the troff docu mentation referenced earlier The PSPIC macro scales the width and height uniformly so that it is no more than width wide and height high If either L or R are specified the graphic is positioned as a left aligned or right aligned illustration The I option allows the gr
29. 2 Notice that I enclosed the sin theta expression in curly brackets They ensure that I can use st as the numerator in a fraction without having to remember to enclose it in the brackets This saves additional keystrokes Using additional braces does not affect the operation of EQ 11 2 Reference Customization In a manner similar to customizing equations you can set up your references by means of a definition file I use the following and find it quite adequate although recently an individual indicated that it was non standard You be the judge The definitions that I use and show here were used to format this document SN SMUOO How I like my bibliographic references formatted xkx QNM XM R1 accumulate bracket label et al et al 12 3 date as label D yD y a D y qualifies the date in the reference text no label in reference removes label in reference list label D y a adds disambiguating letter in text and label sort A D sort by first author surname then by date move punctuation R2 July 2001 Groff and Friends HOWTO Revision 1 28 44 12 Useful Scripts If you examine my makefile in detail you ll see that I invoke several scripts These are not required for normal processing with groff and friends I use them to generate an index and to remove duplicate refer ences to my reference and equation customizations see the previous section For the sake of
30. 28 Groff and Friends HOWTO July 2001 23 7 1 Key Words for Equation Setup Other key words are described in the following table Key Words for Describing Equations Term Description sub sup These terms indicate subscripts and superscripts Order is important as A sub i sup j which yields A j is different from A sup j sub i which is A You might also want A which results from A sup j sub i over This is used to create fractions such as a over b which creates zi and a sin theta cos alpha sup 2 over sqrt b sup 2 4 a c which creates a sin 0 cos amp Vb2 4ac sum int from to inf These terms are used to create sums and integrals with optional limits One can have sum from i 0 to inf a sup 2 sin theta int from 0 to pi cos alpha d m alpha which yields Y a sin cosada i 0 0 left right These two terms allow one to bracket expressions with round or square parenthesis such as left x sup 2 left y sup 2 over alpha right sin theta right 2 which yields E Jine Note that the right a clause is optional but the left must appear if a right is required Use a dummy left such as left which means no symbol One particular variation are the phrases left floor left ceiling right floor and right ceiling When used between EQ and EN these produce hooked bracket pairs Ipile cpile rpile pile Piles produce vertically aligned equations such as Ipile a b c above
31. 3 01 eps 407 fig 03 02 eps 407 fig 07 01 eps 407 fig 07 02 eps cat 407 gt 8 14 Formats Other Than PostScript The default output device for groff is PostScript a page description language developed by Adobe Systems Incorporated PostScript is the traditional output format for many UNIX programs that generate formatted text For information about PostScript see either or both Geschke 1985 or Warnock 1985 Revision 1 28 Groff and Friends HOWTO July 2001 61 The T option on the groff command line allows the user to select any of several output devices Those available include the TEX dvi format a device independent format which requires further processing before printing much like the the groff system works X75 and X100 X11 preview formats ascii for typewriter like devices and latin1 for typewriter devices using the ISO Latin 1 character set With release 1 15 of groff comes also html format 15 Questions About groff Some With Answers 15 1 How Did You Create the TEX symbol To be honest I had to copy it I found the appropriate troff codes in a manual page which one I have for gotten but it was on my Linux system The string definitions are sif t ds TX N RTNWh 0 1667m v 0 20v E v 0 20v NNh 0 125m X fP if n ds TX TeX if t ds LX f RL h 0 36m NNv 0 15v NS 2ANSONNMh 0 15m NNv 0 15v N PN TX if n ds LX LaTeX The if statements mean that if troff or groff is r
32. FS label HD header text ID indent KE KF KS B same as BD centered C same as CD indented I same as ID left centered L same as LD or right aligned R same as RD Type I is the default Note that DS tries to keep all the text on a single page while the macros similar to DS do not Thus if all the text cannot appear on the current page a page break occurs if DS is used Place the specified text left center or right in the footers for all evenly numbered pages One or more of the text strings may be omitted but all single quote marks must be given Place the specified text left center or right in the headers for all evenly numbered pages One or more of the text strings may be omitted but all single quote marks must be given End a footnote Create a numbered footnote paragraph Commence a footnote which is terminated by FE Optional label label will appear as a superscript at the beginning of the footnote The user should cause the same label to appear in his text as a superscript possibly by enclosing it as label An alterna tive is to use the automatic numbering scheme afforded by the V macro place this macro at the appropriate place in your text and then use FS FE without any label Place the specified header text below the normal page header Begin an indented display without a keep meaning that the display will commence immediately and carry onto the n
33. IC codes PE NA B2 ENT FI P aun first of possibly several line s of descriptive text PSU LP A UO zem a single blank line N E Nn ds FIGURE Figure nr nmbr 0 de FI nr nmbr 0 ie NASI N NAN NUM 2 NV test second arg for inc decrement ie NN num nr nmbr 2 make a note of the value shift 2 V discard N and inc decrement el shift 1 nr fg n nmbr ft B 2 FIGURE NN Ch Nn g NN PNNS1 nr fg n nmbr Added option for FI P linelength linestart recommend ONU VERD 5I25 5n to make it look like a QP entry el N N ie S1 P ie NX4 2 tm Warning Figure Fg caption length missing near line n c nr nbr 10n M n s 10 11 u n 1 n nbr nr nbr 5m Ww NXNmLosS 5 ds indent n nbr el 11 2 if 3 ds indent 3 nr fin 2 br di fig ft B FIGURE Fg ft x Revision 1 28 Groff and Friends HOWTO July 2001 37 nr fg 1 ds Fg NN Ch NW n g nr fG 1 el br new method is to capture text up to LP and decide then dr fug NV by processing the diversion fig Old method was QP nr fin 1 ft B FIGURE Fg fi r nr fg 1 ds Fg Ch n fg nr fG 1 ENI a RU KCkCkck ck k ck ck kck ck ck kck ck KK KK KKK kc kk X LP my re defined LP IlaCro F M X kk kk k kk ck k kk kk SN de LP Sx sAN Where Dean s changes occur SN Assumes all figures centered on page column or if
34. N 241 where in this example the 241 is the decimal form of the octal 0361 The groff escape sequence N 237 causes the character with octal code 0361 in the correct font to be printed So you must make sure that the current font is the Cyrillic font when this is printed e g by using f or the request ft on a line by itself where is the name of the font i e the name of the font file you were looking at above such as f CCy or ft CCy Once you have got this information you can then link this to your input Myself being primarily in a Latin environment with Cyrillic being required exceptionally I use two schemes One is for single Russian words or very short pieces of Russian text and is based on transliteration For instance the Russian YA looking like an upper case reversed R is denoted by the groff escape YA Similarly the lower case version is Mya This is pre defined in private macros by char YA N 241 This character is at 241 in most but not all of the Cyrillic PostScript fonts which I have Therefore if that is also the case with you you should switch to Cyrillic using a macro like Cyr fnt fontname tr xx N nnn SEDES If the Cyrillic character encoding depends on which font you are using it might be better to make the name of the macro the same as the name of the font Then you can use font specific translations The other for ext
35. N N nul tee a sed e t s NANQCLUEN NINA tee b Sort pf Sr 0 4 4n tee c uniq tee d sed e s N N18 tee d N awk f SCRIPTS index script S tee_e awk f SCRIPTS format script S tee_f sed f SCRIPTS title script tee x N cat gt x echo File var tmp x created for use by groff Format mgs groff source file which now includes an Index and Table of Contents and send to ghostview x gvx var tmp x echo echo Running groff on updated source file echo cat toc I sed f S SCRIPTS refer script ho sed f S SCRIPTS eqn2 script SOELIM I N S REFER S REFER OPTS p DATABASE S TROFF S TROFF OPTS S MACRO Tps gt ps 2 dev null gv ps echo Processing of updated source file complete Create a postscript file with Table of Contents and Index X psx var tmp x echo echo Running groff on updated source file echo cat toc EN sed f S SCRIPTS refer script LA sed f SCRIPTS eqn2 script SOELIM LA S REFER REFER_OPTS p DATABASE IX S TROFF TROFF_OPTS S MACRO Tps gt ps 2 gt dev null echo Processing of updated source file complete Do a make file egz to copy into RCS an eps file as a compressed 3 version Note that the dependent source file file s needs July 2001 Groff and Friends HOWTO Revision 1 28 60
36. S 5 5i FM footer margin next page li HM header margin next page li LL length of a line paragraph 6i LT title length next page 6i PD inter paragraph distance paragraph 0 3v PI paragraph indent paragraph 5n PO left margin next page li PS text size in points paragraph 10 QI quoted paragraph indent next QP 5n VS spacing between lines paragraph 12 ms Macro Number Registers Sorted By Function Name What it Controls When it Takes Effect Default Value DD distance to display displays 0 5v FM footer margin next page li HM header margin next page li LL length of a line paragraph 6i PO left margin next page li FF footnote format next FS 0 1 20r3 FI footnote indent next FS 2n FL footnote length next FS 5 5i PD inter paragraph distance paragraph 0 3v PI paragraph indent paragraph 5n QI quoted paragraph indent next QP 5n VS spacing between lines paragraph 12 PS text size in points paragraph 10 LT title length next page 6i Note that the footnote format has more than one possible value If set to 1 footnote superscripting is sup pressed If set to 2 indentation of the first line is also suppressed If set to 3 the footnote resembles an IP like footnote paragraph Why might you require the number registers If you were a writer or perhaps a student that wanted to for mat some document in a particular manner say for their thesis then these registers would allow you control th
37. an eject sp n p u STILL not at top of page probably a diversion so eject UNS ex Test if odd page continue else test Thesis mode NT if Thesis mode continue else print heading and eject sA if e if thesis 1 ce l place our message at the top of the page d ft R PAGE ft P sp n p lu NV go to next page then reset footers if NN RF References ds RF if NN RF Index ds RF OE NNEELEDUNN ICE UNN ERE EF NN RE ANN CE NN LF NT a NOAIT NT m Now on correct page change footers NT OF NNA LE NN CF NN RE EF NX RE NN CF NA EF NJ if n an gt 0 July 2001 Groff and Friends HOWTO Revision 1 28 oe VN SN SN sx VN de ie SN el A A ae p ae nr 34 EOKCkCk kc k kk KKK KKK ck kk KKK ck ck KK k k KK KANE macro modified ck ck ck ck ckck ck ck ck ck ck k kk kk kA In macro package ms add chapter stuff to macro NH Most of the following is from the supplied tmac gs macro package NH ANSI S shift nr nh hl 0 while n nr nh hl 1 nr H n nh hl ON shift if n nh hl nr Hil 1 nr nh hl 1 error missing arguments to NH S nr nh ohl n nh hl ie n NN nr nh hl 0 S 1 ie n nh hl lt 0 nr nh ohl 0 nr nh hl 1 el if n nh hl n nh ohl gt 1 warning NH n nh ohl followed by NH n nh hl1 el nr nh hl 1 while
38. aphic to be indented by n units of the indicated type If you wish several graphics to be placed at the same vertical position say one left aligned and the other right aligned then you must use certain troff commands Basically you must mark your current position on the page with the mk command and after drawing the first graphic return to that position with either the rt or sp commands As an example let us draw the same rather simple figure three ways We ll position it on both edges of the page and will place it between the other two The macro call to display the graphic sample eps is spr flush all text out first snr p define number register p mk p NV note the present vertical place on the page PSPIC L sample eps 1 5 NV left justified image 2 inches maximum dimension sp 0Ou return to that place mk demonstrate the other mark method PSPIC sample eps 1 5 centered figure att and how we can return to the other mark PSPIC R sample eps 1 5 right aligned figure The result is A limitation of illustration inclusion is that there is no caption capability included with the ms macro pack age I handled this initially by using quoted paragraphs on centered illustrations For example using the same figure as before I would code br PSPIC sample eps 2 OP Figure5 3 This is the caption for my illustration Notice that I used a program called xfig to create it bP This results in the
39. bliographic Database Identifiers Letter Code Description A An author s name in the order first name followed by last name If an author has several names or initials as in Joe B Smith or J B Smith then all of the first names or initials should be linked together by means of the troff code X0 Thus you would code Joe B Smith as Joe OB Smith and this would be placed exactly one space after A The title of a book that contains the article to which you are refer ring See also E The date of publication of the book or article For an article in a book the name of the book s editor See also B The name of the publisher The name of the journal containing the article The journal issue The page numbers of an article The title of the article or the book The volume number of the journal ios H udZzc mgog A few sample entries in a bibliographic database follow oe D Brian 0W Kernighan Murray Hill New Jersey 07974 USA May 1991 AT amp T Bell Laboratories dP oe oe oe DHUA Computing Science Technical Report No 116 oe H PIC A Graphics Language for Typesetting User Manual oe D James 0W Cooley JohnNVOW Tukey 1965 Mathematics of Computation 90 297 301 An Algorithm for the Machine Calculation of Complex Fourier Series 19 ae de oe oe oe cde oe Z4 Hw 24 UO Pp oe D Weikko A Heiskanen oe D Helmut Moritz oe El Graz Austria 1966 Instit
40. char t s n sc ps T s n cap PS char u s n sc ps U s n cap PS char v s n sc ps V s n cap PS char w s n sc ps W s n cap PS char x s n sc ps X s n cap PS char y Ns NWMn sc ps YNs NNn cap PS char z s n sc ps Z2 s n cap PS de smallcaps rcharabcdef ghijklmnopqarstuvwxwyz LP This Line Will Be In Ordinary Capitals And Lowercase Letters LP smallcaps This Line Will Be In Small Caps Instead Of Ordinary Capitals And Lowercase Letters smallcaps LP This Line Will Be In Ordinary Capitals And Lowercase Letters This Line Will Be In Ordinary Capitals And Lowercase Letters Tuis Line WILL BE IN SMALL Caps INSTEAD OF ORDINARY CAPITALS AND LOWERCASE LETTERS This Line Will Be In Ordinary Capitals And Lowercase Letters Ted added in a subsequent Email that in most cases these macros while set up only in terms of the ASCII characters A Z work for many cases of accented characters as well July 2001 Groff and Friends HOWTO Revision 1 28 42 11 Customizing Equations and References 11 1 Equation Customization As I learned more about groff and used it for some course notes I was making I soon discovered that it would be much easier to use abbreviations for some terms in the many equations that I wanted to format The eqn package provides such a facility For the bulk of my writing such as it is I invoke my standard abbreviation file at the beginning of each chapte
41. copied the Cyrillic fonts to groff i e you have installed them as groff fonts in groff fonts devps you could handle this according to some variant of one of the two following methods METHOD 1 Look in this directory at the font file for a particular font e g I have a font which I pulled from the Web called College Cyrillic whose font file I have called CCy quite arbitrarily to Revision 1 28 Groff and Friends HOWTO July 2001 63 which the following applies This may start with a list of kernpairs but in any case you will come to a line with the word charset After the charset line you will see several columns of information the number of columns depends on the font most of which is font metrics one line for each character Some char acters will be Latin others Cyrillic The first column will be either a single ASCII character a groff name for the character or The last column but one will be an octal number of the form Opqr For instance the standard octal code for the letter A in English is 0101 In decimal this is 65 which is the ASCII code for A The rule for conversion from octal Opqr to decimal is 64 p 8 q r You now need to identify which decimal codes correspond to which Cyrillic characters if they also have groff names so much the better but it doesn t matter The most direct way to do this is to print out a table consisting in groff input of lines like 24
42. d Shown here are my modified EQ macro and my QN macro LN EESEESE EU SDE TA UE UESE EUR UESESUE IUE UN EUR ES Uie SK BC macro modified xwkk kk d ee x x A In macro package ms add automatic equation numbering to EQ ENN Most of the following is from the supplied tmac gs macro package SA de EQ ds eqn num 2 ie ANSI L nr eqn type 0 el N N ie NNS1 I nr eqn type 1 el nr eqn type 2 if 1 C ds eqn num 1 F SN NM kk k kk kk kkkkkkkkkkkk k Dean s additions x xxkxkXkk kk kk k kk kk ko ko kk ko if eqn num ds eqn num Eq nr eq 1 ds Eq Ch n eq SN 2 Nat kkk kkkkkk k Back to the original EQ Stuff N k k kkkkkkkkkkkkkk kk di egn div in 0 DE Revision 1 28 Groff and Friends HOWTO July 2001 39 NA COE KR KK KE KK ok ke RK o ke S ORE KH KK OK OR KKK KK CONT macro KKKKKKKKKKKKKKKKKKKKKKKKKKKKKK SN N This macro simply prints equation in the text with possibly N trailing punctuation It also allows for referencing an equation NM To assign a label reference the current equation use SN VR QN A label single word VN To refer to an equation by label reference use a NM NR QN R label punct ENT To refer to an equation by increment use NT E ON N offset punct NT ds EQUATION equation ds output doc ref ds references doc ref de ON if references
43. d it as EQ P sub n m cos theta 1 over 2 sup n n t t sup 2 sup m 2 d sup ntm over dt sup ntm t sup 2 1 sup n EN Here is another expression a discrete Fourier transform k N 1 _i2a jk F AD Y f Ane N n 0 1 N 1 j 0 It was coded as EQ F k over N DELTA t sum from j 0 to N 1 f j DELTA t e sup i 2 pi jki ov N mo Uy ly wes y NSI EN As you can see an English like syntax using tokens that generally represent the mathematical symbols allow you to describe fairly complex expressions Each token is separated from all others by white space i e space bar entries tab key entries or newline entries Four other special characters are used as follows eqn Token Separators Separator Use Braces Braces or curly brackets are used to group terms so that they may be acted on as a unit An example would be to take the square root of a b Without braces ie sqrt a b you get Ya b but with braces i e sqrt a b you get Va b Note that the braces do not require white space around them n double quotes Double quotes are used to separate text from an equa tion when used between a EQ and EN pair tilde A tilde represents a full space in the output That is it ensures that the math symbols are separated when printed normally eqn removes unnecessary white space Circumflex A circumflex provides half the space of a tilde Revision 1
44. d of each page via text If not specified the page title defaults to 96 where is the current page number Print the table of contents If no is used as the argu ment then no title is added Normally this is invoked by the TC macro Commence a paragraph that is fully indented on both the left and right hand sides This is often used for quotations Return to Roman font Note that there is no argu ment for this macro Compare to B BI and C all of which accept arguments Begin a right justified display without a keep Com pare with DS R Retreat one level of relative indentation See also RS Format the document in released paper format If no is used as the argument then suppress the title on the first page Indent by one level of relative indentation The amount of indentation may be altered by use of the troff command in default 5n within a RS RE pair such as RS in 10n text RS Create a new section using the line or lines follow ing up to another paragraph command like NH as a bold title Unlike NH this section will not be num bered Decrease the size of following text by 2 points Com pare to LG and NL Set the tab setting to to 5n This macro may be rede fined say as de TA ta T 2i fc which would cause text separated by colons to appear to separated by 2 inch tabs Print a table of contents page with the first page hav ing page number one set in Roman numerals Com
45. da Table of Contents 1 Introduction 2 Disclaimer 3 Credits and Copyright 4 ms Macro Overview 4 1 A Simple Example 5 Useful ms Macro References 5 1 Registers used by the ms Macros 5 1 1 Number Registers 5 1 2 String Registers 6 Tables 7 Equations i 7 1 Key Words for Equation Setup 7 2 Words with Special Meaning in Rai 7 3 Other Symbols for Use in Equations 7 4 Equations and Comments 8 Figures 9 References 10 Customizing and Creating ms Macros 10 1 The Bullet Macro BU a E 10 2 The AN Macro 10 3 Modified NH Macro 10 4 Figure Caption and Numbering FI 10 5 Equation Numbering and References QN 10 6 Small Caps 11 Customizing Equations and References 11 1 Equation Customization 2 11 2 Reference Customization 12 Useful Scripts 12 1 Scripts to Strip Redundant Customizations 12 2 Creating the Index 13 Document Organization and a Sample Makefile 13 1 The Makefile uw s xb Rath ded 14 Formats Other Than PostScript 15 Questions About groff Some With Answers 15 1 How Did You Create the TEX symbol 15 2 How Do I Convert This HOWTO s Source into Format XX Groff and Friends HOWTO 17 17 18 19 21 23 24 25 25 25 28 30 30 32 32 35 38 40 42 42 43 44 44 45 52 53 60 61 61 61 ii 15 3 How Do I Change the Paper Size 15 4 How Do I Convert PostScript to ASCII or HTML 15 5 How Do I Convert groff Source to HTML 15 6 How Do I Convert gro
46. dded to the package and also modified the supplied macros In the sequel I ll show some of these things so that you are left with a sufficiently comfortable feeling about what you can do and how you might go about it 4 1 A Simple Example Suppose that we need to write a short report It requires a title some author information and an abstract to precede several chapters or sections some of which may have subsections We can format it as follows and we ll see the result in Figure 1 1 SEE 2 Our Important Report 1999 2001 Dean Allen Provins 5 For the terms of this licence see the file COPYING that comes with the groff distribution 6 Some of us older folks found it rather enjoyable It sort of set apart the men from the boys so to speak 7 There are several macro packages available with the groff distribution including man ms mm and me see for example man 7 groff ms and man 7 groff me for details 8 I won t describe all as some are embarrassingly poor hacks July 2001 Groff and Friends HOWTO Revision 1 28 d AU 4 Dean Provins 5 AI 6 oted Author and Hacker gi Student of Life and the University of Calgary 8 AB 9 Noted author and hacker Dean Provins reveals all in the much heralded 0 HOWTO for MfIgroffNfP In this classic document Provins describes the 1 inner workings of one of the earliest machine document processing systems 2 available 3 Readers are encouraged to try any or all t
47. e Caption and Numbering FI The second last macro that PII illustrate is my figure captioning and numbering macro It permits me to automatically number and add captions to figures as well as refer back to figures by number An alterna tive scheme is used for equation references and I m considering modifying this macro to be more like the other I ll show you that macro next The figure macro will place a figure number in the text 1f the N option is invoked or expect a following caption if it isn t A short caption about one to one and one half lines requires nothing more than you type it in and follow it with my modified LP macro also shown here For longer captions you must usea P option at least until I make that the default feel free to add this yourself The comments in the macro should give you some insight into how it should be used NM SX EOKCkCk Ck k kk KKK KKK KKK k kc k KK KK k ck k kk k kFT Ina CroF M X XX kk kk ck ck k ck ck ck k ck KKK KKK KKK KKK NS The FI macro if invoked with an N argument print the word and July 2001 Groff and Friends HOWTO Revision 1 28 36 do nothing else If a second argument assume it is punctuation VR If no argument treat as a figure caption All text following N will be in italics Follow with paragraph command e g PP or LP ENT N Recommended coding m VN F or KS SNC O00 we a single blank line NM Bl NN PSPIC file eps size or PS P
48. e complicated The table capabilities of the groff suite are handled by a processor known as tbl To use tbl one needs to describe the general format it needn t be fixed for the entire table and then enter the text in a manner that indicates which text belongs in which column While I describe text as appearing in tables I know that equations can also be entered Whether figures can be or not is not something I have ever experimented with The only limitation that I have ever encountered with tables is the use to footnotes As I recall automati cally numbered footnotes are incorrectly numbered but we ll see if that still holds in the following exam ple Suppose that we have some names and telephone numbers of key individuals and that we would like to organize them in a table to be contained in a document The following might do the job for an individual who uses groff to keep his diary 1 SH 2 Another Day in the Life of Dean P 3 LP 4 Lately my life has become more complicated Now the boss wants me to 5 remember the names and telephone numbers of key suppliers and selected 6 contacts As if I don t already have enough to do Well my memory used 7 to be up to the task but in these declining years if I want to hang on 8 to this job I better work smarter I think I ll use that new fangled 9 groff program I hear it s great LO TS 11 center box tabo lt 12 cb cb cb cb 13 E n m pod Eos 14 Telephone Numb
49. e duplicate If you missed entering an author the output will show only a date If as I do you use the database to record journal names and library call numbers then strange looking references will appear in the output These really aren t refer problems but they are annoyances If you would like to recommend a replacement sed script that corrects any problems that you encounter I ll be happy to include it in the next release of this HOWTO and give you credit 15 16 How Do I Make the Output of gv Bigger If you re unfamiliar with gv then I recommend it to you and suggest that you explore its lengthy documen tation i e the man page But to answer the question and thus get you going try using the numeric keys above the QWERTY section of the keyboard Numbers 1 through 5 increase the font size in reasonable increments 1 414 2 4 8 and 10 times the original 20 The plus and minus keys do the same thing July 2001 Groff and Friends HOWTO Revision 1 28 68 15 17 How Can I Defer Page Numbers in a Floating Keep Steve Izma provided a solution to this perplexing at least to me problem It involves the use of transpar ent throughput section 10 6 of Ossanna 1992 In his reply to a writer who had created a figure macro called Fc which sent to standard error certain infor mation Steve suggested the following Since KF uses a diversion to capture the floating object you can delay the interpretation of n PN wit
50. e index file formatting in i e var tmp x and then add the Table of Contents to the output file If we encountered citations we ll have in the hold space t p x SPINS CEN PLL t got_refer a PGN Revision 1 28 Groff and Friends HOWTO July 2001 47 so var tmp xN DO LF DO RF abc b no refer got refer a PGN XSN ps n s 2 SpN ReferencesN ps XEN DO LF DO RF References SEN LIST PGN so var tmp x DO RF IG no refer Find all BOLD or ITALICIZED text B single_word OR B multiple words and use it to create index entries PX S BEVEL t If IX or IP encountered skip the line N IP gt b not this N IX gt b not thas p Delete the initial B I or BI S N BI S N BI Remove trailing punctuation do twice in case have B several words to generate several words in the output July 2001 Groff and Friends HOWTO Revision 1 28 48 Sc Cane Me CR Sis Sf PE Mes wey Strip s if they commence a line Q s GN 8 8 1 g s IX not this Strip the signs from the RCS stuff EF gt s gp N OFN s gp Print everything else t end p end Two of the other scripts index script and format script are awk scripts The third title script is another shell script The three fini
51. e look of the document I believe that WYSIWYG call the look of a document the document style For 10 Tn these tables I show only the default values for groff i e the equivalent to troff not nroff See the man page for details July 2001 Groff and Friends HOWTO Revision 1 28 18 example you might want unequal left and right margins Perhaps the left should be 2 inches and the right just 1 This can be effected by altering the left margin and length of line registers at the beginning of the document You would do this as follows nr PO 2i Hr Bh 5 53 If you also wanted to set 12 point type with a corresponding increase in line spacing you would use nr PS 12 nr VS 10 1200 1000 Why you ask did I use such a complicated formula for setting the line spacing Well groff doesn t sup port floating point arithmetic and to get a line spacing which is 2096 larger than the point size I simply multiplied by 1 2 times the sizescale parameter and then rescaled down the result to points by dividing by the sizescale parameter 5 1 2 String Registers There are also registersstring available for use in your documents These are tabulated as follows ms Macro String Registers sorted Alphabetically Register Name Function VO leading quote mark VU trailing quote mark Vv dash MO current month of the year DA current day of the month Ves automatically numbered footnote iun acute accent place before
52. e option ie groff Thtml filename troff gt filename html 15 6 How Do I Convert groff Source to ASCII From Gaius Mulley comes the following answer To generate ASCII from groff or troff source use the Tascii option on the command line to groff and pipe the result to col The command would be groff Tascii filename troff col bx filename ascii where the bx option replaces tabs with spaces and removes overstrike characters 15 7 Is There a groff info File Trent Fisher has contributed a rudimentary groff texinfo file and this is now a part of the groff distribution Should an interested party wish to extend this work their assistance would be gratefully received 15 8 How can I do Cyrillic with groff Recently the following question was posed On 29 Oct 99 Grigoriy Strokin wrote Hello How do I prepare Cyrillic documents in PostScript using groff provided I have Cyrillic fonts for Ghostscript In fact some cyrillic letters appear as expected gt gt gt gt gt gt gt but some other are replaced by groff to funny characters gt such as Thorn or multiply sign The following is a transcription of the response I m not familiar with Cyrillic fonts for Ghostscript and these may possibly have a problem with missing characters for all I know The following assumes that you have a PostScript font with a complete Cyrillic character set possibly from ghostscript of course Provided you have
53. e terminated by a LP command a section command works just as well and furthermore it resets the list to bulleted For example I might write first line second line and so on The same pretend list with numbering would look like 1 first line 2 second line and so on The text to create these two was 16 Hopefully you ll find this HOWTO to be a useful reference at least while you re getting started 11 While writing this HOWTO I noticed that a reference to figure 3 was preceded by a comma which I did not include This is likely a bug in my macro Revision 1 28 Groff and Friends HOWTO July 2001 31 BU first line BU second line p BU n first line BU second line LP The macro looks like SN WOKOKUKOK X RRR KIER A Hee OK OK GR OK OK X ko M BU InaCroF M X XXX kk kk ck k ck ck ck k ck KKK KKK KKK KK KK KK KK Nn Predefine some registers and strings These are also reset with N every NH i invocation nr bu 0 ds symbol NN bu ds numeric de BU SN SN If there is an argument its either a symbol or a numeric format amp value VN shi IONNS MIN ds symbol ds numeric 1 ie S1 n af bu 1 set format to 1 el ie S1 N af bu 001 set format to 001 el ie NNSACI vaf bui NV set format to lower case roman numerals el ie S1 I af bu I set format to upper case roman numerals el ie NNM 1 a af bu a set format to lower case al
54. e the same except that it allows text to be placed on the current page if there is room for it The coding looks like the following Notice that I dropped the br command as I knew that KS would issue a break KS Start the keep You can use KF here if desired Bi July 2001 Groff and Friends HOWTO Revision 1 28 28 PSPIC sample eps 2 QP Figure5 3 This is the caption for my illustration Notice that I used a program called xfig to create it BP B2 KE This ends the keep A last comment on figures I mentioned that encapsulated PostScript was the format to use This is not entirely true and groff and its predecessor troff also accept a format called PIC PIC is a graphics language which was developed and in use at Bell Labs at least early as 1984 It is a descriptive language and uses English words to describe a picture An example taken from Kernighan 1991 is the following PS ellipse document arrow box PIC arrow box TBL EQN optional dashed arrow box TROFF arrow ellipse typesetter PE This somewhat innocuous text produces the following image TBL EQN FE optional TROFF typesetter The previous reference gives a full description of PIC s capabilities Those not interested in learning the PIC language but still wishing to use it in their documents are referred to xfig which will produce PIC on request 9 References If you are w
55. een developed What You See Is What You Get or WYSIWYG types of programs such as the many that are available under Microsoft s various operating systems Other similar programs include those available from Sun Microsystems or Applix In fact these are not or at least haven t been document formatting programs so much as tools to generate shorter works with their emphasis being on look rather than content The only true alternatives known to this writer are troff and the versatile TEX system with its accompanying macro packages such as IATEX As this writer understands the history of text formatting the predecessor to TEX was troff It was developed at AT amp T Bell Labs and was in use from about 1971 according to Kernighan 1978 troff and related pro grams were provided as part of the Documenter s WorkBench an optional extra for those purchasing a licence to use UNIX In the late 1980 s the Free Software Foundation s version of these tools was devel oped and was named groff At about the same time possibly a little earlier the TEX formatting system was developed Like troff groff TEX and subsequently IATEX use text formatting commands interspersed with document text to describe how a page is to be formatted by a type setting device troff groff however tend to be much more like typical UNIX applications in that the commands used to describe page formatting are terse These commands are typically 3 characters in length and may be c
56. ended text where using escapes like YA throughout would be too tedious is based on a similar character translation which allows me to type in Latin characters using a July 2001 Groff and Friends HOWTO Revision 1 28 64 transliteration like convention I can t be bothered to fiddle with keyboards like using Rus sian alphabetical order tr A NN 225 Cyrillic char identical to Latin A tr B NN 226 Cyrillic char like large b tr V N 247 Cyrillic char identical to Latin B t5 iG NN 236 Cyrillic char identical to Greek GAMMA tr N YA N 241 so that for instance the word for Probability would be entered as Vero yatnoste i This reduces the use of escape sequences to the minimum The sequence Wi stands for i kratkoi You could also of course Grigoriy define the compound character char iy V so that your name would be typed Grigor iy METHOD 2 which depends on info from Method 1 In your environment which is presumably primarily Cyrillic you will probably be using a Russian keyboard and a screen font based on the ISO font encoding iso 8859 5 Cyrillic where various numerical codes above 128 correspond to Cyrillic characters For the reasons given above the iso latin 5 character encoding may differ from the encoding in the PostScript font you are using Therefore you should carry out the above check as to which decimal codes correspond to which printed characters in
57. er Serial Number Contact Supplier 15 L6 123 3456 123 Jim ABS Supplies 17 123 5437 456 Genco Paints 8 557 234 3333 123 456 Suzy HAL Computer Systems 19 TE 20 Well that should do it As long as I have this diary I ll never forget 2l again 22 SH 23 The Next Day 24 LP 25 Wow I sure impressed the boss today I got ABS Supplies contact name 26 with just one small glance at my diary Now I m in his good books And what is the result of this Here is Figure 2 12 Let us assume that we don t need numbered chapters July 2001 Groff and Friends HOWTO Revision 1 28 20 Another Day in the Life of Dean P Lately my life has become more complicated Now the boss wants me to remember the names and tele phone numbers of key suppliers and selected contacts As if I don t already have enough to do Well my memory used to be up to the task but in these declining years if I want to hang on to this job I better work smarter I think I ll use that new fangled groff program I hear it s great Telephone Number Serial Number Contact Supplier 123 3456 123 Jim ABS Supplies 123 5437 456 Genco Paints 557 234 3333 123 456 Suzy HAL Computer Systems Well that should do it As long as I have this diary I ll never forget again The Next Day Wow I sure impressed the boss today I got ABS Supplies contact name with just one small glance at my diary Now I m in his good books Fi
58. ered by use of the troff command in default 5n within a RS RE pair such as RS in 10n text RS Decrease the size of following text by 2 points Com pare to LG and NL Underline the text on the macro command line Mul tiple words may be underlined if enclosed in double quotes Unlike commands such as B following lines of text are not processed by the UL macro Place the word UNIX in the text the first time the macro is used but only the word UNIX on subse quent invocations If text multiple words allows if enclosed in quotes appears on the macro command the text will be appended to the word UNIX This is useful for adding punctuation Enclose the following text in a box End with B2 End the boxed text which was begun with B1 Surround the text usually a single word with a box To surround multiple words separate them with a digit width space i e 0 Revision 1 28 Groff and Friends HOWTO July 2001 2175 5 1 Registers used by the ms Macros 5 1 1 Number Registers So those are the ms macros To use them effectively you should also know about the registers that are set when you use the ms macros These are in the following tables ms Macro Number Registers Sorted Alphabetically Name What it Controls When it Takes Effect Default Value DD distance to display displays 0 5v FF footnote format next FS 0 1 20r3 FI footnote indent next FS 2n FL footnote length next F
59. ext All text is dis played as it is found in the source file centered on the longest line until terminated with DE Compare with DS B Print text in bold italic See also B I and C In some version of the ms macros commence the bib liographic format i e precede a bibliographic record This is not used in groff and so may be defined by the user Set the bottom title i e at the foot of the page to text This is the date if not otherwise specified Surround the text usually a single word with a box To surround multiple words separate them with a digit width space i e VO Commence centered display with each line individu ally centered until terminated with a DE Compare with DS C Print text in constant width font See also B BI and I Print the current date as the center footer of each page If text is specified use that value in each page footer End text displayed under the control of BD CD JD LD or DS July 2001 Groff and Friends HOWTO Revision 1 28 Alphabetical Listing of ms Macros Type Macro Description Page Format Page Format Page Format Mathematics Mathematics Page Format Page Format Page Format Page Format Text Format Page Format Paragraph Format DS type EF left center right EH left center right EN EQ x y FE FP FS label HD header text I text trail precede ID indent IP tag
60. ext page if necessary Compare with DSI End a collection of lines of text which together will be kept together as a keep See KF and KS for a description of the types of keeps available Begin a collection of lines of text which will be kept together as a keep This keep is known as a floating keep in that if there is insufficient room on the current page for the entire block then it will be placed at the top of the next page See also KS Begin a collection of lines of text which will be kept together as a keep This keep is known as a fixed keep IF there is at least one line of room available for output text on the present page then this collec tion will be added to the current page July 2001 Groff and Friends HOWTO Revision 1 28 4 Functional Listing of ms Macros Type Macro Description Page Format Page Format Page Format Page Format Page Format Page Format Page Format Page Format Paragraph Format Paragraph Format Paragraph Format Paragraph Format Paragraph Format Paragraph Format LD Begin a left justified display without a keep Com pare with DS L MC width Begin outputting multiple columns of width width The width parameter should be specified in units like inches such as MC 21 ND text Prevent the placing of the date in each page footer see DA Place text on the cover page OF left center right Place the specified te
61. ff Source to ASCII 15 7 Is There a groff info File 15 8 How can I do Cyrillic with groff 15 9 What is the Meaning of Double Quotes in Macro Ateste 15 10 Footnotes and Indented Paragraphs 15 11 Where can I get Windows binaries of grof 15 12 Is There a Document Like the Troff User s Manual for era 15 13 How Should I Name My Macros 15 14 How Can I Avoid Name Clashes with Macros in Use 15 15 How Can I Get a List of All My References 15 16 How Do I Make the Output of gv Bigger 15 17 How Can I Defer Page Numbers in a Floating Keep 16 Other Sources of Information References Index Groff and Friends HOWTO 61 62 62 62 62 62 64 64 65 65 65 65 65 67 68 68 69 71 The Groff and Friends HOWTO Dean Allen Provins University of Calgary dprovins ucalgary ca 1 Introduction This HOWTO attempts to introduce the document formatting system known as groff It isn t intended to be a reference document other individuals are working on that It is aimed at two groups firstly the individ uals who are new to UNIX Linux or another UNIX variant and are discovering that operating system s enormous potential and versatility and secondly at those who are considering the use of a document for matting system for producing high quality and consistently formatted papers articles and possibly books groff is not the only document formatting system available to writers In recent years there have b
62. ff and friends There are even more available for its prede cessor troff 2 1 The ms Macro Package The ms macros provide a much needed lift for those toiling with the basic troff commands They the ms macros are now used extensively by writers the world over Figure 1 This page was created from the example text in the HOWTO This caption and the figure number was added with a custom ms macro So what happened The ms macros which are introduced by a period followed by 2 uppercase letters in the example text were interpreted by the troff processor as representing troff commands These then con trolled the formatting of the final result With the exception of line 26 which is a troff command to be explained later all others represented font size changes centering emboldening and so on We start with the TL command This is a macro for a title It appears at the beginning of a document centers the following text increases the text size and sets it in bold The author is identified after line 3 AU which indicates that an author name or several author s names follows This macro sets the name in italics The author is further identified by lines of text following the AI macro in line 5 The abstract is identified by a AB macro call and is terminated by a AE which presumably means abstract end The text of the document follows line 15 which indicates a chapter or main section via the macro call NH The section chap
63. ffGffii org An acknowledgement of your request to join will be received and you will be assigned a password Mail received by the list will be archived at http ffii org archive mails groff The web site is http groff ffii org There the latest version of groff and friends is always available References Dougherty 1987 Dale Dougherty and Tim O Reilly UNIX Text Processing Hayden Books A Division of Howrd W Sams and Company Indianapolis Indiana U S A 1987 Geschke 1985 Charles Geschke PostScript Language Tutorial and Cookbook Addison Wesley Publishing Company 1985 Kernighan 1978 B W Kernighan M E Lesk and J F Ossanna Jr Document Preparation The Bell System Techni cal Journal 57 6 part 2 pp 2115 2135 American Telephone and Telegraph Company Short Hills New Jersey U S A July August 1978 Kernighan 1974 B W Kernighan and PJ Plauger The Elements of Programming Style McGraw Hill New York U S A 1974 Kernighan 1976 B W Kernighan and P J Plauger Software Tools Addison Wesley Reading Massechusetts U S A 1976 Kernighan 1991 Brian W Kernighan PIC A Graphics Language for Typesetting User Manual Computing Sci ence Technical Report No 116 AT amp T Bell Laboratories Murray Hill New Jersey 07974 USA May 1991 Knuth 1986 Donald E Knuth The TeXbook ISBN 0 201 13447 0 Addison Wesley 1986 Lamport 1985 Leslie Lamport LaTeX A Document Preparat
64. following Revision 1 28 Groff and Friends HOWTO July 2001 Som Title for a Sample Figure Drawn with xfig Figure 5 3 This is the caption for my illustration Notice that I used a program called xfig to create it While this was satisfactory initially I eventually developed some macro add ons for ms to handle captions for figures and tables and to allow me to reference these elsewhere in the text I ll describe these later I should add that to surround a figure with a box such as we saw in the first two illustrations see for exam ple Figure 1 you simply surround the figure with the macro pair B1 and B2 Using the same figure as last time the code would look like spr B1 ESPIC sample eps 2 OP Figure 5 3 This is the caption for my illustration Notice that I used a program called xfig to create it LP B2 This is displayed as Title for a Sample Figure Drawn with xfig Figure 5 3 This is the caption for my illustration Notice that I used a program called xfig to create it Lastly you will want to be sure that your figure and caption remain together This is called keeping the text together The macro pair to use is either KS and KE or KF and KE The first pair will determine the size of the figure and caption and place it on the same page if sufficient room remains else it will move it to the next page and leave a blank space on the current page The second pair do
65. format description Then comes a horizontal line followed by the remaining lines of text Notice the colons separating each column and notice that line 17 lacks one column of data The tbl program leaves space for missing data if necessary As I said earlier the tab character a colon here can be any character not in the text This is a very simple table example but is useful to illustrate how easy it is to generate one A very slightly more complicated table might look like A Table Containing Equations Equation 1 zuo quation a tg N m Equation 2 a C x dx i l 0 Don t you wish there were no more Equations It was generated by means of Revision 1 28 Groff and Friends HOWTO July 2001 21 PS center doublebox delim tab 4 cb s de ds A Table Containing Equations An Oo fF WD FE Equation 1 Ga sqrt b sup 2 c over d sup 3 Equation 2 a sub k sum from i l to N C sub i int from 0 to pi x sub k sup 2 dx T amp Ed T Don t you wish there were fBno more fP Te T BP WHY FP O o o ODE Equations T TE a o 1 O CO In this example I have illustrated inline equation definitions As you can see they are textual which makes them reasonably easy to read and key in I also asked for a doublebox centered with equation delimiters of and 9 and a TAB character as the separator between the columns Between lines 7 and 8 there is a
66. gt make file p check the input s file for picture errors gt make file t check the input s file for table errors gt make file e check the input s file for equation errors make file x create an index for the specified source file gt make file toc add TOC and index entries to Source file gt make file egz compress an EPS file and store in RCS gt make file pgz compress a PS file and store in RCS make file html make an HTML version of a groff source file This makefile makes use of several scripts namely S SCRIPTS error script lt nul sed f S SCRIPTS toc scripb lt gt toc awk f SCRIPTS index script ttee d awk f SCRIPTS format script ttee e sed f S SCRIPTS title script ttee x N GS SCRIPTS clean script Following are documents that are composed to chapters each of which is in a separate file I show just one here to keep what is a busy makefile shorter It says that the word 407 407 s Revision 1 28 Groff and Friends HOWTO July 2001 55 The following are used for debugging Uncomment them and comment out the succeeding set tee a tee var tmp a tee b tee var tmp b tee c tee var tmp c tee d tee var tmp d tee e tee var tmp e tee f tee var tmp f tee g tee var tmp g tee_a tee b tee c teu de tee e tee f tee g tee x tee var tmp x SJBUEFIXES 5 De ll igv ee 1D lt b lpr X X TMAC TMAC
67. gure 2 This is the page that corresponds to the un numbered chapter titled Another Day in the Life of Dean P In this example we used the section command SH to provide unnumbered section titles lines 1 3 Line 10 saw the beginning of our table which went to line 19 As you can see tables begin with a TS com mand and end with a TE command The first line after TS up to the semi colon describes some general parameters I have indicated that the table should be centered enclosed in a box and that the text information will be divided into columns by a colon the tab command You can use any character here including a real TAB Note that this line must be terminated by the semicolon The next line applies to the first line of the table data In this case it says that there will be four columns and that the text for each column if given is to be centered and set in bold type The final line up to the period on line 13 describes the subsequent lines of text which make up the table Here I indicated that the first column was to be right justified r and followed by a vertical line I The next column will be treated as numeric data and the decimal points will be aligned The last two columns will be left justified Vertical lines will separate all columns The period at the end of this line indicates that the formatting information is complete The next line is presumed to be the column headers corresponding to the first line of
68. h of line 18 lineup 23 LP 5 Ipile 23 M macro customization 30 macros double quotes 64 man 3 me 3 mm 3 ms 3 macros in use 65 mail list 69 make 54 makefile 44 52 53 man 3 macros 3 man pages 2 mark 23 26 markup language 3 math symbols eqn 25 matrix 21 23 me 3 macros 3 mk 26 mm 3 macros 3 ms 3 65 67 macros 3 MS macro number registers by function 17 dictionary order 17 MS macro registers 17 number 17 string 18 Index Groff and Friends HOWTO MS macro string registers 18 ms macros 6 MS macros by type 12 dictionary order 7 N naming macro extensions 65 NH 5 30 32 number MS macro registers 17 registers 17 number registers 17 0 organization 52 over 23 P page numbers floating keep 68 KF 68 paper size 61 paperlength 61 paperwidth 61 paragraph bug footnotes 64 PIC 28 pile 23 PNG 25 52 points 26 61 PostScript 1 25 62 to ASCII 62 to HTML 62 print 61 ps2ascii 62 PSPIC 25 Q QN 38 example 38 R rcol 22 23 refer 28 67 reference customization 43 references 28 73 registers 18 number 17 return 26 right 23 rpile 23 rt 26 S sample makefile 54 scripts format 50 index 48 title 51 toc 45 section 5 security 68 sed 1 45 65 67 setting format HOWTO source 61 SGML 3 SH 6 20 sizescale 61 small caps 40 so 61 sort 45 sp 26 sqrt 23 string MS macro registers 18 string
69. h something like de fig toc ie tNAn z WIN tm FIG sp tm FIG 1 tT tm FIG NN 2 i tm FIG T t n PN eN el fig_toc and call fig_toc in your Fc macro rather than immediate calls to tm You need to give fig_toc the 2nd and 3rd arguments to Fc This is interpreted as defining an additional macro called fig_toc which upon invocation immediately tests to see if it is in a diversion the ie statement If not it executes 4 tm statements which place the desired information into the standard error file If it is in a diversion then it places an invocation of itself into the floating keep the el statement Notice that that this last statement begins with the two character sequence This tells groff not to execute the fig_toc macro now but only to strip off the characters When the diversion has ended and the floating keep is being positioned on the page the macro is invoked Only at this time is the page number n PN set to its current numeric value 16 Other Sources of Information Several of the references cited earlier are worth looking at if copies can be located in your local library In particular the book by Dougherty and O Reilly is useful although not particularly so as a reference The Sun Microsystems document is very good and is based on the PostScript files mentioned below There are several documents available in PostScript format which describe the use of troff and associated proces
70. he examples provided 4 AE 9 NH 6 Machine Document Processing 7 LP 8 In this chapter we see that computers have finally come into their own 9 No more must workers labour over Gutenberg presses as they have for 20 generations 21 NH 22 Macros 23 LP 24 There are many macro packages available for fIgroff fP and friends There 25 are even more available for its predecessor flItroff fP 26 ds MS fIms f P 27 NH 2 28 The N MS Macro Package 29 LP 30 The MS macros provide a much needed lift for those toiling with the 31 basic fItroff fP commands They the MS macros are now used 32 extensively by writers the world over The result looks like the following I trimmed the bottom of the page off for this display Revision 1 28 Groff and Friends HOWTO July 2001 Our Important Report Dean Provins Noted Author and Hacker Student of Life and the University of Calgary ABSTRACT Noted author and hacker Dean Provins reveals all in the much heralded HOWTO for groff In this classic document Provins describes the inner workings of one of the earliest machine document processing systems available Readers are encouraged to try any or all the examples provided 1 Machine Document Processing In this chapter we see that computers have finally come into their own No more must workers labour over Gutenberg presses as they have for generations 2 Macros There are many macro packages available for gro
71. ich when interpreted are translated into low level troff instructions You are welcome to use only the low level instructions in your documents but you will likely find that the use of a package like ms greatly facilitates your productivity On the other hand you may find that the macro packages available don t meet your specific formatting needs and you may wish to alter an existing package or write your own package In this document you won t see any new macro package development but later I ll show you how one might customize some of the ms commands or add to that package When groff invokes the GNU version of troff it causes the replacement of the high level macro commands that you introduce to describe how you have organized your text into chapters sections tables and so on into low level formatting commands These are interpreted by the code that actually manipulates your text into an attractive document If you re familiar with HTML which is a subset of Structured Generalized Markup Language or SGML then you already know about page formatting and markup languages The troff macros and consequently the groff macros are simply the earliest implementation of machine inter preted markup languages The ms macros are designed to assist you in formatting letters proposals memos technical papers and reports I have used them for all of these purposes and have also created admittedly short books To meet my particular needs I have a
72. iends 3 The following names have been gleaned from the groff mail list and the groff documentation If you do not appear here but have contributed to the success of groff and friends please let me know TIl be glad to include you Revision 1 28 Groff and Friends HOWTO July 2001 Peter Miller soelim path control Gaius Mulley grohtml and tmac arkup for HTML generation Bernhard Reiter mail list manager Paco Andres Verdu patches for the Canon caps printer Bernd Warken programming long options for groff man page discussion and page creation This document is copyright by the author who grants all readers a non exclusive right to copy and to dis tribute it without compensation under the terms of the GNU General Public Licence 4 ms Macro Overview As indicated earlier there are several macro packages available for groff but what is a macro package Think of it as a high level page description which is written in a low level page description language An analogy to a macro package might be a procedural language like C which is relatively easy to read but which when compiled is turned into a low level language like assembler and ultimately machine instruc tions Few people code in assembly language any more preferring to use higher level instruction sets which incidentally greatly improves productivity In a similar manner a macro package for groff such as the package of ms macros is a collection of state ments wh
73. ion System Addison Wesley ISBN 0 201 15790 X 1985 Oram 1991 Andrew Oram and Steve Talbott Managing Projects with make O Reilly and Associates Inc 1991 Ossanna 1992 Joseph F Ossanna and Brian W Kernighan Troff User s Manual Computing Science Technical Report No 54 AT amp T Bell Laboratories Murray Hill New Jersey 07974 USA November 1992 Sequin 1975 C H Sequin and M F Tompsett Charge Transfer Devices Academic Press New York U S A 1975 Groff and Friends HOWTO References 70 Sun Microsystems 1988 Sun Microsystems Using NROFF and TROFF in Sun Microsystems System Documentation Sun Microsystems May 1988 Revision A Warnock 1985 John Warnock PostScript Language Reference Manual Addison Wesley Publishing Company 1985 References Groff and Friends HOWTO ils Index A reference 43 AA 61 customizing macros 30 AB 5 abstract 5 abstract end 5 ad hoc definition equation 43 adding macros 30 AE 5 AI 5 AN 30 32 ascii 61 AU 5 author name 5 automatically numbered footnotes 19 awk 48 B B1 27 B2 27 bar 23 blank lines 6 BoundingBox 25 box figure 27 braces 22 BU 30 by function MS macro number registers 17 by type MS macros 12 C captions figures 35 cat 67 ccol 22 23 centimeters 26 chapter 5 Characters available in groff 25 circumflex 22 col 62 convert 52 cpile 23 creation index 45 customization
74. ize by chapters That way I can work on a single chapter with periodic reviews without having to wait on the processing of the entire work I simplify the organization by storing documents on a particular subject in a subdirectory of the directory where all my documents reside On my system it is home provinsd docs s The docs subdirectory has documents that are not groff formatted works the s subdirectory just happens to contain everything that uses the ms macros Pictorially it looks like Figure 3 I use RCS to track revisions of each document or chapter I even use RCS to track revisions of figures generated by xfig which I used to create Figure 3 Notice that RCS is included in each directory This ensures that if I use the same name for a figure say that I don t clobber one with the same name in another subdirectory which corresponds to another docu ment and I ve done that unfortunately Notice that I have used a single makefile I do this because then I can track everything I ve done and I don t need to duplicate a fairly complex set of dependencies Another file that is common for all groff documents using the ms macros is tmac ds This file contains all of my personal macros and my customizations of the macro set called tmac s which is found in usr share groff tmac The directories in the illustration odds ends and approximation contain shorter documents like this HOWTO which is in odds ends and longer works like
75. l titles s L July 2001 Groff and Friends HOWTO Revision 1 28 66 The file all titles s is ready for processing by groff ms Begin by inserting two lines in the output 1 i So home provinsd docs s ref s LB When a blank line is reached insert copy the hold space into pattern space replace all embedded newlines with spaces and append print the line delete the contents of the pattern space place the now empty patter space into the hold space for the next cycle iN s g s Nn g a iJ p s Append the last name of each author or editor to the hold space S EA s amp a zA Z 1 H Append the date to the hold space amp D s D Append the title to the hold space 8T s T H and associated command cat home provinsd bibtex refer bib home uc sed f sed script gt all titles s will do the trick As described below it grabs the author s surnames the date of publication and the full title of the work This seems to be enough to make each entry unique The beginning of the output from this commands for my bibliographic database looks like Revision 1 28 Groff and Friends HOWTO July 2001 67 So home provinsd docs s ref s LP Cruz June 1983 Experiences with Altimeter Data Gridding Heiskanen Moritz 1966 Physical Geodesy Krakiwsky 1990 The Method of Least Squares A Synthesis of Advance
76. ld cause the next section level to be something like 3 Section Title even though the previous section was say 17 Set point size to the default 10 pts if not specified via the number register PS at the beginning of the document Place the specified text left center or right in the footers of all odd numbered pages One or more of the text strings may be omitted but all single quote marks must be given July 2001 Groff and Friends HOWTO Revision 1 28 10 Alphabetical Listing of ms Macros Type Macro Description Page Format Page Format Paragraph Format Page Format Table of Contents Paragraph Format Text Format Page Format Text Format Document Format Text Format Section Header Text Format Paragraph Format Table of Contents Table Format Table Format OH left center right P1 PP PT text PX no QP RD RE RP no RS SH SM TA TC no TE TH Place the specified text left center or right in the headers of all odd numbered pages One or more of the text strings may be omitted but all single quote marks must be given May be used to print the header on the first page if macro TM is defined In groff it is defined to set the first page to page 1 Commence a paragraph with the first line indented by the amount given in number register PI Specify the page title placed at the hea
77. letter Vet grave accent place before letter circumflex accent place before letter VE cedilla accent place before letter Ve umlaut accent place before letter Ven tilde accent place before letter Note that if you employ AM to obtain enhanced mark definitions the strings should appear after the letter not before To use these registers say to place a circumflex over the letters e in the word example you code as follows exampl e This results in xampl if the AM macro has not been invoked If it has then the coding is e xample Let me add an aside on string registers You can create and use your own string registers with the troff command ds Suppose that you are writing this HOWTO and find that you have to type fIgroff fP many times as I have done in this document or perhaps you want to use the phrase groff is great many times You could code as follows where you want the two letter code GG to represent the longer string not a great example but you get the idea ds GG fIgroff is fP fBgreat fP You can now use GG or GG either will do see the gtroff man page to produce groff is great See the man page for gtroff for a description of fractional point sizes Revision 1 28 Groff and Friends HOWTO July 2001 19 6 Tables Periodically you may find that you need to set out some text in a tabular form Perhaps it s a list of names and numbers or perhaps it is much mor
78. n nh hl gt n nh ohl nr nh ohl 1 nr H n nh ohl 0 nr H n nh hl 1 kk ck kk kk kkkkkkkkkkk k Dean s additions x xkxkXkkkXk kk kk kk ko ko ko kk ko kk With every NH i invocation reset the bullet stuff bu 0 symbol bu numeric For first level NH invocations reset the equation table and figure numbering to 1 if the AN macro was invoked n fan Revision 1 28 Groff and Friends HOWTO July 2001 35 if n nh hl 1 ds Ch n H1 nr eq 1 nr tod nr fg 1 ds Fg Ch n fg ds Tb Ch n tb ds Eq Ch n eq NI Users MUST put bp 1 after their abstract AB AE to get the article text to start on page 1 ENS Note that oddly this does not place the first chapter on page 1 as NH PG doesn t seem to recognize that it is at the top of page 1 N The solution for now is to put bp 0 after the abstract The N first page of chapter 1 then appears where it belongs on the third page but numbered as 1 Note that this applies when AN has been invoked VN For first level NH invocations ensure the heading and text starts on an odd page number NT ds RF Chapter n H1 PG if n nh hl 1 if n an SNM kk ck kk kk kkkkkkkk k Back to the original NH Stuff kkkkkk k kkkk ds SN nr nh i 0 while n nh i lt n nh hl nr nh i t as SN n H n nh i SH NE SN 10 4 Figur
79. ntry is different output a line feed if start 0 if j 1 1 start 0 printf n else start 0 If only the line number is different just add it if j 5 printf s entry j July 2001 Groff and Friends HOWTO Revision 1 28 50 else for X Jp I lt 67 iL if i 1 first word different just print it printf s entry i else if i lt 5 not the page number if length entry i gt 0 non blank word go to next line printf ynt if length entry i 0 indent i indent the word sufficiently printf s entry i else printf s entry i add the page number after a COMMA for i 1 i lt 6 i copy current line to last line last i entry i next get next line of input The format script format script Awk script to apply groff formatting to index output from GS macro This script follows the index script invocation in a pipeline of three index script format script title script BEGIN FS t OFS lower abcdefghijklmnopqrstuvwxyz upper ABCDEFGHIJKLMNOPORSTUVWXYZ Mainline EU printf sWMn DO RF Index printf s n DO LF if 0 ignore lines beginning with spaces n 1 while newchar substr 1 n 1 A Za z n Revision 1 28 Groff and Friends HOWTO July 2001 5 if n 25 bad line newchar oldchar break if ne
80. numbered sections As you can see using the ms macros is quite straightforward There is no need for you to fill every line of text in fact groff is quite happy with a single word per line although you may find it difficult to read When entering text use your favourite text editor vi or emacs and type away If you need to add a few lines just insert it at the appropriate point With a text editor it will be unlikely that you will ever encounter the formatting and overflow problems that have plagued WYSIWYG word processing programs on longer documents They simply don t have the overhead just one more reason to use a document pro cessing system Just a word about blank lines Blank lines terminate the filling of lines They also indicate the ends of paragraphs Note that the chapter section subsection commands generate blank lines before and after the chapter section subsection title 5 Useful ms Macro References This section lists the ms macros available for use with groff They are sorted in two ways once by func tion and once alphabetically In the following lists the reference to keep is a reference to a macro action wherein all formatted text is kept together The text is added to the output on the current page if there is sufficient room for all of it or it is placed at the top of the next page if there was not sufficient room Revision 1 28 Groff and Friends HOWTO July 2001 Alphabetical Listing of ms Macros
81. ombined in sometimes difficult to read combinations not unlike the regular expressions used with sed or grep The macro packages available for use with troff groff are somewhat more easily read but are still brief The advantage offered by TEX is that the commands are much more descriptive or readable Their disadvantage in the opinion of this writer is that they take more time to type Both however offer writers the opportunity to focus on content without the distraction of look While the early systems were designed to drive specific devices this is no longer the case Both systems generate a neutral device independent page description which subsequent processes format for specific devices This is often via PostScript which on UNIX or UNIX clone systems is easily formatted for a wide variety of available printing and plotting devices but need not be Today plain text TEX format PCL5 HP s printer description language and HTML are available Although I have acknowledged the availability of TEX and IATEX this document will not dwell on them or compare groff to them For further information on TEX interested readers are referred to Lamport 1985 The original troff program was designed to drive a specific machine a Graphic Systems Incorporated C A T Computer Assisted Typesetter Kernighan 1978 Sun Microsystems 1988 At least not in this revision July 2001 Groff and Friends HOWTO Revision 1 28 and Knuth 1986
82. ome of you may be interested in the following macros which do a primitive implementation of small capitals I think the main point to be careful of is Don t change the point size within a smallcaps block you re unlikely to need to do so anyway but if you do it won t work right If you need to do that you d better do the smallcaps by hand or maybe make more than one block of it The two macros smallcaps to turn it on and smallcaps to turn it off follow with a small Revision 1 28 Groff and Friends HOWTO July 2001 A1 example at the end His macros and a short example follow de smallcaps nr sc ps n s 75 100 nr cap PS n s char a s n sc ps A s n cap PS char b s n sc ps B s n cap PS char c s n sc ps C s n cap PS char d s n sc ps D s n cap PS char e s n sc ps E s n cap PS char f s n sc ps F s n cap PS char g s n sc ps G s n cap PS char h s n sc ps H s n cap PS char i s n sc ps I s n cap PsS char j Ns NWn sc ps JNs NWn cap PS char k s n sc ps s n cap Ps char 1 s n sc ps L s n cap PsS char m s n sc ps M s n cap PS char n s n sc ps N s n cap PS char o s n sc ps O s n cap PS char p s n sc ps P s n cap PS char q Ns NWMn sc ps QNs NNn cap PS char t s n sc ps R s n cap PS char s s n sc ps S s n cap PS
83. pare to PX which does not alter the page numbers in any way If no is specified then the title Table of Contents is not printed End a table which was commenced by the macro TS and which will be formatted by the tbl processor End a table header which will be printed at the head of each page if the table exceeds a single page This requires the use of option H on the TS invocation Revision 1 28 Groff and Friends HOWTO July 2001 11 Alphabetical Listing of ms Macros Type Macro Description Cover Page Document Format Table Format Text Format Text Format Table of Contents Table of Contents Paragraph Format Table of Contents TL TM TS H UL text UX text XA no indent XE XP XS page no indent Set the title which is all following text up to the next macro command generally AU in bold text two points larger than the default font size This macro is not implemented in groff but was used to set documents in the University of California thesis format It may be defined by users for their own pur pose Begin a table to be formatted by the tbl processor generally invoked with the t option to groff If H is specified then the table will have a multi page header see TH Underline the text on the macro command line Mul tiple words may be underlined if enclosed in double quotes Unlike commands such as B following
84. phabetic el ie NNS1 A af bu A set format to upper case alphabetic el ds symbol 1 ds numeric AJ Ash QNT INN If there is a second argument it must be the start value NT if numeric ie NX 2 nr bu 1 8 Note that interpolated values arguments to macros strings number registers and special characters must be preceded by two backslash characters when used in a macro definition July 2001 Groff and Friends HOWTO Revision 1 28 32 NI el nr bu NN 2 NJ NT ie numeric IP n bu af bu 1 nr bu n butl ie numeric n af bu 1 el ie numeric N af bu 001 el af bu numeric io WW el MA IP symbol 10 2 The AN Macro This is a very simple macro If invoked it sets a number register to a non zero value This number register is tested in my modified NH macro illustrated next and if found to be non zero resets the numbering for equations figures and tables from zero for each chapter I define the macro as nr an 0 de AN nr an 1 count the invocations of AN out of interest 10 3 Modified NH Macro The NH is an important one It sets section headings and performs resets of selected internal items I wanted it to do more and so copied the whole to my macro definition file and added a few lines which I deliberately noted as mine so as not to muck up the original I
85. r I do this as I compose each chapter and I store them in separate files In this way I can format a chapter and scan it for syntax spelling and all manner of other composition errors by piping the output to gv Since an equation definition always seems to insert the space for an equation even if it contains nothing but abbreviations I use a script see the section titled Useful Scripts to strip out the redundant copies The abbreviations that I employ are listed below Note that the first token following the word define is the abbreviation subsequently available for use in an equation The eqn processor replaces the token with the text following the token I enclose all the following text in double quotes and where I believe that the dou ble quotes must be preserved I enclose the entire expression with its encompassing double quotes by additional single quotes This may not be necessary but it doesn t seem to hurt Note that if you are examining the source that generated this HOWTO you will find that I had to use addi tional backslash characters for formatting purposes In other words to make a comment appear comments start with I had to type it as NU kk kk kk kkkkkkk k Dbefine some useful equation StCuLLE KKK KKKKKK KKK K KKK SAM N MUST be manually added to the text i e the s file but WILL N leave space for an equation Thus may be worthwhile to include it in the FIRST equation of each chapter NM
86. r to separated by 2 inch tabs XP Commence a paragraph with the first line having no indent but with subsequent lines having an indent equal to the value of number register PI default is 5n Subsequent paragraphs will all be indented Revision 1 28 Groff and Friends HOWTO July 2001 15 Functional Listing of ms Macros Type Macro Description Section Header NH level start level Place a numbered chapter or section header in the output the header text follows on the next line or lines until a LP or other paragraph macro is encoun tered A level of zero or one or if none is specified causes a section header of the highest level to be cre ated Levels 2 through 4 are subordinate i e level 0 would appear as 1 Title and level 2 would appears as 1 1 Section If start level is specified and level equals S then the current section number is set to that value such as NH S 3 would cause the next section level to be something like 3 Section Title even though the previous section was say 17 Section Header SH Create a new section using the line or lines follow ing up to another paragraph command like NH as a bold title Unlike NH this section will not be num bered Table Format TE End a table which was commenced by the macro TS and which will be formatted by the tbl processor Table Format TH End a table header which will be printed at the head of each page if the
87. registers 18 sub 23 subsection 6 sum 23 sup 23 T T amp 21 tab 20 21 table of contents 45 tables 19 text blocks 21 tbl 19 20 21 TE 20 text blocks 21 tables 21 tilde 22 23 title 5 51 scripts 51 TL 5 tmac ds 52 tmac s 52 Groff and Friends HOWTO Index 74 to 22 23 to ASCII PostScript 62 to HTML PostScript 62 toc 45 scripts 45 token separators eqn 22 troff 1 68 troff manual 65 TS 20 T 21 T 21 U under 23 uniq 45 unnumbered sections 6 US letter 61 V vec 23 vi 6 W Winzip 65 WYSIWYG 1 6 17 X X100 61 X75 61 Xfig 28 52 53 Groff and Friends HOWTO
88. riting articles that will be published you may want to include references Certainly for any academic journal this will be a requirement Fortunately groff has a complete bibliographic package called refer refer is a program that copies a groff document from standard input to standard output while watching for lines between and When these are encountered refer replaces the citation found between them with an appropriate text sequence This sequence is usually just the first if there are several author and a date contained between a matched pair of parenthesis As well refer adds a complete citation at an appropriate place in the document often at the end refer refers to a text based bibliographic database in order to perform its actions To recognize a reference you must place key words that uniquely identify the reference between the and symbols For example the sequence I Kernighan 1991 Revision 1 28 Groff and Friends HOWTO July 2001 29 generates the reference Kernighan 1991 in the text using my particular refer specifications The bibliographic database is composed of fields which define different parts of a reference Each begins with a letter which defines the kind of information contained and ends with a newline The letter is pre ceded by an symbol Each complete entry is separated from all other entries in the database by one or more blank lines Typical fields are Bi
89. roff source file for HTML input FILE s output FILE html s html Ss cat sed f S SCRIPTS refer script sed f S SCRIPTS eqn2 script SOELIM I N S REFER S REFER OPTS pS DATABASE 2 nul S TROFF S HTML_OPTS MACRO markup Thtml gt html 2 gt gt nul S SCRIPTS error script lt nul echo HTML file html created Format mgs groff source file for PS input FILE s output FILE ps S ps S28 cat LFX sed f SCRIPTS refer script sed f SCRIPTS eqn2 script SOELIM S REFER S REFER OPTS p DATABASE 2 nul S TROFF S TROFF OPTS S MACRO Tps gt ps 2 gt gt nul S SCRIPTS error script lt nul RM nul echo PostScript file ps created D Format mgs groff source file and send to screen line printer mode 2S lpz cat sed f S SCRIPTS refer script sed f S SCRIPTS eqn2 script JN SOELIM N S REFER S REFER OPTS p DATABASE LA July 2001 Groff and Friends HOWTO Revision 1 28 58 S TROFF TROFF_OPTS S MACRO Tascii gt lp 25 S nul GS SCRIPTS error script lt nul more 1p rm 1p Format mgs groff source file and send to a text file S txt cat eX sed f S SCRIPTS refer script sed f S SCRIPTS eqn2 script li X SOELIM 1 S REFER S REFER OPTS p DATABASE Its S TROFF TROFF_OPTS S MACRO Tascii
90. s and many more After running those through groff with the ms macro package I get pages of references neatly sorted by author and date These look like Acton 1970 Forman S Acton Numerical Methods that Work Harper amp Row Publishers New York USA 1970 N R Adam et al 1997 N R Adam and A Gabgopadhyay Database Issues in Information Systems Kluwer Academic Publishers 1997 In this example I have found all the title entries T in the two files in which I keep my database home provinsd bibtex refer bib home and refer bib uc The cat command concatenates the two files and passes all the text to grep which searches for the T commencing in column 1 The lines that are found are then passed to sed for processing This script inserts two lines before line 1 the so and the LP com mands It then watches for 6T in column 1 and when this 1s found it inserts before the line removes the T and follows it with the closing macro that refer expects The so command reads my specific formatting requirements for references from the file I have indicated The output I called it all titles s is then run through groff with the ms macro package The final result is as you see it above a sorted list of references Are there any problems using this method Unfortunately there is one It shows up errors that you have made in your entries If for example there are duplicates refer will complain and drop th
91. s 95 98 and NT You can obtain it plus some installation information at http www cs vu nl tmgil misc wingroff html Other recom mended software such as Winzip and GSview are also available at that site 15 12 Is There a Document Like the Troff User s Manual for groff One of the maintainers Ted Harding has embarked on such a document As this is not a trivial undertak ing it may not be available for some time Readers are encouraged to subscribe to the groff mail list to fol low the development or to volunteer to assist Ted in order to speed it along For immediate use are a series of overheads that Ted used in a recent presentation to his local Linux user s group These foils with their groff source files are available from the following European site http www manlug mcc ac uk 19991120 talk tar gz See the file talk txt for a description of the con tents 15 13 How Should I Name My Macros Werner Lemberg suggested the following to an inquirer The usual thing in high level languages like C is to always have a unique prefix say www I think that your choice to have lt as a prefix is optimal It is AFAIK unique and it always reminds the user that it has something to do with HTML 15 14 How Can I Avoid Name Clashes with Macros in Use Werner Lemberg suggested the following in the context of name clashes when creating a new macro pack age which might be included with an existing package such as ms
92. s and my customizations to the ms macros Directory RCS contains all revisions to text figures fig and also gzipped versions of the encapsulated PostScript figures eps One thing to remember about xfig is that if you re not set up properly you may end up with landscape for mat for your diagrams This probably won t be what you want Simply start xfig as xfig portrait file fig 13 1 The Makefile The makefile makes everything go The following is a stripped down version with one document in suffi cient detail to illustrate the process that I use You may have a much better way and I would be pleased to hear from you The listing is quite lengthy it is the result of trial and error you know two forward one back If you have a better way and I m sure that someone out there does please let me know so that I for one will be better informed and other readers will also benefit from your experience I tried reducing the font size by 4 points for the following listing in order to make it a little shorter and I tried setting it in two columns but unfortunately the text became too small to read even though it met my requirement of a fewer number of pages I hope that the comments included in the listing are sufficiently clear naturally they are to me If you find them unclear please drop me a line with your questions and suggestions for change I will not in this ver sion of the HOWTO explain the makefile in detail Suffice to
93. sh the process of setting up the index The index script index script Awk script to process index output from tmac s macros This is the first of 2 awk scripts It precedes format script in a pipeline The title script a sed script follows last index script format script title script In the Makefile this sequence is preceded by a sed command to replace the sequence in the index entries in the error file by a TAB This is output is sorted and made unique BEGIN ESS itr start 1 indent_space n 3 space indent for i 1 i lt 6 itt last i Revision 1 28 Groff and Friends HOWTO July 2001 49 Our indenting function function indent count while count printf s indent space Mainline n split 0 entry store up to 5 entries 5th is line number Strip out warning lines like indent cannot be negative and can t break line if match 0 warning print warning encountered and ignored gt tmp groff errors next try the next line of input if match 0 error print error encountered by index script line was gt tmp groff_errors print gt tmp groff_errors print 0 gt tmp groff errors print tmp groff errors print run terminated gt tmp groff errors exit Find the first different entry for i 1 i lt 6 itt if entry i last i jai break If the first e
94. sors These are available at http www kohala com start in the troff resources link and at http cm bell labs com cm cs cstr html Of particular use is Ossanna 1992 At http plan9 bell labs com 7thEdMan index html may be found the original troff sources for the docu mentation that was shipped with the Unix Seventh Edition Manual Included is material on troff and related processors A selection of groff gems may be found at http www eas slu edu People RBHer rmann GROFF index html Things like creating business cards and using groff to make large format posters for presentations This has been provided by rbh eas slu edu In a recent posting to the groff mail list the following URL was cited http mirror viii This writer finds the text too wordy and the index not sufficiently so Revision 1 28 Groff and Friends HOWTO July 2001 69 lo krakow pl bugs security bugs mUNIXes groff html It discusses certain security issues surrounding some groff commands Note that these are disabled by default via tne S option The groff maintainers have set up a mailing list and web site to provide interested users with the latest releases bug fixes and problem solving facilities In addition a moderated newsgroup named gnu groff bug is available To subscribe to the mail list send an Email to groff request ffii org with the word subscribe in either the header or the mail body Then to post to the list send your email to gro
95. t See elsewhere in this HOWTO for a possible script End an equation which was begun with EQ Wom Commence an equation x may be L I or C corre sponding to left indented or centered alignment y is an optional equation label use quotes to enclose multi word labels Set single column mode causes a page break Set two column mode Return to single column with IC Commence block display of text All text is dis played as it is found in the source file centered on the longest line without a keep until terminated with DE Compare with DS B Set the bottom title i e at the foot of the page to text This is the date if not otherwise specified Commence centered display with each line individu ally centered until terminated with a DE Compare with DS C Revision 1 28 Groff and Friends HOWTO July 2001 13 Functional Listing of ms Macros Type Macro Description Page Format DA text Print the current date as the center footer of each page If text is specified use that value in each page footer Page Format DE End text displayed under the control of BD CD ID LD or DS Page Format DS type Start displayed text with keep of type block centered Page Format Page Format Page Format Page Format Page Format Page Format Page Format Page Format Page Format Page Format EF left center right EH left center right FE FP
96. t depends on the existence of certain string and number registers plus another macro that does paging on request DX ON KNKeK KE Kev oko ko A Ren et Ege TIC and registers xx xxx oce kk ee x NT N Number registers eq equation tb table fg figure 4 N These are updated by invocations of EQ TB and FI N with eq tb and fg preset to the next value for use prior to the EQ TB and FI commands SNP QNM If macro TB or FG is invoked then number register tB or fG is incremented so that other macros can determine if they were N every invoked NT N string Ch is set as required in the NH macro following 19 But have yet to use the count for anything Revision 1 28 Groff and Friends HOWTO July 2001 33 nr eq mE CD nr tB nr g snr vtG ds Ch ds Eq Ch n eq ds Tb Ch n tb ds Fg Ch n fg OrorRF NM NM XCkCck ck kckck ck kck kc kckck ck k KKK kk kk k k k b my page eject IlaCro F X kk kk k kk ck ck kk kk SN ds PAGE This page intentionally blank de PG EA This macro tests the an register ENS If not gt 0 it does nothing if n an gt 0 fl VN ENS For first level NH invocations ensure the heading m and text starts on an odd page number EH ds dummy string amp if n nl u n HM sp n plu NOT at top of page so eject while n nl u n HM dummy_string Fl needed to add something to the page to allow
97. te was written by James J Clark who re implemented the troff system in some 60 000 lines of C code Since then he has gone on to develop SGML parsers and related proces sors in both C and C All users of groff owe considerable thanks to his not inconsiderable efforts The current suite of programs are being maintained by Werner Lemberg and Ted Harding with contribu tions by many others As this document is being written the current release of the suite with enhance ments for HTML and graph rendering is version 1 17 x Some of the current and past contributors to this document either directly or indirectly plus contributors to the groff suite in general are Known Contributors to the groff Suite Nicola Bernardini discussion on so and mso James J Clark groff s author Jeffrey Copeland duplex printing Paul Eggert various patches including Y2K compliance Trent Fisher tex info format reference manual Joerg Freudenberger man page discussion Thor M Gil Windows 95 98 NT binaries for groff J rgen H gg new mm macros version 1 32 Robert Herrmann groff gem contributions posters business cards etc Ted Harding user assistance and smallcaps macros Steve Izma how to defer determining page numbers in floating keeps Larry Jones Gxditview additions including grey levels Susan G Kleinmann Additional man pages Werner Lemberg release coordination Eddie Maddox web site maintainer Blake McBride WIN32 port of groff and fr
98. ter title follows immediately and is terminated by LP on line 17 Until the next macro call on line 21 all text is read and after setting in the current font and pitch with line filling turned on The text is output to be later formatted as PostScript or whatever format you wish and is available At line 21 another chapter is identified and text is read in lines 24 and 25 At line 26 the author thought he might take a short cut and declared a string expression named MS as AfBmsMP From that point on the author could use the string expansion expression MS to represent If insufficient text is read on an input line more text from the next and subsequent lines is added to fill the output line This happens until a blank line or another macro call is encountered July 2001 Groff and Friends HOWTO Revision 1 28 fBms fP Admittedly this wasn t much of a saving but it could have been if the string definition was for fItrofffP which takes more keystrokes than MS The ds definition is an example of a troff com mand inserted into a document to facilitate text entry All that remains in the example is a subsection definition at line 27 As you can see in the resulting text sections receive numeric identifiers followed by a period Subsections received subordinate numeric identi fiers The ms macros allow for up to 4 levels of sections subsections For the record another macro command named SH introduces un
99. tions You know that the charac ter is also used in internet mail addresses Unfortunately the eqn processor doesn t know the difference between the start of an inline equation and an address If you need to include addresses in your document pre cede the by a backslash e g dprovins ucalgary ca Perhaps a better choice would be a dollar sign i e Then when you wanted to use that symbol you could either hide it with a backslash i e or use a Postscript dollar symbol Do which looks just the same i e 14 A real TAB entered at this location on the page causes the parentheses to appear separated by this amount At another location the amount might be different July 2001 Groff and Friends HOWTO Revision 1 28 ee center and right justified by the terms Icol ccol and rcol Limits of sums and integrals are easy to define with terms like from and to We ve already seen how equations can be included in tables lets look at some more The only rule that you need to remember and which I frequently fail to observe because of my poor make that sloppy typing ability is the need to separate terms by at least one space I suppose one other is that curly brackets i e and are used to group expressions which are to be treated as a unit as in defining the numerator of a complicated fraction Here s an expression for a Legendre function quem a 2 m 2 2 n P m COS 0 LR t t dem t 1 I code
100. to have the eps files listed as dependencies does that make sense We can remove the copies by running make clean eps egz touch extracted_eps_files touch TMPFILE grep lt extracted eps files gt TMPFILE 2 gt amp 1 if s TMPFILE a L lt then echo File lt not extracted do mv lt gzip ci m gzipped version of lt gz echo lt checked in X fi rm TMPFILE EG yN gA CO lt gz eps gunzip lt mv eps if f RCS gz v then echo eps gt gt extracted eps files fi clean GS SCRIPTS clean script rm f html Here is the document I call 407 There are several chapters each in their own file e g 407 01 2 and so on To build the entire document we ll make something called 407 s using the alias 407 defined at the beginning of this makefile Notice that certain chapters have dependencies on encapsulated postscript files Ig we make those chapters and the files are not in the current directory they ll be copied out from the RCS directory i e by co If we make the entire document they ll also be copied out A make clean will remove them from teh current directory but not the RCS directory 407 02 s 407 fig 02 O0O1l eps 407 fig 02 02 eps 407 03 s 407 fig 03 0O1l eps 407 fig 03 02 eps 407 07 s 407 fig 07 Ol eps 407 fig 07 02 eps 407 s 407 407_fig_02_0l eps 407 fig 02 02 eps 407 fig 0
101. unning then use the first and third definitions for TX and LX If nroff is running then use the second and fourth Assuming PostScript output the first and third string definitions generate TEX and TEX respectively As we saw earlier they would be invoked as V TX and V L X respectively 15 2 How Do I Convert This HOWTO s Source into Format XX It isn t quite that easy as I have some custom scripts and so files that I use for all my documents but I ll see if I can cut it down to size and make it available Be warned though they look a little a lot messy To make them useful I d have to post a bunch of stuff and the user you would have to put everything in the right place Perhaps though I can put the needed macros in the source file not sure if that is possible but think so and I may be able to skip the index which I think is very useful I hate having to rely on a table of contents to find things it takes so much reading to find a reference again Skipping the index for now at least would mean few perhaps no scripts would be required I ll look into the whole mess and return to this question again hopefully the result will be acceptable 15 3 How Do I Change the Paper Size Changing the paper size for the output of groff requires altering a single value in the device description file for a particular device As shipped groff supports several different devices including PostScript devps LaserJet4 devlj4
102. ute of Physical Geodesy Technical University oe oe EN ts T geomatics geodesy H amp M 1993 Physical Geodesy oe oe E ES 15 For the complete list do man refer July 2001 Groff and Friends HOWTO Revision 1 28 30 The first two entries are for a report and for a journal article The third is a book 10 Customizing and Creating ms Macros When I started to use groff several years ago spring of 1997 to be exact I had a copy of Dougherty 1987 to work with This is not a book that I recommend not because it is incomplete as it covers every thing but because I could not easily locate the information I wanted to accomplish some specific formatting requirement The book wasn t written to be a reference at least in my opinion I was influenced by some comments about the ms package though I was left with the impression that if I wanted to modify any macro set then I should consider that package specifically it being the easiest to play with So I jumped in and made several modifications to ms and added several other macro instructions For example I added a macro called AN which altered the way that figures tables and equations were num bered Of course these weren t automatically numbered so as you ll see shortly I altered the NH macro to accommodate my numbering requirements as well as how chapters were to be positioned on pages Another macro that I added was one to place not just bullets i e e
103. wchar a z convert first char to uppercase for i 1 i lt 26 i if newchar substr lower i 1 newchar substr upper i 1 break if substr 1 1 1 0 9 newchar if newchar oldchar next alphabetic character add title printf n n Ss n ne 4 printf sXn ti 2m printf Ss s s n fB newchar fR printf sXn Tibr oldchar newchar printf sXn ne 2 printf ssn pL 4g printf Ss n 0 printf s n be The title script title script This is the third of three scripts 2 awk 1 sed to process the index file created by groff The three scripts are piped together with several other UNIX commands The order is index script format script title script If this is run under gsed then multiple comments are available If not then delete all comments Before the FIRST line insert the following format codes iN bp XSN ps n s 2 SpN IndexN ps July 2001 Groff and Friends HOWTO Revision 1 28 52 SSH X Index brN NlNn lu Mn iu N brN 42 N in 4n na s After the LAST line reset the footer codes RF is set in format script Sa ds RF 13 Document Organization and a Sample Makefile For shorter documents like papers I might publish or perhaps just a nicely formatted letter I do the whole thing as a single unit Longer documents I organ
104. xt left center or right in the footers of all odd numbered pages One or more of the text strings may be omitted but all single quote marks must be given OH left center right Place the specified text left center or right in the headers of all odd numbered pages One or more of the text strings may be omitted but all single quote marks must be given P1 May be used to print the header on the first page if macro TM is defined In groff it is defined to set the first page to page 1 PT text Specify the page title placed at the head of each page via text If not specified the page title defaults to 96 where 96 is the current page number RD Begin a right justified display without a keep Com pare with DS R IP tag indent Commence a new paragraph with an optional hang ing word or phrase if surrounded by quote marks The amount of indentation may also be specified such as IP Label 1 li which will add the text Label 1 to the output and indent all following lines by 1 inch LP Commence a left justified paragraph PP Commence a paragraph with the first line indented by the amount given in number register PI QP Commence a paragraph that is fully indented on both the left and right hand sides This is often used for quotations TA Set the tab setting to to 5n This macro may be rede fined say as de TA ta T 2i fc which would cause text separated by colons to appea
105. y cos theta Notice that I included braces as well as sur rounding the aliased expression with quotes The cos theta braces allow be to say ct over a b to get ze a E instead of cos which is not likely to be what I want The quote marks simply identify the com plete expression being aliased Greek letters etc Lower case Greek letters like alpha beta and so on produce a f and upper case PHI GAMMA yield T as you might expect 7 2 Words with Special Meaning in Equations Certain words are interpreted by eqn to mean certain mathematical symbols While all available symbols are described in the next section there is a short list of commonly used symbols for which easily remem bered names have been ascribed The following table lists them Special Words in Equations Input Output gt gt lt lt gt gt lt c lt lt gt gt gt inf co partial prime approx Revision 1 28 Groff and Friends HOWTO July 2001 25 Special Words in Equations Input Output nothing cdot times x del V grad V prod II union U inter A Selected mathematical words are printed in Roman font when used These are sin sinh arc log Re and cos cosh max In Im if tan tanh min exp det for 7 3 Other Symbols for Use in Equations There are many mathematical symbols available for your use far too many for me to list here If you do a

Groff and Friends HOWTO

Contents

Download Pdf Manuals

Related Search

Related Contents