title: groff_ms(7)

summary: groff ms macros

text:
# groff_ms(7)

## NAME
groff_ms - groff ms macros

## SYNOPSIS
groff -ms [ options... ] [ files... ]

groff -m ms [ options... ] [ files... ]

## DESCRIPTION
This manual page describes the GNU version of the ms macros, part of the groff typesetting system. The ms macros are mostly compatible with the documented behavior of the 4.3 BSD Unix ms macros (see Differences from troff ms below for details). The ms macros are suitable for reports, letters, books, and technical documentation.

## USAGE
The ms macro package expects files to have a certain amount of structure. The simplest documents can begin with a paragraph macro and consist of text separated by paragraph macros or even blank lines. Longer documents have a structure as follows:

Document type

If you use the RP (report) macro at the beginning 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. Other document formats found in AT&T troff are specific to AT&T or Berkeley, and are not supported in groff ms.

Format and layout

By setting number registers, you can change your document's type (font and size), margins, spacing, headers and footers, and footnotes. See Document control registers below for more details.

Cover page

A cover page consists of a title, and optionally the author's name and institution, an abstract, and the date. See Cover page macros below for more details.

Body

Following the cover page is your document. It consists of paragraphs, headings, and lists.

Table of contents

Longer documents usually include a table of contents, which you can add by placing the TC macro at the end of your document.

### Document control registers
The following table lists the 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.

Margin settings

Reg.

Definition

Effective

Default

PO

Page offset (left margin)

next page

1i

LL

Line length

next paragraph

6i

LT

Header/footer length

next paragraph

6i

HM

Top (header) margin

next page

1i

FM

Bottom (footer) margin

next page

1i

Text settings

Reg.

Definition

Effective

Default

PS

Point size

next paragraph

10p

VS

Line spacing (leading)

next paragraph

12p

PSINCR

Point size increment for section headings of increasing importance

next heading

1p

GROWPS

Heading level beyond which PSINCR is ignored

next heading

0

Paragraph settings

Reg.

Definition

Effective

Default

PI

Initial indent

next paragraph

5n

PD

Space between paragraphs

next paragraph

0.3v

QI

Quoted paragraph indent

next paragraph

5n

PORPHANS

Number of initial lines to be kept together

next paragraph

1

HORPHANS

Number of initial lines to be kept with heading

next heading

1

Footnote settings

Reg.

Definition

Effective

Default

FL

Footnote length

next footnote

\n[LL]*5/6

FI

Footnote indent

next footnote

2n

FF

Footnote format

next footnote

0

FPS

Point size

next footnote

\n[PS]-2

FVS

Vert. spacing

next footnote

\n[FPS]+2

FPD

Para. spacing

next footnote

\n[PD]/2

Other settings

Reg.

Definition

Effective

Default

DD

Display, table, eqn, pic spacing

next para.

0.5v

MINGW

Minimum width between columns

next page

2n

### Cover page macros
Use the following macros to create a cover page for your document in the order shown.

.RP [no]

Specifies the report format for your document. The report format creates a separate cover page. With no RP macro, groff prints a subset of the cover page on page 1 of your document.

If you use the optional no argument, groff prints a title page but does not repeat any of the title page information (title, author, abstract, etc.) on page 1 of the document.

.P1

(P-one) Prints the header on page 1. The default is to suppress the header.

.DA [xxx]

(optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) and in the footers. This is the default for nroff.

.ND [xxx]

(optional) Print the current date, or the arguments to the macro if any, on the title page (if specified) but not in the footers. This is the default for troff.

.TL

Specifies the document title. Groff collects text following the TL macro into the title, until reaching the author name or abstract.

.AU

Specifies the author's name. You can specify multiple authors by using an AU macro for each author.

.AI

Specifies the author's institution. You can specify multiple institutions.

.AB [no]

Begins the abstract. The default is to print the word ABSTRACT, centered and in italics, above the text of the abstract. The option no suppresses this heading.

.AE

End the abstract.

### Paragraphs
Use the PP macro to create indented paragraphs, and the LP macro to create paragraphs with no initial indent.

The QP macro indents all text at both left and right margins. The effect is identical to the HTML <BLOCKQUOTE> The next paragraph or heading returns margins to normal.

The XP macro produces an exdented paragraph. The first line of the paragraph begins at the left margin, and subsequent lines are indented (the opposite of PP).

For each of the above paragraph types, and also for any list entry introduced by the IP macro (described later), the document control register PORPHANS, sets the minimum number of lines which must be printed, after the start of the paragraph, and before any page break occurs. If there is insufficient space remaining on the current page to accommodate this number of lines, then a page break is forced before the first line of the paragraph is printed.

Similarly, when a section heading (see subsection Headings below) precedes any of these paragraph types, the HORPHANS document control register specifies the minimum number of lines of the paragraph which must be kept on the same page as the heading. If insufficient space remains on the current page to accommodate the heading and this number of lines of paragraph text, then a page break is forced before the heading is printed.

### Headings
Use headings to create a hierarchical structure for your document. By default, the ms macros print headings in bold using the same font family and point size as the body text. For output devices which support scalable fonts, this behaviour may be modified, by defining the document control registers, GROWPS and PSINCR.

The following heading macros are available:

.NH xx

Numbered heading. The argument xx is either a numeric argument to indicate the level of the heading, or S xx xx "..." to set the section number explicitly. If you specify heading levels out of sequence, such as invoking .NH 3 after .NH 1, groff prints a warning on standard error.

If the GROWPS register is set to a value greater than the level of the heading, then the point size of the heading will be increased by PSINCR units over the text size specified by the PS register, for each level by which the heading level is less than the value of GROWPS. For example, the sequence:

```
.nr PS 10
.nr GROWPS 3
.nr PSINCR 1.5p
.
.NH 1
Top Level Heading
.
.NH 2
Second Level Heading
.
.NH 3
Third Level Heading
```

will cause “1. Top Level Heading” to be printed in 13pt bold text, followed by “1.1. Second Level Heading” in 11.5pt bold text, while “1.1.1. Third Level Heading”, and all more deeply nested heading levels, will remain in the 10pt bold text which is specified by the PS register.

Note that the value stored in PSINCR is interpreted in groff basic units; the p scaling factor should be employed, when assigning a value specified in points.

The style used to represent the section number, within a numbered heading, is controlled by the SN-STYLE string; this may be set to either the SN-DOT or the SN-NO-DOT style, (described below), by aliasing SN-STYLE accordingly. By default, SN-STYLE is initialised by defining the alias

```
.als SN-STYLE SN-DOT
```

it may be changed to the SN-NO-DOT style, if preferred, by defining the alternative alias

```
.als SN-STYLE SN-NO-DOT
```

Any such change becomes effective with the first use of .NH, after the new alias is defined.

After invoking .NH, the assigned heading number is available in the strings SN-DOT (as it appears in the default formatting style for numbered headings, with a terminating period following the number), and SN-NO-DOT (with this terminating period omitted). The string SN is also defined, as an alias for SN-DOT; if preferred, the user may redefine it as an alias for SN-NO-DOT, by including the initialisation:

```
.als SN SN-NO-DOT
```

at any time; the change becomes effective with the next use of .NH, after the new alias is defined.

.SH [xx]

Unnumbered subheading. The use of the optional xx argument is a GNU extension, which adjusts the point size of the unnumbered subheading to match that of a numbered heading, introduced using .NH xx with the same value of xx. For example, given the same settings for PS, GROWPS and PSINCR, as used in the preceding .NH example, the sequence:

```
.SH 2
An Unnumbered Subheading
```

will print “An Unnumbered Subheading” in 11.5pt bold text.

### Highlighting
The ms macros provide a variety of methods to highlight or emphasize text:

.B [txt [post [pre]]]

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,

.B foo ) (

prints (foo).

If you give this macro no arguments, groff prints all text following in bold until the next highlighting, paragraph, or heading macro.

.R [txt [post [pre]]]

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

.I [txt [post [pre]]]

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

.CW [txt [post [pre]]]

Sets its first argument in a constant width face. It operates similarly to the B macro otherwise.

.BI [txt [post [pre]]]

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

.BX [txt]

Prints its argument and draws a box around it. If you want to box a string that contains spaces, use a digit-width space (\0).

.UL [txt [post]]

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.

.LG

Prints all text following in larger type (2 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.

.SM

Prints all text following in smaller type (2 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.

.NL

Prints all text following in the normal point size (that is, the value of the PS register).

\*{text\*}

Print the enclosed text as a superscript.

### Indents
You may need to indent sections of text. A typical use for indents is to create nested lists and sublists.

Use the RS and RE macros to start and end a section of indented text, respectively. The PI register controls the amount of indent.

You can nest indented sections as deeply as needed by using multiple, nested pairs of RS and RE.

### Lists
The IP macro handles duties for all lists. Its syntax is as follows:

.IP [marker [width]]

The marker is usually a bullet character \(bu for unordered lists, a number (or auto-incrementing number register) for numbered lists, or a word or phrase for indented (glossary-style) lists.

The width specifies the indent for the body of each list item. Once specified, the indent remains the same for all list items in the document until specified again.

### Tab stops
Use the ta request to set tab stops as needed. Use the TA macro to reset tabs to the default (every 5n). You can redefine the TA macro to create a different set of default tab stops.

### Displays and keeps
Use displays to show text-based examples or figures (such as code listings). Displays turn off filling, so lines of code can be 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. The following table shows the display types available.

Display macro

Type of display

With keep

No keep

.DS L

.LD

Left-justified.

.DS I [indent]

.ID

Indented (default indent in the DI register).

.DS B

.BD

Block-centered (left-justified, longest line centered).

.DS C

.CD

Centered.

.DS R

.RD

Right-justified.

Use the DE macro to end any display type. The macros Ds and De were formerly provided as aliases for DS and DE, respectively, but they have been removed, and should no longer be used. X11 documents which actually use Ds and De always load a specific macro file from the X11 distribution (macros.t) which provides proper definitions for the two macros.

To keep text together on a page, such as a paragraph that refers to a table (or list, or other item) immediately following, use the KS and KE macros. The KS macro begins a block of text to be kept on a single page, and the KE macro ends the block.

You can specify a floating keep using the KF and KE macros. 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.

The macros B1 and B2 can be used to enclose a text within a box; .B1 begins the box, and .B2 ends it. Text in the box is automatically placed in a diversion (keep).

### Tables, figures, equations, and references
The -ms macros support the standard groff preprocessors: tbl, pic, eqn, and refer. Mark text meant for preprocessors by enclosing it in pairs of tags as follows:

.TS [H] and .TE

Denotes a table, to be processed by the tbl preprocessor. The optional H argument instructs groff to create a running header with the information up to the TH macro. Groff prints the header at the beginning of the table; if the table runs onto another page, groff prints the header on the next page as well.

.PS and .PE

Denotes a graphic, to be processed by the pic preprocessor. You can create a pic file by hand, using the AT&T pic manual available on the Web as a reference, or by using a graphics program such as xfig.

.EQ [align] and .EN

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.

.[ and .]

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

### Footnotes
The ms macros provide a flexible footnote system. You can specify a numbered footnote by using the \** escape, followed by the text of the footnote enclosed by FS and FE macros.

You can specify symbolic footnotes by placing the mark character (such as \(dg for the dagger character) in the body text, followed by the text of the footnote enclosed by FS \(dg and FE macros.

You can control how groff prints footnote numbers by changing the value of the FF register as follows:

0

Prints the footnote number as a superscript; indents the footnote (default).

1

Prints the number followed by a period (like 1.) and indents the footnote.

2

Like 1, without an indent.

3

Like 1, but prints the footnote number as a hanging paragraph.

You can use footnotes safely within keeps and displays, but avoid using numbered footnotes within floating keeps. You can set a second \** between a \** and its corresponding .FS; as long as each .FS occurs after the corresponding \** and the occurrences of .FS are in the same order as the corresponding occurrences of \**.

### Headers and footers
There are three ways to define headers and footers:

- Use the strings LH, CH, and RH to set the left, center, and right headers; use LF, CF, and RF to set the left, center, and right footers. This works best for documents that do not distinguish between odd and even pages.

- Use the OH and EH macros to define headers for the odd and even pages; and OF and EF macros to define footers for the odd and even pages. This is more flexible than defining the individual strings. The syntax for these macros is as follows:

.OH 'left'center'right'

You can replace the quote (') marks with any character not appearing in the header or footer text.

You can also redefine the PT and BT macros to change the behavior of the header and footer, respectively. The header process also calls the (undefined) HD macro after PT ; you can define this macro if you need additional processing after printing the header (for example, to draw a line below the header).

### Margins
You control margins using a set of number registers. The following table lists the register names and defaults:

Reg.

Definition

Effective

Default

PO

Page offset (left margin)

next page

1i

LL

Line length

next paragraph

6i

LT

Header/footer length

next paragraph

6i

HM

Top (header) margin

next page

1i

FM

Bottom (footer) margin

next page

1i

Note that there is no right margin setting. The combination of page offset and line length provide the information necessary to derive the right margin.

### Multiple columns
The ms macros can set text in as many columns as will 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.

.1C

Single-column mode.

.2C

Two-column mode.

.MC [width [gutter]]

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 MINGW number register is the default gutter width.

### Creating a table of contents
Wrap text that you want to appear in the table of contents in XS and XE macros. Use the TC macro to print the table of contents at the end of the document, resetting the page number to i (Roman numeral 1).

You can manually create a table of contents by specifying a page number as the first argument to XS. Add subsequent entries using the XA macro. For example:

```
.XS 1
Introduction
.XA 2
A Brief History of the Universe
.XA 729
Details of Galactic Formation
...
.XE
```

Use the PX macro to print a manually-generated table of contents without resetting the page number.

If you give the argument no to either PX or TC, groff suppresses printing the title specified by the \*[TOC] string.

### Fractional point sizes
Traditionally, the ms macros only support integer values for the document's font size and vertical spacing. To overcome this restriction, values larger than or equal to 1000 are taken as fractional values, multiplied by 1000. For example, ‘.nr PS 10250’ sets the font size to 10.25 points.

The following four registers accept fractional point sizes: PS, VS, FPS, and FVS.

Due to backwards compatibility, the value of VS must be smaller than 40000 (this is 40.0 points).

## DIFFERENCES FROM troff ms
The groff ms macros are a complete re-implementation, using no original AT&T code. Since they take advantage of the extended features in groff, they cannot be used with AT&T troff. Other differences include:

- The internals of groff ms differ from the internals of Unix ms. Documents that depend upon implementation details of Unix ms may not format properly with groff ms.

- The error-handling policy of groff ms is to detect and report errors, rather than silently to ignore them.

- Some Bell Labs localisms are not implemented by default. However, if you call the otherwise undocumented SC section-header macro, you will enable implementations of three other archaic Bell Labs macros: UC, P1, and P2. These are not enabled by default because (a) they were not documented, in the original ms manual, and (b) the P1 and UC macros both collide with different macros in the Berkeley version of ms.

These emulations are sufficient to give back the 1976 Kernighan & Cherry paper Typesetting Mathematics – User's Guide its section headings, and restore some text that had gone missing as arguments of undefined macros. No warranty express or implied is given as to how well the typographic details these produce match the original Bell Labs macros.

- Berkeley localisms, in particular the TM and CT macros, are not implemented.

- Groff ms does not work in compatibility mode (e.g., with the -C option).

- There is no support for typewriter-like devices.

- Groff ms does not provide cut marks.

- Multiple line spacing is not supported (use a larger vertical spacing instead).

- Some Unix ms documentation says that the CW and GW number registers can be used to control the column width and gutter width, respectively. These number registers are not used in groff ms.

- Macros that cause a reset (paragraphs, headings, etc.) may change the indent. Macros that change the indent do not increment or decrement the indent, but rather set it absolutely. This can cause problems for documents that define additional macros of their own. The solution is to use not the in request but instead the RS and RE macros.

- The number register GS is set to 1 by the groff ms macros, but is not used by the Unix ms macros. Documents that need to determine whether they are being formatted with Unix ms or groff ms should use this number register.

- To make groff ms use the default page offset (which also specifies the left margin), the PO number register must stay undefined until the first ms macro is evaluated. This implies that PO should not be used early in the document, unless it is changed also: Remember that accessing an undefined register automatically defines it.

### Strings
You can redefine the following strings to adapt the groff ms macros to languages other than English:

String

Default Value

REFERENCES

References

ABSTRACT

ABSTRACT

TOC

Table of Contents

MONTH1

January

MONTH2

February

MONTH3

March

MONTH4

April

MONTH5

May

MONTH6

June

MONTH7

July

MONTH8

August

MONTH9

September

MONTH10

October

MONTH11

November

MONTH12

December

The \*- string produces an em dash — like this.

Use \*Q and \*U to get a left and right typographer's quote, respectively, in troff (and plain quotes in nroff).

### Text Settings
The FAM string sets the default font family. If this string is undefined at initialization, it is set to Times.

The point size, vertical spacing, and inter-paragraph spacing for footnotes are controlled by the number registers FPS, FVS, and FPD; at initialization these are set to \n(PS-2, \n[FPS]+2, and \n(PD/2, respectively. If any of these registers are defined before initialization, the initialization macro does not change them.

The hyphenation flags (as set by the hy request) are set from the HY register; the default is 14.

Improved accent marks (as originally defined in Berkeley's ms version) are available by specifying the AM macro at the beginning of your document. You can place an accent over most characters by specifying the string defining the accent directly after the character. For example, n\*~ produces an n with a tilde over it.

## NAMING CONVENTIONS
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.

Internally the macros are divided into modules; naming conventions are as follows:

- Names used only within one module are of the form module*name.

- Names used outside the module in which they are defined are of the form module@name.

- Names associated with a particular environment are of the form environment:name; these are used only within the par module.

- name does not have a module prefix.

- Constructed names used to implement arrays are of the form array!index.

Thus the groff ms macros reserve the following names:

- Names containing the characters *, @, and :.

- Names containing only uppercase letters and digits.

## FILES
/usr/share/groff/1.22.3/tmac/ms.tmac (a wrapper file for s.tmac)

/usr/share/groff/1.22.3/tmac/s.tmac

## SEE ALSO
groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1), Groff: The GNU Implementation of troff by Trent Fisher and Werner Lemberg.

## COPYING
Copyright © 1989-2014 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

## AUTHORS
Original manual page by James Clark et al, rewritten by Larry Kollar.


package: groff-extra

title: groff_trace(7)

summary: groff macro package trace.tmac

text:
# groff_trace(7)

## NAME
groff_trace - groff macro package trace.tmac

## SYNOPSIS
groff -m trace

[options ...] [files ...]

## DESCRIPTION
The trace macro package of groff(1) can be a valuable tool for debugging documents written in the roff formatting language. A call stack trace is protocolled on standard error, this is, a diagnostic message is emitted on entering and exiting of a macro call. This greatly eases to track down an error in some macro.

This tracing process is activated by specifying the groff or troff command line option -m trace. This works also with the groffer(1) viewer program. A finer control can be obtained by including the macro file within the document by the groff macro call .mso trace.tmac. Only macros that are defined after this line are traced.

If command line option -r trace-full=1 is given (or if this register is set in the document), number and string register assignments together with some other requests are traced also.

If some other macro package should be traced as well it must be specified after -m trace on the command line.

The macro file trace.tmac is unusual because it does not contain any macros to be called by a user. Instead, the existing macro definition and appending facilities are modified such that they display diagnostic messages.

## EXAMPLES
In the following examples, a roff fragment is fed into groff via standard input. As we are only interested in the diagnostic messages (standard error) on the terminal, the normal formatted output (standard output) is redirected to the nirvana device /dev/null. The resulting diagnostic messages are displayed directly below the corresponding example.

### Command line option
Example:

```
sh# echo '.
> .de test_macro
> ..
> .test_macro
> .test_macro some dummy arguments
> ' | groff -m trace > /dev/null
*** .de test_macro
*** de trace enter: .test_macro
*** trace exit: .test_macro
*** de trace enter: .test_macro "some" "dummy" "arguments"
*** trace exit: .test_macro "some" "dummy" "arguments"
```

The entry and the exit of each macro call is displayed on the terminal (standard output) — together with the arguments (if any).

### Nested macro calls
Example:

```
sh# echo '.
> .de child
> ..
> .de parent
> .child
> ..
> .parent
> ' | groff -m trace > /dev/null
*** .de child
*** .de parent
*** de trace enter: .parent

 *** de trace enter: .child

 *** trace exit: .child
*** trace exit: .parent
```

This shows that macro calls can be nested. This powerful feature can help to tack down quite complex call stacks.

### Activating with .mso
Example:

```
sh# echo '.
> .de before
> ..
> .mso trace.tmac
> .de after
> ..
> .before
> .after
> .before
> ' | groff > /dev/null
*** de trace enter: .after
*** trace exit: .after
```

Here, the tracing is activated within the document, not by a command line option. As tracing was not active when macro before was defined, no call of this macro is protocolled; on the other hand, the macro after is fully protocolled.

## PROBLEMS
Because trace.tmac wraps the .de request (and its cousins), macro arguments are expanded one level more. This causes problems if an argument contains four backslashes or more to prevent too early expansion of the backslash. For example, this macro call

```
.foo \\\\n[bar]

```

normally passes ‘\\n[bar]’ to macro ‘.foo’, but with the redefined .de request it passes ‘\n[bar]’ instead.

The solution to this problem is to use groff's \E escape which is an escape character not interpreted in copy mode, for example

```
.foo \En[bar]

```

## FILES
The trace macros are kept in the file trace.tmac located in the tmac directory; see groff_tmac(5) for details.

## ENVIRONMENT
$GROFF_TMAC_PATH

A colon-separated list of additional tmac directories in which to search for macro files; see groff_tmac(5) for details.

## SEE ALSO
groff(1)

An overview of the groff system.

troff(1)

For details on option -m.

groffer(1)

A viewer program for all kinds of roff documents.

groff_tmac(5)

A general description of groff macro packages.

groff(7)

A short reference for the groff formatting language.

A complete reference for all parts of the groff system is found in the groff info(1) file.

## COPYING
Copyright © 2002-2014 Free Software Foundation, Inc.

This file is part of groff, the GNU roff type-setting system.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being this .ig-section and AUTHOR, with no Front-Cover Texts, and with no Back-Cover Texts.

A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package.

## AUTHORS
Written by Bernd Warken.


title: groff_www(7)

summary: groff macros for authoring web pages

text:
# groff_www(7)

## NAME
groff_www - groff macros for authoring web pages

## SYNOPSIS
groff -mwww [ options ] file ...

## DESCRIPTION
This manual page describes the GNU -mwww macro package, which is part of the groff document formatting system. The manual page is very a basic guide, and the html device driver (grohtml) has been completely rewritten but still remains as in an alpha state. It has been included into the distribution so that a lot of people have a chance to test it. Note that this macro file is automatically called (via the troffrc file) if you use -Thtml or -Txhtml.

To see the hyperlinks in action, please format this man page with the grohtml device.

Here is a summary of the functions found in this macro set.

.JOBNAME

split output into multiple files

.HX

automatic heading level cut off

.BCL

specify colours on a web page

.BGIMG

specify background image

.URL

create a url using two parameters

.FTP

create an ftp reference

.MTO

create a html email address

.FTP

create an ftp reference

.TAG

generate an html name

.IMG

include an image file

.PIMG

include png image

.MPIMG

place png on the margin and wrap text around it

.HnS

begin heading

.HnE

end heading

.LK

emit automatically collected links.

.HR

produce a horizontal rule

.NHR

suppress automatic generation of rules.

.HTL

only generate HTML title

.HEAD

add data to <head> block

.ULS

unorder list begin

.ULE

unorder list end

.OLS

ordered list begin

.OLE

ordered list end

.DLS

definition list begin

.DLE

definition list end

.LI

insert a list item

.DC

generate a drop capital

.HTML

pass an html raw request to the device driver

.CDS

code example begin

.CDE

code example end

.ALN

place links on left of main text.

.LNS

start a new two-column table with links in the left.

.LNE

end the two-column table.

.LINKSTYLE

initialize default url attributes.

Output of the pic, eqn, refer, and tbl preprocessors is acceptable as input.

## REQUESTS
.JOBNAME filename

Split output into multiple HTML files. A file is split whenever a .SH or .NH 1 is encountered. Its argument is the file stem name for future output files. This option is equivalent to grohtml's -j option.

.HX n

Specify the cut off depth when generating links from section headings. For example, a parameter of 2 would cause grohtml to generate a list of links for .NH 1 and .NH 2 but not for .NH 3. Whereas

```
.HX 0
```

tells grohtml that no heading links should be created at all. Another method for turning automatic headings off is by issuing the the command line switch -P-l to groff.

.BCL foreground background active not-visited visited

This macro takes five parameters: foreground, background, active hypertext link, hypertext link not yet visited, and visited hypertext link colour.

.BGIMG imagefile

the only parameter to this macro is the background image file.

.URL url [description] [after]

generates a URL using either one, two or three arguments. The first parameter is the actual URL, the second is the name of the link, and the third is optional stuff to be printed immediately afterwards. If description and after are absent then the url becomes the anchor text. Hyphenation is disabled while printing the actual URL; explicit breakpoints should be inserted with the \: escape. Here is how to encode

.URL http://\:foo.\:org/ foo :

If this is processed by a device other than -Thtml or -Txhtml it appears as:

foo ⟨http://foo.org⟩:

The URL macro can be of any type; for example we can reference by:

.URL pic.html "Eric Raymond's pic guide"

.MTO address [description] [after]

Generate an email html reference. The first argument is mandatory as the email address. The optional second argument is the text you see in your browser. If an empty argument is given, address is used instead. An optional third argument is stuff printed immediately afterwards. Hyphenation is disabled while printing the actual email address. For example, was achieved by the following macro:

.MTO joe@user.org "Joe User"

Note that all the URLs actually are treated as consuming no textual space in groff. This could be considered as a bug since it causes some problems. To circumvent this, www.tmac inserts a zero-width character which expands to a harmless space (only if run with -Thtml or -Txhtml).

.FTP url [description] [after]

indicates that data can be obtained via ftp. The first argument is the url and the second is the browser text. A third argument, similar to the macros above, is intended for stuff printed immediately afterwards. The second and the third parameter are optional. Hyphenation is disabled while printing the actual URL. As an example, here the location of the The macro example above was specified by:

.FTP ftp://\:ftp.gnu.org/ "GNU ftp server" .

.TAG name

Generates an html name tag from its argument. This can then be referenced using the macro. As you can see, you must precede the tag name with # since it is a local reference. This link was achieved via placing a TAG in the URL description above; the source looks like this:

```
.TP
.B URL
generates
.TAG URL
a URL using either two or three arguments.
...
```

.IMG [-R|-L|-C] filename [width] [height]

Include a picture into the document. The first argument is the horizontal location: right, left, or center (-R, -L, or -C). Alignment is centered by default (-C). The second argument is the filename. The optional third and fourth arguments are the width and height. If the width is absent it defaults to 1 inch. If the height is absent it defaults to the width. This maps onto an html img tag. If you are including a png image then it is advisable to use the PIMG macro.

.PIMG [-R|-L|-C] filename [width [height]]

Include an image in PNG format. This macro takes exactly the same parameters as the IMG macro; it has the advantage of working with postscript and html devices also since it can automatically convert the image into the EPS format, using the following programs of the netpbm package: pngtopnm, pnmcrop, and pnmtops. If the document isn't processed with -Thtml or -Txhtml it is necessary to use the -U option of groff.

.MPIMG [-R|-L] [-G gap] filename [width [height]]

Place a PNG image on the margin and wrap text around it. The first parameters are optional. The alignment: left or right (-L or -R) specifies the margin where the picture is placed at. The default alignment is left (-L). Optionally, -G gap can be used to arrange a gap between the picture and the text that wraps around it. The default gap width is zero.

The first non-optional argument is the filename. The optional following arguments are the width and height. If the width is absent it defaults to 1 inch. If the height is absent it defaults to the width. Example:

```
.MPIMG -L -G 2c foo.png 3c 1.5c

```

The height and width may also be given as percentages. The PostScript device calculates the width from the .l register and the height from the .p register. For example:

```
.MPIMG -L -G 2c foo.png 15%

```

.HnS n

Begin heading. The numeric heading level n is specified by the first parameter. Use this macro if your headings contain URL, FTP or MTO macros. Example:

```
.HnS 1
.HR
GNU Troff
.URL http://groff.ffii.org (Groff)
— a
.URL http://www.gnu.org/ GNU
project.
Hosted by
.URL http://ffii.org/ FFII .
.HR
.HnE

```

In this case you might wish to disable automatic links to headings. This can be done via -P-l from the command line.

.HnE

End heading.

.LK

Force grohtml to place the automatically generated links at this position. If this manual page has been processed with -Thtml or -Txhtml those links can be seen right here.

.HR

Generate a full-width horizontal rule for -Thtml and -Txhtml. No effect for all other devices.

.NHR

Suppress generation of the top and bottom rules which grohtml emits by default.

.HTL

Generate an HTML title only. This differs from the TL macro of the ms macro package which generates both an HTML title and an <H1> heading. Use it to provide an HTML title as search engine fodder but a graphic title in the document. The macro terminates when a space or break is seen (.sp, .br).

.HEAD

Add arbitrary HTML data to the <head> block. Ignored if not processed with -Thtml or -Txhtml. Example:

```
.HEAD "<link \
  rel=""icon"" \
  type=""image/png"" \
  href=""http://foo.org//bar.png""/>"
```

.HTML

All text after this macro is treated as raw html. If the document is processed without -Thtml or -Txhtml then the macro is ignored. Internally, this macro is used as a building block for other higher-level macros.

For example, the BGIMG macro is defined as

```
.de BGIMG
.   HTML <body background=\\$1>
..

```

.DC l text [color]

Produce a drop capital. The first parameter is the letter to be dropped and enlarged, the second parameter text is the adjoining text whose height the first letter should not exceed. The optional third parameter is the color of the dropped letter. It defaults to black.

.CDS

Start displaying a code section in constant width font.

.CDE

End code display

.ALN [color] [percentage]

Place section heading links automatically to the left of the main text. The color argument is optional and if present indicates which HTML background color is to be used under the links. The optional percentage indicates the amount of width to devote to displaying the links. The default values are #eeeeee and 30 for color and percentage width, respectively. This macro should only be called once at the beginning of the document. After calling this macro each section heading emits an HTML table consisting of the links in the left and the section text on the right.

.LNS

Start a new two-column table with links in the left column. This can be called if the document has text before the first .SH and if .ALN is used. Typically this is called just before the first paragraph and after the main title as it indicates that text after this point should be positioned to the right of the left-hand navigational links.

.LNE

End a two-column table. This should be called at the end of the document if .ALN was used.

.LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]

Initialize default url attributes to be used if this macro set is not used with the HTML device. The macro set initializes itself with the following call

```
.LINKSTYLE blue C \[la] \[ra]

```

but these values will be superseded by a user call to LINKSTYLE.

## SECTION HEADING LINKS
By default grohtml generates links to all section headings and places these at the top of the html document. (See for details of how to switch this off or alter the position).

## LIMITATIONS OF GROHTML
tbl information is currently rendered as a PNG image.

## FILES
/usr/share/groff/1.22.3/tmac/www.tmac

## BUGS
Report bugs to the Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of groff you are using.

## SEE ALSO
groff(1), troff(1) grohtml(1), netpbm(1)

## COPYING
Copyright © 2000-2014 Free Software Foundation, Inc.

This file is part of groff.

groff is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

groff is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see GPLs.

## AUTHORS
grohtml was written by


roff

title: roff(7)

text:
# roff(7)

## NAME
roff - concepts and history of roff typesetting

## DESCRIPTION
roff is the general name for a set of text formatting programs, known under names like troff, nroff, ditroff, groff, etc. A roff system consists of an extensible text formatting language and a set of programs for printing and converting to other text formats. Unix-like operating systems distribute a roff system as a core package.

The most common roff system today is the free software implementation GNU roff, groff(1). groff implements the look-and-feel and functionality of its ancestors, with many extensions.

The ancestry of roff is described in section HISTORY. In this document, the term roff always refers to the general class of roff programs, not to the roff command provided in early UNIX systems.

In spite of its age, roff is in wide use today, for example, the manual pages on UNIX systems (man pages), many software books, system documentation, standards, and corporate documents are written in roff. The roff output for text devices is still unmatched, and its graphical output has the same quality as other free type-setting programs and is better than some of the commercial systems.

roff is used to format UNIX manual pages, (or man pages), the standard documentation system on many UNIX-derived operating systems.

This document describes the history of the development of the roff system; some usage aspects common to all roff versions, details on the roff pipeline, which is usually hidden behind front-ends like groff(1); a general overview of the formatting language; some tips for editing roff files; and many pointers to further readings.

## HISTORY
Document formatting by computer dates back to the 1960s. The roff system itself is intimately connected to the Unix operating system, but its roots go back to the earlier operating systems CTSS and Multics.

### The Predecessor RUNOFF
roff's ancestor RUNOFF was written in the MAD language by Jerry Saltzer for the Compatible Time Sharing System (CTSS), a project of the Massachusetts Institute of Technology (MIT), in 1963 and 1964 – note that CTSS commands were all uppercase.

In 1965, MIT's Project MAC teamed with Bell Telephone Laboratories (BTL) and General Electric to begin the Multics system. A command called runoff was written for Multics in the late 60s in the BCPL language, by Bob Morris, Doug McIlroy, and other members of the Multics team.

Like its CTSS ancestor, Multics runoff formatted an input file consisting of text and command lines; commands began with a period and were two letters. Output from these commands was to terminal devices such as IBM Selectric terminals. Multics runoff had additional features added, such as the ability to do two-pass formatting; it became the main format for Multics documentation and text processing.

BCPL and runoff were ported to the GCOS system at Bell Labs when BTL left the development of Multics.

There is a free archive about historical RUNOFF documents. You can get it anonymously by the shell command

```
$git clone https://github.com/bwarken/RUNOFF_historical.git
```

As well, there is a new project for writing a program that can read RUNOFF files , but it does not yet work so far. You can get an early version anonymously by the shell command

```
$git clone https://github.com/bwarken/runoff.git
```

### The Classical nroff/troff System
At BTL, there was a need to drive the Graphic Systems CAT typesetter, a graphical output device from a PDP-11 computer running Unix. As runoff was too limited for this task it was further developed into a more powerful text formatting system by Joseph F. Ossanna, who already programmed several runoff ports.

The name runoff was shortened to roff. The greatly enlarged language of Ossanna's version already included all elements of a full roff system. All modern roff systems try to implement compatibility to this system. So Joe Ossanna can be called the father of all roff systems.

This first roff system had three formatter programs.

troff

(typesetter roff) generated a graphical output for the CAT typesetter as its only device.

nroff

produced text output suitable for terminals and line printers.

roff

was the reimplementation of the former runoff program with its limited features; this program was abandoned in later versions. Today, the name roff is used to refer to a troff/nroff system as a whole.

Ossanna's first version was written in the PDP-11 assembly language and released in 1973. Brian Kernighan joined the roff development by rewriting it in the C programming language. The C version was released in 1975.

The syntax of the formatting language of the nroff/troff programs was documented in the famous Troff User's Manual [CSTR #54], first published in 1976, with further revisions up to 1992 by Brian Kernighan. This document is the specification of the classical troff. All later roff systems tried to establish compatibility with this specification.

After Ossanna's death in 1977, Kernighan went on with developing troff. In the late 1970s, Kernighan equipped troff with a general interface to support more devices, the intermediate output format, and the postprocessor system. This completed the structure of a roff system as it is still in use today; see section USING ROFF. In 1979, these novelties were described in the paper [CSTR #97]. This new troff version is the basis for all existing newer troff systems, including groff. On some systems, this device independent troff got a binary of its own, called ditroff(7). All modern troff programs already provide the full ditroff capabilities automatically.

### Availability
The source code of both the ancient Unix and classical troff weren't available for two decades. Meanwhile, it is accessible again (on-line) for non-commercial use, cf. section SEE ALSO.

### groff — free GNU roff
The most important free roff project was the GNU implementation of troff, written from scratch by James Clark and put under the GNU Public License. It was called groff (GNU roff). See groff(1) for an overview.

The groff system is still actively developed. It is compatible to the classical troff, but many extensions were added. It is the first roff system that is available on almost all operating systems — and it is free. This makes groff the de-facto roff standard today.

### Free Heirloom roff
An alternative is Gunnar Ritter's Heirloom roff project project, started in 2005, which provides enhanced versions of the various roff tools found in the OpenSolaris and Plan 9 operating systems, now available under free licenses. You can get this package with the shell command:

```
$ git clone https://github.com/n-t-roff/heirloom-doctools
```

Moreover, one finds there the Original Documenter's Workbench Release 3.3.

## USING ROFF
Most people won't even notice that they are actually using roff. When you read a system manual page (man page) roff is working in the background. roff documents can be viewed with a native viewer called xditview(1x), a standard program of the X window distribution, see X(7x). But using roff explicitly isn't difficult either.

Some roff implementations provide wrapper programs that make it easy to use the roff system on the shell command line. For example, the GNU roff implementation groff(1) provides command line options to avoid the long command pipes of classical troff; a program grog(1) tries to guess from the document which arguments should be used for a run of groff; people who do not like specifying command line options should try the groffer(1) program for graphically displaying groff files and man pages.

### The roff Pipe
Each roff system consists of preprocessors, roff formatter programs, and a set of device postprocessors. This concept makes heavy use of the piping mechanism, that is, a series of programs is called one after the other, where the output of each program in the queue is taken as the input for the next program.

cat file | ... | preproc | ... | troff options | postproc

The preprocessors generate roff code that is fed into a roff formatter (e.g. troff), which in turn generates intermediate output that is fed into a device postprocessor program for printing or final output.

All of these parts use programming languages of their own; each language is totally unrelated to the other parts. Moreover, roff macro packages that were tailored for special purposes can be included.

Most roff documents use the macros of some package, intermixed with code for one or more preprocessors, spiced with some elements from the plain roff language. The full power of the roff formatting language is seldom needed by users; only programmers of macro packages need to know about the gory details.

### Preprocessors
A roff preprocessor is any program that generates output that syntactically obeys the rules of the roff formatting language. Each preprocessor defines a language of its own that is translated into roff code when run through the preprocessor program. Parts written in these languages may be included within a roff document; they are identified by special roff requests or macros. Each document that is enhanced by preprocessor code must be run through all corresponding preprocessors before it is fed into the actual roff formatter program, for the formatter just ignores all alien code. The preprocessor programs extract and transform only the document parts that are determined for them.

There are a lot of free and commercial roff preprocessors. Some of them aren't available on each system, but there is a small set of preprocessors that are considered as an integral part of each roff system. The classical preprocessors are

tbl

for tables.

eqn

for mathematical formulae.

pic

for drawing diagrams.

refer

for bibliographic references.

soelim

for including macro files from standard locations.

chem

for drawing chemical formulæ.

Other known preprocessors that are not available on all systems include

grap

for constructing graphical elements.

grn

for including gremlin(1) pictures.

### Formatter Programs
A roff formatter is a program that parses documents written in the roff formatting language or uses some of the roff macro packages. It generates intermediate output, which is intended to be fed into a single device postprocessor that must be specified by a command-line option to the formatter program. The documents must have been run through all necessary preprocessors before.

The output produced by a roff formatter is represented in yet another language, the intermediate output format or troff output. This language was first specified in [CSTR #97]; its GNU extension is documented in groff_out(5). The intermediate output language is a kind of assembly language compared to the high-level roff language. The generated intermediate output is optimized for a special device, but the language is the same for every device.

The roff formatter is the heart of the roff system. The traditional roff had two formatters, nroff for text devices and troff for graphical devices.

Often, the name troff is used as a general term to refer to both formatters.

### Devices and Postprocessors
Devices are hardware interfaces like printers, text or graphical terminals, etc., or software interfaces such as a conversion into a different text or graphical format.

A roff postprocessor is a program that transforms troff output into a form suitable for a special device. The roff postprocessors are like device drivers for the output target.

For each device there is a postprocessor program that fits the device optimally. The postprocessor parses the generated intermediate output and generates device-specific code that is sent directly to the device.

The names of the devices and the postprocessor programs are not fixed because they greatly depend on the software and hardware abilities of the actual computer. For example, the classical devices mentioned in [CSTR #54] have greatly changed since the classical times. The old hardware doesn't exist any longer and the old graphical conversions were quite imprecise when compared to their modern counterparts.

For example, the Postscript device post in classical troff had a resolution of 720 units per inch, while groff's ps device has 72000, a refinement of factor 100.

Today the operating systems provide device drivers for most printer-like hardware, so it isn't necessary to write a special hardware postprocessor for each printer.

## ROFF PROGRAMMING
Documents using roff are normal text files decorated by roff formatting elements. The roff formatting language is quite powerful; it is almost a full programming language and provides elements to enlarge the language. With these, it became possible to develop macro packages that are tailored for special applications. Such macro packages are much handier than plain roff. So most people will choose a macro package without worrying about the internals of the roff language.

### Macro Packages
Macro packages are collections of macros that are suitable to format a special kind of documents in a convenient way. This greatly eases the usage of roff. The macro definitions of a package are kept in a file called name.tmac (classically tmac.name). All tmac files are stored in one or more directories at standardized positions. Details on the naming of macro packages and their placement is found in groff_tmac(5).

A macro package that is to be used in a document can be announced to the formatter by the command line option -m, see troff(1), or it can be specified within a document using the file inclusion requests of the roff language, see groff(7).

Famous classical macro packages are man for traditional man pages, mdoc for BSD-style manual pages; the macro sets for books, articles, and letters are me (probably from the first name of its creator Eric Allman), ms (from Manuscript Macros), and mm (from Memorandum Macros).

### The roff Formatting Language
The classical roff formatting language is documented in the Troff User's Manual [CSTR #54]. The roff language is a full programming language providing requests, definition of macros, escape sequences, string variables, number or size registers, and flow controls.

Requests are the predefined basic formatting commands similar to the commands at the shell prompt. The user can define request-like elements using predefined roff elements. These are then called macros. A document writer will not note any difference in usage for requests or macros; both are written on a line on their own starting with a dot.

Escape sequences are roff elements starting with a backslash ‘\’. They can be inserted anywhere, also in the midst of text in a line. They are used to implement various features, including the insertion of non-ASCII characters with \(, font changes with \f, in-line comments with \", the escaping of special control characters like \\, and many other features.

Strings are variables that can store a string. A string is stored by the .ds request. The stored string can be retrieved later by the \* escape sequence.

Registers store numbers and sizes. A register can be set with the request .nr and its value can be retrieved by the escape sequence \n.

## FILE NAME EXTENSIONS
Manual pages (man pages) take the section number as a file name extension, e.g., the filename for this document is roff.7, i.e., it is kept in section 7 of the man pages.

The classical macro packages take the package name as an extension, e.g. file.me for a document using the me macro package, file.mm for mm, file.ms for ms, file.pic for pic files, etc.

But there is no general naming scheme for roff documents, though file.tr for troff file is seen now and then. Maybe there should be a standardization for the filename extensions of roff files.

File name extensions can be very handy in conjunction with the less(1) pager. It provides the possibility to feed all input into a command-line pipe that is specified in the shell environment variable LESSOPEN. This process is not well documented, so here an example:

```
LESSOPEN='|lesspipe %s'
```

where lesspipe is either a system supplied command or a shell script of your own.

More details for file name extensions can be found at groff_filenames(7).

## EDITING ROFF
The best program for editing a roff document is Emacs (or Xemacs), see emacs(1). It provides an nroff mode that is suitable for all kinds of roff dialects. This mode can be activated by the following methods.

When editing a file within Emacs the mode can be changed by typing ‘M-x nroff-mode’, where M-x means to hold down the Meta key (or Alt) and hitting the x key at the same time.

But it is also possible to have the mode automatically selected when the file is loaded into the editor.

•

The most general method is to include the following 3 comment lines at the end of the file.

```
.\" Local Variables:
.\" mode: nroff
.\" End:

```

- There is a set of file name extensions, e.g. the man pages that trigger the automatic activation of the nroff mode.

- Theoretically, it is possible to write the sequence

```
.\" -*- nroff -*-

```

as the first line of a file to have it started in nroff mode when loaded. Unfortunately, some applications such as the man program are confused by this; so this is deprecated.

All roff formatters provide automated line breaks and horizontal and vertical spacing. In order to not disturb this, the following tips can be helpful.

- Never include empty or blank lines in a roff document. Instead, use the empty request (a line consisting of a dot only) or a line comment .\" if a structuring element is needed.

- Never start a line with whitespace because this can lead to unexpected behavior. Indented paragraphs can be constructed in a controlled way by roff requests.

- Start each sentence on a line of its own, for the spacing after a dot is handled differently depending on whether it terminates an abbreviation or a sentence. To distinguish both cases, do a line break after each sentence.

- To additionally use the auto-fill mode in Emacs, it is best to insert an empty roff request (a line consisting of a dot only) after each sentence.

The following example shows how optimal roff editing could look.

```
This is an example for a .I roff document.  .
This is the next sentence in the same paragraph.  .
This is a longer sentence stretching over several lines; abbreviations
like ‘cf.’ are easily identified because the dot is not
followed by a line break.  .  In the output, this will still go to
the same paragraph.
```

Besides Emacs, some other editors provide nroff style files too, e.g. vim(1), an extension of the vi(1) program.

## SEE ALSO
There is a lot of documentation on roff. The original papers on classical troff are still available, and all aspects of groff are documented in great detail.

### Internet sites
troff.org

The historical troff site provides an overview and pointers to all historical aspects of roff.

Multics

The Multics site contains a lot of information on the MIT projects, CTSS, Multics, early Unix, including runoff; especially useful are a glossary and the many links to ancient documents.

Unix Archive

The Ancient Unixes Archive provides the source code and some binaries of the ancient Unixes (including the source code of troff and its documentation) that were made public by Caldera since 2001, e.g. of the famous Unix version 7 for PDP-11 at the Unix V7 site.

Developers at AT&T Bell Labs

Bell Labs Computing and Mathematical Sciences Research provides a search facility for tracking information on the early developers.

Plan 9

The Plan 9 operating system by AT&T Bell Labs.

runoff

Jerry Saltzer's home page stores some documents using the ancient RUNOFF formatting language.

CSTR Papers

The Bell Labs CSTR site stores the original troff manuals (CSTR #54, #97, #114, #116, #122) and famous historical documents on programming.

GNU roff

The groff web site provides the free roff implementation groff, the actual standard roff.

### Historical roff Documentation
Many classical troff documents are still available on-line. The two main manuals of the troff language are

[CSTR #54]

J. F. Ossanna, Nroff/Troff User's Manual; Bell Labs, 1976; revised by Brian Kernighan, 1992.

[CSTR #97]

Brian Kernighan, A Typesetter-independent TROFF, Bell Labs, 1981, revised March 1982.

The “little language” roff papers are

[CSTR #114]

Jon L. Bentley and Brian W. Kernighan, GRAP – A Language for Typesetting Graphs; Bell Labs, August 1984.

[CSTR #116]

Brian W. Kernighan, PIC – A Graphics Language for Typesetting; Bell Labs, December 1984.

[CSTR #122]

J. L. Bentley, L. W. Jelinski, and B. W. Kernighan, CHEM – A Program for Typesetting Chemical Structure Diagrams, Computers and Chemistry; Bell Labs, April 1986.

You can get an archive with most classical roff documentation as reasonable PDF files at github using the shell command

```
$ git clone https://github.com/bwarken/roff_classical.git
```

### Manual Pages
Due to its complex structure, a full roff system has many man pages, each describing a single aspect of roff. Unfortunately, there is no general naming scheme for the documentation among the different roff implementations.

In groff, the man page groff(1) contains a survey of all documentation available in groff.

On other systems, you are on your own, but troff(1) might be a good starting point.

## COPYING
Copyright © 2000-2014 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the FDL (GNU Free Documentation License) Version 1.3 or any later version published by the Free Software Foundation. with the Invariant Sections being the .au and .co macro definitions, with no Front-Cover Texts, and with no Back-Cover Texts.

A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package.

The license text is also available on-line at the GNU copyleft site.

## AUTHORS
This man-page was written by Bernd Warken and is maintained by Werner Lemberg.


gvfs

package: gvfs

title: gvfs(7)

summary: GIO virtual file system

text:
# gvfs(7)

## NAME
gvfs - GIO virtual file system

## DESCRIPTION
GIO provides a VFS API to GLib applications. It includes a 'local' implementation using POSIX. gvfs provides implementations that go beyond that and allow to access files and storage using many protocols, such as ftp, http, sftp, dav, nfs, etc. It also provides support for trash folders, for cd burning and for monitoring interesting devices and volumes on the computer.

Applications use gvfs indirectly, by means of GIO loading the gvfs module that implements the GIO extension points. The gvfs support for volume monitoring is included in a separate loadable module.

The actual gvfs implementation is distributed over a number of processes. None of these are expected to be started from the commandline, except for debugging purposes.

Main processes:

•gvfsd - the main gvfs daemon

•gvfsd-fuse - mounts gvfs as a fuse filesystem

•gvfsd-metadata - writes gvfs metadata

Volume monitors:

•gvfs-afc-volume-monitor - a volume monitor for Apple iPhone/iPod Touch devices

•gvfs-goa-volume-monitor - a volume monitor for GNOME Online Accounts

•gvfs-gphoto2-volume-monitor - a volume monitor for PTP devices

•gvfs-mtp-volume-monitor - a volume monitor for MTP devices

•gvfs-udisks2-volume-monitor - a udisks2-based volume monitor

Mount backends:

•gvfsd-admin - mounts local filesystem with admin privileges

•gvfsd-afc - mounts iPhone/iPod touch volumes

•gvfsd-afp - mounts Apple Filing Protocol volumes

•gvfsd-afp-browse - browses Apple Filing Protocol volumes

•gvfsd-archive - mounts archive files in various formats

•gvfsd-burn - provides a location for burning CDs

•gvfsd-cdda - mounts audio CDs

•gvfsd-computer - provides computer://

•gvfsd-dav - mounts DAV filesystems

•gvfsd-dnssd - browses dnssd

•gvfsd-ftp - mounts over FTP

•gvfsd-google - mounts Google Drive shares

•gvfsd-gphoto2 - mounts over PTP

•gvfsd-http - mounts over HTTP

•gvfsd-localtest - a test backend

•gvfsd-mtp - mounts over MTP

•gvfsd-network - provides network://

•gvfsd-nfs - mounts over NFS

•gvfsd-recent - provides recent://

•gvfsd-sftp - mounts over sftp

•gvfsd-smb - mounts Windows Shares Filesystem volumes

•gvfsd-smb-browse - browses Windows Shares Filesystem volumes

•gvfsd-trash - provides trash://

## ENVIRONMENT
GIO_USE_VFS

If set, specifies the GIO vfs implementation to use. Possible values include 'local' and 'gvfs'.

GIO_USE_VOLUME_MONITOR

If set, specifies the GIO volume monitor implementation to use. Possible values include 'unix', 'GProxyVolumeMonitorUDisks2', as well as other native volume monitors that are described in the key files in $XDG_DATA_DIRS/gvfs/remote-volume-monitors.

## FILES
$XDG_DATA_DIRS/gvfs/mounts

This directory contains key files describing mount daemons.

$XDG_DATA_DIRS/gvfs/remote-volume-monitors

This directory contains key files describing remote volume monitors.

## SEE ALSO
GIO documentation[1], gvfsd(1), gvfsd-fuse(1), gvfsd-metadata(1)

## NOTES
1.

GIO documentation

http://developer.gnome.org/gio


gvpe.protocol

package: gvpe

title: gvpe.protocol(7)

text:
# gvpe.protocol(7)

## Overview
GVPE can make use of a number of protocols. One of them is the GNU VPE protocol which is used to authenticate tunnels and send encrypted data packets. This protocol is described in more detail the second part of this document.

The first part of this document describes the transport protocols which are used by GVPE to send its data packets over the network.

## PART 1: Transport protocols
GVPE offers a wide range of transport protocols that can be used to interchange data between nodes. Protocols differ in their overhead, speed, reliability, and robustness.

The following sections describe each transport protocol in more detail. They are sorted by overhead/efficiency, the most efficient transport is listed first:

### RAW IP
This protocol is the best choice, performance-wise, as the minimum overhead per packet is only 38 bytes.

It works by sending the VPN payload using raw IP frames (using the protocol set by ip-proto).

Using raw IP frames has the drawback that many firewalls block "unknown" protocols, so this transport only works if you have full IP connectivity between nodes.

### ICMP
This protocol offers very low overhead (minimum 42 bytes), and can sometimes tunnel through firewalls when other protocols can not.

It works by prepending an ICMP header with type icmp-type and a code of 255. The default icmp-type is echo-reply, so the resulting packets look like echo replies, which looks rather strange to network administrators.

This transport should only be used if other transports (i.e. raw IP) are not available or undesirable (due to their overhead).

### UDP
This is a good general choice for the transport protocol as UDP packets tunnel well through most firewalls and routers, and the overhead per packet is moderate (minimum 58 bytes).

It should be used if RAW IP is not available.

### TCP
This protocol is a very bad choice, as it not only has high overhead (more than 60 bytes), but the transport also retries on its own, which leads to congestion when the link has moderate packet loss (as both the TCP transport and the tunneled traffic will retry, increasing congestion more and more). It also has high latency and is quite inefficient.

It's only useful when tunneling through firewalls that block better protocols. If a node doesn't have direct internet access but a HTTP proxy that supports the CONNECT method it can be used to tunnel through a web proxy. For this to work, the tcp-port should be 443 (https), as most proxies do not allow connections to other ports.

It is an abuse of the usage a proxy was designed for, so make sure you are allowed to use it for GVPE.

This protocol also has server and client sides. If the tcp-port is set to zero, other nodes cannot connect to this node directly. If the tcp-port is non-zero, the node can act both as a client as well as a server.

### DNS
WARNING: Parsing and generating DNS packets is rather tricky. The code almost certainly contains buffer overflows and other, likely exploitable, bugs. You have been warned.

This is the worst choice of transport protocol with respect to overhead (overhead can be 2-3 times higher than the transferred data), and latency (which can be many seconds). Some DNS servers might not be prepared to handle the traffic and drop or corrupt packets. The client also has to constantly poll the server for data, so the client will constantly create traffic even if it doesn't need to transport packets.

In addition, the same problems as the TCP transport also plague this protocol.

Its only use is to tunnel through firewalls that do not allow direct internet access. Similar to using a HTTP proxy (as the TCP transport does), it uses a local DNS server/forwarder (given by the dns-forw-host configuration value) as a proxy to send and receive data as a client, and an NS record pointing to the GVPE server (as given by the dns-hostname directive).

The only good side of this protocol is that it can tunnel through most firewalls mostly undetected, iff the local DNS server/forwarder is sane (which is true for most routers, wireless LAN gateways and nameservers).

Fine-tuning needs to be done by editing src/vpn_dns.C directly.

## PART 2: The GNU VPE protocol
This section, unfortunately, is not yet finished, although the protocol is stable (until bugs in the cryptography are found, which will likely completely change the following description). Nevertheless, it should give you some overview over the protocol.

### Anatomy of a VPN packet
The exact layout and field lengths of a VPN packet is determined at compile time and doesn't change. The same structure is used for all transport protocols, be it RAWIP or TCP.

```
 +------+------+--------+------+
 | HMAC | TYPE | SRCDST | DATA |
 +------+------+--------+------+
```

The HMAC field is present in all packets, even if not used (e.g. in auth request packets), in which case it is set to all zeroes. The MAC itself is calculated over the TYPE, SRCDST and DATA fields in all cases.

The TYPE field is a single byte and determines the purpose of the packet (e.g. RESET, COMPRESSED/UNCOMPRESSED DATA, PING, AUTH REQUEST/RESPONSE, CONNECT REQUEST/INFO etc.).

SRCDST is a three byte field which contains the source and destination node IDs (12 bits each).

The DATA portion differs between each packet type, naturally, and is the only part that can be encrypted. Data packets contain more fields, as shown:

```
 +------+------+--------+-------+------+
 | HMAC | TYPE | SRCDST | SEQNO | DATA |
 +------+------+--------+-------+------+
```

SEQNO is a 32-bit sequence number. It is negotiated at every connection initialization and starts at some random 31 bit value. GVPE currently uses a sliding window of 512 packets/sequence numbers to detect reordering, duplication and replay attacks.

The encryption is done on SEQNO+DATA in CTR mode with IV generated from the seqno (for AES: seqno || seqno || seqno || (u32)0), which ensures uniqueness for a given key.

### The authentication/key exchange protocol
Before nodes can exchange packets, they need to establish authenticity of the other side and a key. Every node has a private RSA key and the public RSA keys of all other nodes.

When a node wants to establish a connection to another node, it sends an RSA-OEAP-encrypted challenge and an ECDH (curve25519) key. The other node replies with its own ECDH key and a HKDF of the challenge and both ECDH keys to prove its identity.

The remote node enganges in exactly the same protocol. When both nodes have exchanged their challenge and verified the response, they calculate a cipher key and a HMAC key and start exchanging data packets.

In detail, the challenge consist of:

```
  RSA-OAEP (SEQNO MAC CIPHER SALT EXTRA-AUTH) ECDH1
```

That is, it encrypts (with the public key of the remote node) an initial sequence number for data packets, key material for the HMAC key, key material for the cipher key, a salt used by the HKDF (as shown later) and some extra random bytes that are unused except for authentication. It also sends the public key of a curve25519 exchange.

The remote node decrypts the RSA data, generates its own ECDH key (ECDH2), and replies with:

```
  HKDF-Expand (HKDF-Extract (ECDH2, RSA), ECDH1, AUTH_DIGEST_SIZE) ECDH2
```

That is, it extracts from the decrypted RSA challenge, using its ECDH key as salt, and then expands using the requesting node's ECDH1 key. The resulting hash is returned as a proof that the node could decrypt the RSA challenge data, together with the ECDH key.

After both nodes have done this to each other, they calculate the shared ECDH secret, cipher and HMAC keys for the session (each node generates two cipher and HMAC keys, one for sending and one for receiving).

The HMAC key for sending is generated as follow:

```
   HMAC_KEY = HKDF-Expand (HKDF-Extract (REMOTE_SALT, MAC ECDH_SECRET), info, HMAC_MD_SIZE)
```

It extracts from MAC and ECDH_SECRET using the remote SALT, then expands using a static info string.

The cipher key is generated in the same way, except using the CIPHER part of the original challenge.

The result of this process is to authenticate each node to the other node, while exchanging keys using both RSA and ECDH, the latter providing perfect forward secrecy.

The protocol has been overdesigned where this was possible without increasing implementation complexity, in an attempt to protect against implementation or protocol failures. For example, if the ECDH challenge was found to be flawed, perfect forward secrecy would be lost, but the data would likely still be protected. Likewise, standard algorithms and implementations are used where possible.

### Retrying
When there is no response to an auth request, the node will send auth requests in bursts with an exponential back-off. After some time it will resort to PING packets, which are very small (8 bytes + protocol header) and lightweight (no RSA operations required). A node that receives ping requests from an unconnected peer will respond by trying to create a connection.

In addition to the exponential back-off, there is a global rate-limit on a per-IP base. It allows long bursts but will limit total packet rate to something like one control packet every ten seconds, to avoid accidental floods due to protocol problems (like a RSA key file mismatch between two nodes).

The intervals between retries are limited by the max-retry configuration value. A node with connect = always will always retry, a node with connect = ondemand will only try (and re-try) to connect as long as there are packets in the queue, usually this limits the retry period to max-ttl seconds.

Sending packets over the VPN will reset the retry intervals as well, which means as long as somebody is trying to send packets to a given node, GVPE will try to connect every few seconds.

### Routing and Protocol translation
The GVPE routing algorithm is easy: there isn't much routing to speak of: When routing packets to another node, GVPE tries the following options, in order:

If the two nodes should be able to reach each other directly (common protocol, port known), then GVPE will send the packet directly to the other node.

If this isn't possible (e.g. because the node doesn't have a hostname or known port), but the nodes speak a common protocol and a router is available, then GVPE will ask a router to "mediate" between both nodes (see below).

If a direct connection isn't possible (no common protocols) or forbidden (deny-direct) and there are any routers, then GVPE will try to send packets to the router with the highest priority that is connected already and is able (as specified by the config file) to connect directly to the target node.

If no such router exists, then GVPE will simply send the packet to the node with the highest priority available.

Failing all that, the packet will be dropped.

A host can usually declare itself unreachable directly by setting its port number(s) to zero. It can declare other hosts as unreachable by using a config-file that disables all protocols for these other hosts. Another option is to disable all protocols on that host in the other config files.

If two hosts cannot connect to each other because their IP address(es) are not known (such as dial-up hosts), one side will send a mediated connection request to a router (routers must be configured to act as routers!), which will send both the originating and the destination host a connection info request with protocol information and IP address of the other host (if known). Both hosts will then try to establish a direct connection to the other peer, which is usually possible even when both hosts are behind a NAT gateway.

Routing via other nodes works because the SRCDST field is not encrypted, so the router can just forward the packet to the destination host. Since each host uses its own private key, the router will not be able to decrypt or encrypt packets, it will just act as a simple router and protocol translator.


hamlib

package: hamlib-devel

title: hamlib(7)

summary: radio and rotator control library

text:
# hamlib(7)

## NAME
hamlib - radio and rotator control library

## DESCRIPTION
The Ham Radio Control Libraries, Hamlib for short, is a development effort to provide a consistent interface for programmers wanting to incorporate radio and rotator control in their programs.

Hamlib is not a complete user application, rather, it is a software layer intended to make controlling various radios and other amateur radio station (shack) hardware much easier. Hamlib will allow authors of software such as logging programs, digital communications programs, or those wanting to develop the ultimate radio control software to concentrate on the user interface and the basic function of the program rather than radio control. Hamlib consists of several parts, the programming library, utility programs, and library interfaces to other programming languages.

Most recent amateur radio transceivers allow external control of their functions through a serial interface. Unfortunately, control commands are not always consistent across a manufacturer's product line and each manufacturer's product line differs greatly from its competitors.

Hamlib attempts to solve this problem by presenting a virtual radio to the programmer by providing an interface to actions such as setting a given Variable Frequency Oscillator's (VFO) frequency, setting the operating mode, querying the radio of its current status and settings, and giving the application a list of a given radio's capabilities. Unfortunately, what can be accomplished by Hamlib is limited by the radios themselves and some offer very limited capability.

Other devices, such as antenna rotators, can be placed into the Hamlib control scheme. Other recent developments include network interface servers and a USB interface capability. Language bindings are provided for C, C++, Perl, Python, Lua and TCL (more to come).

### Overview
Hamlib is a front end library providing a C language Application Programming Interface (API) to programmers wishing to integrate radio or rotator control in their applications. Hamlib presents a virtual radio or virtual rotator that is a consistent interface to an application despite wide differences in radio and rotator interfaces and capabilities.

The front end library uses a number of back end libraries to translate from the front end to the various individual radio and rotator models. A back end library handles conversion of the front end variables to the format needed by the radio or rotator device it controls. The back end libraries are generally grouped by manufacturer and in some cases by a common control protocol.

Hamlib also provides an interface library for each of several common scripting languages such as Perl, Python, Lua, and TCL. These language bindings are generated through the use of SWIG, a parser/generator for multiple language interfaces to a C library. A natively generated C++ language interface is also provided.

Besides the C and supplemental APIs, Hamlib also provides a pair of network daemons that provide a text command based API for controlling an attached radio or rotator through a TCP/IP network connection. The daemons then handle the interface to the Hamlib C API.

More than one type of device, radio or rotator, may be controlled at a time, however, there is generally a limit of one device per serial port or other port.

### Hamlib project information
The Hamlib Project was founded by Frank Singleton, VK3FCS/KM5WS in July 2000. Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib project and the API and implementation development led to a reasonable level of maturity in a few years. A major milestone was reached when Hamlib 1.2.0 was released in March 2004. The API and Application Binary Interface (ABI) interfaces have remained stable since that time up to the release of 3.3 in mid 2018. Version 4.0 marks a major change to the ABI and certain changes to the API.

Development continues through the major version number 4.x series and beyond. The 4.0 release marks a major change in the ABI with several changes for additional modes and such that will require client programs that use the C ABI to be recompiled/relinked, etc. Other goals include improving the overall documentation (this man page with more in progress), and other updates as warranted.

The Project is hosted by SourceForge.net at the Hamlib project page. As GitHub has become a very popular project hosting site, Hamlib also has a dedicated GitHub project page. GitHub also hosts the hamlib.org Web site and the Hamlib Wiki.

Development discussion and most user support take place on the hamlib-developer mailing list. While there are SourceForge.net discussion forums, they are rarely used and not as closely read by the developers as the mailing list.

For source code management, the project uses Git, a fast, distributed content tracker. Among its features is that every developer has the complete Hamlib development history available locally. For more information on using Git, see hamlib-git(7).

Note: while a canonical Git repository is hosted at SourceForge, its availability is not essential to continued development although development work flows would change temporarily. Several developers find the GitHub Web interface easier to use and lately development has centered around GitHub rather than SourceForge.

### Applications using Hamlib
A number of application developers have taken advantage of Hamlib's capabilities to implement radio and/or rotator control. While not exhaustive, a list is maintained at the Hamlib Wiki, Applications/Screenshots. Developers are encouraged to request their applications be added to the gallery by way of the hamlib-developer mailing list.

### Using Hamlib with your program
As with other Free Software projects, Hamlib relies heavily on copyleft licensing to encourage development contributions and provide an open atmosphere for development. Hamlib's source code is released under two licenses, the Lesser General Public License (LGPL) version 2.1 for the library portion, and the General Public License (GPL) version 2 for the utility programs.

The LGPL allows the library to be used (linked) by programs regardless of their individual license. However, any contributions to the library source remain under a copyleft license which means that the library source code may not be used in violation of the terms of the LGPL (see the file COPYING.LIB in the main source directory). Concepts learned by studying these sources for the purpose of understanding the Hamlib API is not covered nor prohibited by the LGPL, however, directly copying LGPL sources into any work that is incompatible with the terms of the LGPL is a violation of the terms of the license.

The utility program source files are released under the GPL. Any direct use of these sources must be in a form that complies with the terms of the GPL (see the file COPYING in the main source directory). Concepts learned by studying these sources for the purpose of understanding the Hamlib API is not covered nor prohibited by the GPL, however, directly copying GPL sources into any work that is incompatible with the terms of the GPL is a violation of the terms of the license.

### Radios with a clone capability
Hamlib's focus is on controlling radios that employ a port and command protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF transceivers do not employ such control capability but do provide for cloning the memory contents from radio to another of the same model. A related project, Chirp, aims to support radios with such a clone capability. Please contact the Chirp project for support of such radios.

### Pronouncing Hamlib
English speakers seem to have two alternate pronunciations for our project:

-

```
Hamlib (Ham - lib, long ‘i’, as in library.)  IPA style: /'ham læb/
```

-

```
Hamlib (Ham - lib, short ‘i’, as in liberty.)  IPA style: /'ham lɪb/
```

Then again, we have people who say Linux “L-eye-nux” and those who say “L-in-nux”...

If you're French, the above does not apply! :-)

## COPYING
This file is part of Hamlib, a project to develop a library that simplifies radio, rotator, and amplifier control functions for developers of software primarily of interest to radio amateurs and those interested in radio communications.

Copyright © 2001-2020 Hamlib Group (various contributors)

This is free software; see the file COPYING for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
hamlib-primer(7)

## COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org.