Readme: Add preamble and Examples

1 files changed, 42 insertions, 1 deletions

diff --git a/README.adoc b/README.adoc
index d0aceba..1bcadcd 100644
--- a/README.adoc
+++ b/README.adoc
@@ -15,7 +15,48 @@ image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://ww
 endif::env-github[]
 
 
-TODO
+This project is an http://asciidoctor.org/[Asciidoctor] extension providing implicit (automatic) reference text (label) for inter-document cross references.
+
+
+== Examples
+
+When you define a cross reference to another document “other.adoc” _without_ a label, e.g.:
+
+----
+xref:other#[]
+----
+
+Asciidoctor converts it into a plain link with the target document’s path as a text:
+
+// GitHub doesn't render Example block as a box.
+[subs="+macros"]
+----
+link:other.html[other.html]
+----
+
+but this extensions converts it into:
+
+[subs="+macros"]
+----
+link:other.html[Other Document]
+----
+
+where “Other Document” is a *title* of the _other.adoc_.
+
+Similarly with cross reference to a section in another document, e.g.:
+
+----
+xref:other#sec1[]
+----
+
+Asciidoctor converts it in the same way as above, but this extensions converts it into:
+
+[subs="+macros"]
+----
+link:other.html#sec1[The First Section]
+----
+
+where “The First Section” is *title* of the section with id _sec1_ in _other.adoc_.
 
 
 == Installation