Re: Mandoc Not Parsing Sy Macro (In some cases)

[Ingo Schwarze <schwarze@usta.de>]

Hi,

Ingo Schwarze wrote on Mon, Jan 09, 2017 at 02:40:25PM +0100:

> I think i will also commit a clarification to the mdoc(7) manual

Done:


Log Message:
-----------
Clarify how tabs after .It work  
because this is a really nasty trap for the unwary.

Triggered by a question from Abhinav Upadhyay <er dot abhinav dot 
upadhyay at gmail dot com> (NetBSD) on discuss@.

Modified Files:
--------------
    mdocml:
        mdoc.7

Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mdoc.7,v
retrieving revision 1.259
retrieving revision 1.260
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.259 -r1.260
--- mdoc.7
+++ mdoc.7
@@ -1,7 +1,7 @@
 .\"	$Id$
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -1831,14 +1831,25 @@ The
 list is the most complicated.
 Its syntax is as follows:
 .Pp
-.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
+.D1 Pf \. Sx \&It Ar cell Op <TAB> 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-de
 line.
 For example,
 .Pp
-.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
+.Dl .It \(dqcol1 ,\& <TAB> 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 .
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv