Update of bug #67881 (group groff):
Status: Fixed => In Progress
Open/Closed: Closed => Open
Planned Release: 1.24.0 => None
_______________________________________________________
Follow-up Comment #5:
Hi Branden,
[comment #3 comment #3:]
> I'm re-purposing this ticket to the objective of helping _mdoc_(7) package
> users to remember to spell an intended hyphen-minus as `\-`.
>
> The package can't handle them all for the writer, and it seemed a little odd
> to direct _mdoc_ users to _groff_man_style_(7) for advice. Surely, few such
> users would ever read that document, assuming it to be a complete waste of
> time to glean any knowledge from resources prepared for authors using the
> purportedly clumsy and inferior _man_(7) package.
Actually, i agree with the goal of pointing to the relevant information from
the groff_mdoc(7) manual.
That doesn't necessarily mean that the information about common character
escapes needs to be duplicated inside the mdoc documentation - there is
certainly more than one way to do this correctly, and duplication is one of
the ways.
For example, the mdoc(7) manual from the mandoc package says this:
Fl [word ...]
Command-line flag or option. Used when listing arguments to
command-line utilities. For each argument, prints an ASCII hyphen-
minus character ‘-’, immediately followed by the argument. If
no
arguments are provided, a hyphen-minus is printed followed by a
space. If the argument is a macro, a hyphen-minus is prefixed to
the subsequent macro output.
Examples:
.Nm du Op Fl H | L | P
.Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
.Nm route Cm add Fl inet Ar destination gateway
.Nm locate.updatedb Op Fl \-fcodes Ns = Ns Ar dbfile
.Nm aucat Fl o Fl
.Nm kill Fl Ar signal_number
For GNU-style long options, escaping the additional hyphen-minus is
not strictly required, but may be safer with future versions of GNU
troff; see mandoc_char(7) for details.
And then in mandoc_char(7), the very first subsection is entitled "Dashes and
hyphens" and says, among other things,
In roff(7) documents, the minus sign is normally written as ‘\-’.
In
manual pages, some style guides recommend to also use ‘\-’ if an
ASCII
0x2d “hyphen-minus” output glyph that can be copied and pasted is
desired
in output modes supporting it, for example in -T utf8 and -T html. But
currently, no practically relevant manual page formatter requires that
subtlety, so in manual pages, it is sufficient to write plain ‘-’ to
represent hyphen, minus, and hyphen-minus.
I guess that's now outdated and i should change it to recommend \- and nothing
else for hyphen-minus in manuals, because that requirment is not so "future"
in groff any more (though it might still depend on the OS, e.g. Debian
patching it back?). Right?
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?67881>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
