MySQL Bugs: #34599: MySQLD Option and Variable Reference need to be consistent in formatting!

Bug #34599	MySQLD Option and Variable Reference need to be consistent in formatting!
Submitted:	15 Feb 2008 17:14	Modified:	13 Nov 10:41
Reporter:	Jonathan Miller
Status:	Patch pending
Category:	Server	Severity:	S3 (Non-critical)
Version:	5.1	OS:	Any
Assigned to:	Sergei Golubchik	Target Version:
Triage:	Triaged: D4 (Minor)

Description:
http://dev.mysql.com/doc/refman/5.1/en/mysqld-option-tables.html

Please take a moment to review the above link ^.

You will notice that there is many different variations in variable formatting. Not being
consistent in naming conventions for server variables make us look like we are not ready
for enterprise. 

I feel that we should come up with a standard and that all server related options should
be corrected to follow that standard.

There is issue with backwards computability, therefore, if this is implemented efforts to
ensure that upgrade customer will not be affected will need to be taken.

Examples:

Aborted_clients
abort-slave-event-count
bulk_insert_buffer_size

   

How to repeat:
N/A see above

Suggested fix:
all variables follow one standard

1) either all uppercase or all lowercase, but should not be both or a mix
2) either all dashes or all underlined, but should not be both or a mix

 

examples

VAR-NAME-OPT
VAR_NAME_OPT
var-name-opt
var_name_opt

documentation issue.
command line options (like --abort-slave-event-count) use lowercase, dashes.
server variables (like bulk_insert_buffer_size, accessible as @@var_name) use lowercase,
underscore.
status variables (visible in SHOW STATUS) use first letter uppercase, underscore.

The manual puts them all in one table, which create that inconsistent look you're
complaining about.

I must beg to differe: There *are* server options that use underscores, e.g. it's
--ndb_autoincrement_prefetch_sz and not --ndb-autoincrement-prefetch-sz (which really
ought to be "--ndb-autoincrement-prefetch-size" as there's no reason to abbreviate a
4-letter word).

In addition, there are some settings which can be made via a command-line option but not
as a server variable, and some which can be set as a server variable but not as a
command-line option, and in many cases, there appears to be no rhyme or reason for this,
other than "That's just the way it is".

These are not documentation issues.

Additional issues:

In cases where a setting can be made as either a command-line option or a server
variable, which of these should be the canonical form that appears in the docs?

We're aware of the conventions, but (a) these are not always followed in the server; and
(b) when we suggest putting these in the docs, people complain that it's too difficult to
remember them without being told explicitly (e.g.) "the mysqld option is
'--auto-increment-offset' but the server variable is 'auto_increment_offset'".
Seriously!

Finally, I'd like to point out that, in the latest 6.0, there are 288 status variables,
308 system variables, and $__DEITY__ knows how many server options. It's about time that
we started supporting some kind of namespaces for all of these.

cheers

jon.

it's --ndb-autoincrement-prefetch-sz as far as I can see:

% mysqld --help|grep t-prefetch
  --ndb-autoincrement-prefetch-sz=# 
ndb-autoincrement-prefetch-sz     1

Although, indeed, I'd prefer mysqld --help to print all option names with dashes
(auto-converting them in my_print_help and my_print_variables). I'll submit a separate
feature request about it, let's keep this one what it was, about
http://dev.mysql.com/doc/refman/5.1/en/mysqld-option-tables.html

bug#34635

Jeb: Setting this to !Bg because, as Serg pointed out, the table you're referring to just
*looks* inconsistent while it apparently isn't. If you still feel we (Docs) should do
anything about it, please explicitly say what we should do (e.g. split the table into
multiple ones), and change this bug to a feature request.

There are also a number of InnoDB *options* that use underscores in the names, which you
can confirm by inspection of the option structure in sql/mysqld.cc or by running mysqld
--verbose --help.

That too is inconsistent with the general convention that dashes are used in option
names. The documentation can't be consistent if it is to follow the server's help text
and that help text isn't consistent.

paul: it's a part of bug#34635

Work log open for this issue

https://intranet.mysql.com/worklog/Server-Sprint/?tid=4277

will be fixed in WL#4738