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 serve to contain other blocks (e.g., multiple paragraphs) or to define the content model of the contained content (e.g., literal text).

In most documents, the paragraph is the most important block type. You do not need to use special marks or attributes to create paragraphs. You can simply start typing sentences. Whether you put each sentence on its own line or write everything continuously, the content will always form a paragraph. A blank line separates paragraphs from each other.

Divides an AsciiDoc document into a content hierarchy. A section is defined by a section title that is preceded by one or more equals signs. The section comprises all content that follows the section title until the next section title of the same or higher level or the end of the document.

Marks the beginning of a section and also serves as the heading for that section. You define the section level by the prefix marker (equals signs). In adoc Studio, the equals signs can be shown in the left margin of the editor.

An abstract is a brief overview or summary of a document. Sometimes the term is also used as a synonym for the preamble.

Admonitions draw attention to specific statements by taking the block or paragraph out of the content flow. You define the presentation using one of five types (NOTE, TIP, IMPORTANT, CAUTION, WARNING). An admonition can be defined as a paragraph or as a block.

The short form for adoc Studio and at the same time the file extension of text files for AsciiDoc.

The name of this app.

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 customary to place them at the end of a document.

An anchor is a link target defined via the ID attribute.

The article is 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. In AsciiDoc, however, ASCII stands for “everything is text — even emoji”. AsciiDoc uses the full Unicode character set.

A mature, lightweight, semantic markup language primarily designed for authoring structured documents. You convert AsciiDoc files to HTML or PDF with programs like adoc Studio or Asciidoctor. The AsciiDoc language was created in 2002 by Stuart Rackham. A reimplementation is Asciidoctor, which has been developed by Dan Allen since 2013. Since 2020, the Eclipse Foundation, together 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 create PDF documents, Asciidoctor PDF is required. Essentially, it’s similar 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 developed by Dan Allen.

Used in AsciiDoc to configure documents and store variables. A document attribute is available from its definition onward in the document. Some attributes must appear at the beginning of a document. Attribute entries are also often 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 by a pair of square brackets. This applies to both element attributes and attributes in a block or inline macro.

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

The author 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 possible.

A document attribute defined by the author, used to store reusable content and to control conditional inclusion.

An independent list of literature references—or the creation or study of such a list. In adoc Studio, it can be used in books and articles.

Defines the structure of the document in an AsciiDoc file. Some blocks can contain other blocks, so the document structure is inherently hierarchical (i.e., a tree). You can see this block structure in the preview, e.g., by enabling the automatic table of contents. Examples of blocks include paragraphs, sections, lists, delimited blocks, tables, and admonitions.

Refers to user-defined blocks that can associate an arbitrary name with one or more contexts. It has a similar function to the style for a built-in block, e.g., an admonition block.

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

see bold

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

Builds on the doctype article and additionally offers the option to use a top-level title as a part title. It contains the appendix, the dedication, the preface, the bibliography, the glossary, the index, and the colophon. A book can either contain only chapters or additionally various parts, which in turn can contain one or more chapters.

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

A set of instructions or a template with settings for styling a document. With different CSS, a document or website with the same content can be presented completely differently. In adoc Studio, both HTML and PDF are styled with CSS. You can also add your own .css files to a project and include them via :stylesheet:.

A document format defined in a document type definition (DTD) available for SGML and 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 feature of AsciiDoc allows you to insert custom content into the head, header, or footer of an output document. This content is read from files known as docinfo files by the converter. Docinfo files conveniently supplement output produced by a converter. Examples include injecting auxiliary metadata, stylesheets, and scripting logic not already supported by the converter.

A file in adoc Studio is called a document. It is plain text. A document can consist of a single sentence (or even a single character, to be academic).

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 user-defined attributes.

Refers to the philosophy that documentation should be written using the same means as a software project’s source code. That means following the same workflows as development teams and integrating them into the product team. This fosters a culture in which both writers and developers feel responsible for the documentation and work together to make it as good as possible.

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

Defines the expected structure of an AsciiDoc document. In adoc Studio, articles (as default) and books are offered.

A program (component) for creating and modifying text. In adoc Studio, the editor is located in the central window area. It provides special features, such as intelligent text completion, to aid writing. The editor can be styled in adoc Studio via a program setting.

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

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

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

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

see Hinweise

The output of an adoc file is produced in a format such as HTML or PDF. An export can have its own styles and attributes that are assigned either in the AsciiDoc document or in the export dialog. The output can be written to a file and optionally shared directly with other programs.

Because adjacent lines of text in AsciiDoc are combined into a paragraph during conversion, you can put each sentence or phrase on its own line. The line breaks do not appear in the output. To separate paragraphs, a single additional blank line is sufficient. This technique is commonly used with the Docs as Code workflow. If you want line breaks to be preserved within a paragraph, you can use a space followed by a plus sign (+), or set the “Hard breaks” option for the paragraph.

Bold text stands out from normal text with a heavier and/or darker typeface. The markup for boldface is an asterisk * before and after the word.

A formatting mark is a symbolic character such as *, _ or ~ that indicates the inline style the AsciiDoc converter should apply to the text. Formatting marks always come in pairs. A formatting pair consists of an identical opening and closing mark that encloses the text to be formatted. The formatted text (i.e., the text enclosed by a formatting pair) may span multiple contiguous lines. The opening mark indicates where formatting begins. The closing mark indicates where 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.

An outline is the division of a whole into several structural parts or areas that are largely self-contained, but cannot be removed from the whole without making it incomplete. adoc Studio contains several outlines: The file navigator and section navigator in the sidebar, the heading structure above the editor, and more.

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

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

see Marking

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

HyperText Markup Language (HTML) is a text-based markup language for structuring electronic documents such as text 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 a document by keywords from an index.

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

The inline doctype enables the AsciiDoc processor to cover the full range of use cases, 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. They are used to format text and perform various types of text substitutions. Inline elements and their syntax are defined in configuration files. Conversion of inline documents is not yet implemented in adoc Studio.

see italic

Software that provides comprehensive writing and knowledge management features for authors and information workers — including adoc Studio. IWEs enable authors and information workers to perform a variety of document-related tasks in a single environment. Ideally, principles like Docs as Code are supported. This ensures a distraction-free workspace and an optimized writing environment.

A content-based subdivision in texts. In adoc Studio, we refer to files in composite documents as chapters.

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

see Encoding

An element of a book, usually found at the end. It includes information such as content, author, place, time, manufacturer, client, and production details of the publication.

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

Text is often set in italics to emphasize a word or sentence, to quote a speaker, or to introduce a term. Italic text is slightly slanted to the right and may, depending on the font, have cursive flourishes and swashes. The markup for italic is an underscore.

tbd:

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

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

Syntax for representing non-text elements or syntax that, using the provided metadata, turns into text. 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 simplified markup language published in December 2004 by John Gruber and Aaron Swartz.

Another way to draw attention to text is to highlight it with a mark. This semantic style is used for reference or notation purposes, or to emphasize the importance of a key topic or point. The markup for marking is a hash #.

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

Structured data that includes overarching information about a resource — such as books, web documents, videos, or images. For a document, examples include a description of the document, 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 elements contained in the <head> section of an HTML document.

In technical content, text often needs to be styled to indicate a command or source code. Such text is typically set in a fixed-width (i.e., monospace) font. The markup for monospace is a backtick `.

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

A parser is a computer program responsible for breaking down and transforming 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.

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

In IT, denotes data that is unformatted, human-readable, and can therefore be directly represented as text using characters. The AsciiDoc documents in adoc Studio use plaintext.

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

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 arbitrary condition (ifeval). An include directive can add lines to the document that originate from another document.

see Preprocessor Directive

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

In adoc Studio, text is separated from styling. A technique is therefore needed to connect the two. This task is handled by product styles. A product style is a file bundle that contains at least an information file and the style file in CSS format. Optionally, additional resources such as media or fonts may be included.

In adoc Studio, a project is a collection of all AsciiDoc files and folders, including media folders. Projects can also contain other files such as CSS files. They are organized and managed in adoc Studio via the project navigator. Additionally, a continuous synchronization with the directory in the operating system takes place. Thus, the project can also be modified in the Finder.

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

A link from a given place to another position in the document marked by an anchor.

You can assign one or more roles to blocks and most other inline elements using the role attribute. A role adds additional semantics to an element, for example to assign an additional style (via a CSS selector).

A proprietary text file format introduced by Microsoft in 1987. It can serve as an interchange format between word processors 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 selectable for export and within products.

A distinct document type in adoc Studio, in contrast to standalone documents. It collects many chapters into a large document. Within a composite document, many folders and media folders can be created for further structuring. Any folder can be selected to show the chapters beneath it combined in the preview. Attributes defined anywhere in the composite document can be used in any chapter of the composite document.

see Keywords

see Section

Roughly comparable to a template. The idea is to separate text from presentation. The program that evaluates the stylesheet interprets the assigned data (text, tables, graphics, etc.) and formats it according to the rules. Cascading Style Sheets are the best-known example of a stylesheet. In adoc Studio, custom stylesheets can be added to the project as .css files and used via the attribute :stylesheet:.

A document title can be supplemented by a second title (also called a subtitle). Contrary to the AsciiDoc definition, in adoc Studio this is set not only in PDF but also in HTML.

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

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

Surrounded by marks, delimiters, and metadata lines lies the text. Text is the focus of a document and the reason why the AsciiDoc syntax gives it so much room to breathe. Text is most often found in the lines of a block (e.g., paragraph), in the block title (e.g., section title), and in list items, but also elsewhere. 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 types of text substitutions. Normal text is subject to all substitutions unless otherwise noted. Literal text is subject to a minimal set of substitutions so it appears in the output as it does in the source. It is also possible to disable all substitutions to pass the text through unchanged (i.e., raw). Parsing text consists of a mixture of inline elements and other forms of transformations.

When text from the editor or the preview is dragged 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 there.

AsciiDoc provides a set of formatting marks that let you visually emphasize your document and use typographic punctuation. You can build on these basic formatting marks using built-in and custom roles. Examples include: bold, italic, highlight, etc.

A technique that, after typing two to three letters in the editor, recognizes that attributes, macros, or other items relevant to the current context are possible at the cursor position. The key is not to block the writer’s flow, but only to assist. It is also often used to save time.

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

An environment attribute is a dynamic document attribute that relates to or provides information about the runtime environment.

see Encoding

A version control system (such as Git) manages multiple versions of a document efficiently. In most systems, besides the original document, only the changes required to produce a given version are stored. Version control also enables collaborative work on the same document.

A predefined attribute is a document attribute defined for convenience. It is often used to insert special characters for content.

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.

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

Is a product or an export that creates from a project a standalone website. The result can be viewed both offline, on the local machine, and online on a web server.

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

AsciiDoc is a line-oriented language, hence the line is an important construct. A line is defined as text bounded on both sides either by a line break or by the document boundary. Many aspects of the syntax must occupy an entire line. When working according to Docs as Code, the individual line is particularly important because changes to it are easier to detect in Git.

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

see Abstract