0

When writing a manual page of a command, the SYNOPSIS contains:

.RB [ \-v
.IR version ]

Unfortunately when formatting the SYNOPSIS there is a line break between "[-v" and "version]".

How can I avoid that?

Adding the Obvious

As requested multiple times, here is a longer sample input for the lack of imagination, as well as a screenshot showing the problem: Screenshot of formatted sample (problem area highlighted)

And here is the source:

.TH FOOBAR-DEMO 8 2022-03-16 "Charlie Brown" "System Administration"
.\"
.SH NAME
foobar-demo \- demonstration of manual formatting
.\"
.SH SYNOPSIS
.na
.nr hy-mode-save \n[.hy]
.hy 0
.B foobar-demo123
.RB [ \-a
.IR match_spec ]
.RB [ \-\-resource-agent
.IR match_spec ]
.RB [ \-v
.IR version ]
.RB [ \-\-version
.IR version ]
.hy \n[hy-mode-save]
.ad b
.\"
.SH DESCRIPTION
The purpose of this page is none...
Improve this question
2
  • Just add some text before to shift "-v" to the end of the line.
    – U. Windl
    Commented Mar 16, 2022 at 14:04
  • You have an unexpected line break, or have you reached the end of the line and you want to push [-v to the next so it's kept adjacent to --version]?
    – Chris Davies
    Commented Mar 16, 2022 at 14:09

3 Answers 3

Reset to default
1

Thomas Dickey has one correct (and portable) solution but like you, I find it a bit unprepossessing due to the font selection escape sequences. I much prefer man(7)'s font styling macros.

Further, the \ (backslash-space) escape sequence can also be ugly because its unbreakable space is fixed-width; on a line that undergoes adjustment, this can be noticeable and jarring.

I therefore recommend using the output line continuation escape sequence \c to permit an input line to end without causing the insertion of a breakable space, and the \~ escape sequence for an unbreakable, but adjustable space.

You've turned off adjustment in your example, but that is not necessary as I will show. By using \~, adjustment can be done evenly across the lines of the synopsis without causing problems. This escape sequence is portable to all currently-maintained troff projects except that in Illumos. groff has had it since 1991 (at least), Heirloom Doctools since September 2005, mandoc (which isn't a troff but does parse man pages) since September 2009, neatroff since September 2016, and Plan 9 from User Space troff as of August 2022.

In your example, you used the groff register .hy and groff's extended interpolation syntax to get at it. If you're using groff, you might want to consider its SY/YS extensions to the man(7) macro package for setting your command synopses.2 (These macros also save and restore the hyphenation mode for you.)

.TH FOOBAR-DEMO 8 2022-03-16 "Charlie Brown" "System Administration"
.\"
.SH NAME
foobar-demo \- demonstration of manual formatting
.\"
.SH SYNOPSIS
.B foobar\-demo123 \" I escaped this hyphen as well.
.RB [ \-a\~\c
.IR match_spec ]
.RB [ \-\-resource-agent\~\c
.IR match_spec ]
.RB [ \-v\~\c
.IR version ]
.RB [ \-\-version\~\c
.IR version ]
.\"
.SH DESCRIPTION
Improve this answer
3
  • Interestingly \c is documented as "interrupt text processing", and it can be queried via \n[.int]in groff. So that is rather non-obvious to me. Also I had been wondering whether I could write a "horizontal equivalent" of .ne, possibly using \n[hp] in groff before.
    – U. Windl
    Commented Mar 28, 2022 at 6:31
  • I entirely agree about the non-obviousness of \c's meaning. I think this has led variously to avoidance when it would be useful, and cargo-cult inclusion of it when it is not. In the forthcoming groff release, its Texinfo manual, groff(7) man page, and groff_man_style(7) page--the last aimed at authors of man pages--try to explain \c more clearly than in the past.
    – TheNotoriousGBR
    Commented Mar 28, 2022 at 15:59
  • I need to correct myself about the longevity of \~ in groff. It dates back not merely to December 2000 (when its support code was refactored by Werner Lemberg), but to the oldest copies of James Clark's original work that are publicly available--that means groff 1.02, released 1991-06-02.
    – TheNotoriousGBR
    Commented Mar 28, 2022 at 17:06
1

The macros get in the way. You can fix the problem using an escaped space (which will not split the line), like this:

.TH FOOBAR-DEMO 8 2022-03-16 "Charlie Brown" "System Administration"
.\"
.SH NAME
foobar-demo \- demonstration of manual formatting
.\"
.SH SYNOPSIS
.na
.nr hy-mode-save \n[.hy]
.hy 0
.B foobar-demo123
\fB[\-a\ \fImatch_spec\fR]
\fB[\-\-resource-agent\ \fImatch_spec\fR]
\fB[\-v\ \fIversion\fR]
\fB[\-\-version\ \fIversion\fR]
.hy \n[hy-mode-save]
.ad b
.\"
.SH DESCRIPTION
The purpose of this page is none...
Improve this answer
1
  • Of course I could do that, but I consider explicit font commands (\f) to be ugly, and they make the source hard to read.
    – U. Windl
    Commented Mar 17, 2022 at 10:21
-1

Most likely, you have a CRLF in the line, instead of LF.

Improve this answer
4
  • Please do not guess what I might have. In fact the lines are OK.
    – U. Windl
    Commented Mar 16, 2022 at 14:06
  • 1
    @U.Windl we have to guess because the information is not in your question
    – Chris Davies
    Commented Mar 16, 2022 at 14:10
  • 1
    @White Owl Maybe explain what a difference CRLF would make over just LF.
    – U. Windl
    Commented Mar 17, 2022 at 10:23
  • CRLF - windows style line separator. 0D,0A in hex. \r\n in C style strings. LF - linux style line separator. 0A in hex. \n in C style strings. groff adds a line feed if it sees the \r in the text.
    – White Owl
    Commented Mar 17, 2022 at 12:17

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .