Re: [Quilt-dev] [patch 08/26] Make synopsis comprehensive.

[Jean Delvare]

On Sat, 16 Jun 2018 12:22:40 -0400, address@hidden wrote:
> Document --quiltrc, --trace, and --version options explicitly.

Good idea.

> Separate the informational operation modes for reporting help and
> version information.

Good idea as well.

> Mark up synopsis canonically (literals in bold, variable content in
> italics, and roman for "synopsis language" (option brackets, etc.)).
> 
> Use groff_man(7)'s SY and YS macros for more attractive presentation.
> 
> Index: quilt/doc/quilt.1.in
> ===================================================================
> --- quilt.orig/doc/quilt.1.in
> +++ quilt/doc/quilt.1.in
> @@ -4,8 +4,19 @@
>  .SH NAME
>  quilt \\- tool to manage series of patches
>  .SH SYNOPSIS
> -.B quilt
> -[\\-h] command [options]
> +.SY quilt
> +.RB [ \\-\\-quiltrc
> +.IR file ]
> +.OP \\-\\-trace
> +.I command

You are dropping the trailing [options], which I believe was valuable.
You may argue that "options" is vague, but it had at least the merit to
show that command-specific options must go after the command. In fact,
[command options] may be even better.

> +.YS
> +.SY "quilt \\-h"
> +.RI [ command ]
> +.SY quilt
> +.I command
> +.B \\-h

This one is redundant with both the first invocation (technically) and
the second invocation (functionally), so I would not mention it. At
least not on a separate line... If you really want to document command
option -h because it is common to all commands, then I would add it to
the first invocation:

        quilt [--quiltrc file] [--trace] command [-h] [command options]

> +.SY "quilt \\-\\-version"
> +.YS
>  .SH DESCRIPTION
>  Quilt is a tool to manage large sets of patches by keeping track of the
>  changes each patch makes.

Thanks,
-- 
Jean Delvare
SUSE L3 Support