/[groff]/groff/doc/groff.texinfo
ViewVC logotype

Diff of /groff/doc/groff.texinfo

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.221 by wl, Thu Sep 1 22:25:06 2005 UTC revision 1.222 by wl, Sun Sep 4 09:41:37 2005 UTC
# Line 372  Software Foundation raise funds for GNU Line 372  Software Foundation raise funds for GNU
372  @end macro  @end macro
373    
374    
375  @c We need special parentheses and brackets:  @c We need special parentheses, brackets, and braces:
376  @c  @c
377  @c . Real parentheses in @deffn produce an error while compiling with  @c . Real parentheses in @deffn produce an error while compiling with
378  @c   TeX.  @c   TeX.
379  @c . Real brackets use the wrong font in @deffn, overriding @t{}.  @c . Real brackets use the wrong font in @deffn, overriding @t{}.
380  @c  @c
381    @c . @{ and @} fail with info if used in a macro.
382    @c
383  @c Since macros aren't expanded in @deffn during -E, the following  @c Since macros aren't expanded in @deffn during -E, the following
384  @c definitions are for non-TeX only.  @c definitions are for non-TeX only.
385  @c  @c
386  @c This is true for texinfo 4.0.  @c This is true for texinfo 4.0 and above.
387    
388  @iftex  @iftex
389  @set Lparenmacro @lparen  @set Lparenmacro @lparen
390  @set Rparenmacro @rparen  @set Rparenmacro @rparen
391  @set Lbrackmacro @lbrack  @set Lbrackmacro @lbrack
392  @set Rbrackmacro @rbrack  @set Rbrackmacro @rbrack
393    @set Lbracemacro @{
394    @set Rbracemacro @}
395  @end iftex  @end iftex
396    
397  @ifnottex  @ifnottex
# Line 395  Software Foundation raise funds for GNU Line 399  Software Foundation raise funds for GNU
399  @set Rparenmacro )  @set Rparenmacro )
400  @set Lbrackmacro [  @set Lbrackmacro [
401  @set Rbrackmacro ]  @set Rbrackmacro ]
402    @set Lbracemacro @{
403    @set Rbracemacro @}
404  @end ifnottex  @end ifnottex
405    
406  @macro Lparen{}  @macro Lparen{}
# Line 409  Software Foundation raise funds for GNU Line 415  Software Foundation raise funds for GNU
415  @macro Rbrack{}  @macro Rbrack{}
416  @value{Rbrackmacro}  @value{Rbrackmacro}
417  @end macro  @end macro
418    @macro Lbrace{}
419    @value{Lbracemacro}
420    @end macro
421    @macro Rbrace{}
422    @value{Rbracemacro}
423    @end macro
424    
425    
426  @c This suppresses the word `Appendix' in the appendix headers.  @c This suppresses the word `Appendix' in the appendix headers.
# Line 480  Software Foundation raise funds for GNU Line 492  Software Foundation raise funds for GNU
492  @end ifinfo  @end ifinfo
493    
494  @ifhtml  @ifhtml
495    @menu
496    * Introduction::
497    * Invoking groff::
498    * Tutorial for Macro Users::
499    * Macro Packages::
500    * gtroff Reference::
501    * Preprocessors::
502    * Output Devices::
503    * File formats::
504    * Installation::
505    * Copying This Manual::
506    * Request Index::
507    * Escape Index::
508    * Operator Index::
509    * Register Index::
510    * Macro Index::
511    * String Index::
512    * Glyph Name Index::
513    * Font File Keyword Index::
514    * Program and File Index::
515    * Concept Index::
516    @end menu
517    
518  @node Top, Introduction, (dir), (dir)  @node Top, Introduction, (dir), (dir)
519  @top GNU troff  @top GNU troff
520    
# Line 2148  restrictions, 2@tie{} to not hyphenate t Line 2183  restrictions, 2@tie{} to not hyphenate t
2183  values are additive; the default is@tie{}14.  values are additive; the default is@tie{}14.
2184    
2185  @item -rIN=@var{length}  @item -rIN=@var{length}
2186  Set the body text indent to @var{length}.  Set the body text indentation to @var{length}.
2187  If not specified, the indent defaults to 7@dmn{n}  If not specified, the indentation defaults to 7@dmn{n}
2188  (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.  (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise.
2189  For nroff, this value should always be an integer multiple of unit @samp{n}  For nroff, this value should always be an integer multiple of unit @samp{n}
2190  to get consistent indentation.  to get consistent indentation.
# Line 2186  Use @var{xx} (which can be 10, 11, or@ti Line 2221  Use @var{xx} (which can be 10, 11, or@ti
2221  document font size instead of the default value of@tie{}10@dmn{pt}.  document font size instead of the default value of@tie{}10@dmn{pt}.
2222    
2223  @item -rSN=@var{length}  @item -rSN=@var{length}
2224  Set the indent for sub-subheadings to @var{length}.  Set the indentation for sub-subheadings to @var{length}.
2225  If not specified, the indent defaults to 3@dmn{n}.  If not specified, the indentation defaults to 3@dmn{n}.
2226    
2227  @item -rX@var{nnn}  @item -rX@var{nnn}
2228  After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,  After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
# Line 2746  at the command line). Line 2781  at the command line).
2781  @section @file{ms}  @section @file{ms}
2782  @cindex @code{ms} macros  @cindex @code{ms} macros
2783    
2784  The @file{-ms}  The @file{-ms} macros are suitable for reports, letters, books, user
2785  macros are suitable for reports, letters, books,  manuals, and so forth.  The package provides macros for cover pages,
2786  user manuals, and so forth.  section headings, paragraphs, lists, footnotes, pagination, and a
2787  The package provides macros for cover pages, section headings,  table of contents.
 paragraphs, lists, footnotes, pagination,  
 and a table of contents.  
2788    
2789  @menu  @menu
2790  * ms Intro::  * ms Intro::
# Line 2761  and a table of contents. Line 2794  and a table of contents.
2794  * ms Body Text::  * ms Body Text::
2795  * ms Page Layout::  * ms Page Layout::
2796  * Differences from AT&T ms::  * Differences from AT&T ms::
2797    * Naming Conventions::
2798  @end menu  @end menu
2799    
2800  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
# Line 2768  and a table of contents. Line 2802  and a table of contents.
2802  @node ms Intro, General ms Structure, ms, ms  @node ms Intro, General ms Structure, ms, ms
2803  @subsection Introduction to @file{ms}  @subsection Introduction to @file{ms}
2804    
2805  The original @file{-ms} macros were included with  The original @file{-ms} macros were included with @acronym{AT&T}
2806  @acronym{AT&T} @code{troff} as well as the  @code{troff} as well as the @file{man} macros.  While the @file{man}
2807  @file{man} macros.  package is intended for brief documents that can be read on-line as
2808  While the @file{man} package is intended for brief documents  well as printed, the @file{ms} macros are suitable for longer
2809  that can be read on-line as well as printed, the @file{ms}  documents that are meant to be printed rather than read on-line.
2810  macros are suitable for longer documents that are meant to be  
2811  printed rather than read on-line.  The @file{ms} macro package included with @code{groff} is a complete,
2812    bottom-up re-implementation.  Several macros (specific to
2813  The @file{ms} macro package included with @code{groff}  @acronym{AT&T} or Berkeley) are not included, while several new
2814  is a complete, bottom-up re-implementation.  commands are.  @xref{Differences from AT&T ms}, for more information.
 Several macros (specific to @acronym{AT&T}  
 or Berkeley) are not included, while several new commands are.  
 @xref{Differences from AT&T ms}, for more information.  
2815    
2816  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
2817    
# Line 2788  or Berkeley) are not included, while sev Line 2819  or Berkeley) are not included, while sev
2819  @subsection General structure of an @file{ms} document  @subsection General structure of an @file{ms} document
2820  @cindex @code{ms} macros, general structure  @cindex @code{ms} macros, general structure
2821    
2822  The @file{ms} macro package expects a certain amount of structure,  The @file{ms} macro package expects a certain amount of structure, but
2823  but not as much as packages such as @file{man} or @file{mdoc}.  not as much as packages such as @file{man} or @file{mdoc}.
2824    
2825  The simplest documents can begin with a paragraph macro  The simplest documents can begin with a paragraph macro (such as
2826  (such as @code{LP} or @code{PP}),  @code{LP} or @code{PP}), and consist of text separated by paragraph
2827  and consist of text separated by paragraph macros  macros or even blank lines.  Longer documents have a structure as
2828  or even blank lines.  follows:
 Longer documents have a structure as follows:  
2829    
2830  @table @strong  @table @strong
2831  @item Document type  @item Document type
2832  If you invoke the @code{RP}  If you invoke the @code{RP} (report) macro on the first line of the
2833  (report) macro on the first line of the document,  document, @code{groff} prints the cover page information on its own
2834  @code{groff} prints the cover page information on its own page;  page; otherwise it prints the information on the first page with your
2835  otherwise it prints the information on the  document text immediately following.  Other document formats found in
2836  first page with your document text immediately following.  @acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or
2837  Other document formats found in @acronym{AT&T} @code{troff}  Berkeley, and are not supported in @code{groff}.
 are specific to @acronym{AT&T} or Berkeley, and are not supported in  
 @code{groff}.  
2838    
2839  @item Format and layout  @item Format and layout
2840  By setting number registers,  By setting number registers, you can change your document's type (font
2841  you can change your document's type (font and size),  and size), margins, spacing, headers and footers, and footnotes.
 margins, spacing, headers and footers, and footnotes.  
2842  @xref{ms Document Control Registers}, for more details.  @xref{ms Document Control Registers}, for more details.
2843    
2844  @item Cover page  @item Cover page
2845  A cover page consists of a title, the author's name and institution,  A cover page consists of a title, the author's name and institution,
2846  an abstract, and the date.  an abstract, and the date.@footnote{Actually, only the title is
2847  @footnote{Actually, only the title is required.}  required.}  @xref{ms Cover Page Macros}, for more details.
 @xref{ms Cover Page Macros}, for more details.  
2848    
2849  @item Body  @item Body
2850  Following the cover page is your document.  Following the cover page is your document.  You can use the @file{ms}
2851  You can use the @file{ms}  macros to write reports, letters, books, and so forth.  The package is
2852  macros to write reports, letters, books, and so forth.  designed for structured documents, consisting of paragraphs
2853  The package is designed for structured documents,  interspersed with headings and augmented by lists, footnotes, tables,
2854  consisting of paragraphs interspersed with headings  and other common constructs.  @xref{ms Body Text}, for more details.
 and augmented by lists, footnotes, tables, and other  
 common constructs.  
 @xref{ms Body Text}, for more details.  
2855    
2856  @item Table of contents  @item Table of contents
2857  Longer documents usually include a table of contents,  Longer documents usually include a table of contents, which you can
2858  which you can invoke by placing the  invoke by placing the @code{TC} macro at the end of your document.
2859  @code{TC}  The @file{ms} macros have minimal indexing facilities, consisting of
2860  macro at the end of your document.  the @code{IX} macro, which prints an entry on standard error.
 The @file{ms}  
 macros have minimal indexing facilities, consisting of the  
 @code{IX} macro, which prints an entry on standard error.  
2861  Printing the table of contents at the end is necessary since  Printing the table of contents at the end is necessary since
2862  @code{groff} is a single-pass text formatter,  @code{groff} is a single-pass text formatter, thus it cannot determine
2863  thus it cannot determine the page number of each section  the page number of each section until that section has actually been
2864  until that section has actually been set and printed.  set and printed.  Since @file{ms} output is intended for hardcopy, you
2865  Since @file{ms} output is intended for hardcopy,  can manually relocate the pages containing the table of contents
2866  you can manually relocate the pages containing  between the cover page and the body text after printing.
 the table of contents between the cover page and the  
 body text after printing.  
2867  @end table  @end table
2868    
2869  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
# Line 2854  body text after printing. Line 2872  body text after printing.
2872  @subsection Document control registers  @subsection Document control registers
2873  @cindex @code{ms} macros, document control registers  @cindex @code{ms} macros, document control registers
2874    
2875  The following is a list of document control number registers.  The following is a list of document control number registers.  For the
2876  For the sake of consistency,  sake of consistency, set registers related to margins at the beginning
2877  set registers related to margins at the beginning of your document,  of your document, or just after the @code{RP} macro.  You can set
2878  or just after the @code{RP} macro.  other registers later in your document, but you should keep them
2879  You can set other registers later in your document,  together at the beginning to make them easy to find and edit as
2880  but you should keep them together at the beginning  necessary.
 to make them easy to find and edit as necessary.  
2881    
2882  @unnumberedsubsubsec Margin Settings  @unnumberedsubsubsec Margin Settings
2883    
2884  @Defmpreg {PO, ms}  @Defmpreg {PO, ms}
2885  Defines the page offset (i.e.@: the left margin).  Defines the page offset (i.e., the left margin).  There is no explicit
2886  There is no explicit right margin setting; the combination of  right margin setting; the combination of the @code{PO} and @code{LL}
2887  the @code{PO} and @code{LL} registers implicitly define the  registers implicitly define the right margin width.
 right margin width.  
2888    
2889  Effective: next page.  Effective: next page.
2890    
# Line 2876  Default value: 1@dmn{i}. Line 2892  Default value: 1@dmn{i}.
2892  @endDefmpreg  @endDefmpreg
2893    
2894  @Defmpreg {LL, ms}  @Defmpreg {LL, ms}
2895  Defines the line length (i.e.@: the width of the body text).  Defines the line length (i.e., the width of the body text).
2896    
2897  Effective: next paragraph.  Effective: next paragraph.
2898    
# Line 2884  Default: 6@dmn{i}. Line 2900  Default: 6@dmn{i}.
2900  @endDefmpreg  @endDefmpreg
2901    
2902  @Defmpreg {LT, ms}  @Defmpreg {LT, ms}
2903  Defines the title length (i.e.@: the header and footer width).  Defines the title length (i.e., the header and footer width).  This
2904  This is usually the same as @code{LL}, but not necessarily.  is usually the same as @code{LL}, but not necessarily.
2905    
2906  Effective: next paragraph.  Effective: next paragraph.
2907    
# Line 2911  Default: 1@dmn{i}. Line 2927  Default: 1@dmn{i}.
2927  @unnumberedsubsubsec Text Settings  @unnumberedsubsubsec Text Settings
2928    
2929  @Defmpreg {PS, ms}  @Defmpreg {PS, ms}
2930  Defines the point size of the body text.  If the value is larger than or  Defines the point size of the body text.  If the value is larger than
2931  equal to 1000, divide it by 1000 to get a fractional point size.  For  or equal to 1000, divide it by 1000 to get a fractional point size.
2932  example, @samp{.nr PS 10250} sets the document's point size to 10.25@dmn{p}.  For example, @samp{.nr PS 10250} sets the document's point size to
2933    10.25@dmn{p}.
2934    
2935  Effective: next paragraph.  Effective: next paragraph.
2936    
# Line 2921  Default: 10@dmn{p}. Line 2938  Default: 10@dmn{p}.
2938  @endDefmpreg  @endDefmpreg
2939    
2940  @Defmpreg {VS, ms}  @Defmpreg {VS, ms}
2941  Defines the space between lines (line height plus leading).  If the value  Defines the space between lines (line height plus leading).  If the
2942  is larger than or equal to 1000, divide it by 1000 to get a fractional point  value is larger than or equal to 1000, divide it by 1000 to get a
2943  size.  Due to backwards compatibility, @code{VS} must be smaller than  fractional point size.  Due to backwards compatibility, @code{VS} must
2944  40000 (this is 40.0@dmn{p}).  be smaller than 40000 (this is 40.0@dmn{p}).
2945    
2946  Effective: next paragraph.  Effective: next paragraph.
2947    
# Line 2933  Default: 12@dmn{p}. Line 2950  Default: 12@dmn{p}.
2950    
2951  @Defmpreg {PSINCR, ms}  @Defmpreg {PSINCR, ms}
2952  Defines an increment in point size, which will be applied to section  Defines an increment in point size, which will be applied to section
2953  headings at nesting levels below the value specified in @code{GROWPS}.  The  headings at nesting levels below the value specified in @code{GROWPS}.
2954  value of @code{PSINCR} should be specified in points, with the @dmn{p}  The value of @code{PSINCR} should be specified in points, with the
2955  scaling factor, and may include a fractional component; for example,  @dmn{p} scaling factor, and may include a fractional component; for
2956  @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 1.5@dmn{p}.  example, @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of
2957    1.5@dmn{p}.
2958    
2959  Effective: next section heading.  Effective: next section heading.
2960    
# Line 2945  Default: 1@dmn{p}. Line 2963  Default: 1@dmn{p}.
2963    
2964  @Defmpreg {GROWPS, ms}  @Defmpreg {GROWPS, ms}
2965  Defines the heading level below which the point size increment set by  Defines the heading level below which the point size increment set by
2966  @code{PSINCR} becomes effective.  Section headings at and above the level  @code{PSINCR} becomes effective.  Section headings at and above the
2967  specified by @code{GROWPS} will be printed at the point size set by @code{PS};  level specified by @code{GROWPS} will be printed at the point size set
2968  for each level below the value of @code{GROWPS}, the point size will be  by @code{PS}; for each level below the value of @code{GROWPS}, the
2969  increased in steps equal to the value of @code{PSINCR}.  Setting @code{GROWPS}  point size will be increased in steps equal to the value of
2970  to any value less than@tie{}2 disables the incremental heading size feature.  @code{PSINCR}.  Setting @code{GROWPS} to any value less than@tie{}2
2971    disables the incremental heading size feature.
2972    
2973  Effective: next section heading.  Effective: next section heading.
2974    
# Line 2957  Default: 0. Line 2976  Default: 0.
2976  @endDefmpreg  @endDefmpreg
2977    
2978  @Defmpreg {HY, ms}  @Defmpreg {HY, ms}
2979  Defines the hyphenation level. @code{HY} sets safely the value of the  Defines the hyphenation level.  @code{HY} sets safely the value of the
2980  low-level @code{.hy} register. Setting the value of @code{HY} to 0 is  low-level @code{hy} register.  Setting the value of @code{HY}
2981  equivalent to using the @code{.nh} request.  to@tie{}0 is equivalent to using the @code{nh} request.
2982    
2983  Effective: next paragraph.  Effective: next paragraph.
2984    
# Line 2977  Default: as defined in the output device Line 2996  Default: as defined in the output device
2996  @unnumberedsubsubsec Paragraph Settings  @unnumberedsubsubsec Paragraph Settings
2997    
2998  @Defmpreg {PI, ms}  @Defmpreg {PI, ms}
2999  Defines the initial indent of a @code{.PP} paragraph.  Defines the initial indentation of a (@code{PP} macro) paragraph.
3000    
3001  Effective: next paragraph.  Effective: next paragraph.
3002    
# Line 2993  Default: 0.3@dmn{v}. Line 3012  Default: 0.3@dmn{v}.
3012  @endDefmpreg  @endDefmpreg
3013    
3014  @Defmpreg {QI, ms}  @Defmpreg {QI, ms}
3015  Defines the indent on both sides of a quoted (@code{.QP}) paragraph.  Defines the indentation on both sides of a quoted (@code{QP} macro)
3016    paragraph.
3017    
3018  Effective: next paragraph.  Effective: next paragraph.
3019    
# Line 3001  Default: 5@dmn{n}. Line 3021  Default: 5@dmn{n}.
3021  @endDefmpreg  @endDefmpreg
3022    
3023  @Defmpreg {PORPHANS, ms}  @Defmpreg {PORPHANS, ms}
3024  Defines the minimum number of initial lines of any paragraph which should  Defines the minimum number of initial lines of any paragraph which
3025  be kept together, to avoid orphan lines at the bottom of a page.  If a new  should be kept together, to avoid orphan lines at the bottom of a
3026  paragraph is started close to the bottom of a page, and there is insufficient  page.  If a new paragraph is started close to the bottom of a page,
3027  space to accommodate @code{PORPHANS} lines before an automatic page break,  and there is insufficient space to accommodate @code{PORPHANS} lines
3028  then the page break will be forced, before the start of the paragraph.  before an automatic page break, then the page break will be forced,
3029    before the start of the paragraph.
3030    
3031  Effective: next paragraph.  Effective: next paragraph.
3032    
# Line 3013  Default: 1. Line 3034  Default: 1.
3034  @endDefmpreg  @endDefmpreg
3035    
3036  @Defmpreg {HORPHANS, ms}  @Defmpreg {HORPHANS, ms}
3037  Defines the minimum number of lines of the following paragraph which should  Defines the minimum number of lines of the following paragraph which
3038  be kept together with any section heading introduced by the @code{NH} or  should be kept together with any section heading introduced by the
3039  @code{SH} macros.  If a section heading is placed close to the bottom of a  @code{NH} or @code{SH} macros.  If a section heading is placed close
3040  page, and there is insufficient space to accommodate both the heading and  to the bottom of a page, and there is insufficient space to
3041  at least @code{HORPHANS} lines of the following paragraph, before an  accommodate both the heading and at least @code{HORPHANS} lines of the
3042  automatic page break, then the page break will be forced before the heading.  following paragraph, before an automatic page break, then the page
3043    break will be forced before the heading.
3044    
3045  Effective: next paragraph.  Effective: next paragraph.
3046    
# Line 3036  Default: @math{@code{@\n[LL]} * 5 / 6}. Line 3058  Default: @math{@code{@\n[LL]} * 5 / 6}.
3058  @endDefmpreg  @endDefmpreg
3059    
3060  @Defmpreg {FI, ms}  @Defmpreg {FI, ms}
3061  Defines the footnote indent.  Defines the footnote indentation.
3062    
3063  Effective: next footnote.  Effective: next footnote.
3064    
# Line 3047  Default: 2@dmn{n}. Line 3069  Default: 2@dmn{n}.
3069  The footnote format:  The footnote format:
3070  @table @code  @table @code
3071  @item 0  @item 0
3072  Prints the footnote number as a superscript; indents the footnote (default).  Print the footnote number as a superscript; indent the footnote
3073    (default).
3074    
3075  @item 1  @item 1
3076  Prints the number followed by a period (like 1.)  Print the number followed by a period (like 1.@:) and indent the
3077  and indents the footnote.  footnote.
3078    
3079  @item 2  @item 2
3080  Like 1, without an indent.  Like 1, without an indentation.
3081    
3082  @item 3  @item 3
3083  Like 1, but prints the footnote number as a hanging paragraph.  Like 1, but print the footnote number as a hanging paragraph.
3084  @end table  @end table
3085    
3086  Effective: next footnote.  Effective: next footnote.
# Line 3066  Default: 0. Line 3089  Default: 0.
3089  @endDefmpreg  @endDefmpreg
3090    
3091  @Defmpreg {FPS, ms}  @Defmpreg {FPS, ms}
3092  Defines the footnote point size.  If the value is larger than or equal to  Defines the footnote point size.  If the value is larger than or equal
3093  1000, divide it by 1000 to get a fractional point size.  to 1000, divide it by 1000 to get a fractional point size.
3094    
3095  Effective: next footnote.  Effective: next footnote.
3096    
# Line 3075  Default: @math{@code{@\n[PS]} - 2}. Line 3098  Default: @math{@code{@\n[PS]} - 2}.
3098  @endDefmpreg  @endDefmpreg
3099    
3100  @Defmpreg {FVS, ms}  @Defmpreg {FVS, ms}
3101  Defines the footnote vertical spacing.  If the value is larger than or equal  Defines the footnote vertical spacing.  If the value is larger than or
3102  to 1000, divide it by 1000 to get a fractional point size.  equal to 1000, divide it by 1000 to get a fractional point size.
3103    
3104  Effective: next footnote.  Effective: next footnote.
3105    
# Line 3108  Default: 2@dmn{n}. Line 3131  Default: 2@dmn{n}.
3131  @cindex @code{ms} macros, cover page  @cindex @code{ms} macros, cover page
3132  @cindex cover page macros, [@code{ms}]  @cindex cover page macros, [@code{ms}]
3133    
3134  Use the following macros to create a cover page for your document  Use the following macros to create a cover page for your document in
3135  in the order shown.  the order shown.
3136    
3137  @Defmac {RP, [@code{no}], ms}  @Defmac {RP, [@code{no}], ms}
3138  Specifies the report format for your document.  Specifies the report format for your document.  The report format
3139  The report format creates a separate cover page.  creates a separate cover page.  The default action (no @code{RP}
3140  The default action (no @code{.RP}  macro) is to print a subset of the cover page on page@tie{}1 of your
3141  macro) is to print a subset of the  document.
3142  cover page on page 1 of your document.  
3143    If you use the word @code{no} as an optional argument, @code{groff}
3144  If you use the word @code{no} as an optional argument,  prints a title page but does not repeat any of the title page
3145  @code{groff} prints a title page but  information (title, author, abstract, etc.@:) on page@tie{}1 of the
3146  does not repeat any of the title page information  document.
3147  (title, author, abstract, etc.)  @endDefmac
3148  on page 1 of the document.  
3149    @Defmac {P1, , ms}
3150    (P-one) Prints the header on page@tie{}1.  The default is to suppress
3151    the header.
3152  @endDefmac  @endDefmac
3153    
3154  @Defmac {DA, [@dots{}], ms}  @Defmac {DA, [@dots{}], ms}
3155  (optional) Print the current date, or the arguments to the macro if any,  (optional) Prints the current date, or the arguments to the macro if
3156  on the title page (if specified) and in the footers.  any, on the title page (if specified) and in the footers.  This is the
3157  This is the default for @code{nroff}.  default for @code{nroff}.
3158  @endDefmac  @endDefmac
3159    
3160  @Defmac {ND, [@dots{}], ms}  @Defmac {ND, [@dots{}], ms}
3161  (optional) Print the current date, or the arguments to the macro if any,  (optional) Prints the current date, or the arguments to the macro if
3162  on the title page (if specified) but not in the footers.  any, on the title page (if specified) but not in the footers.  This is
3163  This is the default for @code{troff}.  the default for @code{troff}.
3164  @endDefmac  @endDefmac
3165    
3166  @Defmac {TL, , ms}  @Defmac {TL, , ms}
3167  Specifies the document title.  Specifies the document title.  @code{groff} collects text following
3168  @code{groff} collects text following the @code{.TL}  the @code{TL} macro into the title, until reaching the author name or
3169  macro into the title, until reaching the author name or abstract.  abstract.
3170  @endDefmac  @endDefmac
3171    
3172  @Defmac {AU, , ms}  @Defmac {AU, , ms}
3173  Specifies the author's name, which appears on the  Specifies the author's name, which appears on the line (or lines)
3174  line (or lines) immediately following.  immediately following.  You can specify multiple authors as follows:
 You can specify multiple authors as follows:  
3175    
3176  @Example  @Example
3177  .AU  .AU
# Line 3163  Monolithic Corporation Line 3188  Monolithic Corporation
3188  @endDefmac  @endDefmac
3189    
3190  @Defmac {AI, , ms}  @Defmac {AI, , ms}
3191  Specifies the author's institution.  Specifies the author's institution.  You can specify multiple
3192  You can specify multiple institutions in the same way  institutions in the same way that you specify multiple authors.
 that you specify multiple authors.  
3193  @endDefmac  @endDefmac
3194    
3195  @Defmac {AB, [@code{no}], ms}  @Defmac {AB, [@code{no}], ms}
3196  Begins the abstract.  Begins the abstract.  The default is to print the word
3197  The default is to print the word @acronym{ABSTRACT},  @acronym{ABSTRACT}, centered and in italics, above the text of the
3198  centered and in italics, above the text of the abstract.  abstract.  The word @code{no} as an optional argument suppresses this
3199  The word @code{no} as an optional argument suppresses this heading.  heading.
3200  @endDefmac  @endDefmac
3201    
3202  @Defmac {AE, , ms}  @Defmac {AE, , ms}
3203  End the abstract.  Ends the abstract.
3204  @endDefmac  @endDefmac
3205    
3206  The following is example mark-up for a title page.  The following is example mark-up for a title page.
# Line 3221  user demand. Line 3245  user demand.
3245  @subsection Body text  @subsection Body text
3246  @cindex @code{ms} macros, body text  @cindex @code{ms} macros, body text
3247    
3248  This section describes macros used to mark up the body of your document.  This section describes macros used to mark up the body of your
3249  Examples include paragraphs, sections, and other groups.  document.  Examples include paragraphs, sections, and other groups.
3250    
3251  @menu  @menu
3252  * Paragraphs in ms::  * Paragraphs in ms::
3253  * Headings in ms::  * Headings in ms::
3254  * Highlighting in ms::  * Highlighting in ms::
3255  * Lists in ms::  * Lists in ms::
3256  * Indents in ms::  * Indentation values in ms::
3257  * Tabstops in ms::  * Tabstops in ms::
3258  * ms Displays and Keeps::  * ms Displays and Keeps::
3259  * ms Insertions::  * ms Insertions::
# Line 3245  Examples include paragraphs, sections, a Line 3269  Examples include paragraphs, sections, a
3269    
3270  The following paragraph types are available.  The following paragraph types are available.
3271    
3272  @Defmac {PP, , ms}  @DefmacList {PP, , ms}
3273  Sets a paragraph with an initial indent.  @DefmacListEnd {LP, , ms}
3274  @endDefmac  Sets a paragraph with an initial indentation.
   
 @Defmac {LP, , ms}  
 Sets a paragraph with no initial indent.  
3275  @endDefmac  @endDefmac
3276    
3277  @Defmac {QP, , ms}  @Defmac {QP, , ms}
3278  Sets a paragraph that is indented at both left and right margins.  Sets a paragraph that is indented at both left and right margins.  The
3279  The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.  effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element.
3280  The next paragraph or heading returns margins to normal.  The next paragraph or heading returns margins to normal.
3281  @endDefmac  @endDefmac
3282    
3283  @Defmac {XP, , ms}  @Defmac {XP, , ms}
3284  Sets a paragraph whose lines are indented,  Sets a paragraph whose lines are indented, except for the first line.
 except for the first line.  
3285  This is a Berkeley extension.  This is a Berkeley extension.
3286  @endDefmac  @endDefmac
3287    
# Line 3312  printing of orphan lines at the bottom o Line 3332  printing of orphan lines at the bottom o
3332  @cindex @code{ms} macros, headings  @cindex @code{ms} macros, headings
3333    
3334  Use headings to create a hierarchical structure for your document.  Use headings to create a hierarchical structure for your document.
3335  The @file{ms} macros print headings in @strong{bold},  The @file{ms} macros print headings in @strong{bold}, using the same
3336  using the same font family and point size as the body text.  font family and point size as the body text.
3337    
3338  The following describes the heading macros:  The following describes the heading macros:
3339    
3340  @DefmacList {NH, @Var{curr-level}, ms}  @DefmacList {NH, @Var{curr-level}, ms}
3341  @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}  @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms}
3342  Numbered heading.  Numbered heading.  The argument is either a numeric argument to
3343  The argument is either a numeric argument to indicate the  indicate the level of the heading, or the letter@tie{}@code{S}
3344  level of the heading, or the letter@tie{}@code{S} followed by numeric  followed by numeric arguments to set the heading level explicitly.
 arguments to set the heading level explicitly.  
3345    
3346  If you specify heading levels out of sequence, such as invoking  If you specify heading levels out of sequence, such as invoking
3347  @samp{.NH 3} after @samp{.NH 1}, @code{groff}  @samp{.NH 3} after @samp{.NH 1}, @code{groff} prints a warning on
3348  prints a warning on standard error.  standard error.
3349  @endDefmac  @endDefmac
3350    
3351  @DefstrList {SN, ms}  @DefstrList {SN, ms}
# Line 3358  omitted).  The string @code{SN} is also Line 3377  omitted).  The string @code{SN} is also
3377  @Defmac {SH, [@Var{match-level}], ms}  @Defmac {SH, [@Var{match-level}], ms}
3378  Unnumbered subheading.  Unnumbered subheading.
3379    
3380  The optional @code{match-level} argument is a GNU extension.  It is a  The optional @var{match-level} argument is a GNU extension.  It is a
3381  number indicating the level of the heading, in a manner analogous to  number indicating the level of the heading, in a manner analogous to
3382  the @code{curr-level} argument to @code{.NH}.  Its purpose is to match  the @var{curr-level} argument to @code{.NH}.  Its purpose is to match
3383  the point size, at which the heading is printed, to the size of a  the point size, at which the heading is printed, to the size of a
3384  numbered heading at the same level, when the @code{GROWPS}/@code{PSINCR}  numbered heading at the same level, when the @code{GROWPS} and
3385  heading size adjustment mechanism is in effect.  @code{PSINCR} heading size adjustment mechanism is in effect.
3386  @xref{ms Document Control Registers}.  @xref{ms Document Control Registers}.
3387  @endDefmac  @endDefmac
3388    
# Line 3378  page. Line 3397  page.
3397  @subsubsection Highlighting  @subsubsection Highlighting
3398  @cindex @code{ms} macros, highlighting  @cindex @code{ms} macros, highlighting
3399    
3400  The @file{ms} macros provide a variety of methods to highlight  The @file{ms} macros provide a variety of methods to highlight or
3401  or emphasize text:  emphasize text:
3402    
3403  @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}  @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3404  Sets its first argument in @strong{bold type}.  Sets its first argument in @strong{bold type}.  If you specify a
3405  If you specify a second argument, @code{groff} prints it in the  second argument, @code{groff} prints it in the previous font after the
3406  previous font after the bold text, with no intervening space  bold text, with no intervening space (this allows you to set
3407  (this allows you to set punctuation after the highlighted text  punctuation after the highlighted text without highlighting the
3408  without highlighting the punctuation).  punctuation).  Similarly, it prints the third argument (if any) in the
3409  Similarly, it prints the third argument (if any) in the previous  previous font @strong{before} the first argument.  For example,
 font @strong{before} the first argument.  
 For example,  
3410    
3411  @Example  @Example
3412  .B foo ) (  .B foo ) (
# Line 3397  For example, Line 3414  For example,
3414    
3415  prints (@strong{foo}).  prints (@strong{foo}).
3416    
3417  If you give this macro no arguments, @code{groff}  If you give this macro no arguments, @code{groff} prints all text
3418  prints all text following in bold until  following in bold until the next highlighting, paragraph, or heading
3419  the next highlighting, paragraph, or heading macro.  macro.
3420  @endDefmac  @endDefmac
3421    
3422  @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}  @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3423  Sets its first argument in roman (or regular) type.  Sets its first argument in roman (or regular) type.  It operates
3424  It operates similarly to the @code{B}@tie{}macro otherwise.  similarly to the @code{B}@tie{}macro otherwise.
3425  @endDefmac  @endDefmac
3426    
3427  @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}  @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3428  Sets its first argument in @emph{italic type}.  Sets its first argument in @emph{italic type}.  It operates similarly
3429  It operates similarly to the @code{B}@tie{}macro otherwise.  to the @code{B}@tie{}macro otherwise.
3430  @endDefmac  @endDefmac
3431    
3432  @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}  @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3433  Sets its first argument in a @code{constant width face}.  Sets its first argument in a @code{constant width face}.  It operates
3434  It operates similarly to the @code{B}@tie{}macro otherwise.  similarly to the @code{B}@tie{}macro otherwise.
3435  @endDefmac  @endDefmac
3436    
3437  @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}  @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms}
3438  Sets its first argument in bold italic type.  Sets its first argument in bold italic type.  It operates similarly to
3439  It operates similarly to the @code{B}@tie{}macro otherwise.  the @code{B}@tie{}macro otherwise.
3440  @endDefmac  @endDefmac
3441    
3442  @Defmac {BX, [@Var{txt}], ms}  @Defmac {BX, [@Var{txt}], ms}
3443  Prints its argument and draws a box around it.  Prints its argument and draws a box around it.  If you want to box a
3444  If you want to box a string that contains spaces,  string that contains spaces, use a digit-width space (@code{\0}).
 use a digit-width space (@code{\0}).  
3445  @endDefmac  @endDefmac
3446    
3447  @Defmac {UL, [@Var{txt} [@Var{post}]], ms}  @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
3448  Prints its first argument with an underline.  Prints its first argument with an underline.  If you specify a second
3449  If you specify a second argument, @code{groff}  argument, @code{groff} prints it in the previous font after the
3450  prints it in the previous font after  underlined text, with no intervening space.
 the underlined text, with no intervening space.  
3451  @endDefmac  @endDefmac
3452    
3453  @Defmac {LG, , ms}  @Defmac {LG, , ms}
3454  Prints all text following in larger type  Prints all text following in larger type (two points larger than the
3455  (two points larger than the current point size) until  current point size) until the next font size, highlighting, paragraph,
3456  the next font size, highlighting, paragraph, or heading macro.  or heading macro.  You can specify this macro multiple times to
3457  You can specify this macro multiple times  enlarge the point size as needed.
 to enlarge the point size as needed.  
3458  @endDefmac  @endDefmac
3459    
3460  @Defmac {SM, , ms}  @Defmac {SM, , ms}
3461  Prints all text following in smaller type  Prints all text following in smaller type (two points smaller than the
3462  (two points smaller than the current point size) until  current point size) until the next type size, highlighting, paragraph,
3463  the next type size, highlighting, paragraph, or heading macro.  or heading macro.  You can specify this macro multiple times to reduce
3464  You can specify this macro multiple times  the point size as needed.
 to reduce the point size as needed.  
3465  @endDefmac  @endDefmac
3466    
3467  @Defmac {NL, , ms}  @Defmac {NL, , ms}
3468  Prints all text following in the normal point size  Prints all text following in the normal point size (that is, the value
3469  (that is, the value of the @code{PS} register).  of the @code{PS} register).
3470  @endDefmac  @endDefmac
3471    
3472    @DefstrList {@Lbrace{}, ms}
3473    @DefstrListEnd {@Rbrace{}, ms}
3474    Text enclosed with @code{\*@{} and @code{\*@}} is printed as a
3475    superscript.
3476    @endDefstr
3477    
3478  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
3479    
3480  @node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text  @node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text
3481  @subsubsection Lists  @subsubsection Lists
3482  @cindex @code{ms} macros, lists  @cindex @code{ms} macros, lists
3483    
3484  The @code{.IP} macro handles duties for all lists.  The @code{IP} macro handles duties for all lists.
3485    
3486  @Defmac {IP, [@Var{marker} [@Var{width}]], ms}  @Defmac {IP, [@Var{marker} [@Var{width}]], ms}
3487  The @var{marker} is usually a bullet glyph (@code{\[bu]})  The @var{marker} is usually a bullet glyph (@code{\[bu]}) for
3488  for unordered lists, a number (or auto-incrementing number  unordered lists, a number (or auto-incrementing number register) for
3489  register) for numbered lists, or a word or phrase for indented  numbered lists, or a word or phrase for indented (glossary-style)
3490  (glossary-style) lists.  lists.
3491    
3492  The @var{width} specifies the indent for the body of each list item;  The @var{width} specifies the indentation for the body of each list
3493  its default unit is @samp{n}.  item; its default unit is @samp{n}.  Once specified, the indentation
3494  Once specified, the indent remains the same for all  remains the same for all list items in the document until specified
3495  list items in the document until specified again.  again.
3496    
3497  The @code{PORPHANS} register (@pxref{ms Document Control Registers})  The @code{PORPHANS} register (@pxref{ms Document Control Registers})
3498  operates in conjunction with the @code{IP} macro, to inhibit the  operates in conjunction with the @code{IP} macro, to inhibit the
# Line 3506  o guns Line 3525  o guns
3525  o money  o money
3526  @endExample  @endExample
3527    
 @sp 1  
   
3528  The following is an example of a numbered list.  The following is an example of a numbered list.
3529  @cindex example markup, numbered list [@code{ms}]  @cindex example markup, numbered list [@code{ms}]
3530  @cindex numbered list, example markup [@code{ms}]  @cindex numbered list, example markup [@code{ms}]
# Line 3535  A numbered list: Line 3552  A numbered list:
3552  3. money  3. money
3553  @endExample  @endExample
3554    
3555  Note the use of the auto-incrementing number  Note the use of the auto-incrementing number register in this example.
 register in this example.  
3556    
 @sp 1  
3557  The following is an example of a glossary-style list.  The following is an example of a glossary-style list.
3558  @cindex example markup, glossary-style list [@code{ms}]  @cindex example markup, glossary-style list [@code{ms}]
3559  @cindex glossary-style list, example markup [@code{ms}]  @cindex glossary-style list, example markup [@code{ms}]
# Line 3569  money Line 3584  money
3584        Gotta pay for those lawyers and guns!        Gotta pay for those lawyers and guns!
3585  @endExample  @endExample
3586    
3587  In the last example, the @code{IP} macro places the definition  In the last example, the @code{IP} macro places the definition on the
3588  on the same line as the term if it has enough space; otherwise,  same line as the term if it has enough space; otherwise, it breaks to
3589  it breaks to the next line and starts the definition below the  the next line and starts the definition below the term.  This may or
3590  term.  may not be the effect you want, especially if some of the definitions
3591  This may or may not be the effect you want, especially if some  break and some do not.  The following examples show two possible ways
3592  of the definitions break and some do not.  to force a break.
 The following examples show two possible ways to force a break.  
3593    
3594  The first workaround uses the @code{br}  The first workaround uses the @code{br} request to force a break after
3595  request to force a break after printing the term or label.  printing the term or label.
3596    
3597  @Example  @Example
3598  @cartouche  @cartouche
# Line 3593  Gotta pay for those lawyers and guns! Line 3607  Gotta pay for those lawyers and guns!
3607  @end cartouche  @end cartouche
3608  @endExample  @endExample
3609    
 @sp 1  
3610  The second workaround uses the @code{\p} escape to force the break.  The second workaround uses the @code{\p} escape to force the break.
3611  Note the space following the escape; this is important.  Note the space following the escape; this is important.  If you omit
3612  If you omit the space, @code{groff} prints the first word on  the space, @code{groff} prints the first word on the same line as the
3613  the same line as the term or label (if it fits) @strong{then}  term or label (if it fits) @strong{then} breaks the line.
 breaks the line.  
3614    
3615  @Example  @Example
3616  @cartouche  @cartouche
# Line 3612  Gotta pay for those lawyers and guns! Line 3624  Gotta pay for those lawyers and guns!
3624  @end cartouche  @end cartouche
3625  @endExample  @endExample
3626    
 @sp 1  
3627  To set nested lists, use the @code{RS} and @code{RE} macros.  To set nested lists, use the @code{RS} and @code{RE} macros.
3628  @xref{Indents in ms}, for more information.  @xref{Indentation values in ms}, for more information.
3629  @cindex @code{ms} macros, nested lists  @cindex @code{ms} macros, nested lists
3630  @cindex nested lists [@code{ms}]  @cindex nested lists [@code{ms}]
3631    
# Line 3653  o Guns Line 3664  o Guns
3664    
3665  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
3666    
3667  @node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text  @node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text
3668  @subsubsection Indents  @subsubsection Indentation values
3669    
3670  In many situations,  In many situations, you may need to indentation a section of text
3671  you may need to indent a section of text  while still wrapping and filling.  @xref{Lists in ms}, for an example
3672  while still wrapping and filling.  of nested lists.
 @xref{Lists in ms},  
 for an example of nested lists.  
3673    
3674  @DefmacList {RS, , ms}  @DefmacList {RS, , ms}
3675  @DefmacListEnd {RE, , ms}  @DefmacListEnd {RE, , ms}
3676  These macros begin and end an indented section.  These macros begin and end an indented section.  The @code{PI}
3677  The @code{PI} register controls the amount of indent,  register controls the amount of indentation, allowing the indented
3678  allowing the indented text to line up under hanging  text to line up under hanging and indented paragraphs.
 and indented paragraphs.  
3679  @endDefmac  @endDefmac
3680    
3681  @xref{ms Displays and Keeps},  @xref{ms Displays and Keeps}, for macros to indentation and turn off
3682  for macros to indent and turn off filling.  filling.
3683    
3684  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
3685    
3686  @node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text  @node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body Text
3687  @subsubsection Tab Stops  @subsubsection Tab Stops
3688    
3689  Use the @code{ta} request to define tab stops as needed.  Use the @code{ta} request to define tab stops as needed.  @xref{Tabs
3690  @xref{Tabs and Fields}.  and Fields}.
3691    
3692  @Defmac{TA, , ms}  @Defmac{TA, , ms}
3693  Use this macro to reset the tab stops to the default for @file{ms}  Use this macro to reset the tab stops to the default for @file{ms}
3694  (every 5n).  (every 5n).  You can redefine the @code{TA} macro to create a
3695  You can redefine the @code{TA} macro to create a different set  different set of default tab stops.
 of default tab stops.  
3696  @endDefmac  @endDefmac
3697    
3698  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
# Line 3697  of default tab stops. Line 3704  of default tab stops.
3704  @cindex keeps [@code{ms}]  @cindex keeps [@code{ms}]
3705  @cindex displays [@code{ms}]  @cindex displays [@code{ms}]
3706    
3707  Use displays to show text-based examples or figures  Use displays to show text-based examples or figures (such as code
3708  (such as code listings).  listings).
3709    
3710  Displays turn off filling, so lines of code are displayed  Displays turn off filling, so lines of code are displayed as-is
3711  as-is without inserting @code{br} requests in between each line.  without inserting @code{br} requests in between each line.  Displays
3712  Displays can be @dfn{kept} on a single page, or allowed  can be @dfn{kept} on a single page, or allowed to break across pages.
 to break across pages.  
3713    
3714  @DefmacList {DS, @t{L}, ms}  @DefmacList {DS, @t{L}, ms}
3715  @DefmacItem {LD, , ms}  @DefmacItem {LD, , ms}
3716  @DefmacListEnd {DE, , ms}  @DefmacListEnd {DE, , ms}
3717  Left-justified display.  Left-justified display.  The @samp{.DS L} call generates a page break,
3718  The @samp{.DS L} call generates a page break, if necessary,  if necessary, to keep the entire display on one page.  The @code{LD}
3719  to keep the entire display on one page.  macro allows the display to break across pages.  The @code{DE} macro
3720  The @code{LD} macro allows the display to break across pages.  ends the display.
 The @code{DE} macro ends the display.  
3721  @endDefmac  @endDefmac
3722    
3723  @DefmacList {DS, @t{I}, ms}  @DefmacList {DS, @t{I}, ms}
3724  @DefmacItem {ID, , ms}  @DefmacItem {ID, , ms}
3725  @DefmacListEnd {DE, , ms}  @DefmacListEnd {DE, , ms}
3726  Indents the display as defined by the @code{DI} register.  Indents the display as defined by the @code{DI} register.  The
3727  The @samp{.DS I} call generates a page break, if necessary,  @samp{.DS I} call generates a page break, if necessary, to keep the
3728  to keep the entire display on one page.  entire display on one page.  The @code{ID} macro allows the display to
3729  The @code{ID} macro allows the display to break across pages.  break across pages.  The @code{DE} macro ends the display.
 The @code{DE} macro ends the display.  
3730  @endDefmac  @endDefmac
3731    
3732  @DefmacList {DS, @t{B}, ms}  @DefmacList {DS, @t{B}, ms}
3733  @DefmacItem {BD, , ms}  @DefmacItem {BD, , ms}
3734  @DefmacListEnd {DE, , ms}  @DefmacListEnd {DE, , ms}
3735  Sets a block-centered display: the entire display is left-justified,  Sets a block-centered display: the entire display is left-justified,
3736  but indented so that the longest line in the display is centered  but indented so that the longest line in the display is centered on
3737  on the page.  the page.  The @samp{.DS B} call generates a page break, if necessary,
3738  The @samp{.DS B} call generates a page break, if necessary,  to keep the entire display on one page.  The @code{BD} macro allows
3739  to keep the entire display on one page.  the display to break across pages.  The @code{DE} macro ends the
3740  The @code{BD} macro allows the display to break across pages.  display.
 The @code{DE} macro ends the display.  
3741  @endDefmac  @endDefmac
3742    
3743  @DefmacList {DS, @t{C}, ms}  @DefmacList {DS, @t{C}, ms}
3744  @DefmacItem {CD, , ms}  @DefmacItem {CD, , ms}
3745  @DefmacListEnd {DE, , ms}  @DefmacListEnd {DE, , ms}
3746  Sets a centered display: each line in the display is centered.  Sets a centered display: each line in the display is centered.  The
3747  The @samp{.DS C} call generates a page break, if necessary,  @samp{.DS C} call generates a page break, if necessary, to keep the
3748  to keep the entire display on one page.  entire display on one page.  The @code{CD} macro allows the display to
3749  The @code{CD} macro allows the display to break across pages.  break across pages.  The @code{DE} macro ends the display.
 The @code{DE} macro ends the display.  
3750  @endDefmac  @endDefmac
3751    
3752  @DefmacList {DS, @t{R}, ms}  @DefmacList {DS, @t{R}, ms}
3753  @DefmacItem {RD, , ms}  @DefmacItem {RD, , ms}
3754  @DefmacListEnd {DE, , ms}  @DefmacListEnd {DE, , ms}
3755  Right-justifies each line in the display.  Right-justifies each line in the display.  The @samp{.DS R} call
3756  The @samp{.DS R} call generates a page break, if necessary,  generates a page break, if necessary, to keep the entire display on
3757  to keep the entire display on one page.  one page.  The @code{RD} macro allows the display to break across
3758  The @code{RD} macro allows the display to break across pages.  pages.  The @code{DE} macro ends the display.
 The @code{DE} macro ends the display.  
3759  @endDefmac  @endDefmac
3760    
3761  @DefmacList {Ds, , ms}  @DefmacList {Ds, , ms}
3762  @DefmacListEnd {De, , ms}  @DefmacListEnd {De, , ms}
3763  These two macros were formerly provided as aliases for  These two macros were formerly provided as aliases for @code{DS} and
3764  @code{DS} and @code{DE}, respectively.  @code{DE}, respectively.  They have been removed, and should no longer
3765  They have been removed, and should no longer be used.  be used.  The original implementations of @code{DS} and @code{DE} are
3766  The original implementations of @code{DS} and @code{DE}  retained, and should be used instead.  X11 documents which actually
3767  are retained, and should be used instead.  use @code{Ds} and @code{De} always load a specific macro file from the
3768  X11 documents which actually use @code{Ds} and @code{De} always load a  X11 distribution (@file{macros.t}) which provides proper definitions
3769  specific macro file from the X11 distribution (@file{macros.t}) which  for the two macros.
 provides proper definitions for the two macros.  
3770  @endDefmac  @endDefmac
3771    
 @sp 1  
3772  On occasion, you may want to @dfn{keep} other text together on a page.  On occasion, you may want to @dfn{keep} other text together on a page.
3773  For example, you may want to keep two paragraphs together, or  For example, you may want to keep two paragraphs together, or a
3774  a paragraph that refers to a table (or list, or other item)  paragraph that refers to a table (or list, or other item) immediately
3775  immediately following.  following.  The @file{ms} macros provide the @code{KS} and @code{KE}
 The @file{ms} macros provide the @code{KS} and @code{KE}  
3776  macros for this purpose.  macros for this purpose.
3777    
3778  @DefmacList {KS, , ms}  @DefmacList {KS, , ms}
3779  @DefmacListEnd {KE, , ms}  @DefmacListEnd {KE, , ms}
3780  The @code{KS} macro begins a block of text to be kept on a  The @code{KS} macro begins a block of text to be kept on a single
3781  single page, and the @code{KE} macro ends the block.  page, and the @code{KE} macro ends the block.
3782  @endDefmac  @endDefmac
3783    
3784  @DefmacList {KF, , ms}  @DefmacList {KF, , ms}
3785  @DefmacListEnd {KE, , ms}  @DefmacListEnd {KE, , ms}
3786  Specifies a @dfn{floating keep};  Specifies a @dfn{floating keep}; if the keep cannot fit on the current
3787  if the keep cannot fit on the current page, @code{groff}  page, @code{groff} holds the contents of the keep and allows text
3788  holds the contents of the keep and allows text following  following the keep (in the source file) to fill in the remainder of
3789  the keep (in the source file) to fill in the remainder of  the current page.  When the page breaks, whether by an explicit
3790  the current page.  @code{bp} request or by reaching the end of the page, @code{groff}
3791  When the page breaks, whether by an explicit @code{bp}  prints the floating keep at the top of the new page.  This is useful
3792  request or by reaching the end of the page, @code{groff}  for printing large graphics or tables that do not need to appear
3793  prints the floating keep at the top of the new page.  exactly where specified.
3794  This is useful for printing large graphics or tables  @endDefmac
3795  that do not need to appear exactly where specified.  
3796  @endDefmac  You can also use the @code{ne} request to force a page break if there
3797    is not enough vertical space remaining on the page.
3798  You can also use the @code{ne} request to force a page break if  
3799  there is not enough vertical space remaining on the page.  Use the following macros to draw a box around a section of text (such
3800    as a display).
 @sp 1  
 Use the following macros to draw a box around a section of  
 text (such as a display).  
3801    
3802  @DefmacList {B1, , ms}  @DefmacList {B1, , ms}
3803  @DefmacListEnd {B2, , ms}  @DefmacListEnd {B2, , ms}
3804  Marks the beginning and ending of text that is to have a  Marks the beginning and ending of text that is to have a box drawn
3805  box drawn around it.  around it.  The @code{B1} macro begins the box; the @code{B2} macro
3806  The @code{B1} macro begins the box; the @code{B2} macro ends it.  ends it.  Text in the box is automatically placed in a diversion
3807  Text in the box is automatically placed in a diversion (keep).  (keep).
3808  @endDefmac  @endDefmac
3809    
3810  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
# Line 3825  Text in the box is automatically placed Line 3820  Text in the box is automatically placed
3820  @cindex equations [@code{ms}]  @cindex equations [@code{ms}]
3821  @cindex references [@code{ms}]  @cindex references [@code{ms}]
3822    
3823  The @file{ms} macros support the standard  The @file{ms} macros support the standard @code{groff} preprocessors:
 @code{groff} preprocessors:  
3824  @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.  @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}.
3825  @pindex tbl  @pindex tbl
3826  @pindex pic  @pindex pic
# Line 3837  in pairs of tags as follows. Line 3831  in pairs of tags as follows.
3831    
3832  @DefmacList {TS, [@code{H}], ms}  @DefmacList {TS, [@code{H}], ms}
3833  @DefmacListEnd {TE, , ms}  @DefmacListEnd {TE, , ms}
3834  Denotes a table, to be processed by the @code{tbl} preprocessor.  Denotes a table, to be processed by the @code{tbl} preprocessor.  The
3835  The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff}  optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to
3836  to create a running header with the information  create a running header with the information up to the @code{TH}
3837  up to the @code{TH} macro.  macro.  @code{groff} prints the header at the beginning of the table;
3838  @code{groff} prints the header at the beginning of the  if the table runs onto another page, @code{groff} prints the header on
3839  table; if the table runs onto another page, @code{groff}  the next page as well.
 prints the header on the next page as well.  
3840  @endDefmac  @endDefmac
3841    
3842  @DefmacList {PS, , ms}  @DefmacList {PS, , ms}
3843  @DefmacListEnd {PE, , ms}  @DefmacListEnd {PE, , ms}
3844  Denotes a graphic, to be processed by the @code{pic} preprocessor.  Denotes a graphic, to be processed by the @code{pic} preprocessor.
3845  You can create a @code{pic} file by hand, using the @acronym{AT&T}  You can create a @code{pic} file by hand, using the @acronym{AT&T}
3846  @code{pic} manual available on the Web as a reference, or by using  @code{pic} manual available on the Web as a reference, or by using a
3847  a graphics program such as @code{xfig}.  graphics program such as @code{xfig}.
3848  @endDefmac  @endDefmac
3849    
3850  @DefmacList {EQ, [@Var{align}], ms}  @DefmacList {EQ, [@Var{align}], ms}
# Line 3881  database. Line 3874  database.
3874  @cindex example markup, multi-page table [@code{ms}]  @cindex example markup, multi-page table [@code{ms}]
3875  @cindex multi-page table, example markup [@code{ms}]  @cindex multi-page table, example markup [@code{ms}]
3876    
3877  The following is an example of how to set up a  The following is an example of how to set up a table that may print
3878  table that may print across two or more pages.  across two or more pages.
3879    
3880  @Example  @Example
3881  @cartouche  @cartouche
# Line 3907  l | l . Line 3900  l | l .
3900  @cindex @code{ms} macros, footnotes  @cindex @code{ms} macros, footnotes
3901  @cindex footnotes [@code{ms}]  @cindex footnotes [@code{ms}]
3902    
3903  The @file{ms} macro package has a flexible footnote system.  The @file{ms} macro package has a flexible footnote system.  You can
3904  You can specify either numbered footnotes or symbolic footnotes  specify either numbered footnotes or symbolic footnotes (that is,
3905  (that is, using a marker such as a dagger symbol).  using a marker such as a dagger symbol).
3906    
3907  @Defstr {*, ms}  @Defstr {*, ms}
3908  Specifies the location of a numbered footnote marker in the text.  Specifies the location of a numbered footnote marker in the text.
# Line 3917  Specifies the location of a numbered foo Line 3910  Specifies the location of a numbered foo
3910    
3911  @DefmacList {FS, , ms}  @DefmacList {FS, , ms}
3912  @DefmacListEnd {FE, , ms}  @DefmacListEnd {FE, , ms}
3913  Specifies the text of the footnote.  Specifies the text of the footnote.  The default action is to create a
3914  The default action is to create a numbered footnote;  numbered footnote; you can create a symbolic footnote by specifying a
3915  you can create a symbolic footnote by specifying  @dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the
3916  a @dfn{mark} glyph  body text and as an argument to the @code{FS} macro, followed by the
3917  (such as @code{\[dg]} for the dagger glyph)  text of the footnote and the @code{FE} macro.
3918  in the body text and as an argument to the @code{FS} macro,  @endDefmac
3919  followed by the text of the footnote  
3920  and the @code{FE} macro.  You can control how @code{groff} prints footnote numbers by changing
3921  @endDefmac  the value of the @code{FF} register.  @xref{ms Document Control
3922    Registers}.
3923  You can control how @code{groff}  
3924  prints footnote numbers by changing the value of the  @cindex footnotes, and keeps [@code{ms}]
3925  @code{FF} register.  @xref{ms Document Control Registers}.  @cindex keeps, and footnotes [@code{ms}]
3926    @cindex footnotes, and displays [@code{ms}]
3927    @cindex displays, and footnotes [@code{ms}]
3928    Footnotes can be safely used within keeps and displays, but you should
3929    avoid using numbered footnotes within floating keeps.  You can set a
3930    second @code{\**} marker between a @code{\**} and its corresponding
3931    @code{.FS} entry; as long as each @code{FS} macro occurs @emph{after}
3932    the corresponding @code{\**} and the occurrences of @code{.FS} are in
3933    the same order as the corresponding occurrences of @code{\**}.
3934    
3935  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
3936    
# Line 3938  prints footnote numbers by changing the Line 3939  prints footnote numbers by changing the
3939  @cindex @code{ms} macros, page layout  @cindex @code{ms} macros, page layout
3940  @cindex page layout [@code{ms}]  @cindex page layout [@code{ms}]
3941    
3942  The default output from the @file{ms}  The default output from the @file{ms} macros provides a minimalist
3943  macros provides a minimalist page layout:  page layout: it prints a single column, with the page number centered
3944  it prints a single column, with the page number centered at the top  at the top of each page.  It prints no footers.
 of each page.  
 It prints no footers.  
3945    
3946  You can change the layout by setting  You can change the layout by setting the proper number registers and
3947  the proper number registers and strings.  strings.
3948    
3949  @menu  @menu
3950  * ms Headers and Footers::  * ms Headers and Footers::
# Line 3964  the proper number registers and strings. Line 3963  the proper number registers and strings.
3963  @cindex headers [@code{ms}]  @cindex headers [@code{ms}]
3964  @cindex footers [@code{ms}]  @cindex footers [@code{ms}]
3965    
3966  For documents that do not distinguish between odd and even pages,  For documents that do not distinguish between odd and even pages, set
3967  set the following strings:  the following strings:
3968    
3969  @DefstrList {LH, ms}  @DefstrList {LH, ms}
3970  @DefstrItem {CH, ms}  @DefstrItem {CH, ms}
# Line 3979  Sets the left, center, and right headers Line 3978  Sets the left, center, and right headers
3978  Sets the left, center, and right footers.  Sets the left, center, and right footers.
3979  @endDefstr  @endDefstr
3980    
3981  @sp 1  For documents that need different information printed in the even and
3982  For documents that need different information printed in the  odd pages, use the following macros:
 even and odd pages, use the following macros:  
3983    
3984  @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}  @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3985  @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}  @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3986  @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}  @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3987  @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}  @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms}
3988  The @code{OH} and @code{EH} macros define headers for the odd and even pages;  The @code{OH} and @code{EH} macros define headers for the odd and even
3989  the @code{OF} and @code{EF} macros define footers for the odd and even pages.  pages; the @code{OF} and @code{EF} macros define footers for the odd
3990  This is more flexible than defining the individual strings.  and even pages.  This is more flexible than defining the individual
3991    strings.
3992    
3993  You can replace the quote (@code{'}) marks with any character not  You can replace the quote (@code{'}) marks with any character not
3994  appearing in the header or footer text.  appearing in the header or footer text.
# Line 4001  appearing in the header or footer text. Line 4000  appearing in the header or footer text.
4000  @subsubsection Margins  @subsubsection Margins
4001  @cindex @code{ms} macros, margins  @cindex @code{ms} macros, margins
4002    
4003  You control margins using a set of number registers.  You control margins using a set of number registers.  @xref{ms
4004  @xref{ms Document Control Registers}, for details.  Document Control Registers}, for details.
4005    
4006  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
4007    
# Line 4012  You control margins using a set of numbe Line 4011  You control margins using a set of numbe
4011  @cindex multiple columns [@code{ms}]  @cindex multiple columns [@code{ms}]
4012    
4013  The @file{ms} macros can set text in as many columns as will  The @file{ms} macros can set text in as many columns as will
4014  reasonably fit on the page.  reasonably fit on the page.  The following macros are available; all
4015  The following macros are available;  of them force a page break if a multi-column mode is already set.
 all of them force a page break if a multi-column mode is already set.  
4016  However, if the current mode is single-column, starting a multi-column  However, if the current mode is single-column, starting a multi-column
4017  mode does @strong{not} force a page break.  mode does @emph{not} force a page break.
4018    
4019  @Defmac {1C, , ms}  @Defmac {1C, , ms}
4020  Single-column mode.  Single-column mode.
# Line 4027  Two-column mode. Line 4025  Two-column mode.
4025  @endDefmac  @endDefmac
4026    
4027  @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}  @Defmac {MC, [@Var{width} [@Var{gutter}]], ms}
4028  Multi-column mode.  Multi-column mode.  If you specify no arguments, it is equivalent to
4029  If you specify no arguments, it is equivalent to the  the @code{2C} macro.  Otherwise, @var{width} is the width of each
4030  @code{2C} macro.  column and @var{gutter} is the space between columns.  The
4031  Otherwise, @var{width} is the width of each column and  @code{MINGW} number register controls the default gutter width.
 @var{gutter} is the space between columns.  
 The @code{MINGW} number register controls the default gutter width.  
4032  @endDefmac  @endDefmac
4033    
4034  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
# Line 4042  The @code{MINGW} number register control Line 4038  The @code{MINGW} number register control
4038  @cindex @code{ms} macros, creating table of contents  @cindex @code{ms} macros, creating table of contents
4039  @cindex table of contents, creating [@code{ms}]  @cindex table of contents, creating [@code{ms}]
4040    
4041  The facilities in the @file{ms} macro package for creating  The facilities in the @file{ms} macro package for creating a table of
4042  a table of contents are semi-automated at best.  contents are semi-automated at best.  Assuming that you want the table
4043  Assuming that you want the table of contents to consist of  of contents to consist of the document's headings, you need to repeat
4044  the document's headings, you need to repeat those headings  those headings wrapped in @code{XS} and @code{XE} macros.
 wrapped in @code{XS} and @code{XE} macros.  
4045    
4046  @DefmacList {XS, [@Var{page}], ms}  @DefmacList {XS, [@Var{page}], ms}
4047  @DefmacItem {XA, [@Var{page}], ms}  @DefmacItem {XA, [@Var{page}], ms}
4048  @DefmacListEnd {XE, , ms}  @DefmacListEnd {XE, , ms}
4049  These macros define a table of contents  These macros define a table of contents or an individual entry in the
4050  or an individual entry in the table of contents,  table of contents, depending on their use.  The macros are very
4051  depending on their use.  simple; they cannot indent a heading based on its level.  The easiest
4052  The macros are very simple; they cannot indent a heading based on its level.  way to work around this is to add tabs to the table of contents
4053  The easiest way to work around this is to add tabs  string.  The following is an example:
 to the table of contents string.  
 The following is an example:  
4054    
4055  @Example  @Example
4056  @cartouche  @cartouche
# Line 4079  Methodology Line 4072  Methodology
4072  @end cartouche  @end cartouche
4073  @endExample  @endExample
4074    
4075  You can manually create a table of contents  You can manually create a table of contents by beginning with the
4076  by beginning with the @code{XS} macro for the first entry,  @code{XS} macro for the first entry, specifying the page number for
4077  specifying the page number for that entry as the argument to @code{XS}.  that entry as the argument to @code{XS}.  Add subsequent entries using
4078  Add subsequent entries using the @code{XA} macro,  the @code{XA} macro, specifying the page number for that entry as the
4079  specifying the page number for that entry as the argument to @code{XA}.  argument to @code{XA}.  The following is an example:
 The following is an example:  
4080    
4081  @Example  @Example
4082  @cartouche  @cartouche
# Line 4101  Details of Galactic Formation Line 4093  Details of Galactic Formation
4093  @endDefmac  @endDefmac
4094    
4095  @Defmac {TC, [@code{no}], ms}  @Defmac {TC, [@code{no}], ms}
4096  Prints the table of contents on a new page,  Prints the table of contents on a new page, setting the page number
4097  setting the page number to@tie{}@strong{i} (Roman numeral one).  to@tie{}@strong{i} (Roman lowercase numeral one).  You should usually
4098  You should usually place this macro at the end of the  place this macro at the end of the file, since @code{groff} is a
4099  file, since @code{groff} is a single-pass formatter and  single-pass formatter and can only print what has been collected up to
4100  can only print what has been collected up to the point  the point that the @code{TC} macro appears.
 that the @code{TC} macro appears.  
4101    
4102  The optional argument @code{no} suppresses printing  The optional argument @code{no} suppresses printing the title
4103  the title specified by the string register @code{TOC}.  specified by the string register @code{TOC}.
4104  @endDefmac  @endDefmac
4105    
4106  @Defmac{PX, [@code{no}], ms}  @Defmac{PX, [@code{no}], ms}
4107  Prints the table of contents on a new page,  Prints the table of contents on a new page, using the current page
4108  using the current page numbering sequence.  numbering sequence.  Use this macro to print a manually-generated
4109  Use this macro to print a manually-generated table of contents  table of contents at the beginning of your document.
4110  at the beginning of your document.  
4111    The optional argument @code{no} suppresses printing the title
4112  The optional argument @code{no} suppresses printing  specified by the string register @code{TOC}.
4113  the title specified by the string register @code{TOC}.  @endDefmac
4114  @endDefmac  
4115    The @cite{Groff and Friends HOWTO} includes a @code{sed} script that
4116  The @cite{Groff and Friends HOWTO}  automatically inserts @code{XS} and @code{XE} macro entries after each
4117  includes a @code{sed} script that automatically inserts  heading in a document.
4118  @code{XS} and @code{XE} macro entries after each heading in a document.  
4119    Altering the @code{NH} macro to automatically build the table of
4120  Altering the @code{NH} macro to automatically build the table  contents is perhaps initially more difficult, but would save a great
4121  of contents is perhaps initially more difficult, but would save  deal of time in the long run if you use @file{ms} regularly.
 a great deal of time in the long run if you use @file{ms} regularly.  
4122    
4123  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
4124    
# Line 4141  a great deal of time in the long run if Line 4131  a great deal of time in the long run if
4131  @cindex special characters [@code{ms}]  @cindex special characters [@code{ms}]
4132  @cindex strings [@code{ms}]  @cindex strings [@code{ms}]
4133    
4134  The @file{ms} macros provide the following predefined strings.  The @file{ms} macros provide the following predefined strings.  You
4135  You can change the string definitions to help in creating  can change the string definitions to help in creating documents in
4136  documents in languages other than English.  languages other than English.
4137    
4138  @Defstr {REFERENCES, ms}  @Defstr {REFERENCES, ms}
4139  Contains the string printed at the beginning of the  Contains the string printed at the beginning of the references
4140  references (bibliography) page.  (bibliography) page.  The default is @samp{References}.
 The default is @samp{References}.  
4141  @endDefstr  @endDefstr
4142    
4143  @Defstr {ABSTRACT, ms}  @Defstr {ABSTRACT, ms}
4144  Contains the string printed at the beginning of the abstract.  Contains the string printed at the beginning of the abstract.  The
4145  The default is @samp{ABSTRACT}.  default is @samp{ABSTRACT}.
4146  @endDefstr  @endDefstr
4147    
4148  @Defstr {TOC, ms}  @Defstr {TOC, ms}
# Line 4172  Contains the string printed at the begin Line 4161  Contains the string printed at the begin
4161  @DefstrItem {MONTH10, ms}  @DefstrItem {MONTH10, ms}
4162  @DefstrItem {MONTH11, ms}  @DefstrItem {MONTH11, ms}
4163  @DefstrListEnd {MONTH12, ms}  @DefstrListEnd {MONTH12, ms}
4164  Prints the full name of the month in dates.  Prints the full name of the month in dates.  The default is
4165  The default is @samp{January}, @samp{February}, etc.  @samp{January}, @samp{February}, etc.
4166  @endDefstr  @endDefstr
4167    
4168  The following special characters are available@footnote{For an  The following special characters are available@footnote{For an
4169  explanation what special characters are see @ref{Special Characters}.}:  explanation what special characters are see @ref{Special
4170    Characters}.}:
4171    
4172  @Defstr {-, ms}  @Defstr {-, ms}
4173  Prints an em dash.  Prints an em dash.
4174  @endDefstr  @endDefstr
4175    
4176  @DefstrList {*Q, ms}  @DefstrList {Q, ms}
4177  @DefstrListEnd {*U, ms}  @DefstrListEnd {U, ms}
4178  Prints typographer's quotes in troff,  Prints typographer's quotes in troff, and plain quotes in nroff.
4179  plain quotes in nroff.  @code{\*Q} is the left quote and @code{\*U} is the right quote.
 @code{*Q} is the left quote and @code{*U} is the right quote.  
4180  @endDefstr  @endDefstr
4181    
4182  Improved accent marks are available in the @file{ms} macros.  Improved accent marks are available in the @file{ms} macros.
4183    
4184  @Defmac {AM, , ms}  @Defmac {AM, , ms}
4185  Specify this macro at the beginning of your document  Specify this macro at the beginning of your document to enable
4186  to enable extended accent marks and special characters.  extended accent marks and special characters.  This is a Berkeley
4187  This is a Berkeley extension.  extension.
4188    
4189    To use the accent marks, place them @strong{after} the character being
4190    accented.
4191    
4192  To use the accent marks, place them @strong{after}  Note that groff's native support for accents is superior to the
4193  the character being accented.  following definitions.
4194  @endDefmac  @endDefmac
4195    
4196  The following accent marks are available  The following accent marks are available after invoking the @code{AM}
4197  after invoking the @code{AM} macro:  macro:
4198    
4199  @Defstr {\', ms}  @Defstr {\', ms}
4200  Acute accent.  Acute accent.
# Line 4250  Underdot. Line 4242  Underdot.
4242  Ring above.  Ring above.
4243  @endDefstr  @endDefstr
4244    
4245  The following are standalone characters  The following are standalone characters available after invoking the
4246  available after invoking the @code{AM} macro:  @code{AM} macro:
4247    
4248  @Defstr {?, ms}  @Defstr {?, ms}
4249  Upside-down question mark.  Upside-down question mark.
# Line 4299  Uppercase Æ ligature. Line 4291  Uppercase Æ ligature.
4291    
4292  @c ---------------------------------------------------------------------  @c ---------------------------------------------------------------------
4293    
4294  @node Differences from AT&T ms,  , ms Page Layout, ms  @node Differences from AT&T ms, Naming Conventions, ms Page Layout, ms
4295  @subsection Differences from @acronym{AT&T} @file{ms}  @subsection Differences from @acronym{AT&T} @file{ms}
4296  @cindex @code{ms} macros, differences from @acronym{AT&T}  @cindex @code{ms} macros, differences from @acronym{AT&T}
4297  @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences  @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences
4298    
4299  This section lists the (minor) differences between the  This section lists the (minor) differences between the @code{groff
4300  @code{groff -ms} macros and @acronym{AT&T}  -ms} macros and @acronym{AT&T} @code{troff -ms} macros.
4301  @code{troff -ms} macros.  
4302    @itemize @bullet
4303    @item
4304    The internals of @code{groff -ms} differ from the internals of
4305    @acronym{AT&T} @code{troff -ms}.  Documents that depend upon
4306    implementation details of @acronym{AT&T} @code{troff -ms} may not
4307    format properly with @code{groff -ms}.
4308    
4309    @item
4310    The general error-handling policy of @code{groff -ms} is to detect and
4311    report errors, rather than silently to ignore them.
4312    
4313    @item
4314    @code{groff -ms} does not work in compatibility mode (this is, with
4315    the @option{-C} option).
4316    
4317    @item
4318    There is no special support for typewriter-like devices.
4319    
4320    @item
4321    @code{groff -ms} does not provide cut marks.
4322    
4323    @item
4324    Multiple line spacing is not supported.  Use a larger vertical spacing
4325    instead.
4326    
4327    @item
4328    Some @acronym{UNIX} @code{ms} documentation says that the @code{CW}
4329    and @code{GW} number registers can be used to control the column width
4330    and gutter width, respectively.  These number registers are not used in
4331    @code{groff -ms}.
4332    
4333    @item
4334    Macros that cause a reset (paragraphs, headings, etc.@:) may change
4335    the indentation.  Macros that change the indentation do not increment
4336    or decrement the indentation, but rather set it absolutely.  This can
4337    cause problems for documents that define additional macros of their
4338    own.  The solution is to use not the @code{in} request but instead the
4339    @code{RS} and @code{RE} macros.
4340    
4341    @item
4342    To make @code{groff -ms} use the default page offset (which also
4343    specifies the left margin), the @code{PO} register must stay undefined
4344    until the first @file{-ms} macro is evaluated.  This implies that
4345    @code{PO} should not be used early in the document, unless it is
4346    changed also: Remember that accessing an undefined register
4347    automatically defines it.
4348    @end itemize
4349    
4350    @Defmpreg {GS, ms}
4351    This number register is set to@tie{}1 by the @code{groff -ms} macros,
4352    but it is not used by the @code{AT&T} @code{troff -ms} macros.
4353    Documents that need to determine whether they are being formatted with
4354    @code{AT&T} @code{troff -ms} or @code{groff -ms} should use this
4355    number register.
4356    @endDefmpreg
4357    
4358  @menu  @menu
4359  * Missing ms Macros::  * Missing ms Macros::
# Line 4318  This section lists the (minor) differenc Line 4365  This section lists the (minor) differenc
4365  @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms  @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms
4366  @subsubsection @code{troff} macros not appearing in @code{groff}  @subsubsection @code{troff} macros not appearing in @code{groff}
4367    
4368  Macros missing from @code{groff -ms}  Macros missing from @code{groff -ms} are cover page macros specific to
4369  are cover page macros specific to Bell Labs.  Bell Labs and Berkeley.  The macros known to be missing are:
 The macros known to be missing are:  
4370    
4371  @table @code  @table @code
4372  @item .TM  @item .TM
# Line 4381  You can write a script to capture and pr Line 4427  You can write a script to capture and pr
4427  generated in this manner.  generated in this manner.
4428  @endDefmac  @endDefmac
4429    
 @sp 1  
4430  The following additional number registers  The following additional number registers
4431  appear in @code{groff -ms}:  appear in @code{groff -ms}:
4432    
# Line 4392  place of the @code{GW} register that was Line 4437  place of the @code{GW} register that was
4437  not implemented in @acronym{AT&T} @code{troff}.  not implemented in @acronym{AT&T} @code{troff}.
4438  @endDefmpreg  @endDefmpreg
4439    
 @sp 1  
4440  Several new string registers are available as well.  Several new string registers are available as well.
4441  You can change these to handle (for example) the local language.  You can change these to handle (for example) the local language.
4442  @xref{ms Strings and Special Characters}, for details.  @xref{ms Strings and Special Characters}, for details.
4443    
4444    @c ---------------------------------------------------------------------
4445    
4446    @node Naming Conventions,  , Differences from AT&T ms, ms
4447    @subsection Naming Conventions
4448    @cindex @code{ms} macros, naming conventions
4449    @cindex naming conventions, @code{ms} macros
4450    
4451    The following conventions are used for names of macros, strings and
4452    number registers.  External names available to documents that use the
4453    @code{groff -ms} macros contain only uppercase letters and digits.
4454    
4455    Internally the macros are divided into modules; naming conventions are
4456    as follows:
4457    
4458    @itemize @bullet
4459    @item
4460    Names used only within one module are of the form
4461    @var{module}@code{*}@var{name}.
4462    
4463    @item
4464    Names used outside the module in which they are defined are of the
4465    form @var{module}@code{@@}@var{name}.
4466    
4467    @item
4468    Names associated with a particular environment are of the form
4469    @var{environment}@code{:}@var{name}; these are used only within the
4470    @code{par} module.
4471    
4472    @item
4473    @var{name} does not have a module prefix.
4474    
4475    @item
4476    Constructed names used to implement arrays are of the form
4477    @var{array}@code{!}@var{index}.
4478    @end itemize
4479    
4480    Thus the groff ms macros reserve the following names:
4481    
4482    @itemize @bullet
4483    @item
4484    Names containing the characters @code{*}, @code{@@},
4485    and@tie{}@code{:}.
4486    
4487    @item
4488    Names containing only uppercase letters and digits.
4489    @end itemize
4490    
4491    
4492  @c =====================================================================  @c =====================================================================
4493    
# Line 7988  If a negative indentation value is speci Line 8079  If a negative indentation value is speci
8079  @code{gtroff} emits a warning of type @samp{range} and sets the  @code{gtroff} emits a warning of type @samp{range} and sets the
8080  indentation to zero.  indentation to zero.
8081    
8082  The effect of @code{in} is delayed until a partially collected line (if  The effect of @code{in} is delayed until a partially collected line
8083  it exists) is output.  A temporary indent value is reset to zero also.  (if it exists) is output.  A temporary indentation value is reset to
8084    zero also.
8085    
8086  The current indentation (as set by @code{in}) can be found in the  The current indentation (as set by @code{in}) can be found in the
8087  read-only number register @samp{.i}.  read-only number register @samp{.i}.
# Line 12340  The number of lines still to center, or Line 12432  The number of lines still to center, or
12432  (with or without underlined spaces); they are set to zero.  (with or without underlined spaces); they are set to zero.
12433    
12434  @item  @item
12435  The status whether a temporary indent is active.  The status whether a temporary indentation is active.
12436    
12437  @item  @item
12438  Input traps and its associated data.  Input traps and its associated data.

Legend:
Removed from v.1.221  
changed lines
  Added in v.1.222

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26