branch: master
commit 9b5d16cdb00b96660313e8551dddbf3402cc6eed
Author: Leo Perrin <leoper...@picarresursix.fr>
Commit: Alexey Veretennikov <alexey.veretenni...@gmail.com>
Added detailed info on the README file.
---
README.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 118 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index 3636994..4930cf8 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,56 @@
-There is a minor mode for Emacs acting like occur but w/o creating a new
window. It just hides all the text excepting lines containing matches. To use
it, add the following to your .emacs file:
+Functionnalities
+================
+
+
+Provides is a minor mode for Emacs acting like occur but without
+creating a new window. It just hides all the text except lines
+containing matches for a given regex. The following functions are
+provided:
+
+ + `loccur` Prompts for a regex and hides all the lines not containing
+ matches. If the given regex is empty, defaults to the current
+ selection and, if the selection is also empty, defaults to the word
+ at point.
+ + `loccur-previous-match` Repeats the last `loccur` search.
+ + `loccur-toggle-highlight` Disables or enables highlighting of the
+ matches.
+
+After `loccur` is ran, hit `RET` to move to the line where the cursor
+is and display everything again.
+
+The good thing about this mode is that you can navigate through the
+buffer easily. In particular, if you bind `(loccur ""
+
+
+Example
+=======
+
+If you run `loccur` on regex `[0-9]+` (finding any decimal number) on
+the following buffer,
+
+``` Lorem ipsum dolor 100 sit amet, consectetur adipisicing elit, sed
+do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+ad minim veniam, quis 20090 nostrud exercitation ullamco laboris nisi
+ut aliquip ex ea commodo consequat. Duis aute irure dolor in
+reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+pariatur. Excepteur sint occaecat 3 cupidatat non proident, sunt in
+culpa qui officia deserunt mollit anim id est laborum.```
+
+we obtain
+
+``` Lorem ipsum dolor 100 sit amet, consectetur adipisicing elit, sed
+ad minim veniam, quis 20090 nostrud exercitation ullamco laboris nisi
+pariatur. Excepteur sint occaecat 3 cupidatat non proident, sunt in
+```
+
+and, if we hit `RET` on the third line of this display, the first
+content is displayed again and the cursor is placed on the 6th line.
+
+
+Suggested settings
+=================
+
+You can add the following to your .emacs file:
```scheme
(require 'loccur)
@@ -10,4 +62,68 @@ There is a minor mode for Emacs acting like occur but w/o
creating a new window.
(define-key global-map [(control shift o)] 'loccur-previous-match)
```
-Now you can point the cursor to the word and press "Ctrl+o" to hide all lines
except those containing this word. Moving cursor to the required line and
pressing "Ctrl+o" again will shows all the text. The good thing about this mode
is what you can navigate through the buffer easily. "Ctrl+Shift+o" will repeat
last search.
+Now you can point the cursor to the word and press `C-o` to hide all
+lines except those containing this word. Moving cursor to the required
+line and pressing `C-o` again or `RET` will shows all the text.
+`C-S-o` will repeat the last search.
+
+
+Quick navigation
+================
+
+
+You can also use `loccur` to efficiently navigate in a buffer. For
+instance, the following function displays only the declaration of all
+the *Python* functions in the current file; making it very easy to
+jump to a particular function.
+
+```scheme
+(defun loccur/list-Python-functions()
+ "Displays only the lines corresponding to a function
+declaration in a Python file."
+ (loccur-no-highlight "^ *def "))
+```
+
+In the same way, the following snippet provides a very useful function
+for whoever uses
+[beamer](http://en.wikipedia.org/wiki/Beamer_%28LaTeX%29): it lists
+all the frame titles to easily jump to a particular one.
+
+
+```scheme
+(defun loccur/list-beamer-frames()
+ "Displays only the lines corresponding to a frame title
+declaration in a beamer LaTeX file."
+ (loccur-no-highlight "\\frametitle"))
+```
+
+When running this command, this buffer
+```
+\begin{frame}
+ \frametitle{First frame}
+
+ <insert fascinating content here>
+\end{frame}
+
+\begin{frame}
+ \frametitle{Then let's talk about this}
+
+ <insert some stunning figure here>
+\end{frame}
+
+\begin{frame}
+ \frametitle{Wrapping up}
+
+ <insert witty and challenging conclusion here>
+\end{frame}
+```
+
+becomes
+```
+
+ \frametitle{First frame}
+ \frametitle{Then let's talk about this}
+ \frametitle{Wrapping up}
+```
+and hitting `RET` will bring back the first buffer and place the
+cursor on the line wanted.
