This is the mail archive of the
mailing list for the GCC project.
Re: organization of C Extensions in manual
- From: Sandra Loosemore <sandra at codesourcery dot com>
- To: David Wohlferd <dw at LimeGreenSocks dot com>
- Cc: "gcc at gcc dot gnu dot org" <gcc at gcc dot gnu dot org>, "joel dot sherrill at oarcorp dot com >> Joel Sherrill" <joel dot sherrill at oarcorp dot com>, "gary at intrepid dot com >> Gary Funck" <gary at intrepid dot com>, Jeff Law <law at redhat dot com>, Gerald Pfeifer <gerald at pfeifer dot com>, "joseph at codesourcery dot com >> Joseph Myers" <joseph at codesourcery dot com>
- Date: Sun, 18 Jan 2015 09:47:11 -0700
- Subject: Re: organization of C Extensions in manual
- Authentication-results: sourceware.org; auth=none
- References: <54BAF3EE dot 70308 at LimeGreenSocks dot com>
On 01/17/2015 04:44 PM, David Wohlferd wrote:
The page for Extensions to the C Language Family
(https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html) is very long (60+
items) and completely unordered. This makes it hard to find things,
even when you know they are there. I have taken a first shot at
grouping these. Hopefully it can at least serve as the basis for
These section headings were just the general terms that first occurred
to me. Feel free to propose more computer-y terminology. And yes, some
of these topics are a stretch to be included in the sections in which I
have placed them. Still, I believe this is better than what is there now.
Better section names and alternative groupings welcome.
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.
Arrays and Vectors
Designated Inits: Labeling elements of initializers.
I think this one might better be placed in a section on initializers.
Pointers to Arrays: Pointers to arrays with qualifiers work as
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
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.
Zero Length: Zero-length arrays.
Attribute Syntax: Formal syntax for attributes.
Function Attributes: Declaring that functions have no side effects,
or that they can never return.
Inline: Defining inline functions (as fast as macros).
Doesn't seem to belong here.
Label Attributes: Specifying attributes on labels.
Thread-Local: Per-thread variables.
Or this one....
Type Attributes: Specifying attributes of types.
Variable Attributes: Specifying attributes of variables.
Volatiles: What constitutes an access to a volatile object.
Or this one.
__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
Integer Overflow Builtins: Built-in functions to perform
arithmetics and arithmetic overflow checking.
Object Size Checking: Built-in functions for limited buffer
Other Builtins: Other built-in functions.
Pointer Bounds Checker builtins: Built-in functions for Pointer
Target Builtins: Built-in functions specific to particular targets.
x86 specific memory model extensions for transactional memory: x86
This looks OK.
Alignment: Inquiring about the alignment of a type or variable.
Conditionals: Omitting the middle operand of a â?:â expression.
Initializers: Non-constant initializers.
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.
Statement Exprs: Putting statements and declarations inside
Target Format Checks: Format checks specific to particular targets.
Typeof: typeof: referring to the type of an expression.
Variadic Macros: Macros with a variable number of arguments.
Binary constants: Binary constants using the â0bâ prefix.
Character Escapes: â\eâ stands for the character <ESC>.
Compound Literals: Compound literals give structures, unions or
arrays as values.
Escaped Newlines: Slightly looser rules for escaped newlines.
Hex Floats: Hexadecimal floating-point constants.
Labels as Values: Getting pointers to labels, and computed gotos.
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 think the variadic macros section belongs in either of
those groups and should be left separate for now.
__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.
This is good.
Alternate Keywords: __const__, __asm__, etc., for header files.
Cast to Union: Casting to union type from any member of the union.
Dollar Signs: Dollar sign is allowed in identifiers.
Function Names: Printable strings which are the name of the current
Incomplete Enums: enum foo;, with details to follow.
Local Labels: Labels local to a block.
Mixed Declarations: Mixing declarations and code.
Named Address Spaces: Named address spaces.
Unnamed Fields: Unnamed struct/union fields within structs/unions.
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.
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.
Nested Functions: As in Algol and Pascal, lexical scoping of
Pragmas: Pragmas accepted by GCC.
Using Assembly Language with C: Instructions and extensions for
interfacing C with assembler.
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.
In a related question, should we change the "Extensions" page to only
contain these section headers ("Data types", "Builtins" etc) and make
submenus (ie new pages) out of the items under them? From a strict "how
docs should be written" point of view, perhaps we should. But from a
"help people find things" point of view, perhaps not. Opinions?
I'm not much of a UI expert but I'd guess menus longer than a page
(however long that is) that you have to scroll through are not really
considered good design. On the other hand, the naming of things on the
main menu has to make it obvious where to find submenus with more