[PATCH] clean up docs for DWARF line number directives

[Bob Wilson <bwilson at tensilica dot com>]

While writing a description of the .local directive, I noticed some issues with 
the directive documentation for GAS.  As far as I can tell, the intention is to 
have the directives listed in alphabetical order, and in fact, the menu listings 
are (mostly) alphabetized.  The actual descriptions are not so consistent, i.e., 
the order of texinfo nodes does not match the menu.  I've got a series of 
patches, split up to make them easier to review, to fix these issues.  Here is 
the first patch.

The DWARF2 line number directives (.file, .loc, and .loc_mark_labels) were 
described as 3 sections in one texinfo node.  That doesn't work so well for a 
printed document, where it just looks like .file is out of order.  Even worse, 
there is another section for the default (non-DWARF) version of .file, so you 
get two different .file sections and they're not even adjacent.

This patch moves the description of the DWARF2 .file directive into the same 
node as the non-DWARF2 .file directive.  I used subheadings to separate the two 
versions, in the same way that is done for the ELF & COFF versions of .section. 
 I kept the no-file-dir conditional, so that when it is defined, you get only 
the DWARF2 version.

OK?

2008-10-07  Bob Wilson  <bob.wilson@acm.org>
	
	* doc/as.texinfo (Pseudo Ops): Remove no-file-dir conditional around
	menu entry for File; remove version-specific .file operands from menu
	description.  Replace "LNS directives" menu entry with new entries
	for "Loc" and "Loc_mark_labels".
	(LNS directives): Split into separate nodes for each directive.
	(Loc): New node for .loc directive.  Mention that this directive
	is for DWARF2 and add a missing article.
	(Loc_mark_labels): Likewise for .loc_mark_labels.
	(File): Change this node to describe both the default version and
	the DWARF2 version of .file.  Move the no-file-dir conditional to
	include only the default version.

Index: doc/as.texinfo
===================================================================
RCS file: /cvs/src/src/gas/doc/as.texinfo,v
retrieving revision 1.185
diff -u -r1.185 as.texinfo
--- doc/as.texinfo	6 Oct 2008 17:31:39 -0000	1.185
+++ doc/as.texinfo	7 Oct 2008 18:06:24 -0000
@@ -3841,10 +3841,7 @@
 * Exitm::			@code{.exitm}
 * Extern::                      @code{.extern}
 * Fail::			@code{.fail}
-@ifclear no-file-dir
-* File::                        @code{.file @var{string}}
-@end ifclear
-
+* File::                        @code{.file}
 * Fill::                        @code{.fill @var{repeat} , @var{size} , @var{value}}
 * Float::                       @code{.float @var{flonums}}
 * Func::                        @code{.func}  
@@ -3875,8 +3872,8 @@
 * Linkonce::			@code{.linkonce [@var{type}]}
 * List::                        @code{.list}
 * Ln::                          @code{.ln @var{line-number}}
-
-* LNS directives::              @code{.file}, @code{.loc}, etc.
+* Loc::                         @code{.loc @var{fileno} @var{lineno}}
+* Loc_mark_labels::             @code{.loc_mark_labels @var{enable}}
 @ifset ELF
 * Local::                       @code{.local @var{names}}
 @end ifset
@@ -4244,22 +4241,11 @@
 by a direct branch and no copy of the return address exists in memory
 or another register.
 
-@node LNS directives
-@section @code{.file @var{fileno} @var{filename}}
-@cindex @code{file} directive
-When emitting dwarf2 line number information @code{.file} assigns filenames
-to the @code{.debug_line} file name table.  The @var{fileno} operand should
-be a unique positive integer to use as the index of the entry in the table.
-The @var{filename} operand is a C string literal.
-
-The detail of filename indices is exposed to the user because the filename
-table is shared with the @code{.debug_info} section of the dwarf2 debugging
-information, and thus the user must know the exact indices that table
-entries will have.
-
+@node Loc
 @section @code{.loc @var{fileno} @var{lineno} [@var{column}] [@var{options}]}
 @cindex @code{loc} directive
-The @code{.loc} directive will add row to the @code{.debug_line} line
+When emitting DWARF2 line number information,
+the @code{.loc} directive will add a row to the @code{.debug_line} line
 number matrix corresponding to the immediately following assembly
 instruction.  The @var{fileno}, @var{lineno}, and optional @var{column}
 arguments will be applied to the @code{.debug_line} state machine before
@@ -4291,9 +4277,11 @@
 
 @end table
 
+@node Loc_mark_labels
 @section @code{.loc_mark_labels @var{enable}}
 @cindex @code{loc_mark_labels} directive
-The @code{.loc_mark_labels} directive makes the assembler emit an entry
+When emitting DWARF2 line number information,
+the @code{.loc_mark_labels} directive makes the assembler emit an entry
 to the @code{.debug_line} line number matrix with the @code{basic_block}
 register in the state machine set whenever a code label is seen.
 The @var{enable} argument should be either 1 or 0, to enable or disable
@@ -4529,21 +4517,51 @@
 include the value of @var{expression}.  This can occasionally be useful inside
 complex nested macros or conditional assembly.
 
-@ifclear no-file-dir
 @node File
-@section @code{.file @var{string}}
-
+@section @code{.file}
 @cindex @code{file} directive
+
+@ifclear no-file-dir
+There are two different versions of the @code{.file} directive.  Targets
+that support DWARF2 line number information use the DWARF2 version of
+@code{.file}.  Other targets use the default version.
+
+@subheading Default Version
+
 @cindex logical file name
 @cindex file name, logical
-@code{.file} tells @command{@value{AS}} that we are about to start a new logical
-file.  @var{string} is the new file name.  In general, the filename is
+This version of the @code{.file} directive tells @command{@value{AS}} that we
+are about to start a new logical file.  The syntax is:
+
+@smallexample
+.file @var{string}
+@end smallexample
+
+@var{string} is the new file name.  In general, the filename is
 recognized whether or not it is surrounded by quotes @samp{"}; but if you wish
 to specify an empty file name, you must give the quotes--@code{""}.  This
 statement may go away in future: it is only recognized to be compatible with
 old @command{@value{AS}} programs.
+
+@subheading DWARF2 Version
 @end ifclear
 
+When emitting DWARF2 line number information, @code{.file} assigns filenames
+to the @code{.debug_line} file name table.  The syntax is:
+
+@smallexample
+.file @var{fileno} @var{filename}
+@end smallexample
+
+The @var{fileno} operand should be a unique positive integer to use as the
+index of the entry in the table.  The @var{filename} operand is a C string
+literal.
+
+The detail of filename indices is exposed to the user because the filename
+table is shared with the @code{.debug_info} section of the DWARF2 debugging
+information, and thus the user must know the exact indices that table
+entries will have.
+
 @node Fill
 @section @code{.fill @var{repeat} , @var{size} , @var{value}}