discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: discuss@mdocml.bsd.lv
Cc: Thomas Klausner <wiz@netbsd.org>,
	Abhinav Upadhyay <er.abhinav.upadhyay@gmail.com>
Subject: Re: Mandoc Not Parsing Sy Macro (In some cases)
Date: Mon, 9 Jan 2017 14:40:25 +0100	[thread overview]
Message-ID: <20170109134025.GD94305@athene.usta.de> (raw)
In-Reply-To: <CAHwRYJkz-iANNhLsj1C+UtaKf8Vt+-vmmYbZDmjxGcmJxme4Uw@mail.gmail.com>

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

  reply	other threads:[~2017-01-09 13:40 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-01-09 10:36 Abhinav Upadhyay
2017-01-09 13:40 ` Ingo Schwarze [this message]
2017-01-09 14:18   ` Ingo Schwarze
2017-01-10 14:50   ` Abhinav Upadhyay

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170109134025.GD94305@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mdocml.bsd.lv \
    --cc=er.abhinav.upadhyay@gmail.com \
    --cc=wiz@netbsd.org \
    --subject='Re: Mandoc Not Parsing Sy Macro (In some cases)' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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