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