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