branch: elpa/adoc-mode
commit 00c59c8d952c92c547cb18ba57dff0f673866670
Author: TobiasZawada <i...@tn-home.de>
Commit: GitHub <nore...@github.com>
[Fix #7] Convert readme to AsciiDoc (#10)
---
README.md => README.asciidoc | 100 ++++++++++++++++++++++++++-----------------
1 file changed, 60 insertions(+), 40 deletions(-)
diff --git a/README.md b/README.asciidoc
similarity index 71%
rename from README.md
rename to README.asciidoc
index 06cb9a59ea..4c74386201 100644
--- a/README.md
+++ b/README.asciidoc
@@ -1,13 +1,25 @@
-[](https://github.com/emacsorphanage/adoc-mode/actions?query=workflow%3ACI)
-[![MELPA][melpa-badge]][melpa-package]
-[![MELPA Stable][melpa-stable-badge]][melpa-stable-package]
-[![License GPL 3][badge-license]][copying]
+:experimental:
+:highlighter: coderay
+:melpa-badge: http://melpa.org/packages/adoc-mode-badge.svg
+:melpa-stable-badge: http://stable.melpa.org/packages/adoc-mode-badge.svg
+:melpa-package: http://melpa.org/#/adoc-mode
+:melpa-stable-package: http://stable.melpa.org/#/adoc-mode
+:melpa: http://melpa.org
+:melpa-stable: http://stable.melpa.org
+:license-badge: https://img.shields.io/badge/license-GPL_3-green.svg
+:copying: http://www.gnu.org/copyleft/gpl.html
-# adoc-mode
-## Introduction
+image:https://github.com/emacsorphanage/adoc-mode/workflows/CI/badge.svg[link="https://github.com/emacsorphanage/adoc-mode/actions?query=workflow%3ACI";]
+image:{melpa-badge}[link="{melpa-package}"]
+image:{melpa-stable-badge}[link="{melpa-stable-package}"]
+image:{license-badge}[link="{copying}"]
-[AsciiDoc](https://asciidoc.org/) is a text document format for
+= `adoc-mode`
+
+== Introduction
+
+https://asciidoc.org/[AsciiDoc] is a text document format for
writing short documents, articles, books and UNIX man pages. AsciiDoc files
can be translated to HTML and DocBook markups.
@@ -17,7 +29,7 @@ final output. What must be bold is bold, what must be italic
is italic etc.
Meta characters are naturally still visible, but in a faint way, so they can
be easily ignored.
-## Features
+== Features
Here are some of the main features of `adoc-mode`:
@@ -28,17 +40,17 @@ Here are some of the main features of `adoc-mode`:
- goto anchor defining a given id, default reading from xref at point
- support for outline (however only with the one-line title style)
-### Demo
+=== Demo
The highlighting emphasizes on how the output will look like. _All_
characters are visible, however meta characters are displayed in a faint way.
-
+image:http://dl.dropbox.com/u/75789984/adoc-mode.png[alt=screenshot]
-## Installation
+== Installation
`adoc-mode` is available on the community-maintained
-[MELPA Stable][] and [MELPA][] repos.
+link:{melpa-stable-package}[MELPA Stable] and link:{melpa-package}[MELPA]
repos.
Using MELPA Stable is recommended as it has the latest stable version.
MELPA has a development snapshot for users who don't mind breakage but
@@ -46,25 +58,30 @@ don't want to run `adoc-mode` from a git checkout.
You can install `adoc-mode` using the following command:
-<kbd>M-x package-install [RET] adoc-mode [RET]</kbd>
+kbd:[M-x] `package-install` kbd:[RET] `adoc-mode` kbd:[RET]
If the installation doesn't work try refreshing the package list:
-<kbd>M-x package-refresh-contents</kbd>
+kbd:[M-x] `package-refresh-contents`
Alternative, you can add something like this to your Emacs config:
-```emacs-lisp
+[source,emacs-lisp]
+----
(unless (package-installed-p 'adoc-mode)
(package-refresh-contents)
(package-install 'adoc-mode))
+----
+
+or if you're into use-package
-;; or if you're into use-package
+[source,emacs-lisp]
+----
(use-package adoc-mode
:ensure t)
-```
+----
-## Configuration
+== Configuration
* 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
@@ -78,7 +95,7 @@ Alternative, you can add something like this to your Emacs
config:
`buffer-face-mode` is for you: `(add-hook 'adoc-mode-hook (lambda()
(buffer-face-mode t)))`
-### Coming features
+=== Coming features
The next features I plan to implement
@@ -86,9 +103,9 @@ The next features I plan to implement
- Outline support also for two line titles
- Correctly highlighting backslash escapes
-## Hacking
+== Hacking
-adoc-mode uses [Eldev](https://github.com/doublep/eldev) for development, so
+adoc-mode uses https://github.com/doublep/eldev[Eldev] for development, so
you should install the tool first.
The easiest and "purest" way to run adoc-mode is to execute:
@@ -107,19 +124,21 @@ you use for editing:
- Generate autoloads file (that's done automatically when installing
via `package.el` but you'll have to do it manually in this case):
-``` shellsession
+[source,shellsession]
+----
$ eldev build :autoloads
-```
+----
- Add to your `.emacs`:
-``` emacs-lisp
+[source,emacs-lisp]
+----
;; load adoc-mode from its source code
(add-to-list 'load-path "~/projects/adoc-mode")
(load "adoc-mode-autoloads" t t)
-```
+----
-### Changing the code
+=== Changing the code
It's perfectly fine to load adoc-mode from `package.el` and then to start
making
experiments by changing existing code and adding new code.
@@ -134,34 +153,35 @@ can open an Emacs Lisp REPL with `M-x ielm`.
You can also quickly evaluate some Emacs Lisp code in the minibuffer with
`M-:`.
-### Running the tests
+=== Running the tests
Run all tests with:
- $ eldev test
+[source,shellsession]
+----
+$ eldev test
+----
NOTE: Tests may not run correctly inside Emacs' `shell-mode` buffers. Running
them in a terminal is recommended.
You can also check for compliance with a variety of coding standards in batch
mode (including docstrings):
- $ eldev lint
+[source,shellsession]
+----
+$ eldev lint
+----
To check for byte-compilation warnings you can just compile the project with
Eldev:
- $ eldev compile
+[source,shellsession]
+----
+$ eldev compile
+----
-## License
+== License
Copyright © 2010-2013 Florian Kaufmann
-Distributed under the GNU General Public License; type <kbd>C-h C-c</kbd> to
view it.
+Distributed under the link:{copying}[GNU General Public License]; type
kbd:[C-h] kbd:[C-c] to view it.
-[melpa-badge]: http://melpa.org/packages/adoc-mode-badge.svg
-[melpa-stable-badge]: http://stable.melpa.org/packages/adoc-mode-badge.svg
-[melpa-package]: http://melpa.org/#/adoc-mode
-[melpa-stable-package]: http://stable.melpa.org/#/adoc-mode
-[melpa]: http://melpa.org
-[melpa stable]: http://stable.melpa.org
-[badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg
-[copying]: http://www.gnu.org/copyleft/gpl.html
![https://github.com/emacsorphanage/adoc-mode/workflows/CI/badge.svg[link="https://github.com/emacsorphanage/adoc-mode/actions?query=workflow%3ACI"](https://github.com/emacsorphanage/adoc-mode/workflows/CI/badge.svg[link="https://github.com/emacsorphanage/adoc-mode/actions?query=workflow%3ACI"){kind=link}
