[XBoard-devel] texi file

[h . g . muller]

If we are going to rethink the taxi file:

what would be the best way to handle the menu control - command-line
option duality? Almost any menu control corresponds to an option, because
most settings are persistent, which necessitates an option to store it in
the settings file. Historically there were almost no menu dialogs, so the
descriptions often reside in the options section. When menu controls were
later added, and had to be described in the manual, this invited either
duplicated description of the same feature, or just a reference to the
option description.

Interactive help clicks can only retrieve the description of the menu
control, and it would not be very illuminating to get help texts of the
form "This sets the value of the -XXX option".

So it seems the division into a menu section and an options section is
starting to be counter-productive. Perhaps the documentation should be
based on a unified description of the feature, with headers that both
mention the menu control and the command-line option that can be used to
set it. Like

@item Flip View
@itemx -flipView true/false
@itemx -flip
@itemx -xflip
@cindex Flip View, Menu item
@cindex flipView, option
@cindex flip, option
@cindex xflip, option
The Flip View menu item nverts your view of the chess board
for the duration of the current game.
The @kbd{F2} key is a keyboard equivalent.
Starting a new game returns the board to 'standard orientation',
which is determined as follows:
if @samp{Auto Flip View} in the @samp{General Options} dialog is on,
and you participate in the game yourself,
you will play upwards.
Otherwise, when the (volatile) @code{flipView} option was set to true,
black will play upwards,
when it is false, white will play upward.
Default: false

Such unified descriptions could then be grouped by menu dialog, and the
menu dialogs (with a little description of their general function and
content) would be gouped by main menu.

That just leaves options that cannot be controlled from the menu for a
separate option section.

Does that sound like a workable idea?

H.G.