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