Hi Wookey,
At 2023-10-15T16:08:32+0100, Wookey wrote:
> OK. So I read all that, and learned a whole load of stuff I was quite
> happy not knowing about.
>
> However despite reading it all, and especially this bit:
> > Whenever I've maintained man pages in roff I tend to be precise in
> > the usage of - and \-, but TBH this has seemed like a lost battle,
>
> I was left not actually know what - and \- represent, nor which one I
> _should_ be using in my man pages. And that seems to be the one thing
> we should be telling the 'average maintainer'.
>
> I think you can consider me representative of the typical maintainer
> who's intereaction with *roff languages almost entirely takes the
> form: 'Oh bloody hell I really ought to write a man page for this
> because upstream is too youthful to have done so - now how the hell
> does roff/nroff/groff work again' (no I'm not sure which it is I'm
> actually using, nor how any of this machinery really works, nor where
> to look for good practice, so I mostly copy existing stuff and DDG for
> answers, which is less than ideal when it comes to details like this).
>
> So this message is mostly a reminder that most people have not been
> following along at all, so just referring people to bugs like this,
> which discuss the issue in some detail, is not sufficient for
> maintainers to stop doign unhelpful things.
>
> (Yes I realise I could look it up, but I get the impression that
> everyone involved in this discusssion assumes people know what '-' and
> '\-' are so if they are just told to 'use the right one' will do so,
> and I thought it worth pointing out that that's not correct). Info for
> your average maintainer needs to go one step back and say "use stringA
> in this circumstance and stringB in this circumstance. <explanation of
> what they represent>. The reason why it matters is: stuff about hyphen
> and minus being different and minus being used in commands and
> cut+pasting being important"
Yes, I appreciate your popping of the context stack.
Andreas and Russ provided good, quick answers. One can reasonably
wonder where to find the same answer in groff's documentation.
Subsection "Fundamental character set" of the groff_char(7) man page
covers the matter, but like the bug report we've Cced, it goes into
great detail.
Subsection "Portability" of groff_man_style(7) (or groff_man(7) in groff
1.22.4) covers the subject in a more practical, how-to manner.
[UTF-8 follows.]
groff_man_style(7):
... Some escape sequences
are however required for correct typesetting even in man pages and
usually do not cause portability problems.
Several of these render glyphs corresponding to punctuation code
points in the Unicode basic Latin range (U+0000–U+007F) that are
handled specially in roff input; the escape sequences below must be
used to render them correctly and portably when documenting
material that uses them syntactically—namely, any of the set ' - \
^ ` ~ (apostrophe, dash or minus, backslash, caret, grave accent,
tilde).
...
\- Minus sign or basic Latin hyphen‐minus. \- produces the
Unix command‐line option dash in the output. “-” is a
hyphen in the roff language; some output devices replace it
with U+2010 (hyphen) or similar.
\(aq Basic Latin neutral apostrophe. Some output devices format
“'” as a right single quotation mark.
...
\(ga Basic Latin grave accent. Some output devices format “`” as
a left single quotation mark.
\(ha Basic Latin circumflex accent (“hat”). Some output devices
format “^” as U+02C6 (modifier letter circumflex accent) or
similar.
\(rs Reverse solidus (backslash). The backslash is the default
escape character in the roff language, so it does not
represent itself in output. Also see \e above.
\(ti Basic Latin tilde. Some output devices format “~” as U+02DC
(small tilde) or similar.
> Hope that's helpful.
I hope this message goes some way toward relieving your frustration.
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature