Re: [RP] [PATCH] improve new manpage layout

[Jérémie Courrèges-Anglas]

"Bernhard R. Link" <address@hidden> writes:

> * Jérémie Courrèges-Anglas <address@hidden> [140325 22:21]:
>> "Bernhard R. Link" <address@hidden> writes:
>> 
>> > Make everything to be typed in that way Ic,
>> 
>> Literal strings are literal strings.  In some contexts they can be
>> treated as command modifiers (Cm), but not as internal commands on their
>> own.
>
> Well, I'm not sure which sementic is correct from them. But what I know
> is that their layout is wrong. They are printed as normal text (thus
> like the markers for optional / alternate arguments) but not bold as
> they should be so that people know which parts are to be typed in that
> way.

I've modified the command sub-arguments to use Cm instead of Li, and
I think it's much better like this.  I'm still puzzled about the
VARIABLES section.

>> > use Br* to denote
>> > alternates,
>>
>> I disagree.  Square brackets denote optional arguments.  Using Op is
>> perfect here, from semantic and presentation points of view.
>
> My description was perhaps a bit too short: I mean
>
> "use Br* to denote non-optional alternates".
> (I've kept [ ... | ... ] where nothing is allowed).

Ok, I misunderstood your intent here, since the argument for `dedicate'
and `gravity' is actually optional.  I've corrected `warp' and `swap',
thanks.

>> Also curly brackets are not a replacement for parens to denote groups of
>> alternates.
>
> I'm also happy with round parens. Braces are just a nice way to express
> that the mdoc manpage of my system uses:
> "If there are alternative values for a mandatory
> parameter, braces are used (together with ‘|’) to enclose the value
> set."

I haven't modified the VARIABLES section because I still can't think of
a better way than Li to denote settings values, and I doubt adding [ ]
to all alternatives occurrences would improve readability (yes, here the
setting value is optional).

-- 
jca | PGP : 0x1524E7EE / 5135 92C1 AD36 5293 2BDF  DDCC 0DFA 74AE 1524 E7EE