organization of C Extensions in manual

[David Wohlferd]

 > Hmmmm, looking at your list, I think it is better to leave things that
 > are hard to categorize where they are, as top-level sections within the
 > chapter, rather than trying to group them arbitrarily with other things
 > that are hard to categorize; the latter only makes things things harder
 > to find by burying them.

I understand what you are saying.  I have said uncomplimentary things 
about other documentation that had the information I was looking for in 
the 'wrong' place.

OTOH, leaving everything ungrouped is what we have now, and that's also 
a mess.  An unordered list with more than about a dozen entries also 
makes it "hard to find things by burying them."

While I have disagreed with some of your suggestions (see comments 
below), some of them made good sense.  In an attempt to keep this post 
readable, I have included a complete, updated list of groupings at the 
end, rather than piecemeal inline.

 >> Arrays and Vectors
 >>      Designated Inits: Labeling elements of initializers.
 >
 > I think this one might better be placed in a section on initializers.

Since the only place 'Designated Inits' can be used is on arrays, 
placing this in the 'Arrays and Vectors' section seems appropriate.

 >>      Vector Extensions: Using vector instructions through built-in 
functions.
 >
 > I'm not sure where this one belongs, but it doesn't seem to go with
 > array extensions.  It's not really about builtins, either.

The section is entitled 'Arrays and Vectors.'  I don't see why a topic 
about vectors doesn't fit.

 >
Extracting your next comments, you object to Inline, Thread-Local and 
Volatiles being grouped under 'Attributes.'  Honestly, I don't have a 
problem implying that these are attributes.  But since you do, I pored 
over some standards docs, and it seems like they refer to these things 
as 'Specifiers.'  I have created a new section and moved these three there.

 >> Computed values
 >> Constant Values

 > I don't really like this division.  To me, it would be more useful to
 > have a section on purely syntactic extensions (the binary constants,
 > character escapes, dollar signs in identifiers), and one on expression
 > values.

I don't know what the term "syntactic extensions" would mean in this 
context.  Not knowing what it means makes it difficult to know what 
items to place under it.

 > I don't think the variadic macros section belongs in either of those
 > groups and should be left separate for now.

Ok.

 >> Naming

 > A lot of these things don't have anything to do with naming, and
 > burying them here would just make them hard to find.  How about
 > moving the purely syntactic things to that section and leave the
 > others at top-level for now, unless some other grouping suggests
 > itself appropriate with the leftovers.

Ok, here you've got me.  Forcing some of these items into 'Naming' 
required a bit of imagination.  I could walk you thru the contortions I 
used to justify them, but finding a better grouping seems like a more 
sensible plan (see below).

 >> Misc
 > The first two items might go into the syntactic extensions category.
 > Pragmas and inline asm definitely should stay at top level. Not
 > sure about the others.

It is not clear to me that moving them back to top level provides any 
advantages over putting them in the 'Misc' group.

Folding in your changes (especially re-working Naming and 
Constants/Computed) gives me this.  I can already guess which one is 
going to make you wince, but perhaps you can come up with a better 
section name.

Arrays and Vectors
     Designated Inits: Labeling elements of initializers.
     Pointers to Arrays: Pointers to arrays with qualifiers work as 
expected.
     Subscripting: Any array can be subscripted, even if not an lvalue.
     Variable Length: Arrays whose length is computed at run time.
     Vector Extensions: Using vector instructions through built-in 
functions.
     Zero Length: Zero-length arrays.

Assignments
     Cast to Union: Casting to union type from any member of the union.
     Conditionals: Omitting the middle operand of a ‘?:’ expression.
     Compound Literals: Compound literals give structures, unions or 
arrays as values.
     Initializers: Non-constant initializers.
     Statement Exprs: Putting statements and declarations inside 
expressions.

Attributes
     Attribute Syntax: Formal syntax for attributes.
     Function Attributes: Declaring that functions have no side effects, 
or that they can never return.
     Label Attributes: Specifying attributes on labels.
     Type Attributes: Specifying attributes of types.
     Variable Attributes: Specifying attributes of variables.

BuiltIns
     __atomic Builtins: Atomic built-in functions with memory model.
     __sync Builtins: Legacy built-in functions for atomic memory access.
     Cilk Plus Builtins: Built-in functions for the Cilk Plus language 
extension.
     Integer Overflow Builtins: Built-in functions to perform 
arithmetics and arithmetic overflow checking.
     Object Size Checking: Built-in functions for limited buffer 
overflow checking.
     Other Builtins: Other built-in functions.
     Pointer Bounds Checker builtins: Built-in functions for Pointer 
Bounds Checker.
     Target Builtins: Built-in functions specific to particular targets.
     x86 specific memory model extensions for transactional memory: x86 
memory models.

Data types
     __int128: 128-bit integers---__int128.
     Complex: Data types for complex numbers.
     Decimal Float: Decimal Floating Types.
     Empty Structures: Structures with no members.
     Fixed-Point: Fixed-Point Types.
     Floating Types: Additional Floating Types.
     Half-Precision: Half-Precision Floating Point.
     Long Long: Double-word integers---long long int.

Expression values
     Alignment: Inquiring about the alignment of a type or variable.
     Binary constants: Binary constants using the ‘0b’ prefix.
     Character Escapes: ‘\e’ stands for the character <ESC>.
     Escaped Newlines: Slightly looser rules for escaped newlines.
     Hex Floats: Hexadecimal floating-point constants.
     Labels as Values: Getting pointers to labels, and computed gotos.
     Offsetof: Special syntax for implementing offsetof.
     Pointer Arith: Arithmetic on void-pointers and function pointers.
     Return Address: Getting the return or frame address of a function.
     Typeof: typeof: referring to the type of an expression.

Naming
     Alternate Keywords: __const__, __asm__, etc., for header files.
     Dollar Signs: Dollar sign is allowed in identifiers.
     Function Names: Printable strings which are the name of the current 
function.
     Local Labels: Labels local to a block.
     Named Address Spaces: Named address spaces.
     Unnamed Fields: Unnamed struct/union fields within structs/unions.

Specifiers
      Inline: Defining inline functions (as fast as macros).
      Thread-Local: Per-thread variables.
      Volatiles: What constitutes an access to a volatile object.

Miscellaneous
     C++ Comments: C++ comments are recognized.
     Case Ranges: `case 1 ... 9' and such.
     Constructing Calls: Dispatching a call to another function.
     Function Prototypes: Prototype declarations and old-style definitions.
     Incomplete Enums: enum foo;, with details to follow.
     Mixed Declarations: Mixing declarations and code.
     Nested Functions: As in Algol and Pascal, lexical scoping of functions.
     Pragmas: Pragmas accepted by GCC.
     Target Format Checks: Format checks specific to particular targets.
     Using Assembly Language with C: Instructions and extensions for 
interfacing C with assembler.
     Variadic Macros: Macros with a variable number of arguments.

dw