> 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
