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