branch: elpa/adoc-mode
commit ff382b94de9f9c80be896297dc5fc7a3373527e9
Author: Bozhidar Batsov <bozhi...@batsov.dev>
Commit: Bozhidar Batsov <bozhi...@batsov.dev>
Improve the configuration docs
---
README.adoc | 59 ++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 40 insertions(+), 19 deletions(-)
diff --git a/README.adoc b/README.adoc
index 71fb83755d..5dc1aca01c 100644
--- a/README.adoc
+++ b/README.adoc
@@ -86,24 +86,30 @@ or if you're into `use-package`:
=== General
-* According to an old AsciiDoc manual, `.txt` is the standard file extension of
- AsciiDoc files. Add the following to your initialization file to open all
- `.txt` files with adoc-mode as major mode automatically: `(add-to-list
- 'auto-mode-alist (cons "\\.txt\\'" 'adoc-mode))`.
- More recent conventions for AsciiDoc file extensions include `.adoc` and
- `.asciidoc`, these are associated with `adoc-mode` automatically.
-
-* If your default face is a fixed pitch (monospace) face, but in AsciiDoc
- files you liked to have normal text with a variable pitch face,
- `buffer-face-mode` is for you: `(add-hook 'adoc-mode-hook (lambda()
- (buffer-face-mode t)))`
-
-* Settings regarding native fontification of source blocks:
-** Native fontification of source blocks can be switched off by setting
`adoc-fontify-code-blocks-natively` to `nil`.
-** Native fontification of lengthy code blocks can cause performance problems.
If the value of `adoc-fontify-code-blocks-natively` is an integer only those
code blocks are fontified natively whose length is less or equal to that value.
-** To avoid performance problems with code block beginnings that do not have a
matching end yet the scanning for the code block end is delimited by
`adoc-font-lock-extend-after-change-max`.
-** All programming languages `XYZ` that have an Emacs major mode `XYZ-mode`
and use `font-lock` are automatically supported. Some other languages not
fitting into that name scheme are supported through the alist
`adoc-code-lang-modes`. You can add your own languages and modes there if they
work based on `font-lock` and are not automatically supported.
-** The fall-back language mode is `prog-mode` without any fontification. You
can set your own default by `adoc-fontify-code-block-default-mode`.
+According to an old AsciiDoc manual, `.txt` is the standard file extension of
+AsciiDoc files. Add the following to your initialization file to open all
`.txt`
+files with adoc-mode as major mode automatically:
+
+[source,emacs-lisp]
+----
+(add-to-list 'auto-mode-alist (cons "\\.txt\\'" 'adoc-mode))
+----
+
+Modern conventions for AsciiDoc file extensions favor `.adoc` and
+`.asciidoc` and they are associated with `adoc-mode` automatically.
+
+You can see a list of all configuration options offered by `adoc-mode` by
running the following command - kbd:[M-x] `customize-group adoc`.
+
+=== Native Syntax Highlighting of Source Code Blocks
+
+Out-of-the-box `adoc-mode` will try to apply native font-locking to source
code blocks (e.g. the same font-locking that `ruby-mode` would use for Ruby
code blocks).
+This can be tweaked by several configuration options:
+
+* Native fontification of source blocks can be switched off by setting
`adoc-fontify-code-blocks-natively` to `nil`.
+* Native fontification of lengthy code blocks can cause performance problems.
If the value of `adoc-fontify-code-blocks-natively` is an integer only those
code blocks are fontified natively whose length is less or equal to that value.
+* To avoid performance problems with code block beginnings that do not have a
matching end yet the scanning for the code block end is delimited by
`adoc-font-lock-extend-after-change-max`.
+* All programming languages `XYZ` that have an Emacs major mode `XYZ-mode` and
use `font-lock` are automatically supported. Some other languages not fitting
into that name scheme are supported through the alist `adoc-code-lang-modes`.
You can add your own languages and modes there if they work based on
`font-lock` and are not automatically supported.
+* The fall-back language mode is `prog-mode` without any fontification. You
can set your own default by `adoc-fontify-code-block-default-mode`.
=== Syntax Highlighting Customization
@@ -126,7 +132,7 @@ kbd:[M-x] `describe-face`
One possible solution to change the look of a face is to use the
built-in `use-package` feature `:custom-face`.
-Example
+Example:
[source,emacs-lisp]
----
@@ -139,6 +145,21 @@ Example
Of course, this is only one way to do it. Emacs has a few ways to
customize faces. Simply, pick the one you prefer.
+If your default face is a fixed pitch (monospace) face, but in AsciiDoc files
+you liked to have normal text with a variable pitch face, `buffer-face-mode`
+is one good options for you:
+
+[source,emacs-lisp]
+----
+(defun my-buffer-face-mode-variable ()
+ "Set font to a variable width (proportional) fonts in current buffer."
+ (interactive)
+ (setq buffer-face-mode-face '(:family "DejaVu Sans" :height 100 :width
semi-condensed))
+ (buffer-face-mode))
+
+(add-hook 'adoc-mode-hook (lambda() (buffer-face-mode t)))
+----
+
== Roadmap
Here are some features that we're considering to add in the future:
