[spec/declaration.dd] Add grammar headings (#3213)

Add link to DeclDef under Declaration.
Add Grammar heading and subheadings. This helps break up a big block of
grammar text for easier navigation.

Inline *VarDeclaratorIdentifier* and *ExpInitializer* as they are
singletons and not referenced anywhere else. It doesn't appear in
grammar.dd.

Author: ntrel

spec/declaration.dd

@@ -4,6 +4,8 @@ $(SPEC_S Declarations,
 
 $(HEADERNAV_TOC)
 
+$(H2 $(LNAME2 grammar, Grammar))
+
 $(GRAMMAR
 $(GNAME Declaration):
     $(GLINK2 function, FuncDeclaration)
@@ -18,6 +20,11 @@ $(GNAME Declaration):
     $(GLINK2 version, StaticAssert)
 )
 
+$(P See also $(GLINK2 module, DeclDef).
+)
+
+$(H3 $(LNAME2 aggregates, Aggregates))
+
 $(GRAMMAR
 $(GNAME AggregateDeclaration):
     $(GLINK2 class, ClassDeclaration)
@@ -26,6 +33,8 @@ $(GNAME AggregateDeclaration):
     $(GLINK2 struct, UnionDeclaration)
 )
 
+$(H3 $(LNAME2 variable-declarations, Variable Declarations))
+
 $(GRAMMAR
 $(GNAME VarDeclarations):
     $(GLINK StorageClasses)$(OPT) $(GLINK2 type, BasicType) $(GLINK Declarators) $(D ;)
@@ -43,10 +52,7 @@ $(GNAME DeclaratorIdentifierList):
     $(GLINK DeclaratorIdentifier)
     $(GLINK DeclaratorIdentifier) $(D ,) $(GSELF DeclaratorIdentifierList)
 
-$(GNAME DeclaratorIdentifier):
-    $(GLINK VarDeclaratorIdentifier)
-
-$(GNAME VarDeclaratorIdentifier):
+$(GNAME DeclaratorIdentifier):$(LEGACY_LNAME2 VarDeclaratorIdentifier)
     $(GLINK_LEX Identifier)
     $(GLINK_LEX Identifier) $(GLINK2 template, TemplateParameters)$(OPT) $(D =) $(GLINK Initializer)
 
@@ -57,6 +63,8 @@ $(GNAME VarDeclarator):
     $(GLINK2 type, TypeSuffixes)$(OPT) $(GLINK_LEX Identifier)
 )
 
+$(H3 $(LNAME2 storage-classes, Storage Classes))
+
 $(GRAMMAR
 $(GNAME StorageClasses):
     $(GLINK StorageClass)
@@ -87,19 +95,18 @@ $(MULTICOLS 5,     $(GLINK2 attribute, LinkageAttribute)
     $(D ref))
 )
 
+$(H3 $(LNAME2 initializers, Initializers))
+
 $(GRAMMAR
 $(GNAME Initializer):
     $(GLINK VoidInitializer)
     $(GLINK NonVoidInitializer)
 
 $(GNAME NonVoidInitializer):
-    $(GLINK ExpInitializer)
+    $(GLINK2 expression, AssignExpression)$(LEGACY_LNAME2 ExpInitializer)
     $(GLINK ArrayInitializer)
     $(GLINK StructInitializer)
 
-$(GNAME ExpInitializer):
-    $(GLINK2 expression, AssignExpression)
-
 $(GNAME ArrayInitializer):
     $(D [) $(GLINK ArrayMemberInitializations)$(OPT) $(D ])