Date: Fri, 31 Mar 2000 15:08:13 +1100 (KOST)
From: John Hawkinson <jhawk@mit.edu>
Reply-To: jhawk@mit.edu
To: gnats-bugs@gnats.netbsd.org
Subject: mdoc's .Li is indistinguishable in nroff


>Number:         9745
>Category:       misc
>Synopsis:       mdoc's .Li is indistinguishable in nroff
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Mar 31 16:30:03 PST 2000
>Closed-Date:    
>Last-Modified:  
>Originator:     John Hawkinson
>Release:        NetBSD 1.4.2
>Organization:
	MIT
>Environment:

	
System: NetBSD zorkmid.mit.edu 1.4.2 NetBSD 1.4.2 (ZORKMID) #10: Mon Mar 27 12:33:31 CST 2000 jhawk@zorkmid.mit.edu:/usr/src/sys/arch/i386/compile/ZORKMID i386




>Description:
	mandoc's .Li, which is designed for literal text, is
indistinguishable from running text when formatted by nroff.
Formatting via "groff -Tps" causes such to be displayed in a monospaced
font, which is sufficient to distinguish it from running text.


	To be very clear, "literal" does not mean "indistinguishable",
but rather is to reflect a piece of literal information that a user
should type as-is. mdoc.samples(7) makes this clear:


     The `.Li' literal macro may be used for special characters, variable con-
     stants, anything which should be displayed as it would be typed.


Presumably because of this fault, a number of man pages seem
to use .Li incorrectly, in two chief ways:


	a)	Putting .Li items in lists (eg. .It Li) . This is not
	strictly incorrect, but the intent of the lists should not be
	to indent their text simply so they can be recognized as literal.

	
	b) 	Placing quotation marks around the text in Li. Again,
	it's very tempting to do this because it causes the text to
	render usefully in nroff, but it is Li's job to do things
	like that, not the users of Li.


And of course, some manpages combine this. Like find(1):


.It Li "find  /  \e!  -name  \*q*.c\*q  -print"


Or using .Dq (Double quote) for a combination of a) and b).




Alternatively, if my interpretation is incorrect and .Li should be
used in combination with .It or .Dq, then mdoc.samples(7) should
be updated to state this explicitly, and all contrary examples
should be removed.




>How-To-Repeat:
	Try to read a manpage that uses this in the midst of
running text (admittedly they are few and far between, probably
because their authors have observed that they do not format
properly).
>Fix:
	I really don't know. Certainly the "Alternatively" solution
would be easiest, but I don't think that's right. Presumably
boldface (i.e. the standout used by .Fl and .Cm) might be appropriate,
however double-quoting would also do...


	As for the actual implementation of the fix, I'm afraid my
'roff is too weak for that.
>Release-Note:
>Audit-Trail:
>Unformatted: