man7/mdoc.samples.7

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