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