discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Mandoc Not Parsing Sy Macro (In some cases)
@ 2017-01-09 10:36 Abhinav Upadhyay
  2017-01-09 13:40 ` Ingo Schwarze
  0 siblings, 1 reply; 4+ messages in thread
From: Abhinav Upadhyay @ 2017-01-09 10:36 UTC (permalink / raw)
  To: discuss; +Cc: Thomas Klausner

Hi Ingo,

In NetBSD's sysctl(7) man page, we noticed an issue where in some
tables the Sy macro was not being parsed and being rendered literally
as "Sy". While in other places it was being parsed correctly. On
looking closely, we realized that in the cases where Sy was not being
parsed, we were using <TAB> instead of Ta macro, like this:

.It Sy Second level name    Sy Type Sy Changeable

Which is being rendered as:
Second level name  Sy Type    Sy Changeable

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

I think this issue was not present in the previous version of mandoc,
It has been noticed only with the latest release.

-
Abhinav
--
 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 10:36 Mandoc Not Parsing Sy Macro (In some cases) Abhinav Upadhyay
@ 2017-01-09 13:40 ` Ingo Schwarze
  2017-01-09 14:18   ` Ingo Schwarze
  2017-01-10 14:50   ` Abhinav Upadhyay
  0 siblings, 2 replies; 4+ messages in thread
From: Ingo Schwarze @ 2017-01-09 13:40 UTC (permalink / raw)
  To: discuss; +Cc: Thomas Klausner, Abhinav Upadhyay

Hi Abhinav,

Abhinav Upadhyay wrote on Mon, Jan 09, 2017 at 04:06:43PM +0530:

> In NetBSD's sysctl(7) man page, we noticed an issue where in some
> tables the Sy macro was not being parsed and being rendered literally
> as "Sy". While in other places it was being parsed correctly. On
> looking closely, we realized that in the cases where Sy was not being
> parsed, we were using <TAB> instead of Ta macro, like this:
> 
> .It Sy Second level name    Sy Type Sy Changeable
> 
> Which is being rendered as:
> Second level name  Sy Type    Sy Changeable

That is correct rendering.

Groff renders it the same way.

> 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.

> 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.

I think i will also commit a clarification to the mdoc(7) manual
because this is indeed a nasty trap for the unwary.

Yours,
  Ingo
--
 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: 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

end of thread, other threads:[~2017-01-10 14:50 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-01-09 10:36 Mandoc Not Parsing Sy Macro (In some cases) Abhinav Upadhyay
2017-01-09 13:40 ` Ingo Schwarze
2017-01-09 14:18   ` Ingo Schwarze
2017-01-10 14:50   ` Abhinav Upadhyay

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).