[nongnu] elpa/adoc-mode ff382b94de 181/199: Improve the configuration docs

[ELPA Syncer]

branch: elpa/adoc-mode
commit ff382b94de9f9c80be896297dc5fc7a3373527e9
Author: Bozhidar Batsov <bozhidar@batsov.dev>
Commit: Bozhidar Batsov <bozhidar@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: