Blurs the current textInput.
diff --git a/api/resources/csses/ace_api.css b/api/resources/csses/ace_api.css
index f849dcf7..7080c7a5 100644
--- a/api/resources/csses/ace_api.css
+++ b/api/resources/csses/ace_api.css
@@ -147,6 +147,19 @@ form.navbar-search {
form.navbar-search .search-query {
background-color: #FFFFFF;
+ border-color: #999;
+ -webkit-transition: border 0.3s;
+ -moz-transition: border 0.3s;
+ font-size: 14px;
+ line-height: 16px;
+}
+
+form.navbar-search .search-query:focus, form.navbar-search .search-query:active {
+ border: 1px solid #666;
+}
+
+.navbar-search .search-query:focus, .navbar-search .search-query.focused {
+ padding: 4px 9px;
}
h3.api_title {
@@ -154,24 +167,28 @@ h3.api_title {
}
ul.menu {
- margin-left: 16px;
+ margin-left: 2px;
}
.menu li {
list-style-image: url(../images/menu_disc.png);
- margin-bottom: 3px;
- font-weight : 700;
+ margin-bottom: 4px;
+ font-weight: 700;
+ padding-left: 10px;
+ margin-left: 0;
}
.menu li .menu-item a.menuLink, .menu li .menu-item span.menuLink {
- color: #262626;
+ color: #3E7096;
+ font-weight: 100;
}
.menuTwo {
margin-bottom: 5px;
margin-top: 2px;
}
.menuTwo li .menu-item a.menuLink {
- color: #262626;
+ color: #3E7096;
+ font-weight: 100;
}
/* need specificity to "beat" the above colors */
@@ -281,9 +298,14 @@ ul.menu {
.srolled .membersContent {
/*top : 0;*/
width: 625px;
- padding-left: 330px;
+ padding-left: 327px;
margin : 0 auto 0 auto;
}
+
+.srolled ul.nav {
+ padding-right: 10px;
+}
+
.membersBackground {
/* background-color: white;
position: fixed;
@@ -480,7 +502,6 @@ ul.tabs .double ul, ul.tabs .triple ul, ul.tabs .quad ul{
height: 100%;
}
.content .row {
- width: 1060px;
margin-left: auto;
margin-right: auto;
}
@@ -492,8 +513,8 @@ header.filler {
}
.centerpiece {
- background: url(../images/sidebar_border.png) repeat-y 230px 0;
min-height: 100%;
+ padding: 20px 0;
}
/*
@@ -510,7 +531,7 @@ header.filler {
}
#sidebar {
- margin-top: 9px;
+ margin-top: 5px;
/*background: url(../images/sidebar-border.png) repeat-y right 0;*/
margin-left: 12px;
/* width: 280px;*/
@@ -535,6 +556,9 @@ header.filler {
#documentation article.article {
border-top: 1px solid #e9e9e9;
padding: 16px 10px 2px;
+ -webkit-transition: padding 0.2s;
+ -moz-transition: padding 0.2s;
+ -o-transition: padding 0.2s;
}
#documentation h3.sectionHeader + article.article {
@@ -781,7 +805,7 @@ li.signature {
#documentation i.methodToggle {
cursor: pointer;
color: #9f9f9f;
- padding-top: 5px;
+ padding-top: 2px;
float: left;
}
#documentation i.methodToggle.methodToggleHover {
@@ -802,6 +826,7 @@ li.signature {
/* Opera */
-o-transform: rotate(45deg);
+ padding-top: 9px;
}
#documentation h3.sectionHeader {
diff --git a/api/resources/javascripts/bootstrap-dropdown.js b/api/resources/javascripts/bootstrap-dropdown.js
deleted file mode 100644
index 54b61c5e..00000000
--- a/api/resources/javascripts/bootstrap-dropdown.js
+++ /dev/null
@@ -1,92 +0,0 @@
-/* ============================================================
- * bootstrap-dropdown.js v2.0.2
- * http://twitter.github.com/bootstrap/javascript.html#dropdowns
- * ============================================================
- * Copyright 2012 Twitter, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- * ============================================================ */
-
-
-!function( $ ){
-
- "use strict"
-
- /* DROPDOWN CLASS DEFINITION
- * ========================= */
-
- var toggle = '[data-toggle="dropdown"]'
- , Dropdown = function ( element ) {
- var $el = $(element).on('click.dropdown.data-api', this.toggle)
- $('html').on('click.dropdown.data-api', function () {
- $el.parent().removeClass('open')
- })
- }
-
- Dropdown.prototype = {
-
- constructor: Dropdown
-
- , toggle: function ( e ) {
- var $this = $(this)
- , selector = $this.attr('data-target')
- , $parent
- , isActive
-
- if (!selector) {
- selector = $this.attr('href')
- selector = selector && selector.replace(/.*(?=#[^\s]*$)/, '') //strip for ie7
- }
-
- $parent = $(selector)
- $parent.length || ($parent = $this.parent())
-
- isActive = $parent.hasClass('open')
-
- clearMenus()
- !isActive && $parent.toggleClass('open')
-
- return false
- }
-
- }
-
- function clearMenus() {
- $(toggle).parent().removeClass('open')
- }
-
-
- /* DROPDOWN PLUGIN DEFINITION
- * ========================== */
-
- $.fn.dropdown = function ( option ) {
- return this.each(function () {
- var $this = $(this)
- , data = $this.data('dropdown')
- if (!data) $this.data('dropdown', (data = new Dropdown(this)))
- if (typeof option == 'string') data[option].call($this)
- })
- }
-
- $.fn.dropdown.Constructor = Dropdown
-
-
- /* APPLY TO STANDARD DROPDOWN ELEMENTS
- * =================================== */
-
- $(function () {
- $('html').on('click.dropdown.data-api', clearMenus)
- $('body').on('click.dropdown.data-api', toggle, Dropdown.prototype.toggle)
- })
-
-}( window.jQuery );
\ No newline at end of file
diff --git a/api/resources/javascripts/bootstrap-tab.js b/api/resources/javascripts/bootstrap-tab.js
deleted file mode 100644
index 070deb8f..00000000
--- a/api/resources/javascripts/bootstrap-tab.js
+++ /dev/null
@@ -1,135 +0,0 @@
-/* ========================================================
- * bootstrap-tab.js v2.1.1
- * http://twitter.github.com/bootstrap/javascript.html#tabs
- * ========================================================
- * Copyright 2012 Twitter, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- * ======================================================== */
-
-
-!function ($) {
-
- "use strict"; // jshint ;_;
-
-
- /* TAB CLASS DEFINITION
- * ==================== */
-
- var Tab = function (element) {
- this.element = $(element)
- }
-
- Tab.prototype = {
-
- constructor: Tab
-
- , show: function () {
- var $this = this.element
- , $ul = $this.closest('ul:not(.dropdown-menu)')
- , selector = $this.attr('data-target')
- , previous
- , $target
- , e
-
- if (!selector) {
- selector = $this.attr('href')
- selector = selector && selector.replace(/.*(?=#[^\s]*$)/, '') //strip for ie7
- }
-
- if ( $this.parent('li').hasClass('active') ) return
-
- previous = $ul.find('.active a').last()[0]
-
- e = $.Event('show', {
- relatedTarget: previous
- })
-
- $this.trigger(e)
-
- if (e.isDefaultPrevented()) return
-
- $target = $(selector)
-
- this.activate($this.parent('li'), $ul)
- this.activate($target, $target.parent(), function () {
- $this.trigger({
- type: 'shown'
- , relatedTarget: previous
- })
- })
- }
-
- , activate: function ( element, container, callback) {
- var $active = container.find('> .active')
- , transition = callback
- && $.support.transition
- && $active.hasClass('fade')
-
- function next() {
- $active
- .removeClass('active')
- .find('> .dropdown-menu > .active')
- .removeClass('active')
-
- element.addClass('active')
-
- if (transition) {
- element[0].offsetWidth // reflow for transition
- element.addClass('in')
- } else {
- element.removeClass('fade')
- }
-
- if ( element.parent('.dropdown-menu') ) {
- element.closest('li.dropdown').addClass('active')
- }
-
- callback && callback()
- }
-
- transition ?
- $active.one($.support.transition.end, next) :
- next()
-
- $active.removeClass('in')
- }
- }
-
-
- /* TAB PLUGIN DEFINITION
- * ===================== */
-
- $.fn.tab = function ( option ) {
- return this.each(function () {
- var $this = $(this)
- , data = $this.data('tab')
- if (!data) $this.data('tab', (data = new Tab(this)))
- if (typeof option == 'string') data[option]()
- })
- }
-
- $.fn.tab.Constructor = Tab
-
-
- /* TAB DATA-API
- * ============ */
-
- $(function () {
- $('body').on('click.tab.data-api', '[data-toggle="tab"], [data-toggle="pill"]', function (e) {
- e.preventDefault()
- $(this).tab('show')
- })
- })
-
-}(window.jQuery);
\ No newline at end of file
diff --git a/api/resources/javascripts/bootstrap.js b/api/resources/javascripts/bootstrap.js
new file mode 100644
index 00000000..79241e74
--- /dev/null
+++ b/api/resources/javascripts/bootstrap.js
@@ -0,0 +1,389 @@
+/* ============================================================
+ * bootstrap-dropdown.js v2.1.1
+ * http://twitter.github.com/bootstrap/javascript.html#dropdowns
+ * ============================================================
+ * Copyright 2012 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============================================================ */
+
+
+!function ($) {
+
+ "use strict"; // jshint ;_;
+
+
+ /* DROPDOWN CLASS DEFINITION
+ * ========================= */
+
+ var toggle = '[data-toggle=dropdown]'
+ , Dropdown = function (element) {
+ var $el = $(element).on('click.dropdown.data-api', this.toggle)
+ $('html').on('click.dropdown.data-api', function () {
+ $el.parent().removeClass('open')
+ })
+ }
+
+ Dropdown.prototype = {
+
+ constructor: Dropdown
+
+ , toggle: function (e) {
+ var $this = $(this)
+ , $parent
+ , isActive
+
+ if ($this.is('.disabled, :disabled')) return
+
+ $parent = getParent($this)
+
+ isActive = $parent.hasClass('open')
+
+ clearMenus()
+
+ if (!isActive) {
+ $parent.toggleClass('open')
+ $this.focus()
+ }
+
+ return false
+ }
+
+ , keydown: function (e) {
+ var $this
+ , $items
+ , $active
+ , $parent
+ , isActive
+ , index
+
+ if (!/(38|40|27)/.test(e.keyCode)) return
+
+ $this = $(this)
+
+ e.preventDefault()
+ e.stopPropagation()
+
+ if ($this.is('.disabled, :disabled')) return
+
+ $parent = getParent($this)
+
+ isActive = $parent.hasClass('open')
+
+ if (!isActive || (isActive && e.keyCode == 27)) return $this.click()
+
+ $items = $('[role=menu] li:not(.divider) a', $parent)
+
+ if (!$items.length) return
+
+ index = $items.index($items.filter(':focus'))
+
+ if (e.keyCode == 38 && index > 0) index-- // up
+ if (e.keyCode == 40 && index < $items.length - 1) index++ // down
+ if (!~index) index = 0
+
+ $items
+ .eq(index)
+ .focus()
+ }
+
+ }
+
+ function clearMenus() {
+ getParent($(toggle))
+ .removeClass('open')
+ }
+
+ function getParent($this) {
+ var selector = $this.attr('data-target')
+ , $parent
+
+ if (!selector) {
+ selector = $this.attr('href')
+ selector = selector && /#/.test(selector) && selector.replace(/.*(?=#[^\s]*$)/, '') //strip for ie7
+ }
+
+ $parent = $(selector)
+ $parent.length || ($parent = $this.parent())
+
+ return $parent
+ }
+
+
+ /* DROPDOWN PLUGIN DEFINITION
+ * ========================== */
+
+ $.fn.dropdown = function (option) {
+ return this.each(function () {
+ var $this = $(this)
+ , data = $this.data('dropdown')
+ if (!data) $this.data('dropdown', (data = new Dropdown(this)))
+ if (typeof option == 'string') data[option].call($this)
+ })
+ }
+
+ $.fn.dropdown.Constructor = Dropdown
+
+
+ /* APPLY TO STANDARD DROPDOWN ELEMENTS
+ * =================================== */
+
+ $(function () {
+ $('html')
+ .on('click.dropdown.data-api touchstart.dropdown.data-api', clearMenus)
+ $('body')
+ .on('click.dropdown touchstart.dropdown.data-api', '.dropdown form', function (e) { e.stopPropagation() })
+ .on('click.dropdown.data-api touchstart.dropdown.data-api' , toggle, Dropdown.prototype.toggle)
+ .on('keydown.dropdown.data-api touchstart.dropdown.data-api', toggle + ', [role=menu]' , Dropdown.prototype.keydown)
+ })
+
+}(window.jQuery);
+/* ========================================================
+ * bootstrap-tab.js v2.1.1
+ * http://twitter.github.com/bootstrap/javascript.html#tabs
+ * ========================================================
+ * Copyright 2012 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ======================================================== */
+
+
+!function ($) {
+
+ "use strict"; // jshint ;_;
+
+
+ /* TAB CLASS DEFINITION
+ * ==================== */
+
+ var Tab = function (element) {
+ this.element = $(element)
+ }
+
+ Tab.prototype = {
+
+ constructor: Tab
+
+ , show: function () {
+ var $this = this.element
+ , $ul = $this.closest('ul:not(.dropdown-menu)')
+ , selector = $this.attr('data-target')
+ , previous
+ , $target
+ , e
+
+ if (!selector) {
+ selector = $this.attr('href')
+ selector = selector && selector.replace(/.*(?=#[^\s]*$)/, '') //strip for ie7
+ }
+
+ if ( $this.parent('li').hasClass('active') ) return
+
+ previous = $ul.find('.active a').last()[0]
+
+ e = $.Event('show', {
+ relatedTarget: previous
+ })
+
+ $this.trigger(e)
+
+ if (e.isDefaultPrevented()) return
+
+ $target = $(selector)
+
+ this.activate($this.parent('li'), $ul)
+ this.activate($target, $target.parent(), function () {
+ $this.trigger({
+ type: 'shown'
+ , relatedTarget: previous
+ })
+ })
+ }
+
+ , activate: function ( element, container, callback) {
+ var $active = container.find('> .active')
+ , transition = callback
+ && $.support.transition
+ && $active.hasClass('fade')
+
+ function next() {
+ $active
+ .removeClass('active')
+ .find('> .dropdown-menu > .active')
+ .removeClass('active')
+
+ element.addClass('active')
+
+ if (transition) {
+ element[0].offsetWidth // reflow for transition
+ element.addClass('in')
+ } else {
+ element.removeClass('fade')
+ }
+
+ if ( element.parent('.dropdown-menu') ) {
+ element.closest('li.dropdown').addClass('active')
+ }
+
+ callback && callback()
+ }
+
+ transition ?
+ $active.one($.support.transition.end, next) :
+ next()
+
+ $active.removeClass('in')
+ }
+ }
+
+
+ /* TAB PLUGIN DEFINITION
+ * ===================== */
+
+ $.fn.tab = function ( option ) {
+ return this.each(function () {
+ var $this = $(this)
+ , data = $this.data('tab')
+ if (!data) $this.data('tab', (data = new Tab(this)))
+ if (typeof option == 'string') data[option]()
+ })
+ }
+
+ $.fn.tab.Constructor = Tab
+
+
+ /* TAB DATA-API
+ * ============ */
+
+ $(function () {
+ $('body').on('click.tab.data-api', '[data-toggle="tab"], [data-toggle="pill"]', function (e) {
+ e.preventDefault()
+ $(this).tab('show')
+ })
+ })
+
+}(window.jQuery);
+/* ==========================================================
+ * bootstrap-affix.js v2.1.1
+ * http://twitter.github.com/bootstrap/javascript.html#affix
+ * ==========================================================
+ * Copyright 2012 Twitter, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ========================================================== */
+
+
+!function ($) {
+
+ "use strict"; // jshint ;_;
+
+
+ /* AFFIX CLASS DEFINITION
+ * ====================== */
+
+ var Affix = function (element, options) {
+ this.options = $.extend({}, $.fn.affix.defaults, options)
+ this.$window = $(window).on('scroll.affix.data-api', $.proxy(this.checkPosition, this))
+ this.$element = $(element)
+ this.checkPosition()
+ }
+
+ Affix.prototype.checkPosition = function () {
+ if (!this.$element.is(':visible')) return
+
+ var scrollHeight = $(document).height()
+ , scrollTop = this.$window.scrollTop()
+ , position = this.$element.offset()
+ , offset = this.options.offset
+ , offsetBottom = offset.bottom
+ , offsetTop = offset.top
+ , reset = 'affix affix-top affix-bottom'
+ , affix
+
+ if (typeof offset != 'object') offsetBottom = offsetTop = offset
+ if (typeof offsetTop == 'function') offsetTop = offset.top()
+ if (typeof offsetBottom == 'function') offsetBottom = offset.bottom()
+
+ affix = this.unpin != null && (scrollTop + this.unpin <= position.top) ?
+ false : offsetBottom != null && (position.top + this.$element.height() >= scrollHeight - offsetBottom) ?
+ 'bottom' : offsetTop != null && scrollTop <= offsetTop ?
+ 'top' : false
+
+ if (this.affixed === affix) return
+
+ this.affixed = affix
+ this.unpin = affix == 'bottom' ? position.top - scrollTop : null
+
+ this.$element.removeClass(reset).addClass('affix' + (affix ? '-' + affix : ''))
+ }
+
+
+ /* AFFIX PLUGIN DEFINITION
+ * ======================= */
+
+ $.fn.affix = function (option) {
+ return this.each(function () {
+ var $this = $(this)
+ , data = $this.data('affix')
+ , options = typeof option == 'object' && option
+ if (!data) $this.data('affix', (data = new Affix(this, options)))
+ if (typeof option == 'string') data[option]()
+ })
+ }
+
+ $.fn.affix.Constructor = Affix
+
+ $.fn.affix.defaults = {
+ offset: 0
+ }
+
+
+ /* AFFIX DATA-API
+ * ============== */
+
+ $(window).on('load', function () {
+ $('[data-spy="affix"]').each(function () {
+ var $spy = $(this)
+ , data = $spy.data()
+
+ data.offset = data.offset || {}
+
+ data.offsetBottom && (data.offset.bottom = data.offsetBottom)
+ data.offsetTop && (data.offset.top = data.offsetTop)
+
+ $spy.affix(data)
+ })
+ })
+
+
+}(window.jQuery);
\ No newline at end of file
diff --git a/api/resources/javascripts/clicker.js b/api/resources/javascripts/clicker.js
index b5a86168..90e7e12c 100644
--- a/api/resources/javascripts/clicker.js
+++ b/api/resources/javascripts/clicker.js
@@ -28,7 +28,10 @@ function setupClicker() {
if (!$article.hasClass('methodToggleOpen') || this.force) {
$article.addClass('methodToggleOpen');
$arrow.removeClass('inactive').addClass('active');
-
+
+ if (!$arrow[0])
+ return;
+
var data = $arrow[0].id.replace(/^js_/, "");
//var state = {};
//state.section = data;
diff --git a/api/resources/javascripts/disqus-ext.js b/api/resources/javascripts/disqus-ext.js
index 66da8bfc..6bb7ff4e 100644
--- a/api/resources/javascripts/disqus-ext.js
+++ b/api/resources/javascripts/disqus-ext.js
@@ -1,22 +1,17 @@
-function setupDisqus() {
+function setupDisqus(href) {
var disqus_shortname = 'aceapi';
- var dsqId = "disqusScript";
//var paths = window.location.pathname.split("/");
//var fileName = paths[paths.length - 2] + "/" + paths[paths.length - 1];
//var disqus_identifier = fileName;
-
- var lochash = location.hash.substr(1);
- var disqus_identifier = "api/" + (lochash.substr(lochash.indexOf('api=')).split('&')[0].split('=')[1] || "index") + ".html";
+ var disqus_identifier = href.substring(2);
(function() {
- if (document.getElementById(dsqId))
- (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).removeChild(document.getElementById(dsqId));
-
- var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
- dsq.src = 'https://' + disqus_shortname + '.disqus.com/embed.js';
- dsq.id="disqusScript";
- (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+ if (document.getElementById("disqusScript") === null) {
+ var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
+ dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+ (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+ }
})();
}
\ No newline at end of file
diff --git a/build b/build
index c2f3abb2..6149ca6b 160000
--- a/build
+++ b/build
@@ -1 +1 @@
-Subproject commit c2f3abb2ecd3287f90225d804132f0fd26cfb639
+Subproject commit 6149ca6b148e878d4c1341d4675ca3597d78dbdd
diff --git a/demo/kitchen-sink/demo.js b/demo/kitchen-sink/demo.js
index f3a163e5..9db36c18 100644
--- a/demo/kitchen-sink/demo.js
+++ b/demo/kitchen-sink/demo.js
@@ -55,201 +55,18 @@ var Editor = require("ace/editor").Editor;
var MultiSelect = require("ace/multi_select").MultiSelect;
// workers do not work for file:
-if (location.protocol == "file:")
- EditSession.prototype.$useWorker = false;
+/* if (location.protocol == "file:")
+ EditSession.prototype.$useWorker = false; */
-/************** modes ***********************/
-var modes = [];
-function getModeFromPath(path) {
- var mode = modesByName.text;
- for (var i = 0; i < modes.length; i++) {
- if (modes[i].supportsFile(path)) {
- mode = modes[i];
- break;
- }
- }
- return mode;
-};
-
-var Mode = function(name, desc, extensions) {
- this.name = name;
- this.desc = desc;
- this.mode = "ace/mode/" + name;
- this.extRe = new RegExp("^.*\\.(" + extensions + ")$", "g");
-};
-
-Mode.prototype.supportsFile = function(filename) {
- return filename.match(this.extRe);
-};
-
-var modesByName = {
- c9search: ["C9Search" , "c9search_results"],
- coffee: ["CoffeeScript" , "coffee|^Cakefile"],
- coldfusion: ["ColdFusion" , "cfm"],
- csharp: ["C#" , "cs"],
- css: ["CSS" , "css"],
- diff: ["Diff" , "diff|patch"],
- glsl: ["Glsl" , "glsl|frag|vert"],
- golang: ["Go" , "go"],
- groovy: ["Groovy" , "groovy"],
- haxe: ["haXe" , "hx"],
- html: ["HTML" , "htm|html|xhtml"],
- c_cpp: ["C/C++" , "c|cc|cpp|cxx|h|hh|hpp"],
- clojure: ["Clojure" , "clj"],
- jade: ["Jade" , "jade"],
- java: ["Java" , "java"],
- javascript: ["JavaScript" , "js"],
- json: ["JSON" , "json"],
- jsx: ["JSX" , "jsx"],
- latex: ["LaTeX" , "latex|tex|ltx|bib"],
- less: ["LESS" , "less"],
- liquid: ["Liquid" , "liquid"],
- lua: ["Lua" , "lua"],
- luapage: ["LuaPage" , "lp"], // http://keplerproject.github.com/cgilua/manual.html#templates
- markdown: ["Markdown" , "md|markdown"],
- ocaml: ["OCaml" , "ml|mli"],
- perl: ["Perl" , "pl|pm"],
- pgsql: ["pgSQL" , "pgsql"],
- php: ["PHP" , "php|phtml"],
- powershell: ["Powershell" , "ps1"],
- python: ["Python" , "py"],
- ruby: ["Ruby" , "ru|gemspec|rake|rb"],
- scad: ["OpenSCAD" , "scad"],
- scala: ["Scala" , "scala"],
- scss: ["SCSS" , "scss|sass"],
- sh: ["SH" , "sh|bash|bat"],
- sql: ["SQL" , "sql"],
- svg: ["SVG" , "svg"],
- tcl: ["Tcl" , "tcl"],
- text: ["Text" , "txt"],
- textile: ["Textile" , "textile"],
- xml: ["XML" , "xml|rdf|rss|wsdl|xslt|atom|mathml|mml|xul|xbl"],
- xquery: ["XQuery" , "xq"],
- yaml: ["YAML" , "yaml"]
-};
-
-for (var name in modesByName) {
- var mode = modesByName[name];
- mode = new Mode(name, mode[0], mode[1])
- modesByName[name] = mode;
- modes.push(mode);
-}
-
-
-/*********** demo documents ***************************/
-var fileCache = {};
-
-function initDoc(file, path, doc) {
- if (doc.prepare)
- file = doc.prepare(file);
-
- var session = new EditSession(file);
- session.setUndoManager(new UndoManager());
- doc.session = session;
- doc.path = path;
- if (doc.wrapped) {
- session.setUseWrapMode(true);
- session.setWrapLimitRange(80, 80);
- }
- var mode = getModeFromPath(path)
- session.modeName = mode.name;
- session.setMode(mode.mode);
-}
-
-
-function makeHuge(txt) {
- for (var i = 0; i < 5; i++)
- txt += txt;
- return txt
-}
-
-var docs = {
- "docs/javascript.js": "JavaScript",
- "docs/clojure.clj": "Clojure",
- "docs/coffeescript.coffee": "Coffeescript",
- "docs/coldfusion.cfm": "ColdFusion",
- "docs/cpp.cpp": "C/C++",
- "docs/csharp.cs": "C#",
- "docs/css.css": "CSS",
- "docs/diff.diff": "Diff",
- "docs/glsl.glsl": "Glsl",
- "docs/golang.go": "Go",
- "docs/groovy.groovy": "Groovy",
- "docs/Haxe.hx": "haXe",
- "docs/html.html": "HTML",
- "docs/jade.jade": "Jade",
- "docs/java.java": "Java",
- "docs/json.json": "JSON",
- "docs/jsx.jsx": "JSX",
- "docs/latex.tex": {name: "LaTeX", wrapped: true},
- "docs/less.less": "LESS",
- "docs/liquid.liquid": "Liquid",
- "docs/lua.lua": "Lua",
- "docs/luapage.lp": "LuaPage",
- "docs/markdown.md": {name: "Markdown", wrapped: true},
- "docs/ocaml.ml": "OCaml",
- "docs/OpenSCAD.scad": "OpenSCAD",
- "docs/perl.pl": "Perl",
- "docs/pgsql.pgsql": {name: "pgSQL", wrapped: true},
- "docs/php.php": "PHP",
- "docs/plaintext.txt": {name: "Plain Text", prepare: makeHuge, wrapped: true},
- "docs/powershell.ps1": "Powershell",
- "docs/python.py": "Python",
- "docs/ruby.rb": "Ruby",
- "docs/scala.scala": "Scala",
- "docs/scss.scss": "SCSS",
- "docs/sh.sh": "SH",
- "docs/sql.sql": {name: "SQL", wrapped: true},
- "docs/svg.svg": "SVG",
- "docs/tcl.tcl": "Tcl",
- "docs/textile.textile": {name: "Textile", wrapped: true},
- "docs/xml.xml": "XML",
- "docs/xquery.xq": "XQuery",
- "docs/yaml.yaml": "YAML",
- "docs/c9search.c9search_results": "C9 Search Results"
-}
-
-var ownSource = {
- /* filled from require*/
-};
-
-var hugeDocs = {
- "build/src/ace.js": "",
- "build/src-min/ace.js": ""
-};
-
-if (window.require && window.require.s) try {
- for (var path in window.require.s.contexts._.loaded) {
- if (path.indexOf("!") != -1)
- path = path.split("!").pop();
- else
- path = path + ".js";
- ownSource[path] = ""
- }
-} catch(e) {}
-
-function prepareDocList(docs) {
- var list = []
- for (var path in docs) {
- var doc = docs[path];
- if (typeof doc != "object")
- doc = {name: doc || path};
-
- doc.path = path;
- doc.desc = doc.name.replace(/^(ace|docs|demo|build)\//, "");
- if (doc.desc.length > 18)
- doc.desc = doc.desc.slice(0, 7) + ".." + doc.desc.slice(-9)
-
- fileCache[doc.name] = doc;
- list.push(doc);
- };
-
- return list;
-}
-
-docs = prepareDocList(docs);
-ownSource = prepareDocList(ownSource);
-hugeDocs = prepareDocList(hugeDocs);
+var doclist = require("./doclist");
+var modelist = require("./modelist");
+var layout = require("./layout");
+var TokenTooltip = require("./token_tooltip").TokenTooltip;
+var util = require("./util");
+var saveOption = util.saveOption;
+var fillDropdown = util.fillDropdown;
+var bindCheckbox = util.bindCheckbox;
+var bindDropdown = util.bindDropdown;
/*********** create editor ***************************/
var container = document.getElementById("editor");
@@ -267,27 +84,30 @@ window.env = env;
window.ace = env.editor;
env.editor.setAnimatedScroll(true);
+// add multiple cursor support to editor
+require("ace/multi_select").MultiSelect(env.editor);
+
var consoleEl = dom.createElement("div");
container.parentNode.appendChild(consoleEl);
-consoleEl.style.position="fixed"
-consoleEl.style.bottom = "1px"
-consoleEl.style.right = 0
-consoleEl.style.background = "white"
-consoleEl.style.border = "1px solid #baf"
-consoleEl.style.zIndex = "100"
-var cmdLine = new singleLineEditor(consoleEl);
+consoleEl.style.cssText = "position:fixed; bottom:1px; right:0;\
+border:1px solid #baf; zIndex:100";
+
+var cmdLine = new layout.singleLineEditor(consoleEl);
cmdLine.editor = env.editor;
env.editor.cmdLine = cmdLine;
+/**
+ * This demonstrates how you can define commands and bind shortcuts to them.
+ */
env.editor.commands.addCommands([{
name: "gotoline",
bindKey: {win: "Ctrl-L", mac: "Command-L"},
exec: function(editor, line) {
if (typeof line == "object") {
var arg = this.name + " " + editor.getCursorPosition().row;
- editor.cmdLine.setValue(arg, 1)
- editor.cmdLine.focus()
- return
+ editor.cmdLine.setValue(arg, 1);
+ editor.cmdLine.focus();
+ return;
}
line = parseInt(line, 10);
if (!isNaN(line))
@@ -299,10 +119,10 @@ env.editor.commands.addCommands([{
bindKey: {win: "Ctrl-F", mac: "Command-F"},
exec: function(editor, needle) {
if (typeof needle == "object") {
- var arg = this.name + " " + editor.getCopyText()
- editor.cmdLine.setValue(arg, 1)
- editor.cmdLine.focus()
- return
+ var arg = this.name + " " + editor.getCopyText();
+ editor.cmdLine.setValue(arg, 1);
+ editor.cmdLine.focus();
+ return;
}
editor.find(needle);
},
@@ -312,24 +132,32 @@ env.editor.commands.addCommands([{
bindKey: "shift-esc",
exec: function(editor, needle) { editor.cmdLine.focus(); },
readOnly: true
-}])
+}, {
+ name: "execute",
+ bindKey: "ctrl+enter",
+ exec: function(editor) {
+ try {
+ var r = eval(editor.getCopyText()||editor.getValue());
+ } catch(e) {
+ r = e;
+ }
+ editor.cmdLine.setValue(r + "")
+ },
+ readOnly: true
+}]);
cmdLine.commands.bindKeys({
- "Shift-Return|Ctrl-Return|Alt-Return": function(cmdLine) { cmdLine.insert("\n")},
+ "Shift-Return|Ctrl-Return|Alt-Return": function(cmdLine) { cmdLine.insert("\n"); },
"Esc|Shift-Esc": function(cmdLine){ cmdLine.editor.focus(); },
"Return": function(cmdLine){
var command = cmdLine.getValue().split(/\s+/);
var editor = cmdLine.editor;
editor.commands.exec(command[0], editor, command[1]);
editor.focus();
- },
-})
+ }
+});
-cmdLine.commands.removeCommands(["find", "gotoline", "findall", "replace", "replaceall"])
-
-/**
- * This demonstrates how you can define commands and bind shortcuts to them.
- */
+cmdLine.commands.removeCommands(["find", "gotoline", "findall", "replace", "replaceall"]);
var commands = env.editor.commands;
commands.addCommand({
@@ -350,28 +178,28 @@ var keybindings = {
"outdent": "[",
"gotolinestart": "^",
"gotolineend": "$"
- })
+ })
};
/*********** manage layout ***************************/
-var consoleHight = 20;
+var consoleHeight = 20;
function onResize() {
var left = env.split.$container.offsetLeft;
var width = document.documentElement.clientWidth - left;
container.style.width = width + "px";
- container.style.height = document.documentElement.clientHeight - consoleHight + "px";
+ container.style.height = document.documentElement.clientHeight - consoleHeight + "px";
env.split.resize();
consoleEl.style.width = width + "px";
- cmdLine.resize()
+ cmdLine.resize();
}
window.onresize = onResize;
onResize();
-/*********** options pane ***************************/
+/*********** options panel ***************************/
var docEl = document.getElementById("doc");
var modeEl = document.getElementById("mode");
var wrapModeEl = document.getElementById("soft_wrap");
@@ -388,54 +216,23 @@ var animateScrollEl = document.getElementById("animate_scroll");
var softTabEl = document.getElementById("soft_tab");
var behavioursEl = document.getElementById("enable_behaviours");
-var group = document.createElement("optgroup");
-group.setAttribute("label", "Mode Examples");
-fillDropdown(docs, group);
-docEl.appendChild(group);
-var group = document.createElement("optgroup");
-group.setAttribute("label", "Huge documents");
-fillDropdown(hugeDocs, group);
-docEl.appendChild(group);
-var group = document.createElement("optgroup");
-group.setAttribute("label", "own source");
-fillDropdown(ownSource, group);
-docEl.appendChild(group);
-
-
-fillDropdown(modes, modeEl);
+fillDropdown(docEl, doclist.all);
+fillDropdown(modeEl, modelist.modes);
+var modesByName = modelist.modesByName;
bindDropdown("mode", function(value) {
- env.editor.getSession().setMode(modesByName[value].mode || modesByName.text.mode);
- env.editor.getSession().modeName = value;
+ env.editor.session.setMode(modesByName[value].mode || modesByName.text.mode);
+ env.editor.session.modeName = value;
});
bindDropdown("doc", function(name) {
- var doc = fileCache[name];
- if (!doc)
- return;
-
- if (doc.session)
- return setSession(doc.session)
-
- //@todo do something while waiting
- // env.editor.setSession(emptySession || (emptySession = new EditSession("")))
- var path = doc.path;
- var parts = path.split("/");
- if (parts[0] == "docs")
- path = "demo/kitchen-sink/" + path;
- else if (parts[0] == "ace")
- path = "lib/" + path;
-
- net.get(path, function(x) {
- initDoc(x, path, doc);
- setSession(doc.session)
- })
-
- function setSession(session) {
- var session = env.split.setSession(session);
+ doclist.loadDoc(name, function(session) {
+ if (!session)
+ return;
+ session = env.split.setSession(session);
updateUIEditorOptions();
env.editor.focus();
- }
+ });
});
function updateUIEditorOptions() {
@@ -461,40 +258,22 @@ function updateUIEditorOptions() {
saveOption(behavioursEl, editor.getBehavioursEnabled());
}
-function saveOption(el, val) {
- if (!el.onchange && !el.onclick)
- return;
-
- if ("checked" in el) {
- if (val !== undefined)
- el.checked = val;
-
- localStorage && localStorage.setItem(el.id, el.checked ? 1 : 0);
- }
- else {
- if (val !== undefined)
- el.value = val;
-
- localStorage && localStorage.setItem(el.id, el.value);
- }
-}
-
event.addListener(themeEl, "mouseover", function(e){
this.desiredValue = e.target.value;
if (!this.$timer)
this.$timer = setTimeout(this.updateTheme);
-})
+});
event.addListener(themeEl, "mouseout", function(e){
this.desiredValue = null;
if (!this.$timer)
this.$timer = setTimeout(this.updateTheme, 20);
-})
+});
themeEl.updateTheme = function(){
env.split.setTheme(themeEl.desiredValue || themeEl.selectedValue);
themeEl.$timer = null;
-}
+};
bindDropdown("theme", function(value) {
if (!value)
@@ -512,33 +291,28 @@ bindDropdown("fontsize", function(value) {
});
bindDropdown("folding", function(value) {
- env.editor.getSession().setFoldStyle(value);
+ env.editor.session.setFoldStyle(value);
env.editor.setShowFoldWidgets(value !== "manual");
});
bindDropdown("soft_wrap", function(value) {
- var session = env.editor.getSession();
+ var session = env.editor.session;
var renderer = env.editor.renderer;
switch (value) {
case "off":
session.setUseWrapMode(false);
renderer.setPrintMarginColumn(80);
break;
- case "40":
- session.setUseWrapMode(true);
- session.setWrapLimitRange(40, 40);
- renderer.setPrintMarginColumn(40);
- break;
- case "80":
- session.setUseWrapMode(true);
- session.setWrapLimitRange(80, 80);
- renderer.setPrintMarginColumn(80);
- break;
case "free":
session.setUseWrapMode(true);
session.setWrapLimitRange(null, null);
renderer.setPrintMarginColumn(80);
break;
+ default:
+ session.setUseWrapMode(true);
+ var col = parseInt(value, 10);
+ session.setWrapLimitRange(col, col);
+ renderer.setPrintMarginColumn(col);
}
});
@@ -579,7 +353,7 @@ bindCheckbox("animate_scroll", function(checked) {
});
bindCheckbox("soft_tab", function(checked) {
- env.editor.getSession().setUseSoftTabs(checked);
+ env.editor.session.setUseSoftTabs(checked);
});
bindCheckbox("enable_behaviours", function(checked) {
@@ -615,42 +389,15 @@ bindDropdown("split", function(value) {
}
});
-function bindCheckbox(id, callback) {
- var el = document.getElementById(id);
- if (localStorage && localStorage.getItem(id))
- el.checked = localStorage.getItem(id) == "1";
-
- var onCheck = function() {
- callback(!!el.checked);
- saveOption(el);
- };
- el.onclick = onCheck;
- onCheck();
-}
-
-function bindDropdown(id, callback) {
- var el = document.getElementById(id);
- if (localStorage && localStorage.getItem(id))
- el.value = localStorage.getItem(id);
-
- var onChange = function() {
- callback(el.value);
- saveOption(el);
- };
-
- el.onchange = onChange;
- onChange();
-}
-
-function fillDropdown(list, el) {
- list.forEach(function(item) {
- var option = document.createElement("option");
- option.setAttribute("value", item.name);
- option.innerHTML = item.desc;
- el.appendChild(option);
- });
-}
-
+bindCheckbox("highlight_token", function(checked) {
+ var editor = env.editor;
+ if (editor.tokenTooltip && !checked) {
+ editor.tokenTooltip.destroy();
+ delete editor.tokenTooltip;
+ } else if (checked) {
+ editor.tokenTooltip = new TokenTooltip(editor);
+ }
+});
/************** dragover ***************************/
event.addListener(container, "dragover", function(e) {
@@ -679,96 +426,10 @@ event.addListener(container, "drop", function(e) {
}
});
-// add multiple cursor support to editor
-require("ace/multi_select").MultiSelect(env.editor);
-
-function singleLineEditor(el) {
- var renderer = new Renderer(el);
- renderer.scrollBar.element.style.display = "none";
- renderer.scrollBar.width = 0;
- renderer.content.style.height = "auto";
-
- renderer.screenToTextCoordinates = function(x, y) {
- var pos = this.pixelToScreenCoordinates(x, y);
- return this.session.screenToDocumentPosition(
- Math.min(this.session.getScreenLength() - 1, Math.max(pos.row, 0)),
- Math.max(pos.column, 0)
- );
- };
- // todo size change event
- renderer.$computeLayerConfig = function() {
- var longestLine = this.$getLongestLine();
- var firstRow = 0;
- var lastRow = this.session.getLength();
- var height = this.session.getScreenLength() * this.lineHeight;
-
- this.scrollTop = 0;
- var config = this.layerConfig;
- config.width = longestLine;
- config.padding = this.$padding;
- config.firstRow = 0;
- config.firstRowScreen = 0;
- config.lastRow = lastRow;
- config.lineHeight = this.lineHeight;
- config.characterWidth = this.characterWidth;
- config.minHeight = height;
- config.maxHeight = height;
- config.offset = 0;
- config.height = height;
-
- this.$gutterLayer.element.style.marginTop = 0 + "px";
- this.content.style.marginTop = 0 + "px";
- this.content.style.width = longestLine + 2 * this.$padding + "px";
- this.content.style.height = height + "px";
- this.scroller.style.height = height + "px";
- this.container.style.height = height + "px";
- };
- renderer.isScrollableBy=function(){return false};
-
- var editor = new Editor(renderer);
- new MultiSelect(editor);
- editor.session.setUndoManager(new UndoManager());
-
- editor.setHighlightActiveLine(false);
- editor.setShowPrintMargin(false);
- editor.renderer.setShowGutter(false);
- editor.renderer.setHighlightGutterLine(false);
- return editor;
-};
-
-
-/** simple statusbar **/
-var editor = env.editor;
-var statusBarEl = dom.createElement("div");
-statusBarEl.style.cssText = "color:gray;position:absolute;right:0;border-left:1px solid";
-cmdLine.container.appendChild(statusBarEl);
-var statusUpdate = lang.deferredCall(function() {
- var status = [];
- function add(s, sep) {s && status.push(s, sep || "|")}
- if (editor.$vimModeHandler)
- add(editor.$vimModeHandler.getStatusText());
- else if (editor.commands.recording)
- add("REC");
-
- var c = editor.selection.lead;
- add(c.row + ":" + c.column, " ");
- if (!editor.selection.isEmpty()) {
- var r = editor.getSelectionRange()
- add("(" + (r.end.row - r.start.row) + ":" +(r.end.column - r.start.column) + ")");
- }
- status.pop();
- statusBarEl.textContent = status.join("");
-});
-
-env.editor.on("changeStatus", function() {
- statusUpdate.schedule(50);
-});
-env.editor.on("changeSelection", function() {
- statusUpdate.schedule(50);
-});
-
+var StatusBar = require("./statusbar").StatusBar;
+new StatusBar(env.editor, cmdLine.container);
});
diff --git a/demo/kitchen-sink/doclist.js b/demo/kitchen-sink/doclist.js
new file mode 100644
index 00000000..56208dad
--- /dev/null
+++ b/demo/kitchen-sink/doclist.js
@@ -0,0 +1,190 @@
+/* ***** BEGIN LICENSE BLOCK *****
+ * Distributed under the BSD license:
+ *
+ * Copyright (c) 2010, Ajax.org B.V.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ * * Neither the name of Ajax.org B.V. nor the
+ * names of its contributors may be used to endorse or promote products
+ * derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL AJAX.ORG B.V. BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * ***** END LICENSE BLOCK ***** */
+
+ define(function(require, exports, module) {
+"use strict";
+
+var EditSession = require("ace/edit_session").EditSession;
+var UndoManager = require("ace/undomanager").UndoManager;
+var net = require("ace/lib/net");
+
+var modelist = require("./modelist");
+/*********** demo documents ***************************/
+var fileCache = {};
+
+function initDoc(file, path, doc) {
+ if (doc.prepare)
+ file = doc.prepare(file);
+
+ var session = new EditSession(file);
+ session.setUndoManager(new UndoManager());
+ doc.session = session;
+ doc.path = path;
+ if (doc.wrapped) {
+ session.setUseWrapMode(true);
+ session.setWrapLimitRange(80, 80);
+ }
+ var mode = modelist.getModeFromPath(path);
+ session.modeName = mode.name;
+ session.setMode(mode.mode);
+}
+
+
+function makeHuge(txt) {
+ for (var i = 0; i < 5; i++)
+ txt += txt;
+ return txt;
+}
+
+var docs = {
+ "docs/AsciiDoc.asciidoc": "AsciiDoc",
+ "docs/javascript.js": "JavaScript",
+ "docs/clojure.clj": "Clojure",
+ "docs/coffeescript.coffee": "Coffeescript",
+ "docs/coldfusion.cfm": "ColdFusion",
+ "docs/cpp.cpp": "C/C++",
+ "docs/csharp.cs": "C#",
+ "docs/css.css": "CSS",
+ "docs/diff.diff": "Diff",
+ "docs/glsl.glsl": "Glsl",
+ "docs/golang.go": "Go",
+ "docs/groovy.groovy": "Groovy",
+ "docs/Haxe.hx": "haXe",
+ "docs/html.html": "HTML",
+ "docs/jade.jade": "Jade",
+ "docs/java.java": "Java",
+ "docs/jsp.jsp": "JSP",
+ "docs/json.json": "JSON",
+ "docs/jsx.jsx": "JSX",
+ "docs/latex.tex": {name: "LaTeX", wrapped: true},
+ "docs/less.less": "LESS",
+ "docs/liquid.liquid": "Liquid",
+ "docs/lua.lua": "Lua",
+ "docs/luapage.lp": "LuaPage",
+ "docs/markdown.md": {name: "Markdown", wrapped: true},
+ "docs/ocaml.ml": "OCaml",
+ "docs/OpenSCAD.scad": "OpenSCAD",
+ "docs/perl.pl": "Perl",
+ "docs/pgsql.pgsql": {name: "pgSQL", wrapped: true},
+ "docs/php.php": "PHP",
+ "docs/plaintext.txt": {name: "Plain Text", prepare: makeHuge, wrapped: true},
+ "docs/powershell.ps1": "Powershell",
+ "docs/python.py": "Python",
+ "docs/ruby.rb": "Ruby",
+ "docs/scala.scala": "Scala",
+ "docs/scss.scss": "SCSS",
+ "docs/sh.sh": "SH",
+ "docs/sql.sql": {name: "SQL", wrapped: true},
+ "docs/svg.svg": "SVG",
+ "docs/tcl.tcl": "Tcl",
+ "docs/textile.textile": {name: "Textile", wrapped: true},
+ "docs/typescript.ts": "Typescript",
+ "docs/xml.xml": "XML",
+ "docs/xquery.xq": "XQuery",
+ "docs/yaml.yaml": "YAML",
+ "docs/c9search.c9search_results": "C9 Search Results"
+};
+
+var ownSource = {
+ /* filled from require*/
+};
+
+var hugeDocs = {
+ "build/src/ace.js": "",
+ "build/src-min/ace.js": ""
+};
+
+if (window.require && window.require.s) try {
+ for (var path in window.require.s.contexts._.defined) {
+ if (path.indexOf("!") != -1)
+ path = path.split("!").pop();
+ else
+ path = path + ".js";
+ ownSource[path] = "";
+ }
+} catch(e) {}
+
+function prepareDocList(docs) {
+ var list = [];
+ for (var path in docs) {
+ var doc = docs[path];
+ if (typeof doc != "object")
+ doc = {name: doc || path};
+
+ doc.path = path;
+ doc.desc = doc.name.replace(/^(ace|docs|demo|build)\//, "");
+ if (doc.desc.length > 18)
+ doc.desc = doc.desc.slice(0, 7) + ".." + doc.desc.slice(-9);
+
+ fileCache[doc.name] = doc;
+ list.push(doc);
+ }
+
+ return list;
+}
+
+function loadDoc(name, callback) {
+ var doc = fileCache[name];
+ if (!doc)
+ return callback(null);
+
+ if (doc.session)
+ return callback(doc.session);
+
+ // TODO: show load screen while waiting
+ var path = doc.path;
+ var parts = path.split("/");
+ if (parts[0] == "docs")
+ path = "demo/kitchen-sink/" + path;
+ else if (parts[0] == "ace")
+ path = "lib/" + path;
+
+ net.get(path, function(x) {
+ initDoc(x, path, doc);
+ callback(doc.session);
+ });
+}
+
+module.exports = {
+ fileCache: fileCache,
+ docs: prepareDocList(docs),
+ ownSource: prepareDocList(ownSource),
+ hugeDocs: prepareDocList(hugeDocs),
+ initDoc: initDoc,
+ loadDoc: loadDoc
+};
+module.exports.all = {
+ "Mode Examples": module.exports.docs,
+ "Huge documents": module.exports.hugeDocs,
+ "own source": module.exports.ownSource
+};
+
+});
+
diff --git a/demo/kitchen-sink/docs/AsciiDoc.asciidoc b/demo/kitchen-sink/docs/AsciiDoc.asciidoc
new file mode 100644
index 00000000..8cddab5d
--- /dev/null
+++ b/demo/kitchen-sink/docs/AsciiDoc.asciidoc
@@ -0,0 +1,6040 @@
+AsciiDoc User Guide
+===================
+Stuart Rackham
+:Author Initials: SJR
+:toc:
+:icons:
+:numbered:
+:website: http://www.methods.co.nz/asciidoc/
+
+AsciiDoc is a text document format for writing notes, documentation,
+articles, books, ebooks, slideshows, web pages, blogs and UNIX man
+pages. AsciiDoc files can be translated to many formats including
+HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the
+AsciiDoc source file syntax and the backend output markups (which can
+be almost any type of SGML/XML markup) can be customized and extended
+by the user.
+
+.This document
+**********************************************************************
+This is an overly large document, it probably needs to be refactored
+into a Tutorial, Quick Reference and Formal Reference.
+
+If you're new to AsciiDoc read this section and the <> section and take a look at the example AsciiDoc (`*.txt`)
+source files in the distribution `doc` directory.
+**********************************************************************
+
+
+Introduction
+------------
+AsciiDoc is a plain text human readable/writable document format that
+can be translated to DocBook or HTML using the asciidoc(1) command.
+You can then either use asciidoc(1) generated HTML directly or run
+asciidoc(1) DocBook output through your favorite DocBook toolchain or
+use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,
+LaTeX, PostScript, man page, HTML and text formats.
+
+The AsciiDoc format is a useful presentation format in its own right:
+AsciiDoc markup is simple, intuitive and as such is easily proofed and
+edited.
+
+AsciiDoc is light weight: it consists of a single Python script and a
+bunch of configuration files. Apart from asciidoc(1) and a Python
+interpreter, no other programs are required to convert AsciiDoc text
+files to DocBook or HTML. See <>
+below.
+
+Text markup conventions tend to be a matter of (often strong) personal
+preference: if the default syntax is not to your liking you can define
+your own by editing the text based asciidoc(1) configuration files.
+You can also create configuration files to translate AsciiDoc
+documents to almost any SGML/XML markup.
+
+asciidoc(1) comes with a set of configuration files to translate
+AsciiDoc articles, books and man pages to HTML or DocBook backend
+formats.
+
+.My AsciiDoc Itch
+**********************************************************************
+DocBook has emerged as the de facto standard Open Source documentation
+format. But DocBook is a complex language, the markup is difficult to
+read and even more difficult to write directly -- I found I was
+spending more time typing markup tags, consulting reference manuals
+and fixing syntax errors, than I was writing the documentation.
+**********************************************************************
+
+
+[[X6]]
+Getting Started
+---------------
+Installing AsciiDoc
+~~~~~~~~~~~~~~~~~~~
+See the `README` and `INSTALL` files for install prerequisites and
+procedures. Packagers take a look at <>.
+
+[[X11]]
+Example AsciiDoc Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The best way to quickly get a feel for AsciiDoc is to view the
+AsciiDoc web site and/or distributed examples:
+
+- Take a look at the linked examples on the AsciiDoc web site home
+ page {website}. Press the 'Page Source' sidebar menu item to view
+ corresponding AsciiDoc source.
+- Read the `*.txt` source files in the distribution `./doc` directory
+ along with the corresponding HTML and DocBook XML files.
+
+
+AsciiDoc Document Types
+-----------------------
+There are three types of AsciiDoc documents: article, book and
+manpage. All document types share the same AsciiDoc format with some
+minor variations. If you are familiar with DocBook you will have
+noticed that AsciiDoc document types correspond to the same-named
+DocBook document types.
+
+Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc
+document type -- the default document type is 'article'.
+
+By convention the `.txt` file extension is used for AsciiDoc document
+source files.
+
+article
+~~~~~~~
+Used for short documents, articles and general documentation. See the
+AsciiDoc distribution `./doc/article.txt` example.
+
+AsciiDoc defines standard DocBook article frontmatter and backmatter
+<> (appendix, abstract, bibliography,
+glossary, index).
+
+book
+~~~~
+Books share the same format as articles, with the following
+differences:
+
+- The part titles in multi-part books are <>
+ (same level as book title).
+- Some sections are book specific e.g. preface and colophon.
+
+Book documents will normally be used to produce DocBook output since
+DocBook processors can automatically generate footnotes, table of
+contents, list of tables, list of figures, list of examples and
+indexes.
+
+AsciiDoc defines standard DocBook book frontmatter and backmatter
+<> (appendix, dedication, preface,
+bibliography, glossary, index, colophon).
+
+.Example book documents
+Book::
+ The `./doc/book.txt` file in the AsciiDoc distribution.
+
+Multi-part book::
+ The `./doc/book-multi.txt` file in the AsciiDoc distribution.
+
+manpage
+~~~~~~~
+Used to generate roff format UNIX manual pages. AsciiDoc manpage
+documents observe special header title and section naming conventions
+-- see the <> section for details.
+
+AsciiDoc defines the 'synopsis' <> to
+generate the DocBook `refsynopsisdiv` section.
+
+See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from
+the AsciiDoc distribution.
+
+
+[[X5]]
+AsciiDoc Backends
+-----------------
+The asciidoc(1) command translates an AsciiDoc formatted file to the
+backend format specified by the `-b` (`--backend`) command-line
+option. asciidoc(1) itself has little intrinsic knowledge of backend
+formats, all translation rules are contained in customizable cascading
+configuration files. Backend specific attributes are listed in the
+<> section.
+
+docbook45::
+ Outputs DocBook XML 4.5 markup.
+
+html4::
+ This backend generates plain HTML 4.01 Transitional markup.
+
+xhtml11::
+ This backend generates XHTML 1.1 markup styled with CSS2. Output
+ files have an `.html` extension.
+
+html5::
+ This backend generates HTML 5 markup, apart from the inclusion of
+ <> it is functionally identical to
+ the 'xhtml11' backend.
+
+slidy::
+ Use this backend to generate self-contained
+ http://www.w3.org/Talks/Tools/Slidy2/[Slidy] HTML slideshows for
+ your web browser from AsciiDoc documents. The Slidy backend is
+ documented in the distribution `doc/slidy.txt` file and
+ {website}slidy.html[online].
+
+wordpress::
+ A minor variant of the 'html4' backend to support
+ http://srackham.wordpress.com/blogpost1/[blogpost].
+
+latex::
+ Experimental LaTeX backend.
+
+Backend Aliases
+~~~~~~~~~~~~~~~
+Backend aliases are alternative names for AsciiDoc backends. AsciiDoc
+comes with two backend aliases: 'html' (aliased to 'xhtml11') and
+'docbook' (aliased to 'docbook45').
+
+You can assign (or reassign) backend aliases by setting an AsciiDoc
+attribute named like `backend-alias-` to an AsciiDoc backend
+name. For example, the following backend alias attribute definitions
+appear in the `[attributes]` section of the global `asciidoc.conf`
+configuration file:
+
+ backend-alias-html=xhtml11
+ backend-alias-docbook=docbook45
+
+[[X100]]
+Backend Plugins
+~~~~~~~~~~~~~~~
+The asciidoc(1) `--backend` option is also used to install and manage
+backend <>.
+
+- A backend plugin is used just like the built-in backends.
+- Backend plugins <> over built-in backends with
+ the same name.
+- You can use the `{asciidoc-confdir}` <> to
+ refer to the built-in backend configuration file location from
+ backend plugin configuration files.
+- You can use the `{backend-confdir}` <> to
+ refer to the backend plugin configuration file location.
+- By default backends plugins are installed in
+ `$HOME/.asciidoc/backends/` where `` is the
+ backend name.
+
+
+DocBook
+-------
+AsciiDoc generates 'article', 'book' and 'refentry'
+http://www.docbook.org/[DocBook] documents (corresponding to the
+AsciiDoc 'article', 'book' and 'manpage' document types).
+
+Most Linux distributions come with conversion tools (collectively
+called a toolchain) for <> to
+presentation formats such as Postscript, HTML, PDF, EPUB, DVI,
+PostScript, LaTeX, roff (the native man page format), HTMLHelp,
+JavaHelp and text. There are also programs that allow you to view
+DocBook files directly, for example http://live.gnome.org/Yelp[Yelp]
+(the GNOME help viewer).
+
+[[X12]]
+Converting DocBook to other file formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DocBook files are validated, parsed and translated various
+presentation file formats using a combination of applications
+collectively called a DocBook 'tool chain'. The function of a tool
+chain is to read the DocBook markup (produced by AsciiDoc) and
+transform it to a presentation format (for example HTML, PDF, HTML
+Help, EPUB, DVI, PostScript, LaTeX).
+
+A wide range of user output format requirements coupled with a choice
+of available tools and stylesheets results in many valid tool chain
+combinations.
+
+[[X43]]
+a2x Toolchain Wrapper
+~~~~~~~~~~~~~~~~~~~~~
+One of the biggest hurdles for new users is installing, configuring
+and using a DocBook XML toolchain. `a2x(1)` can help -- it's a
+toolchain wrapper command that will generate XHTML (chunked and
+unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
+file outputs from an AsciiDoc text file. `a2x(1)` does all the grunt
+work associated with generating and sequencing the toolchain commands
+and managing intermediate and output files. `a2x(1)` also optionally
+deploys admonition and navigation icons and a CSS stylesheet. See the
+`a2x(1)` man page for more details. In addition to `asciidoc(1)` you
+also need <>, <> and
+optionally: <> or <> (to generate PDF);
+`w3m(1)` or `lynx(1)` (to generate text).
+
+The following examples generate `doc/source-highlight-filter.pdf` from
+the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
+example uses `dblatex(1)` (the default PDF generator) the second
+example forces FOP to be used:
+
+ $ a2x -f pdf doc/source-highlight-filter.txt
+ $ a2x -f pdf --fop doc/source-highlight-filter.txt
+
+See the `a2x(1)` man page for details.
+
+TIP: Use the `--verbose` command-line option to view executed
+toolchain commands.
+
+HTML generation
+~~~~~~~~~~~~~~~
+AsciiDoc produces nicely styled HTML directly without requiring a
+DocBook toolchain but there are also advantages in going the DocBook
+route:
+
+- HTML from DocBook can optionally include automatically generated
+ indexes, tables of contents, footnotes, lists of figures and tables.
+- DocBook toolchains can also (optionally) generate separate (chunked)
+ linked HTML pages for each document section.
+- Toolchain processing performs link and document validity checks.
+- If the DocBook 'lang' attribute is set then things like table of
+ contents, figure and table captions and admonition captions will be
+ output in the specified language (setting the AsciiDoc 'lang'
+ attribute sets the DocBook 'lang' attribute).
+
+On the other hand, HTML output directly from AsciiDoc is much faster,
+is easily customized and can be used in situations where there is no
+suitable DocBook toolchain (for example, see the {website}[AsciiDoc
+website]).
+
+PDF generation
+~~~~~~~~~~~~~~
+There are two commonly used tools to generate PDFs from DocBook,
+<> and <>.
+
+.dblatex or FOP?
+- 'dblatex' is easier to install, there's zero configuration
+ required and no Java VM to install -- it just works out of the box.
+- 'dblatex' source code highlighting and numbering is superb.
+- 'dblatex' is easier to use as it converts DocBook directly to PDF
+ whereas before using 'FOP' you have to convert DocBook to XML-FO
+ using <>.
+- 'FOP' is more feature complete (for example, callouts are processed
+ inside literal layouts) and arguably produces nicer looking output.
+
+HTML Help generation
+~~~~~~~~~~~~~~~~~~~~
+. Convert DocBook XML documents to HTML Help compiler source files
+ using <> and <>.
+. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
+ (`.chm`) files using the <>.
+
+Toolchain components summary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc::
+ Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
+
+[[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::
+ These are a set of XSL stylesheets containing rules for converting
+ DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
+ The stylesheets are used in conjunction with an XML parser such as
+ <>.
+
+[[X40]]http://www.xmlsoft.org[xsltproc]::
+ An XML parser for applying XSLT stylesheets (in our case the
+ <>) to XML documents.
+
+[[X31]]http://dblatex.sourceforge.net/[dblatex]::
+ Generates PDF, DVI, PostScript and LaTeX formats directly from
+ DocBook source via the intermediate LaTeX typesetting language --
+ uses <>, <> and
+ `latex(1)`.
+
+[[X14]]http://xml.apache.org/fop/[FOP]::
+ The Apache Formatting Objects Processor converts XSL-FO (`.fo`)
+ files to PDF files. The XSL-FO files are generated from DocBook
+ source files using <> and
+ <>.
+
+[[X67]]Microsoft Help Compiler::
+ The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool
+ that converts HTML Help source files to a single HTML Help (`.chm`)
+ file. It runs on MS Windows platforms and can be downloaded from
+ http://www.microsoft.com.
+
+AsciiDoc dblatex configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The AsciiDoc distribution `./dblatex` directory contains
+`asciidoc-dblatex.xsl` (customized XSL parameter settings) and
+`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples
+of optional <> output customization and are used by
+<>.
+
+AsciiDoc DocBook XSL Stylesheets drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You will have noticed that the distributed HTML and HTML Help
+documentation files (for example `./doc/asciidoc.html`) are not the
+plain outputs produced using the default 'DocBook XSL Stylesheets'
+configuration. This is because they have been processed using
+customized DocBook XSL Stylesheets along with (in the case of HTML
+outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet.
+
+You'll find the customized DocBook XSL drivers along with additional
+documentation in the distribution `./docbook-xsl` directory. The
+examples that follow are executed from the distribution documentation
+(`./doc`) directory. These drivers are also used by <>.
+
+`common.xsl`::
+ Shared driver parameters. This file is not used directly but is
+ included in all the following drivers.
+
+`chunked.xsl`::
+ Generate chunked XHTML (separate HTML pages for each document
+ section) in the `./doc/chunked` directory. For example:
+
+ $ python ../asciidoc.py -b docbook asciidoc.txt
+ $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
+
+`epub.xsl`::
+ Used by <> to generate EPUB formatted documents.
+
+`fo.xsl`::
+ Generate XSL Formatting Object (`.fo`) files for subsequent PDF
+ file generation using FOP. For example:
+
+ $ python ../asciidoc.py -b docbook article.txt
+ $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
+ $ fop article.fo article.pdf
+
+`htmlhelp.xsl`::
+ Generate Microsoft HTML Help source files for the MS HTML Help
+ Compiler in the `./doc/htmlhelp` directory. This example is run on
+ MS Windows from a Cygwin shell prompt:
+
+ $ python ../asciidoc.py -b docbook asciidoc.txt
+ $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
+ $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
+
+`manpage.xsl`::
+ Generate a `roff(1)` format UNIX man page from a DocBook XML
+ 'refentry' document. This example generates an `asciidoc.1` man
+ page file:
+
+ $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
+ $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
+
+`xhtml.xsl`::
+ Convert a DocBook XML file to a single XHTML file. For example:
+
+ $ python ../asciidoc.py -b docbook asciidoc.txt
+ $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
+
+If you want to see how the complete documentation set is processed
+take a look at the A-A-P script `./doc/main.aap`.
+
+
+Generating Plain Text Files
+---------------------------
+AsciiDoc does not have a text backend (for most purposes AsciiDoc
+source text is fine), however you can convert AsciiDoc text files to
+formatted text using the AsciiDoc <> toolchain wrapper
+utility.
+
+
+[[X35]]
+HTML5 and XHTML 1.1
+-------------------
+The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript
+files in their outputs, there is also a <> plugin
+framework.
+
+- If the AsciiDoc 'linkcss' attribute is defined then CSS and
+ JavaScript files are linked to the output document, otherwise they
+ are embedded (the default behavior).
+- The default locations for CSS and JavaScript files can be changed by
+ setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes
+ respectively.
+- The default locations for embedded and linked files differ and are
+ calculated at different times -- embedded files are loaded when
+ asciidoc(1) generates the output document, linked files are loaded
+ by the browser when the user views the output document.
+- Embedded files are automatically inserted in the output files but
+ you need to manually copy linked CSS and Javascript files from
+ AsciiDoc <> to the correct location
+ relative to the output document.
+
+.Stylesheet file locations
+[cols="3*",frame="topbot",options="header"]
+|====================================================================
+|'stylesdir' attribute
+|Linked location ('linkcss' attribute defined)
+|Embedded location ('linkcss' attribute undefined)
+
+|Undefined (default).
+|Same directory as the output document.
+|`stylesheets` subdirectory in the AsciiDoc configuration directory
+(the directory containing the backend conf file).
+
+|Absolute or relative directory name.
+|Absolute or relative to the output document.
+|Absolute or relative to the AsciiDoc configuration directory (the
+directory containing the backend conf file).
+
+|====================================================================
+
+.JavaScript file locations
+[cols="3*",frame="topbot",options="header"]
+|====================================================================
+|'scriptsdir' attribute
+|Linked location ('linkcss' attribute defined)
+|Embedded location ('linkcss' attribute undefined)
+
+|Undefined (default).
+|Same directory as the output document.
+|`javascripts` subdirectory in the AsciiDoc configuration directory
+(the directory containing the backend conf file).
+
+|Absolute or relative directory name.
+|Absolute or relative to the output document.
+|Absolute or relative to the AsciiDoc configuration directory (the
+directory containing the backend conf file).
+
+|====================================================================
+
+[[X99]]
+Themes
+~~~~~~
+The AsciiDoc 'theme' attribute is used to select an alternative CSS
+stylesheet and to optionally include additional JavaScript code.
+
+- Theme files reside in an AsciiDoc <>
+ named `themes//` (where `` is the the theme name set
+ by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute
+ to the theme directory path name.
+- The 'theme' attribute can also be set using the asciidoc(1)
+ `--theme` option, the `--theme` option can also be used to manage
+ theme <>.
+- AsciiDoc ships with two themes: 'flask' and 'volnitsky'.
+- The `.css` file replaces the default `asciidoc.css` CSS file.
+- The `.js` file is included in addition to the default
+ `asciidoc.js` JavaScript file.
+- If the <> attribute is defined then icons are loaded
+ from the theme `icons` sub-directory if it exists (i.e. the
+ 'iconsdir' attribute is set to theme `icons` sub-directory path).
+- Embedded theme files are automatically inserted in the output files
+ but you need to manually copy linked CSS and Javascript files to the
+ location of the output documents.
+- Linked CSS and JavaScript theme files are linked to the same linked
+ locations as <>.
+
+For example, the command-line option `--theme foo` (or `--attribute
+theme=foo`) will cause asciidoc(1) to search <<"X27","configuration
+file locations 1, 2 and 3">> for a sub-directory called `themes/foo`
+containing the stylesheet `foo.css` and optionally a JavaScript file
+name `foo.js`.
+
+
+Document Structure
+------------------
+An AsciiDoc document consists of a series of <>
+starting with an optional document Header, followed by an optional
+Preamble, followed by zero or more document Sections.
+
+Almost any combination of zero or more elements constitutes a valid
+AsciiDoc document: documents can range from a single sentence to a
+multi-part book.
+
+Block Elements
+~~~~~~~~~~~~~~
+Block elements consist of one or more lines of text and may contain
+other block elements.
+
+The AsciiDoc block structure can be informally summarized as follows
+footnote:[This is a rough structural guide, not a rigorous syntax
+definition]:
+
+ Document ::= (Header?,Preamble?,Section*)
+ Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
+ AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
+ RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
+ Preamble ::= (SectionBody)
+ Section ::= (Title,SectionBody?,(Section)*)
+ SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
+ Block ::= (Paragraph|DelimitedBlock|List|Table)
+ List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
+ BulletedList ::= (ListItem)+
+ NumberedList ::= (ListItem)+
+ CalloutList ::= (ListItem)+
+ LabeledList ::= (ListEntry)+
+ ListEntry ::= (ListLabel,ListItem)
+ ListLabel ::= (ListTerm+)
+ ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
+
+Where:
+
+- '?' implies zero or one occurrence, '+' implies one or more
+ occurrences, '*' implies zero or more occurrences.
+- All block elements are separated by line boundaries.
+- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
+ shown) can occur almost anywhere.
+- There are a number of document type and backend specific
+ restrictions imposed on the block syntax.
+- The following elements cannot contain blank lines: Header, Title,
+ Paragraph, ItemText.
+- A ListParagraph is a Paragraph with its 'listelement' option set.
+- A ListContinuation is a <>.
+
+[[X95]]
+Header
+~~~~~~
+The Header contains document meta-data, typically title plus optional
+authorship and revision information:
+
+- The Header is optional, but if it is used it must start with a
+ document <>.
+- Optional Author and Revision information immediately follows the
+ header title.
+- The document header must be separated from the remainder of the
+ document by one or more blank lines and cannot contain blank lines.
+- The header can include comments.
+- The header can include <>, typically
+ 'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc',
+ 'numbered'.
+- Header attributes are overridden by command-line attributes.
+- If the header contains non-UTF-8 characters then the 'encoding' must
+ precede the header (either in the document or on the command-line).
+
+Here's an example AsciiDoc document header:
+
+ Writing Documentation using AsciiDoc
+ ====================================
+ Joe Bloggs
+ v2.0, February 2003:
+ Rewritten for version 2 release.
+
+The author information line contains the author's name optionally
+followed by the author's email address. The author's name is formatted
+like:
+
+ firstname[ [middlename ]lastname][ ]]
+
+i.e. a first name followed by optional middle and last names followed
+by an email address in that order. Multi-word first, middle and last
+names can be entered using the underscore as a word separator. The
+email address comes last and must be enclosed in angle <> brackets.
+Here a some examples of author information lines:
+
+ Joe Bloggs
+ Joe Bloggs
+ Vincent Willem van_Gogh
+
+If the author line does not match the above specification then the
+entire author line is treated as the first name.
+
+The optional revision information line follows the author information
+line. The revision information can be one of two formats:
+
+. An optional document revision number followed by an optional
+ revision date followed by an optional revision remark:
++
+--
+ * If the revision number is specified it must be followed by a
+ comma.
+ * The revision number must contain at least one numeric character.
+ * Any non-numeric characters preceding the first numeric character
+ will be dropped.
+ * If a revision remark is specified it must be preceded by a colon.
+ The revision remark extends from the colon up to the next blank
+ line, attribute entry or comment and is subject to normal text
+ substitutions.
+ * If a revision number or remark has been set but the revision date
+ has not been set then the revision date is set to the value of the
+ 'docdate' attribute.
+
+Examples:
+
+ v2.0, February 2003
+ February 2003
+ v2.0,
+ v2.0, February 2003: Rewritten for version 2 release.
+ February 2003: Rewritten for version 2 release.
+ v2.0,: Rewritten for version 2 release.
+ :Rewritten for version 2 release.
+--
+
+. The revision information line can also be an RCS/CVS/SVN $Id$
+ marker:
++
+--
+ * AsciiDoc extracts the 'revnumber', 'revdate', and 'author'
+ attributes from the $Id$ revision marker and displays them in the
+ document header.
+ * If an $Id$ revision marker is used the header author line can be
+ omitted.
+
+Example:
+
+ $Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $
+--
+
+You can override or set header parameters by passing 'revnumber',
+'revremark', 'revdate', 'email', 'author', 'authorinitials',
+'firstname' and 'lastname' attributes using the asciidoc(1) `-a`
+(`--attribute`) command-line option. For example:
+
+ $ asciidoc -a revdate=2004/07/27 article.txt
+
+Attribute entries can also be added to the header for substitution in
+the header template with <> elements.
+
+The 'title' element in HTML outputs is set to the AsciiDoc document
+title, you can set it to a different value by including a 'title'
+attribute entry in the document header.
+
+[[X87]]
+Additional document header information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+AsciiDoc has two mechanisms for optionally including additional
+meta-data in the header of the output document:
+
+'docinfo' configuration file sections::
+If a <> section named 'docinfo' has been loaded
+then it will be included in the document header. Typically the
+'docinfo' section name will be prefixed with a '+' character so that it
+is appended to (rather than replace) other 'docinfo' sections.
+
+'docinfo' files::
+Two docinfo files are recognized: one named `docinfo` and a second
+named like the AsciiDoc source file with a `-docinfo` suffix. For
+example, if the source document is called `mydoc.txt` then the
+document information files would be `docinfo.xml` and
+`mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and
+`mydoc-docinfo.html` (for HTML outputs). The <> attributes control which docinfo files are included in
+the output files.
+
+The contents docinfo templates and files is dependent on the type of
+output:
+
+HTML::
+ Valid 'head' child elements. Typically 'style' and 'script' elements
+ for CSS and JavaScript inclusion.
+
+DocBook::
+ Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines
+ numerous elements for document meta-data, for example: copyrights,
+ document history and authorship information. See the DocBook
+ `./doc/article-docinfo.xml` example that comes with the AsciiDoc
+ distribution. The rendering of meta-data elements (or not) is
+ DocBook processor dependent.
+
+
+[[X86]]
+Preamble
+~~~~~~~~
+The Preamble is an optional untitled section body between the document
+Header and the first Section title.
+
+Sections
+~~~~~~~~
+In addition to the document title (level 0), AsciiDoc supports four
+section levels: 1 (top) to 4 (bottom). Section levels are delimited
+by section <>. Sections are translated using
+configuration file <>. AsciiDoc
+generates the following <> specifically for
+use in section markup templates:
+
+level::
+The `level` attribute is the section level number, it is normally just
+the <> level number (1..4). However, if the `leveloffset`
+attribute is defined it will be added to the `level` attribute. The
+`leveloffset` attribute is useful for <>.
+
+sectnum::
+The `-n` (`--section-numbers`) command-line option generates the
+`sectnum` (section number) attribute. The `sectnum` attribute is used
+for section numbers in HTML outputs (DocBook section numbering are
+handled automatically by the DocBook toolchain commands).
+
+[[X93]]
+Section markup templates
+^^^^^^^^^^^^^^^^^^^^^^^^
+Section markup templates specify output markup and are defined in
+AsciiDoc configuration files. Section markup template names are
+derived as follows (in order of precedence):
+
+1. From the title's first positional attribute or 'template'
+ attribute. For example, the following three section titles are
+ functionally equivalent:
++
+.....................................................................
+[[terms]]
+[glossary]
+List of Terms
+-------------
+
+["glossary",id="terms"]
+List of Terms
+-------------
+
+[template="glossary",id="terms"]
+List of Terms
+-------------
+.....................................................................
+
+2. When the title text matches a configuration file
+ <> entry.
+3. If neither of the above the default `sect` template is used
+ (where `` is a number from 1 to 4).
+
+In addition to the normal section template names ('sect1', 'sect2',
+'sect3', 'sect4') AsciiDoc has the following templates for
+frontmatter, backmatter and other special sections: 'abstract',
+'preface', 'colophon', 'dedication', 'glossary', 'bibliography',
+'synopsis', 'appendix', 'index'. These special section templates
+generate the corresponding Docbook elements; for HTML outputs they
+default to the 'sect1' section template.
+
+Section IDs
+^^^^^^^^^^^
+If no explicit section ID is specified an ID will be synthesised from
+the section title. The primary purpose of this feature is to ensure
+persistence of table of contents links (permalinks): the missing
+section IDs are generated dynamically by the JavaScript TOC generator
+*after* the page is loaded. If you link to a dynamically generated TOC
+address the page will load but the browser will ignore the (as yet
+ungenerated) section ID.
+
+The IDs are generated by the following algorithm:
+
+- Replace all non-alphanumeric title characters with underscores.
+- Strip leading or trailing underscores.
+- Convert to lowercase.
+- Prepend the `idprefix` attribute (so there's no possibility of name
+ clashes with existing document IDs). Prepend an underscore if the
+ `idprefix` attribute is not defined.
+- A numbered suffix (`_2`, `_3` ...) is added if a same named
+ auto-generated section ID exists.
+- If the `ascii-ids` attribute is defined then non-ASCII characters
+ are replaced with ASCII equivalents. This attribute may be
+ deprecated in future releases and *should be avoided*, it's sole
+ purpose is to accommodate deficient downstream applications that
+ cannot process non-ASCII ID attributes.
+
+Example: the title 'Jim's House' would generate the ID `_jim_s_house`.
+
+Section ID synthesis can be disabled by undefining the `sectids`
+attribute.
+
+[[X16]]
+Special Section Titles
+^^^^^^^^^^^^^^^^^^^^^^
+AsciiDoc has a mechanism for mapping predefined section titles
+auto-magically to specific markup templates. For example a title
+'Appendix A: Code Reference' will automatically use the 'appendix'
+<>. The mappings from title to template
+name are specified in `[specialsections]` sections in the Asciidoc
+language configuration files (`lang-*.conf`). Section entries are
+formatted like:
+
+ =
+
+`` is a Python regular expression and `` is the name
+of a configuration file markup template section. If the ``
+matches an AsciiDoc document section title then the backend output is
+marked up using the `` markup template (instead of the
+default `sect` section template). The `{title}` attribute value
+is set to the value of the matched regular expression group named
+'title', if there is no 'title' group `{title}` defaults to the whole
+of the AsciiDoc section title. If `` is blank then any
+existing entry with the same `` will be deleted.
+
+.Special section titles vs. explicit template names
+*********************************************************************
+AsciiDoc has two mechanisms for specifying non-default section markup
+templates: you can specify the template name explicitly (using the
+'template' attribute) or indirectly (using 'special section titles').
+Specifying a <> attribute explicitly is
+preferred. Auto-magical 'special section titles' have the following
+drawbacks:
+
+- They are non-obvious, you have to know the exact matching
+ title for each special section on a language by language basis.
+- Section titles are predefined and can only be customised with a
+ configuration change.
+- The implementation is complicated by multiple languages: every
+ special section title has to be defined for each language (in each
+ of the `lang-*.conf` files).
+
+Specifying special section template names explicitly does add more
+noise to the source document (the 'template' attribute declaration),
+but the intention is obvious and the syntax is consistent with other
+AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
+
+Special section titles have been deprecated but are retained for
+backward compatibility.
+
+*********************************************************************
+
+Inline Elements
+~~~~~~~~~~~~~~~
+<> are used to format text and to
+perform various types of text substitution. Inline elements and inline
+element syntax is defined in the asciidoc(1) configuration files.
+
+Here is a list of AsciiDoc inline elements in the (default) order in
+which they are processed:
+
+Special characters::
+ These character sequences escape special characters used by
+ the backend markup (typically `<`, `>`, and `&` characters).
+ See `[specialcharacters]` configuration file sections.
+
+Quotes::
+ Elements that markup words and phrases; usually for character
+ formatting. See `[quotes]` configuration file sections.
+
+Special Words::
+ Word or word phrase patterns singled out for markup without
+ the need for further annotation. See `[specialwords]`
+ configuration file sections.
+
+Replacements::
+ Each replacement defines a word or word phrase pattern to
+ search for along with corresponding replacement text. See
+ `[replacements]` configuration file sections.
+
+Attribute references::
+ Document attribute names enclosed in braces are replaced by
+ the corresponding attribute value.
+
+Inline Macros::
+ Inline macros are replaced by the contents of parametrized
+ configuration file sections.
+
+
+Document Processing
+-------------------
+The AsciiDoc source document is read and processed as follows:
+
+1. The document 'Header' is parsed, header parameter values are
+ substituted into the configuration file `[header]` template section
+ which is then written to the output file.
+2. Each document 'Section' is processed and its constituent elements
+ translated to the output file.
+3. The configuration file `[footer]` template section is substituted
+ and written to the output file.
+
+When a block element is encountered asciidoc(1) determines the type of
+block by checking in the following order (first to last): (section)
+Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
+AttributeLists, BlockTitles, Paragraphs.
+
+The default paragraph definition `[paradef-default]` is last element
+to be checked.
+
+Knowing the parsing order will help you devise unambiguous macro, list
+and block syntax rules.
+
+Inline substitutions within block elements are performed in the
+following default order:
+
+1. Special characters
+2. Quotes
+3. Special words
+4. Replacements
+5. Attributes
+6. Inline Macros
+7. Replacements2
+
+The substitutions and substitution order performed on
+Title, Paragraph and DelimitedBlock elements is determined by
+configuration file parameters.
+
+
+Text Formatting
+---------------
+[[X51]]
+Quoted Text
+~~~~~~~~~~~
+Words and phrases can be formatted by enclosing inline text with
+quote characters:
+
+_Emphasized text_::
+ Word phrases \'enclosed in single quote characters' (acute
+ accents) or \_underline characters_ are emphasized.
+
+*Strong text*::
+ Word phrases \*enclosed in asterisk characters* are rendered
+ in a strong font (usually bold).
+
+[[X81]]+Monospaced text+::
+ Word phrases \+enclosed in plus characters+ are rendered in a
+ monospaced font. Word phrases \`enclosed in backtick
+ characters` (grave accents) are also rendered in a monospaced
+ font but in this case the enclosed text is rendered literally
+ and is not subject to further expansion (see <>).
+
+`Single quoted text'::
+ Phrases enclosed with a \`single grave accent to the left and
+ a single acute accent to the right' are rendered in single
+ quotation marks.
+
+``Double quoted text''::
+ Phrases enclosed with \\``two grave accents to the left and
+ two acute accents to the right'' are rendered in quotation
+ marks.
+
+#Unquoted text#::
+ Placing \#hashes around text# does nothing, it is a mechanism
+ to allow inline attributes to be applied to otherwise
+ unformatted text.
+
+New quote types can be defined by editing asciidoc(1) configuration
+files. See the <> section for details.
+
+.Quoted text behavior
+- Quoting cannot be overlapped.
+- Different quoting types can be nested.
+- To suppress quoted text formatting place a backslash character
+ immediately in front of the leading quote character(s). In the case
+ of ambiguity between escaped and non-escaped text you will need to
+ escape both leading and trailing quotes, in the case of
+ multi-character quotes you may even need to escape individual
+ characters.
+
+[[X96]]
+Quoted text attributes
+^^^^^^^^^^^^^^^^^^^^^^
+Quoted text can be prefixed with an <>. The first
+positional attribute ('role' attribute) is translated by AsciiDoc to
+an HTML 'span' element 'class' attribute or a DocBook 'phrase' element
+'role' attribute.
+
+DocBook XSL Stylesheets translate DocBook 'phrase' elements with
+'role' attributes to corresponding HTML 'span' elements with the same
+'class' attributes; CSS can then be used
+http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
+generated HTML]. Thus CSS styling can be applied to both DocBook and
+AsciiDoc generated HTML outputs. You can also specify multiple class
+names separated by spaces.
+
+CSS rules for text color, text background color, text size and text
+decorators are included in the distributed AsciiDoc CSS files and are
+used in conjunction with AsciiDoc 'xhtml11', 'html5' and 'docbook'
+outputs. The CSS class names are:
+
+- '' (text foreground color).
+- '-background' (text background color).
+- 'big' and 'small' (text size).
+- 'underline', 'overline' and 'line-through' (strike through) text
+ decorators.
+
+Where '' can be any of the
+http://en.wikipedia.org/wiki/Web_colors#HTML_color_names[sixteen HTML
+color names]. Examples:
+
+ [red]#Obvious# and [big red yellow-background]*very obvious*.
+
+ [underline]#Underline text#, [overline]#overline text# and
+ [blue line-through]*bold blue and line-through*.
+
+is rendered as:
+
+[red]#Obvious# and [big red yellow-background]*very obvious*.
+
+[underline]#Underline text#, [overline]#overline text# and
+[bold blue line-through]*bold blue and line-through*.
+
+NOTE: Color and text decorator attributes are rendered for XHTML and
+HTML 5 outputs using CSS stylesheets. The mechanism to implement
+color and text decorator attributes is provided for DocBook toolchains
+via the DocBook 'phrase' element 'role' attribute, but the actual
+rendering is toolchain specific and is not part of the AsciiDoc
+distribution.
+
+[[X52]]
+Constrained and Unconstrained Quotes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are actually two types of quotes:
+
+Constrained quotes
+++++++++++++++++++
+Quoted must be bounded by white space or commonly adjoining
+punctuation characters. These are the most commonly used type of
+quote.
+
+Unconstrained quotes
+++++++++++++++++++++
+Unconstrained quotes have no boundary constraints and can be placed
+anywhere within inline text. For consistency and to make them easier
+to remember unconstrained quotes are double-ups of the `_`, `*`, `+`
+and `#` constrained quotes:
+
+ __unconstrained emphasized text__
+ **unconstrained strong text**
+ ++unconstrained monospaced text++
+ ##unconstrained unquoted text##
+
+The following example emboldens the letter F:
+
+ **F**ile Open...
+
+Superscripts and Subscripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Put \^carets on either^ side of the text to be superscripted, put
+\~tildes on either side~ of text to be subscripted. For example, the
+following line:
+
+ e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
+ and ~some sub text~
+
+Is rendered like:
+
+e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
+and ~some sub text~
+
+Superscripts and subscripts are implemented as <> and they can be escaped with a leading backslash and prefixed
+with with an attribute list.
+
+Line Breaks
+~~~~~~~~~~~
+A plus character preceded by at least one space character at the end
+of a non-blank line forces a line break. It generates a line break
+(`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing
+instruction for DocBook outputs. The `asciidoc-br` processing
+instruction is handled by <>.
+
+Page Breaks
+~~~~~~~~~~~
+A line of three or more less-than (`<<<`) characters will generate a
+hard page break in DocBook and printed HTML outputs. It uses the CSS
+`page-break-after` property for HTML outputs and a custom XML
+`asciidoc-pagebreak` processing instruction for DocBook outputs. The
+`asciidoc-pagebreak` processing instruction is handled by
+<>. Hard page breaks are sometimes handy but as a general
+rule you should let your page processor generate page breaks for you.
+
+Rulers
+~~~~~~
+A line of three or more apostrophe characters will generate a ruler
+line. It generates a ruler (`hr`) tag for HTML outputs and a custom
+XML `asciidoc-hr` processing instruction for DocBook outputs. The
+`asciidoc-hr` processing instruction is handled by <>.
+
+Tabs
+~~~~
+By default tab characters input files will translated to 8 spaces. Tab
+expansion is set with the 'tabsize' entry in the configuration file
+`[miscellaneous]` section and can be overridden in included files by
+setting a 'tabsize' attribute in the `include` macro's attribute list.
+For example:
+
+ include::addendum.txt[tabsize=2]
+
+The tab size can also be set using the attribute command-line option,
+for example `--attribute tabsize=4`
+
+Replacements
+~~~~~~~~~~~~
+The following replacements are defined in the default AsciiDoc
+configuration:
+
+ (C) copyright, (TM) trademark, (R) registered trademark,
+ -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
+ double arrow, <= left double arrow.
+
+Which are rendered as:
+
+(C) copyright, (TM) trademark, (R) registered trademark,
+-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
+double arrow, <= left double arrow.
+
+You can also include arbitrary entity references in the AsciiDoc
+source. Examples:
+
+ ➊ ¶
+
+renders:
+
+➊ ¶
+
+To render a replacement literally escape it with a leading back-slash.
+
+The <> section explains how to configure your
+own replacements.
+
+Special Words
+~~~~~~~~~~~~~
+Words defined in `[specialwords]` configuration file sections are
+automatically marked up without having to be explicitly notated.
+
+The <> section explains how to add and replace
+special words.
+
+
+[[X17]]
+Titles
+------
+Document and section titles can be in either of two formats:
+
+Two line titles
+~~~~~~~~~~~~~~~
+A two line title consists of a title line, starting hard against the
+left margin, and an underline. Section underlines consist a repeated
+character pairs spanning the width of the preceding title (give or
+take up to two characters):
+
+The default title underlines for each of the document levels are:
+
+
+ Level 0 (top level): ======================
+ Level 1: ----------------------
+ Level 2: ~~~~~~~~~~~~~~~~~~~~~~
+ Level 3: ^^^^^^^^^^^^^^^^^^^^^^
+ Level 4 (bottom level): ++++++++++++++++++++++
+
+Examples:
+
+ Level One Section Title
+ -----------------------
+
+ Level 2 Subsection Title
+ ~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[X46]]
+One line titles
+~~~~~~~~~~~~~~~
+One line titles consist of a single line delimited on either side by
+one or more equals characters (the number of equals characters
+corresponds to the section level minus one). Here are some examples:
+
+ = Document Title (level 0) =
+ == Section title (level 1) ==
+ === Section title (level 2) ===
+ ==== Section title (level 3) ====
+ ===== Section title (level 4) =====
+
+[NOTE]
+=====================================================================
+- One or more spaces must fall between the title and the delimiters.
+- The trailing title delimiter is optional.
+- The one-line title syntax can be changed by editing the
+ configuration file `[titles]` section `sect0`...`sect4` entries.
+=====================================================================
+
+Floating titles
+~~~~~~~~~~~~~~~
+Setting the title's first positional attribute or 'style' attribute to
+'float' generates a free-floating title. A free-floating title is
+rendered just like a normal section title but is not formally
+associated with a text body and is not part of the regular section
+hierarchy so the normal ordering rules do not apply. Floating titles
+can also be used in contexts where section titles are illegal: for
+example sidebar and admonition blocks. Example:
+
+ [float]
+ The second day
+ ~~~~~~~~~~~~~~
+
+Floating titles do not appear in a document's table of contents.
+
+
+[[X42]]
+Block Titles
+------------
+A 'BlockTitle' element is a single line beginning with a period
+followed by the title text. A BlockTitle is applied to the immediately
+following Paragraph, DelimitedBlock, List, Table or BlockMacro. For
+example:
+
+........................
+.Notes
+- Note 1.
+- Note 2.
+........................
+
+is rendered as:
+
+.Notes
+- Note 1.
+- Note 2.
+
+
+[[X41]]
+BlockId Element
+---------------
+A 'BlockId' is a single line block element containing a unique
+identifier enclosed in double square brackets. It is used to assign an
+identifier to the ensuing block element. For example:
+
+ [[chapter-titles]]
+ Chapter titles can be ...
+
+The preceding example identifies the ensuing paragraph so it can be
+referenced from other locations, for example with
+`<>`.
+
+'BlockId' elements can be applied to Title, Paragraph, List,
+DelimitedBlock, Table and BlockMacro elements. The BlockId element
+sets the `{id}` attribute for substitution in the subsequent block's
+markup template. If a second positional argument is supplied it sets
+the `{reftext}` attribute which is used to set the DocBook `xreflabel`
+attribute.
+
+The 'BlockId' element has the same syntax and serves the same function
+to the <>.
+
+[[X79]]
+AttributeList Element
+---------------------
+An 'AttributeList' block element is an <> on a
+line by itself:
+
+- 'AttributeList' attributes are only applied to the immediately
+ following block element -- the attributes are made available to the
+ block's markup template.
+- Multiple contiguous 'AttributeList' elements are additively combined
+ in the order they appear..
+- The first positional attribute in the list is often used to specify
+ the ensuing element's <>.
+
+Attribute value substitution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default, only substitutions that take place inside attribute list
+values are attribute references, this is because not all attributes
+are destined to be marked up and rendered as text (for example the
+table 'cols' attribute). To perform normal inline text substitutions
+(special characters, quotes, macros, replacements) on an attribute
+value you need to enclose it in single quotes. In the following quote
+block the second attribute value in the AttributeList is quoted to
+ensure the 'http' macro is expanded to a hyperlink.
+
+---------------------------------------------------------------------
+[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
+_____________________________________________________________________
+Sir, a woman's preaching is like a dog's walking on his hind legs. It
+is not done well; but you are surprised to find it done at all.
+_____________________________________________________________________
+---------------------------------------------------------------------
+
+Common attributes
+~~~~~~~~~~~~~~~~~
+Most block elements support the following attributes:
+
+[cols="1e,1,5a",frame="topbot",options="header"]
+|====================================================================
+|Name |Backends |Description
+
+|id |html4, html5, xhtml11, docbook |
+Unique identifier typically serve as link targets.
+Can also be set by the 'BlockId' element.
+
+|role |html4, html5, xhtml11, docbook |
+Role contains a string used to classify or subclassify an element and
+can be applied to AsciiDoc block elements. The AsciiDoc 'role'
+attribute is translated to the 'role' attribute in DocBook outputs and
+is included in the 'class' attribute in HTML outputs, in this respect
+it behaves like the <>.
+
+DocBook XSL Stylesheets translate DocBook 'role' attributes to HTML
+'class' attributes; CSS can then be used
+http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
+generated HTML].
+
+|reftext |docbook |
+'reftext' is used to set the DocBook 'xreflabel' attribute.
+The 'reftext' attribute can an also be set by the 'BlockId' element.
+
+|====================================================================
+
+
+Paragraphs
+----------
+Paragraphs are blocks of text terminated by a blank line, the end of
+file, or the start of a delimited block or a list. There are three
+paragraph syntaxes: normal, indented (literal) and admonition which
+are rendered, by default, with the corresponding paragraph style.
+
+Each syntax has a default style, but you can explicitly apply any
+paragraph style to any paragraph syntax. You can also apply
+<> styles to single paragraphs.
+
+The built-in paragraph styles are: 'normal', 'literal', 'verse',
+'quote', 'listing', 'TIP', 'NOTE', 'IMPORTANT', 'WARNING', 'CAUTION',
+'abstract', 'partintro', 'comment', 'example', 'sidebar', 'source',
+'music', 'latex', 'graphviz'.
+
+normal paragraph syntax
+~~~~~~~~~~~~~~~~~~~~~~~
+Normal paragraph syntax consists of one or more non-blank lines of
+text. The first line must start hard against the left margin (no
+intervening white space). The default processing expectation is that
+of a normal paragraph of text.
+
+[[X85]]
+literal paragraph syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+Literal paragraphs are rendered verbatim in a monospaced font without
+any distinguishing background or border. By default there is no text
+formatting or substitutions within Literal paragraphs apart from
+Special Characters and Callouts.
+
+The 'literal' style is applied implicitly to indented paragraphs i.e.
+where the first line of the paragraph is indented by one or more space
+or tab characters. For example:
+
+---------------------------------------------------------------------
+ Consul *necessitatibus* per id,
+ consetetur, eu pro everti postulant
+ homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+Renders:
+
+ Consul *necessitatibus* per id,
+ consetetur, eu pro everti postulant
+ homero verear ea mea, qui.
+
+NOTE: Because <> can be indented it's possible for your
+indented paragraph to be misinterpreted as a list -- in situations
+like this apply the 'literal' style to a normal paragraph.
+
+Instead of using a paragraph indent you could apply the 'literal'
+style explicitly, for example:
+
+---------------------------------------------------------------------
+[literal]
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+Renders:
+
+[literal]
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+
+[[X94]]
+quote and verse paragraph styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The optional 'attribution' and 'citetitle' attributes (positional
+attributes 2 and 3) specify the author and source respectively.
+
+The 'verse' style retains the line breaks, for example:
+
+---------------------------------------------------------------------
+[verse, William Blake, from Auguries of Innocence]
+To see a world in a grain of sand,
+And a heaven in a wild flower,
+Hold infinity in the palm of your hand,
+And eternity in an hour.
+---------------------------------------------------------------------
+
+Which is rendered as:
+
+[verse, William Blake, from Auguries of Innocence]
+To see a world in a grain of sand,
+And a heaven in a wild flower,
+Hold infinity in the palm of your hand,
+And eternity in an hour.
+
+The 'quote' style flows the text at left and right margins, for
+example:
+
+---------------------------------------------------------------------
+[quote, Bertrand Russell, The World of Mathematics (1956)]
+A good notation has subtlety and suggestiveness which at times makes
+it almost seem like a live teacher.
+---------------------------------------------------------------------
+
+Which is rendered as:
+
+[quote, Bertrand Russell, The World of Mathematics (1956)]
+A good notation has subtlety and suggestiveness which at times makes
+it almost seem like a live teacher.
+
+[[X28]]
+Admonition Paragraphs
+~~~~~~~~~~~~~~~~~~~~~
+'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION' admonishment
+paragraph styles are generated by placing `NOTE:`, `TIP:`,
+`IMPORTANT:`, `WARNING:` or `CAUTION:` as the first word of the
+paragraph. For example:
+
+ NOTE: This is an example note.
+
+Alternatively, you can specify the paragraph admonition style
+explicitly using an <>. For example:
+
+ [NOTE]
+ This is an example note.
+
+Renders:
+
+NOTE: This is an example note.
+
+TIP: If your admonition requires more than a single paragraph use an
+<> instead.
+
+[[X47]]
+Admonition Icons and Captions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+NOTE: Admonition customization with `icons`, `iconsdir`, `icon` and
+`caption` attributes does not apply when generating DocBook output. If
+you are going the DocBook route then the <> `--no-icons`
+and `--icons-dir` options can be used to set the appropriate XSL
+Stylesheets parameters.
+
+By default the asciidoc(1) HTML backends generate text captions
+instead of admonition icon image links. To generate links to icon
+images define the <> attribute, for example using the `-a
+icons` command-line option.
+
+The <> attribute sets the location of linked icon
+images.
+
+You can override the default icon image using the `icon` attribute to
+specify the path of the linked image. For example:
+
+ [icon="./images/icons/wink.png"]
+ NOTE: What lovely war.
+
+Use the `caption` attribute to customize the admonition captions (not
+applicable to `docbook` backend). The following example suppresses the
+icon image and customizes the caption of a 'NOTE' admonition
+(undefining the `icons` attribute with `icons=None` is only necessary
+if <> have been enabled):
+
+ [icons=None, caption="My Special Note"]
+ NOTE: This is my special note.
+
+This subsection also applies to <>.
+
+
+[[X104]]
+Delimited Blocks
+----------------
+Delimited blocks are blocks of text enveloped by leading and trailing
+delimiter lines (normally a series of four or more repeated
+characters). The behavior of Delimited Blocks is specified by entries
+in configuration file `[blockdef-*]` sections.
+
+Predefined Delimited Blocks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc ships with a number of predefined DelimitedBlocks (see the
+`asciidoc.conf` configuration file in the asciidoc(1) program
+directory):
+
+Predefined delimited block underlines:
+
+ CommentBlock: //////////////////////////
+ PassthroughBlock: ++++++++++++++++++++++++++
+ ListingBlock: --------------------------
+ LiteralBlock: ..........................
+ SidebarBlock: **************************
+ QuoteBlock: __________________________
+ ExampleBlock: ==========================
+ OpenBlock: --
+
+.Default DelimitedBlock substitutions
+[cols="2e,7*^",frame="topbot",options="header,autowidth"]
+|=====================================================
+| |Attributes |Callouts |Macros | Quotes |Replacements
+|Special chars |Special words
+
+|PassthroughBlock |Yes |No |Yes |No |No |No |No
+|ListingBlock |No |Yes |No |No |No |Yes |No
+|LiteralBlock |No |Yes |No |No |No |Yes |No
+|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
+|=====================================================
+
+Listing Blocks
+~~~~~~~~~~~~~~
+'ListingBlocks' are rendered verbatim in a monospaced font, they
+retain line and whitespace formatting and are often distinguished by a
+background or border. There is no text formatting or substitutions
+within Listing blocks apart from Special Characters and Callouts.
+Listing blocks are often used for computer output and file listings.
+
+Here's an example:
+
+[listing]
+......................................
+--------------------------------------
+#include
+
+int main() {
+ printf("Hello World!\n");
+ exit(0);
+}
+--------------------------------------
+......................................
+
+Which will be rendered like:
+
+--------------------------------------
+#include
+
+int main() {
+ printf("Hello World!\n");
+ exit(0);
+}
+--------------------------------------
+
+By convention <> use the listing block syntax and
+are implemented as distinct listing block styles.
+
+[[X65]]
+Literal Blocks
+~~~~~~~~~~~~~~
+'LiteralBlocks' are rendered just like <>.
+Example:
+
+---------------------------------------------------------------------
+...................................
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+...................................
+---------------------------------------------------------------------
+
+Renders:
+...................................
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+...................................
+
+If the 'listing' style is applied to a LiteralBlock it will be
+rendered as a ListingBlock (this is handy if you have a listing
+containing a ListingBlock).
+
+Sidebar Blocks
+~~~~~~~~~~~~~~
+A sidebar is a short piece of text presented outside the narrative
+flow of the main text. The sidebar is normally presented inside a
+bordered box to set it apart from the main text.
+
+The sidebar body is treated like a normal section body.
+
+Here's an example:
+
+---------------------------------------------------------------------
+.An Example Sidebar
+************************************************
+Any AsciiDoc SectionBody element (apart from
+SidebarBlocks) can be placed inside a sidebar.
+************************************************
+---------------------------------------------------------------------
+
+Which will be rendered like:
+
+.An Example Sidebar
+************************************************
+Any AsciiDoc SectionBody element (apart from
+SidebarBlocks) can be placed inside a sidebar.
+************************************************
+
+[[X26]]
+Comment Blocks
+~~~~~~~~~~~~~~
+The contents of 'CommentBlocks' are not processed; they are useful for
+annotations and for excluding new or outdated content that you don't
+want displayed. CommentBlocks are never written to output files.
+Example:
+
+---------------------------------------------------------------------
+//////////////////////////////////////////
+CommentBlock contents are not processed by
+asciidoc(1).
+//////////////////////////////////////////
+---------------------------------------------------------------------
+
+See also <>.
+
+NOTE: System macros are executed inside comment blocks.
+
+[[X76]]
+Passthrough Blocks
+~~~~~~~~~~~~~~~~~~
+By default the block contents is subject only to 'attributes' and
+'macros' substitutions (use an explicit 'subs' attribute to apply
+different substitutions). PassthroughBlock content will often be
+backend specific. Here's an example:
+
+---------------------------------------------------------------------
+[subs="quotes"]
+++++++++++++++++++++++++++++++++++++++
+
+++++++++++++++++++++++++++++++++++++++
+---------------------------------------------------------------------
+
+The following styles can be applied to passthrough blocks:
+
+pass::
+ No substitutions are performed. This is equivalent to `subs="none"`.
+
+asciimath, latexmath::
+ By default no substitutions are performed, the contents are rendered
+ as <>.
+
+Quote Blocks
+~~~~~~~~~~~~
+'QuoteBlocks' are used for quoted passages of text. There are two
+styles: 'quote' and 'verse'. The style behavior is identical to
+<> except that blocks can contain
+multiple paragraphs and, in the case of the 'quote' style, other
+section elements. The first positional attribute sets the style, if
+no attributes are specified the 'quote' style is used. The optional
+'attribution' and 'citetitle' attributes (positional attributes 2 and
+3) specify the quote's author and source. For example:
+
+---------------------------------------------------------------------
+[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
+____________________________________________________________________
+As he spoke there was the sharp sound of horses' hoofs and
+grating wheels against the curb, followed by a sharp pull at the
+bell. Holmes whistled.
+
+"A pair, by the sound," said he. "Yes," he continued, glancing
+out of the window. "A nice little brougham and a pair of
+beauties. A hundred and fifty guineas apiece. There's money in
+this case, Watson, if there is nothing else."
+____________________________________________________________________
+---------------------------------------------------------------------
+
+Which is rendered as:
+
+[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
+____________________________________________________________________
+As he spoke there was the sharp sound of horses' hoofs and
+grating wheels against the curb, followed by a sharp pull at the
+bell. Holmes whistled.
+
+"A pair, by the sound," said he. "Yes," he continued, glancing
+out of the window. "A nice little brougham and a pair of
+beauties. A hundred and fifty guineas apiece. There's money in
+this case, Watson, if there is nothing else."
+____________________________________________________________________
+
+[[X48]]
+Example Blocks
+~~~~~~~~~~~~~~
+'ExampleBlocks' encapsulate the DocBook Example element and are used
+for, well, examples. Example blocks can be titled by preceding them
+with a 'BlockTitle'. DocBook toolchains will normally automatically
+number examples and generate a 'List of Examples' backmatter section.
+
+Example blocks are delimited by lines of equals characters and can
+contain any block elements apart from Titles, BlockTitles and
+Sidebars) inside an example block. For example:
+
+---------------------------------------------------------------------
+.An example
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+=====================================================================
+---------------------------------------------------------------------
+
+Renders:
+
+.An example
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+=====================================================================
+
+A title prefix that can be inserted with the `caption` attribute
+(HTML backends). For example:
+
+---------------------------------------------------------------------
+[caption="Example 1: "]
+.An example with a custom caption
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+=====================================================================
+---------------------------------------------------------------------
+
+[[X22]]
+Admonition Blocks
+~~~~~~~~~~~~~~~~~
+The 'ExampleBlock' definition includes a set of admonition
+<> ('NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION') for
+generating admonition blocks (admonitions containing more than a
+<>). Just precede the 'ExampleBlock' with an
+attribute list specifying the admonition style name. For example:
+
+---------------------------------------------------------------------
+[NOTE]
+.A NOTE admonition block
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+
+. Fusce euismod commodo velit.
+. Vivamus fringilla mi eu lacus.
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+. Donec eget arcu bibendum
+ nunc consequat lobortis.
+=====================================================================
+---------------------------------------------------------------------
+
+Renders:
+
+[NOTE]
+.A NOTE admonition block
+=====================================================================
+Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+adolescens.
+
+. Fusce euismod commodo velit.
+. Vivamus fringilla mi eu lacus.
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+. Donec eget arcu bibendum
+ nunc consequat lobortis.
+=====================================================================
+
+See also <>.
+
+[[X29]]
+Open Blocks
+~~~~~~~~~~~
+Open blocks are special:
+
+- The open block delimiter is line containing two hyphen characters
+ (instead of four or more repeated characters).
+
+- They can be used to group block elements for <>.
+
+- Open blocks can be styled to behave like any other type of delimited
+ block. The following built-in styles can be applied to open
+ blocks: 'literal', 'verse', 'quote', 'listing', 'TIP', 'NOTE',
+ 'IMPORTANT', 'WARNING', 'CAUTION', 'abstract', 'partintro',
+ 'comment', 'example', 'sidebar', 'source', 'music', 'latex',
+ 'graphviz'. For example, the following open block and listing block
+ are functionally identical:
+
+ [listing]
+ --
+ Lorum ipsum ...
+ --
+
+ ---------------
+ Lorum ipsum ...
+ ---------------
+
+- An unstyled open block groups section elements but otherwise does
+ nothing.
+
+Open blocks are used to generate document abstracts and book part
+introductions:
+
+- Apply the 'abstract' style to generate an abstract, for example:
+
+ [abstract]
+ --
+ In this paper we will ...
+ --
+
+. Apply the 'partintro' style to generate a book part introduction for
+ a multi-part book, for example:
+
+ [partintro]
+ .Optional part introduction title
+ --
+ Optional part introduction goes here.
+ --
+
+
+[[X64]]
+Lists
+-----
+.List types
+- Bulleted lists. Also known as itemized or unordered lists.
+- Numbered lists. Also called ordered lists.
+- Labeled lists. Sometimes called variable or definition lists.
+- Callout lists (a list of callout annotations).
+
+.List behavior
+- List item indentation is optional and does not determine nesting,
+ indentation does however make the source more readable.
+- Another list or a literal paragraph immediately following a list
+ item will be implicitly included in the list item; use <> to explicitly append other block elements to a
+ list item.
+- A comment block or a comment line block macro element will terminate
+ a list -- use inline comment lines to put comments inside lists.
+- The `listindex` <> is the current list item
+ index (1..). If this attribute is used outside a list then it's value
+ is the number of items in the most recently closed list. Useful for
+ displaying the number of items in a list.
+
+Bulleted Lists
+~~~~~~~~~~~~~~
+Bulleted list items start with a single dash or one to five asterisks
+followed by some white space then some text. Bulleted list syntaxes
+are:
+
+...................
+- List item.
+* List item.
+** List item.
+*** List item.
+**** List item.
+***** List item.
+...................
+
+Numbered Lists
+~~~~~~~~~~~~~~
+List item numbers are explicit or implicit.
+
+.Explicit numbering
+List items begin with a number followed by some white space then the
+item text. The numbers can be decimal (arabic), roman (upper or lower
+case) or alpha (upper or lower case). Decimal and alpha numbers are
+terminated with a period, roman numbers are terminated with a closing
+parenthesis. The different terminators are necessary to ensure 'i',
+'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and
+'x' alpha numbers. Examples:
+
+.....................................................................
+1. Arabic (decimal) numbered list item.
+a. Lower case alpha (letter) numbered list item.
+F. Upper case alpha (letter) numbered list item.
+iii) Lower case roman numbered list item.
+IX) Upper case roman numbered list item.
+.....................................................................
+
+.Implicit numbering
+List items begin one to five period characters, followed by some white
+space then the item text. Examples:
+
+.....................................................................
+. Arabic (decimal) numbered list item.
+.. Lower case alpha (letter) numbered list item.
+... Lower case roman numbered list item.
+.... Upper case alpha (letter) numbered list item.
+..... Upper case roman numbered list item.
+.....................................................................
+
+You can use the 'style' attribute (also the first positional
+attribute) to specify an alternative numbering style. The numbered
+list style can be one of the following values: 'arabic', 'loweralpha',
+'upperalpha', 'lowerroman', 'upperroman'.
+
+Here are some examples of bulleted and numbered lists:
+
+---------------------------------------------------------------------
+- Praesent eget purus quis magna eleifend eleifend.
+ 1. Fusce euismod commodo velit.
+ a. Fusce euismod commodo velit.
+ b. Vivamus fringilla mi eu lacus.
+ c. Donec eget arcu bibendum nunc consequat lobortis.
+ 2. Vivamus fringilla mi eu lacus.
+ i) Fusce euismod commodo velit.
+ ii) Vivamus fringilla mi eu lacus.
+ 3. Donec eget arcu bibendum nunc consequat lobortis.
+ 4. Nam fermentum mattis ante.
+- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ * Fusce euismod commodo velit.
+ ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+ adolescens. Sit munere ponderum dignissim et. Minim luptatum et
+ vel.
+ ** Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+- Nulla porttitor vulputate libero.
+ . Fusce euismod commodo velit.
+ . Vivamus fringilla mi eu lacus.
+[upperroman]
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+ . Donec eget arcu bibendum nunc consequat lobortis.
+---------------------------------------------------------------------
+
+Which render as:
+
+- Praesent eget purus quis magna eleifend eleifend.
+ 1. Fusce euismod commodo velit.
+ a. Fusce euismod commodo velit.
+ b. Vivamus fringilla mi eu lacus.
+ c. Donec eget arcu bibendum nunc consequat lobortis.
+ 2. Vivamus fringilla mi eu lacus.
+ i) Fusce euismod commodo velit.
+ ii) Vivamus fringilla mi eu lacus.
+ 3. Donec eget arcu bibendum nunc consequat lobortis.
+ 4. Nam fermentum mattis ante.
+- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ * Fusce euismod commodo velit.
+ ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
+ adolescens. Sit munere ponderum dignissim et. Minim luptatum et
+ vel.
+ ** Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+- Nulla porttitor vulputate libero.
+ . Fusce euismod commodo velit.
+ . Vivamus fringilla mi eu lacus.
+[upperroman]
+ .. Fusce euismod commodo velit.
+ .. Vivamus fringilla mi eu lacus.
+ . Donec eget arcu bibendum nunc consequat lobortis.
+
+A predefined 'compact' option is available to bulleted and numbered
+lists -- this translates to the DocBook 'spacing="compact"' lists
+attribute which may or may not be processed by the DocBook toolchain.
+Example:
+
+ [options="compact"]
+ - Compact list item.
+ - Another compact list item.
+
+TIP: To apply the 'compact' option globally define a document-wide
+'compact-option' attribute, e.g. using the `-a compact-option`
+command-line option.
+
+You can set the list start number using the 'start' attribute (works
+for HTML outputs and DocBook outputs processed by DocBook XSL
+Stylesheets). Example:
+
+ [start=7]
+ . List item 7.
+ . List item 8.
+
+Labeled Lists
+~~~~~~~~~~~~~
+Labeled list items consist of one or more text labels followed by the
+text of the list item.
+
+An item label begins a line with an alphanumeric character hard
+against the left margin and ends with two, three or four colons or two
+semi-colons. A list item can have multiple labels, one per line.
+
+The list item text consists of one or more lines of text starting
+after the last label (either on the same line or a new line) and can
+be followed by nested List or ListParagraph elements. Item text can be
+optionally indented.
+
+Here are some examples:
+
+---------------------------------------------------------------------
+In::
+Lorem::
+ Fusce euismod commodo velit.
+
+ Fusce euismod commodo velit.
+
+Ipsum:: Vivamus fringilla mi eu lacus.
+ * Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+Dolor::
+ Donec eget arcu bibendum nunc consequat lobortis.
+ Suspendisse;;
+ A massa id sem aliquam auctor.
+ Morbi;;
+ Pretium nulla vel lorem.
+ In;;
+ Dictum mauris in urna.
+ Vivamus::: Fringilla mi eu lacus.
+ Donec::: Eget arcu bibendum nunc consequat lobortis.
+---------------------------------------------------------------------
+
+Which render as:
+
+In::
+Lorem::
+ Fusce euismod commodo velit.
+
+ Fusce euismod commodo velit.
+
+Ipsum:: Vivamus fringilla mi eu lacus.
+ * Vivamus fringilla mi eu lacus.
+ * Donec eget arcu bibendum nunc consequat lobortis.
+Dolor::
+ Donec eget arcu bibendum nunc consequat lobortis.
+ Suspendisse;;
+ A massa id sem aliquam auctor.
+ Morbi;;
+ Pretium nulla vel lorem.
+ In;;
+ Dictum mauris in urna.
+ Vivamus::: Fringilla mi eu lacus.
+ Donec::: Eget arcu bibendum nunc consequat lobortis.
+
+Horizontal labeled list style
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The 'horizontal' labeled list style (also the first positional
+attribute) places the list text side-by-side with the label instead of
+under the label. Here is an example:
+
+---------------------------------------------------------------------
+[horizontal]
+*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
+labitur dolorum an. Est ne magna primis adolescens.
+
+ Fusce euismod commodo velit.
+
+*Ipsum*:: Vivamus fringilla mi eu lacus.
+- Vivamus fringilla mi eu lacus.
+- Donec eget arcu bibendum nunc consequat lobortis.
+
+*Dolor*::
+ - Vivamus fringilla mi eu lacus.
+ - Donec eget arcu bibendum nunc consequat lobortis.
+
+---------------------------------------------------------------------
+
+Which render as:
+
+[horizontal]
+*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
+labitur dolorum an. Est ne magna primis adolescens.
+
+ Fusce euismod commodo velit.
+
+*Ipsum*:: Vivamus fringilla mi eu lacus.
+- Vivamus fringilla mi eu lacus.
+- Donec eget arcu bibendum nunc consequat lobortis.
+
+*Dolor*::
+ - Vivamus fringilla mi eu lacus.
+ - Donec eget arcu bibendum nunc consequat lobortis.
+
+[NOTE]
+=====================================================================
+- Current PDF toolchains do not make a good job of determining
+ the relative column widths for horizontal labeled lists.
+- Nested horizontal labeled lists will generate DocBook validation
+ errors because the 'DocBook XML V4.2' DTD does not permit nested
+ informal tables (although <> and
+ <> process them correctly).
+- The label width can be set as a percentage of the total width by
+ setting the 'width' attribute e.g. `width="10%"`
+=====================================================================
+
+Question and Answer Lists
+~~~~~~~~~~~~~~~~~~~~~~~~~
+AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating
+DocBook question and answer (Q&A) lists. Example:
+
+---------------------------------------------------------------------
+[qanda]
+Question one::
+ Answer one.
+Question two::
+ Answer two.
+---------------------------------------------------------------------
+
+Renders:
+
+[qanda]
+Question one::
+ Answer one.
+Question two::
+ Answer two.
+
+Glossary Lists
+~~~~~~~~~~~~~~
+AsciiDoc comes pre-configured with a 'glossary' style labeled list for
+generating DocBook glossary lists. Example:
+
+---------------------------------------------------------------------
+[glossary]
+A glossary term::
+ The corresponding definition.
+A second glossary term::
+ The corresponding definition.
+---------------------------------------------------------------------
+
+For working examples see the `article.txt` and `book.txt` documents in
+the AsciiDoc `./doc` distribution directory.
+
+NOTE: To generate valid DocBook output glossary lists must be located
+in a section that uses the 'glossary' <>.
+
+Bibliography Lists
+~~~~~~~~~~~~~~~~~~
+AsciiDoc comes with a predefined 'bibliography' bulleted list style
+generating DocBook bibliography entries. Example:
+
+---------------------------------------------------------------------
+[bibliography]
+.Optional list title
+- [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
+ Programming'. Addison-Wesley. ISBN 0-13-142901-9.
+- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
+ 'DocBook - The Definitive Guide'. O'Reilly & Associates.
+ 1999. ISBN 1-56592-580-7.
+---------------------------------------------------------------------
+
+The `[[[]]]` syntax is a bibliography entry anchor, it
+generates an anchor named `` and additionally displays
+`[]` at the anchor position. For example `[[[taoup]]]`
+generates an anchor named `taoup` that displays `[taoup]` at the
+anchor position. Cite the reference from elsewhere your document using
+`<>`, this displays a hyperlink (`[taoup]`) to the
+corresponding bibliography entry anchor.
+
+For working examples see the `article.txt` and `book.txt` documents in
+the AsciiDoc `./doc` distribution directory.
+
+NOTE: To generate valid DocBook output bibliography lists must be
+located in a <>.
+
+[[X15]]
+List Item Continuation
+~~~~~~~~~~~~~~~~~~~~~~
+Another list or a literal paragraph immediately following a list item
+is implicitly appended to the list item; to append other block
+elements to a list item you need to explicitly join them to the list
+item with a 'list continuation' (a separator line containing a single
+plus character). Multiple block elements can be appended to a list
+item using list continuations (provided they are legal list item
+children in the backend markup).
+
+Here are some examples of list item continuations: list item one
+contains multiple continuations; list item two is continued with an
+<> containing multiple elements:
+
+---------------------------------------------------------------------
+1. List item one.
++
+List item one continued with a second paragraph followed by an
+Indented block.
++
+.................
+$ ls *.sh
+$ mv *.sh ~/tmp
+.................
++
+List item continued with a third paragraph.
+
+2. List item two continued with an open block.
++
+--
+This paragraph is part of the preceding list item.
+
+a. This list is nested and does not require explicit item continuation.
++
+This paragraph is part of the preceding list item.
+
+b. List item b.
+
+This paragraph belongs to item two of the outer list.
+--
+---------------------------------------------------------------------
+
+Renders:
+
+1. List item one.
++
+List item one continued with a second paragraph followed by an
+Indented block.
++
+.................
+$ ls *.sh
+$ mv *.sh ~/tmp
+.................
++
+List item continued with a third paragraph.
+
+2. List item two continued with an open block.
++
+--
+This paragraph is part of the preceding list item.
+
+a. This list is nested and does not require explicit item continuation.
++
+This paragraph is part of the preceding list item.
+
+b. List item b.
+
+This paragraph belongs to item two of the outer list.
+--
+
+
+[[X92]]
+Footnotes
+---------
+The shipped AsciiDoc configuration includes three footnote inline
+macros:
+
+`footnote:[]`::
+ Generates a footnote with text ``.
+
+`footnoteref:[,]`::
+ Generates a footnote with a reference ID `` and text ``.
+
+`footnoteref:[]`::
+ Generates a reference to the footnote with ID ``.
+
+The footnote text can span multiple lines.
+
+The 'xhtml11' and 'html5' backends render footnotes dynamically using
+JavaScript; 'html4' outputs do not use JavaScript and leave the
+footnotes inline; 'docbook' footnotes are processed by the downstream
+DocBook toolchain.
+
+Example footnotes:
+
+ A footnote footnote:[An example footnote.];
+ a second footnote with a reference ID footnoteref:[note2,Second footnote.];
+ finally a reference to the second footnote footnoteref:[note2].
+
+Renders:
+
+A footnote footnote:[An example footnote.];
+a second footnote with a reference ID footnoteref:[note2,Second footnote.];
+finally a reference to the second footnote footnoteref:[note2].
+
+
+Indexes
+-------
+The shipped AsciiDoc configuration includes the inline macros for
+generating DocBook index entries.
+
+`indexterm:[,,]`::
+`(((,,)))`::
+ This inline macro generates an index term (the `` and
+ `` positional attributes are optional). Example:
+ `indexterm:[Tigers,Big cats]` (or, using the alternative syntax
+ `(((Tigers,Big cats)))`. Index terms that have secondary and
+ tertiary entries also generate separate index terms for the
+ secondary and tertiary entries. The index terms appear in the
+ index, not the primary text flow.
+
+`indexterm2:[]`::
+`(())`::
+ This inline macro generates an index term that appears in both the
+ index and the primary text flow. The `` should not be
+ padded to the left or right with white space characters.
+
+For working examples see the `article.txt` and `book.txt` documents in
+the AsciiDoc `./doc` distribution directory.
+
+NOTE: Index entries only really make sense if you are generating
+DocBook markup -- DocBook conversion programs automatically generate
+an index at the point an 'Index' section appears in source document.
+
+
+[[X105]]
+Callouts
+--------
+Callouts are a mechanism for annotating verbatim text (for example:
+source code, computer output and user input). Callout markers are
+placed inside the annotated text while the actual annotations are
+presented in a callout list after the annotated text. Here's an
+example:
+
+---------------------------------------------------------------------
+ .MS-DOS directory listing
+ -----------------------------------------------------
+ 10/17/97 9:04 bin
+ 10/16/97 14:11 DOS \<1>
+ 10/16/97 14:40 Program Files
+ 10/16/97 14:46 TEMP
+ 10/17/97 9:04 tmp
+ 10/16/97 14:37 WINNT
+ 10/16/97 14:25 119 AUTOEXEC.BAT \<2>
+ 2/13/94 6:21 54,619 COMMAND.COM \<2>
+ 10/16/97 14:25 115 CONFIG.SYS \<2>
+ 11/16/97 17:17 61,865,984 pagefile.sys
+ 2/13/94 6:21 9,349 WINA20.386 \<3>
+ -----------------------------------------------------
+
+ \<1> This directory holds MS-DOS.
+ \<2> System startup code for DOS.
+ \<3> Some sort of Windows 3.1 hack.
+---------------------------------------------------------------------
+
+Which renders:
+
+.MS-DOS directory listing
+-----------------------------------------------------
+10/17/97 9:04 bin
+10/16/97 14:11 DOS <1>
+10/16/97 14:40 Program Files
+10/16/97 14:46 TEMP
+10/17/97 9:04 tmp
+10/16/97 14:37 WINNT
+10/16/97 14:25 119 AUTOEXEC.BAT <2>
+ 2/13/94 6:21 54,619 COMMAND.COM <2>
+10/16/97 14:25 115 CONFIG.SYS <2>
+11/16/97 17:17 61,865,984 pagefile.sys
+ 2/13/94 6:21 9,349 WINA20.386 <3>
+-----------------------------------------------------
+
+<1> This directory holds MS-DOS.
+<2> System startup code for DOS.
+<3> Some sort of Windows 3.1 hack.
+
+.Explanation
+- The callout marks are whole numbers enclosed in angle brackets --
+ they refer to the correspondingly numbered item in the following
+ callout list.
+- By default callout marks are confined to 'LiteralParagraphs',
+ 'LiteralBlocks' and 'ListingBlocks' (although this is a
+ configuration file option and can be changed).
+- Callout list item numbering is fairly relaxed -- list items can
+ start with ``, `n>` or `>` where `n` is the optional list item
+ number (in the latter case list items starting with a single `>`
+ character are implicitly numbered starting at one).
+- Callout lists should not be nested.
+- Callout lists start list items hard against the left margin.
+- If you want to present a number inside angle brackets you'll need to
+ escape it with a backslash to prevent it being interpreted as a
+ callout mark.
+
+NOTE: Define the AsciiDoc 'icons' attribute (for example using the `-a
+icons` command-line option) to display callout icons.
+
+Implementation Notes
+~~~~~~~~~~~~~~~~~~~~
+Callout marks are generated by the 'callout' inline macro while
+callout lists are generated using the 'callout' list definition. The
+'callout' macro and 'callout' list are special in that they work
+together. The 'callout' inline macro is not enabled by the normal
+'macros' substitutions option, instead it has its own 'callouts'
+substitution option.
+
+The following attributes are available during inline callout macro
+substitution:
+
+`{index}`::
+ The callout list item index inside the angle brackets.
+`{coid}`::
+ An identifier formatted like `CO-` that
+ uniquely identifies the callout mark. For example `CO2-4`
+ identifies the fourth callout mark in the second set of callout
+ marks.
+
+The `{coids}` attribute can be used during callout list item
+substitution -- it is a space delimited list of callout IDs that refer
+to the explanatory list item.
+
+Including callouts in included code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can annotate working code examples with callouts -- just remember
+to put the callouts inside source code comments. This example displays
+the `test.py` source file (containing a single callout) using the
+'source' (code highlighter) filter:
+
+.AsciiDoc source
+---------------------------------------------------------------------
+ [source,python]
+ -------------------------------------------
+ \include::test.py[]
+ -------------------------------------------
+
+ \<1> Print statement.
+---------------------------------------------------------------------
+
+.Included `test.py` source
+---------------------------------------------------------------------
+print 'Hello World!' # \<1>
+---------------------------------------------------------------------
+
+
+Macros
+------
+Macros are a mechanism for substituting parametrized text into output
+documents.
+
+Macros have a 'name', a single 'target' argument and an 'attribute
+list'. The usual syntax is `:[]` (for
+inline macros) and `::[]` (for block
+macros). Here are some examples:
+
+ http://www.docbook.org/[DocBook.org]
+ include::chapt1.txt[tabsize=2]
+ mailto:srackham@gmail.com[]
+
+.Macro behavior
+- `` is the macro name. It can only contain letters, digits or
+ dash characters and cannot start with a dash.
+- The optional `` cannot contain white space characters.
+- `` is a <> enclosed in square
+ brackets.
+- `]` characters inside attribute lists must be escaped with a
+ backslash.
+- Expansion of macro references can normally be escaped by prefixing a
+ backslash character (see the AsciiDoc 'FAQ' for examples of
+ exceptions to this rule).
+- Attribute references in block macros are expanded.
+- The substitutions performed prior to Inline macro macro expansion
+ are determined by the inline context.
+- Macros are processed in the order they appear in the configuration
+ file(s).
+- Calls to inline macros can be nested inside different inline macros
+ (an inline macro call cannot contain a nested call to itself).
+- In addition to ``, `` and `` the
+ `` and `` named groups are available to
+ <>. A macro is a passthrough macro if the
+ definition includes a `` named group.
+
+Inline Macros
+~~~~~~~~~~~~~
+Inline Macros occur in an inline element context. Predefined Inline
+macros include 'URLs', 'image' and 'link' macros.
+
+URLs
+^^^^
+'http', 'https', 'ftp', 'file', 'mailto' and 'callto' URLs are
+rendered using predefined inline macros.
+
+- If you don't need a custom link caption you can enter the 'http',
+ 'https', 'ftp', 'file' URLs and email addresses without any special
+ macro syntax.
+- If the `` is empty the URL is displayed.
+
+Here are some examples:
+
+ http://www.docbook.org/[DocBook.org]
+ http://www.docbook.org/
+ mailto:joe.bloggs@foobar.com[email Joe Bloggs]
+ joe.bloggs@foobar.com
+
+Which are rendered:
+
+http://www.docbook.org/[DocBook.org]
+
+http://www.docbook.org/
+
+mailto:joe.bloggs@foobar.com[email Joe Bloggs]
+
+joe.bloggs@foobar.com
+
+If the `` necessitates space characters use `%20`, for example
+`large%20image.png`.
+
+Internal Cross References
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Two AsciiDoc inline macros are provided for creating hypertext links
+within an AsciiDoc document. You can use either the standard macro
+syntax or the (preferred) alternative.
+
+[[X30]]
+anchor
+++++++
+Used to specify hypertext link targets:
+
+ [[,]]
+ anchor:[]
+
+The `` is a unique string that conforms to the output markup's
+anchor syntax. The optional `` is the text to be displayed
+by captionless 'xref' macros that refer to this anchor. The optional
+`` is only really useful when generating DocBook output.
+Example anchor:
+
+ [[X1]]
+
+You may have noticed that the syntax of this inline element is the
+same as that of the <>, this is no
+coincidence since they are functionally equivalent.
+
+xref
+++++
+Creates a hypertext link to a document anchor.
+
+ <<,>>
+ xref:[]
+
+The `` refers to an anchor ID. The optional `` is the
+link's displayed text. Example:
+
+ <>
+
+If `` is not specified then the displayed text is
+auto-generated:
+
+- The AsciiDoc 'xhtml11' and 'html5' backends display the ``
+ enclosed in square brackets.
+- If DocBook is produced the DocBook toolchain is responsible for the
+ displayed text which will normally be the referenced figure, table
+ or section title number followed by the element's title text.
+
+Here is an example:
+
+---------------------------------------------------------------------
+[[tiger_image]]
+.Tyger tyger
+image::tiger.png[]
+
+This can be seen in <>.
+---------------------------------------------------------------------
+
+Linking to Local Documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Hypertext links to files on the local file system are specified using
+the 'link' inline macro.
+
+ link:[]
+
+The 'link' macro generates relative URLs. The link macro `` is
+the target file name (relative to the file system location of the
+referring document). The optional `` is the link's displayed
+text. If `` is not specified then `` is displayed.
+Example:
+
+ link:downloads/foo.zip[download foo.zip]
+
+You can use the `#` syntax to refer to an anchor within
+a target document but this usually only makes sense when targeting
+HTML documents.
+
+[[X9]]
+Images
+^^^^^^
+Inline images are inserted into the output document using the 'image'
+macro. The inline syntax is:
+
+ image:[]
+
+The contents of the image file `` is displayed. To display the
+image its file format must be supported by the target backend
+application. HTML and DocBook applications normally support PNG or JPG
+files.
+
+`` file name paths are relative to the location of the
+referring document.
+
+[[X55]]
+.Image macro attributes
+- The optional 'alt' attribute is also the first positional attribute,
+ it specifies alternative text which is displayed if the output
+ application is unable to display the image file (see also
+ http://htmlhelp.com/feature/art3.htm[Use of ALT texts in IMGs]). For
+ example:
+
+ image:images/logo.png[Company Logo]
+
+- The optional 'title' attribute provides a title for the image. The
+ <> renders the title alongside the image.
+ The inline image macro displays the title as a popup ``tooltip'' in
+ visual browsers (AsciiDoc HTML outputs only).
+
+- The optional `width` and `height` attributes scale the image size
+ and can be used in any combination. The units are pixels. The
+ following example scales the previous example to a height of 32
+ pixels:
+
+ image:images/logo.png["Company Logo",height=32]
+
+- The optional `link` attribute is used to link the image to an
+ external document. The following example links a screenshot
+ thumbnail to a full size version:
+
+ image:screen-thumbnail.png[height=32,link="screen.png"]
+
+- The optional `scaledwidth` attribute is only used in DocBook block
+ images (specifically for PDF documents). The following example
+ scales the images to 75% of the available print width:
+
+ image::images/logo.png[scaledwidth="75%",alt="Company Logo"]
+
+- The image `scale` attribute sets the DocBook `imagedata` element
+ `scale` attribute.
+
+- The optional `align` attribute is used for horizontal image
+ alignment. Allowed values are `center`, `left` and `right`. For
+ example:
+
+ image::images/tiger.png["Tiger image",align="left"]
+
+- The optional `float` attribute floats the image `left` or `right` on
+ the page (works with HTML outputs only, has no effect on DocBook
+ outputs). `float` and `align` attributes are mutually exclusive.
+ Use the `unfloat::[]` block macro to stop floating.
+
+Comment Lines
+^^^^^^^^^^^^^
+See <>.
+
+Block Macros
+~~~~~~~~~~~~
+A Block macro reference must be contained in a single line separated
+either side by a blank line or a block delimiter.
+
+Block macros behave just like Inline macros, with the following
+differences:
+
+- They occur in a block context.
+- The default syntax is `::[]` (two
+ colons, not one).
+- Markup template section names end in `-blockmacro` instead of
+ `-inlinemacro`.
+
+Block Identifier
+^^^^^^^^^^^^^^^^
+The Block Identifier macro sets the `id` attribute and has the same
+syntax as the <> since it performs
+essentially the same function -- block templates use the `id`
+attribute as a block element ID. For example:
+
+ [[X30]]
+
+This is equivalent to the `[id="X30"]` <>).
+
+[[X49]]
+Images
+^^^^^^
+The 'image' block macro is used to display images in a block context.
+The syntax is:
+
+ image::[]
+
+The block `image` macro has the same <> as it's
+<> counterpart.
+
+Block images can be titled by preceding the 'image' macro with a
+'BlockTitle'. DocBook toolchains normally number titled block images
+and optionally list them in an automatically generated 'List of
+Figures' backmatter section.
+
+This example:
+
+ .Main circuit board
+ image::images/layout.png[J14P main circuit board]
+
+is equivalent to:
+
+ image::images/layout.png["J14P main circuit board",
+ title="Main circuit board"]
+
+A title prefix that can be inserted with the `caption` attribute
+(HTML backends). For example:
+
+ .Main circuit board
+ [caption="Figure 2: "]
+ image::images/layout.png[J14P main circuit board]
+
+[[X66]]
+.Embedding images in XHTML documents
+*********************************************************************
+If you define the `data-uri` attribute then images will be embedded in
+XHTML outputs using the
+http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme]. You
+can use the 'data-uri' attribute with the 'xhtml11' and 'html5'
+backends to produce single-file XHTML documents with embedded images
+and CSS, for example:
+
+ $ asciidoc -a data-uri mydocument.txt
+
+[NOTE]
+======
+- All current popular browsers support data URIs, although versions
+ of Internet Explorer prior to version 8 do not.
+- Some browsers limit the size of data URIs.
+======
+*********************************************************************
+
+[[X25]]
+Comment Lines
+^^^^^^^^^^^^^
+Single lines starting with two forward slashes hard up against the
+left margin are treated as comments. Comment lines do not appear in
+the output unless the 'showcomments' attribute is defined. Comment
+lines have been implemented as both block and inline macros so a
+comment line can appear as a stand-alone block or within block elements
+that support inline macro expansion. Example comment line:
+
+ // This is a comment.
+
+If the 'showcomments' attribute is defined comment lines are written
+to the output:
+
+- In DocBook the comment lines are enclosed by the 'remark' element
+ (which may or may not be rendered by your toolchain).
+- The 'showcomments' attribute does not expose <>.
+ Comment Blocks are never passed to the output.
+
+System Macros
+~~~~~~~~~~~~~
+System macros are block macros that perform a predefined task and are
+hardwired into the asciidoc(1) program.
+
+- You can escape system macros with a leading backslash character
+ (as you can with other macros).
+- The syntax and tasks performed by system macros is built into
+ asciidoc(1) so they don't appear in configuration files. You can
+ however customize the syntax by adding entries to a configuration
+ file `[macros]` section.
+
+[[X63]]
+Include Macros
+^^^^^^^^^^^^^^
+The `include` and `include1` system macros to include the contents of
+a named file into the source document.
+
+The `include` macro includes a file as if it were part of the parent
+document -- tabs are expanded and system macros processed. The
+contents of `include1` files are not subject to tab expansion or
+system macro processing nor are attribute or lower priority
+substitutions performed. The `include1` macro's intended use is to
+include verbatim embedded CSS or scripts into configuration file
+headers. Example:
+
+------------------------------------
+\include::chapter1.txt[tabsize=4]
+------------------------------------
+
+.Include macro behavior
+- If the included file name is specified with a relative path then the
+ path is relative to the location of the referring document.
+- Include macros can appear inside configuration files.
+- Files included from within 'DelimitedBlocks' are read to completion
+ to avoid false end-of-block underline termination.
+- Attribute references are expanded inside the include 'target'; if an
+ attribute is undefined then the included file is silently skipped.
+- The 'tabsize' macro attribute sets the number of space characters to
+ be used for tab expansion in the included file (not applicable to
+ `include1` macro).
+- The 'depth' macro attribute sets the maximum permitted number of
+ subsequent nested includes (not applicable to `include1` macro which
+ does not process nested includes). Setting 'depth' to '1' disables
+ nesting inside the included file. By default, nesting is limited to
+ a depth of ten.
+- If the he 'warnings' attribute is set to 'False' (or any other
+ Python literal that evaluates to boolean false) then no warning
+ message is printed if the included file does not exist. By default
+ 'warnings' are enabled.
+- Internally the `include1` macro is translated to the `include1`
+ system attribute which means it must be evaluated in a region where
+ attribute substitution is enabled. To inhibit nested substitution in
+ included files it is preferable to use the `include` macro and set
+ the attribute `depth=1`.
+
+Conditional Inclusion Macros
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Lines of text in the source document can be selectively included or
+excluded from processing based on the existence (or not) of a document
+attribute.
+
+Document text between the `ifdef` and `endif` macros is included if a
+document attribute is defined:
+
+ ifdef::[]
+ :
+ endif::[]
+
+Document text between the `ifndef` and `endif` macros is not included
+if a document attribute is defined:
+
+ ifndef::[]
+ :
+ endif::[]
+
+`` is an attribute name which is optional in the trailing
+`endif` macro.
+
+If you only want to process a single line of text then the text can be
+put inside the square brackets and the `endif` macro omitted, for
+example:
+
+ ifdef::revnumber[Version number 42]
+
+Is equivalent to:
+
+ ifdef::revnumber[]
+ Version number 42
+ endif::revnumber[]
+
+'ifdef' and 'ifndef' macros also accept multiple attribute names:
+
+- Multiple ',' separated attribute names evaluate to defined if one
+ or more of the attributes is defined, otherwise it's value is
+ undefined.
+- Multiple '+' separated attribute names evaluate to defined if all
+ of the attributes is defined, otherwise it's value is undefined.
+
+Document text between the `ifeval` and `endif` macros is included if
+the Python expression inside the square brackets is true. Example:
+
+ ifeval::[{rs458}==2]
+ :
+ endif::[]
+
+- Document attribute references are expanded before the expression is
+ evaluated.
+- If an attribute reference is undefined then the expression is
+ considered false.
+
+Take a look at the `*.conf` configuration files in the AsciiDoc
+distribution for examples of conditional inclusion macro usage.
+
+Executable system macros
+^^^^^^^^^^^^^^^^^^^^^^^^
+The 'eval', 'sys' and 'sys2' block macros exhibit the same behavior as
+their same named <>. The difference
+is that system macros occur in a block macro context whereas system
+attributes are confined to inline contexts where attribute
+substitution is enabled.
+
+The following example displays a long directory listing inside a
+literal block:
+
+ ------------------
+ sys::[ls -l *.txt]
+ ------------------
+
+NOTE: There are no block macro versions of the 'eval3' and 'sys3'
+system attributes.
+
+Template System Macro
+^^^^^^^^^^^^^^^^^^^^^
+The `template` block macro allows the inclusion of one configuration
+file template section within another. The following example includes
+the `[admonitionblock]` section in the `[admonitionparagraph]`
+section:
+
+ [admonitionparagraph]
+ template::[admonitionblock]
+
+.Template macro behavior
+- The `template::[]` macro is useful for factoring configuration file
+ markup.
+- `template::[]` macros cannot be nested.
+- `template::[]` macro expansion is applied after all configuration
+ files have been read.
+
+
+[[X77]]
+Passthrough macros
+~~~~~~~~~~~~~~~~~~
+Passthrough macros are analogous to <> and are
+used to pass text directly to the output. The substitution performed
+on the text is determined by the macro definition but can be overridden
+by the ``. The usual syntax is
+`:[]` (for inline macros) and
+`::