* Re: Mandoc Not Parsing Sy Macro (In some cases)
2017-01-09 13:40 ` Ingo Schwarze
@ 2017-01-09 14:18 ` Ingo Schwarze
2017-01-10 14:50 ` Abhinav Upadhyay
1 sibling, 0 replies; 4+ messages in thread
From: Ingo Schwarze @ 2017-01-09 14:18 UTC (permalink / raw)
To: discuss; +Cc: Thomas Klausner, Abhinav Upadhyay
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Mandoc Not Parsing Sy Macro (In some cases)
2017-01-09 13:40 ` Ingo Schwarze
2017-01-09 14:18 ` Ingo Schwarze
@ 2017-01-10 14:50 ` Abhinav Upadhyay
1 sibling, 0 replies; 4+ messages in thread
From: Abhinav Upadhyay @ 2017-01-10 14:50 UTC (permalink / raw)
To: Ingo Schwarze; +Cc: discuss, Thomas Klausner
On Mon, Jan 9, 2017 at 7:10 PM, Ingo Schwarze <schwarze@usta.de> wrote:
> Hi Abhinav,
>
> Abhinav Upadhyay wrote on Mon, Jan 09, 2017 at 04:06:43PM +0530:
>
>> Whereas in the places where it was being rendered correctly, we were
>> using Ta, like this:
>>
>> It Sy Name Ta Sy Constant Ta Sy Next level names Ta Sy Description
>
> Yes, that is exactly why you should preferably use Ta and not
> literal tabs. It's much easier to use correctly, and the mdoc(7)
> source code is easier to read.
>
> If you insist on using literal tabs, you need a blank character
> between the tab and the following macro.
>
> Yes, that is weird: a blank is syntactically significant after
> a tab. But that's just how roff traditionally behaves.
Ah, I wasn't aware of it, and it is also quite difficult to catch :)
>
>> I think this issue was not present in the previous version of mandoc,
>
> Yes, 1.13.3 had a bug processing the first word after a tab
> incorrectly. It was fixed on October 17, 2015.
>
> See
>
> http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/regress/usr.bin/mandoc/mdoc/Bl/column.in
>
> in particular the commit message of revision 1.8, the test code
> added by that commit, and the correct output in
>
> http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/regress/usr.bin/mandoc/mdoc/Bl/column.out_ascii?rev=HEAD&content-type=text/x-cvsweb-markup
>
>> It has been noticed only with the latest release.
>
> The proper response is to fix your manual pages. You should do that
> because as they are, they are not portable and won't work with groff.
> Either insert the missing blanks or - much better for clarity
> and robustness - use Ta rather than bare tabs.
Yes, we have already changed to using Ta.
> I think i will also commit a clarification to the mdoc(7) manual
> because this is indeed a nasty trap for the unwary.
Thanks :)
-
Abhinav
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 4+ messages in thread