summaryrefslogtreecommitdiffstats
path: root/src/roff/nroff
diff options
context:
space:
mode:
Diffstat (limited to 'src/roff/nroff')
-rw-r--r--src/roff/nroff/nroff.1.man358
-rw-r--r--src/roff/nroff/nroff.am44
-rw-r--r--src/roff/nroff/nroff.sh204
-rwxr-xr-xsrc/roff/nroff/tests/verbose_option_works.sh68
4 files changed, 674 insertions, 0 deletions
diff --git a/src/roff/nroff/nroff.1.man b/src/roff/nroff/nroff.1.man
new file mode 100644
index 0000000..cdefee1
--- /dev/null
+++ b/src/roff/nroff/nroff.1.man
@@ -0,0 +1,358 @@
+.TH @g@nroff @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+@g@nroff \- format documents with
+.I groff
+for TTY (terminal) devices
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_nroff_1_man_C \n[.cp]
+.cp 0
+.
+.\" Define fallback for groff 1.23's MR macro if the system lacks it.
+.nr do-fallback 0
+.if !\n(.f .nr do-fallback 1 \" mandoc
+.if \n(.g .if !d MR .nr do-fallback 1 \" older groff
+.if !\n(.g .nr do-fallback 1 \" non-groff *roff
+.if \n[do-fallback] \{\
+. de MR
+. ie \\n(.$=1 \
+. I \%\\$1
+. el \
+. IR \%\\$1 (\\$2)\\$3
+. .
+.\}
+.rr do-fallback
+.
+.
+.\" ====================================================================
+.SH Synopsis
+.\" ====================================================================
+.
+.SY @g@nroff
+.RB [ \-bcCEhikpRStUVz ]
+.RB [ \-d\~\c
+.IR ctext ]
+.RB [ \-d\~\c
+.IB string =\c
+.IR text ]
+.RB [ \-K\~\c
+.IR fallback-encoding ]
+.RB [ \-m\~\c
+.IR macro-package ]
+.RB [ \-M\~\c
+.IR macro-directory ]
+.RB [ \-n\~\c
+.IR page-number ]
+.RB [ \-o\~\c
+.IR page-list ]
+.RB [ \-P\~\c
+.IR postprocessor-argument ]
+.RB [ \-r\~\c
+.IR cnumeric-expression ]
+.RB [ \-r\~\c
+.IB register =\c
+.IR numeric-expression ]
+.RB [ \-T\~\c
+.IR output-device ]
+.RB [ \-w\~\c
+.IR warning-category ]
+.RB [ \-W\~\c
+.IR warning-category ]
+.RI [ file\~ .\|.\|.]
+.YS
+.
+.
+.SY @g@nroff
+.B \-\-help
+.YS
+.
+.
+.SY @g@nroff
+.B \-v
+.
+.SY @g@nroff
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+.I @g@nroff
+formats documents written in the
+.MR groff @MAN7EXT@
+language for typewriter-like devices such as terminal emulators.
+.
+GNU
+.I nroff \" GNU
+emulates the AT&T
+.I nroff \" AT&T
+command using
+.MR groff @MAN1EXT@ .
+.
+.I @g@nroff
+generates output via
+.MR grotty @MAN1EXT@ ,
+.IR groff 's
+terminal output driver,
+which needs to know the character encoding scheme used by the device.
+.
+Consequently,
+acceptable arguments to the
+.B \-T
+option are
+.BR ascii ,
+.BR latin1 ,
+.BR utf8 ,
+and
+.BR cp1047 ;
+any others are ignored.
+.
+If neither the
+.I \%GROFF_TYPESETTER
+environment variable nor the
+.B \-T
+command-line option
+(which overrides the environment variable)
+specifies a (valid) device,
+.I @g@nroff
+consults the locale to select an appropriate output device.
+.
+It first tries the
+.MR locale 1
+program,
+then checks several locale-related environment variables;
+see section \[lq]Environment\[rq] below.
+.
+If all of the foregoing fail,
+.B \-Tascii
+is implied.
+.
+.
+.P
+The
+.BR \-b ,
+.BR \-c ,
+.BR \-C ,
+.BR \-d ,
+.BR \-E ,
+.BR \-i ,
+.BR \-m ,
+.BR \-M ,
+.BR \-n ,
+.BR \-o ,
+.BR \-r ,
+.BR \-U ,
+.BR \-w ,
+.BR \-W ,
+and
+.B \-z
+options have the effects described in
+.MR @g@troff @MAN1EXT@ .
+.
+.B \-c
+and
+.B \-h
+imply
+.RB \[lq] \-P\-c \[rq]
+and
+.RB \[lq] \-P\-h \[rq],
+respectively;
+.B \-c
+is also interpreted directly by
+.IR @g@troff .
+.
+In addition,
+this implementation ignores the AT&T
+.I nroff \" AT&T
+options
+.BR \-e ,
+.BR \-q ,
+and
+.B \-s
+(which are not implemented in
+.IR groff ).
+.
+The options
+.BR \-k ,
+.BR \-K ,
+.BR \-p ,
+.BR \-P ,
+.BR \-R ,
+.BR \-t ,
+and
+.B \-S
+are documented in
+.MR groff @MAN1EXT@ .
+.
+.B \-V
+causes
+.I @g@nroff
+to display the constructed
+.I groff
+command on the standard output stream,
+but does not execute it.
+.
+.B \-v
+and
+.B \-\-version
+show version information about
+.I @g@nroff
+and the programs it runs,
+while
+.B \-\-help
+displays a usage message;
+all exit afterward.
+.
+.
+.\" ====================================================================
+.SH "Exit status"
+.\" ====================================================================
+.
+.I @g@nroff
+exits with error
+.RB status\~ 2
+if there was a problem parsing its arguments,
+with
+.RB status\~ 0
+if any of the options
+.BR \-V ,
+.BR \-v ,
+.BR \-\-version ,
+or
+.B \-\-help
+were specified,
+and with the status of
+.I groff
+otherwise.
+.
+.
+.\" ====================================================================
+.SH Environment
+.\" ====================================================================
+.
+Normally,
+the path separator in environment variables ending with
+.I PATH
+is the colon;
+this may vary depending on the operating system.
+.
+For example,
+Windows uses a semicolon instead.
+.
+.
+.TP
+.I GROFF_BIN_PATH
+is a colon-separated list of directories in which to search for the
+.I groff
+executable before searching in
+.IR PATH .
+.
+If unset,
+.I @BINDIR@
+is used.
+.
+.
+.TP
+.I GROFF_TYPESETTER
+specifies the default output device for
+.IR groff .
+.
+.
+.TP
+.I LC_ALL
+.TQ
+.I LC_CTYPE
+.TQ
+.I LANG
+.TQ
+.I LESSCHARSET
+are pattern-matched in this order for contents matching standard
+character encodings supported by
+.I groff
+in the event no
+.B \-T
+option is given and
+.I \%GROFF_TYPESETTER
+is unset,
+or the values specified are invalid.
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I @MACRODIR@/\:\%tty\-char\:.tmac
+defines fallback definitions of
+.I roff
+special characters.
+.
+These definitions more poorly optically approximate typeset output
+than those of
+.I tty.tmac
+in favor of communicating semantic information.
+.
+.I nroff
+loads it automatically.
+.
+.
+.\" ====================================================================
+.SH Notes
+.\" ====================================================================
+.
+Pager programs like
+.MR more 1
+and
+.MR less 1
+may require command-line options to correctly handle some output
+sequences;
+see
+.MR grotty @MAN1EXT@ .
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.MR groff @MAN1EXT@ ,
+.MR @g@troff @MAN1EXT@ ,
+.MR grotty @MAN1EXT@ ,
+.MR locale 1 ,
+.MR roff @MAN7EXT@
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_nroff_1_man_C]
+.do rr *groff_nroff_1_man_C
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72:
diff --git a/src/roff/nroff/nroff.am b/src/roff/nroff/nroff.am
new file mode 100644
index 0000000..82738d9
--- /dev/null
+++ b/src/roff/nroff/nroff.am
@@ -0,0 +1,44 @@
+# Copyright (C) 2014-2020 Free Software Foundation, Inc.
+#
+# This file is part of groff.
+#
+# groff is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+prefixexecbin_SCRIPTS += nroff
+nroff_srcdir = $(top_srcdir)/src/roff/nroff
+PREFIXMAN1 += src/roff/nroff/nroff.1
+EXTRA_DIST += \
+ src/roff/nroff/nroff.1.man \
+ src/roff/nroff/nroff.sh
+
+nroff_TESTS = \
+ src/roff/nroff/tests/verbose_option_works.sh
+TESTS += $(nroff_TESTS)
+EXTRA_DIST += $(nroff_TESTS)
+
+nroff: $(nroff_srcdir)/nroff.sh $(SH_DEPS_SED_SCRIPT)
+ $(AM_V_GEN)rm -f $@ \
+ && sed -f $(SH_DEPS_SED_SCRIPT) \
+ -e $(SH_SCRIPT_SED_CMD) \
+ -e "s|[@]VERSION[@]|$(VERSION)|" \
+ $(nroff_srcdir)/nroff.sh \
+ >$@ \
+ && chmod +x $@
+
+
+# Local Variables:
+# mode: makefile-automake
+# fill-column: 72
+# End:
+# vim: set autoindent filetype=automake textwidth=72:
diff --git a/src/roff/nroff/nroff.sh b/src/roff/nroff/nroff.sh
new file mode 100644
index 0000000..77f5c06
--- /dev/null
+++ b/src/roff/nroff/nroff.sh
@@ -0,0 +1,204 @@
+#! /bin/sh
+# Emulate nroff with groff.
+#
+# Copyright (C) 1992-2021 Free Software Foundation, Inc.
+#
+# Written by James Clark, Werner Lemberg, and G. Branden Robinson.
+#
+# This file is part of 'groff'.
+#
+# 'groff' is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License (GPL) as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# 'groff' is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+prog="$0"
+
+T=
+Topt=
+opts=
+dry_run=
+is_option_argument_pending=
+
+usage="usage: $prog [-bcCEhikpRStUVz] [-d ctext] [-d string=text] \
+[-K fallback-encoding] [-m macro-package] [-M macro-directory] \
+[-n page-number] [-o page-list] [-P postprocessor-argument] \
+[-r cnumeric-expression] [-r register=numeric-expression] \
+[-T output-device] [-w warning-category] [-W warning-category] \
+[file ...]
+usage: $prog {-v | --version}
+usage: $prog --help"
+
+for arg
+do
+ if [ -n "$is_option_argument_pending" ]
+ then
+ is_option_argument_pending=
+ opts="$opts $arg"
+ shift
+ continue
+ fi
+
+ case $arg in
+ -c)
+ opts="$opts $arg -P-c" ;;
+ -h)
+ opts="$opts -P-h" ;;
+ -[eq] | -s*)
+ # ignore these options
+ ;;
+ -[dKmMnoPrTwW])
+ is_option_argument_pending=yes
+ opts="$opts $arg" ;;
+ -[bCEikpRStUz] | -[dKMmrnoPwW]*)
+ opts="$opts $arg" ;;
+ -T*)
+ Topt=$arg ;;
+ -u*)
+ # -u is for Solaris compatibility and not otherwise documented.
+ #
+ # Solaris 2.2 through at least Solaris 9 'man' invokes
+ # 'nroff -u0 ... | col -x'. Ignore the -u0, since 'less' and
+ # 'more' can use the emboldening info. But disable SGR, since
+ # Solaris 'col' mishandles it.
+ opts="$opts -P-c" ;;
+ -V)
+ dry_run=yes ;;
+ -v | --version)
+ echo "GNU nroff (groff) version @VERSION@"
+ opts="$opts $arg" ;;
+ --help)
+ echo "$usage"
+ exit 0 ;;
+ --)
+ shift
+ break ;;
+ -)
+ break ;;
+ -*)
+ echo "$prog: usage error: invalid option '$arg'" >&2
+ echo "$usage" >&2
+ exit 2 ;;
+ *)
+ break ;;
+ esac
+ shift
+done
+
+if [ -n "$is_option_argument_pending" ]
+then
+ echo "$prog: usage error: option '$arg' requires an argument" >&2
+ exit 2
+fi
+
+# Determine the -T option. Was a valid one specified?
+case "$Topt" in
+ -Tascii | -Tlatin1 | -Tutf8 | -Tcp1047)
+ T=$Topt ;;
+esac
+
+# -T option absent or invalid; try environment.
+if [ -z "$T" ]
+then
+ Tenv=-T$GROFF_TYPESETTER
+ case "$Tenv" in
+ -Tascii | -Tlatin1 | -Tutf8 | -Tcp1047)
+ T=$Tenv ;;
+ esac
+fi
+
+# Finally, infer a -T option from the locale. Try 'locale charmap'
+# first because it is the most reliable, then look at environment
+# variables.
+if [ -z "$T" ]
+then
+ # The separate `exec` is to work around a ~2004 bug in Cygwin sh.exe.
+ case "`exec 2>/dev/null ; locale charmap`" in
+ UTF-8)
+ Tloc=utf8 ;;
+ ISO-8859-1 | ISO-8859-15)
+ Tloc=latin1 ;;
+ IBM-1047)
+ Tloc=cp1047 ;;
+ *)
+ # Some old shells don't support ${FOO:-bar} expansion syntax. We
+ # should switch to it when it is safe to abandon support for them.
+ case "${LC_ALL-${LC_CTYPE-${LANG}}}" in
+ *.UTF-8)
+ Tloc=utf8 ;;
+ iso_8859_1 | *.ISO-8859-1 | *.ISO8859-1 | \
+ iso_8859_15 | *.ISO-8859-15 | *.ISO8859-15)
+ Tloc=latin1 ;;
+ *.IBM-1047)
+ Tloc=cp1047 ;;
+ *)
+ case "$LESSCHARSET" in
+ utf-8)
+ Tloc=utf8 ;;
+ latin1)
+ Tloc=latin1 ;;
+ cp1047)
+ Tloc=cp1047 ;;
+ *)
+ Tloc=ascii ;;
+ esac ;;
+ esac ;;
+ esac
+ T=-T$Tloc
+fi
+
+# Load nroff-style character definitions too.
+opts="-mtty-char$opts"
+
+# Set up the 'GROFF_BIN_PATH' variable to be exported in the current
+# 'GROFF_RUNTIME' environment.
+@GROFF_BIN_PATH_SETUP@
+export GROFF_BIN_PATH
+
+# Let our test harness redirect us. See LC_ALL comment above.
+groff=${GROFF_TEST_GROFF-groff}
+
+# Note 1: It would be nice to apply the DRY ("Don't Repeat Yourself")
+# principle here and store the entire command string to be executed into
+# a variable, and then either display it or execute it. For example:
+#
+# cmd="PATH=... groff ... $@"
+# ...
+# printf "%s\n" "$cmd"
+# ...
+# eval $cmd
+#
+# Unfortunately, the shell is a nightmarish hellscape of quoting issues.
+# Naïve attempts to solve the problem fail when arguments to nroff
+# contain embedded whitespace or shell metacharacters. The solution
+# below works with those, but there is insufficient quoting in -V (dry
+# run) mode, such that you can't copy-and-paste the output of 'nroff -V'
+# if you pass it a filename like foo"bar (with the embedded quotation
+# mark) and expect it to run without further quoting.
+#
+# If POSIX adopts Bash's ${var@Q} or an equivalent, this issue can be
+# revisited.
+#
+# Note 2: The construction '${1+"@$"}' preserves the absence of
+# arguments in old shells; see "Shell Substitutions" in the GNU Autoconf
+# manual. We don't want 'nroff' to become 'groff ... ""' if $# equals
+# zero.
+if [ -n "$dry_run" ]
+then
+ echo PATH="$GROFF_RUNTIME$PATH" $groff $T $opts ${1+"$@"}
+else
+ PATH="$GROFF_RUNTIME$PATH" $groff $T $opts ${1+"$@"}
+fi
+
+# Local Variables:
+# fill-column: 72
+# End:
+# vim: set autoindent expandtab shiftwidth=2 softtabstop=2 textwidth=72:
diff --git a/src/roff/nroff/tests/verbose_option_works.sh b/src/roff/nroff/tests/verbose_option_works.sh
new file mode 100755
index 0000000..85ca8f0
--- /dev/null
+++ b/src/roff/nroff/tests/verbose_option_works.sh
@@ -0,0 +1,68 @@
+#!/bin/sh
+#
+# Copyright (C) 2020 Free Software Foundation, Inc.
+#
+# This file is part of groff.
+#
+# groff is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+# Ensure a predictable character encoding.
+export LC_ALL=C
+export LESSCHARSET=
+export GROFF_TYPESETTER=
+
+set -e
+
+export GROFF_TEST_GROFF=${abs_top_builddir:-.}/test-groff
+
+# The $PATH used by an installed nroff at runtime does not match what
+# we're trying to test, which should be using the groff and runtime
+# support from the build tree. Therefore the $PATH that nroff -V
+# reports will _always_ be wrong for test purposes. Skip over it.
+#
+# If the build environment has a directory in the $PATH matching
+# "test-groff " (with the trailing space), failure may result if sed
+# doesn't match greedily. POSIX says it should.
+sedexpr='s/^PATH=.*test-groff /test-groff /'
+PATH=${abs_top_builddir:-.}:$PATH
+
+nroff_ver=$(nroff -v | awk 'NR == 1 {print $NF}')
+groff_ver=$(nroff -v | awk 'NR == 2 {print $NF}')
+
+echo nroff: $nroff_ver >&2
+echo groff: $groff_ver >&2
+test "$nroff_ver" = "$groff_ver"
+
+echo "testing 'nroff -V'" >&2
+nroff -V | sed "$sedexpr" | grep -x "test-groff -Tascii -mtty-char"
+
+echo "testing 'nroff -V 1'" >&2
+nroff -V 1 | sed "$sedexpr" | grep -x "test-groff -Tascii -mtty-char 1"
+
+echo "testing 'nroff -V \"1a 1b\"'" >&2
+nroff -V \"1a 1b\" | sed "$sedexpr" \
+ | grep -x "test-groff -Tascii -mtty-char \"1a 1b\""
+
+echo "testing 'nroff -V \"1a 1b\" 2'" >&2
+nroff -V \"1a 1b\" 2 | sed "$sedexpr" \
+ | grep -x "test-groff -Tascii -mtty-char \"1a 1b\" 2"
+
+echo "testing 'nroff -V 1a\\\"1b 2'" >&2
+nroff -V 1a\"1b 2 | sed "$sedexpr" \
+ | grep -x "test-groff -Tascii -mtty-char 1a\"1b 2"
+
+echo "testing 'nroff -V -d FOO=BAR 1'" >&2
+nroff -V -d FOO=BAR 1 | sed "$sedexpr" \
+ | grep -x "test-groff -Tascii -mtty-char -d FOO=BAR 1"