A brief overview or summary of a document. The term is sometimes also used as a synonym for preamble.

see Admonition

Admonitions draw attention to specific statements by pulling a block or paragraph out of the flow of content. One of five types (NOTE, TIP, IMPORTANT, CAUTION, WARNING) defines how it is rendered. An admonition can be defined as a paragraph or as a block.

The short form for adoc Studio and also the file extension for AsciiDoc text files.

The name of this app.

see ID Attribute or Anchor

The appendix section style can be used in books and articles and can have further subsections. Although the AsciiDoc structure allows appendices to be placed anywhere, it is conventional to place them at the end of a document.

The default doctype in adoc Studio. It optionally includes the sections appendix, abstract, bibliography, glossary, and index.

An acronym for American Standard Code for Information Interchange. This standard defines 128 characters, consisting of 33 non-printable and 95 printable characters plus the space character. In AsciiDoc, ASCII refers more broadly to "everything is text — including emoji." AsciiDoc uses the full Unicode character set.

A mature, lightweight, and semantic markup language developed primarily for creating structured documents. You convert AsciiDoc files to HTML or PDF using tools like adoc Studio or Asciidoctor. The AsciiDoc language was developed in 2002 by Stuart Rackham. A reimplementation is Asciidoctor, developed since 2013 by Dan Allen. Since 2020, the Eclipse Foundation, with the AsciiDoc Working Group, has been working on standardizing AsciiDoc.

A command-line tool for parsing AsciiDoc files and converting them to output formats such as HTML and others. To generate PDF documents, Asciidoctor PDF is required. It is essentially a similar program to adoc Studio, but without project integration, without an editor, without text completion, and without a preview. Asciidoctor is open source and has been developed and maintained by Dan Allen since 2013.

A command-line tool for parsing AsciiDoc files and converting them to the PDF output format. Asciidoctor PDF is open source and is developed by Dan Allen.

Used in AsciiDoc to configure documents and store variables. A document attribute is available from the point where it is defined in the document. Some attributes must appear at the beginning of a document. Attribute entries are also frequently used to toggle features. An attribute entry consists of two parts: an attribute name and an attribute value.

The definition of attributes used for an element is called an attrlist. An attribute list is always enclosed in a pair of square brackets. This applies both to element attributes and to attributes in a block or inline macro.

The writer of a document. In AsciiDoc documents, the author can be specified below the title and is automatically stored in the :author: attribute. Additional attributes related to the author are also available.

A standalone list of references or the science of creating such a list. In adoc Studio, it can be used in books and articles.

Defines the structure of an AsciiDoc document. Some blocks contain other blocks, making the document structure inherently hierarchical (i.e., a tree structure). You can recognize this block structure in the preview by, for example, enabling the automatic table of contents. Examples of blocks are paragraphs, sections, lists, delimited blocks, tables, and admonitions.

References user-defined blocks that map any name to one or more contexts. It has a similar function to the style for a built-in block, e.g., an admonition block.

Additional information that specializes the context of a block. For example, a source block can be supplemented with the language of the source code used.

see Bold

A built-in attribute that works like a toggle. It can only indicate two states: true or false — on or off. Its purpose is to enable a feature or behavior.

Builds on the doctype article and additionally allows a top-level title to be used as a part title. It includes appendix, dedication, preface, bibliography, glossary, index, and colophon. A book can contain only chapters, or additionally various parts that each contain one or more chapters.

A document attribute for controlling the processing of the AsciiDoc document. It can control integration, styling, localization, and more.

Bold text stands out from normal text with a thicker and/or darker typeface. The formatting character for bold is an asterisk * before and after the word.

A content-dividing subdivision in texts. In adoc Studio, the files in composite documents are called chapters.

Abbreviation for command-line interface. Also referred to as command line, console, or terminal. It is an input area for controlling software, typically operating in text mode.

An element of a book, typically placed at the end. Contains information about content, author, place, date, publisher, and production details of the publication.

A document type unique to adoc Studio, in contrast to standalone documents. Composite documents collect many chapters into one large document. Multiple folders and media folders can be created within a composite document for further structure. All folders can be selected to display the chapters beneath them combined in the preview. Attributes defined anywhere in the composite document can be used in any chapter of that document.

The content model of a block determines what kind of content the block can contain and how that content is processed (e.g., simple, compound, verbatim, raw, etc.).

A software component that an AsciiDoc processor invokes to convert an AsciiDoc document to a specific output format.

A link from one location to another position in the document, identified by an anchor.

A set of instructions or a template with settings for styling a document. Different CSS rules render a document or website with the same content in a completely different way. In adoc Studio, both HTML and PDF are styled with CSS. You can also optionally include custom .css files in a project via :stylesheet:.

A document attribute defined by the author. Not reserved by AsciiDoc or any extension. Use these attributes to define recurring texts centrally, control conditions, or reuse content in multiple places.

Used to express gratitude toward others. In AsciiDoc, the dedication is its own block type, preferably used in books.

A delimited block is a region of content bounded on both sides by a pair of identical delimiter characters on separate lines. Such blocks either enclose other blocks (e.g., multiple paragraphs) or establish the content model of the enclosed content (e.g., verbatim text).

A document format defined in a document type definition (DTD) for Standard Generalized Markup Language (SGML) and Extensible Markup Language (XML). It is suitable for creating books, articles, and documentation in technical contexts (hardware or software). DocBook is an open standard maintained by the Organization for the Advancement of Structured Information Standards (OASIS).

This AsciiDoc feature lets you insert custom content into the head, header, or footer of an output document. This content is read by converters from files known as docinfo files. Docinfo files extend the output generated by a converter. Examples include inserting additional metadata, stylesheets, and script logic not already supported by the converter.

Refers to the philosophy that documentation should be written using the same tools as software source code. This means following the same workflows as development teams and integrating documentation into the product team. It enables a culture where both authors and developers feel responsible for documentation and work together to make it as good as possible.

In adoc Studio, a file is referred to as a document. It is stored in plain text format. A document can consist of a single sentence (or even a single character).

Used either to configure behavior in the processor or to convey information about the document and its environment. A complement to document attributes are element attributes. There are built-in and custom attributes.

An AsciiDoc document begins with a document header. The header can contain the document title, author and revision information, document-wide attributes, and other metadata. Many document attributes must be defined in the document header.

Defines the expected structure of an AsciiDoc document. adoc Studio supports article (as default) and book.

A software component for creating and modifying text. In adoc Studio, the editor is located in the center pane. It provides special features such as intelligent text completion to assist while writing. The editor can be styled via an app setting.

An identifiable part of content in a document. An AsciiDoc document is always a composition of all elements it contains.

Defines built-in and custom settings and metadata. Applied to a single block element or inline element in a document (including macros).

Most AsciiDoc processors, including adoc Studio, assume the text in a file uses UTF-8 encoding. UTF-16 encodings are only supported if the file begins with a BOM.

A dynamic document attribute that relates to or provides information about the runtime environment.

Output of an adoc file in a format such as HTML or PDF. An export can have its own styles and attributes, set either in the AsciiDoc document or in the export dialog. Output can be saved to a file and optionally shared directly with other applications.

A directory within a data structure. In adoc Studio, any number of folders can be created, including nested ones. In composite documents, a folder can be selected to display the chapters it contains combined in the preview.

A formatting mark is a symbolic character such as *, _, or ~ that specifies the inline style the AsciiDoc converter should apply to the text. Formatting characters always come in pairs. A formatting pair consists of an identical opening and closing character enclosing the text to be formatted. The formatted text (i.e., the text enclosed by a formatting pair) can span multiple consecutive lines. The opening mark indicates where the formatting begins. The closing mark indicates where the formatting ends.

Free software for distributed version control of files, initiated in 2005 by Linus Torvalds. All texts and media from adoc Studio can be versioned in a Git repository.

A list of words with definitions or translations. As an appendix to a work, a glossary is also known as a word list; as a standalone work, it is called a dictionary. You are currently reading the glossary of adoc Studio.

Since adjacent text lines in AsciiDoc are joined into a paragraph during conversion, you can place each sentence or phrase on its own line. The line breaks are not shown in the output. A blank line is sufficient to separate paragraphs. This approach is commonly used in the Docs as Code workflow. If you want line breaks within a paragraph to be preserved, enter a space followed by a plus sign (+), or add the "Hard Breaks" option [%hardbreaks] to the paragraph.

A document attribute defined in the header of a document. It is visible from all nodes in the document and is often needed for global attributes, e.g., the icon mode: :icons: font.

see Highlight

Another way to draw attention to text is to highlight it. This semantic style is used for reference or notation purposes, or to emphasize the significance of an important topic or point. The formatting character for highlight is a hash #.

Hypertext Markup Language (HTML) is a text-based markup language for structuring electronic documents such as texts with hyperlinks, images, and other content. HTML documents are the foundation of the World Wide Web and are rendered by web browsers.

An anchor lets you assign an identifier (i.e., a unique name) to a block or inline element. It is used to identify the element as a link target or for styling.

You can explicitly mark index terms in AsciiDoc content. Index terms form a controlled vocabulary that lets you navigate from an index to keywords in the document.

The inline doctype allows the AsciiDoc processor to cover the full range of applications, from unstructured (inline) text to complete standalone documents.

An inline element is a phrase (i.e., a span of content) within a block element or one of its attributes in an AsciiDoc document. Inline elements are used to format text and perform various kinds of text substitutions. Inline elements and inline element syntax are defined in configuration files. Conversion of inline documents is not yet implemented in adoc Studio.

Software that provides comprehensive writing and knowledge management features for authors and information workers. adoc Studio is one such environment. IWEs enable authors to perform a wide range of document-related tasks in a single environment. At best, they also support principles like Docs as Code. This provides a distraction-free workspace and an optimized writing environment.

see Italic

Text is often set in italic to emphasize a word or phrase, quote a speaker, or introduce a term. Italic type is slightly tilted to the right and may, depending on the typeface, have cursive flourishes. The formatting character for italic is an underscore.

The :keywords: attribute contains a comma-separated list of values assigned to the HTML <meta> element.

AsciiDoc is a line-oriented language, making the line an important construct. A line is defined as text bounded on both sides either by a line break or by the limits of the document. Many aspects of the syntax must occupy an entire line. When working with Docs as Code, individual lines are especially important, as changes in Git are more easily tracked line by line.

tbd:

Defined by a group of sibling list items, each identified by the same marker.

A list continuation is a plus sign (+) on its own line that joins adjacent text lines into a single list item.

A syntax for representing non-text elements, or a syntax that transforms into text using provided metadata. See Macro to learn more about the meaning of this term.

An attribute associated with a block or inline macro. These attributes can influence the processing of the macro but cannot be referenced via an attribute reference.

A machine-readable language for structuring and formatting texts and other data. The best-known example is Hypertext Markup Language (HTML), the core language of the World Wide Web.

A simplified markup language published in December 2004 by John Gruber and Aaron Swartz.

In adoc Studio, the media folder has several special functions. When selected, all contained media are displayed as a preview. Any number of media folders can be created.

Structured data containing overarching information about a resource — such as books, web documents, videos, or images. For a document, this includes, for example, a description, keywords, and custom information that can be assigned as attributes in the document header. When converting to HTML, the values of these attributes correspond to the elements found in the <head> section of an HTML document.

Technical content often requires text styled to indicate a command or source code. Such text is typically highlighted with a fixed-width (i.e., monospace) font. The formatting character for monospace is a backtick (also called grave accent).

A structural division of a whole (in adoc Studio, a text) into logically organized parts to create clarity.

In most documents, the paragraph is the most important block type. It requires no special markers or attributes. Whether you use a separate line for each sentence or write everything consecutively, the content always becomes a paragraph. Only a blank line separates paragraphs from each other.

A computer program responsible for decomposing and converting an input into a format more suitable for further processing. For the technically inclined: the parser in adoc Studio is written in Swift, modeled after AsciiDoc. It is a migration — not a copy or direct port.

In the context of a multi-part book, a part is an additional subdivision. A part can in turn contain its own chapters or appendices.

A platform-independent file format developed and released by Adobe Inc. in 1992. Electronic documents in this format can be reproduced faithfully regardless of the original application, operating system, or hardware platform.

In IT, data that is human-readable without formatting and can be directly rendered as text using character sets. The AsciiDoc documents in adoc Studio use plain text.

The content of the first section after the end of the document header. A preamble is optional in AsciiDoc.

A special section that precedes the first chapter of a book or book part. In AsciiDoc, the preface is its own block type, preferably used in books.

A document attribute defined for convenience. Often used to insert special characters into content.

A feature that controls the lines 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 any other condition (ifeval). An include directive can add additional lines to the document from another document.

In the preview, adoc Studio renders all content from the editor in various formats. HTML, PDF, and RTF Text are available. Each output format can be styled with a style.

In adoc Studio, text is separated from its presentation. A technique is needed to connect the two. This is done using product styles. A product style is a file bundle that contains at minimum an information file and a style file in CSS format. Additional resources such as media or fonts can optionally be included.

A logical grouping of multiple exports. Within a product, many exports can be defined, each with their own styles, attributes, and output formats.

In adoc Studio, a collection of all AsciiDoc files and folders, including media folders. Projects can also contain additional files such as CSS files. It is organized and managed via the Project Navigator in adoc Studio. The project is also continuously synchronized with the corresponding directory in the operating system, so it can be modified in Finder as well.

Text surrounded by special punctuation to quote other authors or to give text special meaning.

Blocks and most other inline elements can be assigned one or more roles using the attribute role. A role adds additional semantics to an element, for example to apply additional styling (via a CSS selector).

A proprietary text file format introduced by Microsoft in 1987. It can serve as an exchange format between word processing applications from different vendors on different operating systems. In adoc Studio, the preview can be set to text, which corresponds to Rich Text Format. This format is also available for export and within products.

Divides an AsciiDoc document into a content hierarchy. A section is defined by a section title preceded by one or more equals signs (=). The section includes all content following the section title, up to the next peer or parent section title or the end of the document.

Marks the beginning of a section and serves as the heading for that section. The number of preceding equals signs defines the section level. In adoc Studio, the equals signs are displayed in the left margin of the editor.

Human-readable text written in a programming language. In the Docs as Code workflow, the AsciiDoc text is also often referred to as source text.

Best compared to a format template. The core idea is the separation of content and presentation. The program that evaluates the stylesheet interprets the assigned data (text, tables, graphics, etc.) and formats them according to the defined rules. Cascading Stylesheets are probably the best-known example. In adoc Studio, custom stylesheets can be placed as .css files in the project and used with the attribute :stylesheet:.

Subscript text is frequently used in mathematical expressions and chemical formulas. The formatting character for _subscript is a tilde.

A document title can be supplemented with a second title (also called a subtitle). Unlike the AsciiDoc specification, adoc Studio renders the subtitle not only in PDF but also in HTML.

Superscript text is frequently used in mathematical expressions and chemical formulas. The formatting character for ^superscript is a caret.

Generally understood as a rule system for combining various characters into natural or artificial systems. The rules of syntax are contrasted with the interpretation rules of semantics. The command set of a language such as AsciiDoc is often referred to as its syntax.

Surrounded by markers, delimiters, and metadata lines, text is the focus of a document and the reason the AsciiDoc syntax gives it so much room to breathe. Text is found most commonly in the lines of a block (e.g., a paragraph), in a block title (e.g., a section title), in list items, and elsewhere. Text is subject to substitutions, which interpret markup as text formatting, replace macros with text or non-text elements, expand attribute references, and perform other kinds of text substitutions.

When text is dragged from the editor or preview to the desktop or a Finder window, adoc Studio automatically creates a text clipping in the corresponding format. This text clipping can in turn be dragged into adoc Studio and other apps to insert the contained text.

A technique that, after entering two or three characters in the editor, recognizes that context-appropriate attributes, macros, or other constructs are possible at the current writing position. The key is that the writer is not blocked but only supported in their writing flow. It is also frequently used to save time.

AsciiDoc provides a set of formatting characters for visually emphasizing content and using typographic punctuation. You can build on these basic formatting characters using built-in and custom roles. Examples include: bold, italic, highlight, etc.

see Encoding

A version control system (such as Git) is used to manage multiple versions of a document space-efficiently. Most version control systems store only the changes needed to recreate a specific version, alongside the original document. Version control also enables multiple people to work on the same document simultaneously.

A product or export that exports a project as a standalone website. The result can be viewed both offline on a local machine and online on a web server.