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
......@@ -6,6 +6,7 @@ asciidoc:
source-language: asciidoc@
xrefstyle: short@
listing-caption: Example@
release-version: '2.0.12'
nav:
- modules/ROOT/nav.adoc
- modules/blocks/nav-basics.adoc
......
This diff is collapsed.
// in qr
// tag::base[]
[caption=""]
.Parts{counter2:index:0}
|===
|Part Id |Description
......
......@@ -8,6 +8,7 @@ This paragraph gets a lot of attention.
This paragraph gets a lot of attention.
// end::block-id-shorthand[]
// used in qr
// tag::anchor[]
// tag::anchor-brackets[]
[[bookmark-a]]Inline anchors make arbitrary content referenceable.
......
* Reference
** xref:ref-intrinsic.adoc[]
** xref:ref-document.adoc[]
** xref:ref-character-replacement.adoc[]
** xref:ROOT:syntax-quick-reference.adoc[]
** xref:intrinsic-attributes-reference.adoc[]
** xref:document-attributes-reference.adoc[]
** xref:character-replacement-reference.adoc[]
** xref:ROOT:glossary.adoc[]
......@@ -51,7 +51,7 @@ The attribute's value can be reassigned or the attribute unset at any subsequent
Many, but not all, document attributes can be set, assigned a value, or unset in the document's body (anywhere below the document header).
When you set an attribute in the body, it's visible from the point it's set until it's unset.
See the xref:ref-document.adoc[] for where in a document each attribute can be set.
See the xref:document-attributes-reference.adoc[] for where in a document each attribute can be set.
Finally, document attributes can also be set, assigned values, and unset via the CLI and API, but these methods don't use the attribute entry syntax.
When an attribute is set from the command line or API, it's defined for the whole document and can't be changed in the document header or body unless `@` is added to the end of the value.
......
= Character Replacement Attributes Reference
[%autowidth,cols="^m,^l,^"]
// tag::table[]
[%autowidth,cols="^~m,^~l,^~"]
|===
|Attribute name |Replacement text |Appearance
......@@ -137,3 +138,4 @@ Instead, use numeric character references (e.g., \&#8364;).
^[4]^ The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.
^[5]^ The word joiner (WJ) is a code point in Unicode that prevents a line break at its position.
// end::table[]
......@@ -39,7 +39,7 @@ When you set an attribute in the body, it's visible from the point it's set unti
== Compliance attributes
[%autowidth,cols="m,^,,^,^,"]
[%autowidth,cols="~m,^~,~,^~,^~,~"]
|===
|Name |Automatically Set |Values |Header Set |Body Set |Notes
......@@ -88,7 +88,7 @@ Useful for storing the output in a source code control system as it prevents spu
[#builtin-attributes-i18n]
== Internationalization and numbering
[%autowidth,cols="m,^,,^,^,"]
[%autowidth,cols="~m,^~,~,^~,^~,~"]
|===
|Name |Automatically Set |Values |Header Set |Body Set |Notes
......
......@@ -7,7 +7,7 @@ Like all document attributes, the value of an intrinsic attributes can be access
Many of these attributes are intended to be read only.
// tag::table[]
[#env-attributes-table%autowidth,cols="m,,m"]
[#env-attributes-table%autowidth,cols="~m,~,~m"]
|===
|Attribute |Description |Example Value
......
......@@ -3,7 +3,7 @@
== Valid built-in names
Built-in attribute names are reserved and can't be re-purposed for user-defined attribute names.
The built-in attribute names are listed in the xref:ref-document.adoc[] and xref:ref-character-replacement.adoc[].
The built-in attribute names are listed in the xref:document-attributes-reference.adoc[] and xref:character-replacement-reference.adoc[].
[#user-defined]
== Valid user-defined names
......@@ -34,7 +34,7 @@ Many built-in attributes have one or more built-in values.
One of these values may be designated as the attribute's default value.
Asciidoctor will fall back to this default value if you set the attribute but leave the value blank.
Additionally, Asciidoctor automatically sets numerous built-in attributes at processing time and assigns them their default values unless you explicitly unset the attribute or assign it another value.
For instance, Asciidoctor automatically sets all of the xref:ref-character-replacement.adoc[character replacement attributes].
For instance, Asciidoctor automatically sets all of the xref:character-replacement-reference.adoc[character replacement attributes].
If you want to use the non-default value of a built-in attribute, you need to set it and assign it an alternative value.
......@@ -64,7 +64,7 @@ For example,
----
<1> The xref:header:metadata.adoc#keywords[built-in keywords attribute] doesn't have a default value, so you must explicitly assign it a value when you set it.
<2> Attributes that accept string values may include <<attribute-reference,references to other attributes>>, e.g, `+{meta-topics}+`.
See the xref:ref-document.adoc[Document Attributes Reference] for information about each built-in attribute's accepted value types.
See the xref:document-attributes-reference.adoc[Document Attributes Reference] for information about each built-in attribute's accepted value types.
You must explicitly assign a value to a built-in attribute when you want to override its default value.
For instance, when a section in a document is assigned the appendix style, that section title will be automatically prefixed with a label and a letter that signifies that section's order, e.g., Appendix A, by default.
......
......@@ -38,7 +38,7 @@ For instance, consider a table with the three built-in option values, `header`,
.Table assigned three options using the shorthand syntax
[source#ex-table-short]
----
[%header%footer%autowidth,cols="2*"]
[%header%footer%autowidth,cols=2*~]
|===
|Cell A1 |Cell B1
......@@ -78,7 +78,7 @@ Instead of using the shorthand notation, <<ex-table-formal>> shows how the value
.Table assigned three options using the formal syntax
[source#ex-table-formal]
----
[cols="2*",options="header,footer,autowidth"]
[cols=2*~,options="header,footer,autowidth"]
|===
|Cell A1 |Cell B1
......
////
Included in:
- user-manual: Admonition
- quick-ref
////
// tag::para-c[]
WARNING: Wolpertingers are known to nest in server racks. // <1> <2>
Enter at your own risk.
......@@ -50,11 +44,9 @@ While werewolves are hardy community members, keep in mind the following dietary
======
// end::bl-nest[]
// in qr
// tag::b-para[]
NOTE: An admonition paragraph draws the reader's attention to
auxiliary information.
Its purpose is determined by the label
at the beginning of the paragraph.
NOTE: An admonition draws attention to auxiliary information.
Here are the other built-in admonition types:
......@@ -67,6 +59,7 @@ WARNING: Watch out for...
CAUTION: Ensure that...
// end::b-para[]
// in qr
// tag::b-bl[]
[NOTE]
====
......
////
Included in:
- user-manual: Example
- quick-ref
////
// in qr
// tag::base[]
.Sample document
====
Here's a sample AsciiDoc document:
[listing]
....
----
= Title of Document
Doc Writer
:toc:
This guide provides...
....
----
The document header is useful, but not required.
====
......
////
Included in:
- user-manual: Open Block
- quick-ref
////
// in qr
// tag::base[]
--
An open block can be an anonymous container,
......@@ -12,6 +6,7 @@ or it can masquerade as any other block.
--
// end::base[]
// in qr
// tag::src[]
[source]
--
......
......@@ -5,6 +5,7 @@ Included in:
- quick-ref
////
// in qr
// tag::bl[]
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
......@@ -21,6 +22,7 @@ and as necessary in the political world as storms in the physical.
____
// end::bl-alt[]
// in qr
// tag::para[]
[quote, Albert Einstein]
A person who never made a mistake never tried anything new.
......@@ -49,24 +51,28 @@ Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That's wh
____
// end::comp[]
// in qr
// tag::no-cite[]
____
A person who never made a mistake never tried anything new.
____
// end::no-cite[]
// in qr
// tag::abbr[]
"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
// end::abbr[]
// in qr
// tag::md[]
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
// end::md[]
//in qr
// tag::md-alt[]
> > What's new?
>
......@@ -83,6 +89,7 @@ and as necessary in the political world as storms in the physical."
> Yep. AsciiDoc and Markdown share a lot of common syntax already.
// end::md-alt[]
// in qr
// tag::link-text[]
[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
......
////
Included in:
- user-manual: Sidebar
- quick-ref
////
// tag::base-c[]
.AsciiDoc history // <1>
**** // <2>
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
// in qr
// tag::delimited[]
.Optional Title
****
// end::base-c[]
// tag::base[]
.AsciiDoc history
Sidebars are used to visually separate auxiliary bits of content
that supplement the main text.
****
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
****
// end::base[]
// end::delimited[]
......@@ -4,6 +4,7 @@ Included in:
- quick-ref
////
// used in qr
// tag::base[]
= Reference Documentation
Lead Developer
......@@ -33,6 +34,10 @@ This is documentation for project X.
\include::filename.txt[lines=12..-1]
// end::last[]
// tag::include-with-tag[]
\include::filename.txt[tag=definition]
// end::include-with-tag[]
[source,ruby,subs=attributes+]
----
// tag::tag-co[]
......@@ -90,6 +95,7 @@ class Bar {
--
// end::out[]
// used in qr
// tag::uri[]
\include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[]
// end::uri[]
//all examples used in qr
// tag::qr-author[]
= Document Title
Author Name <author@email.org>; Author Name <author@email.org>
This document provides...
// end::qr-author[]
// tag::qr-rev[]
= Document Title
Author Name <author@email.org>
v2.0, 2019-03-22
This document provides...
// end::qr-rev[]
// tag::qr-attributes[]
= Document Title
Author Name <author@email.org>
v2.0, 2019-03-22
:toc:
:homepage: https://example.org
This document provides...
// end::qr-attributes[]
// tag::b-base[]
= My Document's Title
// used in qr
// tag::qr-title[]
= Document Title
My document provides...
// end::b-base[]
This document provides...
// end::qr-title[]
// tag::sub-1[]
= The Intrepid Chronicles: A Tale of Caffeine and Words
......
......@@ -2,7 +2,7 @@
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
* normal list item
// end::check[]
// tag::check-int[]
......@@ -10,12 +10,12 @@
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
* normal list item
// end::check-int[]
// tag::check-icon[]
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
* normal list item
// end::check-icon[]
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