A visual reference · troff / groff

troff / groff,
one change at a time

From plain text to readable documentation, Unix man pages and longer technical manuals. Complete source. A small change. Its actual result.

The Org file is the canonical source. Read the HTML guide beside your work, or download its PDF and source for offline reading.

Last changes: 2026-10-31. First edition: from plain text to complete documentation, man and mdoc references, longer ms manuals and native PDF/terminal output.

Download PDFRendered tour · read offline

52worked examples

12topic families

1canonical Org source

Choose by appearance

All documents at a glance

52 documents · 12 chapters

Choose a document to open its complete roff source (previews show the first page), explanation and downloads. Search examples or select a topic to narrow this gallery.

Start with text and the command line

4 documents

troff formats a plain text file. groff is the command-line driver that connects preprocessors, the formatter and an output device. These first examples use raw requests before introducing document macros.

GRF-01-001Your first typeset pageView example

GRF-01-002Filled and literal linesView example

GRF-01-003Spaces, comments and literal control charactersView example

GRF-01-004Units and relative changesView example

Build a document with ms

4 documents

The ms package supplies document-level structure: title, author, abstract, headings and paragraphs. Use its macros for structure instead of manually positioning every line.

GRF-02-001Title, author and abstractView example

GRF-02-002Numbered sections and subsectionsView example

GRF-02-003Indented and flush-left paragraphsView example

GRF-02-004Document-wide settingsView example

Typography and readable source

4 documents

Choose text styles intentionally and restore previous settings. Keep source sentences readable; input line breaks need not dictate output line breaks.

GRF-03-001Emphasis and font familiesView example

GRF-03-002Special characters and accentsView example

GRF-03-003Alignment choicesView example

GRF-03-004Size changes with restorationView example

Lists, code, quotations and notes

4 documents

Documentation needs more than paragraphs. Use stable structures for terms, commands, explanations and side material.

GRF-04-001Bullets, numbers and termsView example

GRF-04-002A code block with preserved spacingView example

GRF-04-003Quotations and footnotesView example

GRF-04-004Keep a small explanation togetherView example

Page layout, columns and running text

4 documents

Page furniture belongs in document settings. Use explicit breaks only when they express a deliberate document boundary.

GRF-05-001Headers and page numbersView example

GRF-05-002Two columns for a compact reportView example

GRF-05-003Landscape geometry in raw troffView example

GRF-05-004Page breaks and space reservationsView example

Write a Unix man page

6 documents

The man package describes commands using conventional sections. latexmk is a real-world example: its distributed latexmk.1 source uses these macros. The examples here document an original fictional tool named tourfmt.

GRF-06-001A complete minimal man pageView example

GRF-06-002Command synopsis and optionsView example

GRF-06-003Examples, literal code and escapingView example

GRF-06-004Files, environment and exit statusView example

GRF-06-005Links and manual cross-referencesView example

GRF-06-006A small command reference ready to shipView example

Semantic manuals with mdoc

4 documents

The mdoc package is another manual-page language. Its semantic macros identify names, flags, arguments, paths and references; it is a separate package from man.

GRF-07-001The mdoc document skeletonView example

GRF-07-002Options as a tagged semantic listView example

GRF-07-003Paths, variables and referencesView example

GRF-07-004Literal examples and a cautionView example

Tables with tbl

4 documents

The tbl preprocessor interprets TS/TE blocks before troff sees them. Keep table semantics explicit: headings, units, numeric alignment and short explanatory notes.

GRF-08-001A small numeric tableView example

GRF-08-002Heading rules and column alignmentView example

GRF-08-003A paragraph inside a table cellView example

GRF-08-004A table with a spanned headingView example

Mathematics with eqn

4 documents

The eqn preprocessor reads mathematics inside EQ/EN blocks. The examples use named operators and structures instead of manually positioning every character.

GRF-09-001Fractions and square rootsView example

GRF-09-002Sums, limits and integralsView example

GRF-09-003Matrices and scalable delimitersView example

GRF-09-004Inline equations in explanatory proseView example

Diagrams with pic

4 documents

The pic preprocessor describes shapes, relative placement and connections. Its native drawing commands fit into the same document as prose, tables and mathematics.

GRF-10-001A left-to-right workflowView example

GRF-10-002Branches and named anchorsView example

GRF-10-003Geometry from variablesView example

GRF-10-004A small chart from rectanglesView example

Define reusable formatting

4 documents

Strings, registers and macros reduce repeated source. Keep custom names distinct from macro-package internals, and escape parameters when a macro definition must delay evaluation.

GRF-11-001Strings for repeated namesView example

GRF-11-002Number registers and arithmeticView example

GRF-11-003A macro with an argumentView example

GRF-11-004Conditional text for a chosen editionView example

Write and ship a longer manual

6 documents

These complete projects combine the earlier structures. They explain how to document purpose, installation, command usage, configuration, troubleshooting and maintenance in a readable manual.

GRF-12-001A user guide from title to troubleshootingView example

GRF-12-002A manual with a generated contents pageView example

GRF-12-003Stable references to numbered sectionsView example

GRF-12-004A compact API referenceView example

GRF-12-005A technical note with prose, table, math and diagramView example

GRF-12-006A release note and documentation checklistView example

Reading the tour

Three ways to see a change

Document source

Read complete original roff input and the macro package used to format it.

Native pages

Inspect the first page and download the complete native PDF or terminal text.

Write a manual

Combine headings, examples, tables, equations and diagrams in a reproducible document.

Read from the beginning or jump to a stable example ID. Each example includes its complete input and captured result. Copy link preserves the address of the guide you are reading, including its current domain and path.

From a source file to a document

troff is a text formatter. GNU groff is a command-line driver and typesetting system around it. Write a plain text file in any editor, choose a macro package and output device, then run groff in a terminal. A standalone graphical editor is not required. Macro packages define a document vocabulary: ms for reports and longer prose, man for conventional Unix command references, and mdoc for semantic manual-page markup. Use one primary package for a document.

Install GNU groff with its PDF device and the standard eqn, tbl and pic preprocessors. A system-provided troff or mandoc may implement a different feature set; groff --version identifies the driver used here. The tour records the installed GNU groff version in provenance and in each native compiler log. Poppler supplies SVG conversion for this website; it is not needed to typeset a PDF with groff's own PDF device.

Download the first complete ms report, open a terminal beside it, and run:

groff -S -ms -Tpdf -P-pa5 GRF-02-001.roff > report.pdf
groff -S -ms -Tutf8 -P-c -P-b -P-u GRF-02-001.roff > report.txt

The shell's > saves standard output. Without it, PDF bytes would go to the terminal. Diagnostics go to standard error. -S selects safer mode; the examples need no shell execution or external commands from inside the document. Open report.pdf in a PDF viewer. The utf8 device produces terminal text; the grotty options -P-c -P-b -P-u remove terminal styling sequences and overstrikes from the downloadable text. A normal man viewer can style terminal output itself.

Read the source beside its actual output

Each numbered example contains a complete independent document. The main code view shows its document body; expand the standalone source for page settings and the visible identifier added by the tour. Its MACRO_PACKAGE property records none, ms, man or mdoc; its PAPER property selects A5 portrait or landscape. The publishing command always runs eqn, tbl and pic with -e -t -p, so tables, equations and diagrams work without hidden prerequisites. Preprocessors read their own marked regions before troff formats the result.

A request or macro begins with a dot at the start of a source line. Ordinary lines become filled paragraphs unless no-fill mode or a display changes that behavior. A leading dot in a code sample must be protected with \&. Keep one sentence or logical clause per source line; it makes revisions easier to review without forcing the printed paragraph to follow those line breaks.

The gallery and SVG/PNG downloads show the first page. The native PDF contains all pages and embeds its complete roff source. Each example also provides the actual utf8 output. Diagram examples select an original text alternative with a nroff-mode conditional (.ie n), which also applies to groff HTML output. Terminal devices cannot reproduce all vector geometry. The matrix example likewise supplies a readable terminal form instead of relying on device-dependent stacked matrix metrics. The PDF branches retain the complete pic drawing and eqn matrix. Native logs state the command, page count and diagnostic status. A successful silent formatter is reported as such rather than leaving an empty panel. The complete source kit is also attached to the tour PDF.

Write documentation, not only typography

A usable manual begins with its reader's task: what the tool does, how to get a first result, which arguments it accepts, and how to recognize or resolve a failure. The later chapters build command references, a user guide, an operations manual with contents, an API/configuration reference, and a technical note. tourfmt in these documents is an invented command for teaching; no such program is installed by this tour. The commands beginning with groff are real.

You were right about latexmk: its distributed latexmk.1 is a roff man source, beginning with .TH and section macros such as .SH. Its PDF documentation is presented as a manual page. The official latexmk package page links its source, PDF and text documentation. Use that source as a real-world reference; the examples here are original and do not reproduce its manual.

For your own command, write tool.1 with NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, FILES, ENVIRONMENT, EXIT STATUS and SEE ALSO as appropriate. Document real behavior, defaults and failures; keep examples consistent with the version. For a longer tutorial or handbook, start with an ms title and reading order, then add headings, code displays, tables, figures, references and a contents page.

Publish PDF, terminal text and HTML

For an ms manual that contains equations, tables and drawings:

groff -S -e -t -p -ms -Tpdf manual.ms > manual.pdf
groff -S -e -t -p -ms -Tutf8 manual.ms | less
mkdir -p html
cd html
groff -S -man -Thtml ../tool.1 > index.html

The HTML command above uses a man source saved as tool.1. The HTML device may create companion images for tables, equations and pictures. Run it in a dedicated output directory and publish that complete directory. Depending on the installation, HTML image generation needs Ghostscript and Netpbm utilities. This tour's own searchable HTML guide is made by the shared publisher; the document previews come from actual groff PDF output.

For a downloaded man example, select -man instead of -ms. For mdoc, use -mdoc. To inspect a local man source, use man ./tool.1 on systems whose man viewer accepts local paths; man-db also offers man -l ./tool.1. The section suffix is meaningful: section 1 documents user commands, while section 5 commonly documents file formats. A project can ship its source man page beside the program and install it under an appropriate share/man/man1 prefix.

Review every output you publish: terminal wrapping, PDF page breaks and table widths, and HTML links/image companions. A clean compiler exit cannot decide whether the prose is clear or the page design is useful.

Primary references

The GNU groff project links the official GNU troff manual and documentation for its macro packages and preprocessors. Installed references are available with man groff, man groff_ms, man groff_man, man groff_mdoc, man tbl, man eqn and man pic. The latexmk package provides an extensive real-world man-page source, with PDF and text forms of the same documentation.

Start with text and the command line

GRF-01-001

Your first typeset page

A request begins with a dot at the start of a line. Set a modest line length and write ordinary text; line filling joins the input lines into a paragraph.

Back to figure overview

Complete roff document

.ps 12
.vs 16
.ll 4i
.ft B
Hello from groff
.ft R
.sp .5
This document began as a plain text file.
The formatter joins these source lines into a paragraph.
.br
A forced break starts this sentence on a new output line.

Actual output

Your first typeset page — GRF-01-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     Hello from groff
     This  document  began  as  a  plain text
     file.  The formatter joins these  source
     lines into a paragraph.
     A forced break starts this sentence on a
     new output line.
     GRF‐01‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -Tpdf -P-pa5 GRF-01-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.ps / .vs`	Set type size and vertical spacing in points.
`.ll`	Set the line length.
`.br`	Finish the current output line.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-01-001
.if n .ftr CR R
.pl 8.2677i
.po .5i
.ll 4.7i
.lt 4.7i
.ps 11
.vs 14
.\" BEGIN EXAMPLE
.ps 12
.vs 16
.ll 4i
.ft B
Hello from groff
.ft R
.sp .5
This document began as a plain text file.
The formatter joins these source lines into a paragraph.
.br
A forced break starts this sentence on a new output line.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-01-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-01-002

Filled and literal lines

Fill mode constructs paragraphs. No-fill mode preserves source line breaks, which is useful for short examples with deliberate alignment.

Back to figure overview

Complete roff document

.ps 11
.vs 15
.ll 4i
These three source lines
become one flowing
paragraph on output.
.sp
.nf
Input     Action      Output
text      format      PDF
.fi
.sp
Paragraph filling resumes here.

Actual output

Filled and literal lines — GRF-01-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     These  three  source  lines  become  one
     flowing paragraph on output.

     Input     Action      Output
     text      format      PDF

     Paragraph filling resumes here.
     GRF‐01‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -Tpdf -P-pa5 GRF-01-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.nf`	Disable filling for literal lines.
`.fi`	Resume filling.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-01-002
.if n .ftr CR R
.pl 8.2677i
.po .5i
.ll 4.7i
.lt 4.7i
.ps 11
.vs 14
.\" BEGIN EXAMPLE
.ps 11
.vs 15
.ll 4i
These three source lines
become one flowing
paragraph on output.
.sp
.nf
Input     Action      Output
text      format      PDF
.fi
.sp
Paragraph filling resumes here.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-01-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-01-003

Spaces, comments and literal control characters

A backslash-double-quote introduces a comment. A zero-width escape protects a leading dot, while a backslash escape prints the backslash itself.

Back to figure overview

Complete roff document

.ps 11
.vs 15
.ll 4i
.\" This source comment is not printed.
.nf
\&.SH is printed instead of being executed.
\e is a literal backslash.
The command-line option is \-\-help.
.fi
.sp
Use the minus escape for command options rather than relying on a typographic hyphen.

Actual output

Spaces, comments and literal control characters — GRF-01-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     .SH is printed instead of being executed.
     \ is a literal backslash.
     The command‐line option is −−help.

     Use the minus escape for command options
     rather than relying on a typographic hy‐
     phen.
     GRF‐01‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -Tpdf -P-pa5 GRF-01-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.\"`	Introduce a source comment.
`\&`	Protect a leading control character.
`\e / \-`	Print a backslash or a command-line minus sign.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-01-003
.if n .ftr CR R
.pl 8.2677i
.po .5i
.ll 4.7i
.lt 4.7i
.ps 11
.vs 14
.\" BEGIN EXAMPLE
.ps 11
.vs 15
.ll 4i
.\" This source comment is not printed.
.nf
\&.SH is printed instead of being executed.
\e is a literal backslash.
The command-line option is \-\-help.
.fi
.sp
Use the minus escape for command options rather than relying on a typographic hyphen.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-01-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-01-004

Units and relative changes

Dimensions need a unit. Relative indentation moves a block inward, and restoring it makes the following paragraph align with the first.

Back to figure overview

Complete roff document

.ps 11
.vs 15
.ll 4i
The normal left edge begins here.
.br
.in +.4i
A block indented by four tenths of an inch.
.br
.in -.4i
The original margin is restored.
.sp 1v
One vertical line of space separates these paragraphs.

Actual output

Units and relative changes — GRF-01-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     The normal left edge begins here.
         A  block  indented by four tenths of
         an inch.
     The original margin is restored.

     One vertical  line  of  space  separates
     these paragraphs.
     GRF‐01‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -Tpdf -P-pa5 GRF-01-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`i / p / v`	Use inches, points or vertical line units.
`.in + / -`	Adjust indentation relative to its current value.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-01-004
.if n .ftr CR R
.pl 8.2677i
.po .5i
.ll 4.7i
.lt 4.7i
.ps 11
.vs 14
.\" BEGIN EXAMPLE
.ps 11
.vs 15
.ll 4i
The normal left edge begins here.
.br
.in +.4i
A block indented by four tenths of an inch.
.br
.in -.4i
The original margin is restored.
.sp 1v
One vertical line of space separates these paragraphs.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-01-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Build a document with ms

The ms package supplies document-level structure: title, author, abstract, headings and paragraphs. Use its macros for structure instead of manually positioning every line.

GRF-02-001

Title, author and abstract

The title block is followed by a short abstract. This is a complete small report, independent of the other examples.

Back to figure overview

Complete roff document

.TL
A small technical report
.AU
Lukas C. Bossert
.AI
Documentation laboratory
.AB
We compare two invented measurements and document a reproducible formatting workflow.
.AE
.NH 1
Purpose
.PP
A compact report can begin with a title, a summary and one clearly named section.

Actual output

Title, author and abstract — GRF-02-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                A small technical report


                    Lukas C. Bossert
                Documentation laboratory


                        ABSTRACT

              We  compare  two invented measure‐
         ments and document a reproducible  for‐
         matting workflow.


     1.  Purpose

          A compact report can begin with a title, a
     summary and one clearly named section.
     GRF‐02‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-02-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.TL / .AU / .AI`	Declare title, author and affiliation.
`.AB / .AE`	Begin and end the abstract.
`.PP`	Start an indented paragraph.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-02-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A small technical report
.AU
Lukas C. Bossert
.AI
Documentation laboratory
.AB
We compare two invented measurements and document a reproducible formatting workflow.
.AE
.NH 1
Purpose
.PP
A compact report can begin with a title, a summary and one clearly named section.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-02-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-02-002

Numbered sections and subsections

The heading level determines the section number. An unnumbered heading is suitable for acknowledgements or an appendix label.

Back to figure overview

Complete roff document

.TL
Structure before styling
.NH 1
Overview
.PP
The first top-level section states the purpose.
.NH 2
Scope
.PP
A subsection narrows the discussion.
.NH 1
Method
.PP
The next top-level heading advances the first counter.
.SH
Acknowledgements
.PP
This heading is deliberately unnumbered.

Actual output

Numbered sections and subsections — GRF-02-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                Structure before styling



     1.  Overview

          The  first  top‐level  section  states the
     purpose.

     1.1.  Scope

          A subsection narrows the discussion.

     2.  Method

          The next top‐level  heading  advances  the
     first counter.

     Acknowledgements

          This heading is deliberately unnumbered.
     GRF‐02‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-02-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.NH 1 / .NH 2`	Create numbered headings at the given depth.
`.SH`	Create an unnumbered heading.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-02-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Structure before styling
.NH 1
Overview
.PP
The first top-level section states the purpose.
.NH 2
Scope
.PP
A subsection narrows the discussion.
.NH 1
Method
.PP
The next top-level heading advances the first counter.
.SH
Acknowledgements
.PP
This heading is deliberately unnumbered.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-02-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-02-003

Indented and flush-left paragraphs

Paragraph macros encode two common styles. Their spacing and indentation come from document settings rather than repeated spaces in the source.

Back to figure overview

Complete roff document

.TL
Two paragraph styles
.NH 1
A short note
.PP
An indented paragraph marks its beginning with a first-line inset. Further input lines are filled normally.
.PP
The same style continues in this second paragraph.
.LP
A flush-left paragraph starts at the normal margin. It is useful after a display or where an inset would be distracting.

Actual output

Indented and flush-left paragraphs — GRF-02-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                  Two paragraph styles



     1.  A short note

          An  indented paragraph marks its beginning
     with a first‐line inset.  Further  input  lines
     are filled normally.

          The  same  style  continues in this second
     paragraph.

     A flush‐left paragraph  starts  at  the  normal
     margin.  It  is useful after a display or where
     an inset would be distracting.
     GRF‐02‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-02-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.PP`	Start a paragraph with the configured first-line indentation.
`.LP`	Start a flush-left paragraph.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-02-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Two paragraph styles
.NH 1
A short note
.PP
An indented paragraph marks its beginning with a first-line inset. Further input lines are filled normally.
.PP
The same style continues in this second paragraph.
.LP
A flush-left paragraph starts at the normal margin. It is useful after a display or where an inset would be distracting.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-02-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-02-004

Document-wide settings

Set the ms registers before the title. One group of settings controls the document instead of changing each paragraph individually.

Back to figure overview

Complete roff document

.nr PS 12
.nr VS 16
.nr PI 0
.nr PD .5v
.TL
A more open reading rhythm
.AU
A documentation team
.NH 1
Settings
.PP
Twelve-point text and sixteen-point leading give this small note a relaxed rhythm.
.PP
A zero paragraph inset and half-line paragraph separation make the structure visible without leading spaces.

Actual output

Document-wide settings — GRF-02-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

               A more open reading rhythm


                  A documentation team


     1.  Settings
     Twelve‐point  text  and  sixteen‐point  leading
     give this small note a relaxed rhythm.
     A zero paragraph inset and half‐line  paragraph
     separation  make  the structure visible without
     leading spaces.
     GRF‐02‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-02-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`PS / VS`	Set document type size and line spacing.
`PI / PD`	Set first-line indentation and paragraph separation.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-02-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.nr PS 12
.nr VS 16
.nr PI 0
.nr PD .5v
.TL
A more open reading rhythm
.AU
A documentation team
.NH 1
Settings
.PP
Twelve-point text and sixteen-point leading give this small note a relaxed rhythm.
.PP
A zero paragraph inset and half-line paragraph separation make the structure visible without leading spaces.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-02-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Typography and readable source

Choose text styles intentionally and restore previous settings. Keep source sentences readable; input line breaks need not dictate output line breaks.

GRF-03-001

Emphasis and font families

Font macros apply to their arguments. Inline escapes can change a single word, then restore the previous face.

Back to figure overview

Complete roff document

.TL
Typography as information
.PP
The default face carries the prose.
.B "Bold identifies a term."
.I "Italic marks emphasis."
.PP
The inline word \f[B]required\f[] is bold, then the previous face resumes.
.PP
A short command uses \f[CR]groff -ms note.ms\f[].

Actual output

Emphasis and font families — GRF-03-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                Typography as information



          The  default face carries the prose.  Bold
     identifies a term.  Italic marks emphasis.

          The inline word required is bold, then the
     previous face resumes.

          A short command uses groff ‐ms note.ms.
     GRF‐03‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-03-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.B / .I`	Apply bold or italic to an argument.
`\f[CR] / \f[]`	Select Courier Roman, then restore the previous font.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-03-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Typography as information
.PP
The default face carries the prose.
.B "Bold identifies a term."
.I "Italic marks emphasis."
.PP
The inline word \f[B]required\f[] is bold, then the previous face resumes.
.PP
A short command uses \f[CR]groff -ms note.ms\f[].
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-03-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-03-002

Special characters and accents

Named glyph escapes keep punctuation and symbols explicit. Availability depends on the selected device and font.

Back to figure overview

Complete roff document

.TL
Names for useful glyphs
.PP
A range uses an en dash: 3\(en7.
A sentence may use an em dash\(emwith care.
.PP
The angle is 45\(de. The uncertainty is 12 \(+- 2.
.PP
\(lqQuoted text\(rq differs from straight source quotes.
.PP
The word caf\['e] contains an accented letter.

Actual output

Special characters and accents — GRF-03-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 Names for useful glyphs



          A  range uses an en dash: 3–7.  A sentence
     may use an em dash——with care.

          The angle is 45°. The uncertainty is 12  ±
     2.

          “Quoted text” differs from straight source
     quotes.

          The word café contains an accented letter.
     GRF‐03‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-03-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`\(en / \(em`	Print en and em dashes.
`\(de / \(+-`	Print degree and plus/minus signs.
`\['e]`	Select a named accented glyph.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-03-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Names for useful glyphs
.PP
A range uses an en dash: 3\(en7.
A sentence may use an em dash\(emwith care.
.PP
The angle is 45\(de. The uncertainty is 12 \(+- 2.
.PP
\(lqQuoted text\(rq differs from straight source quotes.
.PP
The word caf\['e] contains an accented letter.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-03-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-03-003

Alignment choices

Temporarily use ragged-right text, then restore justification. A centered display is a distinct structural object.

Back to figure overview

Complete roff document

.TL
Alignment and measure
.na
.PP
Ragged-right setting keeps word spaces regular and leaves an uneven right edge. A narrow measure makes the difference easy to see.
.ad b
.PP
Justification aligns both margins. The formatter adjusts spaces between words while filling each line.
.DS C
A short centered statement
.DE

Actual output

Alignment choices — GRF-03-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                  Alignment and measure



          Ragged‐right setting keeps word spaces
     regular and leaves an uneven right edge. A nar‐
     row measure makes the difference easy to see.

          Justification  aligns  both  margins.  The
     formatter adjusts spaces  between  words  while
     filling each line.

               A short centered statement

     GRF‐03‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-03-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.na`	Disable adjustment.
`.ad b`	Adjust text to both margins.
`.DS C / .DE`	Create a centered display.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-03-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Alignment and measure
.na
.PP
Ragged-right setting keeps word spaces regular and leaves an uneven right edge. A narrow measure makes the difference easy to see.
.ad b
.PP
Justification aligns both margins. The formatter adjusts spaces between words while filling each line.
.DS C
A short centered statement
.DE
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-03-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-03-004

Size changes with restoration

Inline size escapes can make a compact label smaller without changing the surrounding paragraph. A displayed heading can instead use a temporary local size.

Back to figure overview

Complete roff document

.TL
A typographic scale
.PP
Body text contains a \s[-2]small label\s[+2] and then resumes its original size.
.DS C
\s[+5]A large display\s[-5]
.DE
.PP
Avoid shrinking body text to force too much content onto a page.

Actual output

Size changes with restoration — GRF-03-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                   A typographic scale



          Body  text contains a small label and then
     resumes its original size.

                     A large display

          Avoid shrinking body  text  to  force  too
     much content onto a page.
     GRF‐03‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-03-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`\s[-2] / \s[+2]`	Change size relative to the current point size, then reverse the change.
`display`	Keep a deliberate visual treatment separate from ordinary prose.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-03-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A typographic scale
.PP
Body text contains a \s[-2]small label\s[+2] and then resumes its original size.
.DS C
\s[+5]A large display\s[-5]
.DE
.PP
Avoid shrinking body text to force too much content onto a page.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-03-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Lists, code, quotations and notes

Documentation needs more than paragraphs. Use stable structures for terms, commands, explanations and side material.

GRF-04-001

Bullets, numbers and terms

The IP macro makes a hanging paragraph. Its first argument is a label and its second reserves the label width.

Back to figure overview

Complete roff document

.TL
Structured lists
.IP \(bu 2
Collect the input files.
.IP \(bu 2
Run the formatter.
.IP "1." 3
Inspect the generated pages.
.IP "2." 3
Publish the verified output.
.IP "Input" 8
Plain text with requests and macros.
.IP "Output" 8
A formatted document for the selected device.

Actual output

Bullets, numbers and terms — GRF-04-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                    Structured lists



     • Collect the input files.

     • Run the formatter.

     1. Inspect the generated pages.

     2. Publish the verified output.

     Input   Plain text with requests and macros.

     Output  A  formatted  document for the selected
             device.
             GRF‐04‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-04-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.IP`	Start a paragraph with a hanging label.
`label width`	Reserve room for bullets, numbers or definition terms.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-04-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Structured lists
.IP \(bu 2
Collect the input files.
.IP \(bu 2
Run the formatter.
.IP "1." 3
Inspect the generated pages.
.IP "2." 3
Publish the verified output.
.IP "Input" 8
Plain text with requests and macros.
.IP "Output" 8
A formatted document for the selected device.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-04-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-04-002

A code block with preserved spacing

A left-aligned no-fill display preserves lines. Courier distinguishes code, and the source protects a leading dot.

Back to figure overview

Complete roff document

.TL
Show a command accurately
.PP
Run this command in the directory containing the source:
.DS L
.ft CR
groff -S -ms -Tpdf note.ms > note.pdf
\&.PP is a macro, not shell code.
.ft
.DE
.PP
The redirection is handled by the shell; groff writes its selected output to standard output.

Actual output

A code block with preserved spacing — GRF-04-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                Show a command accurately



          Run this command in the directory contain‐
     ing the source:

     groff ‐S ‐ms ‐Tpdf note.ms > note.pdf
     .PP is a macro, not shell code.

          The  redirection  is handled by the shell;
     groff writes its selected  output  to  standard
     output.
     GRF‐04‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-04-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.DS L / .DE`	Keep a left-aligned display together.
`.ft CR / .ft`	Select a fixed-width font, then restore the preceding font.
`\&.PP`	Print a leading dot literally.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-04-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Show a command accurately
.PP
Run this command in the directory containing the source:
.DS L
.ft CR
groff -S -ms -Tpdf note.ms > note.pdf
\&.PP is a macro, not shell code.
.ft
.DE
.PP
The redirection is handled by the shell; groff writes its selected output to standard output.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-04-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-04-003

Quotations and footnotes

The quotation is original teaching prose. A footnote adds supporting detail without interrupting the main paragraph.

Back to figure overview

Complete roff document

.TL
Supporting information
.PP
The build uses a fixed input file.\**
.FS
The values in this tour are invented for teaching.
.FE
.QP
A reproducible document records its input, formatting command and output device.
.PP
The main discussion continues after the quotation.

Actual output

Quotations and footnotes — GRF-04-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 Supporting information



          The build uses a fixed input file.[1]

          A reproducible document  records  its
          input,  formatting command and output
          device.

          The main discussion  continues  after  the
     quotation.
     GRF‐04‐003

























     ───────────
       [1] The  values in this tour are invented
     for teaching.

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-04-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.QP`	Create an indented quotation paragraph.
`\** / .FS / .FE`	Place an automatic footnote mark and its text.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-04-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Supporting information
.PP
The build uses a fixed input file.\**
.FS
The values in this tour are invented for teaching.
.FE
.QP
A reproducible document records its input, formatting command and output device.
.PP
The main discussion continues after the quotation.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-04-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-04-004

Keep a small explanation together

A keep discourages page breaks inside related material. Reserve it for short blocks; a keep larger than a page cannot solve a layout problem.

Back to figure overview

Complete roff document

.TL
Keep a result with its explanation
.PP
A short grouped block follows.
.KS
.B "Result: 30 units"
.PP
Twelve units from the first sample plus eighteen from the second produce the stated total.
.KE
.PP
Long sections should remain free to paginate.

Actual output

Keep a small explanation together — GRF-04-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

           Keep a result with its explanation



          A short grouped block follows.
     Result: 30 units

          Twelve  units  from  the first sample plus
     eighteen from the second produce the stated to‐
     tal.

          Long sections should remain free to  pagi‐
     nate.
     GRF‐04‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-04-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.KS / .KE`	Keep a short block together when possible.
`finite block`	Avoid unbreakable material taller than a page.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-04-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Keep a result with its explanation
.PP
A short grouped block follows.
.KS
.B "Result: 30 units"
.PP
Twelve units from the first sample plus eighteen from the second produce the stated total.
.KE
.PP
Long sections should remain free to paginate.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-04-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Page layout, columns and running text

Page furniture belongs in document settings. Use explicit breaks only when they express a deliberate document boundary.

GRF-05-001

Headers and page numbers

Running strings place a short document name at the left and the example ID at the right. A centered footer prints the current page number.

Back to figure overview

Complete roff document

.ds LH Field notes
.ds RH GRF-05-001
.ds CF Page \\n[%]
.TL
Running text
.PP
The running header and footer belong to the page rather than the paragraph.
.bp
.NH 1
A deliberate second page
.PP
The page number changes while the document label stays the same.

Actual output

Headers and page numbers — GRF-05-001 · Rendered by troff / groff

First-page preview · 2 page(s) in the complete PDF.

Native terminal output

                      Running text



          The  running  header  and footer belong to
     the page rather than the paragraph.








































     Field notes           ‐2‐            GRF‐05‐001
     1.  A deliberate second page

          The page number changes while the document
     label stays the same.
     GRF‐05‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-05-001.roff
Typeset 2 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`LH / RH / CF`	Set left/right headers and the centered footer.
`.bp`	Start a new page.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-05-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.ds LH Field notes
.ds RH GRF-05-001
.ds CF Page \\n[%]
.TL
Running text
.PP
The running header and footer belong to the page rather than the paragraph.
.bp
.NH 1
A deliberate second page
.PP
The page number changes while the document label stays the same.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-05-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-05-002

Two columns for a compact report

The 2C macro changes the text flow to two columns. Returning to one column forces a new page for the full-width conclusion.

Back to figure overview

Complete roff document

.TL
A two-column bulletin
.2C
.NH 1
Input
.PP
A short column can carry a compact explanation of the data and its source.
.PP
Keep paragraphs concise when the line measure is narrow.
.NH 1
Output
.PP
The formatter fills the first column before advancing to the next one.
.PP
The output device determines how the same source is rendered. PDF preserves page geometry, while terminal text uses a fixed character grid.
.NH 1
Review
.PP
Read the source before reviewing the page. A heading should describe the following material, and an example should match the interface it explains. Keep explanations near the commands and values that readers will need.
.PP
Review the generated PDF at a comfortable scale. Check the beginning and end of each column, line lengths, captions and page numbers. A successful compilation is useful evidence, but it cannot determine whether the text answers the reader's question.
.PP
Inspect terminal output separately. Tables may need a narrower format, and diagrams may need a text alternative. Do not assume that a drawing designed for paper can be reproduced accurately on a character grid.
.PP
When preparing a release, keep the original source and the exact formatting command together. Record the macro package and any required preprocessor. This makes the document easier to rebuild and gives future maintainers a clear place to start.
.PP
In a longer report, the column flow continues across page boundaries. Here, a short conclusion deliberately returns to full width on the next page.
.1C
.NH 1
Conclusion
.PP
The full-width discussion resumes after leaving the column layout.

Actual output

Two columns for a compact report — GRF-05-002 · Rendered by troff / groff

First-page preview · 2 page(s) in the complete PDF.

Native terminal output

                  A two‐column bulletin



     1.  Input               values   that  readers
                             will need.
          A   short  column
     can  carry  a  compact       Review the gener‐
     explanation   of   the  ated PDF at a comfort‐
     data and its source.    able scale. Check  the
                             beginning  and  end of
          Keep   paragraphs  each   column,    line
     concise  when the line  lengths,  captions and
     measure is narrow.      page numbers.  A  suc‐
                             cessful compilation is
     2.  Output              useful  evidence,  but
                             it  cannot   determine
          The     formatter  whether  the  text an‐
     fills the first column  swers   the   reader’s
     before   advancing  to  question.
     the next one.
                                  Inspect  terminal
          The output device  output separately. Ta‐
     determines   how   the  bles may need  a  nar‐
     same  source  is  ren‐  rower format, and dia‐
     dered.  PDF  preserves  grams  may need a text
     page  geometry,  while  alternative.  Do   not
     terminal text  uses  a  assume  that a drawing
     fixed character grid.   designed for paper can
                             be  reproduced   accu‐
     3.  Review              rately  on a character
                             grid.
          Read  the  source
     before  reviewing  the       When preparing  a
     page. A heading should  release,    keep   the
     describe the following  original  source   and
     material, and an exam‐  the  exact  formatting
     ple  should  match the  command      together.
     interface it explains.  Record the macro pack‐
     Keep explanations near  age  and  any required
     the    commands    and  preprocessor.     This





                           ‐2‐            GRF‐05‐002
     makes   the   document
     easier to rebuild  and
     gives future maintain‐
     ers  a  clear place to
     start.

          In a  longer  re‐
     port,  the column flow
     continues across  page
     boundaries.   Here,  a
     short  conclusion  de‐
     liberately  returns to
     full width on the next
     page.



































                           ‐3‐            GRF‐05‐002

     4.  Conclusion

          The full‐width  discussion  resumes  after
     leaving the column layout.
     GRF‐05‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-05-002.roff
Typeset 2 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.2C / .1C`	Enter two-column layout and return to one column.
`flow order`	Columns fill in reading order. Returning to one column forces a new page.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-05-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A two-column bulletin
.2C
.NH 1
Input
.PP
A short column can carry a compact explanation of the data and its source.
.PP
Keep paragraphs concise when the line measure is narrow.
.NH 1
Output
.PP
The formatter fills the first column before advancing to the next one.
.PP
The output device determines how the same source is rendered. PDF preserves page geometry, while terminal text uses a fixed character grid.
.NH 1
Review
.PP
Read the source before reviewing the page. A heading should describe the following material, and an example should match the interface it explains. Keep explanations near the commands and values that readers will need.
.PP
Review the generated PDF at a comfortable scale. Check the beginning and end of each column, line lengths, captions and page numbers. A successful compilation is useful evidence, but it cannot determine whether the text answers the reader's question.
.PP
Inspect terminal output separately. Tables may need a narrower format, and diagrams may need a text alternative. Do not assume that a drawing designed for paper can be reproduced accurately on a character grid.
.PP
When preparing a release, keep the original source and the exact formatting command together. Record the macro package and any required preprocessor. This makes the document easier to rebuild and gives future maintainers a clear place to start.
.PP
In a longer report, the column flow continues across page boundaries. Here, a short conclusion deliberately returns to full width on the next page.
.1C
.NH 1
Conclusion
.PP
The full-width discussion resumes after leaving the column layout.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-05-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-05-003

Landscape geometry in raw troff

The document requests a wide page and shorter measure in the vertical direction. The PDF device and PostScript conversion honor the declared paper geometry.

Back to figure overview

Complete roff document

.ps 12
.vs 16
.ll 6i
.ft B
A landscape briefing
.ft R
.sp
A wider measure leaves room for short aligned comparisons.
.sp
.nf
Stage          Input             Result
Prepare        plain text        reviewed source
Format         reviewed source   finished page
.fi

Actual output

Landscape geometry in raw troff — GRF-05-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     A landscape briefing

     A wider measure leaves room for short aligned comparisons.

     Stage          Input             Result
     Prepare        plain text        reviewed source
     Format         reviewed source   finished page
     GRF‐05‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -Tpdf -P-pa5l GRF-05-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`landscape device`	Select A5 landscape through the declared PAPER option.
`.ll`	Keep the line length within the physical page.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-05-003
.if n .ftr CR R
.pl 5.8268i
.po .5i
.ll 4.7i
.lt 4.7i
.ps 11
.vs 14
.\" BEGIN EXAMPLE
.ps 12
.vs 16
.ll 6i
.ft B
A landscape briefing
.ft R
.sp
A wider measure leaves room for short aligned comparisons.
.sp
.nf
Stage          Input             Result
Prepare        plain text        reviewed source
Format         reviewed source   finished page
.fi
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-05-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-05-004

Page breaks and space reservations

The ne request asks for a minimum amount of remaining vertical space. It is useful before a heading and short block.

Back to figure overview

Complete roff document

.TL
Predictable page boundaries
.PP
This first page introduces a small installation guide.
.bp
.NH 1
Installation
.ne 5v
.PP
Reserve room before this short three-line command explanation.
.DS L
.ft CR
groff -S -ms -Tpdf manual.ms > manual.pdf
.ft
.DE

Actual output

Page breaks and space reservations — GRF-05-004 · Rendered by troff / groff

First-page preview · 2 page(s) in the complete PDF.

Native terminal output

               Predictable page boundaries



          This first page introduces a small instal‐
     lation guide.








































                           ‐2‐            GRF‐05‐004
     1.  Installation

          Reserve  room before this short three‐line
     command explanation.

     groff ‐S ‐ms ‐Tpdf manual.ms > manual.pdf

     GRF‐05‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-05-004.roff
Typeset 2 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.bp`	Begin a deliberate new page.
`.ne 5v`	Require five vertical lines of available space.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-05-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Predictable page boundaries
.PP
This first page introduces a small installation guide.
.bp
.NH 1
Installation
.ne 5v
.PP
Reserve room before this short three-line command explanation.
.DS L
.ft CR
groff -S -ms -Tpdf manual.ms > manual.pdf
.ft
.DE
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-05-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Write a Unix man page

GRF-06-001

A complete minimal man page

The NAME line states what the command does; SYNOPSIS shows how to invoke it. One input can serve a terminal viewer and print output.

Back to figure overview

Complete roff document

.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format a small documentation project
.SH SYNOPSIS
.B tourfmt
.RI [ options ] " file"
.SH DESCRIPTION
.B tourfmt
formats a local text document for a selected output device.
.SH EXAMPLES
.EX
tourfmt manual.ms
.EE
.SH SEE ALSO
.BR groff (1)

Actual output

A complete minimal man page — GRF-06-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

TOURFMT(1)       User Commands       TOURFMT(1)

NAME
     tourfmt  -  format  a  small documentation
     project

SYNOPSIS
     tourfmt [options] file

DESCRIPTION
     tourfmt formats a local text document  for
     a selected output device.

EXAMPLES
     tourfmt manual.ms

SEE ALSO
     groff(1)
     GRF‐06‐001

tourfmt 1.0        2026‐10‐31        TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mman -Tpdf -P-pa5 GRF-06-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.TH`	Declare command name, section, date, version and manual title.
`.SH`	Start a conventional man-page section.
`.BR / .RI`	Alternate font styles without losing punctuation.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-06-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format a small documentation project
.SH SYNOPSIS
.B tourfmt
.RI [ options ] " file"
.SH DESCRIPTION
.B tourfmt
formats a local text document for a selected output device.
.SH EXAMPLES
.EX
tourfmt manual.ms
.EE
.SH SEE ALSO
.BR groff (1)
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-06-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-06-002

Command synopsis and options

SY and YS format a command synopsis. TP gives each option a hanging explanation; optional arguments remain visually distinct.

Back to figure overview

Complete roff document

.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH SYNOPSIS
.SY tourfmt
.OP \-T device
.OP \-o output
.I file
.YS
.SH OPTIONS
.TP
.BI \-T " device"
Choose pdf, ps, utf8 or html.
.TP
.BI \-o " output"
Write the selected output file.
.TP
.B \-\-help
Print a concise usage summary.

Actual output

Command synopsis and options — GRF-06-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

TOURFMT(1)       User Commands       TOURFMT(1)

NAME
     tourfmt - format documentation

SYNOPSIS
     tourfmt [-T device] [-o output] file

OPTIONS
     -T device
            Choose pdf, ps, utf8 or html.

     -o output
            Write the selected output file.

     --help
            Print a concise usage summary.
            GRF‐06‐002

tourfmt 1.0        2026‐10‐31        TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mman -Tpdf -P-pa5 GRF-06-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.SY / .YS`	Bound a command synopsis.
`.OP`	Represent an optional option and argument.
`.TP`	Start a tagged paragraph for an option.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-06-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH SYNOPSIS
.SY tourfmt
.OP \-T device
.OP \-o output
.I file
.YS
.SH OPTIONS
.TP
.BI \-T " device"
Choose pdf, ps, utf8 or html.
.TP
.BI \-o " output"
Write the selected output file.
.TP
.B \-\-help
Print a concise usage summary.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-06-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-06-003

Examples, literal code and escaping

EX and EE preserve command lines. Shell options use minus escapes; leading dots are protected so sample source is printed.

Back to figure overview

Complete roff document

.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH EXAMPLES
Compile a report:
.EX
groff \-S \-ms \-Tpdf manual.ms > manual.pdf
.EE
Show a source fragment:
.EX
\&.SH DESCRIPTION
A literal leading dot is protected.
.EE
.SH NOTES
Commands in examples are shown as text and are not executed by the formatter.

Actual output

Examples, literal code and escaping — GRF-06-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

TOURFMT(1)       User Commands       TOURFMT(1)

NAME
     tourfmt - format documentation

EXAMPLES
     Compile a report:
     groff -S -ms -Tpdf manual.ms > manual.pdf
     Show a source fragment:
     .SH DESCRIPTION
     A literal leading dot is protected.

NOTES
     Commands in examples are shown as text and
     are not executed by the formatter.
     GRF‐06‐003

tourfmt 1.0        2026‐10‐31        TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mman -Tpdf -P-pa5 GRF-06-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.EX / .EE`	Create a literal example block.
`\-`	Print command-line minus signs.
`\&`	Protect a leading control character.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-06-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH EXAMPLES
Compile a report:
.EX
groff \-S \-ms \-Tpdf manual.ms > manual.pdf
.EE
Show a source fragment:
.EX
\&.SH DESCRIPTION
A literal leading dot is protected.
.EE
.SH NOTES
Commands in examples are shown as text and are not executed by the formatter.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-06-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-06-004

Files, environment and exit status

A useful reference documents configuration locations, variables and failure modes. The statuses here are a specification for the fictional example command.

Back to figure overview

Complete roff document

.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH FILES
.TP
.I ./tourfmt.conf
Optional project settings.
.SH ENVIRONMENT
.TP
.B TOURFMT_DEVICE
Default output device when no explicit selection is given.
.SH EXIT STATUS
.TP
.B 0
The document was formatted successfully.
.TP
.B 1
A source file or formatting step failed.
.SH DIAGNOSTICS
An unknown output device is reported before formatting starts.

Actual output

Files, environment and exit status — GRF-06-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

TOURFMT(1)       User Commands       TOURFMT(1)

NAME
     tourfmt - format documentation

FILES
     ./tourfmt.conf
            Optional project settings.

ENVIRONMENT
     TOURFMT_DEVICE
            Default  output  device when no ex‐
            plicit selection is given.

EXIT STATUS
     0      The document was formatted success‐
            fully.

     1      A source file  or  formatting  step
            failed.

DIAGNOSTICS
     An  unknown  output device is reported be‐
     fore formatting starts.
     GRF‐06‐004

tourfmt 1.0        2026‐10‐31        TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mman -Tpdf -P-pa5 GRF-06-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.I / .B`	Distinguish file paths and variable names.
`EXIT STATUS`	Document outcomes that scripts can rely on.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-06-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH FILES
.TP
.I ./tourfmt.conf
Optional project settings.
.SH ENVIRONMENT
.TP
.B TOURFMT_DEVICE
Default output device when no explicit selection is given.
.SH EXIT STATUS
.TP
.B 0
The document was formatted successfully.
.TP
.B 1
A source file or formatting step failed.
.SH DIAGNOSTICS
An unknown output device is reported before formatting starts.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-06-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-06-005

Links and manual cross-references

UR and UE mark a web link. A conventional SEE ALSO reference names a manual entry and its section.

Back to figure overview

Complete roff document

.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH DOCUMENTATION
.UR https://www.gnu.org/software/groff/
GNU groff project documentation
.UE .
.SH SEE ALSO
.BR groff (1),
.BR groff_man (7),
.BR groff_ms (7)
.SH AUTHORS
Written for this tour as an original documentation example.

Actual output

Links and manual cross-references — GRF-06-005 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

TOURFMT(1)       User Commands       TOURFMT(1)

NAME
     tourfmt - format documentation

DOCUMENTATION
     GNU groff project documentation.

SEE ALSO
     groff(1), groff_man(7), groff_ms(7)

AUTHORS
     Written for this tour as an original docu‐
     mentation example.
     GRF‐06‐005

tourfmt 1.0        2026‐10‐31        TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mman -Tpdf -P-pa5 GRF-06-005.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.UR / .UE`	Start and end a web link.
`manual section`	Identify the correct section when citing another manual entry.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-06-005
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format documentation
.SH DOCUMENTATION
.UR https://www.gnu.org/software/groff/
GNU groff project documentation
.UE .
.SH SEE ALSO
.BR groff (1),
.BR groff_man (7),
.BR groff_ms (7)
.SH AUTHORS
Written for this tour as an original documentation example.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-06-005\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-06-006

A small command reference ready to ship

This complete reference combines purpose, synopsis, options, examples, files, statuses and links. Save it as tourfmt.1 and install it in an appropriate man1 directory.

Back to figure overview

Complete roff document

.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format a local documentation project
.SH SYNOPSIS
.SY tourfmt
.OP \-T device
.I file
.YS
.SH DESCRIPTION
.B tourfmt
is a fictional command used to demonstrate a complete manual entry.
.SH OPTIONS
.TP
.BI \-T " device"
Select the output device; the default is pdf.
.SH EXAMPLES
.EX
tourfmt \-T pdf manual.ms
.EE
.SH FILES
.I ./tourfmt.conf
.SH EXIT STATUS
Zero indicates success; one indicates a failed input or formatting step.
.SH SEE ALSO
.BR groff (1),
.BR groff_man (7)

Actual output

A small command reference ready to ship — GRF-06-006 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

TOURFMT(1)       User Commands       TOURFMT(1)

NAME
     tourfmt  -  format  a  local documentation
     project

SYNOPSIS
     tourfmt [-T device] file

DESCRIPTION
     tourfmt is a  fictional  command  used  to
     demonstrate a complete manual entry.

OPTIONS
     -T device
            Select  the  output device; the de‐
            fault is pdf.

EXAMPLES
     tourfmt -T pdf manual.ms

FILES
     ./tourfmt.conf

EXIT STATUS
     Zero indicates success;  one  indicates  a
     failed input or formatting step.

SEE ALSO
     groff(1), groff_man(7)
     GRF‐06‐006

tourfmt 1.0        2026‐10‐31        TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mman -Tpdf -P-pa5 GRF-06-006.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`conventional sections`	Make common questions easy to find.
`tourfmt.1`	The filename suffix records manual section one.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-06-006
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TH TOURFMT 1 "2026-10-31" "tourfmt 1.0" "User Commands"
.SH NAME
tourfmt \- format a local documentation project
.SH SYNOPSIS
.SY tourfmt
.OP \-T device
.I file
.YS
.SH DESCRIPTION
.B tourfmt
is a fictional command used to demonstrate a complete manual entry.
.SH OPTIONS
.TP
.BI \-T " device"
Select the output device; the default is pdf.
.SH EXAMPLES
.EX
tourfmt \-T pdf manual.ms
.EE
.SH FILES
.I ./tourfmt.conf
.SH EXIT STATUS
Zero indicates success; one indicates a failed input or formatting step.
.SH SEE ALSO
.BR groff (1),
.BR groff_man (7)
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-06-006\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Semantic manuals with mdoc

The mdoc package is another manual-page language. Its semantic macros identify names, flags, arguments, paths and references; it is a separate package from man.

GRF-07-001

The mdoc document skeleton

Document metadata is followed by conventional sections. Nm and Nd identify the name and short description.

Back to figure overview

Complete roff document

.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format a small documentation project
.Sh SYNOPSIS
.Nm
.Op Fl T Ar device
.Ar file
.Sh DESCRIPTION
.Nm
is an original teaching example for semantic manual markup.

Actual output

The mdoc document skeleton — GRF-07-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     TOURFMT(1)   General Commands Manual TOURFMT(1)

     NAME
          tourfmt  ——  format  a small documentation
          project

     SYNOPSIS
          tourfmt [-T device] file

     DESCRIPTION
          tourfmt is an  original  teaching  example
          for semantic manual markup.
          GRF‐07‐001

     GNU             October 31, 2026     TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mmdoc -Tpdf -P-pa5 GRF-07-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.Dd / .Dt / .Os`	Declare date, manual title and system context.
`.Nm / .Nd`	Mark a command name and its short description.
`.Fl / .Ar`	Identify an option flag and an argument.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-07-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format a small documentation project
.Sh SYNOPSIS
.Nm
.Op Fl T Ar device
.Ar file
.Sh DESCRIPTION
.Nm
is an original teaching example for semantic manual markup.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-07-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-07-002

Options as a tagged semantic list

Bl begins a list and It begins an item. Each flag and its argument keep their semantic roles.

Back to figure overview

Complete roff document

.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format documentation
.Sh OPTIONS
.Bl -tag -width "-T device"
.It Fl T Ar device
Select the output format.
.It Fl o Ar output
Choose the destination file.
.It Fl h
Print usage and exit.
.El

Actual output

Options as a tagged semantic list — GRF-07-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     TOURFMT(1)   General Commands Manual TOURFMT(1)

     NAME
          tourfmt —— format documentation

     OPTIONS
          -T device  Select the output format.

          -o output  Choose the destination file.

          -h         Print usage and exit.
          GRF‐07‐002

     GNU             October 31, 2026     TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mmdoc -Tpdf -P-pa5 GRF-07-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.Bl -tag / .El`	Bound a tagged list.
`.It`	Start a list item with semantic arguments.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-07-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format documentation
.Sh OPTIONS
.Bl -tag -width "-T device"
.It Fl T Ar device
Select the output format.
.It Fl o Ar output
Choose the destination file.
.It Fl h
Print usage and exit.
.El
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-07-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-07-003

Paths, variables and references

Semantic names let the macro package choose a consistent treatment. Cross-references specify both a manual name and section.

Back to figure overview

Complete roff document

.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format documentation
.Sh FILES
.Pa ./tourfmt.conf
contains optional project settings.
.Sh ENVIRONMENT
.Ev TOURFMT_DEVICE
selects a default output device.
.Sh SEE ALSO
.Xr groff 1 ,
.Xr groff_mdoc 7

Actual output

Paths, variables and references — GRF-07-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     TOURFMT(1)   General Commands Manual TOURFMT(1)

     NAME
          tourfmt —— format documentation

     FILES
          ./tourfmt.conf  contains  optional project
          settings.

     ENVIRONMENT
          TOURFMT_DEVICE selects  a  default  output
          device.

     SEE ALSO
          groff(1), groff_mdoc(7)
          GRF‐07‐003

     GNU             October 31, 2026     TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mmdoc -Tpdf -P-pa5 GRF-07-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.Pa`	Identify a path.
`.Ev`	Identify an environment variable.
`.Xr`	Identify a manual cross-reference.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-07-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format documentation
.Sh FILES
.Pa ./tourfmt.conf
contains optional project settings.
.Sh ENVIRONMENT
.Ev TOURFMT_DEVICE
selects a default output device.
.Sh SEE ALSO
.Xr groff 1 ,
.Xr groff_mdoc 7
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-07-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-07-004

Literal examples and a caution

Bd creates a literal display. A paragraph explains the fictional tool so the reader can distinguish a documented interface from an installed command.

Back to figure overview

Complete roff document

.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format documentation
.Sh EXAMPLES
.Bd -literal -offset indent
groff -S -mdoc -Tutf8 tourfmt.1
.Ed
.Pp
The source uses the
.Nm mdoc
macro package.
.Sh CAVEATS
.Nm tourfmt
is a fictional program; the groff commands shown here are real.

Actual output

Literal examples and a caution — GRF-07-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

     TOURFMT(1)   General Commands Manual TOURFMT(1)

     NAME
          tourfmt —— format documentation

     EXAMPLES
                groff ‐S ‐mdoc ‐Tutf8 tourfmt.1

          The source uses the mdoc macro package.

     CAVEATS
          tourfmt  is a fictional program; the groff
          commands shown here are real.
          GRF‐07‐004

     GNU             October 31, 2026     TOURFMT(1)

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mmdoc -Tpdf -P-pa5 GRF-07-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.Bd -literal / .Ed`	Preserve a literal display.
`.Pp`	Start a semantic paragraph.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-07-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.Dd October 31, 2026
.Dt TOURFMT 1
.Os
.Sh NAME
.Nm tourfmt
.Nd format documentation
.Sh EXAMPLES
.Bd -literal -offset indent
groff -S -mdoc -Tutf8 tourfmt.1
.Ed
.Pp
The source uses the
.Nm mdoc
macro package.
.Sh CAVEATS
.Nm tourfmt
is a fictional program; the groff commands shown here are real.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-07-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Tables with tbl

The tbl preprocessor interprets TS/TE blocks before troff sees them. Keep table semantics explicit: headings, units, numeric alignment and short explanatory notes.

GRF-08-001

A small numeric table

A semicolon delimiter keeps the source easy to inspect. The numeric column aligns values around their decimal positions.

Back to figure overview

Complete roff document

.TL
Measurements with units
.PP
These values are synthetic.
.TS
box tab(;);
l n.
Item;Time (s)
_
Alpha;1.2
Beta;12.35
Gamma;3.0
.TE

Actual output

A small numeric table — GRF-08-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 Measurements with units



          These values are synthetic.

     ┌──────────────────┐
     │ Item    Time (s) │
     ├──────────────────┤
     │ Alpha     1.2    │
     │ Beta     12.35   │
     │ Gamma     3.0    │
     └──────────────────┘

     GRF‐08‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-08-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.TS / .TE`	Bound a table processed by tbl.
`tab(;)`	Choose a visible source delimiter.
`n`	Align numeric values by their decimal position.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-08-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Measurements with units
.PP
These values are synthetic.
.TS
box tab(;);
l n.
Item;Time (s)
_
Alpha;1.2
Beta;12.35
Gamma;3.0
.TE
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-08-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-08-002

Heading rules and column alignment

The format line declares left, centered and numeric columns. A rule separates the heading from the data.

Back to figure overview

Complete roff document

.TL
A compact comparison
.LP
.TS
tab(;);
l c n.
Tool;Device;Pages
_
groff;pdf;3
groff;utf8;3
groff;html;1
.TE
.PP
The page counts are invented teaching values, not an output comparison benchmark.

Actual output

Heading rules and column alignment — GRF-08-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                  A compact comparison




     Tool    Device   Pages
     ───────────────────────
     groff    pdf       3
     groff    utf8      3
     groff    html      1

          The page counts are invented teaching val‐
     ues, not an output comparison benchmark.
     GRF‐08‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-08-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`l / c / n`	Select left, centered and numeric column alignment.
`_`	Separate heading and body with a horizontal rule.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-08-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A compact comparison
.LP
.TS
tab(;);
l c n.
Tool;Device;Pages
_
groff;pdf;3
groff;utf8;3
groff;html;1
.TE
.PP
The page counts are invented teaching values, not an output comparison benchmark.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-08-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-08-003

A paragraph inside a table cell

T braces delimit a text block. Give that column a width so the cell wraps predictably.

Back to figure overview

Complete roff document

.TL
Document a pair of settings
.LP
.TS
box tab(;);
l lw(2.2i).
Setting;Meaning
_
T{
Device
T};T{
Selects PDF, terminal text or HTML output. The document source remains a plain text file.
T}
T{
Macro package
T};T{
Selects a document vocabulary such as ms, man or mdoc.
T}
.TE

Actual output

A paragraph inside a table cell — GRF-08-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

               Document a pair of settings




     ┌────────────────────────────────────────┐
     │ Setting         Meaning                │
     ├────────────────────────────────────────┤
     │ Device          Selects  PDF, terminal │
     │                 text or  HTML  output. │
     │                 The   document  source │
     │                 remains a  plain  text │
     │                 file.                  │
     │ Macro package   Selects a document vo‐ │
     │                 cabulary  such  as ms, │
     │                 man or mdoc.           │
     └────────────────────────────────────────┘

     GRF‐08‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-08-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`T{ / T}`	Bound a multi-line text cell.
`w(2.2i)`	Give the prose column a fixed wrapping width.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-08-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Document a pair of settings
.LP
.TS
box tab(;);
l lw(2.2i).
Setting;Meaning
_
T{
Device
T};T{
Selects PDF, terminal text or HTML output. The document source remains a plain text file.
T}
T{
Macro package
T};T{
Selects a document vocabulary such as ms, man or mdoc.
T}
.TE
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-08-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-08-004

A table with a spanned heading

The s format code spans the preceding cell across the next column. Put units in the subheadings rather than hiding them in the surrounding prose.

Back to figure overview

Complete roff document

.TL
A grouped table heading
.LP
.TS
box tab(;);
c s
l n.
Synthetic measurements;
Name;Length (cm)
_
A;12.0
B;18.5
C;15.2
.TE

Actual output

A table with a spanned heading — GRF-08-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 A grouped table heading




     ┌────────────────────────┐
     │ Synthetic measurements │
     │ Name      Length (cm)  │
     ├────────────────────────┤
     │ A            12.0      │
     │ B            18.5      │
     │ C            15.2      │
     └────────────────────────┘

     GRF‐08‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-08-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`s`	Span the preceding column in that row.
`row formats`	Change the format for the heading and body.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-08-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A grouped table heading
.LP
.TS
box tab(;);
c s
l n.
Synthetic measurements;
Name;Length (cm)
_
A;12.0
B;18.5
C;15.2
.TE
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-08-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Mathematics with eqn

The eqn preprocessor reads mathematics inside EQ/EN blocks. The examples use named operators and structures instead of manually positioning every character.

GRF-09-001

Fractions and square roots

Braces group numerator and denominator expressions. The equation is typeset separately from the prose.

Back to figure overview

Complete roff document

.TL
An algebraic expression
.PP
A normalized difference can be written as:
.EQ
z = { x - mu } over sigma
.EN
.PP
A geometric length follows:
.EQ
c = sqrt { a sup 2 + b sup 2 }
.EN

Actual output

Fractions and square roots — GRF-09-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 An algebraic expression



          A normalized difference can be written as:

                          z=x_−σ_μ_

          A geometric length follows:

                        c=√‾a‾2‾+‾b‾2

     GRF‐09‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-09-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`over`	Build a fraction.
`sqrt`	Build a square root.
`sup`	Set a superscript.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-09-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
An algebraic expression
.PP
A normalized difference can be written as:
.EQ
z = { x - mu } over sigma
.EN
.PP
A geometric length follows:
.EQ
c = sqrt { a sup 2 + b sup 2 }
.EN
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-09-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-09-002

Sums, limits and integrals

Operators can carry limits. These are mathematical identities used to demonstrate notation, not computations performed by groff.

Back to figure overview

Complete roff document

.TL
Operators and limits
.LP
.EQ
S = sum from {i=1} to n x sub i
.EN
.EQ
int from 0 to 1 x sup 2 dx = 1 over 3
.EN
.PP
The formatter draws notation; it does not evaluate these expressions.

Actual output

Sums, limits and integrals — GRF-09-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                  Operators and limits




                         S=in=Σ1xi

                         10∫x2dx=13_

          The  formatter draws notation; it does not
     evaluate these expressions.
     GRF‐09‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-09-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`sum from ... to`	Place limits around a summation operator.
`int`	Typeset an integral.
`sub / sup`	Create subscripts and superscripts.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-09-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Operators and limits
.LP
.EQ
S = sum from {i=1} to n x sub i
.EN
.EQ
int from 0 to 1 x sup 2 dx = 1 over 3
.EN
.PP
The formatter draws notation; it does not evaluate these expressions.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-09-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-09-003

Matrices and scalable delimiters

Matrix columns define an aligned rectangular structure. Left and right delimiters grow with the expression.

Back to figure overview

Complete roff document

.TL
A small linear system
.LP
.ie n \{\
.LP
Linear system: 2x + y = 5; x + 3y = 7.
.\}
.el \{\
.EQ
left [ matrix { ccol { 2 above 1 } ccol { 1 above 3 } } right ]
left [ pile { x above y } right ] =
left [ pile { 5 above 7 } right ]
.EN
.\}

Actual output

Matrices and scalable delimiters — GRF-09-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                  A small linear system




     Linear system: 2x + y = 5; x + 3y = 7.
     GRF‐09‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-09-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`matrix / ccol`	Build a matrix from centered columns.
`above`	Separate vertical entries.
`left / right`	Scale delimiters to the enclosed material.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-09-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A small linear system
.LP
.ie n \{\
.LP
Linear system: 2x + y = 5; x + 3y = 7.
.\}
.el \{\
.EQ
left [ matrix { ccol { 2 above 1 } ccol { 1 above 3 } } right ]
left [ pile { x above y } right ] =
left [ pile { 5 above 7 } right ]
.EN
.\}
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-09-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-09-004

Inline equations in explanatory prose

Declare delimiters inside an EQ block. Inline math then shares the paragraph baseline; turn the delimiters off when no longer needed.

Back to figure overview

Complete roff document

.TL
Explain a formula in context
.LP
.EQ
delim $$
.EN
.PP
The area is $A = pi r sup 2$, where $r$ is the radius.
.PP
If the radius doubles, the area becomes $4 A$.
.EQ
delim off
.EN

Actual output

Inline equations in explanatory prose — GRF-09-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

              Explain a formula in context




          The area is A=πr2, where r is the radius.

          If  the  radius  doubles, the area becomes
     4A.
     GRF‐09‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-09-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`delim $$`	Enable dollar-delimited inline mathematics.
`delim off`	Restore ordinary treatment of the delimiter characters.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-09-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Explain a formula in context
.LP
.EQ
delim $$
.EN
.PP
The area is $A = pi r sup 2$, where $r$ is the radius.
.PP
If the radius doubles, the area becomes $4 A$.
.EQ
delim off
.EN
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-09-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Diagrams with pic

The pic preprocessor describes shapes, relative placement and connections. Its native drawing commands fit into the same document as prose, tables and mathematics.

GRF-10-001

A left-to-right workflow

Named shapes and short arrows describe a process. Pic measures its geometry in inches by default.

Back to figure overview

Complete roff document

.TL
A documentation workflow
.LP
.ie n \{\
.LP
Diagram: Write, then Review, then Publish.
.\}
.el \{\
.PS
boxwid = 0.95; boxht = 0.45
A: box "Write"
arrow right 0.3
B: box "Review"
arrow right 0.3
C: box "Publish"
.PE
.\}
.PP
The diagram is part of the document source.

Actual output

A left-to-right workflow — GRF-10-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                A documentation workflow




     Diagram: Write, then Review, then Publish.

          The   diagram  is  part  of  the  document
     source.
     GRF‐10‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-10-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.PS / .PE`	Bound a pic drawing.
`box / arrow`	Draw a node or a directed connection.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-10-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A documentation workflow
.LP
.ie n \{\
.LP
Diagram: Write, then Review, then Publish.
.\}
.el \{\
.PS
boxwid = 0.95; boxht = 0.45
A: box "Write"
arrow right 0.3
B: box "Review"
arrow right 0.3
C: box "Publish"
.PE
.\}
.PP
The diagram is part of the document source.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-10-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-10-002

Branches and named anchors

Named shapes expose compass-point anchors. Separate two outcomes vertically, then label the routes.

Back to figure overview

Complete roff document

.TL
A small decision diagram
.LP
.ie n \{\
.LP
Diagram: Check branches to Publish on pass, and Revise on fail.
.\}
.el \{\
.PS
A: box "Check" width 0.9 height 0.4
B: box "Publish" at A.e + (2,0.6) width 1 height 0.4
C: box "Revise" at A.e + (2,-0.6) width 1 height 0.4
arrow from A.e to B.w
"pass" at A.e + (0.8,0.5)
arrow from A.e to C.w
"fail" at A.e + (0.8,-0.5)
.PE
.\}

Actual output

Branches and named anchors — GRF-10-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                A small decision diagram




     Diagram: Check branches to Publish on pass, and
     Revise on fail.
     GRF‐10‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-10-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`A.e / B.w`	Refer to the east and west anchors of named shapes.
`at`	Place a shape or text at an explicit coordinate.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-10-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A small decision diagram
.LP
.ie n \{\
.LP
Diagram: Check branches to Publish on pass, and Revise on fail.
.\}
.el \{\
.PS
A: box "Check" width 0.9 height 0.4
B: box "Publish" at A.e + (2,0.6) width 1 height 0.4
C: box "Revise" at A.e + (2,-0.6) width 1 height 0.4
arrow from A.e to B.w
"pass" at A.e + (0.8,0.5)
arrow from A.e to C.w
"fail" at A.e + (0.8,-0.5)
.PE
.\}
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-10-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-10-003

Geometry from variables

A small set of variables controls the drawing. Changing the radius changes both circles and their spacing.

Back to figure overview

Complete roff document

.TL
A parametric construction
.LP
.ie n \{\
.LP
Diagram: Two equal circles A and B share one horizontal centre line.
.\}
.el \{\
.PS
r = 0.6
A: circle radius r
B: circle radius r at A.e + (r*1.5,0)
line dashed from A.c to B.c
"A" at A.c
"B" at B.c
.PE
.\}

Actual output

Geometry from variables — GRF-10-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                A parametric construction




     Diagram:  Two  equal  circles A and B share one
     horizontal centre line.
     GRF‐10‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-10-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`variable assignment`	Reuse one geometric quantity.
`circle radius`	Set a circle size.
`dashed`	Use a construction-line stroke.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-10-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A parametric construction
.LP
.ie n \{\
.LP
Diagram: Two equal circles A and B share one horizontal centre line.
.\}
.el \{\
.PS
r = 0.6
A: circle radius r
B: circle radius r at A.e + (r*1.5,0)
line dashed from A.c to B.c
"A" at A.c
"B" at B.c
.PE
.\}
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-10-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-10-004

A small chart from rectangles

Three rectangles encode supplied values 2, 4 and 3 using one linear height scale. This is a deliberate primitive construction, not an automatic charting package.

Back to figure overview

Complete roff document

.TL
A chart built from pic shapes
.LP
.ie n \{\
.LP
Diagram: Three bars have values A=2, B=4 and C=3, on a shared baseline.
.\}
.el \{\
.PS
scale = 1
barw = 0.45
line from (0,0) to (3,0)
box width barw height 0.6 with .s at (0.6,0.0) fill 0.8
box width barw height 1.2 with .s at (1.5,0.0) fill 0.6
box width barw height 0.9 with .s at (2.4,0.0) fill 0.4
"A: 2" at (0.6,-0.2)
"B: 4" at (1.5,-0.2)
"C: 3" at (2.4,-0.2)
.PE
.\}

Actual output

A small chart from rectangles — GRF-10-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

              A chart built from pic shapes




     Diagram:  Three  bars  have values A=2, B=4 and
     C=3, on a shared baseline.
     GRF‐10‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-10-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`height`	Map a supplied value to one fixed geometric scale.
`with .s at`	Anchor every bar at the same baseline.
`fill`	Choose a gray fill fraction.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-10-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A chart built from pic shapes
.LP
.ie n \{\
.LP
Diagram: Three bars have values A=2, B=4 and C=3, on a shared baseline.
.\}
.el \{\
.PS
scale = 1
barw = 0.45
line from (0,0) to (3,0)
box width barw height 0.6 with .s at (0.6,0.0) fill 0.8
box width barw height 1.2 with .s at (1.5,0.0) fill 0.6
box width barw height 0.9 with .s at (2.4,0.0) fill 0.4
"A: 2" at (0.6,-0.2)
"B: 4" at (1.5,-0.2)
"C: 3" at (2.4,-0.2)
.PE
.\}
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-10-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Define reusable formatting

Strings, registers and macros reduce repeated source. Keep custom names distinct from macro-package internals, and escape parameters when a macro definition must delay evaluation.

GRF-11-001

Strings for repeated names

A string is text that can be interpolated later. Changing the product name once updates every use.

Back to figure overview

Complete roff document

.ds Product Tour Formatter
.TL
A reusable product name
.PP
\*[Product] converts plain text into documentation.
.PP
The \*[Product] manual records the source and output commands together.

Actual output

Strings for repeated names — GRF-11-001 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 A reusable product name



          Tour  Formatter  converts  plain text into
     documentation.

          The  Tour  Formatter  manual  records  the
     source and output commands together.
     GRF‐11‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-11-001.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.ds`	Define a named string.
`\*[Product]`	Interpolate its current value.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-11-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.ds Product Tour Formatter
.TL
A reusable product name
.PP
\*[Product] converts plain text into documentation.
.PP
The \*[Product] manual records the source and output commands together.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-11-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-11-002

Number registers and arithmetic

Registers hold numeric values. The formatter evaluates ordinary roff arithmetic left to right unless parentheses specify a different grouping.

Back to figure overview

Complete roff document

.nr Samples 12
.nr Added 18
.nr Total (\n[Samples]+\n[Added])
.TL
Computed text values
.PP
The first group contains \n[Samples] items.
The second contains \n[Added] items.
Together they contain \n[Total] items.

Actual output

Number registers and arithmetic — GRF-11-002 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                  Computed text values



          The  first  group  contains 12 items.  The
     second contains 18 items.  Together  they  con‐
     tain 30 items.
     GRF‐11‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-11-002.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.nr`	Define a numeric register.
`\n[Total]`	Interpolate a numeric value.
`parentheses`	Make the intended grouping explicit.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-11-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.nr Samples 12
.nr Added 18
.nr Total (\n[Samples]+\n[Added])
.TL
Computed text values
.PP
The first group contains \n[Samples] items.
The second contains \n[Added] items.
Together they contain \n[Total] items.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-11-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-11-003

A macro with an argument

Double escapes delay argument expansion until the macro is called. The custom macro gives every note the same form.

Back to figure overview

Complete roff document

.de TourNote
.PP
.B "Note:"
\\$1
..
.TL
One reusable note style
.TourNote "Keep the source beside the formatting command."
.TourNote "Review the PDF before publishing."

Actual output

A macro with an argument — GRF-11-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 One reusable note style



          Note:  Keep  the source beside the format‐
     ting command.

          Note: Review the PDF before publishing.
     GRF‐11‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-11-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.de / ..`	Begin and end a macro definition.
`\\$1`	Delay the first-argument reference until macro invocation.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-11-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.de TourNote
.PP
.B "Note:"
\\$1
..
.TL
One reusable note style
.TourNote "Keep the source beside the formatting command."
.TourNote "Review the PDF before publishing."
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-11-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-11-004

Conditional text for a chosen edition

A numeric register selects a branch. This explicit edition switch is part of the source and works across output devices.

Back to figure overview

Complete roff document

.nr Draft 1
.TL
A controlled draft note
.ie \n[Draft] \{\
.PP
.B "DRAFT: review before publication."
.\}
.el \{\
.PP
Approved publication edition.
.\}
.PP
The same source can select a different message by changing Draft to zero.

Actual output

Conditional text for a chosen edition — GRF-11-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 A controlled draft note



          DRAFT: review before publication.

          The  same  source  can  select a different
     message by changing Draft to zero.
     GRF‐11‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-11-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.ie / .el`	Select one of two conditional branches.
`\{ / \}`	Group multiple requests in a conditional block.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-11-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.nr Draft 1
.TL
A controlled draft note
.ie \n[Draft] \{\
.PP
.B "DRAFT: review before publication."
.\}
.el \{\
.PP
Approved publication edition.
.\}
.PP
The same source can select a different message by changing Draft to zero.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-11-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Write and ship a longer manual

These complete projects combine the earlier structures. They explain how to document purpose, installation, command usage, configuration, troubleshooting and maintenance in a readable manual.

GRF-12-001

A user guide from title to troubleshooting

This original manual documents the fictional tourfmt command. Its prose answers practical questions in reading order; tables and code blocks keep the interface easy to scan.

Back to figure overview

Complete roff document

.TL
Tour Formatter: user guide
.AU
Documentation team
.AB
An original manual showing how to explain a small command-line program.
.AE
.NH 1
Purpose
.PP
Tour Formatter is a fictional example used to teach documentation structure. Real groff commands in this guide can format the source.
.NH 1
Getting started
.PP
Save this document as manual.ms and compile it with groff.
.DS L
.ft CR
groff -S -e -t -p -ms -Tpdf manual.ms > manual.pdf
.ft
.DE
.NH 1
Command usage
.PP
The imaginary command accepts one source file and an optional device selection.
.DS L
.ft CR
tourfmt -T pdf input.ms
.ft
.DE
.NH 1
Configuration
.TS
box tab(;);
l l.
Setting;Default
device;pdf
warnings;enabled
.TE
.NH 1
Troubleshooting
.IP "Missing macro package" 6
Check the package name and the local groff installation.
.IP "Unexpected line break" 6
Look for a no-fill display or a forced break in the source.
.NH 1
Maintenance
.PP
Keep the source, sample inputs and build command under version control. Inspect the generated output after a source change.

Actual output

A user guide from title to troubleshooting — GRF-12-001 · Rendered by troff / groff

First-page preview · 2 page(s) in the complete PDF.

Native terminal output

               Tour Formatter: user guide


                   Documentation team


                        ABSTRACT

              An  original manual showing how to
         explain a small command‐line program.


     1.  Purpose

          Tour Formatter is a fictional example used
     to teach documentation  structure.  Real  groff
     commands in this guide can format the source.

     2.  Getting started

          Save  this  document as manual.ms and com‐
     pile it with groff.

     groff ‐S ‐e ‐t ‐p ‐ms ‐Tpdf manual.ms > manual.pdf

     3.  Command usage

          The imaginary command accepts  one  source
     file and an optional device selection.

     tourfmt ‐T pdf input.ms

     4.  Configuration

     ┌────────────────────┐
     │ Setting    Default │
     │ device     pdf     │
     │ warnings   enabled │
     └────────────────────┘







                           ‐2‐            GRF‐12‐001
     5.  Troubleshooting

     Missing macro package
           Check  the  package  name  and  the local
           groff installation.

     Unexpected line break
           Look for a no‐fill display  or  a  forced
           break in the source.

     6.  Maintenance

          Keep  the  source, sample inputs and build
     command under version control. Inspect the gen‐
     erated output after a source change.
     GRF‐12‐001

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-12-001.roff
Typeset 2 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`reading order`	Lead from purpose to a working command, then reference details and failures.
`complete source`	Keep the title, prose, code and tables together in a standalone document.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-12-001
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Tour Formatter: user guide
.AU
Documentation team
.AB
An original manual showing how to explain a small command-line program.
.AE
.NH 1
Purpose
.PP
Tour Formatter is a fictional example used to teach documentation structure. Real groff commands in this guide can format the source.
.NH 1
Getting started
.PP
Save this document as manual.ms and compile it with groff.
.DS L
.ft CR
groff -S -e -t -p -ms -Tpdf manual.ms > manual.pdf
.ft
.DE
.NH 1
Command usage
.PP
The imaginary command accepts one source file and an optional device selection.
.DS L
.ft CR
tourfmt -T pdf input.ms
.ft
.DE
.NH 1
Configuration
.TS
box tab(;);
l l.
Setting;Default
device;pdf
warnings;enabled
.TE
.NH 1
Troubleshooting
.IP "Missing macro package" 6
Check the package name and the local groff installation.
.IP "Unexpected line break" 6
Look for a no-fill display or a forced break in the source.
.NH 1
Maintenance
.PP
Keep the source, sample inputs and build command under version control. Inspect the generated output after a source change.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-12-001\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-12-002

A manual with a generated contents page

XS/XE capture entries with their current page numbers. TC emits them at the end; a print workflow can reorder the PDF pages if front matter is required.

Back to figure overview

Complete roff document

.TL
A short operations manual
.NH 1
Setup
.XS
1. Setup
.XE
.PP
Install groff and keep the document source in a project directory.
.bp
.NH 1
Build
.XS
2. Build
.XE
.PP
Compile the reviewed source and inspect the result.
.bp
.NH 1
Publish
.XS
3. Publish
.XE
.PP
Ship the selected output together with source and licensing information.
.TC

Actual output

A manual with a generated contents page — GRF-12-002 · Rendered by troff / groff

First-page preview · 4 page(s) in the complete PDF.

Native terminal output

                A short operations manual



     1.  Setup

          Install groff and keep the document source
     in a project directory.






































                           ‐2‐            GRF‐12‐002
     2.  Build

          Compile  the  reviewed  source and inspect
     the result.













































                           ‐3‐            GRF‐12‐002
     3.  Publish

          Ship the  selected  output  together  with
     source and licensing information.













































                           ‐i‐            GRF‐12‐002

                    Table of Contents


     1. Setup  . . . . . . . . . . . . . . . . .   1
     2. Build  . . . . . . . . . . . . . . . . .   2
     3. Publish  . . . . . . . . . . . . . . . .   3
     GRF‐12‐002

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-12-002.roff
Typeset 4 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`.XS / .XE`	Capture a contents entry with the current page number.
`.TC`	Print the collected table of contents on a new page.
`placement`	This complete example deliberately places the contents at the end.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-12-002
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A short operations manual
.NH 1
Setup
.XS
1. Setup
.XE
.PP
Install groff and keep the document source in a project directory.
.bp
.NH 1
Build
.XS
2. Build
.XE
.PP
Compile the reviewed source and inspect the result.
.bp
.NH 1
Publish
.XS
3. Publish
.XE
.PP
Ship the selected output together with source and licensing information.
.TC
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-12-002\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-12-003

Stable references to numbered sections

Capture the ms section-number string immediately after a heading. Later prose can refer to that saved value rather than hard-coding the number.

Back to figure overview

Complete roff document

.TL
References that follow the structure
.NH 1
Installation
.ds SetupSection \*[SN-NO-DOT]
.PP
Install the formatter and choose a macro package.
.NH 1
Building
.ds BuildSection \*[SN-NO-DOT]
.PP
The prerequisites appear in section \*[SetupSection].
.NH 1
Troubleshooting
.PP
Repeat the command described in section \*[BuildSection] before investigating a display problem.

Actual output

Stable references to numbered sections — GRF-12-003 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

          References that follow the structure



     1.  Installation

          Install  the  formatter and choose a macro
     package.

     2.  Building

          The prerequisites appear in section 1.

     3.  Troubleshooting

          Repeat the command described in section  2
     before investigating a display problem.
     GRF‐12‐003

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-12-003.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`\*[SN-NO-DOT]`	Read the current ms section number.
`.ds SetupSection`	Save the current number at the heading, before another heading changes it.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-12-003
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
References that follow the structure
.NH 1
Installation
.ds SetupSection \*[SN-NO-DOT]
.PP
Install the formatter and choose a macro package.
.NH 1
Building
.ds BuildSection \*[SN-NO-DOT]
.PP
The prerequisites appear in section \*[SetupSection].
.NH 1
Troubleshooting
.PP
Repeat the command described in section \*[BuildSection] before investigating a display problem.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-12-003\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-12-004

A compact API reference

Document a fictional configuration-file interface using purpose, fields, defaults and examples. An interface manual needs exact names and clear failure behavior.

Back to figure overview

Complete roff document

.TL
Configuration reference
.NH 1
Format
.PP
This invented interface reads one key=value pair per line. Unknown keys cause a configuration error.
.NH 1
Fields
.TS
box tab(;);
l l lw(1.7i).
Name;Default;Meaning
_
device;pdf;Output device
strict;yes;Reject unknown keys
.TE
.NH 1
Example
.DS L
.ft CR
device=pdf
strict=yes
.ft
.DE
.NH 1
Compatibility
.PP
Document changes to defaults and accepted values when the interface changes. Examples must match the version being described.

Actual output

A compact API reference — GRF-12-004 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

                 Configuration reference



     1.  Format

          This    invented   interface   reads   one
     key=value pair per line. Unknown keys  cause  a
     configuration error.

     2.  Fields

     ┌────────────────────────────────────────┐
     │ Name     Default   Meaning             │
     ├────────────────────────────────────────┤
     │ device   pdf       Output device       │
     │ strict   yes       Reject unknown keys │
     └────────────────────────────────────────┘

     3.  Example

     device=pdf
     strict=yes

     4.  Compatibility

          Document  changes to defaults and accepted
     values when  the  interface  changes.  Examples
     must match the version being described.
     GRF‐12‐004

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-12-004.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`exact field names`	Make configuration keys easy to copy without ambiguity.
`defaults and failures`	State omitted-value behavior and invalid-input behavior.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-12-004
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Configuration reference
.NH 1
Format
.PP
This invented interface reads one key=value pair per line. Unknown keys cause a configuration error.
.NH 1
Fields
.TS
box tab(;);
l l lw(1.7i).
Name;Default;Meaning
_
device;pdf;Output device
strict;yes;Reject unknown keys
.TE
.NH 1
Example
.DS L
.ft CR
device=pdf
strict=yes
.ft
.DE
.NH 1
Compatibility
.PP
Document changes to defaults and accepted values when the interface changes. Examples must match the version being described.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-12-004\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-12-005

A technical note with prose, table, math and diagram

A single source combines all three preprocessors with ms. The supplied numbers are invented, and the equation defines the summary printed in the table.

Back to figure overview

Complete roff document

.TL
A reproducible measurement note
.AU
Documentation team
.AB
Two synthetic measurements illustrate a complete technical note.
.AE
.NH 1
Method
.PP
Collect two values and report their arithmetic mean.
.ie n \{\
.LP
Diagram: Input, then Summarize, then Report.
.\}
.el \{\
.PS
box "Input"; arrow; box "Summarize"; arrow; box "Report"
.PE
.\}
.NH 1
Values
.TS
box tab(;);
l n.
Sample;Value
_
A;12
B;18
.TE
.NH 1
Definition
.EQ
x bar = {12 + 18} over 2 = 15
.EN
.NH 1
Interpretation
.PP
The mean describes only these two invented values. It does not provide an uncertainty estimate or support a population claim.

Actual output

A technical note with prose, table, math and diagram — GRF-12-005 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

             A reproducible measurement note


                   Documentation team


                        ABSTRACT

              Two  synthetic measurements illus‐
         trate a complete technical note.


     1.  Method

          Collect two values and report their arith‐
     metic mean.

     Diagram: Input, then Summarize, then Report.

     2.  Values

     ┌────────────────┐
     │ Sample   Value │
     ├────────────────┤
     │ A         12   │
     │ B         18   │
     └────────────────┘

     3.  Definition

                       _x=1_2_+2_1_8_=15

     4.  Interpretation

          The mean describes only these two invented
     values. It does not provide an uncertainty  es‐
     timate or support a population claim.
     GRF‐12‐005

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-12-005.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`-e / -t / -p`	Run eqn, tbl and pic before formatting.
`explicit definition`	State exactly how the reported summary relates to the displayed input.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-12-005
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
A reproducible measurement note
.AU
Documentation team
.AB
Two synthetic measurements illustrate a complete technical note.
.AE
.NH 1
Method
.PP
Collect two values and report their arithmetic mean.
.ie n \{\
.LP
Diagram: Input, then Summarize, then Report.
.\}
.el \{\
.PS
box "Input"; arrow; box "Summarize"; arrow; box "Report"
.PE
.\}
.NH 1
Values
.TS
box tab(;);
l n.
Sample;Value
_
A;12
B;18
.TE
.NH 1
Definition
.EQ
x bar = {12 + 18} over 2 = 15
.EN
.NH 1
Interpretation
.PP
The mean describes only these two invented values. It does not provide an uncertainty estimate or support a population claim.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-12-005\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

GRF-12-006

A release note and documentation checklist

Release documentation explains user-visible changes and how to verify them. The checklist is part of an original example document.

Back to figure overview

Complete roff document

.TL
Documentation release note
.AU
Documentation team
.NH 1
Changes
.IP \(bu 2
Clarified the output-device option.
.IP \(bu 2
Added a complete command example and troubleshooting advice.
.NH 1
Verification
.IP "Source" 7
Read every option name and check each example against the described interface.
.IP "Terminal" 7
Inspect plain-text output at a useful terminal width.
.IP "PDF" 7
Check page breaks, tables, equations and diagrams.
.IP "HTML" 7
Check links and any generated image companions.
.NH 1
Publication
.PP
Keep original sources, reusable assets and licensing information. Publish the selected reader-facing outputs and retain the exact build command.

Actual output

A release note and documentation checklist — GRF-12-006 · Rendered by troff / groff

First-page preview · 1 page(s) in the complete PDF.

Native terminal output

               Documentation release note


                   Documentation team


     1.  Changes

     • Clarified the output‐device option.

     • Added  a  complete  command example and trou‐
       bleshooting advice.

     2.  Verification

     Source Read every option name  and  check  each
            example against the described interface.

     Terminal
            Inspect  plain‐text  output  at a useful
            terminal width.

     PDF    Check page breaks, tables, equations and
            diagrams.

     HTML   Check links and any generated image com‐
            panions.

     3.  Publication

          Keep original sources, reusable assets and
     licensing  information.  Publish  the  selected
     reader‐facing  outputs  and  retain  the  exact
     build command.
     GRF‐12‐006

troff / groff · exit 0

Native compiler log

Standard output

GNU groff version 1.24.2
groff -S -Kutf8 -e -t -p -mms -Tpdf -P-pa5 GRF-12-006.roff
Typeset 1 page(s) successfully.
Native PDF written to stdout; captured in the PDF download.
Native diagnostics: none (successful run).

Command or parameter	Meaning
`user-visible changes`	Explain the changed interface or explanation, rather than only listing edited files.
`multiple devices`	Review each output device used for publication.

Complete standalone troff / groff program

.\" Complete independent document; no previous example is required.
.nr PO .5i
.nr LL 4.7i
.nr LT 4.7i
.nr HM .55i
.nr FM .55i
.nr PS 10
.nr VS 13
.ds RH GRF-12-006
.if n .ftr CR R
.pl 8.2677i
.\" BEGIN EXAMPLE
.TL
Documentation release note
.AU
Documentation team
.NH 1
Changes
.IP \(bu 2
Clarified the output-device option.
.IP \(bu 2
Added a complete command example and troubleshooting advice.
.NH 1
Verification
.IP "Source" 7
Read every option name and check each example against the described interface.
.IP "Terminal" 7
Inspect plain-text output at a useful terminal width.
.IP "PDF" 7
Check page breaks, tables, equations and diagrams.
.IP "HTML" 7
Check links and any generated image companions.
.NH 1
Publication
.PP
Keep original sources, reusable assets and licensing information. Publish the selected reader-facing outputs and retain the exact build command.
.\" END EXAMPLE
.br
.sp .4v
.nf
.ps 7
\f[CR]GRF-12-006\f[]
.fi

Download: troff / groff source · Terminal text · SVG first page · Complete PDF · PNG first page

Example and command index

GRF-01-001 · Your first typeset page
GRF-01-002 · Filled and literal lines
GRF-01-003 · Spaces, comments and literal control characters
GRF-01-004 · Units and relative changes
GRF-02-001 · Title, author and abstract
GRF-02-002 · Numbered sections and subsections
GRF-02-003 · Indented and flush-left paragraphs
GRF-02-004 · Document-wide settings
GRF-03-001 · Emphasis and font families
GRF-03-002 · Special characters and accents
GRF-03-003 · Alignment choices
GRF-03-004 · Size changes with restoration
GRF-04-001 · Bullets, numbers and terms
GRF-04-002 · A code block with preserved spacing
GRF-04-003 · Quotations and footnotes
GRF-04-004 · Keep a small explanation together
GRF-05-001 · Headers and page numbers
GRF-05-002 · Two columns for a compact report
GRF-05-003 · Landscape geometry in raw troff
GRF-05-004 · Page breaks and space reservations
GRF-06-001 · A complete minimal man page
GRF-06-002 · Command synopsis and options
GRF-06-003 · Examples, literal code and escaping
GRF-06-004 · Files, environment and exit status
GRF-06-005 · Links and manual cross-references
GRF-06-006 · A small command reference ready to ship
GRF-07-001 · The mdoc document skeleton
GRF-07-002 · Options as a tagged semantic list
GRF-07-003 · Paths, variables and references
GRF-07-004 · Literal examples and a caution
GRF-08-001 · A small numeric table
GRF-08-002 · Heading rules and column alignment
GRF-08-003 · A paragraph inside a table cell
GRF-08-004 · A table with a spanned heading
GRF-09-001 · Fractions and square roots
GRF-09-002 · Sums, limits and integrals
GRF-09-003 · Matrices and scalable delimiters
GRF-09-004 · Inline equations in explanatory prose
GRF-10-001 · A left-to-right workflow
GRF-10-002 · Branches and named anchors
GRF-10-003 · Geometry from variables
GRF-10-004 · A small chart from rectangles
GRF-11-001 · Strings for repeated names
GRF-11-002 · Number registers and arithmetic
GRF-11-003 · A macro with an argument
GRF-11-004 · Conditional text for a chosen edition
GRF-12-001 · A user guide from title to troubleshooting
GRF-12-002 · A manual with a generated contents page
GRF-12-003 · Stable references to numbered sections
GRF-12-004 · A compact API reference
GRF-12-005 · A technical note with prose, table, math and diagram
GRF-12-006 · A release note and documentation checklist

Content: CC0 1.0. Structure and publishing framework: CC BY 4.0 by Lukas C. Bossert. Repository source · Publishing framework source · License scope and third-party notices.

troff / groff,one change at a time

All documents at a glance

Start with text and the command line

Build a document with ms

Typography and readable source

Lists, code, quotations and notes

Page layout, columns and running text

Write a Unix man page

Semantic manuals with mdoc

Tables with tbl

Mathematics with eqn

Diagrams with pic

Define reusable formatting

Write and ship a longer manual

Three ways to see a change

From a source file to a document

Read the source beside its actual output

Write documentation, not only typography

Publish PDF, terminal text and HTML

Primary references

Start with text and the command line

Your first typeset page

Complete roff document

Actual output

Standard output

Filled and literal lines

Complete roff document

Actual output

Standard output

Spaces, comments and literal control characters

Complete roff document

Actual output

Standard output

Units and relative changes

Complete roff document

Actual output

Standard output

Build a document with ms

Title, author and abstract

Complete roff document

Actual output

Standard output

Numbered sections and subsections

Complete roff document

Actual output

Standard output

Indented and flush-left paragraphs

Complete roff document

Actual output

Standard output

Document-wide settings

Complete roff document

Actual output

Standard output

Typography and readable source

Emphasis and font families

Complete roff document

Actual output

Standard output

Special characters and accents

Complete roff document

Actual output

Standard output

Alignment choices

Complete roff document

Actual output

Standard output

Size changes with restoration

Complete roff document

Actual output

Standard output

Lists, code, quotations and notes

Bullets, numbers and terms

Complete roff document

Actual output

Standard output

A code block with preserved spacing

Complete roff document

Actual output

Standard output

troff / groff,
one change at a time