Subject: bug#14649: Problems in chroot.2, ln.1, ptx.1, test.1, [.1

From: "Eric S. Raymond" <[email-masked]>
Date: Tue, 18 Jun 2013 12:22:35 -0400

Pádraig Brady <[email-masked]>:
> > Parenthesized comments in command synopsis.  This is impossible
> > to translate to DocBook.
> 
> So is this a limitation of docbook, troff or doclifter?

It's a limitation of XML-DocBook.  The markup includes a special syntax
for synopses with a fixed grammar and terminals. Over 99.7% of manual
pages with command synopses fit that grammar; yours is one of the very few 
exceptions.

> I'm unsure what to do here, but we can't just remove the comments.

I don't see why not; they're just ordinal numbering and thus convey
little or no information.  But if you want a rewrite less dependent
obn the numbering, here's how I'd do it:

With the -T option (1st form above), create a link to TARGET with the
name LINK_NAME.

With a single file or directory argument (2nd form), create a link to
TARGET in the current directory.

With the -t option (3rd form) or a final directory argument (4th form),
create links to each TARGET in DIRECTORY.

Create hard links by default, symbolic links with \fB\-\-symbolic\fR.
By default, each destination (name of new link) should not already exist.
When creating hard links, each TARGET must exist.  Symbolic links
can hold arbitrary text; if later resolved, a relative link is
interpreted in relation to its parent directory.

-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>