1.\" Copyright (c) 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)mdoc.samples.7 5.3 (Berkeley) 07/12/90 7.\" 8.\" This sampler invokes every macro in the package several 9.\" times and is garanteed to give a worst case performance 10.\" for an already slow package. 11.Dd 12.Os BSD 4.4 13.Dt MDOC.SAMPLES 7 14.Sh NAME 15.Nm mdoc.sample 16.Nd detailed samples utilizing 17the 18.Nm -mdoc 19macro package 20.Sh SYNOPSIS 21.Nm man mdoc.sample 22.Sh DESCRIPTION 23A fairly complete sampler of how the 24.Nm \-mdoc 25macro package is used. 26.Sh TROFF IDIOSYNCRASIES 27Although this is a content based formatting package, and 28theoretically one should not have to learn 29.Xr troff 1 30to use it, there are a few 31limitations which are unavoidable and best gotten out 32of the way. And, too, be forewarned, this package is slow. 33Its purpose is to allow translation of man pages from 34.Xr troff 1 35to 36.Xr TeX Coming\ Soon 37and vice versa. 38.Ss Macro Usage 39As in 40.Xr troff 1 , 41a macro (request) is called by placing a 42.Li \&\. 43(dot character) 44at the beginning of 45a line followed by the two character name for the macro. 46Arguments may follow the request separated by spaces. 47It is the dot character at the beginning of the line which causes 48.Xr troff 1 49to interpret the next two characters as a request. 50To place a 51.Li \&\. 52(dot character) 53at the beginning of a line in some context other than 54a macro request, precede the 55.Li \&\. 56(dot) with a 57.Li \e&. 58In this macro package, some macros may be given the 59name of another macro as an argument. In this case 60the argument, although the name of a macro, 61is not preceded by a 62.Li \&\. 63(dot), 64and will be executed 65with the remaining arguments. 66It is in this manner that some requests are nested, such 67as the 68.Li \&.Op 69request may 70.Em call 71the flag request 72.Li \&.Fl . 73.Dp Op Fl ls 74is produced by 75.Li \&.Op Fl ls 76.Dp 77The only requests which check to see if the first argument 78is executable are: 79.Ds I 80.Cw \&.Cx\ Complex\ Expressions 81.Cl \&.Cl\ Column Line Entry \&.Dp Display Examples (tagged paragraph) 82.Cl \&.Cx\ Complex\ Expressions \&.Op\ Option Request 83.Cl \&.Dl\ Display (one) Line \&.Sq Single Quotes 84.Cl \&.Dq\ Double Quotes \&.Tp Tagged Paragraphs 85.Cw 86.De 87.Pp 88The eligible first arguments are: 89.Ds I 90.Cw \&.Cx\ Complex\ Expressions 91.Cl \&.Ad Addresses \&.Fn Functions 92.Cl \&.Ar Arguments \&.Ic Interactive Commands 93.Cl \&.Cl Column Entries \&.Li Literals 94.Cl \&.Cm Command Modifiers \&.Nm Names, subjects 95.Cl \&.Cw Column Widths \&.Op Options 96.Cl \&.Cx Complex Expressions \&.Pa Pathnames 97.Cl \&.Em Emphasis \&.Sy Symbolic 98.Cl \&.Er Errno's \&.Tp Tagged Paragraphs 99.Cl \&.Ev Environment \&.Va Variables 100.Cl \&.Fl Flags \&.Xr Cross References 101.Cw 102.De 103.Pp 104Requests which cannot be called, or call any other macro: 105.Ds I 106.Cw \&.Cx\ Complex\ Expressions 107.Cl \&.Di Display Indent \&.Dw Display Tag Width 108.Cl \&.De Display End \&.Pp Paragraph Start 109.Cl \&.Df Display Filled \&.Tw Tagged Paragraph Tag Width 110.Cl \&.Df Display unfilled 111.Cw 112.De 113.Pp 114The macro 115.Li .Op 116is unusual that it can call more than one request on the same 117line. 118.Ss Passing Space Characters in an Argument 119To pass an argument 120to a macro request which contains spaces, the space must be preceded 121by a 122.Li \e 123to escape special interpretation: 124.Dw int\ *fetch() 125.Dp Fn int\ *fetch 126is created by 127.Li \&.Fn int\e *fetch 128.Dp 129For critical spaces at the end of a line, as might be needed 130with the request 131.Li \&.Cx , 132following the space with 133.Li \e& 134is a good guarantee the space will not be stripped (e.g. 135.Li \e \e&) . 136A blank space at the end of a line is otherwise an open invitation 137to party for 138.Xr troff 1 . 139.Ss Escaping Special Characters 140Special characters 141like the newline character 142.Li \en , 143are handled by replacing the 144.Li \e 145with 146.Li \ee 147(e.g. 148.Li \een ) 149to preserve 150the backslash. 151.Sh HEADER REQUESTS 152Three header macros designate the document title or manual page title, 153the operating system, 154and the date of authorship (if not derived from 155.Xr sccs 1 156or 157.Xr rcs 1 ) . 158These macros are one called once at the very beginning of the document 159and are used to construct the headers and footers only. 160.Tp Li \&.Dt DOCUMENT_TITLE section# [volume] 161The document title is the 162subject of the man page and must be in CAPITALS due to troff 163limitations. 164The section number may be 1,...,8, 165and if it is specified, 166the volume title may be omitted. 167A volume title may be arbitrary or one of the following: 168.\" .Cl 169.\" USD UNIX User's Supplementary Documents 170.\" .Cl 171.\" PS1 UNIX Programmers's Supplementary Documents 172.Cw SMM 173.Cl AMD UNIX Ancestral Manual Documents 174.Cl SMM UNIX System Manager's Manual 175.Cl URM UNIX Reference Manual 176.Cl PRM UNIX Programmers's Manual 177.Cw 178.\" .Cl 179.\" MMI UNIX Manual Master Index 180.\" .Cl 181.\" CON UNIX Contributed Software Manual 182.\" .Cl 183.\" LOC UNIX Local Manual 184.Tp Li \&.Os operating_system release# 185The name of the operating system 186should be the common acronym, e.g. BSD 187or ATT. The release should be the standard release 188nomenclature for the system specified, e.g. 4.3, 4.3+tahoe, V.3, 189V.4. Unrecognized arguments are displayed as given in the page footer. 190For instance, for the footer on this page, the 4.4 Berkeley Distribution 191was produced by: 192.Pp 193.Dl Li \&.Os BSD 4.4 194.Tp Li \&.Dd month day, year 195The date should be written formally: 196.Pp 197.Dl January 25, 1989 198.\" is not a standard SCCS id-key. ?? 199.Tp 200.Sh TEXT MACROS 201The following macro requests have similar 202syntax; the exceptions being the behaviour of the 203request if called without an argument, and the 204behaviour of the requests 205.Li \&.Fn , 206.Li \&.Pa , 207and 208.Li \&.Xr , 209which expect a specific format. 210The other requests can handle up to 9 arguments 211and will format punctuation properly as 212long as the punctuation is placed in the last 213arguments. Punctuation placed in the middle 214of a string of text arguments will result 215in a out of place space character. 216.Pp 217Any argument which may be tested for punctuation 218and contains a member of the mathematical, logical or 219quotation 220set 221{+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"} 222should have 223the character escaped. 224.Pp 225.Ss Address Request 226The address request constructs and address 227of the form addr1[,addr2[,addr3]]. 228.Pp 229.Dl \&.Ad Usage: .Ad address ... \*(Pu 230.Dw \&.Ad\ f1\ ,\ f2\ ,\ f3\ : 231.Dp Li \&.Ad addr1 232.Ad addr1 233.Dp Li \&.Ad addr1\ . 234.Ad addr1 . 235.Dp Li \&.Ad addr1\ , file2 236.Ad addr1 , file2 237.Dp Li \&.Ad f1\ , f2\ , f3\ : 238.Ad f1 , f2 , f3 : 239.Dp Li \&.Ad addr\ )\ )\ , 240.Ad addr ) ) , 241.Dp 242It is an error to call 243.Li \&.Ad 244without arguments. 245The request may be called by 246.Li \&.Cl , 247.Li \&.Cx , 248.Li \&.Dl , 249.Li \&.Dp , 250.Li \&.Op 251or 252.Li \&.Tp . 253.Ss Argument Request 254The 255.Li \&.Ar 256argument request may be used whenever 257a command line argument is referenced. 258.Pp 259.Dl Usage: .Ar argument ... \*(Pu 260.Dw Tx 261.Dp Li \&.Ar 262.Ar 263.Dp Li \&.Ar file1 264.Ar file1 265.Dp Li \&.Ar file1\ . 266.Ar file1 . 267.Dp Li \&.Ar file1 file2 268.Ar file1 file2 269.Dp Li \&.Ar f1 f2 f3\ : 270.Ar f1 f2 f3 : 271.Dp Li \&.Ar file\ )\ )\ , 272.Ar file ) ) , 273.Dp 274.Pp 275If 276.Li \&.Ar 277is called with no arguments 278.Ar 279is assumed. The 280.Li \&.Ar 281request cannot call other macros, but may 282be called by 283.Li \&.Cl , 284.Li \&.Cx , 285.Li \&.Dl , 286.Li \&.Dp , 287.Li \&.Op 288or 289.Li \&.Tp . 290See the 291.Li \&.Op 292request for an example of using 293.Li \&.Ar 294in combination with the 295.Li \&.Fl 296request. 297.Ss Double Quote Request 298The 299.Li \&.Dq 300double quote request may be used to surround 301a string with double quotes. Punctuation is 302placed after the edn quote. To place punctuation 303in inside the quotes it must be escaped with 304.Li \&\e& . 305.Pp 306.Dl Usage: .Dq string ... \*(Pu 307.Dw \&.Dq\ fools\ and\ follies 308.Dp Li \&.Dq 309.Dq 310.Dp Li \&.Dq string 311.Dq string 312.Dp Li \&.Dq string\ . 313.Dq string . 314.Dp Li \&.Dq fools and follies 315.Dq fools and follies 316.Dp Li \&.Dq Ar pattern\ )\ )\ , 317.Dq Ar pattern ) ) , 318.Dp 319.Pp 320If 321.Li \&.Dq 322is called with no arguments 323.Dq 324is assumed. The 325.Li \&.Dq 326request may call or be called by 327.Li \&.Cl , 328.Li \&.Cx , 329.Li \&.Dl , 330.Li \&.Dp , 331.Li \&.Op 332.Li \&.Sq , 333or 334.Li \&.Tp . 335.Pp 336The 337.Li \&.Sq 338provides single quotes 339in the same manner as 340.Li \&.Dq . 341Neither request can nest with in itself, but 342.Li \&.Dq 343and 344.Li \&.Sq 345can be nested with in each other. 346.Ss Emphasis Request 347A portion of text may be stressed or emphasized with the .Em 348request. The font used is commonly italic. 349.Pp 350.Dl Usage: .Em argument ... \*(Pu 351.Dw \&.Em\ vide\ infra\ )\ )\ , 352.Dp Li \&.Em does not 353.Em does not 354.Dp Li \&.Em exceed 1024\ . 355.Em exceed 1024 . 356.Dp Li \&.Em vide infra\ )\ )\ , 357.Em vide infra ) ) , 358.Dp 359.Pp 360It is an error to call 361.Li \&.Em 362without arguments. 363The request cannot call other macros, but 364may be invoked by 365.Li \&.Cl , 366.Li \&.Cx , 367.Li \&.Dl , 368.Li \&.Dp , 369.Li \&.Op 370or 371.Li \&.Tp . 372.Ss Errno's (Section's two and three only) 373The 374.Li \&.Er 375errno request specifies the error return value 376for section two and three library routines. The second example 377below shows 378.Li \&.Er 379used with the 380.Li \&.Op 381request, as it would be used in the error 382section of a section two manual page. 383.Pp 384.Dl Usage: .Er ERRNOTYPE ... \*(Pu 385.Dw Tx 386.Dp Li \&.Er ENOENT 387.Er ENOENT 388.Dp Li \&.Op \&Er ENOTDIR 389.Op Er ENOTDIR 390.Dp 391.Pp 392It is an error to call 393.Li \&.Er 394without arguments. 395The request cannot call other macros, but 396may be invoked by 397.Li \&.Cl , 398.Li \&.Cx , 399.Li \&.Dl , 400.Li \&.Dp , 401.Li \&.Op 402or 403.Li \&.Tp . 404.Ss Environment Variables 405The 406.Li \&.Ev 407request specifies a environment variable. 408.Pp 409.Dl Usage: .Ev argument ... \*(Pu 410.Dw \&.Ev\ PRINTER\ )\ )\ , 411.Dp Li \&.Ev DISPLAY 412.Ev DISPLAY 413.Dp Li \&.Ev PATH\ . 414.Ev PATH . 415.Dp Li \&.Ev PRINTER\ )\ )\ , 416.Ev PRINTER ) ) , 417.Dp 418.Pp 419It is an error to call 420.Li \&.Ev 421without arguments. 422The request cannot call other macros, but 423may be invoked by 424.Li \&.Cl , 425.Li \&.Cx , 426.Li \&.Dl , 427.Li \&.Dp , 428.Li \&.Op 429or 430.Li \&.Tp . 431.Ss Flags 432The 433.Li \&.Fl 434request handles command line flags. It prepends 435a dash, 436.Li \- , 437to the flag. For interactive command flags, which 438are not prepended with a dash, the 439.Li \&.Cm 440request is identical, but with out the dash. 441The 442.Li \&.Cm 443stands for command modifier. 444.Pp 445.Dl Usage: .Fl argument ... \*(Pu 446.Dw Tx 447.Dp Li \&.Fl 448.Fl 449.Dp Li \&.Fl cfv 450.Fl cfv 451.Dp Li \&.Fl cfv\ . 452.Fl cfv . 453.Dp Li \&.Fl s v t 454.Fl s v t 455.Dp Li \&.Fl -\ , 456.Fl - , 457.Dp Li \&.Fl xyz\ )\ , 458.Fl xyz ) , 459.Dp 460.Pp 461The 462.Li \&.Fl 463request without any arguments results 464in a dash sign representing stdin/stdout. 465Note that giving 466.Li \&.Fl 467a single dash, will result in two dashes. 468The request cannot call other macros, but 469may be invoked by 470.Li \&.Cl , 471.Li \&.Cx , 472.Li \&.Dl , 473.Li \&.Dp , 474.Li \&.Op 475or 476.Li \&.Tp . 477.Pp 478.Ss Functions (library routines) 479The .Fn request is modeled on ANSI C conventions. It 480may fail on old style parameter lists. 481.Pp 482Usage: .Fn [type\e\ ] function [[type\e\ ] params ... \*(Pu 483.Dw \&.Fn\ void\e\ push\ int\e\ p\ int\e\ *ptr, 484.Di L 485.Dp Li \&.Fn getchar 486.Fn getchar 487.Dp Li \&.Fn strlen\ )\ , 488.Fn strlen ) , 489.Dp Li \&.Fn strcpy char\e\ *dst char\e\ *src 490.Fn strcpy char\ *dst char\ *src 491.Dp Li \&.Fn int\e\ align int\e\ word 492.Fn int\ align int\ word 493.Dp Li \&.Fn void\e\ push int\e\ p int\e\ *ptr\ , 494.Fn void\ push int\ p int\ *ptr , 495.Dp 496.Pp 497It is an error to call 498.Li \&.Fn 499without any arguments. 500At the moment, 501.Li \&.Fn 502does not check its word boundaries 503against troff line lengths. It may split across a 504line ungracefully. This will be fixed in the near future. 505In the examples above, arguments with more than one word 506escape the blank spaces with a 507.Li \e . 508The 509.Li \&.Fn 510request cannot execute any macro 511names given as the first argument. 512It may be called by the 513.Li \&.Cl , 514.Li \&.Cx , 515.Li \&.Dl , 516.Li \&.Dp , 517.Li \&.Op 518or 519.Li \&.Tp . 520.Ss Literals 521The 522.Li \&.Li 523literal request may be used for special characters, 524variable constants, anything which should be displayed as it 525would be typed. 526.Pp 527.Dl Usage: .Li argument ... \*(Pu 528.Dw Tx 529.Dp Li \&.Li \een 530.Li \en 531.Dp Li \&.Li M1 M2 M3\ ; 532.Li M1 M2 M3 ; 533.Dp Li \&.Li cntrl-D\ )\ , 534.Li cntrl-D ) , 535.Dp Li \&.Li 1024\ ... 536.Li 1024 ... 537.Dp 538.Pp 539It is an error to call 540.Li \&.Li 541without arguments. 542The request cannot call other macros, but 543may be invoked by 544.Li \&.Cl , 545.Li \&.Cx , 546.Li \&.Dl , 547.Li \&.Dp , 548.Li \&.Op 549or 550.Li \&.Tp . 551.Ss Name Request 552The 553.Li \&.Nm 554request is used for the document title or subject name. 555It has the peculiarity of remembering the first 556argument it was called with, which should 557always be the subject name of the page. When called without 558arguments, 559.Li \&.Nm 560regurgitates this initial name for the sole purpose 561of making less work for the author. 562Beyond the NAME section of the man page, a section two 563or three document function name is addressed with the 564.Li \&Fn 565request, while 566.Li \&.Nm 567can continue to be used for any other sections. 568For interactive commands, such as the 569.Li while 570command keyword in 571.Xr csh 1 , 572the 573.Li \&.Ic 574request should be used. 575While the 576.Li \&.Ic 577is nearly identical 578to 579.Li \&.Nm , 580it can not recall the first argument it was invoked with. 581.Pp 582.Dl Usage: .Nm argument ... \*(Pu 583.Dw Tx 584.Dp Li \&.Nm mdoc.sample 585.Nm mdoc.sample 586.Dp Li \&.Nm \-mdoc 587.Nm \-mdoc . 588.Dp Li \&.Nm foo\ )\ )\ , 589.Nm foo ) ) , 590.Dp Li \&.Nm 591.Nm 592.Dp 593.Pp 594The 595.Li \&.Nm 596request cannot call other macros, but 597may be called by 598.Li \&.Cl , 599.Li \&.Cx , 600.Li \&.Dl , 601.Li \&.Dp , 602.Li \&.Op 603or 604.Li \&.Tp . 605.Ss Pathnames 606The 607.Li \&.Pa 608request formats path or file names. It has two 609different behaviours. In any section of the man page 610.Em except 611the section FILES, it 612expects at most one path or file name, and any amount 613of punctuation. In the section FILES, 614it is often desirable to have a column of pathnames 615and a column of pathname descriptions. 616.Pp 617.Dl Usage: .Pa pathname \*(Pu 618.Dw \&.Pa\ /tmp/fooXXXXX\ )\ . 619.Dp Li \&.Pa /usr/share 620.Pa /usr/share 621.Dp Li \&.Pa /tmp/fooXXXXX\ )\ . 622.Pa /tmp/fooXXXXX ) . 623.Dp 624.Pp 625From within section FILES, use the 626.Li \&.Dw 627and 628.Li \&.Dp 629requests to format the pathnames 630and their descriptions. 631.Li \&.Pa 632request cannot call other macros, but 633may be called by 634.Li \&.Cl , 635.Li \&.Cx , 636.Li \&.Dl , 637.Li \&.Dp , 638.Li \&.Op 639or 640.Li \&.Tp . 641.Ss Single Quotes 642See the request 643.Li \&.Dq 644above. The single quoting request 645.Li \&.Sq 646works in the same manner as 647.Li \&.Dq. 648.Ss Symbolic 649The symbolic request is really a boldface request. 650The need for this macro has not been established, 651it is included 'just in case'. 652.Pp 653.Dl Usage: .Sy symbol ... \*(Pu 654.Dw \&.Sy\ something\ bold 655.Dp Li \&.Sy something bold 656.Sy something bold 657.Dp 658.Pp 659The 660.Li \&.Sy 661request cannot call other macros, but can be called 662by 663.Li \&.Cl , 664.Li \&.Cx , 665.Li \&.Dl , 666.Li \&.Dp , 667.Li \&.Op 668or 669.Li \&.Tp . 670.Ss Variables 671Generic variable reference: 672.Pp 673.Dl Usage: .Va variable ... \*(Pu 674.Dw \&.Va\ char\ s\ ]\ )\ )\ , 675.Dp Li \&.Va count 676.Va count 677.Dp Li \&.Va settimer , 678.Va settimer , 679.Dp Li \&.Va int\ *prt\ )\ : 680.Va int\ *prt ) : 681.Dp Li \&.Va char\ s\ ]\ )\ )\ , 682.Va char\ s ] ) ) , 683.Dp 684.Pp 685.Ss Cross References 686The 687.Li \&.Xr 688request expects the first argument to be 689a manual page name, and the second argument, if it exists, 690to be either a section page number or punctuation. Any 691remaining arguments are assumed to be punctuation. 692.Pp 693.Dl Usage: .Xr manpage [1,...,8] \*(Pu 694.Dw Tx 695.Dp Li \&.Xr mdoc 696.Xr mdoc 697.Dp Li \&.Xr mdoc\ , 698.Xr mdoc , 699.Dp Li \&.Xr mdoc 7 700.Xr mdoc 7 701.Dp Li \&.Xr mdoc 7\ )\ )\ , 702.Xr mdoc 7 ) ) , 703.Dp 704.Pp 705The 706.Li \&.Xr 707request cannot call other macros, but may be called 708by 709.Li \&.Cl , 710.Li \&.Cx , 711.Li \&.Dl , 712.Li \&.Dp , 713.Li \&.Op 714or 715.Li \&.Tp . 716It is an error to call 717.Li \&.Xr 718without 719any arguments. 720.Pp 721.\" --- 722.Sh PAGE LAYOUT MACROS 723.Ss Section Headers 724Several 725.Li \&.Sh 726section header requests are required in every 727man page. The 728.Li \&.Sh 729request can take up to nine arguments. 730.Tp \&.Sh NAME 731The 732.Li \&.Sh NAME 733request is mandatory. If not specified, 734the headers, footers and page layout defaults 735will not be set and things will be rather unpleasant. 736The NAME section consists of at least three items. 737The first is the 738.Li \&.Nm 739name request naming the subject of the man page. 740The second is the Name Description request, 741.Li \&.Nd , 742which separates the subject 743name from the third item, which is the description. The 744description should be the most terse and lucid possible, 745as the space available is small. 746.Tp \&.Sh SYNOPSIS 747The SYNOPSIS section describes the typical usage of the 748subject of a man page. The requests required 749are either 750.Li \&.Nm 751or 752.Li \&.Fn . 753The function name 754request 755.Li \&.Fn 756is required 757for manual page sections 2 and 3, the command and general 758name request 759.Li \&.Nm 760is required for the remaining sections 1, 4, 5, 6, 7, 8. 761Several other requests may be necessary to produce 762the synopsis line as shown below: 763.Pp 764.Nm cat 765.Op Fl benstuv 766.Op Fl 767.Ar 768.Pp 769The following requests were used: 770.Pp 771.Dl \&.Nm cat 772.Dl \&.Op Fl benstuv 773.Dl \&.Op Fl 774.Dl \&.Ar 775.Pp 776Note, the 777.Li \&.Op 778request has accepted as its first 779argument the name of another macro 780.Em \&Fl . 781Upon discovering the first argument is callable, 782.Li \&.Op 783calls it with the remaining arguments 784and returns the formatted text in option brackets. 785.Tp \&.Sh DESCRIPTION 786In most cases the first text in the DESCRIPTION section 787is a brief paragraph on the command, function or file, 788followed by a lexical list of options and respective 789explanations. To create such a list, the 790.Li \&.Tp 791request is used in conjunction with text macros, such 792as the 793.Li \&.Fl 794macro (see 795the EXAMPLES section below). 796.Tp 797.Pp 798Other user specified 799.Li \&.Sh 800sections may be added, 801for instance, in this manual page 802.Pp 803.Dl Li \&.Sh PAGE LAYOUT MACROS 804.Pp 805was used for this section. 806.Pp 807The following 808.Li \&.Sh 809section headers are part of the 810preferred manual page layout and must be used appropriately 811to maintain consistency. They are listed in the order 812in which they would be used. 813.Tp \&.Sh ENVIRONMENT 814The ENVIRONMENT section should reveal any related 815environment 816variables and clues to their behaviour and/or usage. 817.Tp \&.Sh EXAMPLES 818There are several ways to create examples. See 819the EXAMPLES section below 820for details. 821.Tp \&.Sh FILES 822Files which are used or created by the man page subject 823should be listed via the 824.Li \&.Pa 825request in the FILES section. 826.Tp \&.Sh SEE ALSO 827References to other material on the man page topic and 828cross references to other relevant man pages should 829be placed in the SEE ALSO section. Cross references 830are specified using the 831.Li \&.Xr 832request. At this time 833.Xr refer 1 834style references are not accommodated. 835.Tp \&.Sh STANDARDS 836If the command, library function or file adheres to a 837specific implementation such as POSIX 1003.1 or 838ANSI C X3.159-1989 this should be noted here. If the 839command does not adhere to any standard, its history 840should be noted in the HISTORY section. 841.Tp \&.Sh HISTORY 842Any command which does not adhere to any specific standards 843should be outlined historically in this section. 844.Tp \&.Sh AUTHORS 845Credits, if need be, should be placed here. 846.Tp \&.Sh DIAGNOSTICS 847Diagnostics from a command should be placed in this section. 848.Tp \&.Sh ERRORS 849Specific error handling, especially from library functions 850(man page sections 2 and 3) should go here. The 851.Li \&.Er 852request is used to specify an errno. 853.Tp \&.Sh BUGS 854Blatant problems with the topic go here... 855.Tp 856.Pp 857.Ss Paragraphs and Line Spacing. 858.Tp \&.Pp 859The \&.Pp paragraph command may 860be used to specify a line space where necessary. 861The request is not necessary after a 862.Li \&.Sh 863or 864.Li \&.Ss 865request or before 866a 867.Li \&.Tp 868or 869.Li \&.Dp 870request. 871.Tp 872.Ss Complex Expressions 873A complex expression is one combined of many 874different elements of text. It is usually only necessary 875in particularly nasty man pages, such as 876.Xr adb 1 877or 878.Xr ex 1 , 879where combinations of commands, addresses and symbols 880may be needed. 881When pieces of text are processed, 882.Xr troff 1 883assumes 884that a space character will be desired after each word 885making it difficult to combine expressions where 886different requests are used. 887.Li \&.Cx 888merely glues text together without spaces. Where 889a space is required, it must be specified. 890A few examples: 891.Pp 892This first example shows how to construct a simple 893expression with no spacing in between: 894.Pp 895.Ds I 896.Cw (ax+bx+c) \ is\ produced\ by\ \& 897.\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& 898.Cl Cx \t\t 899.Li \&.Cx\ ( 900.Cx 901.Cl Cx \t\t 902.Li \&.Va ax 903.Cx 904.Cl Cx \t\t 905.Li \&.Sy \+ 906.Cx 907.Cl Cx \&(\& 908.Va ax 909.Cx + 910.Va by 911.Cx + 912.Va c ) 913.Cx \t 914.Em is produced by 915.Cx \t 916.Li \&.Va by 917.Cx 918.Cl Cx \t\t 919.Li \&.Sy \+ 920.Cx 921.Cl Cx \t\t 922.Li \&.Va c ) 923.Cx 924.Cl Cx \t\t 925.Li \&.Cx 926.Cx 927.Cw 928.De 929.Pp 930This example shows the same equation in a different format. The spaces 931around the 932.Li \&+ 933signs were forced with 934.Li \e : 935.Pp 936.Ds I 937.Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \& 938.\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\& 939.Cl Cx \t\t 940.Li \&.Cx\ ( 941.Cx 942.Cl Cx \t\t 943.Li \&.Va a 944.Cx 945.Cl Cx \t\t 946.Li \&.Sy x 947.Cx 948.Cl Cx \t\t 949.Li \&.Cx \e\ +\e\ \e& 950.Cx 951.Cl Cx \&(\& 952.Va a 953.Sy x 954.Cx \ +\ \& 955.Va b 956.Sy y 957.Cx \ +\ \& 958.Va c ) 959.Cx \t 960.Em is produced by 961.Cl Cx \t\t 962.Li \&.Va b 963.Cx 964.Cl Cx \t\t 965.Li \&.Sy y 966.Cx 967.Cl Cx \t\t 968.Li \&.Cx \e\ +\e\ \e& 969.Cx 970.Cl Cx \t\t 971.Li \&.Va c ) 972.Cx 973.Cl Cx \t\t 974.Li \&.Cx 975.Cx 976.Cw 977.De 978.Pp 979The incantation below was 980lifted from the 981.Xr adb 1 982manual page: 983.Pp 984.Ds I 985.Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by 986.Cl Cx \t\t 987.Li \&.Cx Op Sy ?/ 988.Cx 989.Cl Cx \t\t 990.Li \&.Nm m 991.Cx 992.Cl Cx Op Sy ?/ 993.Nm m 994.Ad \ b1 e1 f1 995.Op Sy ?/ 996.Cx \t 997.Em is produced by 998.Cx \t 999.Li \&.Ar \e\ b1 e1 f1 1000.Cx 1001.Cl Cx \t\t 1002.Li \&.Op Sy ?/ 1003.Cx 1004.Cl Cx \t\t 1005.Li \&.Cx 1006.Cx 1007.Cw 1008.De 1009.Pp 1010.Ss Examples and Displays 1011There are three types of displays, an indented one line display 1012.Li \&.Dl , 1013a non\-filled block display 1014.Li Ds 1015and a filled block display. 1016.Pp 1017.Tw \&.Dl 1018.Tp Li \&.Dl 1019Display one line of indented text. 1020The 1021.Li \&.Dl 1022example request has been used throughout this 1023file. It's 1024basic use is to indent (display) one line of text for quick 1025one line examples. Its default font is set to 1026constant width, however, 1027.Li \&.Dl 1028checks the first argument to see if it is callable. It cannot process 1029more than nine arguments. 1030.Pp 1031.Ds I 1032.Li \&.Dl % ls -ldg /usr/local/bin 1033.Pp 1034produces: 1035.Dl % ls -ldg /usr/local/bin 1036.Pp 1037.Li \&.Dl Fl ldghfstru 1038.Pp 1039produces: 1040.Dl Fl ldghfstru 1041.De 1042.Pp 1043Calling either the request 1044.Li \&.Tp 1045or 1046.Li \&.Dp 1047from 1048.Li \&.Dl 1049is redundant and may cause unpredictable errors. 1050.Tp Li \&.Ds 1051Display a block of text as typed, 1052right margin edges are left ragged. 1053Nesting 1054.Li \&.Ds 1055requests seems to work, 1056so they can be used outside and within 1057tagged paragraphs. Each 1058.Li \&.Ds 1059request must be ended with a 1060.Li \&De 1061request. 1062.Li \&.Ds 1063takes can be manipulated to indent 1064with the 1065.Li \&L , \&C , \&R , 1066and 1067.Li \&I 1068flags. 1069.Dw 4n 1070.Dp Li L 1071Align block on the current left margin, 1072this is the default mode of 1073.Li \&.Ds 1074if called without arguments. 1075.Dp Li C 1076Supposedly center the block. At this time 1077unfortunately, the block merely gets 1078left aligned about an imaginary center margin. 1079This will be fixed some time inthe near future. 1080.Dp Li I 1081Indent from left margin default amount (usually 1082about a three quarters of an inch or eight 1083constant width characters). 1084.Dp Li R 1085This left aligns the block about two inches from 1086the right side of the page. It too, alas, needs 1087work. 1088.Dp 1089.Tp Li \&.De 1090Ends a 1091.Li \&.Ds 1092request. 1093.Tp Li \&.Df 1094Display a filled (formatted) block. Identical to 1095.Li \&.Ds , 1096except the block of text is formatted (the edges are 1097not left ragged). Takes the same modifers as 1098.Li Ds . 1099.Tp 1100.Ss Tagged paragraphs and Columns 1101The commands 1102.Li \&.Tp 1103and 1104.Li \&.Dp 1105create tagged paragraph 1106lists. 1107Like the 1108.Li \&.Cx 1109request, 1110both require a begin and end. When 1111.Li \&.Tp 1112or 1113.Li \&.Dp 1114are called with arguments, they collect and 1115create the tag portion from 1116the arguments. 1117Anything after the tag is placed in 1118the paragraph portion. 1119The 1120.Li \&.Dp 1121macro is essentially the same as 1122the \&.Tp 1123macro, but with a few added features. 1124These are discussed following the 1125.Li \&.Tp 1126example. 1127.Li \&.Tp 1128and 1129.Li \&.Dp 1130can call several macros, 1131these are: 1132.Pp 1133.Dl \&.Ad, \&.Ar, \&.Cm, \&.Em, \&.Er, \&.Ev, \&.Fl, \&.Fn, \&.Ic, 1134.Dl \&.Li, \&.Nm, \&.Sy, \&.Va and \&.Xr. 1135.Pp 1136The 1137.Li \&.Tp 1138request can be nested, and values for determining 1139the width of each tag are based on which macro 1140.Li \&.Tp 1141is calling, if it is calling one, or by specifying 1142a width with the 1143.Li \&.Tw 1144request. 1145The default width for an unknown tag type is set to just 1146about one and three quarter inches, or 20 characters in a 1147constant width font. 1148If the default width is unsatisfactory, 1149.Li \&.Tw 1150can be used as follows: 1151.Dp Li \&.Tw Fl 1152sets the width to the default flag width 1153.Li \&.Fl , 1154which is 1155set to ten constant width characters or about five sixth of 1156an inch. 1157.Dp Li \&.Tw 24n 1158sets the width to 24 constant width characters or about two 1159inches. The 1160.Li n 1161is absolutely necessary for the scaling to work correctly. 1162.Dp Li \&.Tw ENAMETOOLONG 1163sets the width to the constant width length of the 1164string given. 1165.Dp Li \&.Tw int\e\ mkfifo 1166again, the width is set to the constant width of the string 1167given, and the space is protected with a preceding 1168.Li \e . 1169.Dp 1170.Pp 1171A nesting 1172.Li \&.Tp 1173Example: 1174.Pp 1175.Tp Nm Name1 1176This is the first call to 1177.Li \&.Tp 1178with 1179.Li \&.Nm . 1180.Tp Nm Name2 1181Another call with 1182.Li \&.Nm . 1183.Tp Va Variable1 1184An example of the 1185.Li \&.Va 1186request with 1187.Li \&.Tp . 1188Since the first argument was callable 1189and different from the last one, the 1190tag was indented. 1191.Tp Va Variable2 1192Another 1193.Li \&.Va 1194example. 1195.Tp Fl Flag1 1196A third nest (indent) using the 1197.Li \&.Fl 1198request. 1199.Tp Fl Flag2 1200Again the 1201.Li \&.Fl 1202.Tp 1203.Pp 1204A 1205.Li \&.Tp 1206with no arguments stops the current nest 1207and exdents back to the previous level. 1208.Tp Va Variable3 1209Another call with the 1210.Li \&.Va 1211request. 1212.Tp 1213.Pp 1214Again a 1215.Li \&.Tp 1216without arguments exdents. This will put 1217us back at the first level. 1218.Tp Nm Name3 1219Another 1220.Li \&.Nm 1221request. This request is followed 1222by the last call to 1223.Li \&.Tp 1224without arguments. 1225.Tp 1226.Pp 1227The above was created from: 1228.Pp 1229.Ds I 1230\&.Tp Nm Name1 1231This is the first call to 1232\&.Li \&.Tp 1233with 1234\&.Li \&.Nm . 1235\&.Tp Nm Name2 1236Another call with 1237\&.Li \&.Nm . 1238\&.Tp Va Variable1 1239An example of the 1240\&.Li \&.Va 1241request with 1242\&.Li \&.Tp . 1243Since the first argument was callable and different from 1244the last one, the tag was indented. 1245\&.Tp Va Variable2 1246Another 1247\&.Li \&.Va 1248example. 1249\&.Tp Fl Flag1 1250A third nest (indent) using the 1251\&.Li \&.Fl 1252request. 1253\&.Tp Fl Flag2 1254Again the 1255\&.Li \&.Fl 1256\&.Tp 1257A 1258\&.Li \&.Tp 1259with no arguments stops the current nest 1260and exdents back to the previous level. 1261\&.Tp Va Variable3 1262Another call with the 1263\&.Li \&.Va 1264request. 1265\&.Tp 1266Again a 1267\&.Li \&.Tp 1268without argments exdents. 1269This will put us back at the first level. 1270\&.Tp Nm Name3 1271Another 1272\&.Li \&.Nm 1273request. This request is followed by the last call to 1274\&.Li \&.Tp 1275without arguments. 1276\&.Tp 1277.De 1278.Pp 1279An example of 1280.Li \&.Dp: 1281.Pp 1282.Dw PAGEIN\ 10 1283.Dp SL 10 1284sleep time of the process (seconds blocked) 1285.Dp PAGEIN 10 1286number of disk i/o's resulting from references by the process 1287to pages not loaded in core. 1288.Dp UID 10 1289numerical user-id of process owner 1290.Dp PPID 10 1291numerical id of parent of process 1292process priority (non-positive when in non-interruptible wait) 1293.Dp 1294.Pp 1295The raw text: 1296.Pp 1297.Ds I 1298.Li \&.Dw PAGEIN\ 10 1299.Li \&.Dp SL 10 1300sleep time of the process (seconds blocked) 1301.Li \&.Dp PAGEIN 10 1302number of disk i/o's resulting from references by the process 1303to pages not loaded in core. 1304.Li \&.Dp UID 10 1305numerical user-id of process owner 1306.Li \&.Dp PPID 10 1307numerical id of parent of process 1308process priority (non-positive when in non-interruptible wait) 1309.Li \&.Dp 1310.De 1311.Pp 1312The default behaviour of 1313.Li \&.Dp 1314is to indent a small amount from the current margin before 1315processing the tag. This margin can be changed with the 1316request 1317.Li \&.Di 1318which takes as its first argument either a numerical 1319argument (e.g. a scaled number like 24n) or a letter 1320.Li \&L 1321or 1322.Li \&I . 1323The 1324.Li \&L 1325forces a left margin, which is useful if something doesn't 1326quite fit (as in the example for the 1327.Li \&.Fn 1328macro in the TEXT MACRO section above). 1329The 1330.Li \&I 1331is the default, but may be used for a return to the default 1332if necessary. Like all the tagged widths, the indents 1333are pushed on a stack, and when that stack (or level) 1334is expired, the previous values are used (this happens 1335whenever a 1336.Li \&.Dp 1337or 1338.Li \&.Tp 1339is called without arguments). 1340In this example, 1341.Li \&.Dw 1342has been used to set the width of the tag. 1343It is identical to the request 1344.Li \&.Tw 1345discussed above. 1346.Ss Columns 1347The column request is made up of a width request, 1348.Li \&.Cw , 1349and a column line request, 1350.Li \&.Cl . 1351From one to four simple columns can be created 1352and all but the last column, are simple 1353single entry style columns. 1354The last (rightmost) column can overflow into 1355a indented paragraph. 1356.Pp 1357The 1358.Li \&.Cw 1359request takes at most three arguments 1360as width indicators. The number of columns is 1361always one more than given to 1362.Li \&.Cw . 1363the 1364.Li \&.Cl 1365request should have its arguments 1366on the next line and the columns should be 1367separated by a tab character. 1368.Pp 1369An example of two columns: 1370.Cw Macros 1371.Cl Macros Description 1372.Cl \&.Tp List Request 1373.Cl \&.Nm Name Request 1374.Cw 1375.Pp 1376The requests used to format the 1377columns above (the jagged edges are from tabs which can 1378also be represented by 1379.Li \et ) : 1380.Pp 1381.Dl \&.Cw Macros 1382.Dl \&.Cl Macros Description 1383.Dl \&.Cl \e&.Tp List Request 1384.Dl \&.Cl \e&.Nm Name Request 1385.Dl \&.Cw 1386.Pp 1387There some problems with columns at the moment, while they 1388work well in nested lists, they are otherwise difficult 1389to offset via example. 1390.Ss Options 1391The 1392.Li \&.Op 1393request ain't quite working perfectly. 1394The (eventual) goal of 1395.Li \&.Op 1396is to place brackets around the given arguments, and place any 1397punctuation outside the brackets. In the case of 1398.Li \&.Cx, 1399trailing punctuation on the same request line as the 1400.Li \&.Op 1401should be placed outside the brackets. 1402The multiple macro calls are one of the reasons this request is so moody. 1403Is is the only macro which attempts to call other macros on the 1404request line. Its not doing too badly, just not perfect: 1405.Dw \&.Op\ Fl\ c\ Ar\ objfil\ Op\ Ar\ corfil\ , 1406.Dp Li \&.Op 1407.Op 1408.Dp Li \&.Op Fl k 1409.Op Fl k 1410.Dp Li \&.Op Fl k\ )\ . 1411.Op Fl k ) . 1412.Dp Li \&.Op Fl k Ar kookfile 1413.Op Fl k Ar kookfile 1414.Dp Li \&.Op Fl k Ar kookfile\ , 1415.Op Fl k Ar kookfile , 1416.Dp Li \&.Op Ar objfil Op Ar corfil 1417.Op Ar objfil Op Ar corfil 1418.Dp Li \&.Op Fl c Ar objfil Op Ar corfil\ , 1419.Op Fl c Ar objfil Op Ar corfil , 1420.Dp Li \&.Op word1 word2 1421.Op word1 word2 1422.Dp 1423.Pp 1424The punctuation on the second to last example is 1425improperly placed and should be fixed some day. 1426.Sh FILES 1427.\" .Pa /usr/share/tmac/tmac.doc.style site specific layout 1428.Dw /usr/share/man0/template.doc 1429.Di L 1430.Dp Pa /usr/share/tmac/tmac.doc 1431manual macro package 1432.Dp Pa /usr/share/man0/template.doc 1433template for writing a man page 1434.Dp 1435.Sh HISTORY 14364.4 BSD 1437.Sh SEE ALSO 1438.Xr mdoc.samples 7 , 1439.Xr man 1 , 1440.Xr troff 1 1441.Sh BUGS 1442.Pp 1443Punctuation may be broken on 1444.Li \&.Op 1445again. 1446.Pp 1447Undesirable hyphenation on the dash of a flag 1448argument is not yet resolved, and causes 1449occasional mishaps in the DESCRIPTION section. 1450.Pp 1451Predefined strings are not declared in documentation. 1452.Pp 1453Section 3f has not been added to the header routines. 1454.Pp 1455.Li \&.Nm 1456font should be changed in NAME section. 1457.Pp 1458.Li \&.Fn 1459needs to have a check to prevent splitting up 1460if the line length is too short. Right now it 1461separates the last parenthesis, and sometimes 1462looks ridiculous if a line is in fill mode. 1463.Pp 1464The method used to prevent header and footer page 1465breaks (other than the initial header and footer) when using 1466nroff seems to be putting out a partially filled line 1467at the bottom of the page leaving an unsightly blank space. 1468.Pp 1469The tagged paragraph, display and column requests to not do any keeps 1470and certainly should be able to. 1471.Pp 1472Occasionally there maybe a problem with mathematical 1473or logical interpretation of characters from the 1474set 1475{+,\-,/,*,%,<,>,<=,>=,=,==,&} 1476found as the second 1477character in an argument string which may be checked for punctuation. 1478This is a relatively rare occurrence, as a lot of checking is 1479done to prevent it, 1480but if it should happen 1481escape the characters 1482with 1483.Li \e& . 1484