LWN: Comments on "Hyphens, minus, and dashes in Debian man pages"

Hyphens, minus, and dashes in Debian man pages

lmb — Tue, 27 Feb 2024 14:30:29 +0000

I've finally hit this on a man page, was extremely confused, and eventually found this article as an explanation for what was happening to me.

As a user, I'm ... not entirely in love with this change. Yes, it is technically correct, but it has *horrible* UX and breaks things at times when you're already had to resort to reading documentation, not normally times when you want something else to be befuddling. My primary contact with roff (and I suspect for 99% of all users?) since the post-90s are man pages, and for that use case, this change is questionable.

Yes, in theory, all broken man pages out there should be fixed, that's where the origin of the brokenness is, and I appreciate the thoughtful discussion and decision and commitment to proper layout and typesetting.

In practice, I roll my eyes at technical correctness and alias man to `man -E ascii`. Sorry.

Hyphens, minus, and dashes in Debian man pages

mirabilos — Sun, 07 Jan 2024 23:21:46 +0000

My HTML-format manpages (like http://www.mirbsd.org/man1/mksh to complement the prior example) are vastly more read than the PDF-format ones.

(I generate them from catman pages though, which in turn are produced with nroff (not gnroff) and the BSD mdoc, man.old, me, ms, etc. macropackages.)

Hyphens, minus, and dashes in Debian man pages

mirabilos — Sun, 07 Jan 2024 23:20:14 +0000

Yes, and I had to apply extra workarounds around GNU groff “features” to get not-broken URLs in them.

http://www.mirbsd.org/MirOS/dist/mir/mksh/mksh.pdf at least is an okay result.

It is typeset with the BSD mdoc macropackage, not the GNU one, thankfully.

Hyphens, minus, and dashes in Debian man pages

mirabilos — Sun, 07 Jan 2024 23:18:04 +0000

2010 (and 2011, which is used in cases like “foo-, -bar- and -baz-type”) are much narrower than 002D even in Fixed [Misc] for example.

Hyphens, minus, and dashes in Debian man pages

tao — Mon, 04 Dec 2023 21:23:39 +0000

You've got to make yourself some Nordic friends. Most of their keyboards are likely to have a <> key.

Hyphens, minus, and dashes in Debian man pages

gioele — Sun, 03 Dec 2023 11:30:51 +0000

> For example the AZERTY keyboard is very common in Europe ...

Well, if Europe is France, then yes. :) The most common visual layout in Europe is QWERTY, followed by QWERTZ (German-speaking countries and Balkans). https://commons.wikimedia.org/wiki/File:Latin_keyboard_la...

> That's probably why I find keyboards so confusing - the dominant culture is US, within Europe it's Germany, and nobody thinks to tell you how to remap a UK keyboard

That is indeed a real issue.

Keyboards have different levels of abstraction (physical layout, visual layout, functional layout) and only the first levels are really standardized (an many different standards exist). And even the standards are often not followed. So it is hard to write documentation in a way that applies to a non US-centric audience.

I have in a radius of 20 meters from my chair at least 10 different keyboards, all of which are "almost" standard ISO, but each of them has a peculiarity (different physical shape, non-standard legends, extra functionalities...) that makes them non-standard.

Xorg/xkb tries to document all this variability using a declarative language (see xkbcomp/xkbprint) but no keyboard manufacturer I know of provides xkb data for their keyboard. (And in the end everything is an evdev keyboard these days, so...)

Hyphens, minus, and dashes in Debian man pages

Wol — Sun, 03 Dec 2023 10:51:06 +0000

The problem is everyone thinks their layout is the standard layout :-)

For example the AZERTY keyboard is very common in Europe ...

That's probably why I find keyboards so confusing - the dominant culture is US, within Europe it's Germany, and nobody thinks to tell you how to remap a UK keyboard - if all the descriptions are in terms of the developer's local keymaps, we don't seem to have any UK developers ... :-)

Cheers,
Wol

Hyphens, minus, and dashes in Debian man pages

gioele — Sun, 03 Dec 2023 08:19:41 +0000

> My keyboard (which looks like the standard UK layout) has that key, but it's "\|". To the best of my knowledge I've never seen a "<>" key ...

So you have seen the key, but you haven't seen it labeled "<>". :)

The technical name for that physical key, regardless of its legend (= printed label) is "1st main key of the B (= 2nd from the bottom) row". Common legends for it are "<>", "\|", "~`", "][", "«»", "^*".

Hyphens, minus, and dashes in Debian man pages

Wol — Sun, 03 Dec 2023 00:08:27 +0000

My keyboard (which looks like the standard UK layout) has that key, but it's "\|". To the best of my knowledge I've never seen a "<>" key ...

Cheers,
Wol

Hyphens, minus, and dashes in Debian man pages

johill — Sat, 02 Dec 2023 20:40:15 +0000

It's really common (likely standard) for German layout keyboards ... I tend to switch mine to US in software for programming, but have multiple ISO/German layout keyboards, including most recently a split one (Keychron Q11).

Hyphens, minus, and dashes in Debian man pages

ssokolow — Sat, 02 Dec 2023 20:13:56 +0000

Ugh. Which characters have special meaning. Don't post while sleep deprived, kids!

Hyphens, minus, and dashes in Debian man pages

halla — Sat, 02 Dec 2023 19:35:36 +0000

That "standard" ISO layout isn't used by any brand of keyboard, except Apple, in the Netherlands, where I live. I've never met anyone who got the "standard" ISO keyboard layout when buying a macbook in the Netherlands, though I'm sure they exist. I just have never met them.

Hyphens, minus, and dashes in Debian man pages

gioele — Sat, 02 Dec 2023 19:00:00 +0000

> I've never had, or even seen, a keyboard with a key between left shift and Z...

The standard ISO layout (used everywhere except in USA and Japan) has a key between left shift and Z.

https://switchandclick.com/wp-content/uploads/2021/02/phy...

Hyphens, minus, and dashes in Debian man pages

halla — Sat, 02 Dec 2023 18:48:40 +0000

I've never had, or even seen, a keyboard with a key between left shift and Z...

Hyphens, minus, and dashes in Debian man pages

jem — Sat, 02 Dec 2023 18:04:22 +0000

The "<> key" refers to the key between left shift key and the Z key (Y on a German keyboard and W on a French keyboard). Not all keyboards have this key, but if it is present it is usually labelled "<" (unshifted) and ">" (shifted).

If you don't have this key, you can always choose some other key from the 19 alternatives on the list.

Hyphens, minus, and dashes in Debian man pages

Wol — Sat, 02 Dec 2023 14:45:40 +0000

Thanks. So I thought I'd just take a look ...

Key to choose the 2nd level - "<>" - what on earth is that :-)

The keyboard I'm typing on has ",<" and ".>" but no "<>" key :-)

Mind you, it did tell me how to make num lock default to on - it's been a real pain that num lock seems to change now and again for no apparent reason ...

Cheers,
Wol

Hyphens, minus, and dashes in Debian man pages

ssokolow — Sat, 02 Dec 2023 11:56:58 +0000

You'd immediately open up a ton of shell injection exploits, since the assumption of which functions have special meaning is baked into a million different functions like Python's shlex.quote. PowerShell can get away with supporting that because it's a new shell with a new syntax.

Hyphens, minus, and dashes in Debian man pages

ssokolow — Sat, 02 Dec 2023 09:33:05 +0000

System Settings → Input Devices → Keyboard → Advanced → Position of Compose key

Hyphens, minus, and dashes in Debian man pages

mathstuf — Thu, 16 Nov 2023 03:33:34 +0000

That GNOME Settings probably just does something like:

/usr/bin/setxkbmap -option lv3:ralt_switch_multikey

Hyphens, minus, and dashes in Debian man pages

dwmw2 — Sat, 11 Nov 2023 11:21:49 +0000

Yes, obviously the physical layout is the US one.

But in software it is using the standard British layout, in precisely the context I first used that phrase in this thread. Which was nothing to do with the hardware.

Hyphens, minus, and dashes in Debian man pages

Cyberax — Sat, 11 Nov 2023 01:10:04 +0000

Optimus keyboard debuted 15 years ago: https://www.artlebedev.com/optimus/maximus/

There have been other similar products, but they kinda all died. Mostly because experienced users just don't look at the keyboard.

Hyphens, minus, and dashes in Debian man pages

mpr22 — Fri, 10 Nov 2023 17:23:48 +0000

> hash/tilde is above a single-height return

Sounds like your laptop uses the American-style physical layout (and is thus not a standard British keyboard).

https://en.wikipedia.org/wiki/British_and_American_keyboards

Hyphens, minus, and dashes in Debian man pages

dwmw2 — Fri, 10 Nov 2023 15:40:48 +0000

We just need keyboards with LED display keycaps, so the software can ensure that they do display the symbol which will result from pressing them. In real time, as modifiers and combining characters change...

Hyphens, minus, and dashes in Debian man pages

farnz — Fri, 10 Nov 2023 13:54:21 +0000

I was responding to a different point; that of why a Logitech keyboard has pictures on keycaps that do not correspond to any character you can get from that key in a default setup of a single OS; it's done that way because if you share the keyboard between macOS and Windows (or macOS and Linux), you get different symbols in text input boxes from a default setup given the same scancodes.

Two orthogonal outcomes from the same situation (keyboard sending scancodes, and having pretty pictures in the hope your OS is set up to interpret the scancodes the way the keyboard maker thought it would). Although I do wish keyboard manufacturers would bring the Compose key back; I have it mapped as Shift-CapsLock (because who uses CapsLock as CapsLock), but I remember the good old days of a separate Compose keycap :-)

Hyphens, minus, and dashes in Debian man pages

dwmw2 — Fri, 10 Nov 2023 12:21:57 +0000

… the computer will do what I described unless I specifically tell the computer to use a non-default keymap

Right. That's what I was getting at in my first post when I described the things that the AltGr key does in the default keymap that I get when I install a Linux distribution in British English.

Hyphens, minus, and dashes in Debian man pages

farnz — Fri, 10 Nov 2023 10:45:11 +0000

Yep, but the default keymaps convert those scancodes to a specific set of symbols; my keyboard has two sets of keysyms printed on it, which makes it rather cluttered to look at, but that's Logitech's way of only producing one SKU for two markets.

The computer, of course, can't see the pictures; it relies on scancodes. But between OS defaults and my keyboard's HID descriptors telling the computer what it "should" do, the computer will do what I described unless I specifically tell the computer to use a non-default keymap.

Hyphens, minus, and dashes in Debian man pages

dwmw2 — Fri, 10 Nov 2023 10:38:47 +0000

The button you call the 4 key produces a scancode, probably 33. Unless you mean the keypad 4 key, which might be 92.

The software receiving those scancodes may convert them to anything it likes, according to the software keyboard layout/configuration. Any relationship between the symbols generated and the pretty pictures which are painted on the keyboard is purely coincidental.

On my Chromebook keyboard, the pretty picture above the 3 on the key to the left of that one is a #. But it generates a £ when I press it with Shift held down.

Hyphens, minus, and dashes in Debian man pages

farnz — Fri, 10 Nov 2023 09:54:17 +0000

I have a similar Logitech layout. The reason for those weird keys is that the keyboard has both the PC keysyms (right hand side of the key) and the Mac keysyms (left hand side of the key), along with some symbols that are found via AltGr on a PC keyboard or ⌥ / Option on a Mac keyboard.

It also has this thing of labelling all keys with names in lower case, which I've copied for the description below.

On my keyboard, the AltGr symbols are in unfilled circles for the PC keysym, and filled circles for the Mac keysym. So, the 4 key generates $ with shift, and € with alt gr on a PC, while on a Mac, it generates 4 or $ only. The 2 key is the other way round; on a Mac, it generates @ with shift, and € with opt ⌥, while on a PC, it generates " with shift.

And there are more complex keys, like the one to the top left, above tab. On a PC, I can get ` (on its own), ¬ (with shift) and | (with alt gr) from it, while on a Mac, it would give me § (on its own) or ± (with shift).

Hyphens, minus, and dashes in Debian man pages

Wol — Thu, 09 Nov 2023 22:48:17 +0000

> backslash between LSHIFT and Z;

Except the laptop I'm typing this on has no key between LSHIFT and Z

> hash/tilde between L and RETURN;

hash/tilde is above a single-height return

And the fancy ergo logitech I'm using - while similar to layout you describe - has some very weird keys.

2 / euro / at / double-quote

double-quote / at / single-quote

3 / pound / hash

4 / euro / dollar

and there's some more weirdos too ...

Cheers,
Wol

Hyphens, minus, and dashes in Debian man pages

mpr22 — Thu, 09 Nov 2023 18:43:45 +0000

> Standard British keyboard? Does such a thing exist any more?

In terms of layout? Yes, there is.

I've got one right in front of me, and another one in the "WEEE to get rid of" pile that I really need to clear down given I'm moving house soon. Both were purchased within the past five years. (The one in the WEEE pile is there due to negligent handling by mpr22, not due to negligent manufacture.)

They're from different manufacturers (neither of which is Unicomp) and have identical layouts to the Fujitsu FKB-4725 I had back in the late 90s-early 00s, apart from (a) having Windows keys and (b) the broken one having volume and power keys where the undamaged one has Foo Lock indicator lights.

(I'm a nine-finger typist; I learned to type before I ever laid hands on a stringed instrument.)

Even on a laptop, the distinguishing features are "double-height Return key; backtick left of 1; backslash between LSHIFT and Z; semicolon/colon, singlequote/at, and hash/tilde between L and RETURN; 2 has doublequote on it and 3 has £ on it".

Hyphens, minus, and dashes in Debian man pages

dwmw2 — Thu, 09 Nov 2023 13:20:03 +0000

"Standard British keyboard" didn't refer to the physical device on which you bash your fingers. It's about the standard keymap which you get when you install a Linux distribution and tell it what language and keyboard layout you want.

I'm fairly sure that whatever physical keyboard device I plug into my machine (within reason), if I press AltGr-m on it I'm going to get a µ, etc.

Hyphens, minus, and dashes in Debian man pages

Wol — Thu, 09 Nov 2023 13:03:31 +0000

> Most typists don't need to see the basic letters on the keyboard in order to be able to type. Why would you need to be able to see these?

Standard British keyboard? Does such a thing exist any more? I think I have access to four British keyboards - my fancy ergonomic Logitech jobby, my two laptops (home and work), and my wife's laptop. All four keyboards appear to be different.

And I'm a 6-fingered typist. Comes from playing the guitar - my left hand can type, my right hand is two fingered hunt-n-peck :-)

:-)

Cheers,
Wol

Hyphens, minus, and dashes in Debian man pages

Wol — Thu, 09 Nov 2023 13:00:00 +0000

> Most of these you can get by just enabling "Compose Key" in the "Keyboard" section of GNOME Settings.

Except my make.conf includes "-gnome -gtk".

Although I guess KDE/Plasma has something similar.

Cheers,
Wol

Hyphens, minus, and dashes in Debian man pages

dwmw2 — Thu, 09 Nov 2023 12:36:30 +0000

For a standard British keyboard, hold down the right AltGr key, press lots of others (both with an without Shift held down). See what you get.

There are arrows on yuUi ←↓↑→, m is µ, S is §. Superscript numbers ¹²³ on 123...

Most typists don't need to see the basic letters on the keyboard in order to be able to type. Why would you need to be able to see these? ☺

Hyphens, minus, and dashes in Debian man pages

cpitrat — Sun, 05 Nov 2023 11:17:05 +0000

But how harmful is it to have the wrong Hyphen in these cases? Compared to having the wrong one in command line arguments which means copy-pasting fails, searching fails, etc...?

Hyphens, minus, and dashes in Debian man pages

cpitrat — Sun, 05 Nov 2023 11:13:44 +0000

Why is this 'the right way'? I fail to see why having a default that interpret a character as another one visually undistinguishable and needing to escape it to really get it is 'the right way'. It seems to pe that the right way would be to have '-' mean '-' and '\-' mean the other one. Or, of course, directly type the unicode char or its code with the proper escape sequence.

Why not do the same with other char? Use '\_' if you want a real underscore otherwise you get U+0332. Use '\i' for a i otherwise you get 'U+0049, U+0131'.

Hyphens, minus, and dashes in Debian man pages

cpitrat — Sun, 05 Nov 2023 10:43:07 +0000

Or couldn't groff rather invert the behavior? I fail to be understand why '-' should be translated to the unicode version Hyphen rather than to the more natural ASCII Hyphen-minis version. And when the user wants a unicode Hyphen, then escape the -.

It's still an awful task to fix all the man pages which "use it right" (as per v1.23) but it seems much more natural to me.

Hyphens, minus, and dashes in Debian man pages

rra — Sat, 04 Nov 2023 19:45:42 +0000

And next week the problem will be reintroduced in half a dozen packages because for most people it's a silent error that they will introduce by accident. You need some equivalent of a spell-checker to catch reintroduction of the problem or all your work in converting files will degrade with time. And writing that checker is quite challenging.

If someone did manage to write a really good one, we could introduce it as a QA step and indeed it probably wouldn't be that hard to fix man pages over time. In my experience, upstream often doesn't really care, but will merge a PR since why not. But the one we had definitely did not work (I can think of several obvious problems with it just off the top of my head), and writing a better one is challenging.

Someone elsewhere in this discussion suggested using ChatGPT, an option that I find hilarious given ChatGPT's well-known devotion to accuracy and specific detail.

Hyphens, minus, and dashes in Debian man pages

qwertyface — Wed, 01 Nov 2023 11:57:59 +0000

These sort of issues are so pervasive and so hard to debug. I remember once copying and pasting a PostScript snippet from the PDF version of the PostScript Language Reference Manual that is available on Adobe's website, and it not working because the quotation marks were ‘ ’ not ' '. If there is one document in the whole history of computing where you wouldn't expect that mistake, it would be that one, but there it was.

Interestingly, PowerShell treats ‘ or ’ as ', and “ or ” as ", so copy-paste out of auto-converted documents works fine. I guess it probably does the equivalent with the various dashes. I'm not aware of any other language or shell that does the same. One Microsoft feature we should adopt?

Hyphens, minus, and dashes in Debian man pages

jkingweb — Mon, 30 Oct 2023 22:33:25 +0000

Thank you very much for the pointer. I found the groff_man_style(7) very well written and an excellent introduction. After spending a couple of days transcribing my manual to groff then mdoc I decided to go with mdoc (despite its doing a poorer job of layout in a couple of places, especially with links—the groff .UR macro yields beautiful output), but I don't know if I would have been able to grasp the basics without first reading groff_man_style(7), so you have my gratitude!