16

I was reading the manpage for gdb and I came across the line:

You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2.

The C@t{++} looks like a regex but I can't seem to decode it.

What does it mean?

Gilles 'SO- stop being evil'
  • 807,993
  • 194
  • 1,674
  • 2,175
Display name
  • 1,267
  • 2
  • 14
  • 22

2 Answers2

28

GNU hates man pages, so they usually write documentation in another format and generate a man page from that, without really caring if the result is usable.

C@t{++} is some texinfo markup which didn't get translated. It wasn't intended to be part of the user-visible documentation. It should simply say C++ (possibly with some special font for the ++ to make it look nice).

  • 8
    In this case, it was the exact reverse. [The doco was originally written in roff in the 1980s](https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=commitdiff;h=7b4ac7e1ed2c4616bce56d1760807798be87ac9e#patch54) and the roff (badly) hand-converted to texinfo in 2013. – JdeBP Oct 18 '18 at 05:11
  • 6
    Can we get some citation for the opinions in the first sentence? – thosphor Oct 18 '18 at 07:58
  • 4
    @thosphor See e.g. https://unix.stackexchange.com/questions/77514/what-is-gnu-info-for – Kusalananda Oct 18 '18 at 08:41
  • 3
    @Kusalananda Thanks for the link/info. That source doesn't support the opinion in the answer though. – thosphor Oct 18 '18 at 08:47
  • 2
    @thosphor "hate" is a bit of an exaggeration, but it's clear that RMS and FSF don't consider it their preferred format. – Barmar Oct 18 '18 at 21:15
  • The extra historical info from @JdeBP is nice to know, but it doesn't seem relevant to the present situation. texinfo is the master format now, or this error wouldn't be in the man page. –  Oct 18 '18 at 23:11
18

The sequence @t{...} is the texinfo markup to typeset a sequence using fixed-width font (see the Fonts section of the texinfo manual for more details and some examples.)

It looks like they were trying to write "C++" and have the "++" use a fixed width font (like "++".) Perhaps someone found that yields better results with specific fonts while rendering documentation in PostScript or PDF or some format that uses variable-width fonts by default.

The reason why this doesn't seem to work and you're seeing the unprocessed sequence is that texinfo is used by the info documentation system, while man uses nroff which is a different language with different commands (for instance, the command to switch to a constant width font in nroff is \f(CW), so it of course didn't recognize the @t{...} sequence unchanged.

This issue seems to have been introduced in a commit from April 2013 where the man pages were converted to texinfo and that specific markup was introduced. It seems the script now used to generate the man pages (texi2man.pl) doesn't recognize or properly convert that sequence.

filbranden
  • 21,113
  • 3
  • 58
  • 84
  • 4
    [Jan Kratochvil of RedHat converted the original roff manual to texinfo in April 2013](https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=commitdiff;h=43662968f15ddbd815d64b4392a0171d8736f73a) and _introduced_ this markup at that point. – JdeBP Oct 18 '18 at 05:06
  • 6
    The irony is that [`pod2man` provides a roff macro for "a nicer C++"](https://sources.debian.org/src/gdb-doc/8.1-1/gdb/doc/gdb.1/#L18) that does not get used because [its recognition code](https://github.com/rra/podlators/blob/18ec39768f4f06c0790cc97b5e09a6f110ee86d1/lib/Pod/Man.pm#L578) only kicks in for the string "C++". – JdeBP Oct 18 '18 at 05:25
  • 2
    @JdeBP You seem to have the answers here so why don't you write one? – pipe Oct 18 '18 at 06:05
  • 3
    Collaboration, pipe. [Answer comments are for suggesting improvements to answers](https://unix.stackexchange.com/help/privileges/comment). Here are some improvements. Let's see whether the two answerers here wish to incorporate them. I want not to step on their toes if they do. – JdeBP Oct 18 '18 at 09:56
  • 1
    Updated to include the information about the commit that introduced the change, thanks a lot @JdeBP for digging it up! Now we just need a commit to fix it upstream – filbranden Oct 18 '18 at 13:33
  • 3
    @JdeBP Thanks for the call-out. My recollection is that I got the `C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'` troff expansion from a labbie at Murray Hill during the initial evangelism of the C++ language back when we were typesetting USENIX proceedings for those early C++ events. The labbies were pretty serious about their troff. :) – tchrist Oct 19 '18 at 00:21