diff --git a/.editorconfig b/.editorconfig
deleted file mode 100644
index 9d08a1a8..00000000
--- a/.editorconfig
+++ /dev/null
@@ -1,9 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-indent_style = space
-indent_size = 2
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
diff --git a/.eslintignore b/.eslintignore
deleted file mode 100644
index 2cf1da45..00000000
--- a/.eslintignore
+++ /dev/null
@@ -1,2 +0,0 @@
-dist
-build
\ No newline at end of file
diff --git a/.eslintrc.js b/.eslintrc.js
deleted file mode 100644
index 142d6f99..00000000
--- a/.eslintrc.js
+++ /dev/null
@@ -1,53 +0,0 @@
-module.exports = {
- root: true,
- env: {
- node: true
- },
- parser: 'vue-eslint-parser',
- parserOptions: {
- parser: '@typescript-eslint/parser'
- },
- extends: [
- '@vue/eslint-config-standard',
- 'plugin:vue/vue3-recommended',
- 'plugin:@typescript-eslint/recommended'
- ],
- plugins: ['@typescript-eslint', 'prettier'],
- rules: {
- 'no-console': process.env.NODE_ENV === 'production' ? 'error' : 'off',
- 'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
- 'vue/component-name-in-template-casing': ['error', 'PascalCase'],
- 'arrow-parens': ['error', 'as-needed'],
- 'no-unused-vars': 'off',
- 'no-undef': 'off',
- 'vue/no-v-html': 'off',
- 'vue/require-prop-types': 'off',
- 'vue/require-default-prop': 'off',
- 'vue/multi-word-component-names': 'off',
- '@typescript-eslint/semi': ['error', 'never'],
- '@typescript-eslint/member-delimiter-style': [
- 'error',
- { multiline: { delimiter: 'none' } }
- ],
- '@typescript-eslint/type-annotation-spacing': ['error', {}],
- '@typescript-eslint/consistent-type-imports': [
- 'error',
- { prefer: 'type-imports', disallowTypeAnnotations: false }
- ],
- '@typescript-eslint/camelcase': 'off',
- '@typescript-eslint/explicit-function-return-type': 'off',
- '@typescript-eslint/explicit-member-accessibility': 'off',
- '@typescript-eslint/no-explicit-any': 'off',
- '@typescript-eslint/no-parameter-properties': 'off',
- '@typescript-eslint/no-empty-interface': 'off',
- '@typescript-eslint/ban-ts-ignore': 'off',
- '@typescript-eslint/no-empty-function': 'off',
- '@typescript-eslint/no-non-null-assertion': 'off',
- '@typescript-eslint/ban-ts-comment': 'off',
- '@typescript-eslint/explicit-module-boundary-types': 'off',
- '@typescript-eslint/ban-types': 'off',
- '@typescript-eslint/no-namespace': 'off',
- indent: 'off',
- '@typescript-eslint/indent': ['error', 2]
- }
-}
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
index 9791d842..60a44906 100644
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -10,4 +10,4 @@ liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-custom: ['paypal.me/antongithub', antonreshetov.gumroad.com/l/masscode]
+custom: [paypal.me/antongithub, antonreshetov.gumroad.com/l/masscode]
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index f86f7726..e2c913cb 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -1,6 +1,6 @@
-name: "\U0001F41E Bug report"
+name: 🐞 Bug report
description: Report an issue with massCode
-title: "[Bug]: "
+title: '[Bug]: '
labels: [pending triage]
body:
- type: markdown
@@ -53,4 +53,4 @@ body:
- label: Check that there isn't [already an issue](https://github.com/massCodeIO/massCode/issues) that reports the same bug to avoid creating a duplicate.
required: true
- label: Check that this is a concrete bug. For Q&A open a [GitHub Discussion](https://github.com/massCodeIO/massCode/discussions).
- required: true
\ No newline at end of file
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 14a17a2c..f8761111 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -2,4 +2,4 @@ blank_issues_enabled: false
contact_links:
- name: Questions & Discussions
url: https://github.com/massCodeIO/massCode/discussions
- about: Use GitHub discussions for message-board style questions and discussions.
\ No newline at end of file
+ about: Use GitHub discussions for message-board style questions and discussions.
diff --git a/.github/assets/logo.png b/.github/assets/logo.png
new file mode 100644
index 00000000..78f71df0
Binary files /dev/null and b/.github/assets/logo.png differ
diff --git a/.github/workflows/issue-close-require.yml b/.github/workflows/issue-close-require.yml
index 58a7e664..d80cc449 100644
--- a/.github/workflows/issue-close-require.yml
+++ b/.github/workflows/issue-close-require.yml
@@ -2,7 +2,7 @@ name: Issue Close Require
on:
schedule:
- - cron: "0 0 * * *"
+ - cron: '0 0 * * *'
jobs:
close-issues:
@@ -11,7 +11,7 @@ jobs:
- name: need reproduction
uses: actions-cool/issues-helper@v3
with:
- actions: "close-issues"
+ actions: close-issues
token: ${{ secrets.GITHUB_TOKEN }}
- labels: "need reproduction"
- inactive-day: 3
\ No newline at end of file
+ labels: need reproduction
+ inactive-day: 3
diff --git a/.github/workflows/issue-labeled.yml b/.github/workflows/issue-labeled.yml
index 4783fe2a..43512f75 100644
--- a/.github/workflows/issue-labeled.yml
+++ b/.github/workflows/issue-labeled.yml
@@ -13,9 +13,9 @@ jobs:
if: github.event.label.name == 'need reproduction'
uses: actions-cool/issues-helper@v3
with:
- actions: "create-comment, remove-labels"
+ actions: 'create-comment, remove-labels'
token: ${{ secrets.GITHUB_TOKEN }}
issue-number: ${{ github.event.issue.number }}
body: |
- Hello @${{ github.event.issue.user.login }}. Please describe in detail the sequence of actions that leads to the bug (skip it if it's already there). Add screenshots of errors from the console. If possible add a video. Issues marked with `need reproduction` will be closed if they have no activity within 3 days.
- labels: "pending triage"
+ Hello @${{ github.event.issue.user.login }}. Please describe in detail the sequence of actions that leads to the bug (skip it if it's already there). Add screenshots of errors from the console. If possible add a video. Issues marked with `need reproduction` will be closed if they have no activity within 3 days.
+ labels: pending triage
diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml
index 28fa0604..37ac48af 100644
--- a/.github/workflows/release-tag.yml
+++ b/.github/workflows/release-tag.yml
@@ -3,7 +3,7 @@ name: Add GitHub Release Tag
on:
push:
tags:
- - "v*" # Push events to matching v*, i.e. v1.0, v20.15.10
+ - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
jobs:
build:
@@ -23,4 +23,4 @@ jobs:
with:
tag_name: ${{ github.ref }}
draft: true
- preset: angular # Use conventional-changelog preset
\ No newline at end of file
+ preset: angular # Use conventional-changelog preset
diff --git a/.gitignore b/.gitignore
index a2ac8086..1e796700 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,12 +1,10 @@
-node_modules
dist
-build
+build/main
+build/renderer
+scripts/build-sponsored.sh
-.vscode
-.idea
+node_modules
.DS_Store
-src/renderer/types/auto-imports.d.ts
-src/renderer/types/components.d.ts
-*.log
-*.local
-.env
+components.d.ts
+auto-imports.d.ts
+.github/*-instructions.md
\ No newline at end of file
diff --git a/.husky/.gitignore b/.husky/.gitignore
deleted file mode 100644
index 31354ec1..00000000
--- a/.husky/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-_
diff --git a/.husky/commit-msg b/.husky/commit-msg
deleted file mode 100755
index d71a03b9..00000000
--- a/.husky/commit-msg
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-yarn commitlint --edit $1
diff --git a/.husky/pre-commit b/.husky/pre-commit
deleted file mode 100755
index d2ae35e8..00000000
--- a/.husky/pre-commit
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-yarn lint-staged
diff --git a/.npmrc b/.npmrc
deleted file mode 100644
index cc8df9de..00000000
--- a/.npmrc
+++ /dev/null
@@ -1 +0,0 @@
-node-linker=hoisted
\ No newline at end of file
diff --git a/.prettierrc b/.prettierrc
index 49955e2e..8b0bc4ef 100644
--- a/.prettierrc
+++ b/.prettierrc
@@ -1,5 +1,3 @@
{
- "semi": false,
- "singleQuote": true,
- "trailingComma": "none"
-}
+ "plugins": ["prettier-plugin-tailwindcss"]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
index f61e34b9..797ad0fc 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,5 @@
-
-
+
massCode
@@ -11,7 +10,6 @@
Inspired by applications like SnippetsLab and Quiver.
-
@@ -27,8 +25,7 @@
Extensions:
VS Code |
- Raycast |
- Alfred
+ Raycast
@@ -47,10 +44,11 @@
## Support
-massCode is open source project and completely free to use.
+massCode is an open-source project and completely free to use.
-However, the amount of effort needed to maintain and develop new features for the project is not sustainable without proper financial backing. You can support massCode development via the following methods:
+Maintaining and adding new features requires significant time and effort. If you find massCode useful, consider supporting its development. Your contribution helps keep the project alive and moving forward.
+You can support massCode through the following channels:
[](https://opencollective.com/masscode)
@@ -60,54 +58,60 @@ However, the amount of effort needed to maintain and develop new features for th
## Features
+
### Organization
-massCode allows you to organize snippets using multi-level folders as well as tags. Each snippet has fragments - tabs, which gives even greater level of organization.
+
+Organize your snippets with multi-level folders and tags. Each snippet can contain multiple fragments (tabs), giving you fine-grained control over structure and grouping.
### Editor
-massCode uses [Codemirror](https://github.com/codemirror/codemirror5) as the basis for the editor and `.tmLanguage` as the grammar for syntax highlighting. This tandem opens the door to over [600](https://github.com/github/linguist/blob/master/vendor/README.md) existing grammars. The application currently supports more than [160](https://github.com/massCodeIO/massCode/tree/master/src/renderer/components/editor) grammars. In addition to `.tmLanguage`, the application supports `.tmTheme` for themes. There is also support for [Prettier](https://prettier.io) for code formatting.
-### Real-time Render for HTML & CSS
-You can not only collect snippets, but also see the rendering result for HTML and CSS in real time. Test the idea or just view the result.
+Built on [CodeMirror](https://github.com/codemirror/codemirror5) with `.tmLanguage` grammars for syntax highlighting.
-### Markdown
-massCode allows you to write in Markdown and provide support to syntax highlighting, tables, list and other formatting. Also massCode supports [Mermaid](https://mermaid-js.github.io/mermaid/#) - diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.
+* Supports over [600 grammars](https://github.com/github/linguist/blob/master/vendor/README.md), with 160+ available out of the box.
+* Integrated [Prettier](https://prettier.io) for clean, consistent code formatting.
-### Presentation Mode
+### Real-time HTML & CSS Preview
-massCode allows you to make a presentation out of a sequence of snippets. It's great for classroom use, team meetings, conferences or simply reviewing notes on your own.
+Write and instantly preview HTML and CSS snippets. Perfect for prototyping, testing ideas, or quick visual checks.
-### Mindmap
+### Markdown
-massCode allows you to create mental maps from markdown, making the process of creating and editing maps fast and intuitively understandable. It's a great way to organize and structure information visually.
+Full Markdown support with syntax highlighting, tables, lists, and more.
-### Search
-It is impossible to imagine a productive snippets manager without quick access to snippets. Therefore massCode has a fast full-text search with highlighting of the search query.
+* Integrated [Mermaid](https://mermaid-js.github.io/mermaid/#) for dynamic diagrams and charts.
-### Autosave
-massCode automatically saves any changes you make during work, so you don't have to worry about losing changes.
+### Presentation Mode
-### Sync
-You can use any service that provides cloud synchronization, such as iCloud Drive, Google Drive, Dropbox or other similar.
+Turn a sequence of snippets into a presentation. Useful for classrooms, team meetings, conference talks, or simply walking through your own notes.
-### Database
-massCode uses a simple JSON to store your data. The database files are on your local computer.
+### Mindmap
+
+Generate mind maps from Markdown. Fast, intuitive, and ideal for structuring and visualizing ideas.
### Integrations
-massCode supports extensions for [VS Code](https://marketplace.visualstudio.com/items?itemName=AntonReshetov.masscode-assistant), [Raycast](https://www.raycast.com/antonreshetov/masscode) and [Alfred](https://github.com/massCodeIO/assistant-alfred), which gives even more possibilities to use application. With the VS Code extension you get practically zen mode, search for the necessary snippets and insert them immediately or save the selected code sections as a snippet.
+
+Extend your workflow with:
+
+* [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=AntonReshetov.masscode-assistant): zen mode snippet search, instant insertion, and save selected code as snippets.
+* [Raycast Extension](https://www.raycast.com/antonreshetov/masscode): quick snippet access directly from Raycast.
### Beautiful Screenshots
-Create beautiful snippet images on different backgrounds and in different modes
+
+Export snippets as polished images with customizable themes and backgrounds.
### Developer Tools
-massCode provides developers with a range of convenient tools, such as:
-- Text tools: Case Converter, Slug Generator, Sort Lines, URL Parser
-- Cryptography & Security: Hash, HMAC, Password and UUID Generators
-- Encoders & Decoders: URL, Base64
+Handy built-in utilities for everyday dev tasks:
+
+* **Text Tools**: Case Converter, Slug Generator, URL Parser
+* **Crypto & Security**: Hash/HMAC, Password Generator, UUID
+* **Encoders/Decoders**: URL, Base64, JSON ⇄ TOML/XML/YAML, Text ⇄ ASCII/Binary/Unicode, Color Converter
+
+---
## Overview
-The goal of creating this application was mostly my own growth as a developer. Also, I wanted this project to absorb the best of such applications already on the market (both free and paid). At the same time, I wanted this project to be an open source project.
+massCode was created as a personal learning project and evolved into an open-source tool. The goal: combine the best features of snippet managers (free and paid) into one flexible, developer-friendly application.
## Follow
- News and updates on [Twitter](https://twitter.com/anton_reshetov).
@@ -115,11 +119,8 @@ The goal of creating this application was mostly my own growth as a developer. A

-## Other
-You can also [download](https://github.com/antonreshetov/massCode) massCode v1.
-
## License
[AGPL-3.0](https://github.com/massCodeIO/massCode/blob/master/LICENSE)
-Copyright (c) 2019-present, [Anton Reshetov](https://github.com/antonreshetov).
\ No newline at end of file
+Copyright (c) 2019-present, [Anton Reshetov](https://github.com/antonreshetov).
diff --git a/entitlements.mac.inherit.plist b/build/entitlements.mac.inherit.plist
similarity index 100%
rename from entitlements.mac.inherit.plist
rename to build/entitlements.mac.inherit.plist
diff --git a/build/icons/256x256.png b/build/icons/256x256.png
new file mode 100644
index 00000000..8afef6d5
Binary files /dev/null and b/build/icons/256x256.png differ
diff --git a/build/icons/icon.icns b/build/icons/icon.icns
new file mode 100644
index 00000000..38f41a03
Binary files /dev/null and b/build/icons/icon.icns differ
diff --git a/build/icons/icon.ico b/build/icons/icon.ico
new file mode 100644
index 00000000..1993db0a
Binary files /dev/null and b/build/icons/icon.ico differ
diff --git a/commitlint.config.js b/commitlint.config.js
index b2894ad6..5c4a9e1b 100644
--- a/commitlint.config.js
+++ b/commitlint.config.js
@@ -10,15 +10,14 @@ module.exports = {
'docs',
'feat',
'fix',
- 'perf',
'polish',
'refactor',
'release',
'revert',
'style',
'test',
- 'types'
- ]
- ]
- }
+ 'types',
+ ],
+ ],
+ },
}
diff --git a/config/electron-builder.ts b/config/electron-builder.ts
deleted file mode 100644
index e2f85055..00000000
--- a/config/electron-builder.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-/* eslint-disable no-template-curly-in-string */
-import type { Configuration } from 'electron-builder'
-import path from 'path'
-
-const isSponsored = process.env.VITE_SPONSORED === 'true'
-const isTestBuild = process.env.TEST_BUILD === 'true'
-const testMacArch = process.env.TEST_MAC_ARCH
-
-const artifactName = isSponsored
- ? '${productName}-${version}-${arch}-sponsored.${ext}'
- : undefined
-
-const macTarget = [
- { target: 'dmg', arch: 'arm64' },
- { target: 'dmg', arch: 'x64' }
-]
-
-if (isTestBuild) {
- if (testMacArch === 'arm64') macTarget.pop()
- if (testMacArch === 'x64') macTarget.shift()
-}
-
-export default {
- appId: 'io.masscode.app',
- artifactName,
- productName: 'massCode',
- directories: {
- output: path.resolve(__dirname, '../../dist')
- },
- // afterSign: !isTestBuild ? 'build/scripts/notarize.js' : undefined,
- nsis: {
- oneClick: false,
- perMachine: false,
- allowToChangeInstallationDirectory: true,
- shortcutName: 'massCode'
- },
- mac: {
- target: macTarget,
- icon: 'config/icons/icon.icns',
- category: 'public.app-category.productivity',
- hardenedRuntime: true,
- entitlements: 'build/entitlements.mac.inherit.plist'
- },
- win: {
- target: 'nsis',
- icon: 'config/icons/icon.ico'
- },
- linux: {
- target: ['snap'],
- icon: 'config/icons'
- },
- extraMetadata: {
- main: 'src/main/index.js'
- },
- protocols: [
- {
- name: 'massCode',
- schemes: ['masscode']
- }
- ],
- files: [
- '!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}',
- '!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}',
- '!**/node_modules/*.d.ts',
- '!**/node_modules/.bin',
- '!config',
- '!README.md',
- '!scripts',
- '!dist',
- '!src',
- '!build',
- '!hero.png',
- '!commitlint.config.js',
- '!tsconfig.electron.json',
- '!tsconfig.json',
- {
- from: 'build/renderer',
- to: 'renderer',
- filter: ['**/*']
- },
- {
- from: 'build/src',
- to: 'src',
- filter: ['**/*']
- }
- ]
-} as Configuration
diff --git a/config/icons/256x256.png b/config/icons/256x256.png
deleted file mode 100644
index ce728acb..00000000
Binary files a/config/icons/256x256.png and /dev/null differ
diff --git a/config/icons/icon.icns b/config/icons/icon.icns
deleted file mode 100644
index c12d909f..00000000
Binary files a/config/icons/icon.icns and /dev/null differ
diff --git a/config/icons/icon.ico b/config/icons/icon.ico
deleted file mode 100644
index c98a94a9..00000000
Binary files a/config/icons/icon.ico and /dev/null differ
diff --git a/config/vite.ts b/config/vite.ts
deleted file mode 100644
index ceecafb0..00000000
--- a/config/vite.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import path from 'path'
-import vuePlugin from '@vitejs/plugin-vue'
-import { defineConfig } from 'vite'
-import AutoImport from 'unplugin-auto-import/vite'
-import Components from 'unplugin-vue-components/vite'
-import Icons from 'unplugin-icons/vite'
-import { FileSystemIconLoader } from 'unplugin-icons/loaders'
-import IconsResolver from 'unplugin-icons/resolver'
-
-const pathSrc = path.resolve(__dirname, '../../src/renderer')
-const pathOut = path.resolve(__dirname, '../renderer')
-
-export default defineConfig({
- root: pathSrc,
- publicDir: 'public',
- server: {
- port: 8080,
- open: false
- },
- build: {
- outDir: pathOut,
- emptyOutDir: true,
- target: 'esnext'
- },
- define: {
- // прокладка для pseudomap при билде
- 'process.env.TEST_PSEUDOMAP': {}
- },
- plugins: [
- vuePlugin(),
- AutoImport({
- dts: `${pathSrc}/types/auto-imports.d.ts`
- }),
- Components({
- dts: `${pathSrc}/types/components.d.ts`,
- dirs: [`${pathSrc}/components`],
- resolvers: [
- IconsResolver({
- prefix: '',
- customCollections: ['unicons', 'svg']
- })
- ]
- }),
- Icons({
- customCollections: {
- unicons: FileSystemIconLoader(
- './node_modules/@iconscout/unicons/svg/line'
- ),
- svg: FileSystemIconLoader(pathSrc + '/assets/svg')
- }
- })
- ],
- resolve: {
- alias: {
- '@': pathSrc
- }
- }
-})
diff --git a/demo/db/db.json b/demo/db/db.json
deleted file mode 100644
index dd8d921a..00000000
--- a/demo/db/db.json
+++ /dev/null
@@ -1,2879 +0,0 @@
-{
- "folders": [
- {
- "id": "J7rNZi7X",
- "name": "Test Grammars",
- "defaultLanguage": "typescript",
- "parentId": null,
- "isOpen": false,
- "isSystem": false,
- "createdAt": 1659494503299,
- "updatedAt": 1659494610605
- }
- ],
- "snippets": [
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "ABAP",
- "content": [
- {
- "label": "Fragment 1",
- "language": "abap",
- "value": "***************************************\n** Program: EXAMPLE **\n** Author: Joe Byte, 07-Jul-2007 **\n***************************************\n \nREPORT BOOKINGS.\n \n* Read flight bookings from the database\nSELECT * FROM FLIGHTINFO\n WHERE CLASS = 'Y' \"Y = economy\n OR CLASS = 'C'. \"C = business\n(...)\n\nREPORT TEST.\nWRITE 'Hello World'.\n\nUSERPROMPT = 'Please double-click on a line in the output list ' &\n 'to see the complete details of the transaction.'.\n\n\nDATA LAST_EOM TYPE D. \"last end-of-month date\n \n* Start from today's date\n LAST_EOM = SY-DATUM.\n* Set characters 6 and 7 (0-relative) of the YYYYMMDD string to \"01\",\n* giving the first day of the current month\n LAST_EOM+6(2) = '01'.\n* Subtract one day\n LAST_EOM = LAST_EOM - 1.\n \n WRITE: 'Last day of previous month was', LAST_EOM.\n \nDATA : BEGIN OF I_VBRK OCCURS 0,\n VBELN LIKE VBRK-VBELN,\n ZUONR LIKE VBRK-ZUONR,\n END OF I_VBRK.\n\nSORT i_vbrk BY vbeln ASCENDING.\nSORT i_vbrk BY vbeln DESCENDING.\n\nRETURN."
- }
- ],
- "id": "JMINV1s7",
- "createdAt": 1659494546718,
- "updatedAt": 1659494556760
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "ABC",
- "content": [
- {
- "label": "Fragment 1",
- "language": "abc",
- "value": "%abc-2.1\nH:This file contains some example English tunes\n% note that the comments (like this one) are to highlight usages\n% and would not normally be included in such detail\nO:England % the origin of all tunes is England\n\nX:1 % tune no 1\nT:Dusty Miller, The % title\nT:Binny's Jig % an alternative title\nC:Trad. % traditional\nR:DH % double hornpipe\nM:3/4 % meter\nK:G % key\nB>cd BAG|FA Ac BA|B>cd BAG|DG GB AG:|\nBdd gfg|aA Ac BA|Bdd gfa|gG GB AG:|\nBG G/2G/2G BG|FA Ac BA|BG G/2G/2G BG|DG GB AG:|\nW:Hey, the dusty miller, and his dusty coat;\nW:He will win a shilling, or he spend a groat.\nW:Dusty was the coat, dusty was the colour;\nW:Dusty was the kiss, that I got frae the miller.\n\nX:2\nT:Old Sir Simon the King\nC:Trad.\nS:Offord MSS % from Offord manuscript\nN:see also Playford % reference note\nM:9/8\nR:SJ % slip jig\nN:originally in C % transcription note\nK:G\nD|GFG GAG G2D|GFG GAG F2D|EFE EFE EFG|A2G F2E D2:|\nD|GAG GAB d2D|GAG GAB c2D|[1 EFE EFE EFG|[A2G] F2E D2:|\\ % no line-break in score\nM:12/8 % change of meter\n[2 E2E EFE E2E EFG|\\ % no line-break in score\nM:9/8 % change of meter\nA2G F2E D2|]\n\nX:3\nT:William and Nancy\nT:New Mown Hay\nT:Legacy, The\nC:Trad.\nO:England; Gloucs; Bledington % place of origin\nB:Sussex Tune Book % can be found in these books\nB:Mally's Cotswold Morris vol.1 2\nD:Morris On % can be heard on this record\nP:(AB)2(AC)2A % play the parts in this order\nM:6/8\nK:G \n[P:A] D|\"G\"G2G GBd|\"C\"e2e \"G\"dBG|\"D7\"A2d \"G\"BAG|\"C\"E2\"D7\"F \"G\"G2:|\n[P:B] d|\"G\"e2d B2d|\"C\"gfe \"G\"d2d| \"G\"e2d B2d|\"C\"gfe \"D7\"d2c|\n \"G\"B2B Bcd|\"C\"e2e \"G\"dBG|\"D7\"A2d \"G\"BAG|\"C\"E2\"D7\"F \"G\"G2:|\n% changes of meter, using inline fields\n[T:Slows][M:4/4][L:1/4][P:C]\"G\"d2|\"C\"e2 \"G\"d2|B2 d2|\"Em\"gf \"A7\"e2|\"D7\"d2 \"G\"d2|\\\n \"C\"e2 \"G\"d2|[M:3/8][L:1/8] \"G\"B2 d |[M:6/8] \"C\"gfe \"D7\"d2c|\n \"G\"B2B Bcd|\"C\"e2e \"G\"dBG|\"D7\"A2d \"G\"BAG|\"C\"E2\"D7\"F \"G\"G2:|\n\nX:4\nT:South Downs Jig\nR:jig\nS:Robert Harbron\nM:6/8\nL:1/8\nK:G\n|: d | dcA G3 | EFG AFE | DEF GAB | cde d2d |\ndcA G3 | EFG AFE | DEF GAB | cAF G2 :|\nB | Bcd e2c | d2B c2A | Bcd e2c | [M:9/8]d2B c2B A3 |\n[M:6/8]DGF E3 | cBA FED | DEF GAB |1 cAF G2 :|2 cAF G3 |]\n\nX:5\nT:Atholl Brose\n% in this example, which reproduces Highland Bagpipe gracing,\n% the large number of grace notes mean that it is more convenient to be specific about\n% score line-breaks (using the $ symbol), rather than using code line breaks to indicate them\nI:linebreak $\nK:D\n{gcd}c<{e}A {gAGAG}A2 {gef}e>A {gAGAG}Ad|\n{gcd}c<{e}A {gAGAG}A>e {ag}a>f {gef}e>d|\n{gcd}c<{e}A {gAGAG}A2 {gef}e>A {gAGAG}Ad|\n{g}c/d/e {g}G>{d}B {gf}gG {dc}d>B:|$\n{g}ce {ag}a>e {gf}g>e|\n{g}ce {ag}a2 {GdG}a>d|\n{g}ce {ag}a>e {gf}g>f|\n{gef}e>d {gf}g>d {gBd}B<{e}G {dc}d>B|\n{g}ce {ag}a>e {gf}g>e|\n{g}ce {ag}a2 {GdG}ad|\n{g}c<{GdG}e {gf}ga {f}g>e {g}f>d|\n{g}e/f/g {Gdc}d>c {gBd}B<{e}G {dc}d2|]\n\nX:6\nT:Untitled Reel\nC:Trad.\nK:D\neg|a2ab ageg|agbg agef|g2g2 fgag|f2d2 d2:|\\\ned|cecA B2ed|cAcA E2ed|cecA B2ed|c2A2 A2:|\nK:G\nAB|cdec BcdB|ABAF GFE2|cdec BcdB|c2A2 A2:|\n\nX:7\nT:Kitchen Girl\nC:Trad.\nK:D\n[c4a4] [B4g4]|efed c2cd|e2f2 gaba|g2e2 e2fg|\na4 g4|efed cdef|g2d2 efed|c2A2 A4:|\nK:G\nABcA BAGB|ABAG EDEG|A2AB c2d2|e3f edcB|ABcA BAGB|\nABAG EGAB|cBAc BAG2|A4 A4:|\n\n%abc-2.1\n%%pagewidth 21cm\n%%pageheight 29.7cm\n%%topspace 0.5cm\n%%topmargin 1cm\n%%botmargin 0cm\n%%leftmargin 1cm\n%%rightmargin 1cm\n%%titlespace 0cm\n%%titlefont Times-Bold 32\n%%subtitlefont Times-Bold 24\n%%composerfont Times 16\n%%vocalfont Times-Roman 14\n%%staffsep 60pt\n%%sysstaffsep 20pt\n%%musicspace 1cm\n%%vocalspace 5pt\n%%measurenb 0\n%%barsperstaff 5\n%%scale 0.7\nX: 1\nT: Canzonetta a tre voci\nC: Claudio Monteverdi (1567-1643)\nM: C\nL: 1/4\nQ: \"Andante mosso\" 1/4 = 110\n%%score [1 2 3]\nV: 1 clef=treble name=\"Soprano\"sname=\"A\"\nV: 2 clef=treble name=\"Alto\" sname=\"T\"\nV: 3 clef=bass middle=d name=\"Tenor\" sname=\"B\"\n%%MIDI program 1 75 % recorder\n%%MIDI program 2 75\n%%MIDI program 3 75\nK: Eb\n% 1 - 4\n[V: 1] |:z4 |z4 |f2ec |_ddcc |\nw: Son que-sti~i cre-spi cri-ni~e\nw: Que-sti son gli~oc-chi che mi-\n[V: 2] |:c2BG|AAGc|(F/G/A/B/)c=A|B2AA |\nw: Son que-sti~i cre-spi cri-ni~e que - - - - sto~il vi-so e\nw: Que-sti son~gli oc-chi che mi-ran - - - - do fi-so mi-\n[V: 3] |:z4 |f2ec|_ddcf |(B/c/_d/e/)ff|\nw: Son que-sti~i cre-spi cri-ni~e que - - - - sto~il\nw: Que-sti son~gli oc-chi che mi-ran - - - - do\n% 5 - 9\n[V: 1] cAB2 |cAAA |c3B|G2!fermata!Gz ::e4|\nw: que-sto~il vi-so ond' io ri-man-go~uc-ci-so. Deh,\nw: ran-do fi-so, tut-to re-stai con-qui-so.\n[V: 2] AAG2 |AFFF |A3F|=E2!fermata!Ez::c4|\nw: que-sto~il vi-so ond' io ri-man-go~uc-ci-so. Deh,\nw: ran-do fi-so tut-to re-stai con-qui-so.\n[V: 3] (ag/f/e2)|A_ddd|A3B|c2!fermata!cz ::A4|\nw: vi - - - so ond' io ti-man-go~uc-ci-so. Deh,\nw: fi - - - so tut-to re-stai con-qui-so.\n% 10 - 15\n[V: 1] f_dec |B2c2|zAGF |\\\nw: dim-me-lo ben mi-o, che que-sto\\\n=EFG2 |1F2z2:|2F8|] % more notes\nw: sol de-si-o_. % more lyrics\n[V: 2] ABGA |G2AA|GF=EF |(GF3/2=E//D//E)|1F2z2:|2F8|]\nw: dim-me-lo ben mi-o, che que-sto sol de-si - - - - o_.\n[V: 3] _dBc>d|e2AF|=EFc_d|c4 |1F2z2:|2F8|]\nw: dim-me-lo ben mi-o, che que-sto sol de-si-o_."
- }
- ],
- "id": "XvJhtwXD",
- "createdAt": 1659494559915,
- "updatedAt": 1659494581094
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "ActionScript",
- "content": [
- {
- "label": "Fragment 1",
- "language": "actionscript",
- "value": "package code\n{\n /*****************************************\n\t * based on textmate actionscript bundle\n\t ****************************************/\n\t \n\timport fl.events.SliderEvent;\n\t\n\tpublic class Foo extends MovieClip\n\t{\n\t\t//*************************\n\t\t// Properties:\n\t\t\n\t\tpublic var activeSwatch:MovieClip;\n\t\t\n\t\t// Color offsets\n\t\tpublic var c1:Number = 0;\t// R\n\t\t\n\t\t//*************************\n\t\t// Constructor:\n\t\t\n\t\tpublic function Foo()\n\t\t{\n\t\t\t// Respond to mouse events\n\t\t\tswatch1_btn.addEventListener(MouseEvent.CLICK,swatchHandler,false,0,false);\n\t\t\tpreviewBox_btn.addEventListener(MouseEvent.MOUSE_DOWN,dragPressHandler);\n\t\t\t\n\t\t\t// Respond to drag events\n\t\t\tred_slider.addEventListener(SliderEvent.THUMB_DRAG,sliderHandler);\n\t\t\t\n\t\t\t// Draw a frame later\n\t\t\taddEventListener(Event.ENTER_FRAME,draw);\n\t\t}\n \n\t\tprotected function clickHandler(event:MouseEvent):void\n\t\t{\n\t\t\tcar.transform.colorTransform = new ColorTransform(0,0,0,1,c1,c2,c3);\n\t\t}\n\t\t\n\t\tprotected function changeRGBHandler(event:Event):void\n\t\t{\n\t\t\tc1 = Number(c1_txt.text);\n \n\t\t\tif(!(c1>=0)){\n\t\t\t\tc1 = 0;\n\t\t\t}\t\t\t\n\t\t\t\n\t\t\tupdateSliders();\n\t\t}\n\t}\n}"
- }
- ],
- "id": "QpGK-4E3",
- "createdAt": 1659494622609,
- "updatedAt": 1659494644279
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "ADA",
- "content": [
- {
- "label": "Fragment 1",
- "language": "ada",
- "value": "with Ada.Text_IO; use Ada.Text_IO;\nprocedure Hello is\nbegin\n Put_Line(\"Hello, world!\");\nend Hello;"
- }
- ],
- "id": "Px9jIO7P",
- "createdAt": 1659494650343,
- "updatedAt": 1659494671562
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "Alda",
- "content": [
- {
- "label": "Fragment 1",
- "language": "alda",
- "value": "# Example taken from https://github.com/alda-lang/alda-core/blob/master/examples/across_the_sea.alda\n(tempo! 90)\n(quant! 95)\n\npiano:\n o5 g- > g- g-/f > e- d-4. < b-8 d-2 | c-4 e- d- d- g-\n\nflute:\n r2 g-4 a- b-2. > d-32~ e-16.~8 < b-2 a- g-1"
- }
- ],
- "id": "nxTqeuxF",
- "createdAt": 1659494682982,
- "updatedAt": 1659494699425
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "Apache",
- "content": [
- {
- "label": "Fragment 1",
- "language": "apache_conf",
- "value": "Redirect /linux http://www.linux.org\nRedirect 301 /kernel http://www.linux.org\n\n# comment\nRewriteEngine on\n\nRewriteCond %{HTTP_USER_AGENT} ^Mozilla.*\nRewriteRule ^/$ /homepage.max.html [L]\n\nRewriteRule ^/$ /homepage.std.html [L]\n"
- }
- ],
- "id": "A89NVbKL",
- "createdAt": 1659494861634,
- "updatedAt": 1659494932607
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "Apex",
- "content": [
- {
- "label": "Fragment 1",
- "language": "apex",
- "value": "public class testBlockDuplicatesLeadTrigger {\n\t\n\tstatic testMethod void testDuplicateTrigger(){ \n\t\n\t\tLead[] l1 =new Lead[]{\n\t\t\tnew Lead( Email='homer@fox.tv', LastName='Simpson', Company='fox' )\n\t\t};\n\t\tinsert l1;\t\t// add a known lead\n\t\t\n\t\tLead[] l2 =new Lead[]{\n\t\t\tnew Lead( Email='homer@fox.tv', LastName='Simpson', Company='fox' )\n\t\t};\n\t\t// try to add a matching lead\n\t\ttry {\tinsert l2;\t} catch ( System.DmlException e) { \n\t\t\tsystem.assert(e.getMessage().contains('first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, A lead with this email address already exists'),\n\t\t\t e.getMessage());\n\t\t}\n\t\t\n\t\t// test duplicates in the same batch\n\t\tLead[] l3 =new Lead[]{\n\t\t\tnew Lead( Email='marge@fox.tv', LastName='Simpson', Company='fox' ),\n\t\t\tnew Lead( Email='marge@fox.tv', LastName='Simpson', Company='fox' )\n\t\t};\t\t\n\t\ttry { insert l3;\t} catch ( System.DmlException e) { \n\t\t\tsystem.assert(e.getMessage().contains('first error: FIELD_CUSTOM_VALIDATION_EXCEPTION, Another new lead has the same email'),\n\t\t\t\te.getMessage());\n\t\t\t\n\t\t}\n\t\t\n\t\t// test update also\n\t\tLead[] lup = new Lead[]{\n\t\t\tnew Lead( Email='marge@fox.tv', LastName='Simpson', Company='fox' )\n\t\t};\n\t\tinsert lup;\n\t\tLead marge = [ select id,Email from lead where Email = 'marge@fox.tv' limit 1];\n\t\tsystem.assert(marge!=null);\n\t\tmarge.Email = 'homer@fox.tv'; \n\t\t\n\t\ttry { update marge; } catch ( System.DmlException e) { \n\t\t\tsystem.assert(e.getMessage().contains('irst error: FIELD_CUSTOM_VALIDATION_EXCEPTION, A lead with this email address already exists'),\n\t\t\t\te.getMessage());\t\n\t\t}\n\t}\n}"
- }
- ],
- "id": "vvnKSBLd",
- "createdAt": 1659494946912,
- "updatedAt": 1659495156796
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "AppleScript",
- "content": [
- {
- "label": "Fragment 1",
- "language": "applescript",
- "value": "set advancedSettings to {background color:{65535, 0, 0}, background dimensions:{1024, 90}, opacity:100}\ndisplay overlay text \"Warning. Boss approaching…\" duration 1 advanced settings advancedSettings with goose honk"
- }
- ],
- "id": "sHDdrA-8",
- "createdAt": 1659495204662,
- "updatedAt": 1659495281720
- },
- {
- "isDeleted": false,
- "isFavorites": false,
- "folderId": "J7rNZi7X",
- "tagsIds": [],
- "description": null,
- "name": "AsciiDoc",
- "content": [
- {
- "label": "Fragment 1",
- "language": "asciidoc",
- "value": "AsciiDoc User Guide\n===================\nStuart Rackham \n:Author Initials: SJR\n:toc:\n:icons:\n:numbered:\n:website: http://www.methods.co.nz/asciidoc/\n\nAsciiDoc is a text document format for writing notes, documentation,\narticles, books, ebooks, slideshows, web pages, blogs and UNIX man\npages. AsciiDoc files can be translated to many formats including\nHTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the\nAsciiDoc source file syntax and the backend output markups (which can\nbe almost any type of SGML/XML markup) can be customized and extended\nby the user.\n\n.This document\n**********************************************************************\nThis is an overly large document, it probably needs to be refactored\ninto a Tutorial, Quick Reference and Formal Reference.\n\nIf you're new to AsciiDoc read this section and the <> section and take a look at the example AsciiDoc (`*.txt`)\nsource files in the distribution `doc` directory.\n**********************************************************************\n\n\nIntroduction\n------------\nAsciiDoc is a plain text human readable/writable document format that\ncan be translated to DocBook or HTML using the asciidoc(1) command.\nYou can then either use asciidoc(1) generated HTML directly or run\nasciidoc(1) DocBook output through your favorite DocBook toolchain or\nuse the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,\nLaTeX, PostScript, man page, HTML and text formats.\n\nThe AsciiDoc format is a useful presentation format in its own right:\nAsciiDoc markup is simple, intuitive and as such is easily proofed and\nedited.\n\nAsciiDoc is light weight: it consists of a single Python script and a\nbunch of configuration files. Apart from asciidoc(1) and a Python\ninterpreter, no other programs are required to convert AsciiDoc text\nfiles to DocBook or HTML. See <>\nbelow.\n\nText markup conventions tend to be a matter of (often strong) personal\npreference: if the default syntax is not to your liking you can define\nyour own by editing the text based asciidoc(1) configuration files.\nYou can also create configuration files to translate AsciiDoc\ndocuments to almost any SGML/XML markup.\n\nasciidoc(1) comes with a set of configuration files to translate\nAsciiDoc articles, books and man pages to HTML or DocBook backend\nformats.\n\n.My AsciiDoc Itch\n**********************************************************************\nDocBook has emerged as the de facto standard Open Source documentation\nformat. But DocBook is a complex language, the markup is difficult to\nread and even more difficult to write directly -- I found I was\nspending more time typing markup tags, consulting reference manuals\nand fixing syntax errors, than I was writing the documentation.\n**********************************************************************\n\n\n[[X6]]\nGetting Started\n---------------\nInstalling AsciiDoc\n~~~~~~~~~~~~~~~~~~~\nSee the `README` and `INSTALL` files for install prerequisites and\nprocedures. Packagers take a look at <>.\n\n[[X11]]\nExample AsciiDoc Documents\n~~~~~~~~~~~~~~~~~~~~~~~~~~\nThe best way to quickly get a feel for AsciiDoc is to view the\nAsciiDoc web site and/or distributed examples:\n\n- Take a look at the linked examples on the AsciiDoc web site home\n page {website}. Press the 'Page Source' sidebar menu item to view\n corresponding AsciiDoc source.\n- Read the `*.txt` source files in the distribution `./doc` directory\n along with the corresponding HTML and DocBook XML files.\n\n\nAsciiDoc Document Types\n-----------------------\nThere are three types of AsciiDoc documents: article, book and\nmanpage. All document types share the same AsciiDoc format with some\nminor variations. If you are familiar with DocBook you will have\nnoticed that AsciiDoc document types correspond to the same-named\nDocBook document types.\n\nUse the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc\ndocument type -- the default document type is 'article'.\n\nBy convention the `.txt` file extension is used for AsciiDoc document\nsource files.\n\narticle\n~~~~~~~\nUsed for short documents, articles and general documentation. See the\nAsciiDoc distribution `./doc/article.txt` example.\n\nAsciiDoc defines standard DocBook article frontmatter and backmatter\n<> (appendix, abstract, bibliography,\nglossary, index).\n\nbook\n~~~~\nBooks share the same format as articles, with the following\ndifferences:\n\n- The part titles in multi-part books are <>\n (same level as book title).\n- Some sections are book specific e.g. preface and colophon.\n\nBook documents will normally be used to produce DocBook output since\nDocBook processors can automatically generate footnotes, table of\ncontents, list of tables, list of figures, list of examples and\nindexes.\n\nAsciiDoc defines standard DocBook book frontmatter and backmatter\n<> (appendix, dedication, preface,\nbibliography, glossary, index, colophon).\n\n.Example book documents\nBook::\n The `./doc/book.txt` file in the AsciiDoc distribution.\n\nMulti-part book::\n The `./doc/book-multi.txt` file in the AsciiDoc distribution.\n\nmanpage\n~~~~~~~\nUsed to generate roff format UNIX manual pages. AsciiDoc manpage\ndocuments observe special header title and section naming conventions\n-- see the <> section for details.\n\nAsciiDoc defines the 'synopsis' <> to\ngenerate the DocBook `refsynopsisdiv` section.\n\nSee also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from\nthe AsciiDoc distribution.\n\n\n[[X5]]\nAsciiDoc Backends\n-----------------\nThe asciidoc(1) command translates an AsciiDoc formatted file to the\nbackend format specified by the `-b` (`--backend`) command-line\noption. asciidoc(1) itself has little intrinsic knowledge of backend\nformats, all translation rules are contained in customizable cascading\nconfiguration files. Backend specific attributes are listed in the\n<> section.\n\ndocbook45::\n Outputs DocBook XML 4.5 markup.\n\nhtml4::\n This backend generates plain HTML 4.01 Transitional markup.\n\nxhtml11::\n This backend generates XHTML 1.1 markup styled with CSS2. Output\n files have an `.html` extension.\n\nhtml5::\n This backend generates HTML 5 markup, apart from the inclusion of\n <> it is functionally identical to\n the 'xhtml11' backend.\n\nslidy::\n Use this backend to generate self-contained\n http://www.w3.org/Talks/Tools/Slidy2/[Slidy] HTML slideshows for\n your web browser from AsciiDoc documents. The Slidy backend is\n documented in the distribution `doc/slidy.txt` file and\n {website}slidy.html[online].\n\nwordpress::\n A minor variant of the 'html4' backend to support\n http://srackham.wordpress.com/blogpost1/[blogpost].\n\nlatex::\n Experimental LaTeX backend.\n\nBackend Aliases\n~~~~~~~~~~~~~~~\nBackend aliases are alternative names for AsciiDoc backends. AsciiDoc\ncomes with two backend aliases: 'html' (aliased to 'xhtml11') and\n'docbook' (aliased to 'docbook45').\n\nYou can assign (or reassign) backend aliases by setting an AsciiDoc\nattribute named like `backend-alias-` to an AsciiDoc backend\nname. For example, the following backend alias attribute definitions\nappear in the `[attributes]` section of the global `asciidoc.conf`\nconfiguration file:\n\n backend-alias-html=xhtml11\n backend-alias-docbook=docbook45\n\n[[X100]]\nBackend Plugins\n~~~~~~~~~~~~~~~\nThe asciidoc(1) `--backend` option is also used to install and manage\nbackend <>.\n\n- A backend plugin is used just like the built-in backends.\n- Backend plugins <> over built-in backends with\n the same name.\n- You can use the `{asciidoc-confdir}` <> to\n refer to the built-in backend configuration file location from\n backend plugin configuration files.\n- You can use the `{backend-confdir}` <> to\n refer to the backend plugin configuration file location.\n- By default backends plugins are installed in\n `$HOME/.asciidoc/backends/` where `` is the\n backend name.\n\n\nDocBook\n-------\nAsciiDoc generates 'article', 'book' and 'refentry'\nhttp://www.docbook.org/[DocBook] documents (corresponding to the\nAsciiDoc 'article', 'book' and 'manpage' document types).\n\nMost Linux distributions come with conversion tools (collectively\ncalled a toolchain) for <> to\npresentation formats such as Postscript, HTML, PDF, EPUB, DVI,\nPostScript, LaTeX, roff (the native man page format), HTMLHelp,\nJavaHelp and text. There are also programs that allow you to view\nDocBook files directly, for example http://live.gnome.org/Yelp[Yelp]\n(the GNOME help viewer).\n\n[[X12]]\nConverting DocBook to other file formats\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nDocBook files are validated, parsed and translated various\npresentation file formats using a combination of applications\ncollectively called a DocBook 'tool chain'. The function of a tool\nchain is to read the DocBook markup (produced by AsciiDoc) and\ntransform it to a presentation format (for example HTML, PDF, HTML\nHelp, EPUB, DVI, PostScript, LaTeX).\n\nA wide range of user output format requirements coupled with a choice\nof available tools and stylesheets results in many valid tool chain\ncombinations.\n\n[[X43]]\na2x Toolchain Wrapper\n~~~~~~~~~~~~~~~~~~~~~\nOne of the biggest hurdles for new users is installing, configuring\nand using a DocBook XML toolchain. `a2x(1)` can help -- it's a\ntoolchain wrapper command that will generate XHTML (chunked and\nunchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text\nfile outputs from an AsciiDoc text file. `a2x(1)` does all the grunt\nwork associated with generating and sequencing the toolchain commands\nand managing intermediate and output files. `a2x(1)` also optionally\ndeploys admonition and navigation icons and a CSS stylesheet. See the\n`a2x(1)` man page for more details. In addition to `asciidoc(1)` you\nalso need <>, <> and\noptionally: <> or <> (to generate PDF);\n`w3m(1)` or `lynx(1)` (to generate text).\n\nThe following examples generate `doc/source-highlight-filter.pdf` from\nthe AsciiDoc `doc/source-highlight-filter.txt` source file. The first\nexample uses `dblatex(1)` (the default PDF generator) the second\nexample forces FOP to be used:\n\n $ a2x -f pdf doc/source-highlight-filter.txt\n $ a2x -f pdf --fop doc/source-highlight-filter.txt\n\nSee the `a2x(1)` man page for details.\n\nTIP: Use the `--verbose` command-line option to view executed\ntoolchain commands.\n\nHTML generation\n~~~~~~~~~~~~~~~\nAsciiDoc produces nicely styled HTML directly without requiring a\nDocBook toolchain but there are also advantages in going the DocBook\nroute:\n\n- HTML from DocBook can optionally include automatically generated\n indexes, tables of contents, footnotes, lists of figures and tables.\n- DocBook toolchains can also (optionally) generate separate (chunked)\n linked HTML pages for each document section.\n- Toolchain processing performs link and document validity checks.\n- If the DocBook 'lang' attribute is set then things like table of\n contents, figure and table captions and admonition captions will be\n output in the specified language (setting the AsciiDoc 'lang'\n attribute sets the DocBook 'lang' attribute).\n\nOn the other hand, HTML output directly from AsciiDoc is much faster,\nis easily customized and can be used in situations where there is no\nsuitable DocBook toolchain (for example, see the {website}[AsciiDoc\nwebsite]).\n\nPDF generation\n~~~~~~~~~~~~~~\nThere are two commonly used tools to generate PDFs from DocBook,\n<> and <>.\n\n.dblatex or FOP?\n- 'dblatex' is easier to install, there's zero configuration\n required and no Java VM to install -- it just works out of the box.\n- 'dblatex' source code highlighting and numbering is superb.\n- 'dblatex' is easier to use as it converts DocBook directly to PDF\n whereas before using 'FOP' you have to convert DocBook to XML-FO\n using <>.\n- 'FOP' is more feature complete (for example, callouts are processed\n inside literal layouts) and arguably produces nicer looking output.\n\nHTML Help generation\n~~~~~~~~~~~~~~~~~~~~\n. Convert DocBook XML documents to HTML Help compiler source files\n using <> and <>.\n. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help\n (`.chm`) files using the <>.\n\nToolchain components summary\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nAsciiDoc::\n Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.\n\n[[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::\n These are a set of XSL stylesheets containing rules for converting\n DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.\n The stylesheets are used in conjunction with an XML parser such as\n <>.\n\n[[X40]]http://www.xmlsoft.org[xsltproc]::\n An XML parser for applying XSLT stylesheets (in our case the\n <>) to XML documents.\n\n[[X31]]http://dblatex.sourceforge.net/[dblatex]::\n Generates PDF, DVI, PostScript and LaTeX formats directly from\n DocBook source via the intermediate LaTeX typesetting language --\n uses <>, <> and\n `latex(1)`.\n\n[[X14]]http://xml.apache.org/fop/[FOP]::\n The Apache Formatting Objects Processor converts XSL-FO (`.fo`)\n files to PDF files. The XSL-FO files are generated from DocBook\n source files using <> and\n <>.\n\n[[X67]]Microsoft Help Compiler::\n The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool\n that converts HTML Help source files to a single HTML Help (`.chm`)\n file. It runs on MS Windows platforms and can be downloaded from\n http://www.microsoft.com.\n\nAsciiDoc dblatex configuration files\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nThe AsciiDoc distribution `./dblatex` directory contains\n`asciidoc-dblatex.xsl` (customized XSL parameter settings) and\n`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples\nof optional <> output customization and are used by\n<>.\n\nAsciiDoc DocBook XSL Stylesheets drivers\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nYou will have noticed that the distributed HTML and HTML Help\ndocumentation files (for example `./doc/asciidoc.html`) are not the\nplain outputs produced using the default 'DocBook XSL Stylesheets'\nconfiguration. This is because they have been processed using\ncustomized DocBook XSL Stylesheets along with (in the case of HTML\noutputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet.\n\nYou'll find the customized DocBook XSL drivers along with additional\ndocumentation in the distribution `./docbook-xsl` directory. The\nexamples that follow are executed from the distribution documentation\n(`./doc`) directory. These drivers are also used by <>.\n\n`common.xsl`::\n Shared driver parameters. This file is not used directly but is\n included in all the following drivers.\n\n`chunked.xsl`::\n Generate chunked XHTML (separate HTML pages for each document\n section) in the `./doc/chunked` directory. For example:\n\n $ python ../asciidoc.py -b docbook asciidoc.txt\n $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml\n\n`epub.xsl`::\n Used by <> to generate EPUB formatted documents.\n\n`fo.xsl`::\n Generate XSL Formatting Object (`.fo`) files for subsequent PDF\n file generation using FOP. For example:\n\n $ python ../asciidoc.py -b docbook article.txt\n $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo\n $ fop article.fo article.pdf\n\n`htmlhelp.xsl`::\n Generate Microsoft HTML Help source files for the MS HTML Help\n Compiler in the `./doc/htmlhelp` directory. This example is run on\n MS Windows from a Cygwin shell prompt:\n\n $ python ../asciidoc.py -b docbook asciidoc.txt\n $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml\n $ c:/Program\\ Files/HTML\\ Help\\ Workshop/hhc.exe htmlhelp.hhp\n\n`manpage.xsl`::\n Generate a `roff(1)` format UNIX man page from a DocBook XML\n 'refentry' document. This example generates an `asciidoc.1` man\n page file:\n\n $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt\n $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml\n\n`xhtml.xsl`::\n Convert a DocBook XML file to a single XHTML file. For example:\n\n $ python ../asciidoc.py -b docbook asciidoc.txt\n $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html\n\nIf you want to see how the complete documentation set is processed\ntake a look at the A-A-P script `./doc/main.aap`.\n\n\nGenerating Plain Text Files\n---------------------------\nAsciiDoc does not have a text backend (for most purposes AsciiDoc\nsource text is fine), however you can convert AsciiDoc text files to\nformatted text using the AsciiDoc <> toolchain wrapper\nutility.\n\n\n[[X35]]\nHTML5 and XHTML 1.1\n-------------------\nThe 'xhtml11' and 'html5' backends embed or link CSS and JavaScript\nfiles in their outputs, there is also a <> plugin\nframework.\n\n- If the AsciiDoc 'linkcss' attribute is defined then CSS and\n JavaScript files are linked to the output document, otherwise they\n are embedded (the default behavior).\n- The default locations for CSS and JavaScript files can be changed by\n setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes\n respectively.\n- The default locations for embedded and linked files differ and are\n calculated at different times -- embedded files are loaded when\n asciidoc(1) generates the output document, linked files are loaded\n by the browser when the user views the output document.\n- Embedded files are automatically inserted in the output files but\n you need to manually copy linked CSS and Javascript files from\n AsciiDoc <> to the correct location\n relative to the output document.\n\n.Stylesheet file locations\n[cols=\"3*\",frame=\"topbot\",options=\"header\"]\n|====================================================================\n|'stylesdir' attribute\n|Linked location ('linkcss' attribute defined)\n|Embedded location ('linkcss' attribute undefined)\n\n|Undefined (default).\n|Same directory as the output document.\n|`stylesheets` subdirectory in the AsciiDoc configuration directory\n(the directory containing the backend conf file).\n\n|Absolute or relative directory name.\n|Absolute or relative to the output document.\n|Absolute or relative to the AsciiDoc configuration directory (the\ndirectory containing the backend conf file).\n\n|====================================================================\n\n.JavaScript file locations\n[cols=\"3*\",frame=\"topbot\",options=\"header\"]\n|====================================================================\n|'scriptsdir' attribute\n|Linked location ('linkcss' attribute defined)\n|Embedded location ('linkcss' attribute undefined)\n\n|Undefined (default).\n|Same directory as the output document.\n|`javascripts` subdirectory in the AsciiDoc configuration directory\n(the directory containing the backend conf file).\n\n|Absolute or relative directory name.\n|Absolute or relative to the output document.\n|Absolute or relative to the AsciiDoc configuration directory (the\ndirectory containing the backend conf file).\n\n|====================================================================\n\n[[X99]]\nThemes\n~~~~~~\nThe AsciiDoc 'theme' attribute is used to select an alternative CSS\nstylesheet and to optionally include additional JavaScript code.\n\n- Theme files reside in an AsciiDoc <>\n named `themes//` (where `` is the the theme name set\n by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute\n to the theme directory path name.\n- The 'theme' attribute can also be set using the asciidoc(1)\n `--theme` option, the `--theme` option can also be used to manage\n theme <>.\n- AsciiDoc ships with two themes: 'flask' and 'volnitsky'.\n- The `.css` file replaces the default `asciidoc.css` CSS file.\n- The `.js` file is included in addition to the default\n `asciidoc.js` JavaScript file.\n- If the <> attribute is defined then icons are loaded\n from the theme `icons` sub-directory if it exists (i.e. the\n 'iconsdir' attribute is set to theme `icons` sub-directory path).\n- Embedded theme files are automatically inserted in the output files\n but you need to manually copy linked CSS and Javascript files to the\n location of the output documents.\n- Linked CSS and JavaScript theme files are linked to the same linked\n locations as <>.\n\nFor example, the command-line option `--theme foo` (or `--attribute\ntheme=foo`) will cause asciidoc(1) to search <<\"X27\",\"configuration\nfile locations 1, 2 and 3\">> for a sub-directory called `themes/foo`\ncontaining the stylesheet `foo.css` and optionally a JavaScript file\nname `foo.js`.\n\n\nDocument Structure\n------------------\nAn AsciiDoc document consists of a series of <>\nstarting with an optional document Header, followed by an optional\nPreamble, followed by zero or more document Sections.\n\nAlmost any combination of zero or more elements constitutes a valid\nAsciiDoc document: documents can range from a single sentence to a\nmulti-part book.\n\nBlock Elements\n~~~~~~~~~~~~~~\nBlock elements consist of one or more lines of text and may contain\nother block elements.\n\nThe AsciiDoc block structure can be informally summarized as follows\nfootnote:[This is a rough structural guide, not a rigorous syntax\ndefinition]:\n\n Document ::= (Header?,Preamble?,Section*)\n Header ::= (Title,(AuthorInfo,RevisionInfo?)?)\n AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)\n RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)\n Preamble ::= (SectionBody)\n Section ::= (Title,SectionBody?,(Section)*)\n SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+\n Block ::= (Paragraph|DelimitedBlock|List|Table)\n List ::= (BulletedList|NumberedList|LabeledList|CalloutList)\n BulletedList ::= (ListItem)+\n NumberedList ::= (ListItem)+\n CalloutList ::= (ListItem)+\n LabeledList ::= (ListEntry)+\n ListEntry ::= (ListLabel,ListItem)\n ListLabel ::= (ListTerm+)\n ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)\n\nWhere:\n\n- '?' implies zero or one occurrence, '+' implies one or more\n occurrences, '*' implies zero or more occurrences.\n- All block elements are separated by line boundaries.\n- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not\n shown) can occur almost anywhere.\n- There are a number of document type and backend specific\n restrictions imposed on the block syntax.\n- The following elements cannot contain blank lines: Header, Title,\n Paragraph, ItemText.\n- A ListParagraph is a Paragraph with its 'listelement' option set.\n- A ListContinuation is a <>.\n\n[[X95]]\nHeader\n~~~~~~\nThe Header contains document meta-data, typically title plus optional\nauthorship and revision information:\n\n- The Header is optional, but if it is used it must start with a\n document <>.\n- Optional Author and Revision information immediately follows the\n header title.\n- The document header must be separated from the remainder of the\n document by one or more blank lines and cannot contain blank lines.\n- The header can include comments.\n- The header can include <>, typically\n 'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc',\n 'numbered'.\n- Header attributes are overridden by command-line attributes.\n- If the header contains non-UTF-8 characters then the 'encoding' must\n precede the header (either in the document or on the command-line).\n\nHere's an example AsciiDoc document header:\n\n Writing Documentation using AsciiDoc\n ====================================\n Joe Bloggs \n v2.0, February 2003:\n Rewritten for version 2 release.\n\nThe author information line contains the author's name optionally\nfollowed by the author's email address. The author's name is formatted\nlike:\n\n firstname[ [middlename ]lastname][ ]]\n\ni.e. a first name followed by optional middle and last names followed\nby an email address in that order. Multi-word first, middle and last\nnames can be entered using the underscore as a word separator. The\nemail address comes last and must be enclosed in angle <> brackets.\nHere a some examples of author information lines:\n\n Joe Bloggs \n Joe Bloggs\n Vincent Willem van_Gogh\n\nIf the author line does not match the above specification then the\nentire author line is treated as the first name.\n\nThe optional revision information line follows the author information\nline. The revision information can be one of two formats:\n\n. An optional document revision number followed by an optional\n revision date followed by an optional revision remark:\n+\n--\n * If the revision number is specified it must be followed by a\n comma.\n * The revision number must contain at least one numeric character.\n * Any non-numeric characters preceding the first numeric character\n will be dropped.\n * If a revision remark is specified it must be preceded by a colon.\n The revision remark extends from the colon up to the next blank\n line, attribute entry or comment and is subject to normal text\n substitutions.\n * If a revision number or remark has been set but the revision date\n has not been set then the revision date is set to the value of the\n 'docdate' attribute.\n\nExamples:\n\n v2.0, February 2003\n February 2003\n v2.0,\n v2.0, February 2003: Rewritten for version 2 release.\n February 2003: Rewritten for version 2 release.\n v2.0,: Rewritten for version 2 release.\n :Rewritten for version 2 release.\n--\n\n. The revision information line can also be an RCS/CVS/SVN $Id$\n marker:\n+\n--\n * AsciiDoc extracts the 'revnumber', 'revdate', and 'author'\n attributes from the $Id$ revision marker and displays them in the\n document header.\n * If an $Id$ revision marker is used the header author line can be\n omitted.\n\nExample:\n\n $Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $\n--\n\nYou can override or set header parameters by passing 'revnumber',\n'revremark', 'revdate', 'email', 'author', 'authorinitials',\n'firstname' and 'lastname' attributes using the asciidoc(1) `-a`\n(`--attribute`) command-line option. For example:\n\n $ asciidoc -a revdate=2004/07/27 article.txt\n\nAttribute entries can also be added to the header for substitution in\nthe header template with <> elements.\n\nThe 'title' element in HTML outputs is set to the AsciiDoc document\ntitle, you can set it to a different value by including a 'title'\nattribute entry in the document header.\n\n[[X87]]\nAdditional document header information\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nAsciiDoc has two mechanisms for optionally including additional\nmeta-data in the header of the output document:\n\n'docinfo' configuration file sections::\nIf a <> section named 'docinfo' has been loaded\nthen it will be included in the document header. Typically the\n'docinfo' section name will be prefixed with a '+' character so that it\nis appended to (rather than replace) other 'docinfo' sections.\n\n'docinfo' files::\nTwo docinfo files are recognized: one named `docinfo` and a second\nnamed like the AsciiDoc source file with a `-docinfo` suffix. For\nexample, if the source document is called `mydoc.txt` then the\ndocument information files would be `docinfo.xml` and\n`mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and\n`mydoc-docinfo.html` (for HTML outputs). The <> attributes control which docinfo files are included in\nthe output files.\n\nThe contents docinfo templates and files is dependent on the type of\noutput:\n\nHTML::\n Valid 'head' child elements. Typically 'style' and 'script' elements\n for CSS and JavaScript inclusion.\n\nDocBook::\n Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines\n numerous elements for document meta-data, for example: copyrights,\n document history and authorship information. See the DocBook\n `./doc/article-docinfo.xml` example that comes with the AsciiDoc\n distribution. The rendering of meta-data elements (or not) is\n DocBook processor dependent.\n\n\n[[X86]]\nPreamble\n~~~~~~~~\nThe Preamble is an optional untitled section body between the document\nHeader and the first Section title.\n\nSections\n~~~~~~~~\nIn addition to the document title (level 0), AsciiDoc supports four\nsection levels: 1 (top) to 4 (bottom). Section levels are delimited\nby section <>. Sections are translated using\nconfiguration file <>. AsciiDoc\ngenerates the following <> specifically for\nuse in section markup templates:\n\nlevel::\nThe `level` attribute is the section level number, it is normally just\nthe <> level number (1..4). However, if the `leveloffset`\nattribute is defined it will be added to the `level` attribute. The\n`leveloffset` attribute is useful for <>.\n\nsectnum::\nThe `-n` (`--section-numbers`) command-line option generates the\n`sectnum` (section number) attribute. The `sectnum` attribute is used\nfor section numbers in HTML outputs (DocBook section numbering are\nhandled automatically by the DocBook toolchain commands).\n\n[[X93]]\nSection markup templates\n^^^^^^^^^^^^^^^^^^^^^^^^\nSection markup templates specify output markup and are defined in\nAsciiDoc configuration files. Section markup template names are\nderived as follows (in order of precedence):\n\n1. From the title's first positional attribute or 'template'\n attribute. For example, the following three section titles are\n functionally equivalent:\n+\n.....................................................................\n[[terms]]\n[glossary]\nList of Terms\n-------------\n\n[\"glossary\",id=\"terms\"]\nList of Terms\n-------------\n\n[template=\"glossary\",id=\"terms\"]\nList of Terms\n-------------\n.....................................................................\n\n2. When the title text matches a configuration file\n <> entry.\n3. If neither of the above the default `sect` template is used\n (where `` is a number from 1 to 4).\n\nIn addition to the normal section template names ('sect1', 'sect2',\n'sect3', 'sect4') AsciiDoc has the following templates for\nfrontmatter, backmatter and other special sections: 'abstract',\n'preface', 'colophon', 'dedication', 'glossary', 'bibliography',\n'synopsis', 'appendix', 'index'. These special section templates\ngenerate the corresponding Docbook elements; for HTML outputs they\ndefault to the 'sect1' section template.\n\nSection IDs\n^^^^^^^^^^^\nIf no explicit section ID is specified an ID will be synthesised from\nthe section title. The primary purpose of this feature is to ensure\npersistence of table of contents links (permalinks): the missing\nsection IDs are generated dynamically by the JavaScript TOC generator\n*after* the page is loaded. If you link to a dynamically generated TOC\naddress the page will load but the browser will ignore the (as yet\nungenerated) section ID.\n\nThe IDs are generated by the following algorithm:\n\n- Replace all non-alphanumeric title characters with underscores.\n- Strip leading or trailing underscores.\n- Convert to lowercase.\n- Prepend the `idprefix` attribute (so there's no possibility of name\n clashes with existing document IDs). Prepend an underscore if the\n `idprefix` attribute is not defined.\n- A numbered suffix (`_2`, `_3` ...) is added if a same named\n auto-generated section ID exists.\n- If the `ascii-ids` attribute is defined then non-ASCII characters\n are replaced with ASCII equivalents. This attribute may be\n deprecated in future releases and *should be avoided*, it's sole\n purpose is to accommodate deficient downstream applications that\n cannot process non-ASCII ID attributes.\n\nExample: the title 'Jim's House' would generate the ID `_jim_s_house`.\n\nSection ID synthesis can be disabled by undefining the `sectids`\nattribute.\n\n[[X16]]\nSpecial Section Titles\n^^^^^^^^^^^^^^^^^^^^^^\nAsciiDoc has a mechanism for mapping predefined section titles\nauto-magically to specific markup templates. For example a title\n'Appendix A: Code Reference' will automatically use the 'appendix'\n<>. The mappings from title to template\nname are specified in `[specialsections]` sections in the Asciidoc\nlanguage configuration files (`lang-*.conf`). Section entries are\nformatted like:\n\n =\n\n`` is a Python regular expression and `` is the name\nof a configuration file markup template section. If the ``\nmatches an AsciiDoc document section title then the backend output is\nmarked up using the `` markup template (instead of the\ndefault `sect` section template). The `{title}` attribute value\nis set to the value of the matched regular expression group named\n'title', if there is no 'title' group `{title}` defaults to the whole\nof the AsciiDoc section title. If `` is blank then any\nexisting entry with the same `` will be deleted.\n\n.Special section titles vs. explicit template names\n*********************************************************************\nAsciiDoc has two mechanisms for specifying non-default section markup\ntemplates: you can specify the template name explicitly (using the\n'template' attribute) or indirectly (using 'special section titles').\nSpecifying a <> attribute explicitly is\npreferred. Auto-magical 'special section titles' have the following\ndrawbacks:\n\n- They are non-obvious, you have to know the exact matching\n title for each special section on a language by language basis.\n- Section titles are predefined and can only be customised with a\n configuration change.\n- The implementation is complicated by multiple languages: every\n special section title has to be defined for each language (in each\n of the `lang-*.conf` files).\n\nSpecifying special section template names explicitly does add more\nnoise to the source document (the 'template' attribute declaration),\nbut the intention is obvious and the syntax is consistent with other\nAsciiDoc elements c.f. bibliographic, Q&A and glossary lists.\n\nSpecial section titles have been deprecated but are retained for\nbackward compatibility.\n\n*********************************************************************\n\nInline Elements\n~~~~~~~~~~~~~~~\n<> are used to format text and to\nperform various types of text substitution. Inline elements and inline\nelement syntax is defined in the asciidoc(1) configuration files.\n\nHere is a list of AsciiDoc inline elements in the (default) order in\nwhich they are processed:\n\nSpecial characters::\n These character sequences escape special characters used by\n the backend markup (typically `<`, `>`, and `&` characters).\n See `[specialcharacters]` configuration file sections.\n\nQuotes::\n Elements that markup words and phrases; usually for character\n formatting. See `[quotes]` configuration file sections.\n\nSpecial Words::\n Word or word phrase patterns singled out for markup without\n the need for further annotation. See `[specialwords]`\n configuration file sections.\n\nReplacements::\n Each replacement defines a word or word phrase pattern to\n search for along with corresponding replacement text. See\n `[replacements]` configuration file sections.\n\nAttribute references::\n Document attribute names enclosed in braces are replaced by\n the corresponding attribute value.\n\nInline Macros::\n Inline macros are replaced by the contents of parametrized\n configuration file sections.\n\n\nDocument Processing\n-------------------\nThe AsciiDoc source document is read and processed as follows:\n\n1. The document 'Header' is parsed, header parameter values are\n substituted into the configuration file `[header]` template section\n which is then written to the output file.\n2. Each document 'Section' is processed and its constituent elements\n translated to the output file.\n3. The configuration file `[footer]` template section is substituted\n and written to the output file.\n\nWhen a block element is encountered asciidoc(1) determines the type of\nblock by checking in the following order (first to last): (section)\nTitles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,\nAttributeLists, BlockTitles, Paragraphs.\n\nThe default paragraph definition `[paradef-default]` is last element\nto be checked.\n\nKnowing the parsing order will help you devise unambiguous macro, list\nand block syntax rules.\n\nInline substitutions within block elements are performed in the\nfollowing default order:\n\n1. Special characters\n2. Quotes\n3. Special words\n4. Replacements\n5. Attributes\n6. Inline Macros\n7. Replacements2\n\nThe substitutions and substitution order performed on\nTitle, Paragraph and DelimitedBlock elements is determined by\nconfiguration file parameters.\n\n\nText Formatting\n---------------\n[[X51]]\nQuoted Text\n~~~~~~~~~~~\nWords and phrases can be formatted by enclosing inline text with\nquote characters:\n\n_Emphasized text_::\n Word phrases \\'enclosed in single quote characters' (acute\n accents) or \\_underline characters_ are emphasized.\n\n*Strong text*::\n Word phrases \\*enclosed in asterisk characters* are rendered\n in a strong font (usually bold).\n\n[[X81]]+Monospaced text+::\n Word phrases \\+enclosed in plus characters+ are rendered in a\n monospaced font. Word phrases \\`enclosed in backtick\n characters` (grave accents) are also rendered in a monospaced\n font but in this case the enclosed text is rendered literally\n and is not subject to further expansion (see <>).\n\n`Single quoted text'::\n Phrases enclosed with a \\`single grave accent to the left and\n a single acute accent to the right' are rendered in single\n quotation marks.\n\n``Double quoted text''::\n Phrases enclosed with \\\\``two grave accents to the left and\n two acute accents to the right'' are rendered in quotation\n marks.\n\n#Unquoted text#::\n Placing \\#hashes around text# does nothing, it is a mechanism\n to allow inline attributes to be applied to otherwise\n unformatted text.\n\nNew quote types can be defined by editing asciidoc(1) configuration\nfiles. See the <> section for details.\n\n.Quoted text behavior\n- Quoting cannot be overlapped.\n- Different quoting types can be nested.\n- To suppress quoted text formatting place a backslash character\n immediately in front of the leading quote character(s). In the case\n of ambiguity between escaped and non-escaped text you will need to\n escape both leading and trailing quotes, in the case of\n multi-character quotes you may even need to escape individual\n characters.\n\n[[X96]]\nQuoted text attributes\n^^^^^^^^^^^^^^^^^^^^^^\nQuoted text can be prefixed with an <>. The first\npositional attribute ('role' attribute) is translated by AsciiDoc to\nan HTML 'span' element 'class' attribute or a DocBook 'phrase' element\n'role' attribute.\n\nDocBook XSL Stylesheets translate DocBook 'phrase' elements with\n'role' attributes to corresponding HTML 'span' elements with the same\n'class' attributes; CSS can then be used\nhttp://www.sagehill.net/docbookxsl/UsingCSS.html[to style the\ngenerated HTML]. Thus CSS styling can be applied to both DocBook and\nAsciiDoc generated HTML outputs. You can also specify multiple class\nnames separated by spaces.\n\nCSS rules for text color, text background color, text size and text\ndecorators are included in the distributed AsciiDoc CSS files and are\nused in conjunction with AsciiDoc 'xhtml11', 'html5' and 'docbook'\noutputs. The CSS class names are:\n\n- '' (text foreground color).\n- '-background' (text background color).\n- 'big' and 'small' (text size).\n- 'underline', 'overline' and 'line-through' (strike through) text\n decorators.\n\nWhere '' can be any of the\nhttp://en.wikipedia.org/wiki/Web_colors#HTML_color_names[sixteen HTML\ncolor names]. Examples:\n\n [red]#Obvious# and [big red yellow-background]*very obvious*.\n\n [underline]#Underline text#, [overline]#overline text# and\n [blue line-through]*bold blue and line-through*.\n\nis rendered as:\n\n[red]#Obvious# and [big red yellow-background]*very obvious*.\n\n[underline]#Underline text#, [overline]#overline text# and\n[bold blue line-through]*bold blue and line-through*.\n\nNOTE: Color and text decorator attributes are rendered for XHTML and\nHTML 5 outputs using CSS stylesheets. The mechanism to implement\ncolor and text decorator attributes is provided for DocBook toolchains\nvia the DocBook 'phrase' element 'role' attribute, but the actual\nrendering is toolchain specific and is not part of the AsciiDoc\ndistribution.\n\n[[X52]]\nConstrained and Unconstrained Quotes\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThere are actually two types of quotes:\n\nConstrained quotes\n++++++++++++++++++\nQuoted must be bounded by white space or commonly adjoining\npunctuation characters. These are the most commonly used type of\nquote.\n\nUnconstrained quotes\n++++++++++++++++++++\nUnconstrained quotes have no boundary constraints and can be placed\nanywhere within inline text. For consistency and to make them easier\nto remember unconstrained quotes are double-ups of the `_`, `*`, `+`\nand `#` constrained quotes:\n\n __unconstrained emphasized text__\n **unconstrained strong text**\n ++unconstrained monospaced text++\n ##unconstrained unquoted text##\n\nThe following example emboldens the letter F:\n\n **F**ile Open...\n\nSuperscripts and Subscripts\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\nPut \\^carets on either^ side of the text to be superscripted, put\n\\~tildes on either side~ of text to be subscripted. For example, the\nfollowing line:\n\n e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^\n and ~some sub text~\n\nIs rendered like:\n\ne^πi^+1 = 0. H~2~O and x^10^. Some ^super text^\nand ~some sub text~\n\nSuperscripts and subscripts are implemented as <> and they can be escaped with a leading backslash and prefixed\nwith with an attribute list.\n\nLine Breaks\n~~~~~~~~~~~\nA plus character preceded by at least one space character at the end\nof a non-blank line forces a line break. It generates a line break\n(`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing\ninstruction for DocBook outputs. The `asciidoc-br` processing\ninstruction is handled by <>.\n\nPage Breaks\n~~~~~~~~~~~\nA line of three or more less-than (`<<<`) characters will generate a\nhard page break in DocBook and printed HTML outputs. It uses the CSS\n`page-break-after` property for HTML outputs and a custom XML\n`asciidoc-pagebreak` processing instruction for DocBook outputs. The\n`asciidoc-pagebreak` processing instruction is handled by\n<>. Hard page breaks are sometimes handy but as a general\nrule you should let your page processor generate page breaks for you.\n\nRulers\n~~~~~~\nA line of three or more apostrophe characters will generate a ruler\nline. It generates a ruler (`hr`) tag for HTML outputs and a custom\nXML `asciidoc-hr` processing instruction for DocBook outputs. The\n`asciidoc-hr` processing instruction is handled by <>.\n\nTabs\n~~~~\nBy default tab characters input files will translated to 8 spaces. Tab\nexpansion is set with the 'tabsize' entry in the configuration file\n`[miscellaneous]` section and can be overridden in included files by\nsetting a 'tabsize' attribute in the `include` macro's attribute list.\nFor example:\n\n include::addendum.txt[tabsize=2]\n\nThe tab size can also be set using the attribute command-line option,\nfor example `--attribute tabsize=4`\n\nReplacements\n~~~~~~~~~~~~\nThe following replacements are defined in the default AsciiDoc\nconfiguration:\n\n (C) copyright, (TM) trademark, (R) registered trademark,\n -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right\n double arrow, <= left double arrow.\n\nWhich are rendered as:\n\n(C) copyright, (TM) trademark, (R) registered trademark,\n-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right\ndouble arrow, <= left double arrow.\n\nYou can also include arbitrary entity references in the AsciiDoc\nsource. Examples:\n\n ➊ ¶\n\nrenders:\n\n➊ ¶\n\nTo render a replacement literally escape it with a leading back-slash.\n\nThe <> section explains how to configure your\nown replacements.\n\nSpecial Words\n~~~~~~~~~~~~~\nWords defined in `[specialwords]` configuration file sections are\nautomatically marked up without having to be explicitly notated.\n\nThe <> section explains how to add and replace\nspecial words.\n\n\n[[X17]]\nTitles\n------\nDocument and section titles can be in either of two formats:\n\nTwo line titles\n~~~~~~~~~~~~~~~\nA two line title consists of a title line, starting hard against the\nleft margin, and an underline. Section underlines consist a repeated\ncharacter pairs spanning the width of the preceding title (give or\ntake up to two characters):\n\nThe default title underlines for each of the document levels are:\n\n\n Level 0 (top level): ======================\n Level 1: ----------------------\n Level 2: ~~~~~~~~~~~~~~~~~~~~~~\n Level 3: ^^^^^^^^^^^^^^^^^^^^^^\n Level 4 (bottom level): ++++++++++++++++++++++\n\nExamples:\n\n Level One Section Title\n -----------------------\n\n Level 2 Subsection Title\n ~~~~~~~~~~~~~~~~~~~~~~~~\n\n[[X46]]\nOne line titles\n~~~~~~~~~~~~~~~\nOne line titles consist of a single line delimited on either side by\none or more equals characters (the number of equals characters\ncorresponds to the section level minus one). Here are some examples:\n\n = Document Title (level 0) =\n == Section title (level 1) ==\n === Section title (level 2) ===\n ==== Section title (level 3) ====\n ===== Section title (level 4) =====\n\n[NOTE]\n=====================================================================\n- One or more spaces must fall between the title and the delimiters.\n- The trailing title delimiter is optional.\n- The one-line title syntax can be changed by editing the\n configuration file `[titles]` section `sect0`...`sect4` entries.\n=====================================================================\n\nFloating titles\n~~~~~~~~~~~~~~~\nSetting the title's first positional attribute or 'style' attribute to\n'float' generates a free-floating title. A free-floating title is\nrendered just like a normal section title but is not formally\nassociated with a text body and is not part of the regular section\nhierarchy so the normal ordering rules do not apply. Floating titles\ncan also be used in contexts where section titles are illegal: for\nexample sidebar and admonition blocks. Example:\n\n [float]\n The second day\n ~~~~~~~~~~~~~~\n\nFloating titles do not appear in a document's table of contents.\n\n\n[[X42]]\nBlock Titles\n------------\nA 'BlockTitle' element is a single line beginning with a period\nfollowed by the title text. A BlockTitle is applied to the immediately\nfollowing Paragraph, DelimitedBlock, List, Table or BlockMacro. For\nexample:\n\n........................\n.Notes\n- Note 1.\n- Note 2.\n........................\n\nis rendered as:\n\n.Notes\n- Note 1.\n- Note 2.\n\n\n[[X41]]\nBlockId Element\n---------------\nA 'BlockId' is a single line block element containing a unique\nidentifier enclosed in double square brackets. It is used to assign an\nidentifier to the ensuing block element. For example:\n\n [[chapter-titles]]\n Chapter titles can be ...\n\nThe preceding example identifies the ensuing paragraph so it can be\nreferenced from other locations, for example with\n`<>`.\n\n'BlockId' elements can be applied to Title, Paragraph, List,\nDelimitedBlock, Table and BlockMacro elements. The BlockId element\nsets the `{id}` attribute for substitution in the subsequent block's\nmarkup template. If a second positional argument is supplied it sets\nthe `{reftext}` attribute which is used to set the DocBook `xreflabel`\nattribute.\n\nThe 'BlockId' element has the same syntax and serves the same function\nto the <>.\n\n[[X79]]\nAttributeList Element\n---------------------\nAn 'AttributeList' block element is an <> on a\nline by itself:\n\n- 'AttributeList' attributes are only applied to the immediately\n following block element -- the attributes are made available to the\n block's markup template.\n- Multiple contiguous 'AttributeList' elements are additively combined\n in the order they appear..\n- The first positional attribute in the list is often used to specify\n the ensuing element's <>.\n\nAttribute value substitution\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nBy default, only substitutions that take place inside attribute list\nvalues are attribute references, this is because not all attributes\nare destined to be marked up and rendered as text (for example the\ntable 'cols' attribute). To perform normal inline text substitutions\n(special characters, quotes, macros, replacements) on an attribute\nvalue you need to enclose it in single quotes. In the following quote\nblock the second attribute value in the AttributeList is quoted to\nensure the 'http' macro is expanded to a hyperlink.\n\n---------------------------------------------------------------------\n[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']\n_____________________________________________________________________\nSir, a woman's preaching is like a dog's walking on his hind legs. It\nis not done well; but you are surprised to find it done at all.\n_____________________________________________________________________\n---------------------------------------------------------------------\n\nCommon attributes\n~~~~~~~~~~~~~~~~~\nMost block elements support the following attributes:\n\n[cols=\"1e,1,5a\",frame=\"topbot\",options=\"header\"]\n|====================================================================\n|Name |Backends |Description\n\n|id |html4, html5, xhtml11, docbook |\nUnique identifier typically serve as link targets.\nCan also be set by the 'BlockId' element.\n\n|role |html4, html5, xhtml11, docbook |\nRole contains a string used to classify or subclassify an element and\ncan be applied to AsciiDoc block elements. The AsciiDoc 'role'\nattribute is translated to the 'role' attribute in DocBook outputs and\nis included in the 'class' attribute in HTML outputs, in this respect\nit behaves like the <>.\n\nDocBook XSL Stylesheets translate DocBook 'role' attributes to HTML\n'class' attributes; CSS can then be used\nhttp://www.sagehill.net/docbookxsl/UsingCSS.html[to style the\ngenerated HTML].\n\n|reftext |docbook |\n'reftext' is used to set the DocBook 'xreflabel' attribute.\nThe 'reftext' attribute can an also be set by the 'BlockId' element.\n\n|====================================================================\n\n\nParagraphs\n----------\nParagraphs are blocks of text terminated by a blank line, the end of\nfile, or the start of a delimited block or a list. There are three\nparagraph syntaxes: normal, indented (literal) and admonition which\nare rendered, by default, with the corresponding paragraph style.\n\nEach syntax has a default style, but you can explicitly apply any\nparagraph style to any paragraph syntax. You can also apply\n<> styles to single paragraphs.\n\nThe built-in paragraph styles are: 'normal', 'literal', 'verse',\n'quote', 'listing', 'TIP', 'NOTE', 'IMPORTANT', 'WARNING', 'CAUTION',\n'abstract', 'partintro', 'comment', 'example', 'sidebar', 'source',\n'music', 'latex', 'graphviz'.\n\nnormal paragraph syntax\n~~~~~~~~~~~~~~~~~~~~~~~\nNormal paragraph syntax consists of one or more non-blank lines of\ntext. The first line must start hard against the left margin (no\nintervening white space). The default processing expectation is that\nof a normal paragraph of text.\n\n[[X85]]\nliteral paragraph syntax\n~~~~~~~~~~~~~~~~~~~~~~~~\nLiteral paragraphs are rendered verbatim in a monospaced font without\nany distinguishing background or border. By default there is no text\nformatting or substitutions within Literal paragraphs apart from\nSpecial Characters and Callouts.\n\nThe 'literal' style is applied implicitly to indented paragraphs i.e.\nwhere the first line of the paragraph is indented by one or more space\nor tab characters. For example:\n\n---------------------------------------------------------------------\n Consul *necessitatibus* per id,\n consetetur, eu pro everti postulant\n homero verear ea mea, qui.\n---------------------------------------------------------------------\n\nRenders:\n\n Consul *necessitatibus* per id,\n consetetur, eu pro everti postulant\n homero verear ea mea, qui.\n\nNOTE: Because <> can be indented it's possible for your\nindented paragraph to be misinterpreted as a list -- in situations\nlike this apply the 'literal' style to a normal paragraph.\n\nInstead of using a paragraph indent you could apply the 'literal'\nstyle explicitly, for example:\n\n---------------------------------------------------------------------\n[literal]\nConsul *necessitatibus* per id,\nconsetetur, eu pro everti postulant\nhomero verear ea mea, qui.\n---------------------------------------------------------------------\n\nRenders:\n\n[literal]\nConsul *necessitatibus* per id,\nconsetetur, eu pro everti postulant\nhomero verear ea mea, qui.\n\n[[X94]]\nquote and verse paragraph styles\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nThe optional 'attribution' and 'citetitle' attributes (positional\nattributes 2 and 3) specify the author and source respectively.\n\nThe 'verse' style retains the line breaks, for example:\n\n---------------------------------------------------------------------\n[verse, William Blake, from Auguries of Innocence]\nTo see a world in a grain of sand,\nAnd a heaven in a wild flower,\nHold infinity in the palm of your hand,\nAnd eternity in an hour.\n---------------------------------------------------------------------\n\nWhich is rendered as:\n\n[verse, William Blake, from Auguries of Innocence]\nTo see a world in a grain of sand,\nAnd a heaven in a wild flower,\nHold infinity in the palm of your hand,\nAnd eternity in an hour.\n\nThe 'quote' style flows the text at left and right margins, for\nexample:\n\n---------------------------------------------------------------------\n[quote, Bertrand Russell, The World of Mathematics (1956)]\nA good notation has subtlety and suggestiveness which at times makes\nit almost seem like a live teacher.\n---------------------------------------------------------------------\n\nWhich is rendered as:\n\n[quote, Bertrand Russell, The World of Mathematics (1956)]\nA good notation has subtlety and suggestiveness which at times makes\nit almost seem like a live teacher.\n\n[[X28]]\nAdmonition Paragraphs\n~~~~~~~~~~~~~~~~~~~~~\n'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION' admonishment\nparagraph styles are generated by placing `NOTE:`, `TIP:`,\n`IMPORTANT:`, `WARNING:` or `CAUTION:` as the first word of the\nparagraph. For example:\n\n NOTE: This is an example note.\n\nAlternatively, you can specify the paragraph admonition style\nexplicitly using an <>. For example:\n\n [NOTE]\n This is an example note.\n\nRenders:\n\nNOTE: This is an example note.\n\nTIP: If your admonition requires more than a single paragraph use an\n<> instead.\n\n[[X47]]\nAdmonition Icons and Captions\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nNOTE: Admonition customization with `icons`, `iconsdir`, `icon` and\n`caption` attributes does not apply when generating DocBook output. If\nyou are going the DocBook route then the <> `--no-icons`\nand `--icons-dir` options can be used to set the appropriate XSL\nStylesheets parameters.\n\nBy default the asciidoc(1) HTML backends generate text captions\ninstead of admonition icon image links. To generate links to icon\nimages define the <> attribute, for example using the `-a\nicons` command-line option.\n\nThe <> attribute sets the location of linked icon\nimages.\n\nYou can override the default icon image using the `icon` attribute to\nspecify the path of the linked image. For example:\n\n [icon=\"./images/icons/wink.png\"]\n NOTE: What lovely war.\n\nUse the `caption` attribute to customize the admonition captions (not\napplicable to `docbook` backend). The following example suppresses the\nicon image and customizes the caption of a 'NOTE' admonition\n(undefining the `icons` attribute with `icons=None` is only necessary\nif <> have been enabled):\n\n [icons=None, caption=\"My Special Note\"]\n NOTE: This is my special note.\n\nThis subsection also applies to <>.\n\n\n[[X104]]\nDelimited Blocks\n----------------\nDelimited blocks are blocks of text enveloped by leading and trailing\ndelimiter lines (normally a series of four or more repeated\ncharacters). The behavior of Delimited Blocks is specified by entries\nin configuration file `[blockdef-*]` sections.\n\nPredefined Delimited Blocks\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\nAsciiDoc ships with a number of predefined DelimitedBlocks (see the\n`asciidoc.conf` configuration file in the asciidoc(1) program\ndirectory):\n\nPredefined delimited block underlines:\n\n CommentBlock: //////////////////////////\n PassthroughBlock: ++++++++++++++++++++++++++\n ListingBlock: --------------------------\n LiteralBlock: ..........................\n SidebarBlock: **************************\n QuoteBlock: __________________________\n ExampleBlock: ==========================\n OpenBlock: --\n\n.Default DelimitedBlock substitutions\n[cols=\"2e,7*^\",frame=\"topbot\",options=\"header,autowidth\"]\n|=====================================================\n| |Attributes |Callouts |Macros | Quotes |Replacements\n|Special chars |Special words\n\n|PassthroughBlock |Yes |No |Yes |No |No |No |No\n|ListingBlock |No |Yes |No |No |No |Yes |No\n|LiteralBlock |No |Yes |No |No |No |Yes |No\n|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes\n|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes\n|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes\n|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes\n|=====================================================\n\nListing Blocks\n~~~~~~~~~~~~~~\n'ListingBlocks' are rendered verbatim in a monospaced font, they\nretain line and whitespace formatting and are often distinguished by a\nbackground or border. There is no text formatting or substitutions\nwithin Listing blocks apart from Special Characters and Callouts.\nListing blocks are often used for computer output and file listings.\n\nHere's an example:\n\n[listing]\n......................................\n--------------------------------------\n#include \n\nint main() {\n printf(\"Hello World!\\n\");\n exit(0);\n}\n--------------------------------------\n......................................\n\nWhich will be rendered like:\n\n--------------------------------------\n#include \n\nint main() {\n printf(\"Hello World!\\n\");\n exit(0);\n}\n--------------------------------------\n\nBy convention <> use the listing block syntax and\nare implemented as distinct listing block styles.\n\n[[X65]]\nLiteral Blocks\n~~~~~~~~~~~~~~\n'LiteralBlocks' are rendered just like <>.\nExample:\n\n---------------------------------------------------------------------\n...................................\nConsul *necessitatibus* per id,\nconsetetur, eu pro everti postulant\nhomero verear ea mea, qui.\n...................................\n---------------------------------------------------------------------\n\nRenders:\n...................................\nConsul *necessitatibus* per id,\nconsetetur, eu pro everti postulant\nhomero verear ea mea, qui.\n...................................\n\nIf the 'listing' style is applied to a LiteralBlock it will be\nrendered as a ListingBlock (this is handy if you have a listing\ncontaining a ListingBlock).\n\nSidebar Blocks\n~~~~~~~~~~~~~~\nA sidebar is a short piece of text presented outside the narrative\nflow of the main text. The sidebar is normally presented inside a\nbordered box to set it apart from the main text.\n\nThe sidebar body is treated like a normal section body.\n\nHere's an example:\n\n---------------------------------------------------------------------\n.An Example Sidebar\n************************************************\nAny AsciiDoc SectionBody element (apart from\nSidebarBlocks) can be placed inside a sidebar.\n************************************************\n---------------------------------------------------------------------\n\nWhich will be rendered like:\n\n.An Example Sidebar\n************************************************\nAny AsciiDoc SectionBody element (apart from\nSidebarBlocks) can be placed inside a sidebar.\n************************************************\n\n[[X26]]\nComment Blocks\n~~~~~~~~~~~~~~\nThe contents of 'CommentBlocks' are not processed; they are useful for\nannotations and for excluding new or outdated content that you don't\nwant displayed. CommentBlocks are never written to output files.\nExample:\n\n---------------------------------------------------------------------\n//////////////////////////////////////////\nCommentBlock contents are not processed by\nasciidoc(1).\n//////////////////////////////////////////\n---------------------------------------------------------------------\n\nSee also <>.\n\nNOTE: System macros are executed inside comment blocks.\n\n[[X76]]\nPassthrough Blocks\n~~~~~~~~~~~~~~~~~~\nBy default the block contents is subject only to 'attributes' and\n'macros' substitutions (use an explicit 'subs' attribute to apply\ndifferent substitutions). PassthroughBlock content will often be\nbackend specific. Here's an example:\n\n---------------------------------------------------------------------\n[subs=\"quotes\"]\n++++++++++++++++++++++++++++++++++++++\n\n++++++++++++++++++++++++++++++++++++++\n---------------------------------------------------------------------\n\nThe following styles can be applied to passthrough blocks:\n\npass::\n No substitutions are performed. This is equivalent to `subs=\"none\"`.\n\nasciimath, latexmath::\n By default no substitutions are performed, the contents are rendered\n as <>.\n\nQuote Blocks\n~~~~~~~~~~~~\n'QuoteBlocks' are used for quoted passages of text. There are two\nstyles: 'quote' and 'verse'. The style behavior is identical to\n<> except that blocks can contain\nmultiple paragraphs and, in the case of the 'quote' style, other\nsection elements. The first positional attribute sets the style, if\nno attributes are specified the 'quote' style is used. The optional\n'attribution' and 'citetitle' attributes (positional attributes 2 and\n3) specify the quote's author and source. For example:\n\n---------------------------------------------------------------------\n[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]\n____________________________________________________________________\nAs he spoke there was the sharp sound of horses' hoofs and\ngrating wheels against the curb, followed by a sharp pull at the\nbell. Holmes whistled.\n\n\"A pair, by the sound,\" said he. \"Yes,\" he continued, glancing\nout of the window. \"A nice little brougham and a pair of\nbeauties. A hundred and fifty guineas apiece. There's money in\nthis case, Watson, if there is nothing else.\"\n____________________________________________________________________\n---------------------------------------------------------------------\n\nWhich is rendered as:\n\n[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]\n____________________________________________________________________\nAs he spoke there was the sharp sound of horses' hoofs and\ngrating wheels against the curb, followed by a sharp pull at the\nbell. Holmes whistled.\n\n\"A pair, by the sound,\" said he. \"Yes,\" he continued, glancing\nout of the window. \"A nice little brougham and a pair of\nbeauties. A hundred and fifty guineas apiece. There's money in\nthis case, Watson, if there is nothing else.\"\n____________________________________________________________________\n\n[[X48]]\nExample Blocks\n~~~~~~~~~~~~~~\n'ExampleBlocks' encapsulate the DocBook Example element and are used\nfor, well, examples. Example blocks can be titled by preceding them\nwith a 'BlockTitle'. DocBook toolchains will normally automatically\nnumber examples and generate a 'List of Examples' backmatter section.\n\nExample blocks are delimited by lines of equals characters and can\ncontain any block elements apart from Titles, BlockTitles and\nSidebars) inside an example block. For example:\n\n---------------------------------------------------------------------\n.An example\n=====================================================================\nQui in magna commodo, est labitur dolorum an. Est ne magna primis\nadolescens.\n=====================================================================\n---------------------------------------------------------------------\n\nRenders:\n\n.An example\n=====================================================================\nQui in magna commodo, est labitur dolorum an. Est ne magna primis\nadolescens.\n=====================================================================\n\nA title prefix that can be inserted with the `caption` attribute\n(HTML backends). For example:\n\n---------------------------------------------------------------------\n[caption=\"Example 1: \"]\n.An example with a custom caption\n=====================================================================\nQui in magna commodo, est labitur dolorum an. Est ne magna primis\nadolescens.\n=====================================================================\n---------------------------------------------------------------------\n\n[[X22]]\nAdmonition Blocks\n~~~~~~~~~~~~~~~~~\nThe 'ExampleBlock' definition includes a set of admonition\n<> ('NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION') for\ngenerating admonition blocks (admonitions containing more than a\n<>). Just precede the 'ExampleBlock' with an\nattribute list specifying the admonition style name. For example:\n\n---------------------------------------------------------------------\n[NOTE]\n.A NOTE admonition block\n=====================================================================\nQui in magna commodo, est labitur dolorum an. Est ne magna primis\nadolescens.\n\n. Fusce euismod commodo velit.\n. Vivamus fringilla mi eu lacus.\n .. Fusce euismod commodo velit.\n .. Vivamus fringilla mi eu lacus.\n. Donec eget arcu bibendum\n nunc consequat lobortis.\n=====================================================================\n---------------------------------------------------------------------\n\nRenders:\n\n[NOTE]\n.A NOTE admonition block\n=====================================================================\nQui in magna commodo, est labitur dolorum an. Est ne magna primis\nadolescens.\n\n. Fusce euismod commodo velit.\n. Vivamus fringilla mi eu lacus.\n .. Fusce euismod commodo velit.\n .. Vivamus fringilla mi eu lacus.\n. Donec eget arcu bibendum\n nunc consequat lobortis.\n=====================================================================\n\nSee also <>.\n\n[[X29]]\nOpen Blocks\n~~~~~~~~~~~\nOpen blocks are special:\n\n- The open block delimiter is line containing two hyphen characters\n (instead of four or more repeated characters).\n\n- They can be used to group block elements for <>.\n\n- Open blocks can be styled to behave like any other type of delimited\n block. The following built-in styles can be applied to open\n blocks: 'literal', 'verse', 'quote', 'listing', 'TIP', 'NOTE',\n 'IMPORTANT', 'WARNING', 'CAUTION', 'abstract', 'partintro',\n 'comment', 'example', 'sidebar', 'source', 'music', 'latex',\n 'graphviz'. For example, the following open block and listing block\n are functionally identical:\n\n [listing]\n --\n Lorum ipsum ...\n --\n\n ---------------\n Lorum ipsum ...\n ---------------\n\n- An unstyled open block groups section elements but otherwise does\n nothing.\n\nOpen blocks are used to generate document abstracts and book part\nintroductions:\n\n- Apply the 'abstract' style to generate an abstract, for example:\n\n [abstract]\n --\n In this paper we will ...\n --\n\n. Apply the 'partintro' style to generate a book part introduction for\n a multi-part book, for example:\n\n [partintro]\n .Optional part introduction title\n --\n Optional part introduction goes here.\n --\n\n\n[[X64]]\nLists\n-----\n.List types\n- Bulleted lists. Also known as itemized or unordered lists.\n- Numbered lists. Also called ordered lists.\n- Labeled lists. Sometimes called variable or definition lists.\n- Callout lists (a list of callout annotations).\n\n.List behavior\n- List item indentation is optional and does not determine nesting,\n indentation does however make the source more readable.\n- Another list or a literal paragraph immediately following a list\n item will be implicitly included in the list item; use <> to explicitly append other block elements to a\n list item.\n- A comment block or a comment line block macro element will terminate\n a list -- use inline comment lines to put comments inside lists.\n- The `listindex` <> is the current list item\n index (1..). If this attribute is used outside a list then it's value\n is the number of items in the most recently closed list. Useful for\n displaying the number of items in a list.\n\nBulleted Lists\n~~~~~~~~~~~~~~\nBulleted list items start with a single dash or one to five asterisks\nfollowed by some white space then some text. Bulleted list syntaxes\nare:\n\n...................\n- List item.\n* List item.\n** List item.\n*** List item.\n**** List item.\n***** List item.\n...................\n\nNumbered Lists\n~~~~~~~~~~~~~~\nList item numbers are explicit or implicit.\n\n.Explicit numbering\nList items begin with a number followed by some white space then the\nitem text. The numbers can be decimal (arabic), roman (upper or lower\ncase) or alpha (upper or lower case). Decimal and alpha numbers are\nterminated with a period, roman numbers are terminated with a closing\nparenthesis. The different terminators are necessary to ensure 'i',\n'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and\n'x' alpha numbers. Examples:\n\n.....................................................................\n1. Arabic (decimal) numbered list item.\na. Lower case alpha (letter) numbered list item.\nF. Upper case alpha (letter) numbered list item.\niii) Lower case roman numbered list item.\nIX) Upper case roman numbered list item.\n.....................................................................\n\n.Implicit numbering\nList items begin one to five period characters, followed by some white\nspace then the item text. Examples:\n\n.....................................................................\n. Arabic (decimal) numbered list item.\n.. Lower case alpha (letter) numbered list item.\n... Lower case roman numbered list item.\n.... Upper case alpha (letter) numbered list item.\n..... Upper case roman numbered list item.\n.....................................................................\n\nYou can use the 'style' attribute (also the first positional\nattribute) to specify an alternative numbering style. The numbered\nlist style can be one of the following values: 'arabic', 'loweralpha',\n'upperalpha', 'lowerroman', 'upperroman'.\n\nHere are some examples of bulleted and numbered lists:\n\n---------------------------------------------------------------------\n- Praesent eget purus quis magna eleifend eleifend.\n 1. Fusce euismod commodo velit.\n a. Fusce euismod commodo velit.\n b. Vivamus fringilla mi eu lacus.\n c. Donec eget arcu bibendum nunc consequat lobortis.\n 2. Vivamus fringilla mi eu lacus.\n i) Fusce euismod commodo velit.\n ii) Vivamus fringilla mi eu lacus.\n 3. Donec eget arcu bibendum nunc consequat lobortis.\n 4. Nam fermentum mattis ante.\n- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.\n * Fusce euismod commodo velit.\n ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis\n adolescens. Sit munere ponderum dignissim et. Minim luptatum et\n vel.\n ** Vivamus fringilla mi eu lacus.\n * Donec eget arcu bibendum nunc consequat lobortis.\n- Nulla porttitor vulputate libero.\n . Fusce euismod commodo velit.\n . Vivamus fringilla mi eu lacus.\n[upperroman]\n .. Fusce euismod commodo velit.\n .. Vivamus fringilla mi eu lacus.\n . Donec eget arcu bibendum nunc consequat lobortis.\n---------------------------------------------------------------------\n\nWhich render as:\n\n- Praesent eget purus quis magna eleifend eleifend.\n 1. Fusce euismod commodo velit.\n a. Fusce euismod commodo velit.\n b. Vivamus fringilla mi eu lacus.\n c. Donec eget arcu bibendum nunc consequat lobortis.\n 2. Vivamus fringilla mi eu lacus.\n i) Fusce euismod commodo velit.\n ii) Vivamus fringilla mi eu lacus.\n 3. Donec eget arcu bibendum nunc consequat lobortis.\n 4. Nam fermentum mattis ante.\n- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.\n * Fusce euismod commodo velit.\n ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis\n adolescens. Sit munere ponderum dignissim et. Minim luptatum et\n vel.\n ** Vivamus fringilla mi eu lacus.\n * Donec eget arcu bibendum nunc consequat lobortis.\n- Nulla porttitor vulputate libero.\n . Fusce euismod commodo velit.\n . Vivamus fringilla mi eu lacus.\n[upperroman]\n .. Fusce euismod commodo velit.\n .. Vivamus fringilla mi eu lacus.\n . Donec eget arcu bibendum nunc consequat lobortis.\n\nA predefined 'compact' option is available to bulleted and numbered\nlists -- this translates to the DocBook 'spacing=\"compact\"' lists\nattribute which may or may not be processed by the DocBook toolchain.\nExample:\n\n [options=\"compact\"]\n - Compact list item.\n - Another compact list item.\n\nTIP: To apply the 'compact' option globally define a document-wide\n'compact-option' attribute, e.g. using the `-a compact-option`\ncommand-line option.\n\nYou can set the list start number using the 'start' attribute (works\nfor HTML outputs and DocBook outputs processed by DocBook XSL\nStylesheets). Example:\n\n [start=7]\n . List item 7.\n . List item 8.\n\nLabeled Lists\n~~~~~~~~~~~~~\nLabeled list items consist of one or more text labels followed by the\ntext of the list item.\n\nAn item label begins a line with an alphanumeric character hard\nagainst the left margin and ends with two, three or four colons or two\nsemi-colons. A list item can have multiple labels, one per line.\n\nThe list item text consists of one or more lines of text starting\nafter the last label (either on the same line or a new line) and can\nbe followed by nested List or ListParagraph elements. Item text can be\noptionally indented.\n\nHere are some examples:\n\n---------------------------------------------------------------------\nIn::\nLorem::\n Fusce euismod commodo velit.\n\n Fusce euismod commodo velit.\n\nIpsum:: Vivamus fringilla mi eu lacus.\n * Vivamus fringilla mi eu lacus.\n * Donec eget arcu bibendum nunc consequat lobortis.\nDolor::\n Donec eget arcu bibendum nunc consequat lobortis.\n Suspendisse;;\n A massa id sem aliquam auctor.\n Morbi;;\n Pretium nulla vel lorem.\n In;;\n Dictum mauris in urna.\n Vivamus::: Fringilla mi eu lacus.\n Donec::: Eget arcu bibendum nunc consequat lobortis.\n---------------------------------------------------------------------\n\nWhich render as:\n\nIn::\nLorem::\n Fusce euismod commodo velit.\n\n Fusce euismod commodo velit.\n\nIpsum:: Vivamus fringilla mi eu lacus.\n * Vivamus fringilla mi eu lacus.\n * Donec eget arcu bibendum nunc consequat lobortis.\nDolor::\n Donec eget arcu bibendum nunc consequat lobortis.\n Suspendisse;;\n A massa id sem aliquam auctor.\n Morbi;;\n Pretium nulla vel lorem.\n In;;\n Dictum mauris in urna.\n Vivamus::: Fringilla mi eu lacus.\n Donec::: Eget arcu bibendum nunc consequat lobortis.\n\nHorizontal labeled list style\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nThe 'horizontal' labeled list style (also the first positional\nattribute) places the list text side-by-side with the label instead of\nunder the label. Here is an example:\n\n---------------------------------------------------------------------\n[horizontal]\n*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est\nlabitur dolorum an. Est ne magna primis adolescens.\n\n Fusce euismod commodo velit.\n\n*Ipsum*:: Vivamus fringilla mi eu lacus.\n- Vivamus fringilla mi eu lacus.\n- Donec eget arcu bibendum nunc consequat lobortis.\n\n*Dolor*::\n - Vivamus fringilla mi eu lacus.\n - Donec eget arcu bibendum nunc consequat lobortis.\n\n---------------------------------------------------------------------\n\nWhich render as:\n\n[horizontal]\n*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est\nlabitur dolorum an. Est ne magna primis adolescens.\n\n Fusce euismod commodo velit.\n\n*Ipsum*:: Vivamus fringilla mi eu lacus.\n- Vivamus fringilla mi eu lacus.\n- Donec eget arcu bibendum nunc consequat lobortis.\n\n*Dolor*::\n - Vivamus fringilla mi eu lacus.\n - Donec eget arcu bibendum nunc consequat lobortis.\n\n[NOTE]\n=====================================================================\n- Current PDF toolchains do not make a good job of determining\n the relative column widths for horizontal labeled lists.\n- Nested horizontal labeled lists will generate DocBook validation\n errors because the 'DocBook XML V4.2' DTD does not permit nested\n informal tables (although <> and\n <> process them correctly).\n- The label width can be set as a percentage of the total width by\n setting the 'width' attribute e.g. `width=\"10%\"`\n=====================================================================\n\nQuestion and Answer Lists\n~~~~~~~~~~~~~~~~~~~~~~~~~\nAsciiDoc comes pre-configured with a 'qanda' style labeled list for generating\nDocBook question and answer (Q&A) lists. Example:\n\n---------------------------------------------------------------------\n[qanda]\nQuestion one::\n Answer one.\nQuestion two::\n Answer two.\n---------------------------------------------------------------------\n\nRenders:\n\n[qanda]\nQuestion one::\n Answer one.\nQuestion two::\n Answer two.\n\nGlossary Lists\n~~~~~~~~~~~~~~\nAsciiDoc comes pre-configured with a 'glossary' style labeled list for\ngenerating DocBook glossary lists. Example:\n\n---------------------------------------------------------------------\n[glossary]\nA glossary term::\n The corresponding definition.\nA second glossary term::\n The corresponding definition.\n---------------------------------------------------------------------\n\nFor working examples see the `article.txt` and `book.txt` documents in\nthe AsciiDoc `./doc` distribution directory.\n\nNOTE: To generate valid DocBook output glossary lists must be located\nin a section that uses the 'glossary' <>.\n\nBibliography Lists\n~~~~~~~~~~~~~~~~~~\nAsciiDoc comes with a predefined 'bibliography' bulleted list style\ngenerating DocBook bibliography entries. Example:\n\n---------------------------------------------------------------------\n[bibliography]\n.Optional list title\n- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX\n Programming'. Addison-Wesley. ISBN 0-13-142901-9.\n- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.\n 'DocBook - The Definitive Guide'. O'Reilly & Associates.\n 1999. ISBN 1-56592-580-7.\n---------------------------------------------------------------------\n\nThe `[[[]]]` syntax is a bibliography entry anchor, it\ngenerates an anchor named `` and additionally displays\n`[]` at the anchor position. For example `[[[taoup]]]`\ngenerates an anchor named `taoup` that displays `[taoup]` at the\nanchor position. Cite the reference from elsewhere your document using\n`<>`, this displays a hyperlink (`[taoup]`) to the\ncorresponding bibliography entry anchor.\n\nFor working examples see the `article.txt` and `book.txt` documents in\nthe AsciiDoc `./doc` distribution directory.\n\nNOTE: To generate valid DocBook output bibliography lists must be\nlocated in a <>.\n\n[[X15]]\nList Item Continuation\n~~~~~~~~~~~~~~~~~~~~~~\nAnother list or a literal paragraph immediately following a list item\nis implicitly appended to the list item; to append other block\nelements to a list item you need to explicitly join them to the list\nitem with a 'list continuation' (a separator line containing a single\nplus character). Multiple block elements can be appended to a list\nitem using list continuations (provided they are legal list item\nchildren in the backend markup).\n\nHere are some examples of list item continuations: list item one\ncontains multiple continuations; list item two is continued with an\n<> containing multiple elements:\n\n---------------------------------------------------------------------\n1. List item one.\n+\nList item one continued with a second paragraph followed by an\nIndented block.\n+\n.................\n$ ls *.sh\n$ mv *.sh ~/tmp\n.................\n+\nList item continued with a third paragraph.\n\n2. List item two continued with an open block.\n+\n--\nThis paragraph is part of the preceding list item.\n\na. This list is nested and does not require explicit item continuation.\n+\nThis paragraph is part of the preceding list item.\n\nb. List item b.\n\nThis paragraph belongs to item two of the outer list.\n--\n---------------------------------------------------------------------\n\nRenders:\n\n1. List item one.\n+\nList item one continued with a second paragraph followed by an\nIndented block.\n+\n.................\n$ ls *.sh\n$ mv *.sh ~/tmp\n.................\n+\nList item continued with a third paragraph.\n\n2. List item two continued with an open block.\n+\n--\nThis paragraph is part of the preceding list item.\n\na. This list is nested and does not require explicit item continuation.\n+\nThis paragraph is part of the preceding list item.\n\nb. List item b.\n\nThis paragraph belongs to item two of the outer list.\n--\n\n\n[[X92]]\nFootnotes\n---------\nThe shipped AsciiDoc configuration includes three footnote inline\nmacros:\n\n`footnote:[]`::\n Generates a footnote with text ``.\n\n`footnoteref:[,]`::\n Generates a footnote with a reference ID `` and text ``.\n\n`footnoteref:[]`::\n Generates a reference to the footnote with ID ``.\n\nThe footnote text can span multiple lines.\n\nThe 'xhtml11' and 'html5' backends render footnotes dynamically using\nJavaScript; 'html4' outputs do not use JavaScript and leave the\nfootnotes inline; 'docbook' footnotes are processed by the downstream\nDocBook toolchain.\n\nExample footnotes:\n\n A footnote footnote:[An example footnote.];\n a second footnote with a reference ID footnoteref:[note2,Second footnote.];\n finally a reference to the second footnote footnoteref:[note2].\n\nRenders:\n\nA footnote footnote:[An example footnote.];\na second footnote with a reference ID footnoteref:[note2,Second footnote.];\nfinally a reference to the second footnote footnoteref:[note2].\n\n\nIndexes\n-------\nThe shipped AsciiDoc configuration includes the inline macros for\ngenerating DocBook index entries.\n\n`indexterm:[,,]`::\n`(((,,)))`::\n This inline macro generates an index term (the `` and\n `` positional attributes are optional). Example:\n `indexterm:[Tigers,Big cats]` (or, using the alternative syntax\n `(((Tigers,Big cats)))`. Index terms that have secondary and\n tertiary entries also generate separate index terms for the\n secondary and tertiary entries. The index terms appear in the\n index, not the primary text flow.\n\n`indexterm2:[]`::\n`(())`::\n This inline macro generates an index term that appears in both the\n index and the primary text flow. The `` should not be\n padded to the left or right with white space characters.\n\nFor working examples see the `article.txt` and `book.txt` documents in\nthe AsciiDoc `./doc` distribution directory.\n\nNOTE: Index entries only really make sense if you are generating\nDocBook markup -- DocBook conversion programs automatically generate\nan index at the point an 'Index' section appears in source document.\n\n\n[[X105]]\nCallouts\n--------\nCallouts are a mechanism for annotating verbatim text (for example:\nsource code, computer output and user input). Callout markers are\nplaced inside the annotated text while the actual annotations are\npresented in a callout list after the annotated text. Here's an\nexample:\n\n---------------------------------------------------------------------\n .MS-DOS directory listing\n -----------------------------------------------------\n 10/17/97 9:04 bin\n 10/16/97 14:11 DOS \\<1>\n 10/16/97 14:40 Program Files\n 10/16/97 14:46 TEMP\n 10/17/97 9:04 tmp\n 10/16/97 14:37 WINNT\n 10/16/97 14:25 119 AUTOEXEC.BAT \\<2>\n 2/13/94 6:21 54,619 COMMAND.COM \\<2>\n 10/16/97 14:25 115 CONFIG.SYS \\<2>\n 11/16/97 17:17 61,865,984 pagefile.sys\n 2/13/94 6:21 9,349 WINA20.386 \\<3>\n -----------------------------------------------------\n\n \\<1> This directory holds MS-DOS.\n \\<2> System startup code for DOS.\n \\<3> Some sort of Windows 3.1 hack.\n---------------------------------------------------------------------\n\nWhich renders:\n\n.MS-DOS directory listing\n-----------------------------------------------------\n10/17/97 9:04 bin\n10/16/97 14:11 DOS <1>\n10/16/97 14:40 Program Files\n10/16/97 14:46 TEMP\n10/17/97 9:04 tmp\n10/16/97 14:37 WINNT\n10/16/97 14:25 119 AUTOEXEC.BAT <2>\n 2/13/94 6:21 54,619 COMMAND.COM <2>\n10/16/97 14:25 115 CONFIG.SYS <2>\n11/16/97 17:17 61,865,984 pagefile.sys\n 2/13/94 6:21 9,349 WINA20.386 <3>\n-----------------------------------------------------\n\n<1> This directory holds MS-DOS.\n<2> System startup code for DOS.\n<3> Some sort of Windows 3.1 hack.\n\n.Explanation\n- The callout marks are whole numbers enclosed in angle brackets --\n they refer to the correspondingly numbered item in the following\n callout list.\n- By default callout marks are confined to 'LiteralParagraphs',\n 'LiteralBlocks' and 'ListingBlocks' (although this is a\n configuration file option and can be changed).\n- Callout list item numbering is fairly relaxed -- list items can\n start with ``, `n>` or `>` where `n` is the optional list item\n number (in the latter case list items starting with a single `>`\n character are implicitly numbered starting at one).\n- Callout lists should not be nested.\n- Callout lists start list items hard against the left margin.\n- If you want to present a number inside angle brackets you'll need to\n escape it with a backslash to prevent it being interpreted as a\n callout mark.\n\nNOTE: Define the AsciiDoc 'icons' attribute (for example using the `-a\nicons` command-line option) to display callout icons.\n\nImplementation Notes\n~~~~~~~~~~~~~~~~~~~~\nCallout marks are generated by the 'callout' inline macro while\ncallout lists are generated using the 'callout' list definition. The\n'callout' macro and 'callout' list are special in that they work\ntogether. The 'callout' inline macro is not enabled by the normal\n'macros' substitutions option, instead it has its own 'callouts'\nsubstitution option.\n\nThe following attributes are available during inline callout macro\nsubstitution:\n\n`{index}`::\n The callout list item index inside the angle brackets.\n`{coid}`::\n An identifier formatted like `CO-` that\n uniquely identifies the callout mark. For example `CO2-4`\n identifies the fourth callout mark in the second set of callout\n marks.\n\nThe `{coids}` attribute can be used during callout list item\nsubstitution -- it is a space delimited list of callout IDs that refer\nto the explanatory list item.\n\nIncluding callouts in included code\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nYou can annotate working code examples with callouts -- just remember\nto put the callouts inside source code comments. This example displays\nthe `test.py` source file (containing a single callout) using the\n'source' (code highlighter) filter:\n\n.AsciiDoc source\n---------------------------------------------------------------------\n [source,python]\n -------------------------------------------\n \\include::test.py[]\n -------------------------------------------\n\n \\<1> Print statement.\n---------------------------------------------------------------------\n\n.Included `test.py` source\n---------------------------------------------------------------------\nprint 'Hello World!' # \\<1>\n---------------------------------------------------------------------\n\n\nMacros\n------\nMacros are a mechanism for substituting parametrized text into output\ndocuments.\n\nMacros have a 'name', a single 'target' argument and an 'attribute\nlist'. The usual syntax is `:[]` (for\ninline macros) and `::[]` (for block\nmacros). Here are some examples:\n\n http://www.docbook.org/[DocBook.org]\n include::chapt1.txt[tabsize=2]\n mailto:srackham@gmail.com[]\n\n.Macro behavior\n- `` is the macro name. It can only contain letters, digits or\n dash characters and cannot start with a dash.\n- The optional `` cannot contain white space characters.\n- `` is a <> enclosed in square\n brackets.\n- `]` characters inside attribute lists must be escaped with a\n backslash.\n- Expansion of macro references can normally be escaped by prefixing a\n backslash character (see the AsciiDoc 'FAQ' for examples of\n exceptions to this rule).\n- Attribute references in block macros are expanded.\n- The substitutions performed prior to Inline macro macro expansion\n are determined by the inline context.\n- Macros are processed in the order they appear in the configuration\n file(s).\n- Calls to inline macros can be nested inside different inline macros\n (an inline macro call cannot contain a nested call to itself).\n- In addition to ``, `` and `` the\n `` and `` named groups are available to\n <>. A macro is a passthrough macro if the\n definition includes a `` named group.\n\nInline Macros\n~~~~~~~~~~~~~\nInline Macros occur in an inline element context. Predefined Inline\nmacros include 'URLs', 'image' and 'link' macros.\n\nURLs\n^^^^\n'http', 'https', 'ftp', 'file', 'mailto' and 'callto' URLs are\nrendered using predefined inline macros.\n\n- If you don't need a custom link caption you can enter the 'http',\n 'https', 'ftp', 'file' URLs and email addresses without any special\n macro syntax.\n- If the `` is empty the URL is displayed.\n\nHere are some examples:\n\n http://www.docbook.org/[DocBook.org]\n http://www.docbook.org/\n mailto:joe.bloggs@foobar.com[email Joe Bloggs]\n joe.bloggs@foobar.com\n\nWhich are rendered:\n\nhttp://www.docbook.org/[DocBook.org]\n\nhttp://www.docbook.org/\n\nmailto:joe.bloggs@foobar.com[email Joe Bloggs]\n\njoe.bloggs@foobar.com\n\nIf the `` necessitates space characters use `%20`, for example\n`large%20image.png`.\n\nInternal Cross References\n^^^^^^^^^^^^^^^^^^^^^^^^^\nTwo AsciiDoc inline macros are provided for creating hypertext links\nwithin an AsciiDoc document. You can use either the standard macro\nsyntax or the (preferred) alternative.\n\n[[X30]]\nanchor\n++++++\nUsed to specify hypertext link targets:\n\n [[,]]\n anchor:[]\n\nThe `` is a unique string that conforms to the output markup's\nanchor syntax. The optional `` is the text to be displayed\nby captionless 'xref' macros that refer to this anchor. The optional\n`` is only really useful when generating DocBook output.\nExample anchor:\n\n [[X1]]\n\nYou may have noticed that the syntax of this inline element is the\nsame as that of the <>, this is no\ncoincidence since they are functionally equivalent.\n\nxref\n++++\nCreates a hypertext link to a document anchor.\n\n <<,>>\n xref:[]\n\nThe `` refers to an anchor ID. The optional `` is the\nlink's displayed text. Example:\n\n <>\n\nIf `` is not specified then the displayed text is\nauto-generated:\n\n- The AsciiDoc 'xhtml11' and 'html5' backends display the ``\n enclosed in square brackets.\n- If DocBook is produced the DocBook toolchain is responsible for the\n displayed text which will normally be the referenced figure, table\n or section title number followed by the element's title text.\n\nHere is an example:\n\n---------------------------------------------------------------------\n[[tiger_image]]\n.Tyger tyger\nimage::tiger.png[]\n\nThis can be seen in <>.\n---------------------------------------------------------------------\n\nLinking to Local Documents\n^^^^^^^^^^^^^^^^^^^^^^^^^^\nHypertext links to files on the local file system are specified using\nthe 'link' inline macro.\n\n link:[]\n\nThe 'link' macro generates relative URLs. The link macro `` is\nthe target file name (relative to the file system location of the\nreferring document). The optional `` is the link's displayed\ntext. If `` is not specified then `` is displayed.\nExample:\n\n link:downloads/foo.zip[download foo.zip]\n\nYou can use the `#` syntax to refer to an anchor within\na target document but this usually only makes sense when targeting\nHTML documents.\n\n[[X9]]\nImages\n^^^^^^\nInline images are inserted into the output document using the 'image'\nmacro. The inline syntax is:\n\n image:[]\n\nThe contents of the image file `` is displayed. To display the\nimage its file format must be supported by the target backend\napplication. HTML and DocBook applications normally support PNG or JPG\nfiles.\n\n`` file name paths are relative to the location of the\nreferring document.\n\n[[X55]]\n.Image macro attributes\n- The optional 'alt' attribute is also the first positional attribute,\n it specifies alternative text which is displayed if the output\n application is unable to display the image file (see also\n http://htmlhelp.com/feature/art3.htm[Use of ALT texts in IMGs]). For\n example:\n\n image:images/logo.png[Company Logo]\n\n- The optional 'title' attribute provides a title for the image. The\n <> renders the title alongside the image.\n The inline image macro displays the title as a popup ``tooltip'' in\n visual browsers (AsciiDoc HTML outputs only).\n\n- The optional `width` and `height` attributes scale the image size\n and can be used in any combination. The units are pixels. The\n following example scales the previous example to a height of 32\n pixels:\n\n image:images/logo.png[\"Company Logo\",height=32]\n\n- The optional `link` attribute is used to link the image to an\n external document. The following example links a screenshot\n thumbnail to a full size version:\n\n image:screen-thumbnail.png[height=32,link=\"screen.png\"]\n\n- The optional `scaledwidth` attribute is only used in DocBook block\n images (specifically for PDF documents). The following example\n scales the images to 75% of the available print width:\n\n image::images/logo.png[scaledwidth=\"75%\",alt=\"Company Logo\"]\n\n- The image `scale` attribute sets the DocBook `imagedata` element\n `scale` attribute.\n\n- The optional `align` attribute is used for horizontal image\n alignment. Allowed values are `center`, `left` and `right`. For\n example:\n\n image::images/tiger.png[\"Tiger image\",align=\"left\"]\n\n- The optional `float` attribute floats the image `left` or `right` on\n the page (works with HTML outputs only, has no effect on DocBook\n outputs). `float` and `align` attributes are mutually exclusive.\n Use the `unfloat::[]` block macro to stop floating.\n\nComment Lines\n^^^^^^^^^^^^^\nSee <>.\n\nBlock Macros\n~~~~~~~~~~~~\nA Block macro reference must be contained in a single line separated\neither side by a blank line or a block delimiter.\n\nBlock macros behave just like Inline macros, with the following\ndifferences:\n\n- They occur in a block context.\n- The default syntax is `::[]` (two\n colons, not one).\n- Markup template section names end in `-blockmacro` instead of\n `-inlinemacro`.\n\nBlock Identifier\n^^^^^^^^^^^^^^^^\nThe Block Identifier macro sets the `id` attribute and has the same\nsyntax as the <> since it performs\nessentially the same function -- block templates use the `id`\nattribute as a block element ID. For example:\n\n [[X30]]\n\nThis is equivalent to the `[id=\"X30\"]` <>).\n\n[[X49]]\nImages\n^^^^^^\nThe 'image' block macro is used to display images in a block context.\nThe syntax is:\n\n image::[]\n\nThe block `image` macro has the same <> as it's\n<> counterpart.\n\nBlock images can be titled by preceding the 'image' macro with a\n'BlockTitle'. DocBook toolchains normally number titled block images\nand optionally list them in an automatically generated 'List of\nFigures' backmatter section.\n\nThis example:\n\n .Main circuit board\n image::images/layout.png[J14P main circuit board]\n\nis equivalent to:\n\n image::images/layout.png[\"J14P main circuit board\",\n title=\"Main circuit board\"]\n\nA title prefix that can be inserted with the `caption` attribute\n(HTML backends). For example:\n\n .Main circuit board\n [caption=\"Figure 2: \"]\n image::images/layout.png[J14P main circuit board]\n\n[[X66]]\n.Embedding images in XHTML documents\n*********************************************************************\nIf you define the `data-uri` attribute then images will be embedded in\nXHTML outputs using the\nhttp://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme]. You\ncan use the 'data-uri' attribute with the 'xhtml11' and 'html5'\nbackends to produce single-file XHTML documents with embedded images\nand CSS, for example:\n\n $ asciidoc -a data-uri mydocument.txt\n\n[NOTE]\n======\n- All current popular browsers support data URIs, although versions\n of Internet Explorer prior to version 8 do not.\n- Some browsers limit the size of data URIs.\n======\n*********************************************************************\n\n[[X25]]\nComment Lines\n^^^^^^^^^^^^^\nSingle lines starting with two forward slashes hard up against the\nleft margin are treated as comments. Comment lines do not appear in\nthe output unless the 'showcomments' attribute is defined. Comment\nlines have been implemented as both block and inline macros so a\ncomment line can appear as a stand-alone block or within block elements\nthat support inline macro expansion. Example comment line:\n\n // This is a comment.\n\nIf the 'showcomments' attribute is defined comment lines are written\nto the output:\n\n- In DocBook the comment lines are enclosed by the 'remark' element\n (which may or may not be rendered by your toolchain).\n- The 'showcomments' attribute does not expose <>.\n Comment Blocks are never passed to the output.\n\nSystem Macros\n~~~~~~~~~~~~~\nSystem macros are block macros that perform a predefined task and are\nhardwired into the asciidoc(1) program.\n\n- You can escape system macros with a leading backslash character\n (as you can with other macros).\n- The syntax and tasks performed by system macros is built into\n asciidoc(1) so they don't appear in configuration files. You can\n however customize the syntax by adding entries to a configuration\n file `[macros]` section.\n\n[[X63]]\nInclude Macros\n^^^^^^^^^^^^^^\nThe `include` and `include1` system macros to include the contents of\na named file into the source document.\n\nThe `include` macro includes a file as if it were part of the parent\ndocument -- tabs are expanded and system macros processed. The\ncontents of `include1` files are not subject to tab expansion or\nsystem macro processing nor are attribute or lower priority\nsubstitutions performed. The `include1` macro's intended use is to\ninclude verbatim embedded CSS or scripts into configuration file\nheaders. Example:\n\n------------------------------------\n\\include::chapter1.txt[tabsize=4]\n------------------------------------\n\n.Include macro behavior\n- If the included file name is specified with a relative path then the\n path is relative to the location of the referring document.\n- Include macros can appear inside configuration files.\n- Files included from within 'DelimitedBlocks' are read to completion\n to avoid false end-of-block underline termination.\n- Attribute references are expanded inside the include 'target'; if an\n attribute is undefined then the included file is silently skipped.\n- The 'tabsize' macro attribute sets the number of space characters to\n be used for tab expansion in the included file (not applicable to\n `include1` macro).\n- The 'depth' macro attribute sets the maximum permitted number of\n subsequent nested includes (not applicable to `include1` macro which\n does not process nested includes). Setting 'depth' to '1' disables\n nesting inside the included file. By default, nesting is limited to\n a depth of ten.\n- If the he 'warnings' attribute is set to 'False' (or any other\n Python literal that evaluates to boolean false) then no warning\n message is printed if the included file does not exist. By default\n 'warnings' are enabled.\n- Internally the `include1` macro is translated to the `include1`\n system attribute which means it must be evaluated in a region where\n attribute substitution is enabled. To inhibit nested substitution in\n included files it is preferable to use the `include` macro and set\n the attribute `depth=1`.\n\nConditional Inclusion Macros\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nLines of text in the source document can be selectively included or\nexcluded from processing based on the existence (or not) of a document\nattribute.\n\nDocument text between the `ifdef` and `endif` macros is included if a\ndocument attribute is defined:\n\n ifdef::[]\n :\n endif::[]\n\nDocument text between the `ifndef` and `endif` macros is not included\nif a document attribute is defined:\n\n ifndef::[]\n :\n endif::[]\n\n`` is an attribute name which is optional in the trailing\n`endif` macro.\n\nIf you only want to process a single line of text then the text can be\nput inside the square brackets and the `endif` macro omitted, for\nexample:\n\n ifdef::revnumber[Version number 42]\n\nIs equivalent to:\n\n ifdef::revnumber[]\n Version number 42\n endif::revnumber[]\n\n'ifdef' and 'ifndef' macros also accept multiple attribute names:\n\n- Multiple ',' separated attribute names evaluate to defined if one\n or more of the attributes is defined, otherwise it's value is\n undefined.\n- Multiple '+' separated attribute names evaluate to defined if all\n of the attributes is defined, otherwise it's value is undefined.\n\nDocument text between the `ifeval` and `endif` macros is included if\nthe Python expression inside the square brackets is true. Example:\n\n ifeval::[{rs458}==2]\n :\n endif::[]\n\n- Document attribute references are expanded before the expression is\n evaluated.\n- If an attribute reference is undefined then the expression is\n considered false.\n\nTake a look at the `*.conf` configuration files in the AsciiDoc\ndistribution for examples of conditional inclusion macro usage.\n\nExecutable system macros\n^^^^^^^^^^^^^^^^^^^^^^^^\nThe 'eval', 'sys' and 'sys2' block macros exhibit the same behavior as\ntheir same named <>. The difference\nis that system macros occur in a block macro context whereas system\nattributes are confined to inline contexts where attribute\nsubstitution is enabled.\n\nThe following example displays a long directory listing inside a\nliteral block:\n\n ------------------\n sys::[ls -l *.txt]\n ------------------\n\nNOTE: There are no block macro versions of the 'eval3' and 'sys3'\nsystem attributes.\n\nTemplate System Macro\n^^^^^^^^^^^^^^^^^^^^^\nThe `template` block macro allows the inclusion of one configuration\nfile template section within another. The following example includes\nthe `[admonitionblock]` section in the `[admonitionparagraph]`\nsection:\n\n [admonitionparagraph]\n template::[admonitionblock]\n\n.Template macro behavior\n- The `template::[]` macro is useful for factoring configuration file\n markup.\n- `template::[]` macros cannot be nested.\n- `template::[]` macro expansion is applied after all configuration\n files have been read.\n\n\n[[X77]]\nPassthrough macros\n~~~~~~~~~~~~~~~~~~\nPassthrough macros are analogous to <> and are\nused to pass text directly to the output. The substitution performed\non the text is determined by the macro definition but can be overridden\nby the ``. The usual syntax is\n`:[]` (for inline macros) and\n`::[]` (for block macros). Passthroughs, by\ndefinition, take precedence over all other text substitutions.\n\npass::\n Inline and block. Passes text unmodified (apart from explicitly\n specified substitutions). Examples:\n\n pass:[To be or not to be
]\n pass:attributes,quotes[the '{author}']\n\nasciimath, latexmath::\n Inline and block. Passes text unmodified. Used for\n <>.\n\n\\+++::\n Inline and block. The triple-plus passthrough is functionally\n identical to the 'pass' macro but you don't have to escape `]`\n characters and you can prefix with quoted attributes in the inline\n version. Example:\n\n Red [red]+++`sum_(i=1)\\^n i=(n(n+1))/2`$+++ AsciiMathML formula\n\n$$::\n Inline and block. The double-dollar passthrough is functionally\n identical to the triple-plus passthrough with one exception: special\n characters are escaped. Example:\n\n $$`[[a,b],[c,d]]((n),(k))`$$\n\n[[X80]]`::\n Text quoted with single backtick characters constitutes an 'inline\n literal' passthrough. The enclosed text is rendered in a monospaced\n font and is only subject to special character substitution. This\n makes sense since monospace text is usually intended to be rendered\n literally and often contains characters that would otherwise have to\n be escaped. If you need monospaced text containing inline\n substitutions use a <>.\n\nMacro Definitions\n~~~~~~~~~~~~~~~~~\nEach entry in the configuration `[macros]` section is a macro\ndefinition which can take one of the following forms:\n\n`=[=#[=+[`:: Delete the existing macro with this ``.\n\n`` is a Python regular expression and `