SublimeText/LaTeXTools — pull request #433 by btstream (2014-09-19 05:04:16+00:00)
Title: Add Better code folding

# Better code folding

By default, sublime text use "%(fold)" and "%...(end)" marks and "tabs" to identify code folding sections in latex source files.

This feature supplies a better code folding behavior. It can recognize "%(fold)" and "%...(end)" mark pairs, if you forget to use this mark, it all OK too. If the marks of "%(fold)" and "%...(end)" are not used, it will auto pair the code folding sections to the next same level's "section start mark" or "parents' start marks". For example, for the code bellow:

```latex
\section{hello} % (fold)
hello world, hello world.
hello world, hello world.
hello world, hello world.
hello world, hello world.

% section hello (end)

\section{hello too} %(fold)
hello world, too
hello world, too
hello world, too
hello world, too
hello world, too

\section{hello again?}
hello again? I am tired.
```
wil be folded to
```latex
\section{hello} % (fold)...
% section hello (end)

\section{hello too} %(fold)...
\section{hello again?}...
```

## shortcut for code folding

Better code folding can ONLY be used by *shortcuts*!
By default, all of the shortcut bellow can be used.

"Alt+Super+[", "Super+k, Super+1", "Super+k, Super+2", "Super+k, Super+3",
... "Super+k, Super+7" are now can be used in latex source file even there are no "tab" used in source files.

And there are three *special* shortcuts, which are:
"Super+k, Super+o": unfold current foding. I don't know why set this command to the shortcut of "Alt+Super+]" does not work for me, so I set it to "Super+k, Super+o" as alternative.

"Super+k, Super+9": fold whole buffer to "Table of Content", which is called "fold to toc".

"Super+k, Super+0": fold whole buffer to TOC but keep the current editing section unfold.

## About fold_to_toc command

Example of fold to toc(Super+k, Super+9) is like this:

If source cod is :

```latex

\chapter{chapter1}

Content before section of hello.

\section{hello} % (fold)
hello world, hello world.
hello world, hello world.
hello world, hello world.
hello world, hello world.

% section hello (end)

\section{hello too} %(fold)
hello world, too
hello world, too
hello world, too

\subsection{hell subsection}

hello world, too
hello world, too

\section{hello again?}
hello again? I am tired.
```
will be fold to
```latex
\chapter{chapter1}...
\section{hello} % (fold)...
\section{hello too} %(fold)...
\subsection{hell subsection}...
\section{hello again?}...
```
if "Super+k, Super+0" is triggered, it will be folded to

```latex
\chapter{chapter1}...
\section{hello} % (fold)...
\section{hello too} %(fold)...
\subsection{hell subsection}

hello world, too
hello world, too

\section{hello again?}...
```

it can be seen that the in the fold to toc command, fold marks of "%(fold)" and "%...(end)" are ignored.

### "fold_toc_depth" options
There is a "fold_toc_depth" option, which controls the depth of fold_to_toc command fold the buffer.
When "fold_toc_depth" is not set, 4 will be used as default value. If option is set to
```json
"fold_toc_depth": 2
```
in LaTeXtools config files, and the code like
```latex
\chapter{chapter1}

Content before section of hello.

\section{hello} % (fold)
hello world, hello world.
hello world, hello world.
hello world, hello world.
hello world, hello world.

% section hello (end)

\section{hello too} %(fold)
hello world, too
hello world, too
hello world, too

\subsection{hell subsection}

hello world, too
hello world, too

\section{hello again?}
hello again? I am tired.
```
will be folded to
```latex
\chapter{chapter1}...
\section{hello} % (fold)...
\section{hello too} %(fold)...
\section{hello again?}...
```
which means \subsection, \subsubsection and others will be folded into \subsection

## About extreme fold

These is another fold mode called extreme fold. When extreme fold is used, all fold marks of "%(fold)" and "%...(end)" will be ignored. extreme fold is used only in "fold to toc" by default, but it can be set to other scopes by change the "extreme_fold" option in "laTeXTools.sublime-settings". Detailed description can be found in "laTeXTools.sublime-settings" file.