1.\" Copyright (c) 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)mdoc.samples.7 5.6 (Berkeley) 07/01/91 7.\" 8.\" This sampler invokes every macro in the package several 9.\" times and is garanteed to give a worst case performance 10.\" for an already extremely slow package. 11.Dd 12.Os BSD 4.4 13.Dt MDOC.SAMPLES 7 14.Sh NAME 15.Nm mdoc.sample 16.Nd writing manual pages with 17.Nm -mdoc 18macro package 19.Sh SYNOPSIS 20.Nm man mdoc.sample 21.Sh DESCRIPTION 22A tutorial sampler for writing 23.Bx 24manual pages with the 25.Nm \-mdoc 26macro package, a 27.Em content Ns \-based 28formatting 29package for 30.Xr troff 1 . 31Its predecessor, the 32.Xr \-man 7 33package, 34addressed page structure leaving the 35manipulation of fonts and other 36typesetting details to the individual author. 37The 38.Nm \-mdoc 39package 40allows the author to ignore font considerations by 41using macros to label 42pieces of text according to content. 43In the context of manual pages, examples of content 44are a command name, a file pathname or a cross 45reference to another manual page; these 46items have value 47for both the author and the future user of the manual page. 48It is hoped the consistency gained 49across the manual set will provide easier 50translation to future documentation tools. 51.Pp 52Through out the 53.Ux 54manual pages, a manual entry 55is simply referred 56to as a man page, regardless of actual length and without 57sexist intention. 58.Sh TROFF IDIOSYNCRASIES 59The 60.Nm \-mdoc 61package attempts to simplify the process of writing a man page. 62Theoretically, one should not have to learn the dirty details of 63.Xr troff 1 64to use 65.Nm \-mdoc ; 66however, there are a few 67limitations which are unavoidable and best gotten out 68of the way. And, too, be forewarned, this package is 69.Em not 70fast. 71.Ss Macro Usage 72As in 73.Xr troff 1 , 74a macro is called by placing a 75.Ql \&\. 76(dot character) 77at the beginning of 78a line followed by the two character name for the macro. 79Arguments may follow the macro separated by spaces. 80It is the dot character at the beginning of the line which causes 81.Xr troff 1 82to interpret the next two characters as a macro name. 83To place a 84.Ql \&\. 85(dot character) 86at the beginning of a line in some context other than 87a macro macro, precede the 88.Ql \&\. 89(dot) with a 90.Ql \e& . 91.Pp 92In general, 93.Xr troff 1 94macros accept up to nine arguments, any 95extra arguments are ignored. 96Most macros in 97.Nm \-mdoc 98accept nine arguments and, 99in limited cases, arguments may be continued or extended 100on the 101next line (See 102.Sx Extensions 103\- 104macro 105.Ql \&.Xo 106and 107.Ql \&.Xc ) . 108A few macros handle quoted aguments (see 109.Sx Passing Space Characters in an Argument 110below). 111Many 112.Nm \-mdoc 113macros may be given the 114name of another macro as an argument. In this case 115the argument, although the name of a macro, 116is not preceded by a 117.Ql \&\. 118(dot), 119and is 120.Em called 121when the argument is processed. 122It is in this manner that some macros are nested; for 123example 124the option macro, 125.Ql \&.Op , 126may 127.Em call 128the flag and argument macros, 129.Ql \&.Fl 130and 131.Ql \&.Ar , 132to specify an optional flag with an argument: 133.nr D 1 134.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent 135.It Op Fl s Ar bytes 136is produced by 137.Li \&.Op \&Fl s \&Ar bytes 138.El 139.Pp 140To prevent a two character 141string from being interpreted as a macro name, precede 142the string with the 143escape sequence 144.Ql \e& : 145.Bl -tag -width "[\&Fl s \&Ar bytes]" -offset indent 146.It Op \&Fl s \&Ar bytes 147is produced by 148.Li \&.Op \e&Fl s \e&Ar bytes 149.El 150.Pp 151.nr D 0 152Here the strings 153.Ql \&Fl 154and 155.Ql \&Ar 156were not interpreted as macros. 157Details on callable macros are presented in the 158sections 159.Sx CONTENT MACROS 160and 161.Sx PAGE LAYOUT MACROS. 162.Ss Passing Space Characters in an Argument 163Sometimes it is desirable to give as one argument a string 164containing one or more blank space characters. This may be necessary 165to defeat the nine argument limit or to specify arguments to macros 166which expect particular arrangement of items in the argument list. 167For example, 168the function macro 169.Ql \&.Fn 170expects the first argument to be the name of a function and any 171remaining arguments to be function parameters. As 172.Tn "ANSI C" 173stipulates the declaration of function parameters in the 174parenthesized parameter list, each parameter is guaranteed 175to be at minimum a two word string. For example, 176.Fa int foo . 177There are two possible ways to pass an argument which contains 178an imbedded space. Unfortunately, the most convient way 179of passing such a space between quotes was too expensive to implement for 180all the macros. It is however, implemented for the following macros which need 181it the most: 182.Pp 183.Bl -tag -width 4n -offset indent -compact 184.It Li \&Cd 185Configuration declaration (section 4 SYNOPSIS) 186.It Li \&Bl 187Begin list (for the width specifier). 188.It Li \&Em 189Emphasized text. 190.It Li \&Fn 191Functions (sections two and four). 192.It Li \&It 193List items. 194.It Li \&Li 195Literal text. 196.It Li \&Sy 197Symbolic text. 198.It Li \&%B 199Book titles. 200.It Li \&%J 201Journal names. 202.It Li \&%O 203Optional notes for a reference. 204.It Li \&%R 205Report title (in a reference). 206.It Li \&%T 207Title of article in a book or journal. 208.El 209.Pp 210One way of passing a string 211containing blank spaces is to use the hard or unpaddable space character 212.Ql \e\ , 213that is, a blank space preceeded by the escape character 214.Ql \e . 215This method may be used with any macro but has the side effect 216of interfering with the adjustment of text 217over the length of a line. 218.Xr Troff 219sees the hard space as if it were any other printable character and 220cannot split the string into blank or newline separated pieces as one 221would expect. The method is useful for strings which are not expected 222to overlap a line boundary. For example: 223.Bl -tag -width "fetch(char *str)" -offset indent 224.It Fn fetch char\ *str 225is created by 226.Ql \&.Fn fetch char\e *str 227.It Fn fetch "char *str" 228can also be created by 229.Ql \&.Fn fetch "\\*q*char *str\\*q" 230.El 231.Pp 232If the 233.Ql \e 234or quotes 235were omitted, 236.Ql \&.Fn 237would see three arguments and 238the result would be: 239.Pp 240.Dl Fn fetch char *str 241.Pp 242For an example of what happens when the parameter list overlaps 243a newline boundary, see the 244.Sx BUGS 245section. 246.\" Note what happens if the parameter list overlaps a newline 247.\" boundary. For example, the next two examples are repeated several times 248.\" to make sure a line boundary is crossed: 249.\" .Bd -literal 250.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[] 251.\" .Ed 252.\" .Pp 253.\" produces, nudge nudge, 254.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , 255.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] , 256.\" nudge 257.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] . 258.\" .Pp 259.\" If double quotes are used, for example: 260.\" .Bd -literal 261.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q 262.\" .Ed 263.\" .Pp 264.\" produces, nudge nudge, 265.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , 266.\" nudge 267.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" , 268.\" nudge 269.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" . 270.\" .Pp 271.\" Not a pretty sight... 272.\" In a paragraph, a long parameter containing unpaddable spaces as 273.\" in the former example will cause 274.\" .Xr troff 275.\" to break the line and spread 276.\" the remaining words out. The latter example will adjust nicely to 277.\" justified margins, but may break in between an argument and its 278.\" declaration. In 279.\" .Xr nroff 280.\" the right margin adjustment is normally ragged and the problem is 281.\" not as severe. 282.Ss Trailing Blank Space Characters 283.Xr Troff 284can be confused by blank space characters at the end of a line. It 285is wise preventative measure to globally remove all blank spaces 286from <blank-space><end-of-line> character sequences. Should the need 287arise to force a blank character at the end of a line, 288it may be forced with an unpaddable space and the 289.Ql \e& 290escape character. 291For example, 292.Ql string\e\ \e& . 293.Ss Escaping Special Characters 294Special characters 295like the newline character 296.Ql \en , 297are handled by replacing the 298.Ql \e 299with 300.Ql \ee 301(e.g. 302.Ql \een ) 303to preserve 304the backslash. 305.Sh THE ANATOMY OF A MAN PAGE (Getting Started) 306There are three basic groups of macros: specific header macros 307called only once at the very beginning of 308each manual page, page layout or structure macros 309which may be called many times, and content macros which also 310may be called many times. 311The body of a man page is easily constructed from a basic 312template found in the file: 313.Bd -literal -offset indent 314\&.\e" /usr/share/misc/man.tempate : 315\&.\e" The following six lines are required. 316\&.Dt DOCUMENT_TITLE [section number] [volume] 317\&.Os OPERATING_SYSTEM [version/release] 318\&.Dd Month day, year 319\&.Sh NAME 320\&.Sh SYNOPSIS 321\&.Sh DESCRIPTION 322\&.\e" The following requests should be uncommented and 323\&.\e" used where appropriate. This next request is 324\&.\e" for sections 2 and 3 function return values only. 325\&.\e" .Sh RETURN VALUES 326\&.\e" This next request is for sections 1, 6, 7 & 8 only 327\&.\e" .Sh ENVIRONMENT 328\&.\e" .Sh FILES 329\&.\e" .Sh EXAMPLES 330\&.\e" This next request is for sections 1, 6, 7 & 8 only 331\&.\e" (command return values (to shell) and 332\&.\e" fprintf/stderr type diagnostics) 333\&.\e" .Sh DIAGNOSTICS 334\&.\e" The next request is for sections 2 and 3 error 335\&.\e" and signal handling only. 336\&.\e" .Sh ERRORS 337\&.\e" .Sh SEE ALSO 338\&.\e" .Sh STANDARDS 339\&.\e" .Sh HISTORY 340\&.\e" .Sh AUTHORS 341\&.\e" .Sh BUGS 342.Ed 343.Pp 344The first items in the template are the macros 345.Pq Li \&.Dt , \&.Dd , \&.Os ; 346the document or man page title 347.Pq Em in upper case , 348the section of the manual the page 349belongs to, the (document) date, 350and the operating system the man page is derived 351from. These macros identify the page, 352and are discussed below in 353.Sx TITLE MACROS . 354.Pp 355The remaining items in the template are section headers 356.Pq Li \&.Sh ; 357of which NAME, SYNOPSIS and DESCRIPTION 358are mandatory. The 359headers are 360discussed in 361.Sx PAGE LAYOUT MACROS, 362after 363presentation of 364.Sx CONTENT MACROS . 365Several content macros are used to demonstrate page layout macros; 366reading about content macros before page layout macros is 367recommended. 368.Sh TITLE MACROS 369Three header macros designate the document title or manual page title, 370the operating system, 371and the date of authorship. 372These macros are one called once at the very beginning of the document 373and are used to construct the headers and footers only. 374.Bl -tag -width 6n 375.It Li \&.Dt DOCUMENT_TITLE section# [volume] 376The document title is the 377subject of the man page and must be in CAPITALS due to troff 378limitations. 379The section number may be 1,\ ...,\ 8, 380and if it is specified, 381the volume title may be omitted. 382A volume title may be arbitrary or one of the following: 383.\" .Cl 384.\" USD UNIX User's Supplementary Documents 385.\" .Cl 386.\" PS1 UNIX Programmers's Supplementary Documents 387.Pp 388.Bl -column SMM -offset indent -compact 389.It AMD UNIX Ancestral Manual Documents 390.It SMM UNIX System Manager's Manual 391.It URM UNIX Reference Manual 392.It PRM UNIX Programmers's Manual 393.El 394.Pp 395.\" .Cl 396.\" MMI UNIX Manual Master Index 397.\" .Cl 398.\" CON UNIX Contributed Software Manual 399.\" .Cl 400.\" LOC UNIX Local Manual 401.It Li \&.Os operating_system release# 402The name of the operating system 403should be the common acronym, e.g. BSD 404or ATT. The release should be the standard release 405nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3, 406V.4. Unrecognized arguments are displayed as given in the page footer. 407For instance, for the footer on this page, the 4.4 Berkeley Distribution 408was produced by: 409.Pp 410.Dl \&.Os BSD 4.4 411.It Li \&.Dd month day, year 412The date should be written formally: 413.Pp 414.Dl January 25, 1989 415.El 416.Sh CONTENT MACROS 417.Ss What's in a name... 418Content macro names are derived from the day to day 419informal language used to describe commands, subroutines and related 420files. Slightly 421different variations of this language are used to describe 422the three different aspects of writing a man page. 423First, there is the description of 424.Nm \-mdoc 425macro request usage. 426Second is the description of a 427.Ux 428command 429.Em with 430.Nm \-mdoc 431macros and third, 432the 433description a command to a user in the verbal sense; 434that is, discussion of a command in the text of a man page. 435.Pp 436In the first case, 437.Xr troff 1 438macros are themselves a type of command; 439the general syntax for a troff command is: 440.Bd -filled -offset indent 441\&.Va argument1 argument2 ... argument9 442.Ed 443.Pp 444The 445.Ql \&.Va 446is a macro command or request, and anything following it is an argument to 447be processed. 448In the second case, 449the description of a 450.Ux 451command using the content macros is a 452bit more involved; 453a typical SYNOPSIS command line might be displayed as: 454.Pp 455.Bd -filled -offset indent 456.Nm filter 457.Op Fl flag 458.Ar infile outfile 459.Ed 460.Pp 461Here, 462.Nm filter 463is the command name and the 464bracketed string 465.Fl flag 466is a 467.Em flag 468argument designated as optional by the option brackets. 469In 470.Nm \-mdoc 471terms, 472.Ar infile 473and 474.Ar outfile 475are 476called 477.Em arguments . 478The macros which formatted the above example: 479.Pp 480.Bd -literal -offset indent 481\&.Nm filter 482\&.Op \&Fl flag 483\&.Ar infile outfile 484.Ed 485.Pp 486In the third case, discussion of commands and command syntax 487includes both examples above, but may add more detail. The 488arguments 489.Ar infile 490and 491.Ar outfile 492from the example above might be refered to as 493.Em operands 494or 495.Em file arguments . 496Some command line argument lists are quite long: 497.\" .Bl -tag -width make -offset indent 498.Bl -tag -width make -offset indent 499.It Nm make 500.Op Fl eiknqrstv 501.Op Fl D Ar variable 502.Op Fl d Ar flags 503.Op Fl f Ar makefile 504.Op Fl I Ar directory 505.Op Fl j Ar max_jobs 506.Op Ar variable=value 507.br 508.Op Ar "target\ ..." 509.El 510.Pp 511Here one might talk about the command 512.Nm make 513and qualify the argument 514.Ar makefile , 515as an argument to the flag, 516.Fl f , 517or discuss the optional 518file 519operand 520.Ar target . 521In the verbal context, such detail can prevent confusion, 522however the 523.Nm \-mdoc 524package 525does not have a macro for an argument 526.Em to 527a flag. 528Instead the 529.Ql \&Ar 530argument macro is used for an operand or file argument like 531.Ar target 532as well as an argument to a flag like 533.Ar variable : 534.Bd -literal -offset indent 535\&.Nm make 536\&.Op Fl eiknqrstv 537\&.Op Fl D Ar variable 538\&.Op Fl d Ar flags 539\&.Op Fl f Ar makefile 540\&.Op Fl I Ar directory 541\&.Op Fl j Ar max_jobs 542\&.Op Ar variable=value 543\&.Op Ar target ... 544.Ed 545.Ss General Syntax 546All content macros share a similar 547syntax with a few minor deviations: 548.Ql \&.Ar , 549.Ql \&.Fl , 550.Ql \&.Nm , 551and 552.Ql \&.Pa 553differ only when called without arguments; 554.Ql \&.Fn 555and 556.Ql \&.Xr 557impose an order on their argument lists 558and the 559.Em enclosure 560and 561.Em quoting 562macros 563have nesting limitations. All content macros 564are capable of handling punctuation. 565Any argument which may be tested for punctuation 566and contains a member of the mathematical, logical or 567quotation set: 568.Bd -literal -offset indent -compact 569{+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"} 570.Ed 571should have 572the character escaped with 573.Ql \e& . 574Typical syntax is shown in the first content macro displayed 575below, 576.Ql \&.Ad , 577and the syntax for enclosure/quoting macros is shown in 578.Sx Enclosure and Quoting Macros . 579.Ss Address Macro 580The address macro constructs an address 581of the form addr1[,addr2[,addr3]]. 582.Pp 583.Dl Usage: .Ad address ... \*(Pu 584.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n 585.It Li \&.Ad addr1 586.Ad addr1 587.It Li \&.Ad addr1\ . 588.Ad addr1 . 589.It Li \&.Ad addr1\ , file2 590.Ad addr1 , file2 591.It Li \&.Ad f1\ , f2\ , f3\ : 592.Ad f1 , f2 , f3 : 593.It Li \&.Ad addr\ )\ )\ , 594.Ad addr ) ) , 595.El 596.Pp 597It is an error to call 598.Li \&.Ad 599without arguments. 600.Li \&.Ad 601is callable by other macros and may call other macros. 602.Ss Argument Macro 603The 604.Li \&.Ar 605argument macro may be used whenever 606a command line argument is referenced. 607.Pp 608.Dl Usage: .Ar argument ... \*(Pu 609.Bl -tag -width ".Ar file1 file2" -compact -offset 15n 610.It Li \&.Ar 611.Ar 612.It Li \&.Ar file1 613.Ar file1 614.It Li \&.Ar file1\ . 615.Ar file1 . 616.It Li \&.Ar file1 file2 617.Ar file1 file2 618.It Li \&.Ar f1 f2 f3\ : 619.Ar f1 f2 f3 : 620.It Li \&.Ar file\ )\ )\ , 621.Ar file ) ) , 622.El 623.Pp 624If 625.Li \&.Ar 626is called without arguments 627.Ql Ar 628is assumed. The 629.Li \&.Ar 630macro may call other macros, and may be 631called by other macros. 632.Ss Angle Bracket Quote/Enclosure 633Encloses a string or strings in between angle brackets. The macro 634.Ql \&.Aq 635encloses the remaining arguments on the macro command line, and the 636.Ql \&.Ao 637(angle open) and 638.Ql \&.Ac 639(angle close) macros may be used across one or more lines. 640.Pp 641.Dl Usage: .Aq string ... \*(Pu 642.Bl -tag -width ".Aq Pa ctype.h ) ," -compact -offset 14n 643.It Li \&.Aq 644.Aq 645.It Li \&.Aq string. 646.Aq string. 647.It Li \&.Aq string\ . 648.Aq string . 649.It Li \&.Aq stdio.h 650.Aq stdio.h 651.It Li \&.Aq \&Ar ctype.h\ )\ , 652.Aq Ar ctype.h ) , 653.El 654.Pp 655See 656.Sx Enclosure Macros 657for discussion and 658.Sx Options 659for examples of the open and close 660macros 661.Ql \&.Ac 662and 663.Ql \&.Ao . 664.Ql \&.Aq 665is callable by other macros and may call other macros. 666.Ss Bracket Quotes/Enclosure 667Bracket quotes should be used when the string being bracketed is 668.Em not 669an option string. The brackets for an option may be different 670than the default brackets. The macro 671.Ql \&.Bq 672encloses the remaining arguments on a macro command line and the 673macros 674.Ql \&.Bo 675and 676.Ql \&.Bc 677may be used across one or more lines. 678.Pp 679.Dl Usage: .Bq string ... \*(Pu 680.Pp 681The 682.Li \&.Bq 683macro exists for statements which use other macros: 684.Bq Em Greek , French . 685This was done with: 686.Pp 687.Dl Li \&.Bq \&Em Greek \&, French \&. 688.Pp 689It also could have been done using the prefix macro: 690.Pp 691.Dl Li ".Pf [ Em Greek , French ] ." 692.Pp 693See 694.Sx Enclosure Macros 695for discussion and 696.Sx Options 697for examples of the open and close 698macros 699.Ql \&.Bc 700and 701.Ql \&.Bo . 702The 703.Ql \&.Bq 704macro 705is callable and may call other macros. 706.Ss Configuration Declaration (section four only) 707The 708.Ql \&.Cd 709macro is used to demonstrate a 710.Xr config 8 711declaration for a device interface in a section four manual. 712This macro accepts quoted arguments (double quotes only). 713.Pp 714.Bl -tag -width "device le0 at scode?" -offset indent 715.It Cd "device le0 at scode?" 716produced by: 717.Ql ".Cd device le0 at scode?" . 718.El 719.Ss Command Modifier 720The command modifier is identical to the 721.Ql \&.Fl 722(flag) command with the exception 723the 724.Ql \&.Cm 725macro does not assert a dash 726in front of every argument. Traditionally flags are marked by the 727preceding dash, some commands or subsets of commands do not use them. 728Command modifiers may also be specified in conjunction with interactive 729commands such as editor commands. 730See 731.Sx Flags . 732.Ss Double Quote macro/Enclosure 733The 734.Ql \&.Dq 735double quote encloses 736any remaining strings on the command line with double quotes. 737Punctuation is 738placed after the end quote. 739The macros 740.Ql \&.Do 741and 742.Ql \&.Dc 743may be used across one or more lines. 744.Pp 745.Dl Usage: .Dq string ... \*(Pu 746.Bl -tag -width ".Dq Ar patternx ) ) ," -compact -offset 14n 747.It Li \&.Dq 748.Dq 749.It Li ".Dq string." 750.Dq string. 751.It Li ".Dq string abc ." 752.Dq string abc . 753.It Li ".Dq \'^[A-Z]\'" 754.Dq \'^[A-Z]\' 755.It Li \&.Dq \&Ar pattern\ )\ )\ , 756.Dq Ar pattern ) ) , 757.El 758.Pp 759If 760.Ql \&.Dq 761is called with no arguments 762.Dq 763is assumed. The 764.Ql \&.Dq 765macro may call or be called by 766other macros. 767See 768.Sx Enclosure Macros 769for discussion of 770.Ql \&.Dc 771and 772.Ql \&.Do 773macro types. 774.Ss Defined Variables 775A variable which is defined in an include file is specified 776by the macro 777.Ql \&.Dv . 778.Pp 779.Dl Usage: .Dv defined_variable ... \*(Pu 780.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n 781.It Li ".Dv MAXHOSTNAMELEN" 782.Dv MAXHOSTNAMELEN 783.It Li ".Dv TIOCGPGRP )" 784.Dv TIOCGPGRP ) 785.El 786.Pp 787It is an error to call 788.Ql \&.Dv 789without arguments. 790.Ql \&.Dv 791may call other macros and 792may be called by other macros. 793.Ss Emphasis Macro 794Text may be stressed or emphasized with the 795.Ql \&.Em 796macro. The usual font for emphasis is italic. 797.Pp 798.Dl Usage: .Em argument ... \*(Pu 799.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n 800.It Li ".Em does not" 801.Em does not 802.It Li ".Em exceed 1024 ." 803.Em exceed 1024 . 804.It Li ".Em vide infra ) ) ," 805.Em vide infra ) ) , 806.El 807.Pp 808The emphasis can be forced across several lines of text by using 809the 810.Ql \&.Bf 811macro discussed in 812.Sx Modes 813under 814.Sx PAGE LAYOUT . 815.\" .Pp 816.\" .Em 817.\" I'm certain the reason so many people desire an MBA from Harvard 818.\" is because they want to be successful philanthropists. 819.\" .Em 820.Pp 821The 822.Ql \&.Em 823macro 824is callable and may call other macros. 825It is an error to call 826.Ql \&.Em 827without arguments. 828.Ss Enclosure and Quoting Macros 829The concept of enclosure is similar to quoting. 830The object is to enclose a string or more between 831a pair of characters like quotes or parentheses. 832The terms quoting and enclosure are used 833interchangeably throughout this document. Many of the 834one line enclosure macros end 835end in small letter 836.Ql q 837to give a hint of quoting, but there are a few exceptions 838(the macros 839.Ql \&.En , 840.Ql \&.Fn 841and 842.Ql \&.Op 843are also enclosure macros). 844For each enclosure macro 845there is also a pair of open and close macros which end 846in small letters 847.Ql o 848and 849.Ql c 850respectively. These can be used across one or more lines of text 851and while they cannot be nested, the one line quote macros 852can be used inside 853of them. 854For a good example of one these macros, see 855.Sx Options . 856.Pp 857.Bd -filled -offset indent 858.Bl -column "quote" "close" "open" "Enclose Stringx(in XX)" XXstringXX 859.Em " quote close open function result" 860\&.Aq, .Ac, .Ao Angle Bracket Enclosure <string> 861\&.Bq, .Bc, .Bo Bracket Enclosure [string] 862\&.Dq, .Dc, .Do Double Quote ``string'' 863 .Ec, .Eo Enclose String (in XX) XXstringXX 864\&.Fn, .Fc, .Fo Function Enclosure function(string) 865\&.Op, .Oc, .Oo Option Enclosure [string] 866\&.Pq, .Pc, .Po Parenthesis Enclosure (string) 867\&.Qq, .Qc, .Qo Straight Double Quote "string" 868\&.Sq, .Sc, .So Single Quote `string' 869\& .Xc, .Xo Extend Argument \ \-\- 870.El 871.Ed 872.Pp 873The macros 874.Ql \&.Eo 875and 876.Ql \&.Ec 877allow a user to specify an open and close with the first argument as the 878opening or closing string respectively. 879.Ss Errno's (Section two only) 880The 881.Ql \&.Er 882errno macro specifies the error return value 883for section two library routines. The second example 884below shows 885.Ql \&.Er 886used with the 887.Ql \&.Bq 888macro, as it would be used in 889a section two manual page. 890.Pp 891.Dl Usage: .Er ERRNOTYPE ... \*(Pu 892.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n 893.It Li \&.Er ENOENT 894.Er ENOENT 895.It Li \&.Er ENOENT\ )\ ; 896.Er ENOENT ) ; 897.It Li \&.Bq \&Er ENOTDIR 898.Bq Er ENOTDIR 899.El 900.Pp 901It is an error to call 902.Ql \&.Er 903without arguments. 904The 905.Ql \&.Er 906macro 907is callable and may call other macros. 908.Ss Environment Variables 909The 910.Ql \&.Ev 911macro specifies a environment variable. 912.Pp 913.Dl Usage: .Ev argument ... \*(Pu 914.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n 915.It Li \&.Ev DISPLAY 916.Ev DISPLAY 917.It Li \&.Ev PATH\ . 918.Ev PATH . 919.It Li \&.Ev PRINTER\ )\ )\ , 920.Ev PRINTER ) ) , 921.El 922.Pp 923It is an error to call 924.Ql \&.Ev 925without arguments. 926The 927.Ql \&.Ev 928macro 929is callable by other macros and may call other macros. 930.Ss Function Argument 931The 932.Ql \&.Fa 933macro is used to refer to function arguments (parameters) 934outside of the SYNOPSIS section of the manual or inside 935the SYNOPSIS section should a parameter list be too 936long for the 937.Ql \&.Fn 938macro and the enclosure macros 939.Ql \&.Fo 940and 941.Ql \&.Fc 942must be used. 943.Ql \&.Fa 944may also be used to refer to structure members. 945.Pp 946.Dl Usage: .Fa function_argument ... \*(Pu 947.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n 948.It Li \&.Fa d_namlen\ )\ )\ , 949.Fa d_namlen ) ) , 950.It Li \&.Fa iov_len 951.Fa iov_len 952.El 953.Pp 954It is an error to call 955.Ql \&.Fa 956without arguments. 957.Ql \&.Fa 958is callable by other macros and may call other macros. 959.Ss Function Declaration 960The 961.Ql \&.Fd 962macro is used in the SYNOPSIS section with section two or three 963functions. The 964.Ql \&.Fd 965macro does not call other macros and is not callable by other 966macros. 967.Pp 968.Dl Usage: .Fd include_file (or defined variable) 969.Pp 970In the SYNOPSIS section a 971.Ql \&.Fd 972request causes a line break if a function has already been presented 973and a break has not occurred. This leaves a nice vertical space 974in between the previous function call and the declaration for the 975next function. 976.Ss Flags 977The 978.Ql \&.Fl 979macro handles command line flags. It prepends 980a dash, 981.Ql \- , 982to the flag. For interactive command flags, which 983are not prepended with a dash, the 984.Ql \&.Cm 985(command modifier) 986macro is identical, but with out the dash. 987.Pp 988.Dl Usage: .Fl argument ... \*(Pu 989.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n 990.It Li \&.Fl 991.Fl 992.It Li \&.Fl cfv 993.Fl cfv 994.It Li \&.Fl cfv\ . 995.Fl cfv . 996.It Li \&.Fl s v t 997.Fl s v t 998.It Li \&.Fl -\ , 999.Fl - , 1000.It Li \&.Fl xyz\ )\ , 1001.Fl xyz ) , 1002.El 1003.Pp 1004The 1005.Ql \&.Fl 1006macro without any arguments results 1007in a dash representing stdin/stdout. 1008Note that giving 1009.Ql \&.Fl 1010a single dash, will result in two dashes. 1011The 1012.Ql \&.Fl 1013macro 1014is callable and may call other macros. 1015.Ss Functions (library routines) 1016The .Fn macro is modeled on ANSI C conventions. 1017.Bd -literal 1018Usage: .Fn [type] function [[type] params ... \*(Pu] 1019.Ed 1020.Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact 1021.It Li "\&.Fn getchar" 1022.Fn getchar 1023.It Li "\&.Fn strlen ) ," 1024.Fn strlen ) , 1025.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" , 1026.Fn "int align" "const * char *sptrs" , 1027.El 1028.Pp 1029It is an error to call 1030.Ql \&.Fn 1031without any arguments. 1032The 1033.Ql \&.Fn 1034macro 1035is callable by other macros and may call other macros, but 1036note that any call to another macro signals the end of 1037the 1038.Ql \&.Fn 1039call (it will close-paren at that point). 1040.Pp 1041In the SYNOPSIS section, the function will always begin at 1042the beginning of line. If there is more than one function 1043presented in the SYNOPSIS section and a function type has not been 1044given, a line break will occur, leaving a nice vertical space 1045between the current function name and the one prior. 1046At the moment, 1047.Ql \&.Fn 1048does not check its word boundaries 1049against troff line lengths and may split across a newline 1050ungracefully. This will be fixed in the near future. 1051.Ss Function Type 1052This macro is intended for the SYNOPSIS section. It may be used 1053anywhere else in the manpage without problems, but its main purpose 1054is to present the function type in kernel normal form for the SYNOPSIS 1055of sections two and three 1056(it causes a page break allowing the function name to appear 1057on the next line). 1058.Pp 1059.Dl Usage: .Ft type ... \*(Pu 1060.Pp 1061.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact 1062.It Li \&.Ft struct stat 1063.Ft struct stat 1064.El 1065.Pp 1066The 1067.Ql \&.Ft 1068request is not callable by other macros. 1069.Ss Interactive Commands 1070The 1071.Ql \&.Ic 1072macro designates an interactive or internal command. 1073.Pp 1074.Dl Usage: .Li argument ... \*(Pu 1075.Bl -tag -width ".Ic setenv , unsetenv" -compact -offset 14n 1076.It Li \&.Ic :wq 1077.Ic :wq 1078.It Li \&.Ic do while {...} 1079.Ic do while {...} 1080.It Li \&.Ic setenv\ , unsetenv 1081.Ic setenv , unsetenv 1082.El 1083.Pp 1084It is an error to call 1085.Ql \&.Ic 1086without arguments. 1087The 1088.Ql \&.Ic 1089macro may call other macros and is callable. 1090.Ss Literals 1091The 1092.Ql \&.Li 1093literal macro may be used for special characters, 1094variable constants, anything which should be displayed as it 1095would be typed. 1096.Pp 1097.Dl Usage: .Li argument ... \*(Pu 1098.Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n 1099.It Li \&.Li \een 1100.Li \en 1101.It Li \&.Li M1 M2 M3\ ; 1102.Li M1 M2 M3 ; 1103.It Li \&.Li cntrl-D\ )\ , 1104.Li cntrl-D ) , 1105.It Li \&.Li 1024\ ... 1106.Li 1024 ... 1107.El 1108.Pp 1109The 1110.Ql \&.Li 1111macro 1112is callable by other macros and may call other macros. 1113.Ss Name Macro 1114The 1115.Ql \&.Nm 1116macro is used for the document title or subject name. 1117It has the peculiarity of remembering the first 1118argument it was called with, which should 1119always be the subject name of the page. When called without 1120arguments, 1121.Ql \&.Nm 1122regurgitates this initial name for the sole purpose 1123of making less work for the author. 1124Note: 1125a section two 1126or three document function name is addressed with the 1127.Ql \&.Nm 1128in the NAME section, and with 1129.Ql \&.Fn 1130in the SYNOPSIS 1131and remaining sections. 1132For interactive commands, such as the 1133.Ql while 1134command keyword in 1135.Xr csh 1 , 1136the 1137.Ql \&.Ic 1138macro should be used. 1139While the 1140.Ql \&.Ic 1141is nearly identical 1142to 1143.Ql \&.Nm , 1144it can not recall the first argument it was invoked with. 1145.Pp 1146.Dl Usage: .Nm argument ... \*(Pu 1147.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n 1148.It Li \&.Nm mdoc.sample 1149.Nm mdoc.sample 1150.It Li \&.Nm \-mdoc 1151.Nm \-mdoc . 1152.It Li \&.Nm foo\ )\ )\ , 1153.Nm foo ) ) , 1154.It Li \&.Nm 1155.Nm 1156.El 1157.Pp 1158The 1159.Ql \&.Nm 1160macro 1161is callable by other macros and may call other macros. 1162.Ss No\-Op or Normal Text Macro 1163The macro 1164.Li \&.No 1165is 1166a hack for words in a macro command line which should 1167.Em not 1168be formatted and follows the conventional syntax 1169for content macros. 1170.Ss No Space Macro 1171The 1172.Ql \&.Ns 1173macro eliminates unwanted spaces in between macro requests. 1174It is useful for old style argument lists where there is no space 1175between the flag and argument: 1176.Bl -tag -width ".Op Fl I Ns Ar directory" -offset indent 1177.It Li ".Op Fl I Ns Ar directory" 1178produces 1179.Op Fl I Ns Ar directory 1180.El 1181.Pp 1182Note: the 1183.Ql \&.Ns 1184macro always invokes the 1185.Ql \&.No 1186macro after eliminating the space unless another macro name 1187follows it. 1188The macro 1189.Ql \&.Ns 1190is callable and may call other macros. 1191.Ss Options 1192The 1193.Ql \&.Op 1194macro 1195places option brackets around the any remaining arguments on the command 1196line, and places any 1197trailing punctuation outside the brackets. The macros 1198.Ql \&.Oc 1199and 1200.Ql \&.Oo 1201may be used across one or more lines. 1202.Pp 1203.Dl Usage: .Op options ... \*(Pu 1204.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent 1205.It Li \&.Op 1206.Op 1207.It Li ".Op Fl k" 1208.Op Fl k 1209.It Li ".Op Fl k ) ." 1210.Op Fl k ) . 1211.It Li ".Op Fl k Ar kookfile" 1212.Op Fl k Ar kookfile 1213.It Li ".Op Fl k Ar kookfile ," 1214.Op Fl k Ar kookfile , 1215.It Li ".Op Ar objfil Op Ar corfil" 1216.Op Ar objfil Op Ar corfil 1217.It Li ".Op Fl c Ar objfil Op Ar corfil ," 1218.Op Fl c Ar objfil Op Ar corfil , 1219.It Li \&.Op word1 word2 1220.Op word1 word2 1221.El 1222.Pp 1223The 1224.Ql \&.Oc 1225and 1226.Ql \&.Oo 1227macros: 1228.Bd -literal -offset indent 1229\&.Oo 1230\&.Op \&Fl k \&Ar kilobytes 1231\&.Op \&Fl i \&Ar interval 1232\&.Op \&Fl c \&Ar count 1233\&.Oc 1234.Ed 1235.Pp 1236Produce: 1237.Oo 1238.Op Fl k Ar kilobytes 1239.Op Fl i Ar interval 1240.Op Fl c Ar count 1241.Oc 1242.Pp 1243The macros 1244.Ql \&.Op , 1245.Ql \&.Oc 1246and 1247.Ql \&.Oo 1248are callable and may call other macros. 1249.Ss Parenthesis Quote/Enclosure 1250Macros 1251.Li \&.Pq , \&.Pc 1252and 1253.Li \&.Po 1254follow the conventions for a typical quoting macros, 1255see 1256.Sx Enclosure Macros 1257and 1258.Sx Options 1259above. 1260.Ss Pathnames 1261The 1262.Ql \&.Pa 1263macro formats path or file names. 1264.Pp 1265.Dl Usage: .Pa pathname \*(Pu 1266.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n 1267.It Li \&.Pa /usr/share 1268.Pa /usr/share 1269.It Li \&.Pa /tmp/fooXXXXX\ )\ . 1270.Pa /tmp/fooXXXXX ) . 1271.El 1272.Pp 1273The 1274.Ql \&.Pa 1275macro 1276is callable by other macros and may call other macros. 1277.Ss Single Quotes/Enclosure 1278See 1279.Sx Enclosure Macros . 1280See 1281.Sx Double Quote/Enclosure 1282above. 1283The single quoting macro 1284.Ql \&.Sq 1285works in the identical manner as 1286.Ql \&.Dq. 1287.Ss Prefix Macro 1288The 1289.Ql \&.Pf 1290macro 1291is a short cut for combining 1292two strings together, the first of which is 1293in the default font, and the second a content 1294specified string. 1295.Pp 1296.Bl -tag -width ".Pf ( Fa name2 " -offset 14n -compact 1297.It Li ".Pf ( Fa name2" 1298becomes 1299.Pf ( Fa name2 1300.El 1301.Pp 1302The 1303.Ql \&.Pf 1304macro is not callable, but may call other macros. The 1305.Ql \&.Ns 1306macro performs the analogus suffix function. 1307.Ss Section Cross References 1308The 1309.Ql \&.Sx 1310macro designates a reference to a section header 1311within the same document. It is callable by other macros and may 1312call other macros. 1313.Pp 1314.Bl -tag -width "Li \&.Sx FILES" -offset 14n 1315.It Li \&.Sx FILES 1316.Sx FILES 1317.El 1318.Ss References and Citations 1319The following macros make a modest attempt to handle references. 1320At best, the macros make it convientent to manually drop in a subset of 1321refer style references. 1322.Pp 1323.Bl -tag -width 6n -offset indent -compact 1324.It Li ".Rs" 1325Reference Start. Causes a line break and begins collection 1326of reference information until the 1327reference end macro is read. 1328.It Li ".Re" 1329Reference End. The reference is printed. 1330.It Li ".%A" 1331Reference author name, one name per invocation. 1332.It Li ".%B" 1333Book title. 1334.It Li ".%J" 1335Journal title. 1336.It Li ".%N" 1337Issue number. 1338.It Li ".%O" 1339Optional information. 1340.It Li ".%R" 1341Report name. 1342.It Li ".%T" 1343Title of article. 1344.It Li ".%V" 1345Volume(s). 1346.El 1347.Pp 1348The macros begining with 1349.Ql % 1350are not callable, but may call only the trade name macro which 1351returns to its caller. The purpose is to allow trade names 1352to be pretty printed in troff/ditroff output. WARNING: this 1353has very few trade names defined at the moment and will print unknown 1354trade names in the default font. 1355.Ss Symbolic 1356The symbolic emphasis macro is generally a boldface macro in 1357either the symbolic sense or the traditional English usage. 1358.Pp 1359.Dl Usage: .Sy symbol ... \*(Pu 1360.Bl -tag -width ".Sy Important Notice" -compact -offset 14n 1361.It Li \&.Sy Important Notice 1362.Sy Important Notice 1363.El 1364.Pp 1365The 1366.Ql \&.Sy 1367macro 1368is callable by other macros and may call other macros, except 1369in the second form. Arguments to 1370.Ql \&.Sy 1371may be quoted. 1372.Ss Variables 1373Generic variable reference: 1374.Pp 1375.Dl Usage: .Va variable ... \*(Pu 1376.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n 1377.It Li \&.Va count 1378.Va count 1379.It Li \&.Va settimer , 1380.Va settimer , 1381.It Li \&.Va int\ *prt\ )\ : 1382.Va int\ *prt ) : 1383.It Li \&.Va char\ s\ ]\ )\ )\ , 1384.Va char\ s ] ) ) , 1385.El 1386.Pp 1387It is an error to call 1388.Ql \&.Va 1389without any arguments. 1390The 1391.Ql \&.Va 1392macro 1393is callable by other macros and may call other macros. 1394.Ss Cross References 1395The 1396.Ql \&.Xr 1397macro expects the first argument to be 1398a manual page name, and the second argument, if it exists, 1399to be either a section page number or punctuation. Any 1400remaining arguments are assumed to be punctuation. 1401.Pp 1402.Dl Usage: .Xr manpage [1,...,8] \*(Pu 1403.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n 1404.It Li \&.Xr mdoc 1405.Xr mdoc 1406.It Li \&.Xr mdoc\ , 1407.Xr mdoc , 1408.It Li \&.Xr mdoc 7 1409.Xr mdoc 7 1410.It Li \&.Xr mdoc 7\ )\ )\ , 1411.Xr mdoc 7 ) ) , 1412.El 1413.Pp 1414The 1415.Ql \&.Xr 1416macro 1417is callable by other macros and may call other macros. 1418It is an error to call 1419.Ql \&.Xr 1420without 1421any arguments. 1422.Ss Extended Arguments 1423The 1424.Li \&.Xo 1425and 1426.Li \&.Xc 1427maxros allow one to extend an argument list 1428on a macro boundary. Argument lists cannot 1429be extended within a macro 1430which expects all of its arguments on one line such 1431as 1432.Ql \&.Op . 1433.\" --- 1434.Sh PAGE LAYOUT MACROS 1435.Ss Section Headers 1436The first three 1437.Ql \&.Sh 1438section header macros 1439list below are required in every 1440man page. The remaining section headers 1441are recommended at the disgression of the author 1442writing the manual page. The 1443.Ql \&.Sh 1444macro can take up to nine arguments. It may call 1445other macros, but it may not be called by other macros. 1446.Bl -tag -width ".Sh SYNOPSIS" 1447.It \&.Sh NAME 1448The 1449.Ql \&.Sh NAME 1450macro is mandatory. If not specified, 1451the headers, footers and page layout defaults 1452will not be set and things will be rather unpleasant. 1453The NAME section consists of at least three items. 1454The first is the 1455.Ql \&.Nm 1456name macro naming the subject of the man page. 1457The second is the Name Description macro, 1458.Ql \&.Nd , 1459which separates the subject 1460name from the third item, which is the description. The 1461description should be the most terse and lucid possible, 1462as the space available is small. 1463.It \&.Sh SYNOPSIS 1464The SYNOPSIS section describes the typical usage of the 1465subject of a man page. The macros required 1466are either 1467.Ql ".Nm" , 1468.Ql ".Cd" , 1469or 1470.Ql ".Fn" 1471(and possibly 1472.Ql ".Fd" , 1473.Ql ".Ft" 1474macros). 1475The function name 1476macro 1477.Ql ".Fn" 1478is required 1479for manual page sections 2 and 3, the command and general 1480name macro 1481.Ql \&.Nm 1482is required for sections 1, 5, 6, 7, 8. 1483Section 4 manuals require a 1484.Ql ".Nm" , ".Fd" 1485or a 1486.Ql ".Cd" 1487configuration device usage macro. 1488Several other macros may be necessary to produce 1489the synopsis line as shown below: 1490.Pp 1491.Bd -filled -offset indent 1492.Nm cat 1493.Op Fl benstuv 1494.Op Fl 1495.Ar 1496.Ed 1497.Pp 1498The following macros were used: 1499.Pp 1500.Dl \&.Nm cat 1501.Dl \&.Op \&Fl benstuv 1502.Dl \&.Op \&Fl 1503.Dl \&.Ar 1504.It \&.Sh DESCRIPTION 1505In most cases the first text in the DESCRIPTION section 1506is a brief paragraph on the command, function or file, 1507followed by a lexical list of options and respective 1508explanations. To create such a list, the 1509.Ql \&.Bl 1510begin-list, 1511.Ql \&.It 1512list-item and 1513.Ql \&.El 1514end-list 1515macros are used (see 1516.Sx Lists and Columns 1517below). 1518.El 1519.Pp 1520The following 1521.Ql \&.Sh 1522section headers are part of the 1523preferred manual page layout and must be used appropriately 1524to maintain consistency. They are listed in the order 1525in which they would be used. 1526.Bl -tag -width SYNOPSIS 1527.It \&.Sh ENVIRONMENT 1528The ENVIRONMENT section should reveal any related 1529environment 1530variables and clues to their behaviour and/or usage. 1531.It \&.Sh EXAMPLES 1532There are several ways to create examples. See 1533the EXAMPLES section below 1534for details. 1535.It \&.Sh FILES 1536Files which are used or created by the man page subject 1537should be listed via the 1538.Ql \&.Pa 1539macro in the FILES section. 1540.It \&.Sh SEE ALSO 1541References to other material on the man page topic and 1542cross references to other relevant man pages should 1543be placed in the SEE ALSO section. Cross references 1544are specified using the 1545.Ql \&.Xr 1546macro. At this time 1547.Xr refer 1 1548style references are not accommodated. 1549.It \&.Sh STANDARDS 1550If the command, library function or file adheres to a 1551specific implementation such as POSIX 1003.1 or 1552ANSI C X3.159-1989 this should be noted here. If the 1553command does not adhere to any standard, its history 1554should be noted in the HISTORY section. 1555.It \&.Sh HISTORY 1556Any command which does not adhere to any specific standards 1557should be outlined historically in this section. 1558.It \&.Sh AUTHORS 1559Credits, if need be, should be placed here. 1560.It \&.Sh DIAGNOSTICS 1561Diagnostics from a command should be placed in this section. 1562.It \&.Sh ERRORS 1563Specific error handling, especially from library functions 1564(man page sections 2 and 3) should go here. The 1565.Ql \&.Er 1566macro is used to specify an errno. 1567.It \&.Sh BUGS 1568Blatant problems with the topic go here... 1569.El 1570.Pp 1571User specified 1572.Ql \&.Sh 1573sections may be added, 1574for example, this section was set with: 1575.Bd -literal -offset 14n 1576\&.Sh PAGE LAYOUT MACROS 1577.Ed 1578.Ss Paragraphs and Line Spacing. 1579.Bl -tag -width 6n 1580.It \&.Pp 1581The \&.Pp paragraph command may 1582be used to specify a line space where necessary. 1583The macro is not necessary after a 1584.Ql \&.Sh 1585or 1586.Ql \&.Ss 1587macro or before 1588a 1589.Ql \&.Bl 1590macro. 1591(The 1592.Ql \&.Bl 1593macro asserts a vertical distance unless the -compact flag is given). 1594.El 1595.\" .Pp 1596.\" .Ds I 1597.\" .Cw (ax+bx+c) \ is\ produced\ by\ \& 1598.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& 1599.\" .Cl Cx \t\t 1600.\" .Li \&.Cx\ ( 1601.\" .Cx 1602.\" .Cl Cx \t\t 1603.\" .Li \&.Va ax 1604.\" .Cx 1605.\" .Cl Cx \t\t 1606.\" .Li \&.Sy \+ 1607.\" .Cx 1608.\" .Cl Cx \&(\& 1609.\" .Va ax 1610.\" .Cx + 1611.\" .Va by 1612.\" .Cx + 1613.\" .Va c ) 1614.\" .Cx \t 1615.\" .Em is produced by 1616.\" .Cx \t 1617.\" .Li \&.Va by 1618.\" .Cx 1619.\" .Cl Cx \t\t 1620.\" .Li \&.Sy \+ 1621.\" .Cx 1622.\" .Cl Cx \t\t 1623.\" .Li \&.Va c ) 1624.\" .Cx 1625.\" .Cl Cx \t\t 1626.\" .Li \&.Cx 1627.\" .Cx 1628.\" .Cw 1629.\" .De 1630.\" .Pp 1631.\" This example shows the same equation in a different format. The spaces 1632.\" around the 1633.\" .Li \&+ 1634.\" signs were forced with 1635.\" .Li \e : 1636.\" .Pp 1637.\" .Ds I 1638.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& 1639.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& 1640.\" .Cl Cx \t\t 1641.\" .Li \&.Cx\ ( 1642.\" .Cx 1643.\" .Cl Cx \t\t 1644.\" .Li \&.Va a 1645.\" .Cx 1646.\" .Cl Cx \t\t 1647.\" .Li \&.Sy x 1648.\" .Cx 1649.\" .Cl Cx \t\t 1650.\" .Li \&.Cx \e\ +\e\ \e& 1651.\" .Cx 1652.\" .Cl Cx \&(\& 1653.\" .Va a 1654.\" .Sy x 1655.\" .Cx \ +\ \& 1656.\" .Va b 1657.\" .Sy y 1658.\" .Cx \ +\ \& 1659.\" .Va c ) 1660.\" .Cx \t 1661.\" .Em is produced by 1662.\" .Cl Cx \t\t 1663.\" .Li \&.Va b 1664.\" .Cx 1665.\" .Cl Cx \t\t 1666.\" .Li \&.Sy y 1667.\" .Cx 1668.\" .Cl Cx \t\t 1669.\" .Li \&.Cx \e\ +\e\ \e& 1670.\" .Cx 1671.\" .Cl Cx \t\t 1672.\" .Li \&.Va c ) 1673.\" .Cx 1674.\" .Cl Cx \t\t 1675.\" .Li \&.Cx 1676.\" .Cx 1677.\" .Cw 1678.\" .De 1679.\" .Pp 1680.\" The incantation below was 1681.\" lifted from the 1682.\" .Xr adb 1 1683.\" manual page: 1684.\" .Pp 1685.\" .Ds I 1686.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by 1687.\" .Cl Cx \t\t 1688.\" .Li \&.Cx Op Sy ?/ 1689.\" .Cx 1690.\" .Cl Cx \t\t 1691.\" .Li \&.Nm m 1692.\" .Cx 1693.\" .Cl Cx Op Sy ?/ 1694.\" .Nm m 1695.\" .Ad \ b1 e1 f1 1696.\" .Op Sy ?/ 1697.\" .Cx \t 1698.\" .Em is produced by 1699.\" .Cx \t 1700.\" .Li \&.Ar \e\ b1 e1 f1 1701.\" .Cx 1702.\" .Cl Cx \t\t 1703.\" .Li \&.Op Sy ?/ 1704.\" .Cx 1705.\" .Cl Cx \t\t 1706.\" .Li \&.Cx 1707.\" .Cx 1708.\" .Cw 1709.\" .De 1710.\" .Pp 1711.Ss Examples and Displays 1712There are five types of displays, a quickie one line indented display 1713.Ql \&.D1 , 1714a quickie one line literal display 1715.Ql \&.Dl , 1716a block literal, block filled and block ragged which use 1717the 1718.Ql \&.Bd 1719begin-display 1720and 1721.Ql \&.Ed 1722end-display macros. 1723.Pp 1724.Bl -tag -width \&.D1 1725.It Li \&.D1 1726(D-one) Display one line of indented text. 1727Arguments are checked to see if they are callable. 1728.Bd -ragged -offset indent 1729.Li \&.D1 \&Fl ldghfstru 1730.Ed 1731.Pp 1732produces: 1733.Pp 1734.Dl Fl ldghfstru 1735.It Li \&.Dl 1736(D-ell) 1737Display one line of indented 1738.Em literal 1739text. The 1740.Ql \&.Dl 1741example macro has been used throughout this 1742file. It allows 1743the indent (display) of one line of text. 1744Its default font is set to 1745constant width (literal) however 1746.Ql \&.Dl 1747does check arguments to see it they are callable. 1748Macros called from 1749.Li \&.Dl 1750should be content macros; calling macros from 1751the page layout section 1752is redundant and may cause unpredictable errors. 1753.Bd -ragged -offset indent 1754.Li \&.Dl % ls -ldg /usr/local/bin 1755.Ed 1756.Pp 1757produces: 1758.Pp 1759.Dl % ls -ldg /usr/local/bin 1760.It Li \&.Bd 1761Begin-display. The 1762.Ql \&.Bd 1763display must be ended with the 1764.Ql \&.Ed 1765macro. Displays may be nested within displays and 1766lists. 1767.Ql \&.Bd 1768has the following syntax: 1769.Pp 1770.Dl ".Bd display-type [offset offset_value]" 1771.Pp 1772The display-type must be one of the following four types and 1773may have an offset specifier for indentation: 1774.Ql \&.Bd . 1775.Pp 1776.Bl -tag -width "literalxx" -compact 1777.It Fl ragged 1778Display a block of text as typed, 1779right (and left) margin edges are left ragged. 1780.It Fl filled 1781Display a filled (formatted) block. 1782The block of text is formatted (the edges are filled \- 1783not left ragged). 1784.It Fl literal 1785Display a literal block, useful for source code or 1786simple tabbed or spaced text. 1787.It Fl file Ar file_name 1788The file name following the 1789.Fl file 1790flag is read and displayed. Literal mode is 1791asserted and tabs are set at 8 constant width character 1792intervals, however any 1793.Xr troff/ Ns Nm \-mdoc 1794commands in file will be processed. 1795.It Fl offset Ar string 1796If 1797.Fl offset 1798is specified with one of the following strings, the string 1799is interpreted to indicate the level of indentation for the 1800forthcoming block of text: 1801.Pp 1802.Bl -tag -width "indent" -compact 1803.It Ar left 1804Align block on the current left margin, 1805this is the default mode of 1806.Ql \&.Bd . 1807.It Ar center 1808Supposedly center the block. At this time 1809unfortunately, the block merely gets 1810left aligned about an imaginary center margin. 1811.It Ar indent 1812Indents by one default indent value or tab. The default 1813indent value is also used for the 1814.Ql \&.D1 1815display so one can be garanteed of the two types of displays 1816lining up. This indent is nornally set to 6n or about two 1817thirds of an inch (six constant width characters). 1818.It Ar indent-two 1819Indents two times the default indent value. 1820.It Ar right 1821This 1822.Em left 1823aligns the block about two inches from 1824the right side of the page. This macro also needs 1825work and perhaps may never be right in 1826.Xr troff . 1827.El 1828.El 1829.It ".Ed" 1830End-display. 1831.El 1832.Ss Tagged Lists and Columns 1833There are several types of lists which may be initiated with the 1834.Ql ".Bl" 1835begin-list macro. Items within the list 1836are specified with the 1837.Ql ".It" 1838item macro and 1839each list must end with the 1840.Ql ".El" 1841macro. Lists may be nested within themselves and within displays. 1842Columns may be used inside of lists, but lists are unproven 1843inside of columns. 1844.Pp 1845In addition, several list attributes may be specified such as 1846the width of a tag, the list offset, and compactness specified 1847(blank lines between items allowed or disallowed). 1848The following list types are accepted by 1849.Ql ".Bl": 1850.Pp 1851.Bl -ohang -compact 1852.It Fl bullet 1853.It Fl item 1854.It Fl enum 1855These three are the simplest types of lists. Once the 1856.Ql ".Bl" 1857macro has been given, items in the list are merely 1858indicated by a line consisting solely of the 1859.Ql ".It" 1860macro. For example, the source text for a simple enumerated list 1861would look like: 1862.Bd -literal -offset indent-two 1863\&.Bl -enum -compact 1864\&.It 1865\&Item one goes here. 1866\&.It 1867\&And item two here. 1868\&.It 1869\&Lastly item three goes here. 1870\&.El 1871.Ed 1872.Pp 1873The results: 1874.Pp 1875.Bl -enum -offset indent-two -compact 1876.It 1877Item one goes here. 1878.It 1879And item two here. 1880.It 1881Lastly item three goes here. 1882.El 1883.Pp 1884A simple bullet list construction: 1885.Bd -literal -offset indent-two 1886\&.Bl -bullet -compact 1887\&.It 1888\&Bullet one goes here. 1889\&.It 1890\&Bullet two here. 1891\&.El 1892.Ed 1893.Pp 1894Produces: 1895.Bl -bullet -offset indent-two -compact 1896.It 1897Bullet one goes here. 1898.It 1899Bullet two here. 1900.El 1901.Pp 1902.It Fl tag 1903.It Fl diag 1904.It Fl hang 1905.It Fl ohang 1906.It Fl inset 1907These list-types collect arguments specified with the 1908.Ql \&.It 1909macro and create a label which may be 1910.Em inset 1911into the forth coming text, 1912.Em hanged 1913(exdented) from the forth coming text, 1914.Em overhanged 1915set above the forth coming paragraph or 1916.Em tagged 1917(exdented and offset). This 1918list was constructed with the 1919.Ql Fl ohang 1920list-type. The 1921.Ql \&.It 1922macro may call any callable macros for the inset, hang 1923and tag list-types, but will not call macros for the 1924diag type. 1925Here is an example of inset labels: 1926.Bl -inset -offset indent 1927.It Em Tag 1928The tagged list (also called a tagged paragraph) is the 1929most common type of list used in the Berkeley manuals. 1930.It Em Diag 1931Diag lists create section four diagnostic lists 1932and are similar to inset lists except callable 1933macros are ignored. 1934.It Em Hang 1935Hanged labels are a matter of taste. 1936.It Em Ohang 1937Over hanging labels are nice when space is constrained. 1938.It Em Inset 1939Inset labels are useful for controlling blocks of 1940paragraphs and are valuable for converting 1941.Nm \-mdoc 1942manuals to other formats. 1943.El 1944.Pp 1945Here is the source text which produced the above example: 1946.Bd -literal -offset indent 1947\&.Bl -inset -offset indent 1948\&.It Em Tag 1949\&The tagged list (also called a tagged paragraph) is the 1950\&most common type of list used in the Berkeley manuals. 1951\&.It Em Diag 1952\&Diag lists create section four diagnostic lists 1953\&and are similar to inset lists except callable 1954\¯os are ignored. 1955\&.It Em Hang 1956\&Hanged labels are a matter of taste. 1957\&.It Em Ohang 1958\&Over hanging labels are nice when space is constrained. 1959\&.It Em Inset 1960\&Inset labels are useful for controlling blocks of 1961\¶graphs and are valuable for converting 1962\&.Nm \-mdoc 1963\&manuals to other formats. 1964\&.El 1965.Ed 1966.Pp 1967Here is a hanged list with just one item: 1968.Bl -hang -offset indent 1969.It Em Hanged 1970labels appear similar to tagged lists when the 1971label is smaller than the label width. 1972.It Em Longer hanged list labels 1973blend in to the paragraph unlike 1974tagged paragraph labels. 1975.El 1976.Pp 1977And the unfomatted text which created it: 1978.Bd -literal -offset indent 1979\&.Bl -hang -offset indent 1980\&.It Em Hanged 1981\&labels appear similar to tagged lists when the 1982\&label is smaller than the label width. 1983\&.It Em Longer hanged list labels 1984\&blend in to the paragraph unlike 1985\&tagged paragraph labels. 1986\&.El 1987.Ed 1988.Pp 1989The tagged list which follows uses an optional width specifier to controll 1990the width of the tag. 1991.Pp 1992.Bl -tag -width "PAGEIN 10" -compact -offset indent 1993.It SL 10 1994sleep time of the process (seconds blocked) 1995.It PAGEIN 10 1996number of disk i/o's resulting from references 1997by the process to pages not loaded in core. 1998.It UID 10 1999numerical user-id of process owner 2000.It PPID 10 2001numerical id of parent of process process priority 2002(non-positive when in non-interruptible wait) 2003.El 2004.Pp 2005The raw text: 2006.Bd -literal -offset indent 2007\&.Bl -tag -width "PAGEIN 10" -compact -offset indent 2008\&.It SL 10 2009\&sleep time of the process (seconds blocked) 2010\&.It PAGEIN 10 2011\&number of disk i/o's resulting from references 2012\&by the process to pages not loaded in core. 2013\&.It UID 10 2014\&numerical user-id of process owner 2015\&.It PPID 10 2016\&numerical id of parent of process process priority 2017\&(non-positive when in non-interruptible wait) 2018\&.El 2019.Ed 2020.Pp 2021Acceptable width specifiers: 2022.Bl -tag -width Ar -offset indent 2023.It Fl width Ar "\&Fl" 2024sets the width to the default width for a flag. All callable 2025macros have a default width value. The 2026.Ql \&.Fl , 2027value is presently 2028set to ten constant width characters or about five sixth of 2029an inch. 2030.It Fl width Ar "24n" 2031sets the width to 24 constant width characters or about two 2032inches. The 2033.Ql n 2034is absolutely necessary for the scaling to work correctly. 2035.It Fl width Ar "ENAMETOOLONG" 2036sets width to the constant width length of the 2037string given. 2038.It Fl width Ar "\\*qint mkfifo\\*q" 2039again, the width is set to the constant width of the string 2040given. 2041.El 2042.Pp 2043If a width is not specified for the tag list type, the first 2044time 2045.Ql \&.It 2046is invoked, an attempt is made to determine an appropriate 2047width. If the first argument to 2048.Ql ".It" 2049is a callable macro, the default width for that macro will be used 2050as if the macro name had been supplied as the width. However, 2051if another item in the list is given with a different callable 2052macro name, a new and nested list is assumed. Here is an involved 2053example of a self nesting list: 2054.Sh DIAGNOSTICS 2055The debugging facilities for 2056.Nm \-mdoc 2057are limited, but can help detect subtle errors such 2058as the collision of an argument name with an internal 2059register or macro name. (A what?) 2060A register is an arithmetic storage class for 2061.Xr troff 2062with a one or two character name. 2063All registers internal to 2064.Nm \-mdoc 2065for 2066.Xr troff 2067and 2068.Xr ditroff 2069are two characters and 2070of the form <uppercase><lowercase> such as 2071.Ql \&Ar , 2072<lowercase><uppercase> as 2073.Ql \&aR 2074or 2075<upper or lower letter><digit> as 2076.Ql \&C\&1 . 2077And adding to the muddle, 2078.Xr troff 2079has its own internal registers all of which are either 2080two lowercase characters or a dot plus a letter or meta-character 2081character. 2082In one of the introduction examples, it was shown how to 2083prevent the interpretation of a macro name with the escape sequence 2084.Ql \e& . 2085This is sufficient for the internal register names also. 2086.Pp 2087.\" Every callable macro name has a corresponding register 2088.\" of the same name (<Uppercase><lowercase>). 2089.\" There are also specific registers which have 2090.\" been used for stacks and arrays and are listed in the 2091.\" .Sx Appendix . 2092.\" .Bd -ragged -offset 4n 2093.\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'') 2094.\" [a-z][A-Z] registers corresponding to macro names (example ``aR'') 2095.\" C[0-9] argument types (example C1) 2096.\" O[0-9] offset stack (displays) 2097.\" h[0-9] horizontal spacing stack (lists) 2098.\" o[0-9] offset (stack) (lists) 2099.\" t[0-9] tag stack (lists) 2100.\" v[0-9] vertical spacing stack (lists) 2101.\" w[0-9] width tag/label stack 2102.\" .Ed 2103.\" .Pp 2104If a non-escaped register name is given in the argument list of a request 2105unpredictable behaviour will occur. In general, anytime huge portions 2106of text do not appear where expected in the output, or small strings 2107such as list tags disappear, chances are there is a misunderstanding 2108about an argument type in the argument list. 2109Your mother never intended for you to remember this evil stuff - so here 2110is a way to find out whether or not your arguments are valid: The 2111.Ql \&.Db 2112(debug) 2113macro displays the interpretation of the argument list for most 2114macros. Macros such as the 2115.Ql \&.Pp 2116(paragraph) 2117macro do not contain debugging information. All of the callable macros do, 2118and it is strongly advised whenever in doubt, 2119turn on the 2120.Ql \&.Db 2121macro. 2122.Pp 2123.Dl Usage: \&.Db [on | off] 2124.Pp 2125An example of a portion of text with 2126the debug macro placed above and below an 2127artificially created problem (a flag argument 2128.Ql \&aC 2129which should be 2130.Ql \e&aC 2131in order to work): 2132.Bd -literal -offset indent 2133\&.Db on 2134\&.Op Fl aC Ar file ) 2135\&.Db off 2136.Ed 2137.Pp 2138The resulting output: 2139.Bd -literal -offset indent 2140DEBUGGING ON 2141DEBUG(argv) MACRO: `.Op' Line #: 2 2142 Argc: 1 Argv: `Fl' Length: 2 2143 Space: `' Class: Executable 2144 Argc: 2 Argv: `aC' Length: 2 2145 Space: `' Class: Executable 2146 Argc: 3 Argv: `Ar' Length: 2 2147 Space: `' Class: Executable 2148 Argc: 4 Argv: `file' Length: 4 2149 Space: ` ' Class: String 2150 Argc: 5 Argv: `)' Length: 1 2151 Space: ` ' Class: Closing Punctuation or suffix 2152 MACRO REQUEST: .Op Fl aC Ar file ) 2153DEBUGGING OFF 2154.Ed 2155.Pp 2156The first line of information tells the name of the calling 2157macro, here 2158.Ql \&.Op , 2159and the line number it appears on. If one or more files are involved 2160(especially if text from another file is included) the line number 2161may be bogus. If there is only one file, it should be accurate. 2162The second line gives the argument count, the argument 2163.Pq Ql \&Fl 2164and its length. If the length of an argument is two characters, the 2165argument is tested to see if it is executable (unfortunately, any 2166register which contains a non-zero value appears executable). 2167The third line gives the space allotted for a class, and the 2168class type. The problem here is the argument aC should not be 2169executable. The four types of classes are string, executable, closing 2170punctuation and opening punctuation. The last line shows the entire 2171argument list as it was read. In this next example, the offending 2172.Ql \&aC 2173is escaped: 2174.Bd -literal -offset indent 2175\&.Db on 2176\&.Em An escaped \e&aC 2177\&.Db off 2178.Ed 2179.Bd -literal -offset indent 2180DEBUGGING ON 2181DEBUG(fargv) MACRO: `.Em' Line #: 2 2182 Argc: 1 Argv: `An' Length: 2 2183 Space: ` ' Class: String 2184 Argc: 2 Argv: `escaped' Length: 7 2185 Space: ` ' Class: String 2186 Argc: 3 Argv: `aC' Length: 2 2187 Space: ` ' Class: String 2188 MACRO REQUEST: .Em An escaped &aC 2189DEBUGGING OFF 2190.Ed 2191.Pp 2192The argument 2193.Ql \e&aC 2194shows up with the same length of 2 as the 2195.Ql \e& 2196sequence produces a zero width, but a register 2197named 2198.Ql \e&aC 2199was not found and the type classified as string. 2200.Pp 2201Other diagnostics consist of usage statements and are self explanatory. 2202.Sh FILES 2203.Bl -tag -width /usr/share/man0/template.doc -compact 2204.It Pa /usr/share/tmac/tmac.doc 2205manual macro package 2206.It Pa /usr/share/man0/template.doc 2207template for writing a man page 2208.El 2209.Sh HISTORY 22104.4 BSD 2211.Sh SEE ALSO 2212.Xr mdoc 7 , 2213.Xr man 1 , 2214.Xr troff 1 2215.Sh BUGS 2216Undesirable hyphenation on the dash of a flag 2217argument is not yet resolved, and causes 2218occasional mishaps in the DESCRIPTION section. 2219(line break on the hyphen). 2220.Pp 2221Predefined strings are not declared in documentation. 2222.Pp 2223Section 3f has not been added to the header routines. 2224.Pp 2225.Ql \&.Nm 2226font should be changed in NAME section. 2227.Pp 2228.Ql \&.Fn 2229needs to have a check to prevent splitting up 2230if the line length is too short. Right now it 2231separates the last parenthesis, and sometimes 2232looks ridiculous if a line is in fill mode. 2233.Pp 2234The method used to prevent header and footer page 2235breaks (other than the initial header and footer) when using 2236nroff seems to be putting out a partially filled line 2237at the bottom of the page leaving an unsightly blank space. 2238.Pp 2239The list and display macros to not do any keeps 2240and certainly should be able to. 2241