Groff ms manual

Implies -k. Search dir for subdirectories dev name name is the name of the device , for the DESC file, and for font files before looking in the standard directories see Font Directories. This option may be used to specify a directory to search for files. It is passed to the following programs:. The current directory is always searched first. This option may be specified more than once; the directories are searched in the order specified.

No directory search is performed for files specified using an absolute path. Preprocess with preconv. This is run before any other preprocessor. Send the output to a spooler for printing. The command used for this is specified by the print command in the device description file see Font Files , for more info.

If not present, -l is ignored. Pass arg to the spooler. Each argument should be passed with a separate -L option. If the print keyword in the device description file is missing, -L is ignored. Read in the file name. Normally groff searches for this in its macro directories. Search directory dir for macro files before the standard directories see Macro Directories. This is the same as the -N option in geqn.

All the ranges are inclusive on both ends. If your document restarts page numbering at the beginning of each chapter, then gtroff prints the specified page range for each chapter. Pass arg to the postprocessor. Each argument should be passed with a separate -P option. Set number register c or name to the value n. All register assignments happen before loading any macro file including the start-up file. Preprocess with grefer. No mechanism is provided for passing arguments to grefer because most grefer options have equivalent commands that can be included in the file.

See grefer , for more details. Note that gtroff also accepts a -R option, which is not accessible via groff. This option prevents the loading of the troffrc and troffrc-end files. Safer mode.

Pass the -S option to gpic and disable the open , opena , pso , sy , and pi requests. For security reasons, this is enabled by default. Prepare output for device dev. The following are the output devices currently available:. For typewriter-like devices that support the Latin-1 ISO character set.

Note that this driver consists of two parts, a preprocessor pre-grohtml and a postprocessor post-grohtml. The predefined gtroff string register. T contains the current output device; the read-only number register. T is set to 1 if this option is used which is always true if groff is used to call gtroff. The postprocessor to be used for a device is specified by the postpro command in the device description file. See Font Files , for more info.

This can be overridden with the -X option. Unsafe mode. This enables the open , opena , pso , sy , and pi requests. Enable warning name. Available warnings are described in Debugging. Multiple -w options are allowed.

Print the pipeline on stdout instead of executing it. If specified more than once, print the pipeline on stderr and execute it. Preview with gxditview instead of using the usual postprocessor. This is unlikely to produce good results except with -Tps. Note that this is not the same as using -TX75 or -TX to view a document with gxditview : The former uses the metrics of the specified device, whereas the latter uses X-specific fonts and metrics.

Do not postprocess the output of gtroff. Normally groff automatically runs the appropriate postprocessor. There are also several environment variables of the operating system, not within gtroff that can modify the behavior of groff. This search path, followed by PATH , is used for commands executed by groff. If this is set to X , then groff runs X troff instead of gtroff.

This also applies to tbl , pic , eqn , grn , chem , refer , and soelim. It does not apply to grops , grodvi , grotty , pre-grohtml , post-grohtml , preconv , grolj4 , gropdf , and gxditview. The default command prefix is determined during the installation process. The value of this environment value is passed to the preconv preprocessor to select the encoding of input files. If set without a value, groff calls preconv without arguments. See the manual page of preconv for details.

A colon-separated list of directories in which to search for the dev name directory before the default directories are tried. See Font Directories. A colon-separated list of directories in which to search for macro files before the default directories are tried. See Macro Directories. The directory in which groff creates temporary files. All macro file names must be named name. Macro files are kept in the tmac directories , all of which constitute the tmac path. The elements of the search path for macro files are in that order :.

It is possible to fine-tune those directories during the installation process. Basically, there is no restriction how font files for groff are named and how long font names are; however, to make the font family mechanism work see Font Families , fonts within a family should start with the family name, followed by the shape. All font files are kept in the font directories , which constitute the font path. The file search functions always append the directory dev name , where name is the name of the output device.

In groff, the page size for gtroff and for output devices are handled separately. See Page Layout , for vertical manipulation of the page size. See Line Layout , for horizontal changes. Most output devices also have a command-line option -p to override the default paper size and option -l to use landscape orientation.

This defines string paper , which is processed in file papersize. Possible values for size are the same as the predefined values for the papersize keyword but only in lowercase except a7 — d7.

Note that it is up to the particular macro package to respect default page dimensions set in this way most do. This section lists several common uses of groff and the corresponding command lines. This command processes file without a macro package or a preprocessor. This is basically what a call to the man program does. Finally, the less pager displays the result. Preview file with gxditview , using the me macro package. It generates one or more of the options -e , -man , -me , -mm , -mom , -ms , -mdoc , -mdoc-old , -p , -R , -g , -G , -s , and -t.

A special file name - refers to the standard input. Specifying no files also means to read the standard input. Any specified options are included in the printed command. No space is allowed between options and their arguments. The only options recognized are -C which is also passed on to enable compatibility mode, and -v to print the version number and exit. For direct execution, enclose the call to grog in backquotes at the Unix shell prompt:.

As seen in the example, it is still necessary to redirect the output to something meaningful i. Most users tend to use a macro package to format their papers. This means that the whole breadth of groff is not necessary for most people. This chapter covers the material needed to efficiently use a macro package.

This section covers some of the basic concepts necessary to understand how to use a macro package. The input consists of text, or words to be printed, and embedded commands requests and escapes , which tell gtroff how to format the output. For more detail on this, see Embedded Commands. The word argument is used in this chapter to mean a word or number that appears on the same line as a request, and which modifies the meaning of that request.

For example, the request. The number 4 is an argument to the sp request, which says to space four lines instead of one. Arguments are separated from the request and from each other by spaces no tabs. More details on this can be found in Request and Macro Arguments.

The primary function of gtroff is to collect words from input lines, fill output lines with those words, justify the right-hand margin by inserting extra spaces in the line, and output the result. For example, the input:. Now is the time for all good men to come to the aid of their party. Four score and seven years ago, etc.

Sometimes a new output line should be started even though the current line is not yet full; for example, at the end of a paragraph. To do this it is possible to cause a break , which starts a new output line. Some requests cause a break automatically, as normally do blank input lines and input lines beginning with a space. Not all input lines are text to be formatted. Some input lines are requests that describe how to format the text.

The text formatter also does more complex things, such as automatically numbering pages, skipping over page boundaries, putting footnotes in the correct place, and so forth. A number of requests allow to change the way the output looks, sometimes called the layout of the output page. Most of these requests adjust the placing of whitespace blank lines or spaces. N can be omitted meaning skip a single line or can be of the form N i for N inches or N c for N centimeters. Text lines can be centered by using the ce request.

The line after ce is centered horizontally on the page. To center many lines without counting them, type:. All of these requests cause a break; that is, they always start a new line. To start a new line without performing any other action, use br. There are many common routine operations that are done in all documents. These common operations are written into macros and collected into a macro package.

One of the most common and most used capability is starting a paragraph. There are a number of different types of paragraphs, any of which can be initiated with macros supplied by the macro package.

Normally, paragraphs start with a blank line and the first line indented, like the text in this manual. There are also block style paragraphs, which omit the indentation:.

And there are also indented paragraphs, which begin with a tag or label at the margin and the remaining text indented. Most macro packages supply some form of section headers. The simplest kind is simply the heading on a line by itself in bold type. Others supply automatically numbered section heading or different heading styles at different levels.

Some, more sophisticated, macro packages supply macros for starting chapters and appendices. Every macro package gives some way to manipulate the headers and footers also called titles on each page. This is text put at the top and bottom of each page, respectively, which contain data like the current page number, the current chapter title, and so on. Its appearance is not affected by the running text.

Some packages allow for different ones on the even and odd pages for material printed in a book form. The titles are called three-part titles , that is, there is a left-justified part, a centered part, and a right-justified part. Most macro packages let the user specify top and bottom margins and other details about the appearance of the printed pages.

Displays are sections of text to be set off from the body of the paper. Major quotes, tables, and figures are types of displays, as are all the examples used in this document. Major quotes are quotes that are several lines long, and hence are set in from the rest of the text without quote marks around them. A list is an indented, single-spaced, unfilled display. Lists should be used when the material to be printed should not be filled and justified like normal text, such as columns of figures or the examples used in this paper.

A keep is a display of lines that are kept on a single page if possible. An example for a keep might be a diagram. Keeps differ from lists in that lists may be broken over a page boundary whereas keeps are not.

Floating keeps move relative to the text. A floating keep appears at the bottom of the current page if it fits; otherwise, it appears at the top of the next page. Delayed text is very similar to a footnote except that it is printed when called for explicitly. This allows a list of references to appear for example at the end of each chapter, as is the convention in some disciplines. Most macro packages that supply this functionality also supply a means of automatically numbering either type of annotation.

Tables of contents are a type of delayed text having a tag usually the page number attached to each entry after a row of dots. The table accumulates throughout the paper until printed, usually after the paper has ended. Many macro packages provide the ability to have several tables of contents e. While some macro packages use the term index , none actually provide that functionality.

The facilities they call indices are actually more appropriate for tables of contents. To produce a real index in a document, external tools like the makeindex program are necessary. Some macro packages provide stock formats for various kinds of documents.

Many of them provide a common format for the title and opening pages of a technical paper. The mm macros in particular provide formats for letters and memoranda.

Some macro packages but not man provide the ability to have two or more columns on a page. The built-in font and size functions are not always intuitive, so all macro packages provide macros to make these operations simpler.

Most macro packages provide various predefined strings for a variety of uses; examples are sub- and superscripts, printable dates, quotes and various special characters. For example, all macro packages mark tables which are processed with gtbl by placing them between TS and TE macros.

Some macro packages provide means of customizing many of the details of how the package behaves. This ranges from setting the default type size to changing the appearance of section headers.

Note that option arguments are processed before non-option arguments; the above failing sample is thus reordered to. This is the most popular and probably the most important macro package of groff.

It is easy to use, and a vast majority of manual pages are based on it. This option the default if a TTY output device is used creates a single, very long page instead of multiple pages. If more than one manual page is given on the command line, number the pages continuously, rather than starting each at 1.

Set the position of the footer text to dist. If positive, the distance is measured relative to the top of the page, otherwise it is relative to the bottom. The default is Set hyphenation flags. Possible values are 1 to hyphenate without restrictions, 2 to not hyphenate the last word on a page, 4 to not hyphenate the last two characters of a word, and 8 to not hyphenate the first two characters of a word.

These values are additive; the default is 8. Set the body text indentation to length. If not specified, the indentation defaults to 7n 7 characters in nroff mode and 7. Set line length to length. Set title length to length. If not specified, the title length defaults to the line length.

Use xx which can be 10, 11, or 12pt as the base document font size instead of the default value of 10pt. Set the indentation for sub-subheadings to length. If not specified, the indentation defaults to 3n. After page nnn , number pages as nnn a, nnn b, nnn c, etc. For example, the option -rX2 produces the following page numbers: 1, 2, 2a, 2b, 2c, etc. This section describes the available macros for manual pages. For further customization, put additional macros and requests into the file man.

Set the title of the man page to title and the section to section , which must have a value between 1 and 8. The value of section may also have a string appended, e.

Both title and section are positioned at the left and right in the header line with section in parentheses immediately appended to title. Additionally, this macro starts a new page; the new line number is 1 again except if the -rC1 option is given on the command line — this feature is intended only for formatting multiple man pages; a single man page should contain exactly one TH macro at the beginning of the file.

Set up an unnumbered section heading sticking out to the left. Prints out all the text following SH up to the end of the line or the text in the next line if there is no argument to SH in bold face or the font specified by the string HF , one size larger than the base document size.

Additionally, the left margin and the indentation for the following text is reset to its default value. Set up an unnumbered sub section heading. Prints out all the text following SS up to the end of the line or the text in the next line if there is no argument to SS in bold face or the font specified by the string HF , at the same size as the base document size. Set up an indented paragraph with label.

The first line of text following this macro is interpreted as a string to be printed flush-left, as it is appropriate for a label. It is not interpreted as part of a paragraph, so there is no attempt to fill the first line with text from the following input lines.

Nevertheless, if the label is not as wide as the indentation the paragraph starts at the same line but indented , continuing on the following lines. If the label is wider than the indentation the descriptive part of the paragraph begins on the line following the label, entirely indented. Note that neither font shape nor font size of the label is set to a default value; on the other hand, the rest of the text has default font settings.

These macros are mutual aliases. Any of them causes a line break at the current position, followed by a vertical space downwards by the amount specified by the PD macro. The font size and shape are reset to the default value 10pt roman if no -rS option is given on the command line. Finally, the current left margin and the indentation is restored. Set up an indented paragraph, using designator as a tag to mark its beginning. Font size and face of the paragraph but not the designator are reset to their default values.

For example, to start a paragraph with bullets as the designator and 4 en indentation, write. Set up a paragraph with hanging left indentation. Font size and face are reset to their default values. The indentation value is then set to the default. Move the left margin back to level nnn , restoring the previous left margin. If no argument is given, it moves one level back. The first level i. The macros RS and RE also cause a break but do not insert vertical space.

The standard font is roman; the default text size is 10 points. Set the text on the same line or the text on the next line in a font that is one point size smaller than the default font. Set the text on the same line or the text on the next line in bold face font, one point size smaller than the default font.

Set its arguments alternately in bold face and italic, without a space between the arguments. Set text in bold face. If no text is present on the line where the macro is called, then the text of the next line appears in bold face. Set text in italic. If no text is present on the line where the macro is called, then the text of the next line appears in italic.

The default indentation is 7. Set tabs every 0. Since this macro is always executed during a call to the TH macro, it makes sense to call it only if the tab positions have been changed. Adjust the empty space before a new paragraph or section. The first argument system can be:. Alters the footer for use with BSD manpages. The argument can be:. If a preprocessor like gtbl or geqn is needed, it has become common usage to make the first line of the man page look like this:.

Note the single space character after the double quote. Modern implementations of the man program read this first line and automatically call the right preprocessor s. Previous: Preprocessors in man pages , Up: man [ Contents ][ Index ].

Use the file man. In groff versions 1. Control the content of the headers. Normally, the header prints the command name and section number on either side, and the optional fifth argument to TH in the center.

Control the content of the footers. Normally, the footer prints the page number and the third and fourth arguments to TH. The groff source distribution includes a file named man. Copy this file into man. Begin a non-filled display using the constant width Courier typeface. Use the optional indent argument to indent the display.

Set text in Helvetica. If no text is present on the line where the macro is called, then the text of the next line appears in Helvetica. Set text in Helvetica Oblique.

If no text is present on the line where the macro is called, then the text of the next line appears in Helvetica Oblique. Set text in Helvetica Bold. If no text is present on the line where the macro is called, then all text up to the next HB appears in Helvetica Bold. Set a manpage reference in Ultrix format. The title is in Courier instead of italic. Optional punctuation follows the section number without an intervening space.

Begin a note. Text following the macro makes up the body of the note, and is indented on both sides. If called with two arguments, identical to PN. If called with three arguments, set the second argument in constant width Courier , bracketed by the first and third arguments in the current font.

Start printing a change bar in the margin if the number 4 is specified. Otherwise, this macro does nothing. The following example man.

Headings are printed in Helvetica Bold. The -ms macros are suitable for reports, letters, books, user manuals, and so forth. The package provides macros for cover pages, section headings, paragraphs, lists, footnotes, pagination, and a table of contents.

While the man package is intended for brief documents that can be read on-line as well as printed, the ms macros are suitable for longer documents that are meant to be printed rather than read on-line. The ms macro package included with groff is a complete, bottom-up re-implementation. The ms macro package expects a certain amount of structure, but not as much as packages such as man or mdoc.

The simplest documents can begin with a paragraph macro such as LP or PP , and consist of text separated by paragraph macros or even blank lines. Longer documents have a structure as follows:. If you invoke the RP report macro on the first line of the document, groff prints the cover page information on its own page; otherwise it prints the information on the first page with your document text immediately following. See ms Document Control Registers , for more details.

Following the cover page is your document. You can use the ms macros to write reports, letters, books, and so forth. The package is designed for structured documents, consisting of paragraphs interspersed with headings and augmented by lists, footnotes, tables, and other common constructs.

See ms Body Text , for more details. Longer documents usually include a table of contents, which you can invoke by placing the TC macro at the end of your document. The ms macros have minimal indexing facilities, consisting of the IX macro, which prints an entry on standard error.

Printing the table of contents at the end is necessary since groff is a single-pass text formatter, thus it cannot determine the page number of each section until that section has actually been set and printed. Since ms output is intended for hardcopy, you can manually relocate the pages containing the table of contents between the cover page and the body text after printing.

The following is a list of document control number registers. For the sake of consistency, set registers related to margins at the beginning of your document, or just after the RP macro. You can set other registers later in your document, but you should keep them together at the beginning to make them easy to find and edit as necessary.

Defines the page offset i. There is no explicit right margin setting; the combination of the PO and LL registers implicitly define the right margin width. Defines the title length i. This is usually the same as LL , but not necessarily. Defines the point size of the body text.

If the value is larger than or equal to , divide it by to get a fractional point size. Defines the space between lines line height plus leading. Due to backwards compatibility, VS must be smaller than this is Defines an increment in point size, which is applied to section headings at nesting levels below the value specified in GROWPS. Defines the hyphenation level. HY sets safely the value of the low-level hy register. Setting the value of HY to 0 is equivalent to using the nh request.

Defines the minimum number of initial lines of any paragraph that should be kept together, to avoid orphan lines at the bottom of a page. If a new paragraph is started close to the bottom of a page, and there is insufficient space to accommodate PORPHANS lines before an automatic page break, then the page break is forced, before the start of the paragraph.

Defines the minimum number of lines of the following paragraph that should be kept together with any section heading introduced by the NH or SH macros. If a section heading is placed close to the bottom of a page, and there is insufficient space to accommodate both the heading and at least HORPHANS lines of the following paragraph, before an automatic page break, then the page break is forced before the heading.

Defines the footnote point size. Defines the footnote vertical spacing. Sets the vertical spacing before and after a display, a tbl table, an eqn equation, or a pic image. Specifies the report format for your document. The report format creates a separate cover page.

The default action no RP macro is to print a subset of the cover page on page 1 of your document. If you use the word no as an optional argument, groff prints a title page but does not repeat any of the title page information title, author, abstract, etc. This is the default for nroff. This is the default for troff.

Specifies the document title. You can specify multiple authors as follows:. You can specify multiple institutions in the same way that you specify multiple authors.

Begins the abstract. The word no as an optional argument suppresses this heading. The following is example mark-up for a title page. This section describes macros used to mark up the body of your document.

Examples include paragraphs, sections, and other groups. Sets a paragraph that is indented at both left and right margins by the amount of the register QI. The next paragraph or heading returns margins to normal. QP inserts vertical space of amount set by register PD before the paragraph. These macros begin and end a quoted section. The QI register controls the amount of indentation.

Sets a paragraph whose lines are indented, except for the first line. This is a Berkeley extension. Use headings to create a hierarchical structure for your document. The ms macros print headings in bold , using the same font family and point size as the body text. Numbered heading. The argument is either a numeric argument to indicate the level of the heading, or the letter S followed by numeric arguments to set the heading level explicitly. You may control the style used to print section numbers, within numbered section headings, by defining an appropriate alias for the string SN-STYLE.

The default style, in which the printed section number is followed by a terminating period, is obtained by defining the alias. If you prefer to omit the terminating period, from section numbers appearing in numbered section headings, you may define the alias. Any such change in section numbering style becomes effective from the next use of. The optional match-level argument is a GNU extension. It is a number indicating the level of the heading, in a manner analogous to the curr-level argument to.

See ms Document Control Registers. Sets its first argument in bold type. If you specify a second argument, groff prints it in the previous font after the bold text, with no intervening space this allows you to set punctuation after the highlighted text without highlighting the punctuation.

Similarly, it prints the third argument if any in the previous font before the first argument. For example,. If you give this macro no arguments, groff prints all text following in bold until the next highlighting, paragraph, or heading macro.

Sets its first argument in roman or regular type. It operates similarly to the B macro otherwise. Sets its first argument in italic type.

Sets its first argument in a constant width face. Sets its first argument in bold italic type. Prints its argument and draws a box around it.

Prints its first argument with an underline. If you specify a second argument, groff prints it in the previous font after the underlined text, with no intervening space. Prints all text following in larger type two points larger than the current point size until the next font size, highlighting, paragraph, or heading macro. You can specify this macro multiple times to enlarge the point size as needed.

Prints all text following in smaller type two points smaller than the current point size until the next type size, highlighting, paragraph, or heading macro. You can specify this macro multiple times to reduce the point size as needed. Prints all text following in the normal point size that is, the value of the PS register. Once specified, the indentation remains the same for all list items in the document until specified again. The following is an example of a bulleted list. The following is an example of a numbered list.

The following is an example of a glossary-style list. In the last example, the IP macro places the definition on the same line as the term if it has enough space; otherwise, it breaks to the next line and starts the definition below the term. This may or may not be the effect you want, especially if some of the definitions break and some do not. The following examples show two possible ways to force a break.

The first workaround uses the br request to force a break after printing the term or label. Note the space following the escape; this is important. If you omit the space, groff prints the first word on the same line as the term or label if it fits then breaks the line.

To set nested lists, use the RS and RE macros. See Indentation values in ms , for more information. In many situations, you may need to indentation a section of text while still wrapping and filling. See Lists in ms , for an example of nested lists. These macros begin and end an indented section. The PI register controls the amount of indentation, allowing the indented text to line up under hanging and indented paragraphs. See ms Displays and Keeps , for macros to indentation and turn off filling.

Use the ta request to define tab stops as needed. See Tabs and Fields. Use this macro to reset the tab stops to the default for ms every 5n. You can redefine the TA macro to create a different set of default tab stops.

Displays turn off filling, so lines of code are displayed as-is without inserting br requests in between each line. Displays can be kept on a single page, or allowed to break across pages. Left-justified display. The LD macro allows the display to break across pages. The DE macro ends the display. Indents the display as defined by the DI register. The ID macro allows the display to break across pages. Sets a block-centered display: the entire display is left-justified, but indented so that the longest line in the display is centered on the page.

The BD macro allows the display to break across pages. Sets a centered display: each line in the display is centered. The CD macro allows the display to break across pages. Right-justifies each line in the display. The RD macro allows the display to break across pages. These two macros were formerly provided as aliases for DS and DE , respectively. They have been removed, and should no longer be used.

The original implementations of DS and DE are retained, and should be used instead. X11 documents that actually use Ds and De always load a specific macro file from the X11 distribution macros.

On occasion, you may want to keep other text together on a page. For example, you may want to keep two paragraphs together, or a paragraph that refers to a table or list, or other item immediately following. The ms macros provide the KS and KE macros for this purpose.

The KS macro begins a block of text to be kept on a single page, and the KE macro ends the block. Specifies a floating keep ; if the keep cannot fit on the current page, groff holds the contents of the keep and allows text following the keep in the source file to fill in the remainder of the current page. When the page breaks, whether by an explicit bp request or by reaching the end of the page, groff prints the floating keep at the top of the new page. This is useful for printing large graphics or tables that do not need to appear exactly where specified.

You can also use the ne request to force a page break if there is not enough vertical space remaining on the page. Marks the beginning and ending of text that is to have a box drawn around it. The B1 macro begins the box; the B2 macro ends it.

Text in the box is automatically placed in a diversion keep. The ms macros support the standard groff preprocessors: tbl , pic , eqn , and refer. You mark text meant for preprocessors by enclosing it in pairs of tags as follows.

Denotes a table, to be processed by the tbl preprocessor. The optional argument H to TS instructs groff to create a running header with the information up to the TH macro. Denotes a graphic, to be processed by the pic preprocessor. Denotes an equation, to be processed by the eqn preprocessor. The optional align argument can be C , L , or I to center the default , left-justify, or indent the equation.

Denotes a reference, to be processed by the refer preprocessor. The GNU refer 1 man page provides a comprehensive reference to the preprocessor and the format of the bibliographic database.

The ms macro package has a flexible footnote system. You can specify either numbered footnotes or symbolic footnotes that is, using a marker such as a dagger symbol. Specifies the text of the footnote. You can control how groff prints footnote numbers by changing the value of the FF register. Footnotes can be safely used within keeps and displays, but you should avoid using numbered footnotes within floating keeps.

The default output from the ms macros provides a minimalist page layout: it prints a single column, with the page number centered at the top of each page. It prints no footers. For documents that need different information printed in the even and odd pages, use the following macros:.

This is more flexible than defining the individual strings. You can replace the quote ' marks with any character not appearing in the header or footer text. The PT macro defines a custom header; the BT macro defines a custom footer. The HD macro defines additional header processing to take place after executing the PT macro. You control margins using a set of number registers. See ms Document Control Registers , for details.

The ms macros can set text in as many columns as do reasonably fit on the page. The following macros are available; all of them force a page break if a multi-column mode is already set.

However, if the current mode is single-column, starting a multi-column mode does not force a page break. Multi-column mode.

If you specify no arguments, it is equivalent to the 2C macro. Otherwise, width is the width of each column and gutter is the space between columns. The facilities in the ms macro package for creating a table of contents are semi-automated at best. These macros define a table of contents or an individual entry in the table of contents, depending on their use. The macros are very simple; they cannot indent a heading based on its level.

The easiest way to work around this is to add tabs to the table of contents string. The following is an example:. You can manually create a table of contents by beginning with the XS macro for the first entry, specifying the page number for that entry as the argument to XS.

Add subsequent entries using the XA macro, specifying the page number for that entry as the argument to XA. Prints the table of contents on a new page, setting the page number to i Roman lowercase numeral one.

You should usually place this macro at the end of the file, since groff is a single-pass formatter and can only print what has been collected up to the point that the TC macro appears. The optional argument no suppresses printing the title specified by the string register TOC. Prints the table of contents on a new page, using the current page numbering sequence. Use this macro to print a manually generated table of contents at the beginning of your document. Altering the NH macro to automatically build the table of contents is perhaps initially more difficult, but would save a great deal of time in the long run if you use ms regularly.

The ms macros provide the following predefined strings. You can change the string definitions to help in creating documents in languages other than English.

Contains the string printed at the beginning of the references bibliography page. Contains the string printed at the beginning of the abstract. Prints the full name of the month in dates. Specify this macro at the beginning of your document to enable extended accent marks and special characters. Emulations of a few ancient Bell Labs macros can be re-enabled by calling the otherwise undocumented SC section-header macro.

These are not enabled by default because a they were not documented, in the original ms manual, and b the P1 and UC macros collide with different macros with the same names in the Berkeley version of ms. No warranty express or implied is given as to how well the typographic details these produce match the original Bell Labs macros. Macros missing from groff -ms are cover page macros specific to Bell Labs and Berkeley. The macros known to be missing are:. Improved accent marks. See ms Strings and Special Characters , for details.

Indented display. Indexing term printed on standard error. You can write a script to capture and process an index generated in this manner. Several new string registers are available as well. You can change these to handle for example the local language. The following conventions are used for names of macros, strings and number registers.

External names available to documents that use the groff -ms macros contain only uppercase letters and digits. See the meintro. The main documentation files for the mom macros are in HTML format. Additional, useful documentation is in PDF format. The mom macros are in active development between groff releases. This chapter covers all of the facilities of gtroff.

Users of macro packages may skip it if not interested in details. But, even without control codes, gtroff still does several things with the input text:. When gtroff reads text, it collects words from the input and fits as many of them together on one output line as it can.

This is known as filling. Once gtroff has a filled line, it tries to adjust it. This means it widens the spacing between words until the text reaches the right margin in the default adjustment mode. Extra spaces between words are preserved, but spaces at the end of lines are ignored. Spaces at the front of a line cause a break breaks are explained in Implicit Line Breaks.

Since the odds are not great for finding a set of words, for every output line, which fit nicely on a line without inserting excessive amounts of space between words, gtroff hyphenates words so that it can justify lines without inserting too much space between words. It uses an internal hyphenation algorithm a simplified version of the algorithm used within TeX to indicate which words can be hyphenated and how to do so. When a word is hyphenated, the first part of the word is added to the current filled line being output with an attached hyphen , and the other portion is added to the next line to be filled.

Although it is often debated, some typesetting rules say there should be different amounts of space after various punctuation marks.

For example, the Chicago typesetting manual says that a period at the end of a sentence should have twice as much space following it as would a comma or a period as part of an abbreviation.

When gtroff encounters one of these characters at the end of a line, it appends a normal space followed by a sentence space in the formatted output. This justifies one of the conventions mentioned in Input Conventions.

See the cflags request in Using Symbols , for more details. These tab stops are initially located every half inch across the page. Using this, simple tables can be made easily. However, it can often be deceptive as the appearance and width of the text on a terminal and the results from gtroff can vary greatly. Also, a possible sticking point is that lines beginning with tab characters are still filled, again producing unexpected results. For example, the following input.

An important concept in gtroff is the break. When a break occurs, gtroff outputs the partially filled line unjustified , and resumes collecting and filling text on the next output line. There are several ways to cause a break in gtroff. A blank line not only causes a break, but it also outputs a one-line vertical space effectively a blank line. Note that this behaviour can be modified with the blank line macro request blm.

See Blank Line Traps. The following is an example of a bulleted list. The following is an example of a numbered list.

The following is an example of a glossary-style list. In the last example, the IP macro places the definition on the same line as the term if it has enough space; otherwise, it breaks to the next line and starts the definition below the term. This may or may not be the effect you want, especially if some of the definitions break and some do not.

The following examples show two possible ways to force a break. The first workaround uses the br request to force a break after printing the term or label. Note the space following the escape; this is important. If you omit the space, groff prints the first word on the same line as the term or label if it fits then breaks the line.