Commit af4039d4 authored by Dan Allen's avatar Dan Allen
Browse files

rewrite introduction pages to provide a smoother onramp

parent e1af6c7f
* Key Concepts
//* xref:get-started.adoc[]
** xref:doctypes.adoc[]
** xref:elements.adoc[]
** xref:attributes:types.adoc[]
* Introduction
** xref:document-structure.adoc[]
** xref:key-concepts.adoc[]
** xref:document-processing.adoc[]
= Document Processing
AsciiDoc is specifically a writing format, not a publishing format.
In other words, it's not WYSIWYG like when you write in a word processor.
Instead, what you write is the AsciiDoc source.
You then use an AsciiDoc processor, such as Asciidoctor, to convert the AsciiDoc source into a publishable format.
It's this output that you publish.
Converting the AsciiDoc source is an opportunity to interpret and embellish your content to get more out of it than what you put in.
The work of converting the AsciiDoc source to another format is handled by a converter.
An AsciiDoc processor provides several built-in converters, including ones for making HTML and DocBook.
To activate one of these converters, you set the backend on the document (default: html).
The backend is a keyword that tells the processor which output format you want to make.
The processor then selects the converter that makes that output format.
For example, the HTML converter handles the html backend to make HTML output.
An AsciiDoc processor actually works in two steps.
First, it parses the AsciiDoc document.
This parsing produces a structured document that reflects the written structure and interprets all the meaningful markup.
The processor then passes this structured document to the converter to transform it into the output format.
In short, the processor accepts a string (which may be read from a file), parses it into a structure document, then produces another string (which may be written to a file).
= Document Structure
On this page, you'll learn about the overall structure of an AsciiDoc document.
Don't worry about the details of the syntax at this point as it will be covered thoroughly later in the documentation.
Right now, we're just aiming for a sense of what makes up an AsciiDoc document.
== Documents
AsciiDoc is a plain text writing format with no boilerplate enclosure or prologue.
An AsciiDoc document may consist of only a single sentence (or a single character, if you want to be academic).
The following example is a valid AsciiDoc document with a single paragraph containing a single sentence:
[source]
----
This is a basic AsciiDoc document.
----
Of course, you can have more content than this.
An AsciiDoc document is a series of blocks stacked on top of one another (by line).
These blocks are typically offset from one another by blank lines (though not always required).
To expand the previous document from one paragraph to two, you'd separate the two paragraphs by a blank line:
[source]
----
This is a basic AsciiDoc document.
This document contains two paragraphs.
----
An AsciiDoc document may begin with a document header.
Although the document header is optional, it's often used to specify the document title and define document-wide configuration and reusable text in the form of document attributes.
[source]
----
= Document Title
:reproducible:
This is a basic AsciiDoc document by {author}.
This document contains two paragraphs.
It also has a header that specifies the document title.
----
Almost any combination of blocks constitutes a valid AsciiDoc document (with some structural requirements dictated by the document type).
Documents can range from a single sentence to a multi-part book.
== Lines
The line is a significant construct in AsciiDoc.
A line is defined as text that's separated on either side by either a newline character or the boundary of the document.
Many aspects of the syntax must occupy a whole line.
That's why we say AsciiDoc is a line-oriented language.
For example, a section title must be on a line by itself.
The same is true for an attribute entry, a block title, a block attribute list, a block macro, a list item, a block delimiter, and so forth.
.Example of a section title, which must occupy a single line
[source]
----
== Section Title
----
.Example of an attribute entry, which must also occupy at least one line
[source]
-----
:name: value
-----
.Example of an attribute entry that extends to two lines
[source]
-----
:name: value \
more value
-----
Blank lines can also be significant.
A single blank line separates the header from the body.
Many blocks are also separated by a blank line, as you saw in the two paragraph example earlier.
In contrast, lines within paragraph content are insignificant.
Keep these points in mind as you're learning about the AsciiDoc syntax.
== Blocks
Blocks in an AsciiDoc document lay down the document structure.
Some blocks may contain other blocks, so the document structure is inherently hierarchical (i.e., a tree structure).
You can preview this section structure, for example, by enabling the automatic table of contents.
Examples of blocks include paragraphs, sections, lists, delimited blocks, tables, and block macros.
Blocks are easy to identify because they're usually offset from other blocks by a blank line (though not always required).
Blocks always start on a new line, terminate at the end of a line, and are aligned to the left margin.
Every block can have one or more lines of block metadata.
This metadata can be in the form of block attributes, a block anchor, or a block title.
These metadata lines must be above and directly adjacent to the block itself.
Sections, non-verbatim delimited blocks, and AsciiDoc table cells may contain other blocks.
Despite the fact that blocks form a hierarchy, even nested blocks start at the left margin.
By requiring blocks to start at the left margin, it avoids the tedium of having to track and maintain levels of indentation and makes the content more reusable.
== Text and inline elements
Surrounded by the markers, delimiters, and metadata lines is the text.
The text is the main focus of a document and the reason the AsciiDoc syntax gives it so much room the breathe.
Text is most often found in the lines of a block (e.g., paragraph), the block title (e.g., section title), and in list items, though there are other places where it can exist.
Text is subject to substitutions.
Substitutions interpret markup as text formatting, replace macros with text or non-text elements, expand attribute references, and perform other sorts of text replacement.
Normal text is subject to all substitutions, unless specified otherwise.
Verbatim text is subject to a minimal set of substitutions to allow it to be displayed in the output as it appears in the source.
It's also possible to disable all substitutions in order to pass the text through to the output unmodified (i.e., raw).
The parsing of text ends up being a mix of inline elements and other forms of transformations.
== Encodings and AsciiDoc files
An AsciiDoc file is a text file that has the _.adoc_ file extension (e.g., [.path]_document.adoc_).
Most AsciiDoc processors assume the text in the file uses UTF-8 encoding.
UTF-16 encodings are supported only if the file starts with a BOM.
An AsciiDoc processor can process AsciiDoc from a string (i.e., character sequence).
However, most of the time you'll save your AsciiDoc documents to a file.
......@@ -5,21 +5,19 @@ There are two kinds of elements in AsciiDoc, block elements and inline elements.
[#block-element]
== Block elements
A [.term]*block element* is one or more contiguous lines of content in an AsciiDoc document.
A [.term]*block element* is stacked vertically (by line) above or below other block elements.
Block elements are typically referred to simply as [.term]*blocks*.
Examples of blocks include tables, lists, paragraphs, section titles, delimited blocks, and block macros like the block image macro (`image::[]`).
These types of blocks are easy to identify because they're separated from other blocks by a blank line.
However, not all blocks may be separated by a blank line from an adjacent block.
For instance, block titles and block attribute lists are individual block elements that are placed on adjacent, contiguous lines.
An attribute entry is also a block, that when defined in a document header is often directly adjacent to other blocks.
Examples of blocks include sections, paragraphs, lists delimited blocks, tables, and block macros.
Blocks are easy to identify because they're usually separated from other blocks by a blank line (though not always required).
Some blocks, such as sections and delimited blocks, can nest other blocks inside of them.
Blocks can be nested within other blocks.
An attribute entry in a header is also an example of a block nested within another block.
That's because the attribute entry is a block and the entire document header is a block.
Every block can have one or more lines of block metadata.
This metadata can be in the form of block attributes, a block anchor, or a block title.
These metadata lines should be directly adjacent to the block itself.
[#inline-element]
== Inline elements
An [.term]*inline element* performs an operation on a subset of content within a <<block-element,block element>>.
An [.term]*inline element* performs an operation on a span of content within a <<block-element,block element>>.
Inline elements include inline macros such as the icon macro (`icon:[]`) and xref macro (`<< >>`, `xref:[]`), attribute references, and text marked up by inline formatting (italic, bold, etc.).
......@@ -24,6 +24,8 @@ header attribute:: a document attribute defined in the document header; visible
list continuation:: a plus sign (`+`) on a line by itself that connects adjacent lines of text to a list item.
macro:: a syntax for representing non-text elements or that expands into text using the provided metadata.
macro attribute:: an attribute associated with a block or inline macro; these attributes can affect processing of the macro, and are available to macro processors, but cannot be referenced using an attribute reference.
predefined attribute:: a document attribute defined for convenience; often used for inserting special content characters.
......
= AsciiDoc Language Documentation
:url-asciidoc-lang: https://projects.eclipse.org/projects/technology.asciidoc
[caption="Migration in Progress"]
TIP: This documentation is in migration.
[caption=Migration in Progress]
CAUTION: This documentation is in migration.
If you're looking for the current Asciidoctor and AsciiDoc documentation, visit https://asciidoctor.org/docs.
== About AsciiDoc
AsciiDoc is a lightweight and semantic markup language primarily designed for writing technical documentation.
The language can be used to produce a variety of presentation-rich output formats, all from content encoded in a concise, human-readable, plain text format.
The AsciiDoc syntax is intuitive because it recognizes well-established, plain text conventions for marking up and structuring text.
Someone unfamiliar with AsciiDoc can probably guess the purpose of many of its syntax elements just by looking at them.
That's because the elements of the syntax were carefully chosen to look like what they mean (a practice long employed by the tech industry).
The AsciiDoc language isn't coupled to the output format it produces.
An AsciiDoc processor can parse and comprehend an AsciiDoc source document and convert the parsed document structure into one or more output formats, such as HTML, PDF, EPUB3, man(ual) page, or DocBook.
The ability to produce multiple output formats is one of the main advantages of AsciiDoc.
This capability enables it to be used in static site generators, IDEs, git tools and services, CI/CD systems, and other software.
AsciiDoc bridges the gap between ease of writing and the rigorous requirements of technical authoring and publishing.
AsciiDoc only requires a text editor to read or write, thereby offering a low bar to getting started.
== About this documentation
You're reading the user-facing documentation for the AsciiDoc language as it's implemented in xref:asciidoctor::index.adoc[Asciidoctor].
This documentation does not cover how to set up and use Asciidoctor to process AsciiDoc content.
You can find that documentation in the xref:asciidoctor::index.adoc[Asciidoctor] section of this website.
This documentation has been submitted as the initial contribution for the {url-asciidoc-lang}[AsciiDoc Language project at Eclipse^].
That project will use this documentation as the basis for drafting a specification for the AsciiDoc language.
It will also be used as the draft of the user-facing guide for the AsciiDoc Language, which will also be maintained by that project.
Until the first version of the AsciiDoc Language Specification is ratified, AsciiDoc is defined by the Asciidoctor implementation.
There is no other official definition of the language.
The documentation for AsciiDoc will remain on this site until the AsciiDoc Language project starts publishing its own documentation for the AsciiDoc Language.
Until then, let's get started!
= Key Concepts
This pages gives you more of a sense of the concepts and terms you'll encounter as you learn about AsciiDoc.
Each concept will be covered in more depth later in the documentation.
So just use this page to start to familiarize yourself with the lingo.
== Document
A document represents the top-level block element in AsciiDoc.
It consists of an optional document header and either a) one or more sections preceded by an optional preamble or b) a sequence of top-level blocks only.
The document can be configured using a document header.
The header is not a block itself, but contributes metadata to the document, such as the document title and document attributes.
== Elements
An element is an identifiable, addressable, and composible chunk of content in a document.
An AsciiDoc document is merely a composition of all the elements it contains.
Elements are a hierarchy of types, where one element may be a specialization of a family of elements.
For example, a sidebar block is a block element, so it shares the traits of all block elements, and also adds some of its own.
Elements include the document itself, sections, blocks, block macros, breaks, and inline phrases and macros.
A [.term]*block element* that is stacked vertically (by line) above or below other block elements.
Block elements are typically referred to simply as [.term]*blocks*.
Blocks form the main tree structure of the document.
An [.term]*inline element* is a span of content within a block element or one of its attributes (e.g., a block title).
Inline elements include formatted text (italic, bold, etc), inline macros, and element references.
What fills in the gap between these elements is unsubstituted text.
Inline elements are less structured than block elements as they are more geared towards substitutions than a tree structure.
== Attributes
An attribute is a name/value pairs used for storing metadata in the AsciiDoc language.
Attributes can be used to influence the syntax, control behavior, customize styles, activate or configure integrations, or store replacement content.
Attributes truly set AsciiDoc apart from other lightweight markup languages.
An attribute is actually an abstract term.
There are two concrete classifications of attributes: document attributes and element attributes.
=== Document attributes
Document attributes, as the name implies, are associated directly with the document.
They are used to export information about the document and runtime, control behavior of the processor, and to store reusable values or phrases.
Thus, they are a sort of two-way communication channel with the processor.
Document attributes can be referenced in the content using an attribute reference (whereever the attribute substitution is enabled).
A document attribute can be defined either in the document using an attribute entry (typically in the document header) or from the API or CLI.
Not all document attributes can be modified.
=== Element attributes
Element attributes are metadata on a specific element, like a block or an inline element, and only apply to that element.
The name can either be a string (i.e., a named attribute) or a numerical index (i.e., an unnamed, positional attribute).
Element attributes are not accessible at all from the content, so they cannot be referenced like document attributes.
Element attributes enrich or configure the behavior of an element, such as to apply a role or set the width of an image.
An element attribute is defined using an attribute list on an element, or an avaiable shorthand like a block title line.
== Macros
As you read through this documentation, you'll frequently see references to the term macro.
A macro is a syntax for representing non-text elements or that expands into text using the provided metadata.
Here's an example of a block macro:
[source]
----
image::sunset.jpg[Sunset]
----
Here's an example of an inline macro:
[source]
----
Click the button with the image:star.png[Star] to favorite the project.
----
You can think of a macro like a function.
A syntax of macro follows the form of a name, a target which is sometimes optional, and an attribute list consisting of zero or more element attributes enclosed in square brackets.
There are two variations of a macro: block and inline.
In a block macro, the name and target are separated by two colons (`::`) and it must reside on a line by itself.
In an inline macro, the name and target are separated by a single colon (`:`) and it can be alongside text and other inline elements.
A block macro is always parsed, whereas an inline macro is only parsed where the macro substitution is enabled.
== Preprocessor directives
There's another syntax in AsciiDoc that looks a lot like block macros, only they aren't.
These are the preprocessor directives.
A preprocessor directive is function that controls lines that are fed into the parser.
A conditional preprocessor directive can configure lines to be included or excluded based on the presence of an attribute (ifdef, ifndef) or another arbitrary condition (ifeval).
An include directive can add additional lines to the document taken from another document.
Like a block macro, a preprocessor directive must be on a line by itself.
While the preprocessor directive can access document attributes, it is not otherwise aware of the context around it.
It's only a line processor.
......@@ -5,7 +5,7 @@ They're also used to apply user-defined behavior and supplemental information, s
== What are element attributes?
[.term]*Element attributes* define the built-in and user-defined styles, behavior, and metadata that are applied to an individual xref:ROOT:elements.adoc#block[block element] or xref:ROOT:elements.adoc#inline[inline element] in a document.
[.term]*Element attributes* define the built-in and user-defined styles, behavior, and metadata that are applied to an individual block element or inline element in a document.
Element attributes:
......
= AsciiDoc Attributes
Attributes set AsciiDoc apart from other lightweight markup languages.
Attributes activate behaviors, styles, and integrations, or hold replacement (variable) content.
There are two types of attributes: document attributes and element attributes.
== Document attributes
xref:document-attributes.adoc[Document attributes] apply built-in behavior and settings to a whole document, or in select cases, to regions of a document.
They make user-defined information available for use throughout a whole document.
They're set and defined in a document's header using an attribute entry, but can also be used from the API or command line.
== Element attributes
xref:element-attributes.adoc[Element attributes] apply built-in and user-defined styles, metadata, and behavior to individual block and inline elements in a document.
They're set and defined directly on the element they're modifying using an attribute list.
Element attributes are classified as positional or named.
////
Environment attributes:: Environment attributes provide information about the runtime environment, such as how, where, and when a document is being processed.
Environment attributes are built-in and Asciidoctor automatically sets and assigns them values when a document is loaded or converted.
Environment attributes can be referenced wherever attribute references are permitted, but it's recommended that you treat these attributes as read only.
////
......@@ -14,3 +14,4 @@
*** xref:reference-revision-attributes.adoc[]
** xref:metadata.adoc[]
** xref:header-ref.adoc[]
* xref:doctypes.adoc[]
......@@ -3,6 +3,8 @@
Article (`article`)::
The default doctype.
In DocBook, includes the appendix, abstract, bibliography, glossary, and index sections.
Unless you are making a book or a man page, you don't need to worry about the doctype.
The default will suffice.
Book (`book`)::
Builds on the article doctype with the additional ability to use a top-level title as part titles, includes the appendix, dedication, preface, bibliography, glossary, index, and colophon.
......
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