[docs] Naming on GDB/MI sections in docs

[docs] Naming on GDB/MI sections in docs

[Vladimir Prus]

At present, the toc of documentation PDF looks like this:

	gdb
	27 The gdb/mi Interface
	Function and Purpose
	Notation and Terminology
	27.3 gdb/mi General Design
	27.3.1 Context management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	27.3.2 Asynchronous command execution and non-stop mode . .
	27.3.3 Thread groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	27.4 gdb/mi Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	27.4.1 gdb/mi Input Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

I have two concerns about it:

1. Why some section titles are started by "gdb/mi"? We're already inside "The gdb/mi Interface"
section, so it's reasonable to assume subsections talk about gdb/mi. Can we remove those
prefixes?

2. Why is "Function and Purpose" subsection lacks section number in the TOC? I would
have expected "27.1".

Thanks,
Volodya

Re: [docs] Naming on GDB/MI sections in docs

[Eli Zaretskii]

> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Fri, 8 Jan 2010 18:40:44 +0300
> 
> 
> At present, the toc of documentation PDF looks like this:
> 
> 	gdb
> 	27 The gdb/mi Interface
> 	Function and Purpose
> 	Notation and Terminology
> 	27.3 gdb/mi General Design
> 	27.3.1 Context management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
> 	27.3.2 Asynchronous command execution and non-stop mode . .
> 	27.3.3 Thread groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
> 	27.4 gdb/mi Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
> 	27.4.1 gdb/mi Input Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Ouch!

> 1. Why some section titles are started by "gdb/mi"? We're already
> inside "The gdb/mi Interface" section, so it's reasonable to assume
> subsections talk about gdb/mi.

When you look at the entire TOC, yes.  But what if you land in that
section in Info, by following some cross-reference or index search?

> Can we remove those prefixes?

If others don't mind (and if the consideration I mention above doesn't
make you change your mind), then I won't object.  Just make sure we
don't already have other sections by the same name.

> 2. Why is "Function and Purpose" subsection lacks section number in
> the TOC? I would have expected "27.1".

Because it's an @unnumberedsec for some reason.  Change it to
@section, and you will have the number.  The same goes for "Notation
and Terminology".

Thanks for spotting these blunders.