Commit 1d443f45 authored by Sarah White's avatar Sarah White Committed by Dan Allen
Browse files

resolves #13 migrate AsciiDoc syntax quick reference (PR #14)



* migrate AsciiDoc syntax quick reference
* revise commentary and improve examples
* use ~ to denote autowidth column
* add collapsible attribute to enable the extension to backport the collapsible block
* rewrite intro
* change URI to URL
* add note that empty block attribute list can be used to separate lists
* clarify that unordered list marker can be changed using style
* remove note about font-based and interactive checklists
* remove note about sectlinks and sectanchors
* include the term "literal monospace"
* add example of possessive monospace
* rename and reorder sections
* add custom inline role example
Co-authored-by: Dan Allen's avatarDan Allen <dan.j.allen@gmail.com>
parent dc1c3d28
......@@ -52,14 +52,14 @@ However, Asciidoctor doesn't process and replace Unicode escape sequences at thi
****
TIP: AsciiDoc also provides built-in attributes for representing some common symbols.
These attributes and their corresponding output are listed in xref:attributes:ref-character-replacement.adoc[].
These attributes and their corresponding output are listed in xref:attributes:character-replacement-reference.adoc[].
== Default replacements substitution
<<table-replace>> lists the specific blocks and inline elements the replacements substitution step applies to automatically.
.Blocks and inline elements subject to the replacements substitution
[#table-replace%autowidth,cols=",^"]
[#table-replace%autowidth,cols="~,^~"]
|===
|Blocks and elements |Substitution step applied by default
......
......@@ -15,7 +15,7 @@ The special characters substitution step searches for three characters (`<`, `>`
<<table-special>> lists the specific blocks and inline elements the special characters substitution step applies to automatically.
.Blocks and inline elements subject to the special characters substitution
[#table-special%autowidth,cols=",^"]
[#table-special%autowidth,cols="~,^~"]
|===
|Blocks and elements |Substitution step applied by default
......
[cols="2,^1,^1,^1,2"]
[%autowidth,cols="~,^~,^~,^~,~"]
.Textual symbol replacements
|===
|Name |Syntax |Unicode Replacement |Rendered |Notes
......
......@@ -116,6 +116,17 @@ The cell's text is italicized and duplicated in column 3, row 3 and columns 1 an
|===
// end::clone[]
// in qr
// tag::b-spec[]
[cols="e,m,^,>s",width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===
// end::b-spec[]
== THESE ARE THE LEGACY EXAMPLES THAT MAY NO LONGER BE IN USE
// tag::3dup[]
......@@ -196,15 +207,7 @@ The cell's text is italicized and duplicated in column 3, row 3 and columns 1 an
// tag::b-spec[]
[cols="e,m,^,>s", width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===
// end::b-spec[]
// tag::cell-src[]
|===
......
////
Examples for table data format section
////
// all tags are in qr
// tag::csv[]
[%header,format=csv]
|===
......
......@@ -20,6 +20,22 @@
|=== // <1>
// end::base-co[]
// in qr
// tag::b-col-h-co[]
[%header,cols=2*] <.>
|===
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
// end::b-col-h-co[]
// in qr
// tag::b-col-h[]
[%header,cols=2*]
|===
......@@ -85,63 +101,44 @@
|===
// end::indv[]
// in qr
// tag::b-base-h-co[]
.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3 // <1>
// <2>
|Column 1, Header Row |Column 2, Header Row <.>
<.>
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
// end::b-base-h-co[]
// in qr
// tag::b-base-h[]
.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3
|Column 1, Header Row |Column 2, Header Row
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
// end::b-base-h[]
// tag::b-col-h-co[]
[%header,cols=2*] // <1>
|===
|Name of Column 1
|Name of Column 2
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 1, row 2
|Cell in column 2, row 2
|===
// end::b-col-h-co[]
// in qr
// tag::b-col-indv-co[]
[cols="1,1,2", options="header"] // <1>
.Applications
[cols="1,1,2"] // <.>
|===
|Name
|Category
|Description
|Name |Category |Description
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
|Mozilla Firefox is an open source web browser.
It's designed for standards compliance,
performance, portability.
......@@ -153,16 +150,14 @@ Empowers developers to easily create real, automated tests.
// end::b-col-indv-co[]
// tag::b-col-indv[]
[cols="1,1,2", options="header"]
.Applications
[cols="1,1,2"]
|===
|Name
|Category
|Description
|Name |Category |Description
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
|Mozilla Firefox is an open source web browser.
It's designed for standards compliance,
performance, portability.
......@@ -173,12 +168,13 @@ Empowers developers to easily create real, automated tests.
|===
// end::b-col-indv[]
// in qr
// tag::b-col-a[]
[cols="2,2,5a"]
|===
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
|Mozilla Firefox is an open source web browser.
It's designed for:
......
......@@ -4,31 +4,34 @@ This journey begins one late Monday afternoon in Antwerp.
Our team desperately needs coffee, but none of us dare open the office door.
// end::para[]
// used in qr
// FIXME this should be in the blocks module
// tag::b-para[]
Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.
To begin a new paragraph, separate it by at least one blank line.
Paragraphs don't require special markup in AsciiDoc.
A paragraph is defined by one or more consecutive lines of text.
Newlines within a paragraph are not displayed.
Leave at least one blank line to begin a new paragraph.
// end::b-para[]
//used in qr
// tag::hb-all[]
Rubies are red, +
Topazes are blue.
Roses are red, +
violets are blue.
[%hardbreaks]
Ruby is red.
A ruby is red.
Java is black.
// end::hb-all[]
// tag::hb[]
Rubies are red, +
Topazes are blue.
Roses are red, +
violets are blue.
// end::hb[]
// tag::hb-p[]
[%hardbreaks]
Ruby is red.
A ruby is red.
Java is black.
// end::hb-p[]
......@@ -41,8 +44,8 @@ This results in a visible line break (e.g., `<br>`) between the lines.
= Line Break Doc Title
:hardbreaks-option:
Rubies are red,
Topazes are blue.
Roses are red,
violets are blue.
// end::hb-attr[]
// tag::lead[]
......@@ -55,6 +58,13 @@ This is the ultimate paragraph.
This text will be styled as a lead paragraph (i.e., larger font).
// end::b-lead[]
// tag::qr-lead[]
[.lead]
This text will be styled as a lead paragraph (i.e., larger font).
This paragraph will not be.
// end::qr-lead[]
// tag::b-i[]
_To tame_ the wild wolpertingers we needed to build a *charm*.
But **u**ltimate victory could only be won if we divined the
......@@ -67,6 +77,7 @@ But **u**ltimate victory could only be won if we divined the
*_true name_* of the __war__lock.
// end::b-i-n[]
// used in qr
// tag::b-bold-italic-mono[]
bold *constrained* & **un**constrained
......@@ -83,6 +94,29 @@ monospace italic `_constrained_` & ``__un__``constrained
monospace bold italic `*_constrained_*` & ``**__un__**``constrained
// end::b-bold-italic-mono[]
// tag::constrained-bold-italic-mono[]
It has *strong* significance to me.
I _cannot_ stress this enough.
Type `OK` to accept.
That *_really_* has to go.
Can't pick one? Let's use them `*_all_*`.
// end::constrained-bold-italic-mono[]
// tag::unconstrained-bold-italic-mono[]
**C**reate, **R**ead, **U**pdate, and **D**elete (CRUD)
That's fan__freakin__tastic!
Don't pass generic ``Object``s to methods that accept ``String``s!
It was Beatle**__mania__**!
// end::unconstrained-bold-italic-mono[]
// used in qr
// tag::monospace-vs-codespan[]
`{cpp}` is valid syntax in the programming language by the same name.
......@@ -107,6 +141,7 @@ Kizmet shrugged.
but these could be normal groceries for werewolves.`"
// end::c-quote[]
// used in qr
// tag::b-c-quote[]
"`double curved quotes`"
......@@ -114,6 +149,8 @@ but these could be normal groceries for werewolves.`"
Olaf's desk was a mess.
A ``std::vector```'s size is the number of items it contains.
All of the werewolves`' desks were a mess.
Olaf had been with the company since the `'00s.
......@@ -133,6 +170,7 @@ of a shopping list, but I don't think the local bodega sells
E=mc^2^,`" Lazarus replied.
// end::sub-sup[]
//used in qr
// tag::b-sub-sup[]
^super^script phrase
......@@ -147,13 +185,15 @@ but also pure _genius!_
// end::mono[]
// tag::literal-mono[]
You can reference the value of a document attribute using the syntax `+{name}+`, where `name` is the attribute name.
You can reference the value of a document attribute using
the syntax `+{name}+`, where `name` is the attribute name.
// end::literal-mono[]
// tag::literal-mono-with-plus[]
`pass:[++]` is the increment operator in C.
// end::literal-mono-with-plus[]
// used in qr
// tag::b-mono-code[]
Reference code like `types` or `methods` inline.
......@@ -180,17 +220,18 @@ Do werewolves believe in [.small]#small print#?
[big]##O##nce upon an infinite loop.
// end::css[]
// tag::css-all[]
Werewolves are allergic to #cassia cinnamon#.
// used in qr
// tag::qr-all[]
Werewolves are allergic to #cinnamon#.
Did the werewolves read the [.small]#small print#?
##Mark##up refers to text that contains formatting ##mark##s.
Where did all the [.underline]#cores# run off to?
Where did all the [.underline]#cores# go?
We need [.line-through]#ten# make that twenty VMs.
We need [.line-through]#ten# twenty VMs.
[.big]##O##nce upon an infinite loop.
// end::css-all[]
A [.myrole]#custom role# must be fulfilled by the theme.
// end::qr-all[]
// tag::css-custom[]
Type the word [.userinput]#asciidoctor# into the search bar.
......
// in qr
// tag::b-nonselect[]
----
line of code // <1>
......@@ -11,6 +12,7 @@ line of code <!--4-->
<4> A callout behind a line comment for XML or SGML languages like HTML.
// end::b-nonselect[]
// in qr
// tag::source-xml[]
[source,xml]
----
......@@ -35,6 +37,7 @@ end
<3> Response block
// end::basic[]
// in qr
// tag::b-src[]
[source,ruby]
----
......
......@@ -18,42 +18,45 @@ The content inside is displayed as <pre> text.
----
// end::block[]
// tag::b-base[]
// in qr
// tag::qr-listing[]
.Gemfile.lock
----
GEM
remote: https://rubygems.org/
specs:
asciidoctor (1.5.7)
asciidoctor (2.0.12)
PLATFORMS
ruby
DEPENDENCIES
asciidoctor (~> 1.5.7)
asciidoctor (~> 2.0.12)
----
// end::b-base[]
// end::qr-listing[]
// in qr
// tag::subs[]
:version: 1.5.7
:release-version: pass:a[{release-version}]
[source,xml,subs="verbatim,attributes"]
[source,xml,subs="attributes+"]
----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>{version}</version>
<version>{release-version}</version>
</dependency>
----
// end::subs[]
// in qr
// tag::subs-out[]
[source,xml]
[source,xml,subs="attributes+"]
----
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>1.5.7</version>
<version>{release-version}</version>
</dependency>
----
// end::subs-out[]
......@@ -2,28 +2,32 @@
~/secure/vault/defops
// end::indent[]
// tag::b-imp[]
// in qr
// tag::qr-para[]
A normal paragraph.
A paragraph offset by at least one space becomes a literal paragraph.
All lines in a literal paragraph must be adjacent.
A literal paragraph.
One or more consecutive lines indented by at least one space.
A literal paragraph is displayed as preformatted text.
The text is shown in a fixed-width font.
The text is shown in a fixed-width (typically monospace) font.
The lines are preformatted (i.e., as formatted in the source).
Spaces and newlines,
like the ones in this sentence,
are preserved.
// end::qr-para[]
Another normal paragraph.
// end::b-imp[]
// in qr
// tag::b-imp-code[]
Indent the line one space to insert a code snippet
Normal line.
Indent line by one space to create a literal line.
Normal line.
// end::b-imp-code[]
// tag::style[]
[literal]
error: The requested operation returned error: 1954 Forbidden search
error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom
Would you like to try again? y/n
// end::style[]
......@@ -42,10 +46,12 @@ Computer: Calculating ...
....
// end::block[]
//in qr
// tag::b-block[]
....
error: The requested operation returned error: 1954 Forbidden search
error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom
Would you like to try again? y/n
....
// end::b-block[]
//in qr
// tag::src-base[]
[source,ruby]
----
......@@ -40,6 +41,7 @@ end
This is normal content.
// end::src-para-co[]
// in qr
// tag::src-para[]
[source,xml]
<meta name="viewport"
......@@ -70,6 +72,7 @@ public void setAttributes(Attributes attributes) {
require 'sinatra'
// end::override[]
// in qr
// tag::src-inc[]
[source,ruby]
----
......@@ -77,6 +80,7 @@ require 'sinatra'
----
// end::src-inc[]
// in qr
// tag::rel[]
:sourcedir: src/main/java
......@@ -86,13 +90,15 @@ require 'sinatra'
----
// end::rel[]
// in qr
// tag::ind[]
[source,ruby,indent=0]
[source,ruby]
----
\include::lib/document.rb[lines=5..10]
\include::lib/app.rb[tag=main,indent=0]
----
// end::ind[]
// in qr
// tag::fence[]
```ruby
require 'sinatra'
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment