Commit 1683fde5 authored by Dan Allen's avatar Dan Allen
Browse files

resolves #6 use the term "pair" instead of "set" when referring to complements (PR #16)

* replace formatting set with formatting pair
* replace (un)constrained set with (un)constrained pair
* replace set of brackets with pair of brackets
* replace set of delimited lines with pair of delimited lines
* revise overview page for text formatting and punctuation
parent 1d443f45
......@@ -62,7 +62,7 @@ That means that you can reference them throughout your document without having t
TIP: Wolpertingers don't like temperatures above 100{deg}C. <.>
Our servers don't like them either.
----
<.> Reference the character replacement attribute `deg` by enclosing its name in a set of curly brackets (`+{ }+`).
<.> Reference the character replacement attribute `deg` by enclosing its name in a pair of curly brackets (`+{ }+`).
As you can see below, the attribute reference is replaced with the attribute's value when the document is processed.
......
......@@ -4,7 +4,7 @@
== Delimited blocks
Block content can be styled by enclosing it in a set of delimiters.
Block content can be styled by enclosing it in a pair of delimiters (i.e., delimiter lines).
A *delimited block* has an *opening delimiter* and a *closing delimiter*.
The opening and closing delimiters must be the same length.
The style and substitutions applied to the delimited block's content is indicated by the characters in the delimiters.
......
......@@ -8,7 +8,7 @@
A block (or block element) is a line-oriented, discrete chunk of content in an AsciiDoc document.
Some blocks may contain other blocks.
A block is defined as one or more contiguous lines of text or optionally contiguous lines enclosed in block delimiters (aka fences).
A block is defined as one or more contiguous lines of text or optionally contiguous lines enclosed in block delimiters.
A block (including its metadata lines) should be surrounded by a blank line or document boundary on either side.
Examples of a block include a paragraph, a section, a list, a delimited block, a table, a block macro, and the document itself.
......
......@@ -27,7 +27,7 @@ Sidebars are used to visually separate auxiliary bits of content that supplement
== Delimited sidebar syntax
A delimited sidebar block is delimited by a set of four consecutive asterisks (`pass:[****]`).
A delimited sidebar block is delimited by a pair of four consecutive asterisks (`pass:[****]`).
You don't need to set the style name when you use the sidebar's delimiters.
.Sidebar block delimiter syntax
......
......@@ -13,7 +13,7 @@ When assigned implicitly via the author line, the value includes all of the char
email::
The `email` attribute represents an email address or URL associated with the first author (`author`).
When assigned via the author line, it's enclosed in a set of angle brackets (`< >`).
When assigned via the author line, it's enclosed in a pair of angle brackets (`< >`).
=== Name and initials attributes
......@@ -40,7 +40,7 @@ The attributes `firstname_<n>`, `middlename_<n>`, `lastname_<n>`, and `authorini
email_<n>::
The `email_<n>` attribute represents an email address or URL associated with xref:multiple-authors.adoc[each additional author] (`author_<n>`).
It's enclosed in a set of angle brackets (`< >`) on the author line.
It's enclosed in a pair of angle brackets (`< >`) on the author line.
firstname_<n>::
The first word in the value of the `author_<n>` attribute is automatically assigned to `firstname_<n>`.
......
......@@ -26,7 +26,7 @@ firstname middlename lastname <email>
The author's middle name is optional.
An email or URL following the author's last name is also optional.
If included, the email address must be enclosed in a set of angle brackets (`< >`).
If included, the email address must be enclosed in a pair of angle brackets (`< >`).
The author line also accepts xref:multiple-authors.adoc[multiple authors].
......@@ -42,7 +42,7 @@ The author line must be placed on the line directly below the xref:title.adoc[do
Kismet R. Lee <kismet@asciidoctor.org> <.> <.>
----
<.> Enter the author's name on the line below the document title.
<.> In a set of angle brackets (`< >`), enter the author's email or URL.
<.> In a pair of angle brackets (`< >`), enter the author's email or URL.
Remember, a middle name and email are optional.
The processor assigns the content on the author line to the built-in attributes using word position, word count, and syntax.
......
= Document Header
The document header is a set of contiguous lines at the start of the document that encapsulates the document title, author and revision information, metadata, and document-wide attributes.
The document header is a series of contiguous lines at the start of the document that encapsulates the document title, author and revision information, metadata, and document-wide attributes.
== Document header structure
The document header is a set of contiguous lines that starts on the first line of the file.
The document header is a series of contiguous lines that starts on the first line of the file.
WARNING: The document header can't contain blank lines or block content.
The first blank line that the processor encounters is interpreted as the end of the document header and the beginning of the document body.
......
......@@ -19,7 +19,7 @@ To use Font Awesome's icons in your document, set the value of the `icons` docum
icon:tags[] ruby, asciidoctor <.>
----
<.> Set `icons` to `font` to use the Font Awesome icons.
<.> Enter the name of the Font Awesome icon in the target field of the inline icon macro, followed by a set of square brackets (`[]`).
<.> Enter the name of the Font Awesome icon in the target field of the inline icon macro, followed by a pair of square brackets (`[]`).
.Result: Use Font Awesome tags icon
icon:tags[] ruby, asciidoctor
......
......@@ -44,7 +44,7 @@ An icon can be inserted at an arbitrary place in your content with the icon macr
icon:file-name[]
----
Enter the file name of the icon in the target field of the icon macro, followed by a set of square brackets (`[]`).
Enter the file name of the icon in the target field of the icon macro, followed by a pair of square brackets (`[]`).
Depending on the value of `icons` and the converter, Asciidoctor will look for the icon file (e.g., [.path]_file-name_) in the icons directory (`iconsdir`) or in the font icon set.
The file extension (e.g., _.png_) doesn't have to be specified as long as it matches the value of the `icontype` attribute.
`icontype` is set to `.png` by default.
......
......@@ -19,7 +19,7 @@ Content in document
----
<.> To insert a block image, type the `image` macro name directly followed by two colons (`::`).
<.> After the colons, enter the image file target.
Type a set of square brackets (`+[]+`) directly after the target to complete the macro.
Type a pair of square brackets (`+[]+`) directly after the target to complete the macro.
The result of <<ex-block>> is displayed below.
......@@ -75,7 +75,7 @@ Click image:play.png[] to get the party started. <.>
Click image:pause.png[title="Pause"] when you need a break. <.>
----
<.> In the flow of an element, enter the macro name and a single colon (`+image:+`), followed by the image target.
Complete the macro with a set of square brackets (`+[]+`).
Complete the macro with a pair of square brackets (`+[]+`).
<.> You can specify a comma-separated list of attributes inside the square brackets or leave them empty.
The result of <<ex-inline>> is displayed below.
......
......@@ -2,7 +2,7 @@
// The term URL is now preferred over the term URI. See https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#URLs_and_URNs
If you're familiar with the AsciiDoc syntax, you may notice that a URL almost looks like an inline macro.
All that's missing is the set of the trailing square brackets.
All that's missing is the pair of the trailing square brackets.
In fact, if you add them, then a URL is treated an an inline macro.
We call this a URL macro.
......@@ -10,7 +10,7 @@ This page introduces the URL macro, when you would want to use it, and how it di
== From URL to macro
To transform a URL into a macro, add a set of square brackets to the end of the URL.
To transform a URL into a macro, add a pair of square brackets to the end of the URL.
For example:
[source]
......
......@@ -27,7 +27,7 @@ TIP: When you need to prevent or control the substitutions on one or more blocks
[#triple-plus]
== Triple plus macro
The triple plus passthrough excludes content enclosed in a set of triple pluses (pass:[+++]) from all substitutions.
The triple plus passthrough excludes content enclosed in a pair of triple pluses (pass:[+++]) from all substitutions.
+++content passed directly to the output+++ followed by normal content.
......
......@@ -6,8 +6,8 @@ Bold is useful when the text needs to catch the attention of a site visitor quic
== Bold syntax
You can mark a word or phrase as bold by enclosing it in a single set of asterisks (e.g., `+*word*+`) (constrained).
You can mark bounded characters (i.e., characters within a word) as bold by enclosing them in a set of double asterisks (e.g., `+char**act**ers+`) (unconstrained).
You can mark a word or phrase as bold by enclosing it in a single pair of asterisks (e.g., `+*word*+`) (constrained).
You can mark bounded characters (i.e., characters within a word) as bold by enclosing them in a pair of double asterisks (e.g., `+char**act**ers+`) (unconstrained).
.Bold inline formatting
[source#ex-bold]
......@@ -37,8 +37,8 @@ You can add multiple emphasis styles to bold text as long as the syntax is place
`*_monospace bold italic phrase_*` & ``**__char__**``acter``**__s__**``
----
xref:monospace.adoc[Monospace syntax] (`++`++`) must be the outermost formatting set (i.e., outside the bold formatting set).
xref:italic.adoc[Italic syntax] (`+_+`) is always the innermost formatting set.
xref:monospace.adoc[Monospace syntax] (`++`++`) must be the outermost formatting pair (i.e., outside the bold formatting pair).
xref:italic.adoc[Italic syntax] (`+_+`) is always the innermost formatting pair.
The results of <<ex-mix>> are displayed below.
......
......@@ -3,7 +3,7 @@
== Highlight syntax
When text is enclosed in a set of single or double hash symbols (`#`), and no style is assigned to it, the text will be rendered as highlighted text (text wrapped in `<mark>`).
When text is enclosed in a pair of single or double hash symbols (`#`), and no style is assigned to it, the text will be rendered as highlighted text (text wrapped in `<mark>`).
.Highlighted style syntax
[source#ex-highlight]
......
= Text Formatting and Punctuation
Just as we emphasize certain words and phrases when we speak, we emphasize them in text with formatting and punctuation.
AsciiDoc provides six inline text styles and one punctuation style that are applied solely with formatting marks and two built-in styles that are applied with an additional role.
You can also create custom inline formatting roles.
Just as we emphasize certain words and phrases when we speak, we emphasize words and phrases in text using formatting and punctuation.
AsciiDoc provides an assortment of formatting marks for applying visual emphasis and typographic punctuation to your document.
You can build on these basic formatting marks using built-in and user-defined roles.
This page covers the formatting marks that AsciiDoc provides and the rules for applying and customizing them.
== Formatting terms and concepts
=== Formatting marks and sets
=== Formatting marks and pairs
A [#def-format-mark.term]*formatting mark* is a character, such as `+*+`, `_`, or `~`, that indicates the inline style you want Asciidoctor to apply to the text.
Formatting marks come in sets.
A [#def-format-mark.term]*formatting mark* is a symbolic character, such as `+*+`, `_`, or `~`, that indicates the inline style you want Asciidoctor to apply to the text.
Formatting marks come in pairs.
A [#def-format-set.term]*formatting set* consists of an identical opening mark and closing mark.
A [#def-format-pair.term]*formatting pair* consists of an identical opening mark and closing mark that encloses the text you want to style.
The [#def-open-mark.term]*opening mark* indicates where you want the style to start, and the [#def-close-mark.term]*closing mark* indicates where you want the style to end.
Depending on where the formatting marks of a set are placed, a formatting set is either constrained or unconstrained.
The [#def-open-mark.term]*opening mark* specifies where you want the style to start.
The [#def-close-mark.term]*closing mark* specifies where you want the style to end.
[#constrained-set]
=== Constrained set
A formatting pair is defined as either constrained or unconstrained, depending on where it's allowed to be applied.
An unconstrained pair can be applied anywhere, whereas the application of a constrained pair is more limited.
When a blank space directly precedes the formatting set's opening mark and a blank space or punctuation mark (`,`, `;`, `"`, `.`, `?`, and `!`) directly follows the set's closing mark, the formatting set is referred to as a [.term]*constrained set*.
A constrained set uses a single opening mark and a single closing mark to enclose the text that will be styled.
[#constrained]
=== Constrained formatting pair
When a blank space directly precedes the text to format, and a blank space or punctuation mark (`,`, `;`, `"`, `.`, `?`, or `!`) directly follows the text, a [.term]*constrained formatting pair* can be used.
A constrained pair uses a single opening mark and a single closing mark to enclose the text to be styled (e.g., `+*strong*+`).
For example, you use this form to format a word that stands alone,
......@@ -43,19 +47,26 @@ or to format a word adjacent to punctuation, like an exclamation mark.
This stuff is *strong*!
----
[#unconstrained-set]
=== Unconstrained set
As you can see, the constrained pair offers a more succinct markup at the tradeoff of having more limited (constrained) use.
However, it should suffice in most cases, so the abbreviated markup is a benefit.
You can think of a constrained pair as being a weaker markup than an unconstrained pair.
[#unconstrained]
=== Unconstrained formatting pair
When a blank space does not precede the text to format, or a blank space or punctuation mark (`,`, `;`, `"`, `.`, `?`, or `!`) does not directly follow the text, or the text does not start or end with a word character, a [.term]*unconstrained formatting pair* must be used.
An unconstrained pair uses a double opening mark and a double closing mark to enclose the text to be styled (e.g., `+Sara**h**+`).
A double set of formatting marks is required to enclose text when the opening mark isn't directly preceded by a blank space or the closing mark isn't directly followed by a blank space or punctuation mark (`,`, `;`, `"`, `.`, `?`, and `!`).
In this context, a formatting set is an [.term]*unconstrained set*.
You use the unconstrained syntax to format just one or a few letters in a word.
For example, you'd use an unconstrained pair to format just one or a few letters in a word.
[source]
----
She spells her name with an "`h`", as in Sara**h**.
----
See xref:troubleshoot-unconstrained-formatting.adoc#when-to-use-unconstrained[When should I use an unconstrained set?] for more examples and information.
The unconstrained pair provides a more brute force approach to formatting at the tradeoff of being more verbose.
You'll typically switch to an unconstrained pair when a constrained pair doesn't do the trick.
See xref:troubleshoot-unconstrained-formatting.adoc#when-to-use-unconstrained[When should I use an unconstrained pair?] for more examples of when to use an unconstrained pair.
== Inline text and punctuation styles
......@@ -98,7 +109,7 @@ xref:quotation-marks-and-apostrophes.adoc[Curved quotation marks and apostrophes
By default, Asciidoctor uses straight quotation marks and apostrophes.
They can be changed to curved using the backtick (`++`++`) formatting mark.
== Quotes substitutions
== Quotes substitution
When Asciidoctor processes text enclosed by inline formatting syntax, the marks are replaced by the corresponding HTML or XML tags, depending on your backend, during the xref:subs:quotes.adoc[quotes substitution step].
You can control when inline formatting is applied to inline text, macros, or blocks with the xref:subs:quotes.adoc#quotes-value[quotes substitution value].
......
......@@ -6,8 +6,8 @@ Italic type slants slightly to the right, and depending on the font, may have cu
== Italic syntax
You can emphasize (aka italicize) a word or phrase by enclosing it in a single set of underscores (e.g., `+_word_+`) (constrained).
You can emphasize bounded characters (i.e., characters within a word) by enclosing them in a set of double underscores (e.g., `+char__act__ers+`) (unconstrained).
You can emphasize (aka italicize) a word or phrase by enclosing it in a single pair of underscores (e.g., `+_word_+`) (constrained).
You can emphasize bounded characters (i.e., characters within a word) by enclosing them in a pair of double underscores (e.g., `+char__act__ers+`) (unconstrained).
.Italic inline formatting
[source#ex-italic]
......@@ -37,9 +37,9 @@ You can add multiple emphasis styles to italic text as long as the syntax is pla
`*_monospace bold italic phrase_*` & ``**__char__**``acter``**__s__**``
----
xref:monospace.adoc[Monospace syntax] (`++`++`) must be the outermost formatting set.
xref:bold.adoc[Bold syntax] (`+*+`) must be outside the italics formatting set.
Italic syntax is always the innermost formatting set.
xref:monospace.adoc[Monospace syntax] (`++`++`) must be the outermost formatting pair.
xref:bold.adoc[Bold syntax] (`+*+`) must be outside the italics formatting pair.
Italic syntax is always the innermost formatting pair.
The result of <<ex-mix>> is rendered below.
......
= Monospace
In AsciiDoc, a span of text enclosed in a single set of backticks (`{backtick}`) is displayed using a fixed-width (i.e., monospaced) font.
In AsciiDoc, a span of text enclosed in a single pair of backticks (`{backtick}`) is displayed using a fixed-width (i.e., monospaced) font.
Monospace text formatting is typically used to represent text shown in computer terminals or code editors (often referred to as a codespan).
== Constrained
......@@ -21,7 +21,7 @@ include::example$text.adoc[tag=mono]
== Unconstrained
As with other types of text formatting, if the text is bounded by word characters on either side, it must be enclosed in a double set of backtick characters (`{backtick}{backtick}`) in order for the formatting to be applied.
As with other types of text formatting, if the text is bounded by word characters on either side, it must be enclosed in a double pair of backtick characters (`{backtick}{backtick}`) in order for the formatting to be applied.
Here's an example:
......@@ -32,7 +32,7 @@ The command will re``link`` all packages.
== Mixed Formatting
Monospaced text can also be formatted in bold or italic or both, as long as the markup sets are entered in the right order.
Monospaced text can also be formatted in bold or italic or both, as long as the markup pairs are entered in the right order.
The monospace markup must be the outermost formatting mark, then the bold marks, then the italic marks.
.Order of inline formatting syntax
......@@ -63,7 +63,7 @@ However, escaping individual occurrences that way can be tedious.
That's why AsciiDoc offers a special type of monospace formatting called the literal monospace.
To make a true literal codespan in AsciiDoc, you must enclose the monospaced text in a passthrough.
Rather than using a single set of backtick characters, you'll use the combination of the backtick and plus characters, where the plus characters fall on the inside of the backtick characters (e.g., `pass:[`+text+`]`).
Rather than using a single pair of backtick characters, you'll use the combination of the backtick and plus characters, where the plus characters fall on the inside of the backtick characters (e.g., `pass:[`+text+`]`).
The plus characters are a shorthand for the `\pass:c[]` enclosure.
<<ex-literal>> contains literal, monospaced text.
......@@ -121,7 +121,7 @@ Double plus (`++`) is an unconstrained match (can be used anywhere inline, just
TIP: You may recognize that `++` is now equivalent to `$$` (and perhaps easier to read).
Notice that the text is not formatted as monospace.
To apply monospace formatting to content marked by `+` or `++`, surround it with a set of backticks.
To apply monospace formatting to content marked by `+` or `++`, surround it with a pair of backticks.
[source]
----
......@@ -194,16 +194,16 @@ If you aren't worried about how the document renders on services like GitHub, yo
////
Monospace text formatting is often used to emulate how source code appears in computer terminals, simple text editors, and integrated development environments (IDEs).
A word or phrase is rendered using a fixed-width font, i.e. monospaced font, when it is enclosed in a single set of plus signs (+{plus}+).
A character contained within a string of characters must be enclosed in a double set of plus signs (+{plus}{plus}+).
A word or phrase is rendered using a fixed-width font, i.e. monospaced font, when it is enclosed in a single pair of plus signs (+{plus}+).
A character contained within a string of characters must be enclosed in a double pair of plus signs (+{plus}{plus}+).
[source]
----
include::ex-text.adoc[tag=mono]
----
Monospaced text can be bold and italicized, as long as the markup sets are entered in the right order.
The monospace markup must be the outermost set, then the bold set, and the italic markup must always be the innermost set.
Monospaced text can be bold and italicized, as long as the markup pairs are entered in the right order.
The monospace markup must be the outermost pair, then the bold pair, and the italic markup must always be the innermost pair.
.Rendered monospace formatted text
====
......
......@@ -5,15 +5,15 @@
Single and double quotation marks are *not* rendered as curved quotation marks (also known as smart, curly, typographic or book quotation marks).
When entered using the kbd:[{apos}] and kbd:[{quot}] key, Asciidoctor outputs straight (dumb, vertical, typewriter)
quotation marks.
However, by creating a set of backticks (`{backtick}`) contained within a set of single quotes (`{apos}`) or double quotes (`{quot}`), you can tell Asciidoctor where to output curved quotation marks.
However, by creating a pair of backticks (`{backtick}`) contained within a pair of single quotes (`{apos}`) or double quotes (`{quot}`), you can tell Asciidoctor where to output curved quotation marks.
.Single and double curved quotation marks syntax
[source#ex-quote-marks]
----
include::example$text.adoc[tag=c-quote-co]
----
<.> To output double curved quotes, enclose a word or phrase in a set of double quotes (`{quot}`) and a set of backticks (`{backtick}`).
<.> To output single curved quotes, enclose a word or phrase in a set of single quotes (`{apos}`) and a set of backticks (`{backtick}`). In this example, the phrase _wormwood and licorice_ should be enclosed in curved single quotes when the document is rendered.
<.> To output double curved quotes, enclose a word or phrase in a pair of double quotes (`{quot}`) and a pair of backticks (`{backtick}`).
<.> To output single curved quotes, enclose a word or phrase in a pair of single quotes (`{apos}`) and a pair of backticks (`{backtick}`). In this example, the phrase _wormwood and licorice_ should be enclosed in curved single quotes when the document is rendered.
The result of <<ex-quote-marks>> is rendered below.
......
......@@ -7,7 +7,7 @@ The size and precise placement of the text depends on the font and other stylesh
== Subscript and superscript syntax
Text is subscripted when you enclose it in a set of tildes (`{tilde}`) and superscripted with a set of carets (`{caret}`)
Text is subscripted when you enclose it in a pair of tildes (`{tilde}`) and superscripted with a pair of carets (`{caret}`)
Subscript:: One tilde (`{tilde}`) on either side of a word or phrase makes it subscript.
Superscript:: One caret (`{caret}`) on either side of a word or phrase makes it superscript.
......
= Troubleshoot Unconstrained Formatting Sets
= Troubleshoot Unconstrained Formatting Pairs
An xref:index.adoc#unconstrained-set[unconstrained formatting set] is often used to format just one or a few characters in a word.
An xref:index.adoc#unconstrained[unconstrained formatting pair] is often used to format just one or a few characters in a word.
[#use-unconstrained-set]
== When should I use an unconstrained set?
[#use-unconstrained]
== When should I use unconstrained formatting?
Consider the following questions:
......@@ -11,14 +11,14 @@ Consider the following questions:
. Is there a colon, semicolon, or closing curly bracket directly before the opening formatting mark?
. Is there a space directly inside of a formatting mark?
If you answered "`yes`" to any of these questions, you need to use an unconstrained set.
If you answered "`yes`" to any of these questions, you need to use an unconstrained pair.
To help you determine whether a particular syntax pattern requires an unconstrained set versus a xref:index.adoc#constrained-set[constrained set], consider the following scenarios:
To help you determine whether a particular syntax pattern requires an unconstrained pair versus a xref:index.adoc#constrained[constrained pair], consider the following scenarios:
.Constrained or Unconstrained?
[#constrained-or-unconstrained]
|===
|AsciiDoc |Result |Formatting Set |Reason
|AsciiDoc |Result |Formatting Pair |Reason
|`+Sara__h__+`
|Sara__h__
......@@ -52,9 +52,9 @@ To help you determine whether a particular syntax pattern requires an unconstrai
|===
[#unconstrained-edge-cases]
=== Unconstrained set edge cases
=== Unconstrained pair edge cases
There are cases when it might seem logical to use a constrained set, but an unconstrained set is required.
There are cases when it might seem logical to use a constrained pair, but an unconstrained pair is required.
xref:subs:substitutions.adoc[Substitutions] may be applied by the parser before getting to the formatting marks, in which case the characters adjacent to those marks may not be what you see in the original source.
One such example is enclosing a xref:monospace.adoc[monospace phrase] inside xref:quotation-marks-and-apostrophes.adoc[curved quotation marks], such as "```end points```".
......@@ -69,17 +69,17 @@ You might start with the following syntax:
That only gives you "`end points`".
The backticks contribute to making the curved quotation marks, but the word isn't rendered in monospace.
Adding another set of backticks isn't enough either.
Adding another pair of backticks isn't enough either.
[source]
----
"``end points``"
----
The parser ignores the inner set of backticks and interprets them as literal characters, rendering the phrase as "``end points``".
The parser ignores the inner pair of backticks and interprets them as literal characters, rendering the phrase as "``end points``".
You have to use an unconstrained set of monospace formatting marks to render the phrase in monospace and a constrained set of backticks to render the quotation marks as curved.
That's three sets of backticks in total.
You have to use an unconstrained pair of monospace formatting marks to render the phrase in monospace and a constrained pair of backticks to render the quotation marks as curved.
That's three pairs of backticks in total.
.A monospace phrase inside curved quotation marks
[source]
......
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