bin/50569: mandoc man page oddity

[kre%munnari.OZ.AU@localhost]

>Number:         50569
>Category:       bin
>Synopsis:       mandoc man page oddity
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Dec 17 13:40:00 +0000 2015
>Originator:     Robert Elz
>Release:        NetBSD 7.99.21 (I think anything recent with mandoc.1)
>Organization:
	Prince of Songkla University
>Environment:
System: NetBSD andromeda.noi.kre.to 7.99.21 NetBSD 7.99.21 (VBOX64-1.1-20150829) #3: Sun Aug 30 07:16:17 ICT 2015 kre%andromeda.noi.kre.to@localhost:/home/kre/src/current-kernel/usr/src/sys/arch/amd64/compile/VBOX64 amd64
Architecture: x86_64
Machine: amd64
>Description:

   The man page for mandoc (mandoc.1) says (right at the end, under CAVEATS)

	The `'' control character is an alias for the standard macro control
	character and does not emit a line-break as stipulated in GNU troff.

   I'll repeat that annotated...

	The `'' control character

   That is, when ' (single quote, apostrophe, 0x27 ascii) is used
   as a macro call character (column 1)

	is an alias for the standard macro control character

   That is, . (dot, point, period, full-stop, 0x2E ascii)

   So far that would be fine, but ...

	and does not emit a line-break as stipulated in GNU troff.

   is exactly backwards.  I can't believe that even GNU troff (groff)
   scrambled troff syntax that much ... but . as an intro to some macro
   requests in *roff causes a line break, using ' supresses that effect,
   which is exactly the opposite of what this man page suggests.

   For users of mandoc, it should make no difference (which is why I
   believe this s a doc bug, not a program bug) as macro calls themselves
   don't cause line breaks, so whether one uses . or ' to invoke them
   makes no difference at all (the macro may cause a line break, or not,
   regardless of how it is called).   Since madoc doesn't actually
   implement macros as such (I believe) it is perfectly OK for . and '
   to be treated the same (not that anyone is likely to ever actually use ')
   but the man page really ought not confuse people about what *roff
   syntax is.

>How-To-Repeat:
	RTFM

>Fix:
	s/emit a/supress the/

	(probably).  Adding a caveat to the caveat about how it really
	doesn't matter wouldn't hurt...   Or just delete the whole
	sentence.