Introduction This document provides guidance on the use of the AsciiDoc® markup language for producing The Open Group publications. It should be read in conjunction with A Handbook for Publications Development [I153]. Imagine if writing documentation was as simple as writing an email. It can be. That is the idea behind lightweight markup languages such as AsciiDoc. They offer a plain-text syntax, embellished with subtle, yet intuitive markup, that is designed for humans to read, write, and edit in raw form. The natural feel of the syntax keeps you focused on the content. Best of all, the plain text can quickly and easily be translated into output formats such as HTML5 and PDF. Source: Asciidoctor website: asciidoctor.org/docs/what-is-asciidoc/ Overview The AsciiDoc markup language is a lightweight, human-readable markup language used for writing structured documents. The key features of the language are as follows: Plain text syntax: Easy to write and read without special tools Rich formatting: Supports headings, lists, tables, code blocks, footnotes, cross-references, and more Modular documents: Allows content reuse through includes and variables Multiple output formats: Can be converted into HTML, PDF, EPUB, DocBook, and other formats Ideal for technical writing: Popular for documentation, books, and articles It is used to build The Open Group documents in a number of formats, including HTML, PDF, ePUB, and outputs to be used with Antora generated websites. What is Antora? Antora is a modular documentation site generator built specifically for technical writers and developers who write in the AsciiDoc markup language. It is designed to manage large, versioned, multi-repository documentation projects using a docs-as-code approach. Two examples of its use within The Open Group include the Portfolio of Digital Open Standards [WEB1] and The Open Group Standards Process Guide [WEB2]. What Is a Markup Language? A markup language is an approach to document development that tells computers how to structure, format, or display it. Instead of focusing on how content looks, markup languages describe what the text content is (such as headings, lists, links, or emphasis). They are widely used in web development, documentation, publishing, and data exchange. Examples include HTML for web pages, Markdown for lightweight documentation, AsciiDoc for technical writing, and XML for data storage and transport. The Pros of Using a Markup Language Human-readable: Most markup languages are easy to write and understand Portable: Content can be rendered in multiple formats (HTML, PDF, etc.) from the same source Separation of content and presentation: Encourages clean, maintainable documents Version control-friendly: Plain text works well with Git™ and other tools Automation-ready: Easily parsed and manipulated by scripts and tools, for build automation The Cons of Using a Markup Language Learning curve: The language can be complex to learn Not “What You See Is What You Get” (WYSIWYG): A preview tool or renderer is needed to see the output Error-prone: Small syntax mistakes can break formatting or output Basic AsciiDoc Examples for Beginners As an introduction to the AsciiDoc markup language, we include some basic examples in the following sections. Headings = Document Title == Section Level 1 === Section Level 2 ==== Section Level 3 *Unnumbered Heading* Paragraphs and Emphasis This is a normal paragraph. *Bold text* and _italic text_ are easy. Produces: This is a normal paragraph. Bold text and italic text are easy. Lists * Unordered Item 1 * Unordered Item 2 . Ordered Item 1 . Ordered Item 2 Produces: Unordered Item 1 Unordered Item 2 Ordered Item 1 Ordered Item 2 Links https://asciidoctor.org[Visit Asciidoctor] Produces: Visit Asciidoctor Code Blocks [source, ruby] ---- puts 'Hello, World!' ---- Produces: puts 'Hello, World!' Images image::hello-world.png[Hello World Image] Produces: Blockquotes [quote, Albert Einstein] ____ Imagination is more important than knowledge. ____ Produces: Imagination is more important than knowledge. — Albert Einstein Admonitions (Notes, Tips, Warnings) NOTE: This is a helpful note. TIP: You can use `asciidoctor` to convert your file to HTML. WARNING: Do not forget to install required diagram tools! Produces: This is a helpful note. You can use asciidoctor to convert your file to HTML. Do not forget to install required diagram tools! Tables [%header, cols=3*] .Staff Roles and Locations |=== | Name | Role | Location | Alice | Developer | London | Bob | Designer | Manchester | Carol | Manager | Bristol |=== Produces: Table 1. Staff Roles and Locations Name Role Location Alice Developer London Bob Designer Manchester Carol Manager Bristol Referenced Documents Style Usage