1 .\"     $Id: roff.7,v 1.94 2017/07/05 12:25:17 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010,2011,2013-2015,2017 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: July 5 2017 $
  19 .Dt ROFF 5
  20 .Os
  21 .Sh NAME
  22 .Nm roff
  23 .Nd roff language reference for mandoc
  24 .Sh DESCRIPTION
  25 The
  26 .Nm roff
  27 language is a general purpose text formatting language.
  28 Since traditional implementations of the
  29 .Xr mdoc 5
  30 and
  31 .Xr man 5
  32 manual formatting languages are based on it,
  33 many real-world manuals use small numbers of
  34 .Nm
  35 requests and escape sequences intermixed with their
  36 .Xr mdoc 5
  37 or
  38 .Xr man 5

1331 Switch to no-fill mode.
1332 See
1333 .Xr man 5 .
1334 Ignored by
1335 .Xr mdoc 5 .
1336 .It Ic \&nh
1337 Turn off automatic hyphenation mode.
1338 Currently ignored.
1339 .It Ic \&nhychar Ar char ...
1340 Define hyphenation-inhibiting characters.
1341 This is a Heirloom extension and currently ignored.
1342 .It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent
1343 Print line numbers.
1344 Currently unsupported.
1345 .It Ic \&nn Op Ar number
1346 Temporarily turn off line numbering.
1347 Currently unsupported.
1348 .It Ic \&nop Ar body
1349 Execute the rest of the input line as a request or macro line.
1350 Currently unsupported.
1351 .It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
1352 Define or change a register.
1353 A register is an arbitrary string value that defines some sort of state,
1354 which influences parsing and/or formatting.
1355 For the syntax of
1356 .Ar expression ,
1357 see
1358 .Sx Numerical expressions
1359 below.
1360 If it is prefixed by a sign, the register will be
1361 incremented or decremented instead of assigned to.
1362 .Pp








1363 The following
1364 .Ar register
1365 is handled specially:
1366 .Bl -tag -width Ds
1367 .It Cm nS
1368 If set to a positive integer value, certain
1369 .Xr mdoc 5
1370 macros will behave in the same way as in the
1371 .Em SYNOPSIS
1372 section.
1373 If set to 0, these macros will behave in the same way as outside the
1374 .Em SYNOPSIS
1375 section, even when called within the
1376 .Em SYNOPSIS
1377 section itself.
1378 Note that starting a new
1379 .Xr mdoc 5
1380 section with the
1381 .Ic \&Sh
1382 macro will reset this register.

1454 Change point size.
1455 Currently ignored.
1456 .It Ic \&psbb Ar filename
1457 Retrieve the bounding box of a PostScript file.
1458 Currently unsupported.
1459 .It Ic \&pshape Ar indent length ...
1460 Set a special shape for the current paragraph.
1461 This is a Heirloom extension and currently unsupported.
1462 .It Ic \&pso Ar command
1463 Include output of a shell command.
1464 Ignored because insecure.
1465 .It Ic \&ptr
1466 Print the names and positions of all traps on standard error output.
1467 This is a groff extension and currently ignored.
1468 .It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
1469 Change post-vertical spacing.
1470 This is a groff extension and currently ignored.
1471 .It Ic \&rchar Ar glyph ...
1472 Remove glyph definitions.
1473 Currently unsupported.
1474 .It Ic \&rd Op Ar prompt Op Ar agument ...
1475 Read from standard input.
1476 Currently ignored.
1477 .It Ic \&recursionlimit Ar maxrec maxtail
1478 Set the maximum stack depth for recursive macros.
1479 This is a Heirloom extension and currently ignored.
1480 .It Ic \&return Op Ar twice
1481 Exit a macro and return to the caller.
1482 Currently unsupported.
1483 .It Ic \&rfschar Ar font glyph ...
1484 Remove font-specific fallback glyph definitions.
1485 Currently unsupported.
1486 .It Ic \&rhang Ar font char ... afmunits
1487 Hang characters at right margin.
1488 This is a Heirloom extension and currently ignored.
1489 .It Ic \&rj Op Ar N
1490 Justify the next
1491 .Ar N
1492 input lines to the right margin without filling.
1493 .Ar N
1494 defaults to 1.

1979 using the glyph
1980 .Ar c .
1981 .Ss \eM Ns Bq Ar name
1982 Set fill (background) color (groff extension); ignored by
1983 .Xr mandoc 1 .
1984 For short names, there are variants
1985 .No \eM Ns Ar c
1986 and
1987 .No \eM( Ns Ar cc .
1988 .Ss \em Ns Bq Ar name
1989 Set glyph drawing color (groff extension); ignored by
1990 .Xr mandoc 1 .
1991 For short names, there are variants
1992 .No \em Ns Ar c
1993 and
1994 .No \em( Ns Ar cc .
1995 .Ss \eN\(aq Ns Ar number Ns \(aq
1996 Character
1997 .Ar number
1998 on the current font.
1999 .Ss \en Ns Bq Ar name
2000 Interpolate the number register
2001 .Ar name .
2002 For short names, there are variants
2003 .No \en Ns Ar c
2004 and
2005 .No \en( Ns Ar cc .






2006 .Ss \eo\(aq Ns Ar string Ns \(aq
2007 Overstrike, writing all the characters contained in the
2008 .Ar string
2009 to the same output position.
2010 In terminal and HTML output modes,
2011 only the last one of the characters is visible.
2012 .Ss \ep
2013 Break the output line at the end of the current word.
2014 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
2015 Set number register; ignored by
2016 .Xr mandoc 1 .
2017 .Ss \eS\(aq Ns Ar number Ns \(aq
2018 Slant output; ignored by
2019 .Xr mandoc 1 .
2020 .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
2021 Change point size; ignored by
2022 .Xr mandoc 1 .
2023 Alternative forms
2024 .No \es Ns Oo +|- Oc Ns Ar n ,
2025 .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,

   1 .\"     $Id: roff.7,v 1.96 2018/04/10 00:52:30 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2010-2018 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: April 10 2018 $
  19 .Dt ROFF 5
  20 .Os
  21 .Sh NAME
  22 .Nm roff
  23 .Nd roff language reference for mandoc
  24 .Sh DESCRIPTION
  25 The
  26 .Nm roff
  27 language is a general purpose text formatting language.
  28 Since traditional implementations of the
  29 .Xr mdoc 5
  30 and
  31 .Xr man 5
  32 manual formatting languages are based on it,
  33 many real-world manuals use small numbers of
  34 .Nm
  35 requests and escape sequences intermixed with their
  36 .Xr mdoc 5
  37 or
  38 .Xr man 5

1331 Switch to no-fill mode.
1332 See
1333 .Xr man 5 .
1334 Ignored by
1335 .Xr mdoc 5 .
1336 .It Ic \&nh
1337 Turn off automatic hyphenation mode.
1338 Currently ignored.
1339 .It Ic \&nhychar Ar char ...
1340 Define hyphenation-inhibiting characters.
1341 This is a Heirloom extension and currently ignored.
1342 .It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent
1343 Print line numbers.
1344 Currently unsupported.
1345 .It Ic \&nn Op Ar number
1346 Temporarily turn off line numbering.
1347 Currently unsupported.
1348 .It Ic \&nop Ar body
1349 Execute the rest of the input line as a request or macro line.
1350 Currently unsupported.
1351 .It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize
1352 Define or change a register.
1353 A register is an arbitrary string value that defines some sort of state,
1354 which influences parsing and/or formatting.
1355 For the syntax of
1356 .Ar expression ,
1357 see
1358 .Sx Numerical expressions
1359 below.
1360 If it is prefixed by a sign, the register will be
1361 incremented or decremented instead of assigned to.
1362 .Pp
1363 The
1364 .Ar stepsize
1365 is used by the
1366 .Ic \en+
1367 auto-increment feature.
1368 It remains unchanged when omitted while changing an existing register,
1369 and it defaults to 0 when defining a new register.
1370 .Pp
1371 The following
1372 .Ar register
1373 is handled specially:
1374 .Bl -tag -width Ds
1375 .It Cm nS
1376 If set to a positive integer value, certain
1377 .Xr mdoc 5
1378 macros will behave in the same way as in the
1379 .Em SYNOPSIS
1380 section.
1381 If set to 0, these macros will behave in the same way as outside the
1382 .Em SYNOPSIS
1383 section, even when called within the
1384 .Em SYNOPSIS
1385 section itself.
1386 Note that starting a new
1387 .Xr mdoc 5
1388 section with the
1389 .Ic \&Sh
1390 macro will reset this register.

1462 Change point size.
1463 Currently ignored.
1464 .It Ic \&psbb Ar filename
1465 Retrieve the bounding box of a PostScript file.
1466 Currently unsupported.
1467 .It Ic \&pshape Ar indent length ...
1468 Set a special shape for the current paragraph.
1469 This is a Heirloom extension and currently unsupported.
1470 .It Ic \&pso Ar command
1471 Include output of a shell command.
1472 Ignored because insecure.
1473 .It Ic \&ptr
1474 Print the names and positions of all traps on standard error output.
1475 This is a groff extension and currently ignored.
1476 .It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
1477 Change post-vertical spacing.
1478 This is a groff extension and currently ignored.
1479 .It Ic \&rchar Ar glyph ...
1480 Remove glyph definitions.
1481 Currently unsupported.
1482 .It Ic \&rd Op Ar prompt Op Ar argument ...
1483 Read from standard input.
1484 Currently ignored.
1485 .It Ic \&recursionlimit Ar maxrec maxtail
1486 Set the maximum stack depth for recursive macros.
1487 This is a Heirloom extension and currently ignored.
1488 .It Ic \&return Op Ar twice
1489 Exit a macro and return to the caller.
1490 Currently unsupported.
1491 .It Ic \&rfschar Ar font glyph ...
1492 Remove font-specific fallback glyph definitions.
1493 Currently unsupported.
1494 .It Ic \&rhang Ar font char ... afmunits
1495 Hang characters at right margin.
1496 This is a Heirloom extension and currently ignored.
1497 .It Ic \&rj Op Ar N
1498 Justify the next
1499 .Ar N
1500 input lines to the right margin without filling.
1501 .Ar N
1502 defaults to 1.

1987 using the glyph
1988 .Ar c .
1989 .Ss \eM Ns Bq Ar name
1990 Set fill (background) color (groff extension); ignored by
1991 .Xr mandoc 1 .
1992 For short names, there are variants
1993 .No \eM Ns Ar c
1994 and
1995 .No \eM( Ns Ar cc .
1996 .Ss \em Ns Bq Ar name
1997 Set glyph drawing color (groff extension); ignored by
1998 .Xr mandoc 1 .
1999 For short names, there are variants
2000 .No \em Ns Ar c
2001 and
2002 .No \em( Ns Ar cc .
2003 .Ss \eN\(aq Ns Ar number Ns \(aq
2004 Character
2005 .Ar number
2006 on the current font.
2007 .Ss \en Ns Oo +|- Oc Ns Bq Ar name
2008 Interpolate the number register
2009 .Ar name .
2010 For short names, there are variants
2011 .No \en Ns Ar c
2012 and
2013 .No \en( Ns Ar cc .
2014 If the optional sign is specified,
2015 the register is first incremented or decremented by the
2016 .Ar stepsize
2017 that was specified in the relevant
2018 .Ic \&nr
2019 request, and the changed value is interpolated.
2020 .Ss \eo\(aq Ns Ar string Ns \(aq
2021 Overstrike, writing all the characters contained in the
2022 .Ar string
2023 to the same output position.
2024 In terminal and HTML output modes,
2025 only the last one of the characters is visible.
2026 .Ss \ep
2027 Break the output line at the end of the current word.
2028 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
2029 Set number register; ignored by
2030 .Xr mandoc 1 .
2031 .Ss \eS\(aq Ns Ar number Ns \(aq
2032 Slant output; ignored by
2033 .Xr mandoc 1 .
2034 .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
2035 Change point size; ignored by
2036 .Xr mandoc 1 .
2037 Alternative forms
2038 .No \es Ns Oo +|- Oc Ns Ar n ,
2039 .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,