gdb/doc: reorder and group sections relating to aliases
authorAndrew Burgess <andrew.burgess@embecosm.com>
Tue, 12 Jan 2021 13:02:30 +0000 (13:02 +0000)
committerAndrew Burgess <andrew.burgess@embecosm.com>
Thu, 21 Jan 2021 18:16:49 +0000 (18:16 +0000)
commita72d0f3d69896b5fcdc916e0547fe774dcb58614
tree6a68e43b50090fc484e15174efb4ee9d5e6f6ce5
parent325d39e4e09f0b7c8eec7e33ca93d0a9c82632ec
gdb/doc: reorder and group sections relating to aliases

This started by observing that the section name:

  Automatically prepend default arguments to user-defined aliases

Is very long.  When this is rendered in the PDF manual (at least for
me), this name is so long that in the table of contents the page
number ends up being misaligned.

My first thought was we could drop the 'to user-defined aliases' bit
if this section became a sub-section of the section on aliases.

So then I looked for a section with 'aliases' in its name, and
couldn't find one.

It turns out that aliases are documented in a section called:

  Creating new spellings of existing commands

Which (to me) seems an odd aspect of aliases to emphasise.

So, in this patch I make the following changes:

  - Move the section on aliases earlier in the manual, this is now
    immediately after the section about creating user defined
    commands.  This made more sense to me.

  - Rename the section on aliases from 'Creating new spellings of
    existing commands' to 'Command Aliases'.

  - Update the wording of the first paragraph in the 'Command Aliases'
    section so that it reads better given the new name.

  - Add a cross-reference from the 'Command Aliases' section to the
    'Python' section now that the aliases section comes first.

  - Down case all the text inside @var within this section as this is
    the correct style for the GDB manual.

  - Move the section on default args to become a sub-section of the
    'Command Aliases' section, and rename this sub-section from
    'Automatically prepend default arguments to user-defined aliases'
    to 'Default Arguments'.

  - Add @menu into the 'Command Aliases' section to link to the
    'Default Arguments' subsection.

  - Add a @cindex entry to the default arguments sub-section.

gdb/doc/ChangeLog:

* gdb.texinfo (Commands): Update menu.
(Extending GDB): Likewise.
(Command aliases default args): Moved later into the document,
added a cindex entry.  Renamed the section 'Automatically prepend
default arguments to user-defined aliases' to 'Default Arguments'.
(Aliases): Moved earlier in the document.  Minor rewording of the
first paragraph, down-cased the text inside all uses of @var, and
added a cross reference to the Python code.  Renamed the section
'Creating new spellings of existing commands' to 'Command
Aliases'.
gdb/doc/ChangeLog
gdb/doc/gdb.texinfo