Homepage: https://github.com/trietlai/helm-odoc
Author: Triet H. Lai
Updated:
Finding headlines in Org documents
helm-odoc.el is built on top of Helm and Org mode. It provides
some convenient functions to search collections of documents
written in Org format for particular headline, tags, and property.
hod-latex.el is an example how to create a simple but practical
help system; where users can search reference documents, notes
interactively for different categories:
- `helm-c-latex-doc': finding headlines or tags in documents.
- `helm-c-latex-doc-hln': finding hierarchical headlines in documents.
- `helm-c-latex-doc-cmd': searching help document for LaTeX commands.
- `helm-c-latex-doc-env': searching help document for LaTeX environments.
- `helm-c-latex-doc-pkg': searching help document for LaTeX packages.
- `helm-c-latex-doc-param': searching help document for LaTeX parameters.
Prerequisite:
============
- Helm: https://github.com/emacs-helm/helm
- Org mode: http://orgmode.org
Installation:
============
* A. Make sure you have Org mode and Helm installed.
* B. If you are only interested in using hod-latex.el to find help
document for LaTeX commands, environments, etc. you can ignore
Section D.
** Basic setup:
1. Download or clone the package from github:
$ git clone https://github.com/trietlai/helm-odoc.git \
~/path/to/helm-odoc
2. Edit HELM_DIR variable in Makefile & run make in this
directory (This step is optional):
$ cd ~/path/to/helm-odoc
$ editor Makefile # edit HELM_DIR variable
$ make
3. Add following lines in your .emacs startup:
(add-to-list 'load-path "~/path/to/helm-odoc")
(require 'hod-latex) ; Automatically load helm-odoc
If you want to enable key bindings and "Doc" menu globally:
(helm-odoc-global-mode 1)
** Advanced setup:
To enable helm-odoc minor mode in certain type of buffers, comment
out the `helm-odoc-global-mode' and put `helm-odoc-mode' in some
major-mode hook, like:
(add-hook 'LaTeX-mode-hook '(lambda () (helm-odoc-mode)))
Alternatively, do use `helm-odoc-global-mode' and create
*exceptions* using the `helm-odoc-dont-activate' local variable,
like this:
(add-hook 'c-mode-common-hook
'(lambda () (setq helm-odoc-dont-activate t)))
* C. Default key bindings in `helm-odoc-mode':
- Prefix key: "\C-c \C-h"
It is defined by `helm-odoc-prefix-key' variable, which you
can customise.
- `helm-c-odoc-hln': " dh"
- `helm-c-odoc-for-tags': " dt"
- `helm-c-odoc-for-property': " dp"
- `helm-c-latex-doc': " ld"
- `helm-c-latex-doc-hln': " lh"
- `helm-c-latex-doc-cmd': " lc"
- `helm-c-latex-doc-env': " le"
- `helm-c-latex-doc-pkg': " lp"
- `helm-c-latex-doc-param': " lm"
* D. If you'd like to extend helm-odoc or making use of your own Org
files for similar purpose:
** Decide what PROPERTIES or TAGS in your Org files that may help
to categorise headlines (i.e. sections or entries) in the
documents. Your commands may use these PROPERTIES and/or TAGS to
filter candidates while constructing the completion buffer. The
'hod-latex.el' is an example shown how that is done for LaTeX
reference documents.
** Add following lines in your .emacs startup:
(add-to-list 'load-path "~/path/to/helm-odoc")
(require 'helm-odoc)
;; Set directories where Org files can be found:
(setq helm-odoc-directories '("dir1" "dir2"))
;; load your code here
Usage
=====
Typical steps you would do when using the hod-latex library:
- Invoke one of hod-latex commands (described later). As a result,
Helm shows two windows. One displays matching candidates for
completion & searching. The other displays the section of
document that corresponds to the current candidate.
- Search candidates in completion buffer by typing the keyword that
you want to find in the mini-buffer. Helm incrementally narrows
down the search while you typing.
- If you move the point to the next (M-n or down-arrow key) or
previous candidate (M-p or up-arrow key) in the completion
buffer, then the document shown in the other window is
synchronised accordingly.
- Press ENTER to select the candidate; hod-latex displays the
document in the view mode. Once finishing with document you can
type "q" to bury the Org buffer and return back to the previous
buffer, which had been shown before you ran the hod-latex
command.
- While the candidate buffer is displayed, you can press C-g to
quit Helm and return back to the previous buffer.
* Find help sections for LaTeX commands:
- Mini-buffer: M-x helm-c-latex-doc-cmd
- Key bindings: \C-c \C-h lc
- Menu: Doc -> LaTeX -> LaTeX commands
* Find help sections for LaTeX environments:
- Mini-buffer: M-x helm-c-latex-doc-env
- Key bindings: \C-c \C-h le
- Menu: Doc -> LaTeX -> LaTeX environments
* Find help sections for LaTeX packages:
- Mini-buffer: M-x helm-c-latex-doc-pkg
- Key bindings: \C-c \C-h lp
- Menu: Doc -> LaTeX -> LaTeX packages
* Find help sections for LaTeX parameters:
- Mini-buffer: M-x helm-c-latex-doc-param
- Key bindings: \C-c \C-h lm
- Menu: Doc -> LaTeX -> LaTeX parameters
* Find help sections matching tags:
- Mini-buffer: M-x helm-c-latex-doc
- Key bindings: \C-c \C-h ld
- Menu: Doc -> LaTeX -> Search for tags
Completion buffer initially includes all known tags. You can
incrementally filter out the tags by typing tag name in the
mini-buffer. You can also combine multiple tags in the query, e.g.:
math+symbol
it means: match all entries, which are marked by both "math" and
"symbol" tags. For advanced usages, please check the "Match
Syntax" section in Org mode user guide.
* Find help sections matching hierarchical headlines:
- Mini-buffer: M-x helm-c-latex-doc-hln
- Key bindings: \C-c \C-h lh
- Menu: Doc -> LaTeX -> Search for headlines
Acknowledgements
================
* LaTeX help documents are converted from:
- LaTeX Reference of Texmaker program
- LaTeX2e info written by Karl Berry