From 9fe450461bc85144434bb25f42f7c9f6bafa8da4 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Thu, 15 Mar 2018 18:10:31 +0000 Subject: Soften the language discouraging special character escape sequences. After i improved their ASCII renderings in groff and mandoc some time ago, mathematical symbols can now be used in specialised mathematical manual pages like libm and some X libraries. Tweaks and OK jmc@. --- mandoc_char.7 | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/mandoc_char.7 b/mandoc_char.7 index a372b3e9..93893435 100644 --- a/mandoc_char.7 +++ b/mandoc_char.7 @@ -1,4 +1,4 @@ -.\" $Id: mandoc_char.7,v 1.67 2017/06/14 20:57:07 schwarze Exp $ +.\" $Id: mandoc_char.7,v 1.68 2018/03/15 18:10:31 schwarze Exp $ .\" .\" Copyright (c) 2003 Jason McIntyre .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons @@ -16,7 +16,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 14 2017 $ +.Dd $Mdocdate: March 15 2018 $ .Dt MANDOC_CHAR 7 .Os .Sh NAME @@ -35,13 +35,27 @@ documents. .Pp The rendering depends on the .Xr mandoc 1 -output mode; in ASCII output, most characters are completely -unintelligible. -For that reason, using any of the special characters documented here, -except those discussed in the +output mode; it can be inspected by calling +.Xr man 1 +on the +.Nm +manual page with different +.Fl T +arguments. +In ASCII output, the rendering of some characters may be hard +to interpret for the reader. +Many are rendered as descriptive strings like +.Qq , +.Qq , +or +.Qq , +which may look ugly, and many are replaced by similar ASCII characters. +In particular, accented characters are usually shown without the accent. +For that reason, try to avoid using any of the special characters +documented here except those discussed in the .Sx DESCRIPTION , -is strongly discouraged; they are supported merely for backwards -compatibility with existing documents. +unless they are essential for explaining the subject matter at hand, +for example when documenting complicated mathematical functions. .Pp In particular, in English manual pages, do not use special-character escape sequences to represent national language characters in author -- cgit v1.2.3-56-ge451