[Emacs-diffs] /srv/bzr/emacs/trunk r104838: cc-mode.texi (Guessing the Style): New page.

[Alan Mackenzie]

------------------------------------------------------------
revno: 104838
committer: Alan Mackenzie <address@hidden>
branch nick: trunk
timestamp: Fri 2011-07-01 09:42:55 +0000
message:
  cc-mode.texi (Guessing the Style): New page.
  (Styles): Add a short introduction to above.
modified:
  doc/misc/ChangeLog
  doc/misc/cc-mode.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2011-06-28 10:18:02 +0000
+++ b/doc/misc/ChangeLog        2011-07-01 09:42:55 +0000
@@ -1,3 +1,8 @@
+2011-07-01  Alan Mackenzie  <address@hidden>
+
+       * cc-mode.texi (Guessing the Style): New page.
+       (Styles): Add a short introduction to above.
+
 2011-06-28  Deniz Dogan  <address@hidden>
 
        * rcirc.texi (Configuration): Bug-fix:

=== modified file 'doc/misc/cc-mode.texi'
--- a/doc/misc/cc-mode.texi     2011-02-19 19:40:59 +0000
+++ b/doc/misc/cc-mode.texi     2011-07-01 09:42:55 +0000
@@ -287,10 +287,11 @@
 
 Styles
 
-* Built-in Styles::
-* Choosing a Style::
-* Adding Styles::
-* File Styles::
+* Built-in Styles::             
+* Choosing a Style::            
+* Adding Styles::               
+* Guessing the Style::          
+* File Styles::                 
 
 Customizing Auto-newlines
 
@@ -2511,14 +2512,18 @@
 for any particular style, and pretty easily start editing new or
 existing code using these styles.
 
+As an alternative to writing a style definition yourself, you can have
address@hidden @dfn{guess} (at least part of) your style by looking at an
+already formatted piece of your code, @ref{Guessing the Style}.
+
 @menu
-* Built-in Styles::
-* Choosing a Style::
-* Adding Styles::
-* File Styles::
+* Built-in Styles::             
+* Choosing a Style::            
+* Adding Styles::               
+* Guessing the Style::          
+* File Styles::                 
 @end menu
 
-
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 @node    Built-in Styles, Choosing a Style, Styles, Styles
 @comment node-name, next, previous, up
@@ -2653,9 +2658,8 @@
 string.
 @end defvar
 
-
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
address@hidden    Adding Styles, File Styles, Choosing a Style, Styles
address@hidden    Adding Styles, Guessing the Style, Choosing a Style, Styles
 @comment node-name, next, previous, up
 @subsection Adding and Amending Styles
 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -2742,9 +2746,131 @@
 should not be changed directly; use @code{c-add-style} instead.
 @end defvar
 
-
address@hidden !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
address@hidden    File Styles,  , Adding Styles, Styles
address@hidden !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
address@hidden    Guessing the Style, File Styles, Adding Styles, Styles
address@hidden node-name, next, previous, up
address@hidden Guessing the Style
address@hidden !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Instead of specifying a style, you can get @ccmode{} to @dfn{guess}
+your style by examining an already formatted code buffer.  @ccmode{}
+then determines the ''most frequent'' offset (@pxref{c-offsets-alist})
+for each of the syntactic symbols (@pxref{Indentation Engine Basics})
+encountered in the buffer, and the ''most frequent'' value of
+c-basic-offset (@pxref{Customizing Indentation}), then merges the
+current style with these ''guesses'' to form a new style.  This
+combined style is known as the @dfn{guessed style}.
+
+To do this, call @code{c-guess} (or one of the other 5 guessing
+commands) on your sample buffer.  The analysis of your code may take
+some time.
+
+You can then set the guessed style in any @ccmode{} buffer with
address@hidden  You can display the style with
address@hidden, and preserve it by copying it into your
address@hidden for future use, preferably after editing it.
+
address@hidden @asis
address@hidden @kbd{M-x c-guess-no-install}
address@hidden @kbd{M-x c-guess-buffer-no-install}
address@hidden @kbd{M-x c-guess-region-no-install}
address@hidden c-guess-no-install
address@hidden c-guess-buffer-no-install
address@hidden c-guess-region-no-install
address@hidden guess-no-install (c-)
address@hidden guess-buffer-no-install (c-)
address@hidden guess-region-no-install (c-)
+These commands analyze a part of the current buffer and guess the
+style from it.
+
+The part of the buffer examined is either the region
+(@code{c-guess-region-no-install}), the entire buffer
+(@code{c-guess-buffer-no-install}), or the first
address@hidden bytes (@code{c-guess-no-install}).
+
+Each of these commands can be given an optional prefix argument.  This
+instructs @ccmode{} to combine the new guesses with the current
+guesses before forming the guessed style.
address@hidden table
+
address@hidden @asis
address@hidden @kbd{M-x c-guess}
address@hidden @kbd{M-x c-guess-buffer}
address@hidden @kbd{M-x c-guess-region}
address@hidden c-guess
address@hidden c-guess-buffer
address@hidden c-guess-region
address@hidden guess (c-)
address@hidden guess-buffer (c-)
address@hidden guess-region (c-)
+These commands analyze a part of the current buffer, guess the style
+from it, then install the guessed style on the buffer.  The guessed
+style is given a name based on the buffer's absolute file name, and
+you can then set this style on any @ccmode{} buffer with @kbd{C-c .}.
+
+The part of the buffer examined is either the region
+(@code{c-guess-region}), the entire buffer (@code{c-guess-buffer}), or
+the first @code{c-guess-region-max} bytes (@code{c-guess}).
+
+Each of these commands can be given an optional prefix argument.  This
+instructs @ccmode{} to combine the new guesses with the current
+guesses before forming the guessed style.
address@hidden table
+
address@hidden c-guess-region-max
address@hidden guess-region-max (c-)
+This variable, default 50000, is the size in bytes of the buffer
+portion examined by c-guess and c-guess-no-install.  If set to
address@hidden, the entire buffer is examined.
address@hidden defopt
+
address@hidden c-guess-offset-threshold
address@hidden guess-offset-threshold (c-)
+This variable, default 10, is the maximum offset, either outwards or
+inwards, which will be taken into account by the analysis process.
+Any offset bigger than this will be ignored.  For no limit, set this
+variable to a large number.
address@hidden defopt
+
address@hidden @asis
address@hidden  @kbd{M-x c-guess-install}
address@hidden c-guess-install
address@hidden guess-install (c-)
+
+Set the current buffer's style to the guessed style.  This prompts you
+to enter an optional new style name to give to the guessed style.  By
+default, this name is based on the buffer's absolute file name.  You
+can then use this style like any other.
+
address@hidden  @kbd{M-x c-guess-view}
address@hidden c-guess-view
address@hidden guess-view (c-)
+Display the most recently guessed style in a temporary buffer.  This
+display is in the form of a @code{c-add-style} form (@pxref{Adding
+Styles}) which can be easily copied to your @file{.emacs}.  You will
+probably want to edit it first.
+
+The display of the guessed style contains these elements:
+
address@hidden @asis
address@hidden Placeholder Name
+You should replace this with a style name of your own.
address@hidden Parent Style
+The style current when the guessing began, from which the guessed
+style inherits (@pxref{Config Basics}) the settings which weren't
+guessed.
address@hidden Guessed Offsets
+These are the core result of the guessing process.  Each of them is
+marked by a comment.
address@hidden Inherited Offsets
+These are syntactic offsets which have been taken over from the parent
+style.  To avoid possible future conflicts, you should remove either
+these offsets or the parent style name.
address@hidden table
address@hidden table
+
address@hidden !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
address@hidden    File Styles,  , Guessing the Style, Styles
 @comment node-name, next, previous, up
 @subsection File Styles
 @cindex styles, file local