Italics and colour in manual pages on a nosh user-space virtual terminal

nosh pages:

Most typefaces have at least three fonts available: roman, bold, and italic. Normal body copy is printed in the roman font. You can change temporarily to a bold or italic font for emphasis.

— Dale Dougherty & Tim O'Reilly. UNIX text processing. Sams. 1986

Unix document processing tools have supported italicization since the 1970s. ECMA-48 defined a standard Set Graphic Rendition mechanism for specifying boldface, faint, underlined, and italicized text in its first edition, published in 1976.

It is now four decades later. The wide array of disparate terminal types has narrowed, to the extent that people now actually get away with hardwiring ISO colour and attribute control sequences into their programs. (systemd does this, for example. So too does GNU grep.) Support for at least 8 colours, and usually 16 colours, is now the rule rather than the exception when it comes to terminal hardwares that people use. GNU grotty (a part of the manual system that converts the page to display to a terminal character stream with control sequences) actually defaults to using ECMA-48 control sequences for boldface, underline, and italics; and ISO 8613-6:1994 control sequences for colour. One would think that making Unix or Linux manual pages display with italicized and coloured text would be straightforward and commonplace nowadays.

One would be wrong.

Four decades' worth of Unix and Linux people have decided that it is Just Not Right for manual pages to be displayed with italic text where the manual page uses (say) the .I roff macro — that specifies italic text. They have, between them, put in place quite a range of obstacles that must be overcome in order to see something, on today's machines, that was nominally available back in the late 1970s.

User-space virtual terminals provided by the nosh toolset support a full set of ECMA-48 text attributes and ISO 8613-6 24-bit RGB colour. Here are the contortions that will present manual pages in all of their coloured and italicized glory when viewing them on a nosh user-space virtual terminal.

What needs to happen, internally

The manual system is a suite of coöperating programs, all connected together by the man command, that do various pieces of processing in order to end up with a manual page displayed on one's terminal. The last two commands in the chain are the ones that are relevant to colour and italicization.

You do not need to do anything special to the console-fb-realizer display realizer program in the nosh toolset to make it handle italicization and colour. That is the default. You can explicitly hand proper weighted and italicized fonts to it, for best results, and it will just render them. But (as its manual page explains) it will resort to doubling-up and obliquing as fallback measures if it isn't supplied with such fonts.

The console-terminal-emulator terminal emulator program in the nosh toolset supports the ECMA-48 and ISO 8613-6 control sequences right out of the box, no configuration required.

FreeBSD man command

In 2011, FreeBSD's man command gained its MANCOLOR mechanism. Unless the MANCOLOR environment variable is set and non-blank, man arranges for grotty to be invoked with its -c option. The man command also attempts to deduce that it needs to give the -R option to less if that is the pager that is being invoked.

So setting the MANCOLOUR environment variable enables colours with little fanfare. It does not enable italicization, though. FreeBSD's man command does not have a similar flag to tell it to pass the -i command-line option to grotty.

To achieve this, the following patch implements similar logic for a MANITALIC environment variable.

--- /usr/src/usr.bin/man/	2016-01-01 18:53:41.169871849 +0000
+++ /usr/src/usr.bin/man/	2016-05-16 14:26:03.474372847 +0100
@@ -356,8 +356,10 @@
-	if [ -z "$MANCOLOR" ]; then
+	if [ -z "$MANCOLOR" ] && [ -z "$MANITALIC" ]; then
 		NROFF="$NROFF -P-c"
+	elif [ -n "$MANITALIC" ]; then
+		NROFF="$NROFF -P-i"
 	if [ -n "${use_width}" ]; then

Debian man command

The obstacles put in the way on Debian operating systems are subtler, and undocumented.

In 2002, Colin J. Watson of Debian added an undocumented flag to groff. This undocumented flag is the GROFF_SGR environment variable. Unless it is set, roff macro code in the /etc/groff/man.local file forcibly and quietly emits the tty: sgr 0 control sequence into the input that is given to grotty.

Setting this flag is an undocumented override that restores the behaviour of grotty that people expect from its documentation. Debian's man command doesn't itself actually pass the -c command line flag, emit the control sequence, or set the GROFF_NO_SGR environment variable, and a user who didn't know to dig into a decade-and-a-half old bug report against a long since superseded version of Debian Linux could be excused being mystified by how on Earth the programs were not behaving as documented.

It doesn't enable the non-default behaviour of grotty that employs real italicization, though. To do that, it is necessary to pass the -i option to grotty. This is done by passing the -P-i option to groff. But the Debian man command is not a shell script that can be easily patched in situ, but a compiled program. So one has to employ the MANROFFOPT environment variable, setting it to "-P-i".

© Copyright 2016 Jonathan de Boyne Pollard. "Moral" rights asserted.
Permission is hereby granted to copy and to distribute this WWW page in its original, unmodified form as long as its last modification datestamp information is preserved.