27

When editing org files, I find it extremely convenient how you can hide and display headlines and their content by just hitting TAB on the headline.

For instance, consider the following buffer

* Headline 1
Some text here.

* Headline 2
Some more text here.

If I place the point on the first *, and hit TAB, I will get the following:

* Headline 1...
* Headline 2
Some more text here.

Is there a way to achieve that with LaTeX sections?
i.e., how can I hide and display the contents of a LaTeX section/chapter/etc, while keeping the title visible? I'm using AucTeX for LaTeX-mode but I haven't found anything that seems to fill this role.

12

NB: much of this text came from an answer to a question that turned out to be a duplicate of this question. Some of the material is sufficiently different that it seemed worthwhile to add it to this question.

Outline mode and the AUCTeX folding facilities are two different beasts that are meant to do broadly the same thing: hide and show selected parts of the buffer.

outline-minor-mode

A key element to recognize when using outline-minor-mode is that it's got a different prefix key than outline-mode (ie, the major mode) -- precisely to avoid key conflicts with motion keys, etc. That prefix defaults to the awkward-to-type C-c @ (although you can change that by customizing outline-minor-mode-prefix). All the keybindings listed on this node of the manual should still work, but with the twist that you replace the major mode prefix of C-c with the minor mode prefix of C-c @. Hence, C-c @ C-c runs hide-entry, C-c @ C-e runs show-entry, and so on.

To use these facilities, you need to enable outline-minor-mode. The simplest way is with a mode hook:

(add-hook 'LaTeX-mode-hook #'outline-minor-mode)

changing outline-minor-mode-prefix

It should be a simple thing to change outline-minor-mode-prefix (it used to be back in the day). But it's not. What fun!

The docstring now gives a cryptic note that:

Prefix key to use for Outline commands in Outline minor mode. The value of this variable is checked as part of loading Outline mode. After that, changing the prefix key requires manipulating keymaps.

Yes, very helpful. Oddly enough, even customize doesn't set this variable in time to avoid "manipulating keymaps" (despite it being defined with defcustom in the source code). The practical work-around: set this variable in your init file before you load outline or anything else built off of it (eg,org-mode).

You might, for example, want the prefix to be C-o (which means you're losing open-line, but you can rebind that if you really want it). Putting the following early in your init file will do the trick:

(global-unset-key "\C-o")
(setq outline-minor-mode-prefix "\C-o")

Now, you should be able to access all of the outline mode functionality using the C-o prefix -- C-o C-c to call hide-entry, C-o C-e to call show-entry, and so on.

adding new outline headings

As an added bonus, you can also customize which outline headers can get folded, and to what levels. I, for example, like to be able to make "fake" section headers to hide away text that doesn't have a true LaTeX header, but logically is kept at the same level of the document. With the following code, you can use:

%section{a fake section}

Blah blah blah blah blah, LaTeX doesn't recognize me as a section...

\section{a real section}

Blah blah blah blah blah, LaTeX treats me as a real section

And you will be able to manipulate the fake section just like any other one, but LaTeX will ignore it when you compile the document:

;; extra outline headers 
(setq TeX-outline-extra
      '(("%chapter" 1)
        ("%section" 2)
        ("%subsection" 3)
        ("%subsubsection" 4)
        ("%paragraph" 5)))

;; add font locking to the headers
(font-lock-add-keywords
 'latex-mode
 '(("^%\\(chapter\\|\\(sub\\|subsub\\)?section\\|paragraph\\)"
    0 'font-lock-keyword-face t)
   ("^%chapter{\\(.*\\)}"       1 'font-latex-sectioning-1-face t)
   ("^%section{\\(.*\\)}"       1 'font-latex-sectioning-2-face t)
   ("^%subsection{\\(.*\\)}"    1 'font-latex-sectioning-3-face t)
   ("^%subsubsection{\\(.*\\)}" 1 'font-latex-sectioning-4-face t)
   ("^%paragraph{\\(.*\\)}"     1 'font-latex-sectioning-5-face t)))

outline-magic

outline-magic extends the outline modes to use org-mode-like hiding/showing with the magic tab key. In other words, you can probably add this in to your workflow and make your LaTeX documents behave more like org documents. (I don't use it myself, so can't comment on functionality.)

AUCTeX folding facilities

AUCTeX's folding facilities work on environments and what they (confusingly) call macros, rather than sections. To use this functionality, you'll need to enable it with TeX-fold-mode.

For example, the itemize environment, unfolded, might look like:

\begin{itemize}
  \item An item
  \item Another item
\end{itemize}

Calling TeX-fold-env (default: C-c C-o C-e) inside the environment folds it up to look like:

[itemize]

Placing the cursor somewhere inside [itemize] will temporarily expand it again while you edit it, and then will fold back down to [itemize] when you move the cursor out of the environment.

By a "macro," AUCTeX means things like \footnote{...}. Hence, calling TeX-fold-macro (default: C-c C-o C-m) when inside \footnote{This is a footnote} will fold it up to [f]; it will expand and contract in analogous fashion to what happens with environments.

You can use both outline-minor-mode and AUCTeX's folding facilities together in the same document: they do different things on different parts of it.

  • 1
    Just for the record, the name "macro" isn't an AUCTeX oddity, it's the name for these "things" in *TeX. It is the same concept as macros in any macro-expanding language, including elisp macros. About your last sentence, I would add that it mainly works because they use different keybindings. There are attempts to unify both ( github.com/mlf176f2/fold-dwim-org ) but they aren't entirely functional yet. – T. Verron Nov 5 '14 at 8:50
  • Also worth noting is that LaTeX sections are much like org headings, and LaTeX environments are much like org blocks. Org folds both with TAB, and this could probably be made to work for AUCTeX. Folding macros with TAB would be annoying in my opinion (it would be akin to folding inline markdown specifications...). – T. Verron Nov 5 '14 at 8:54
  • And last point, outline-minor-mode should work out-of-the-box with AUCTeX: gnu.org/software/auctex/manual/auctex/Outline.html . That is, until you start defining new heading macros in LaTeX... – T. Verron Nov 5 '14 at 8:56
24

What you want is called folding, and there are 2 ways you can do that.

Outline-minor-mode

This is a built-in minor mode that is exactly what org-mode uses to hide and display it's headlines. You can make sure it's always turned on in latex-mode with

(add-hook 'LaTeX-mode-hook #'outline-minor-mode)

The keybinds it defines are a little hard to use, so you might want to change some of them.

C-c @ C-a       show-all
C-c @ C-c       hide-entry
C-c @ C-d       hide-subtree
C-c @ C-e       show-entry
C-c @ TAB       show-children
C-c @ C-k       show-branches
C-c @ C-l       hide-leaves
C-c @ C-o       hide-other
C-c @ C-q       hide-sublevels
C-c @ C-s       show-subtree
C-c @ C-t       hide-body

Latex-extra

latex-extra is a minor mode available on Melpa and Melpa-stable. You can install it with M-x package-install RET latex-extra and turn it on with

(add-hook 'LaTeX-mode-hook #'latex-extra-mode)

It adds a series of conveniences to latex-mode, one of them is section folding. latex-extra also uses outline-minor-mode behind the scenes, but the advantage is that it emulates org-mode's behaviour more closely (albeit not identically).

From its readme:

Similar to how org-mode hides and displays of subtrees, if you hit TAB on a section header latex-extra will hide the contents of that section for you. Hitting tab twice will expand it again.
This will not interfere with whatever with other keybinds you have set for TAB, such as yasnippet or auto-completion.

Shift-TAB will do the same for the entire buffer.

Of course, the same goes for chapters, subsections, etc.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.