[groff] 04/04: grotty.1.man: Add "Example" section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a01b0760eda23798843d1ee65786f9fb60b32e4e
Author: G. Branden Robinson <address@hidden>
Date:   Sun Jun 30 18:17:02 2019 +1000

    grotty.1.man: Add "Example" section.
    
    Ulterior motive: test suite for TTY output devices.
---
 src/devices/grotty/grotty.1.man | 77 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index b90e681..659c4fc 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -603,6 +603,83 @@ affecting all subsequent operations.
 .
 .
 .\" ====================================================================
+.SH EXAMPLE
+.\" ====================================================================
+.
+The following
+.I groff
+document exercises several features,
+not all of which may be supported by a given output device:
+(1)\~bold style;
+(2)\~italic (underline) style;
+(3)\~bold-italic style;
+(4)\~character composition by overstriking (\[lq]co\[:o]perate\[rq]);
+(5)\~foreground color;
+(6)\~background color; and
+(7)\~horizontal and vertical line-drawing.
+.
+.
+.LP
+.RS
+.EX
+\&.pl 15v
+You might see \ef[B]bold\ef[] and \ef[I]italic\ef[].
+Some people see \ef[BI]both\ef[].
+If the output device does (not) co\ez\e[ad]operate,
+you might see \em[red]red\em[].
+Black on cyan can have a \eM[cyan]\em[black]prominent\em[]\eM[]
+\eD'l 1i 0'\eD'l 0 2i'\eD'l 1i 0' look.
+.EE
+.RE
+.
+.
+.LP
+Compare and contrast the output of the following:
+.
+.
+.LP
+.RS
+.EX
+$ \c
+.B nroff \c
+.I file
+$ \c
+.B groff \-T ascii \c
+.I file
+$ \c
+.B groff \-T utf8 \-Z \c
+.I file \c
+.B | grotty \-i
+$ \c
+.B groff \-T utf8 \-Z \c
+.I file \c
+.B | grotty \-c | ul
+.EE
+.RE
+.
+.
+.\" I wish this went without saying...
+.LP
+Note that the example file above is a \[lq]raw\[rq]
+.I groff
+document,
+not a man page.
+.
+.\" Yes, using \f[BI] here is slightly hypocritical.
+Use of color escapes in man pages is \f[BI]strongly discouraged\f[].
+.
+Some implementations of
+.IR man (1)
+.\" ...like man-db 2.8.5-2 on Debian Buster...
+completely disable them.
+.
+See subsection \[lq]Portability\[rq] of
+.IR groff_man (7)
+for guidance on writing man pages that are viewable by as many readers
+as possible.
+.
+.
+.\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
 .