* Info Catalog Prev auctex: Indenting Up auctex: Editing

auctex: Filling

 
 2.10 Filling
 ============
 
 Filling deals with the insertion of line breaks to prevent lines from
 becoming wider than what is specified in 'fill-column'.  The linebreaks
 will be inserted automatically if 'auto-fill-mode' is enabled.  In this
 case the source is not only filled but also indented automatically as
 you write it.
 
    'auto-fill-mode' can be enabled for AUCTeX by calling
 'turn-on-auto-fill' in one of the hooks AUCTeX is running.  SeeModes
 and Hooks.  As an example, if you want to enable 'auto-fill-mode' in
 'LaTeX-mode', put the following into your init file:
 
      (add-hook 'LaTeX-mode-hook 'turn-on-auto-fill)
 
    You can manually fill explicitely marked regions, paragraphs,
 environments, complete sections, or the whole buffer.  (Note that manual
 filling in AUCTeX will indent the start of the region to be filled in
 contrast to many other Emacs modes.)
 
    There are some syntactical constructs which are handled specially
 with regard to filling.  These are so-called code comments and paragraph
 commands.
 
    Code comments are comments preceded by code or text in the same line.
 Upon filling a region, code comments themselves will not get filled.
 Filling is done from the start of the region to the line with the code
 comment and continues after it.  In order to prevent overfull lines in
 the source code, a linebreak will be inserted before the last
 non-comment word by default.  This can be changed by customizing
 'LaTeX-fill-break-before-code-comments'.  If you have overfull lines
 with code comments you can fill those explicitely by calling
 'LaTeX-fill-paragraph' or pressing 'M-q' with the cursor positioned on
 them.  This will add linebreaks in the comment and indent subsequent
 comment lines to the column of the comment in the first line of the code
 comment.  In this special case 'M-q' only acts on the current line and
 not on the whole paragraph.
 
    Lines with '\par' are treated similarly to code comments, i.e.
 '\par' will be treated as paragraph boundary which should not be
 followed by other code or text.  But it is not treated as a real
 paragraph boundary like an empty line where filling a paragraph would
 stop.
 
    Paragraph commands like '\section' or '\noindent' (the list of
 commands is defined by 'LaTeX-paragraph-commands') are often to be
 placed in their own line(s).  This means they should not be consecuted
 with any preceding or following adjacent lines of text.  AUCTeX will
 prevent this from happening if you do not put any text except another
 macro after the end of the last brace of the respective macro.  If there
 is other text after the macro, AUCTeX regards this as a sign that the
 macro is part of the following paragraph.
 
    Here are some examples:
 
      \begin{quote}
        text text text text
 
      \begin{quote}\label{foo}
        text text text text
 
    If you press 'M-q' on the first line in both examples, nothing will
 change.  But if you write
 
      \begin{quote} text
        text text text text
 
    and press 'M-q', you will get
 
      \begin{quote} text text text text text
 
    Besides code comments and paragraph commands, another speciality of
 filling in AUCTeX involves commented lines.  You should be aware that
 these comments are treated as islands in the rest of the LaTeX code if
 syntactic filling is enabled.  This means, for example, if you try to
 fill an environment with 'LaTeX-fill-environment' and have the cursor
 placed on a commented line which does not have a surrounding environment
 inside the comment, AUCTeX will report an error.
 
    The relevant commands and variables with regard to filling are:
 
 'C-c C-q C-p'
      'LaTeX-fill-paragraph' will fill and indent the current paragraph.
 
 'M-q'
      Alias for 'C-c C-q C-p'
 
 'C-c C-q C-e'
      'LaTeX-fill-environment' will fill and indent the current
      environment.  This may e.g.  be the 'document' environment, in
      which case the entire document will be formatted.
 
 'C-c C-q C-s'
      'LaTeX-fill-section' will fill and indent the current logical
      sectional unit.
 
 'C-c C-q C-r'
      'LaTeX-fill-region' will fill and indent the current region.
 
  -- User Option: LaTeX-fill-break-at-separators
      List of separators before or after which respectively linebreaks
      will be inserted if they do not fit into one line.  The separators
      can be curly braces, brackets, switches for inline math ('$', '\(',
      '\)') and switches for display math ('\[', '\]').  Such formatting
      can be useful to make macros and math more visible or to prevent
      overfull lines in the LaTeX source in case a package for displaying
      formatted TeX output inside the Emacs buffer, like preview-latex,
      is used.
 
  -- User Option: LaTeX-fill-break-before-code-comments
      Code comments are comments preceded by some other text in the same
      line.  When a paragraph containing such a comment is to be filled,
      the comment start will be seen as a border after which no line
      breaks will be inserted in the same line.  If the option
      'LaTeX-fill-break-before-code-comments' is enabled (which is the
      default) and the comment does not fit into the line, a line break
      will be inserted before the last non-comment word to minimize the
      chance that the line becomes overfull.
 
  -- User Option: LaTeX-fill-excluded-macros
      A list of macro names (without leading backslash) for whose
      arguments filling should be disabled.  Typically, you will want to
      add macros here which have long, multi-line arguments.  An example
      is '\pgfplotstabletypeset' from the pgfplotstable package which is
      used as shown in the following listing:
 
      \pgfplotstabletypeset[skip first n=4]{%
        XYZ Format,
        Version 1.234
        Date 2010-09-01
        @author Mustermann
        A B C
        1 2 3
        4 5 6
      }
* Info Catalog Prev auctex: Indenting Up auctex: Editing