CC Mode manual: Better document lines starting with a label

* doc/misc/cc-mode.texi (Syntactic Analysis): Document analysis
of lines starting with labels, and their non-use as anchor
positions.

(cherry picked from commit 6c1c3120b98652de149ee9d8c241cd3636755171)

diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi
index 2166462eca63e26994ddd8339ba78f5e307a70f1..e1dc777ebc13732827baf777264870bd48684c88 100644 (file)
--- a/doc/misc/cc-mode.texi
+++ b/doc/misc/cc-mode.texi
@@ -4177,6 +4177,52 @@ and you can see that the syntactic context contains two syntactic
 elements.  Notice that the first element, @samp{(comment-intro)}, has no
 anchor position.
 
+@cindex label line
+There are special ways of handling lines beginning with labels.  Such
+a line gets a syntactic element beginning with @code{label} or
+@code{substatement-label} rather than the element(s) it would have
+had, were there no label on the line.
+
+Also, a line beginning with a label (or a comment) is never the anchor
+position of a later line.  Instead, that anchor position is the latest
+line at the same level of nesting before the labeled line without a
+leading label or comment.  If there is no such line, the latest line
+containing an enclosing opening brace or parenthesis, which doesn't
+start with a label or comment, provides the anchor postion.  In this
+case extra syntactic element(s) with syntactic symbol
+@code{defun-block-intro}, @code{statement-block-intro}, or some other
+``-intro'' symbol are inserted into the syntactic context to allow the
+correct indentation of the later line using that anchor position.
+
+These conventions allow a style to indent labels specially, perhaps
+giving them greater visibility by indenting them less than the
+surrounding code.
+
+For example, in the following pike fragment:
+
+@example
+ 1: int a()
+ 2: @{
+ 3:   foo: @{
+ 4:     bar: if (t)
+ 5:         x;
+ 6:       y;
+ 7:     @}
+ 8:     y;
+ 9: @}
+@end example
+
+@noindent
+Line 4 gets the syntactic context
+
+@example
+((defun-block-intro 9) (label 9))
+@end example
+
+@noindent
+where position 9 is the brace on line 2, the latest line before line 4
+without a label.
+
 
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node    Syntactic Symbols