From: Sandra Loosemore <sandra@codesourcery.com>
To: Jonathan Wakely <jwakely@redhat.com>, <gcc@gcc.gnu.org>
Subject: Re: Documentation style for options with optional levels
Date: Wed, 10 Apr 2019 15:46:00 -0000 [thread overview]
Message-ID: <555f7a33-8803-8e6a-c402-fc33e2f09633@codesourcery.com> (raw)
In-Reply-To: <20190410111326.GF943@redhat.com>
On 4/10/19 5:13 AM, Jonathan Wakely wrote:
> For options that can be used as -foo or -foo=level we have a variety
> of different styels for documenting what the default level is. See
> below for several examples. I find this a bit confusing when try to
> see what it means to use the option without a level.
>
> Do we want to pick a style and try to be consistent?
I think part of the problem here is that it collides with the existing
convention that we document the -foo form for options that default to
off and the -no-foo form for options that default to on, and we probably
have instances of both flavors that were originally binary options but
now take an optional level. Plus people tack on to the documentation
incrementally for new options and don't always check for or copy the
style of documentation for similar option syntax elsewhere.
I suspect anything we do will eventually get bit-rotten anyway, but if
you want a convention, I'd propose that we always document -foo=level as
the primary form and explicitly list whichever of -foo and/or -no-foo
are also supported (regardless of the default), with information in the
text about what level they correspond to, what the default is, etc.
E.g. roughly following this organization:
@item -foo=@var{level}
@itemx -foo
@itemx -no-foo
@opindex foo
This option controls....
The @var{level} may be one of....
@option{-foo} without a @var{level} is equivalent to....
@option{-fno-foo} is equivalent to....
The default is.... [and/or information about what setting is implied by
other options].
-Sandra
next prev parent reply other threads:[~2019-04-10 15:46 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-10 11:13 Jonathan Wakely
2019-04-10 12:42 ` Nathan Sidwell
2019-04-10 13:53 ` Jonathan Wakely
2019-04-10 15:46 ` Sandra Loosemore [this message]
2019-04-10 22:39 ` Martin Sebor
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=555f7a33-8803-8e6a-c402-fc33e2f09633@codesourcery.com \
--to=sandra@codesourcery.com \
--cc=gcc@gcc.gnu.org \
--cc=jwakely@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).