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
......@@ -30,11 +30,11 @@ Keep in mind that the header is optional.
----
= Document Title
Doc Writer <doc.writer@asciidoc.org>
v1.0, 2013-01-01
v1.0, 2022-01-01
----
// end::complex[]
// used in qr
// tag::b-complex[]
* Every list item has at least one paragraph of content,
which may be wrapped, even using a hanging indent.
......@@ -46,20 +46,15 @@ list continuation:: a plus sign (`{plus}`) on a line by itself
* A literal paragraph does not require a list continuation.
$ gem install asciidoctor
$ cd projects/my-book
* AsciiDoc lists may contain any complex content.
+
[cols="2", options="header"]
|===
|Application
|Language
|AsciiDoc
|Python
|Column 1, Header Row |Column 2, Header Row
|Asciidoctor
|Ruby
|Column 1, Row 1
|Column 2, Row 1
|===
// end::b-complex[]
......
////
Included in:
- user-manual: Description list
- quick-ref
.Description list
[source]
----
......@@ -34,17 +30,13 @@ Hard drive:: Permanent storage for operating system and/or user files.
RAM:: Temporarily stores information the CPU uses during operation.
// end::base-horz[]
// tag::b-base[]
first term:: definition of first term
second term:: definition of second term
// end::b-base[]
// tag::b-base-multi[]
first term::
definition of first term
second term::
definition of second term
// end::b-base-multi[]
// tag::qr-base[]
First term:: The description can be placed on the same line
as the term.
Second term::
Description of the second term.
The description can also start on its own line.
// end::qr-base[]
// tag::base-mix[]
Dairy::
......@@ -71,6 +63,7 @@ Produce::
* Bananas
// end::base-mix-alt[]
// in qr
// tag::3-mix[]
Operating Systems::
Linux:::
......@@ -92,9 +85,11 @@ Cloud Providers::
. Rackspace
// end::3-mix[]
// in qr
// tag::qa[]
[qanda]
What is Asciidoctor?::
An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
What is the answer?::
This is the answer.
Have you seen my duck?:: No.
// end::qa[]
////
Included in:
- user-manual: Ordered list
- quick-ref
- writers guide
////
// tag::b-base[]
. Step 1
. Step 2
. Step 3
// end::b-base[]
// tag::base[]
. Protons
. Electrons
......@@ -51,6 +38,7 @@ Included in:
. Neutrons
// end::reversed[]
// in qr
// tag::nest[]
. Step 1
. Step 2
......@@ -59,13 +47,14 @@ Included in:
. Step 3
// end::nest[]
// in qr
// tag::max[]
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
. Level 1 list item
.. Level 2 list item
... Level 3 list item
.... Level 4 list item
..... Level 5 list item
. Level 1 list item
// end::max[]
// tag::num[]
......
////
Included in:
- user-manual: Unordered list
- user-manual: checklist
- quick-ref
- writers guide
////
// tag::qr-base[]
* List item
** Nested list item
*** Nested list item
* List item
** Another nested list item
* List item
// end::qr-base[]
// tag::base[]
* Edgar Allan Poe
......@@ -44,13 +45,14 @@ Included in:
* Untracked file in git repository
// end::nest[]
// in qr
// tag::max[]
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
* Level 1 list item
** Level 2 list item
*** Level 3 list item
**** Level 4 list item
***** Level 5 list item
* Level 1 list item
// end::max[]
// tag::square[]
......
......@@ -115,6 +115,7 @@ include::example$ordered.adoc[tag=mix-alt]
The description list page demonstrates how to xref:description.adoc#three-hybrid[combine all three list types].
[#styles]
== Number styles
For ordered lists, Asciidoctor supports the numeration styles such as lowergreek and decimal-leading-zero.
......
......@@ -93,6 +93,7 @@ A new level is created for each unique marker encountered.
However, it's much more intuitive to follow the convention that the number of asterisks equals the level of nesting.
After all, we're shooting for plain text markup that is readable _as is_.
[#markers]
== Custom markers
Asciidoctor offers numerous bullet styles for lists.
......
// in qr as syntax
// tag::base[]
image::sunset.jpg[]
// end::base[]
// in qr as result
// tag::qr-base[]
image::macros:sunset.jpg[]
// end::qr-base[]
// in qr as syntax
// tag::alt[]
image::sunset.jpg[Sunset]
// end::alt[]
// in qr as result
// tag::qr-alt[]
image::macros:sunset.jpg[Sunset]
// end::qr-alt[]
// tag::attr-co[]
[#img-sunset] <.>
.A mountain sunset <.>
[link=https://www.flickr.com/photos/javh/5448336655] <.>
image::sunset.jpg[Sunset,300,200] <.> <.>
image::sunset.jpg[Sunset,200,100] <.> <.>
// end::attr-co[]
// in qr as syntax
// tag::attr[]
.A mountain sunset
[#img-sunset]
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655]
image::sunset.jpg[Sunset,300,200]
image::sunset.jpg[Sunset,200,100]
// end::attr[]
// in qr as result
// tag::qr-attr[]
.A mountain sunset
[#img-sunset]
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655]
image::macros:sunset.jpg[Sunset,200,100]
// end::qr-attr[]
// in qr as syntax and result
// tag::ab-url[]
image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]
// end::ab-url[]
// in qr as syntax
// tag::inline[]
Click image:play.png[] to get the party started.
Click image:pause.png[title="Pause"] when you need a break.
// end::inline[]
// in qr as result
// tag::qr-inline[]
Click image:macros:play.png[] to get the party started.
Click image:macros:pause.png[title="Pause"] when you need a break.
// end::qr-inline[]
// in qr as syntax
// tag::in-role[]
image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!
image:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!
// end::in-role[]
// in qr as result
// tag::qr-role[]
image:macros:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!
// end::qr-role[]
// tag::role[]
[.right.text-center]
image::tiger.png[Tiger,200,200]
......@@ -51,10 +105,7 @@ image::3/35/Tux.svg[Tux,250,350]
:imagesdir: {imagesdir-old}
// end::base-url[]
// tag::ab-url[]
image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot]
// end::ab-url[]
// in qr as syntax and result
// tag::data[]
= Document Title
:data-uri:
......
////
Included in:
- user-manual: User Interface Macros
- quick-ref
////
// in qr
// tag::button[]
Press the btn:[OK] button when you are finished.
Select a file in the file navigator and click btn:[Open].
// end::button[]
// in qr
// tag::qr-key[]
|===
|Shortcut |Purpose
|kbd:[F11]
|Toggle fullscreen
|kbd:[Ctrl+T]
|Open a new tab
|===
// end::qr-key[]
// tag::key[]
|===
|Shortcut |Purpose
......@@ -34,6 +42,7 @@ Select a file in the file navigator and click btn:[Open].
|===
// end::key[]
// in qr
// tag::menu[]
To save the file, select menu:File[Save].
......
////
Included in:
- user-manual: URL
- quick-ref
////
// tag::base[]
The homepage for the Asciidoctor Project is https://asciidoctor.org.
......@@ -58,42 +52,41 @@ link:protocol.json[Open the JSON file]
link:external.html#livereload[LiveReload]
// end::hash[]
// used in qr
// tag::b-base[]
https://asciidoctor.org - automatic!
https://asciidoctor.org[Asciidoctor]
https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
// end::b-base[]
// tag::bare-email[]
Email us at hello@example.com to say hello.
// end::bare-email[]
// used in qr
// tag::b-scheme[]
devel@discuss.arquillian.org
devel@discuss.example.org
mailto:devel@discuss.arquillian.org[Discuss Arquillian]
mailto:devel@discuss.example.org[Discuss]
mailto:devel-join@discuss.arquillian.org[Subscribe,Subscribe me,I want to join!]
irc://irc.freenode.org/#fedora
mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join!]
// end::b-scheme[]
// used in qr
// tag::b-linkattrs[]
https://discuss.asciidoctor.org[Discuss Asciidoctor,role=external,window=_blank]
https://discuss.asciidoctor.org[Discuss Asciidoctor^]
https://example.org["Google, Yahoo, Bing^",role=teal]
// end::b-linkattrs[]
// used in qr
// tag::b-spaces[]
link:++https://example.org/?q=[a b]++[URL with special characters]
link:https://example.org/?q=%5Ba%20b%5D[URL with special characters]
https://example.org/?q=%5Ba%20b%5D[URL with special characters]
// end::b-spaces[]
// used in qr
// tag::b-windows[]
link:\\server\share\whitepaper.pdf[Whitepaper]
// end::b-windows[]
......@@ -9,7 +9,7 @@ video::video_file.mp4[]
// end::base[]
// tag::attr[]
video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
video::video_file.mp4[width=640,start=60,end=140,opts=autoplay]
// end::attr[]
// tag::caption[]
......
......@@ -32,14 +32,16 @@ Refer to <<document-b.adoc#section-b,Section B>> for more information.
Refer to <<document-b.adoc#,Document B>> for more information.
// end::base-inter-top[]
// used in qr
// tag::b-base[]
See <<paragraphs>> to learn how to write paragraphs.
Learn how to organize the document into <<section-titles,sections>>.
// end::b-base[]
// used in qr
// tag::b-inter[]
Refer to <<document-b.adoc#section-b,Section B>> for more information.
Refer to xref:document-b.adoc#section-b[Section B of Document B] for more information.
See you when you get back from <<document-b#section-b,Section B>>!
If you never return from xref:document-b.adoc[Document B], we'll send help.
// end::b-inter[]
......@@ -13,7 +13,7 @@ It's preceded by a blank line, entered on a line by itself, and then followed by
----
Content in document.
image::sunset.jpg[] <.> <.>
include::example$image.adoc[tag=base] <.> <.>
Content in document
----
......@@ -23,7 +23,7 @@ Type a set of square brackets (`+[]+`) directly after the target to complete the
The result of <<ex-block>> is displayed below.
image::sunset.jpg[]
include::example$image.adoc[tag=base]
You can specify a comma-separated list of optional attributes inside the square brackets or leave them empty.
If you want to specify alt text, enter it inside the square brackets.
......@@ -31,7 +31,7 @@ If you want to specify alt text, enter it inside the square brackets.
.Block image macro with alt text
[source#ex-alt]
----
image::sunset.jpg[Sunset]
include::example$image.adoc[tag=alt]
----
You can also give the image an id, title, set its dimensions and make it a link.
......@@ -80,8 +80,6 @@ Complete the macro with a set of square brackets (`+[]+`).
The result of <<ex-inline>> is displayed below.
Click image:play.png[] to get the party started.
Click image:pause.png[title="Pause"] when you need a break.
include::example$image.adoc[tag=inline]
For inline images, the optional title is displayed as a tooltip.
// tag::dollar[]
$$*Stars*$$ will not be bold.
// end::dollar[]
// tag::in-macro[]
The text pass:[<u>underline me</u>] is underlined.
// end::in-macro[]
......@@ -26,6 +22,7 @@ will appear in a monospace font but without any other
text formatting.
// end::tick[]
// in qr
// tag::plus[]
Text between + characters, such as +/document/{id}+
is not substituted.
......@@ -37,17 +34,11 @@ If you need to reference another {pp} language,
you can write it as `+SQL{pp}+`.
// end::plus[]
// in qr
// tag::backtick-plus[]
Output literal monospace text such as `+{backtick}+`
by enclosing the text in pluses, then in backticks.
Output literal monospace text such as `+{backtick}+` or `+http://localhost:8080+` by enclosing the text in a pair of pluses surrounded by a pair backticks.
// end::backtick-plus[]
// tag::b-tick[]
`Text in {backticks}` renders exactly as entered,
in `monospace`.
The attribute reference is not resolved.
// end::b-tick[]
// tag::sub-in[]
[subs=+macros] <.>
----
......@@ -72,6 +63,7 @@ pass:quotes[But I should contain *bold* text.]
++++
// end::bl[]
// in qr
// tag::b-bl[]
++++
<p>
......
////
Included in:
- user-manual: Sections
- quick-ref
////
// in qr
// tag::base[]
= Document Title (Level 0)
......@@ -68,20 +63,25 @@ Content of nested section
Content of second section
// end::content[]
// in qr
// tag::book[]
= Document Title (Level 0)
== Section Level 1
== Level 1 Section Title
=== Section Level 2
= Level 0 Section Title (Part)
==== Section Level 3
== Level 1 Section Title
===== Section Level 4
=== Level 2 Section Title
====== Section Level 5
==== Level 3 Section Title
= Section Level 0
===== Level 4 Section Title
====== Level 5 Section Title
= Another Level 0 Section Title (Part)
// end::book[]
// tag::b-book[]
......@@ -180,6 +180,7 @@ Unnumbered Section
:sectnumlevels: 2 <.>
// end::sectnuml[]
// in qr
// tag::md[]
# Document Title (Level 0)
......@@ -194,6 +195,7 @@ Unnumbered Section
###### Section Level 5
// end::md[]
//in qr
// tag::b-md[]
[float]
# Document Title (Level 0)
......
......@@ -33,28 +33,6 @@ It won't be italicized.
\{two-semicolons} will appear {two-semicolons}, not resolved as ;;.
// end::slash[]
// tag::b-slash[]
\*Stars* is not rendered as bold text.
The asterisks around the word are preserved.
\{author} is not resolved to the author name.
The curly brackets around the word are preserved.
`A\--Z` connects A to Z in monospace using two dashes.
The dashes are not replaced by an em dash.
\=> is an equal sign followed by a greater than sign.
The two characters are not combined to form a double arrow.
\[[Word]] is not interpreted as an anchor.
The double brackets around the word are preserved.
[\[[Word]]] is not interpreted as a bibliography anchor.
The triple brackets around the word are preserved.
In these cases, the backslash character is automatically removed.
// end::b-slash[]
// tag::subs-in[]
[source,java,subs="verbatim,quotes"] // <.>
----
......
......@@ -4,7 +4,7 @@
Substitution steps or groups can be applied to any block and certain inline elements by setting the `subs` attribute and assigning it a comma-separated list of one or more of the substitution group or step values.
// tag::group[]
[#subs-groups]
`none`:: Substitution group that disables all substitutions.
`normal`:: Substitution group that performs all substitution types except callouts.
......@@ -25,7 +25,6 @@ The output of `replacements` may depend on whether the `specialcharacters` subst
`macros`:: Substitution step that processes inline and block macros.
`post_replacements`:: Substitution step that processes the line break character (`{plus}`).
// end::group[]
== Set the subs attribute on a block
......
......@@ -13,7 +13,7 @@ Attribute references are replaced with their values when they're processed by th
<<table-attributes>> lists the specific blocks and inline elements the attributes substitution step applies to automatically.
.Blocks and inline elements subject to the attributes substitution
[#table-attributes%autowidth,cols=",^"]
[#table-attributes%autowidth,cols="~,^~"]
|===
|Blocks and elements |Substitution step applied by default
......
......@@ -15,7 +15,7 @@ The macros step replaces a macro's content with the appropriate built-in and use
<<table-macros>> lists the specific blocks and inline elements the macros substitution step applies to automatically.
.Blocks and inline elements subject to the macros substitution
[#table-macros%autowidth,cols=",^"]
[#table-macros%autowidth,cols="~,^~"]
|===
|Blocks and elements |Substitution step applied by default
......
......@@ -13,7 +13,7 @@ The line break character, `{plus}`, is replaced when the `post_replacements` sub
<<table-post>> lists the specific blocks and inline elements the post replacements substitution step applies to automatically.
.Blocks and inline elements subject to the post replacements substitution
[#table-post%autowidth,cols=",^"]
[#table-post%autowidth,cols="~,^~"]
|===
|Blocks and elements |Substitution step applied by default
......
......@@ -26,7 +26,7 @@ Happy werewolves are <strong>really</strong> slobbery.
<<table-quotes-html>> shows the HTML source code that is generated by the quotes substitution step.
.HTML source code generated from AsciiDoc formatting syntax
[#table-quotes-html%autowidth,cols=",^,^"]
[#table-quotes-html%autowidth,cols="~,^~,^~"]
|===
|Name |AsciiDoc |HTML
......@@ -64,7 +64,7 @@ Happy werewolves are <strong>really</strong> slobbery.
<<table-quotes>> lists the specific blocks and inline elements the quotes substitution step applies to automatically.
.Blocks and inline elements subject to the quotes substitution
[#table-quotes%autowidth,cols=",^"]
[#table-quotes%autowidth,cols="~,^~"]
|===