Merge a9df2fc4ca into 038f4cb0c9

asciidoc.md

@@ -3,12 +3,13 @@ name: AsciiDoc
 contributors:
     - ["Ryan Mavilia", "http://unoriginality.rocks/"]
     - ["Abel Salgado Romero", "https://twitter.com/abelsromero"]
+    - ["Mykolas Bamberg", "https://github.com/MykBamberg"]
 filename: asciidoc.adoc
 ---
 
 AsciiDoc is a markup language similar to Markdown and it can be used for anything from books to blogs. Created in 2002 by Stuart Rackham the language is simple but it allows for a great amount of customization.
 
-Document Header
+**Document Header**
 
 Headers are optional and can't contain blank lines. It must be offset from content by at least one blank line.
 
@@ -48,18 +49,49 @@ v1.0, 2016-01-13
 This article about chips is going to be fun.
 ```
 
-Paragraphs
+**Comments**
+
+```
+// AsciiDoc offers line comments, beginning with a double slash
+
+////
+and block comments enclosed
+by four-slash delimiters
+which can span multiple lines
+////
+```
+
+**Built-in Document Attributes**
+
+```
+= Document Title
+// Document attributes change different behaviors of the document
+// These are commonly used to
+:imagesdir: ./images
+:iconsdir: ./icons
+// set resource directories,
+:toc:
+// enable an automatic table of contents,
+:notitle:
+// hide the document title,
+:sectnums:
+// automatically number document sections,
+:source-highlighter: pygments
+// set a source code highlighter
+```
+
+**Paragraphs**
 
 ```
 You don't need anything special for paragraphs.
 
 Add a blank line between paragraphs to separate them.
 
-To create a line blank add a +
-and you will receive a line break!
+To create a line break within a paragraph add a +
+to the end of the line and you will receive a line break!
 ```
 
-Formatting Text
+**Formatting Text**
 
 ```
 _underscore creates italics_
@@ -67,9 +99,11 @@ _underscore creates italics_
 *_combine for extra fun_*
 `use ticks to signify monospace`
 `*bolded monospace*`
+"`double curved quotes`"
+'`single curved quotes`'
 ```
 
-Section Titles
+**Section Titles**
 
 ```
 = Level 0 (may only be used in document's header)
@@ -83,9 +117,9 @@ Section Titles
 ===== Level 4 <h5>
 ```
 
-Lists
+**Lists**
 
-To create a bulleted list use asterisks.
+To create an unordered list use asterisks.
 
 ```
 * foo
@@ -93,7 +127,7 @@ To create a bulleted list use asterisks.
 * baz
 ```
 
-To create a numbered list use periods.
+To create an ordered list use periods.
 
 ```
 . item 1
@@ -117,15 +151,94 @@ You can nest lists by adding extra asterisks or periods up to five times.
 ..... foo 5
 ```
 
+**Source Code Blocks**
+
+```
+[source,c]
+----
+#include <stdio.h>
+
+int main(void) {
+    printf("AsciiDoc source code blocks are rendered"
+           "in a fixed-width font with syntax highlighting\n");
+}
+----
+```
+
+**Images**
+
+```
+image::image.png[]
+
+.Figure caption
+image::image.png["Alt text",128,128]
+```
+
+**Tables**
+
+```
+// The cols attribute specifies the number and relative width of each
+// column. In this case there are two columns with the first having
+// Twice the width of the latter.
+[cols="2,1"]
+|===
+|column 1, row 1
+|column 2, row 1
+
+|column 1, row 2
+|column 2, row 2
+|===
+```
+
+**Hyperlinks**
+
+```
+https://learnxinyminutes.com/
+
+<https://learnxinyminutes.com/>
+
+https://learnxinyminutes.com/[]
+
+https://learnxinyminutes.com/[Learn X in Y minutes]
+```
+
+**Text replacements**
+
+Some character sequences are replaced by appropriate Unicode characters
+
+```
+* Copyright: (C)
+* Registered: (R)
+* Trademark: (TM)
+* Em dash: --
+* Ellipsis: ...
+* Arrows: -> => <- <=
+```
+
+**Includes**
+
+Include another file's content in the document
+
+```
+include::other_asciidoc_file.adoc[]
+```
+
+**Horizontal Rule**
+
+```
+'''
+```
+
 ## Further Reading
 
-There are two tools to process AsciiDoc documents:
+**Converters**
 
-1. [AsciiDoc](http://asciidoc.org/): original Python implementation available in the main Linux distributions. Stable and currently in maintenance mode.
-2. [Asciidoctor](http://asciidoctor.org/): alternative Ruby implementation, usable also from Java and JavaScript. Under active development, it aims to extend the AsciiDoc syntax with new features and output formats.
+1. [Asciidoctor](http://asciidoctor.org/): Actively developed reference implementation in Ruby
+2. [AsciiDoc.py](http://asciidoc.org/): Legacy implementation supporting an older syntax
 
-Following links are related to `Asciidoctor` implementation:
+**Helpful Resources**
 
 * [Markdown - AsciiDoc syntax comparison](http://asciidoctor.org/docs/user-manual/#comparison-by-example): side-by-side comparison of common Markdown and AsciiDoc elements.
 * [Getting started](http://asciidoctor.org/docs/#get-started-with-asciidoctor): installation and quick start guides to render simple documents.
 * [Asciidoctor User Manual](http://asciidoctor.org/docs/user-manual/): complete single-document manual with syntax reference, examples, rendering tools, amongst others.
+* [AsciiDoc Syntax Quick Reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/)