From 57d2969f5561fe3980763539d31856762bb3673e Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Mon, 9 Jan 2017 14:10:53 +0000 Subject: Clarify how tabs after .It work because this is a really nasty trap for the unwary. Triggered by a question from Abhinav Upadhyay (NetBSD) on discuss@. --- mdoc.7 | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) (limited to 'mdoc.7') diff --git a/mdoc.7 b/mdoc.7 index 38e87b60..e28db482 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -1,7 +1,7 @@ -.\" $Id: mdoc.7,v 1.259 2016/12/28 17:34:18 schwarze Exp $ +.\" $Id: mdoc.7,v 1.260 2017/01/09 14:10:53 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons -.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze +.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,7 +15,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: December 28 2016 $ +.Dd $Mdocdate: January 9 2017 $ .Dt MDOC 7 .Os .Sh NAME @@ -1831,14 +1831,25 @@ The list is the most complicated. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&It Ar cell Op Ar cell ... .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... +.D1 Pf \. Sx \&It Ar cell Op Ar cell ... .Pp The arguments consist of one or more lines of text and macros representing a complete table line. -Cells within the line are delimited by tabs or by the special +Cells within the line are delimited by the special .Sx \&Ta -block macro. +block macro or by literal tab characters. +.Pp +Using literal tabs is strongly discouraged because they are very +hard to use correctly and +.Nm +code using them is very hard to read. +In particular, a blank character is syntactically significant +before and after the literal tab character. +If a word precedes or follows the tab without an intervening blank, +that word is never interpreted as a macro call, but always output +literally. +.Pp The tab cell delimiter may only be used within the .Sx \&It line itself; on following lines, only the @@ -1853,9 +1864,10 @@ Note that quoted strings may span tab-delimited cells on an line. For example, .Pp -.Dl .It \(dqcol1 ; col2 ;\(dq \&; +.Dl .It \(dqcol1 ,\& col2 ,\(dq \&; .Pp -will preserve the semicolon whitespace except for the last. +will preserve the whitespace before both commas, +but not the whitespace before the semicolon. .Pp See also .Sx \&Bl . -- cgit v1.2.3-56-ge451