zeus
4 years ago
284 changed files with 91334 additions and 572 deletions
File diff suppressed because it is too large
File diff suppressed because it is too large
File diff suppressed because it is too large
File diff suppressed because it is too large
@ -0,0 +1,327 @@ |
|||
= QuickStart ! |
|||
Apostolos rootApostolos@swarmlab.io |
|||
// Metadata: |
|||
:description: Intro and Install |
|||
:keywords: doc, Quick |
|||
:data-uri: |
|||
:toc: right |
|||
:toc-title: Πίνακας περιεχομένων |
|||
:toclevels: 4 |
|||
:source-highlighter: highlight |
|||
:icons: font |
|||
:sectnums: |
|||
|
|||
|
|||
include::header.adoc[] |
|||
|
|||
{empty} + |
|||
|
|||
|
|||
[[cheat-Ascii]] |
|||
== Install (swarmlab-adoc) |
|||
|
|||
https://git.swarmlab.io:3000/swarmlab/swarmlab-adoc[^] |
|||
|
|||
|
|||
[[cheat-useadoc]] |
|||
|
|||
== Create project |
|||
|
|||
- Open a console |
|||
|
|||
[source,bash] |
|||
---- |
|||
mkdir mytest |
|||
cd mytest |
|||
swarmlab-adoc |
|||
---- |
|||
|
|||
== Copy-Paste asciidoc source |
|||
|
|||
.copy-paste source |
|||
[source,asciidoc] |
|||
---- |
|||
Paragraphs don't require any special markup in AsciiDoc. |
|||
A paragraph is just one or more lines of consecutive text. |
|||
|
|||
To begin a new paragraph, separate it by at least one blank line. |
|||
Newlines within a paragraph are not displayed. |
|||
A paragraph offset by at least one space becomes a literal paragraph. |
|||
All lines in a literal paragraph must be adjacent. |
|||
|
|||
A literal paragraph is displayed as preformatted text. |
|||
The text is shown in a fixed-width font. |
|||
Spaces and newlines, |
|||
like the ones in this sentence, |
|||
are preserved. |
|||
|
|||
NOTE: An admonition paragraph draws the reader's attention to |
|||
auxiliary information. |
|||
Its purpose is determined by the label |
|||
at the beginning of the paragraph. |
|||
|
|||
Here are the other built-in admonition types: |
|||
|
|||
TIP: Pro tip... |
|||
|
|||
IMPORTANT: Don't forget... |
|||
|
|||
WARNING: Watch out for... |
|||
|
|||
CAUTION: Ensure that... |
|||
|
|||
bold *constrained* & **un**constrained |
|||
|
|||
italic _constrained_ & __un__constrained |
|||
|
|||
bold italic *_constrained_* & **__un__**constrained |
|||
|
|||
monospace `constrained` & ``un``constrained |
|||
|
|||
monospace bold `*constrained*` & ``**un**``constrained |
|||
|
|||
monospace italic `_constrained_` & ``__un__``constrained |
|||
|
|||
monospace bold italic `*_constrained_*` & ``**__un__**``constrained |
|||
|
|||
|
|||
=== Level 2 Section Title |
|||
|
|||
==== Level 3 Section Title |
|||
|
|||
===== Level 4 Section Title |
|||
|
|||
====== Level 5 Section Title |
|||
|
|||
|
|||
Rubies are red, + |
|||
Topazes are blue. |
|||
|
|||
[%hardbreaks] |
|||
Ruby is red. |
|||
|
|||
|
|||
|
|||
* Edgar Allen Poe |
|||
* Sheri S. Tepper |
|||
* Bill Bryson |
|||
|
|||
Unordered, basic (alt) |
|||
|
|||
- Edgar Allen Poe |
|||
- Sheri S. Tepper |
|||
- Bill Bryson |
|||
|
|||
* [*] checked |
|||
* [x] also checked |
|||
* [ ] not checked |
|||
* normal list item |
|||
|
|||
https://asciidoctor.org - automatic! |
|||
|
|||
https://asciidoctor.org[Asciidoctor] |
|||
|
|||
https://github.com/asciidoctor[Asciidoctor @ *GitHub*] |
|||
|
|||
image::sunset.jpg[] |
|||
|
|||
image::sunset.jpg[Sunset] |
|||
|
|||
.A mountain sunset |
|||
[#img-sunset] |
|||
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655] |
|||
image::sunset.jpg[Sunset,300,200] |
|||
|
|||
|
|||
|
|||
video::video_file.mp4[] |
|||
|
|||
video::video_file.mp4[width=640, start=60, end=140, options=autoplay] |
|||
|
|||
=== The Greatest |
|||
|
|||
Embedded Youtube video |
|||
|
|||
video::axMLZZNINCU[youtube] |
|||
|
|||
=== pipe de oro |
|||
|
|||
Embedded Vimeo video |
|||
|
|||
video::154836263[vimeo] |
|||
|
|||
|
|||
|
|||
|
|||
---- |
|||
|
|||
|
|||
== Run |
|||
|
|||
.run |
|||
- Create a file.adoc in mytest directory |
|||
- Paste code |
|||
|
|||
[source,bash] |
|||
---- |
|||
cd mytest |
|||
swarmlab-adoc |
|||
---- |
|||
|
|||
TIP: swarmlab-adoc convert all *.adoc files recursiv in html5 and pdf |
|||
|
|||
.If you need to convert only one file |
|||
[NOTE] |
|||
==== |
|||
``` |
|||
docker run --rm -v $(pwd):/documents/ registry.vlabs.uniwa.gr:5080/swarmlab-asciidoctor asciidoctor --safe -b html5 -a theme=flask -a toc2 -a toc-placement=right -o ./path/to/FILENAME.html ./path/from/FILENAME.adoc |
|||
``` |
|||
Please note, there is a **.** in ./path |
|||
==== |
|||
|
|||
== Using a web browser |
|||
|
|||
You can see the file rendered as HTML just by visiting it! |
|||
|
|||
|
|||
== view result |
|||
|
|||
.view result |
|||
Paragraphs don't require any special markup in AsciiDoc. |
|||
A paragraph is just one or more lines of consecutive text. |
|||
|
|||
To begin a new paragraph, separate it by at least one blank line. |
|||
Newlines within a paragraph are not displayed. |
|||
A paragraph offset by at least one space becomes a literal paragraph. |
|||
All lines in a literal paragraph must be adjacent. |
|||
|
|||
A literal paragraph is displayed as preformatted text. |
|||
The text is shown in a fixed-width font. |
|||
Spaces and newlines, |
|||
like the ones in this sentence, |
|||
are preserved. |
|||
|
|||
NOTE: An admonition paragraph draws the reader's attention to |
|||
auxiliary information. |
|||
Its purpose is determined by the label |
|||
at the beginning of the paragraph. |
|||
|
|||
Here are the other built-in admonition types: |
|||
|
|||
TIP: Pro tip... |
|||
|
|||
IMPORTANT: Don't forget... |
|||
|
|||
WARNING: Watch out for... |
|||
|
|||
CAUTION: Ensure that... |
|||
|
|||
bold *constrained* & **un**constrained |
|||
|
|||
italic _constrained_ & __un__constrained |
|||
|
|||
bold italic *_constrained_* & **__un__**constrained |
|||
|
|||
monospace `constrained` & ``un``constrained |
|||
|
|||
monospace bold `*constrained*` & ``**un**``constrained |
|||
|
|||
monospace italic `_constrained_` & ``__un__``constrained |
|||
|
|||
monospace bold italic `*_constrained_*` & ``**__un__**``constrained |
|||
|
|||
|
|||
|
|||
=== Level 2 Section Title |
|||
|
|||
==== Level 3 Section Title |
|||
|
|||
===== Level 4 Section Title |
|||
|
|||
====== Level 5 Section Title |
|||
|
|||
|
|||
Rubies are red, + |
|||
Topazes are blue. |
|||
|
|||
[%hardbreaks] |
|||
Ruby is red. |
|||
|
|||
|
|||
|
|||
* Edgar Allen Poe |
|||
* Sheri S. Tepper |
|||
* Bill Bryson |
|||
|
|||
Unordered, basic (alt) |
|||
|
|||
- Edgar Allen Poe |
|||
- Sheri S. Tepper |
|||
- Bill Bryson |
|||
|
|||
* [*] checked |
|||
* [x] also checked |
|||
* [ ] not checked |
|||
* normal list item |
|||
|
|||
https://asciidoctor.org - automatic! |
|||
|
|||
https://asciidoctor.org[Asciidoctor] |
|||
|
|||
https://github.com/asciidoctor[Asciidoctor @ *GitHub*] |
|||
|
|||
image::sunset.jpg[] |
|||
|
|||
image::sunset.jpg[Sunset] |
|||
|
|||
.A mountain sunset |
|||
[#img-sunset] |
|||
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655] |
|||
image::sunset.jpg[Sunset,300,200] |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
video::video_file.mp4[] |
|||
|
|||
video::video_file.mp4[width=640, start=60, end=140, options=autoplay] |
|||
|
|||
=== The Greatest |
|||
Embedded Youtube video |
|||
|
|||
video::axMLZZNINCU[youtube] |
|||
|
|||
=== pipe de oro |
|||
Embedded Vimeo video |
|||
|
|||
video::154836263[vimeo] |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
:hardbreaks: |
|||
|
|||
{empty} + |
|||
{empty} + |
|||
{empty} |
|||
|
|||
:!hardbreaks: |
|||
|
|||
''' |
|||
|
|||
.Reminder |
|||
[NOTE] |
|||
==== |
|||
:hardbreaks: |
|||
Caminante, no hay camino, |
|||
se hace camino al andar. |
|||
|
|||
Wanderer, there is no path, |
|||
the path is made by walking. |
|||
|
|||
*Antonio Machado* Campos de Castilla |
|||
==== |
|||
@ -0,0 +1,977 @@ |
|||
<!DOCTYPE html> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta charset="UTF-8"> |
|||
<meta http-equiv="X-UA-Compatible" content="IE=edge"> |
|||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
|||
<meta name="generator" content="Asciidoctor 2.0.10"> |
|||
<meta name="description" content="Intro and Install"> |
|||
<meta name="keywords" content="doc, Quick"> |
|||
<meta name="author" content="Apostolos rootApostolos@swarmlab.io"> |
|||
<title>QuickStart !</title> |
|||
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> |
|||
<style> |
|||
/* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */ |
|||
/* Uncomment @import statement to use as custom stylesheet */ |
|||
/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ |
|||
article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block} |
|||
audio,video{display:inline-block} |
|||
audio:not([controls]){display:none;height:0} |
|||
html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
|||
a{background:none} |
|||
a:focus{outline:thin dotted} |
|||
a:active,a:hover{outline:0} |
|||
h1{font-size:2em;margin:.67em 0} |
|||
abbr[title]{border-bottom:1px dotted} |
|||
b,strong{font-weight:bold} |
|||
dfn{font-style:italic} |
|||
hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} |
|||
mark{background:#ff0;color:#000} |
|||
code,kbd,pre,samp{font-family:monospace;font-size:1em} |
|||
pre{white-space:pre-wrap} |
|||
q{quotes:"\201C" "\201D" "\2018" "\2019"} |
|||
small{font-size:80%} |
|||
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
|||
sup{top:-.5em} |
|||
sub{bottom:-.25em} |
|||
img{border:0} |
|||
svg:not(:root){overflow:hidden} |
|||
figure{margin:0} |
|||
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
|||
legend{border:0;padding:0} |
|||
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
|||
button,input{line-height:normal} |
|||
button,select{text-transform:none} |
|||
button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} |
|||
button[disabled],html input[disabled]{cursor:default} |
|||
input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} |
|||
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
|||
textarea{overflow:auto;vertical-align:top} |
|||
table{border-collapse:collapse;border-spacing:0} |
|||
*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} |
|||
html,body{font-size:100%} |
|||
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} |
|||
a:hover{cursor:pointer} |
|||
img,object,embed{max-width:100%;height:auto} |
|||
object,embed{height:100%} |
|||
img{-ms-interpolation-mode:bicubic} |
|||
.left{float:left!important} |
|||
.right{float:right!important} |
|||
.text-left{text-align:left!important} |
|||
.text-right{text-align:right!important} |
|||
.text-center{text-align:center!important} |
|||
.text-justify{text-align:justify!important} |
|||
.hide{display:none} |
|||
img,object,svg{display:inline-block;vertical-align:middle} |
|||
textarea{height:auto;min-height:50px} |
|||
select{width:100%} |
|||
.center{margin-left:auto;margin-right:auto} |
|||
.stretch{width:100%} |
|||
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} |
|||
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} |
|||
a{color:#2156a5;text-decoration:underline;line-height:inherit} |
|||
a:hover,a:focus{color:#1d4b8f} |
|||
a img{border:0} |
|||
p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
|||
p aside{font-size:.875em;line-height:1.35;font-style:italic} |
|||
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} |
|||
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} |
|||
h1{font-size:2.125em} |
|||
h2{font-size:1.6875em} |
|||
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
|||
h4,h5{font-size:1.125em} |
|||
h6{font-size:1em} |
|||
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} |
|||
em,i{font-style:italic;line-height:inherit} |
|||
strong,b{font-weight:bold;line-height:inherit} |
|||
small{font-size:60%;line-height:inherit} |
|||
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
|||
ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
|||
ul,ol{margin-left:1.5em} |
|||
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} |
|||
ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} |
|||
ul.square{list-style-type:square} |
|||
ul.circle{list-style-type:circle} |
|||
ul.disc{list-style-type:disc} |
|||
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
|||
dl dt{margin-bottom:.3125em;font-weight:bold} |
|||
dl dd{margin-bottom:1.25em} |
|||
abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} |
|||
abbr{text-transform:none} |
|||
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
|||
blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} |
|||
blockquote cite::before{content:"\2014 \0020"} |
|||
blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} |
|||
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
|||
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
|||
h1{font-size:2.75em} |
|||
h2{font-size:2.3125em} |
|||
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
|||
h4{font-size:1.4375em}} |
|||
table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} |
|||
table thead,table tfoot{background:#f7f8f7} |
|||
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} |
|||
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
|||
table tr.even,table tr.alt{background:#f8f8f7} |
|||
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} |
|||
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
|||
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
|||
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} |
|||
.clearfix::after,.float-group::after{clear:both} |
|||
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word} |
|||
:not(pre)>code.nobreak{word-wrap:normal} |
|||
:not(pre)>code.nowrap{white-space:nowrap} |
|||
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} |
|||
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} |
|||
pre>code{display:block} |
|||
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} |
|||
em em{font-style:normal} |
|||
strong strong{font-weight:400} |
|||
.keyseq{color:rgba(51,51,51,.8)} |
|||
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} |
|||
.keyseq kbd:first-child{margin-left:0} |
|||
.keyseq kbd:last-child{margin-right:0} |
|||
.menuseq,.menuref{color:#000} |
|||
.menuseq b:not(.caret),.menuref{font-weight:inherit} |
|||
.menuseq{word-spacing:-.02em} |
|||
.menuseq b.caret{font-size:1.25em;line-height:.8} |
|||
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em} |
|||
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} |
|||
b.button::before{content:"[";padding:0 3px 0 2px} |
|||
b.button::after{content:"]";padding:0 2px 0 3px} |
|||
p a>code:hover{color:rgba(0,0,0,.9)} |
|||
#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
|||
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} |
|||
#header::after,#content::after,#footnotes::after,#footer::after{clear:both} |
|||
#content{margin-top:1.25em} |
|||
#content::before{content:none} |
|||
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
|||
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} |
|||
#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} |
|||
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} |
|||
#header .details span:first-child{margin-left:-.125em} |
|||
#header .details span.email a{color:rgba(0,0,0,.85)} |
|||
#header .details br{display:none} |
|||
#header .details br+span::before{content:"\00a0\2013\00a0"} |
|||
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
|||
#header .details br+span#revremark::before{content:"\00a0|\00a0"} |
|||
#header #revnumber{text-transform:capitalize} |
|||
#header #revnumber::after{content:"\00a0"} |
|||
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
|||
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} |
|||
#toc>ul{margin-left:.125em} |
|||
#toc ul.sectlevel0>li>a{font-style:italic} |
|||
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
|||
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
|||
#toc li{line-height:1.3334;margin-top:.3334em} |
|||
#toc a{text-decoration:none} |
|||
#toc a:active{text-decoration:underline} |
|||
#toctitle{color:#7a2518;font-size:1.2em} |
|||
@media screen and (min-width:768px){#toctitle{font-size:1.375em} |
|||
body.toc2{padding-left:15em;padding-right:0} |
|||
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} |
|||
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
|||
#toc.toc2>ul{font-size:.9em;margin-bottom:0} |
|||
#toc.toc2 ul ul{margin-left:0;padding-left:1em} |
|||
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
|||
body.toc2.toc-right{padding-left:0;padding-right:15em} |
|||
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} |
|||
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
|||
#toc.toc2{width:20em} |
|||
#toc.toc2 #toctitle{font-size:1.375em} |
|||
#toc.toc2>ul{font-size:.95em} |
|||
#toc.toc2 ul ul{padding-left:1.25em} |
|||
body.toc2.toc-right{padding-left:0;padding-right:20em}} |
|||
#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
|||
#content #toc>:first-child{margin-top:0} |
|||
#content #toc>:last-child{margin-bottom:0} |
|||
#footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em} |
|||
#footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
|||
#content{margin-bottom:.625em} |
|||
.sect1{padding-bottom:.625em} |
|||
@media screen and (min-width:768px){#content{margin-bottom:1.25em} |
|||
.sect1{padding-bottom:1.25em}} |
|||
.sect1:last-child{padding-bottom:0} |
|||
.sect1+.sect1{border-top:1px solid #e7e7e9} |
|||
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} |
|||
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} |
|||
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} |
|||
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} |
|||
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} |
|||
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
|||
details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em} |
|||
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} |
|||
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} |
|||
.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} |
|||
table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} |
|||
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
|||
.admonitionblock>table td.icon{text-align:center;width:80px} |
|||
.admonitionblock>table td.icon img{max-width:none} |
|||
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
|||
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)} |
|||
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
|||
.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} |
|||
.exampleblock>.content>:first-child{margin-top:0} |
|||
.exampleblock>.content>:last-child{margin-bottom:0} |
|||
.sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px} |
|||
.sidebarblock>:first-child{margin-top:0} |
|||
.sidebarblock>:last-child{margin-bottom:0} |
|||
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
|||
.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} |
|||
.literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em} |
|||
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} |
|||
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} |
|||
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} |
|||
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} |
|||
.listingblock>.content{position:relative} |
|||
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5} |
|||
.listingblock:hover code[data-lang]::before{display:block} |
|||
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} |
|||
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} |
|||
.listingblock pre.highlightjs{padding:0} |
|||
.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
|||
.listingblock pre.prettyprint{border-width:0} |
|||
.prettyprint{background:#f7f7f8} |
|||
pre.prettyprint .linenums{line-height:1.45;margin-left:2em} |
|||
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} |
|||
pre.prettyprint li code[data-lang]::before{opacity:1} |
|||
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} |
|||
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
|||
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} |
|||
table.linenotable td.code{padding-left:.75em} |
|||
table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em} |
|||
pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em} |
|||
pre.pygments .lineno::before{content:"";margin-right:-.125em} |
|||
.quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
|||
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} |
|||
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} |
|||
.quoteblock blockquote{margin:0;padding:0;border:0} |
|||
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} |
|||
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
|||
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} |
|||
.verseblock{margin:0 1em 1.25em} |
|||
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} |
|||
.verseblock pre strong{font-weight:400} |
|||
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
|||
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
|||
.quoteblock .attribution br,.verseblock .attribution br{display:none} |
|||
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
|||
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} |
|||
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} |
|||
.quoteblock.abstract{margin:0 1em 1.25em;display:block} |
|||
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} |
|||
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} |
|||
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} |
|||
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} |
|||
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0} |
|||
table.tableblock{max-width:100%;border-collapse:separate} |
|||
p.tableblock:last-child{margin-bottom:0} |
|||
td.tableblock>.content>:last-child{margin-bottom:-1.25em} |
|||
td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0} |
|||
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
|||
table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0} |
|||
table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0} |
|||
table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0} |
|||
table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px} |
|||
table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0} |
|||
table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0} |
|||
table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0} |
|||
table.frame-all{border-width:1px} |
|||
table.frame-sides{border-width:0 1px} |
|||
table.frame-topbot,table.frame-ends{border-width:1px 0} |
|||
table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7} |
|||
th.halign-left,td.halign-left{text-align:left} |
|||
th.halign-right,td.halign-right{text-align:right} |
|||
th.halign-center,td.halign-center{text-align:center} |
|||
th.valign-top,td.valign-top{vertical-align:top} |
|||
th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
|||
th.valign-middle,td.valign-middle{vertical-align:middle} |
|||
table thead th,table tfoot th{font-weight:bold} |
|||
tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} |
|||
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
|||
p.tableblock>code:only-child{background:none;padding:0} |
|||
p.tableblock{font-size:1em} |
|||
ol{margin-left:1.75em} |
|||
ul li ol{margin-left:1.5em} |
|||
dl dd{margin-left:1.125em} |
|||
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
|||
ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
|||
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} |
|||
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} |
|||
ul.unstyled,ol.unstyled{margin-left:0} |
|||
ul.checklist{margin-left:.625em} |
|||
ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} |
|||
ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} |
|||
ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} |
|||
ul.inline>li{margin-left:1.25em} |
|||
.unstyled dl dt{font-weight:400;font-style:normal} |
|||
ol.arabic{list-style-type:decimal} |
|||
ol.decimal{list-style-type:decimal-leading-zero} |
|||
ol.loweralpha{list-style-type:lower-alpha} |
|||
ol.upperalpha{list-style-type:upper-alpha} |
|||
ol.lowerroman{list-style-type:lower-roman} |
|||
ol.upperroman{list-style-type:upper-roman} |
|||
ol.lowergreek{list-style-type:lower-greek} |
|||
.hdlist>table,.colist>table{border:0;background:none} |
|||
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
|||
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
|||
td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
|||
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
|||
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} |
|||
.colist td:not([class]):first-child img{max-width:none} |
|||
.colist td:not([class]):last-child{padding:.25em 0} |
|||
.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} |
|||
.imageblock.left{margin:.25em .625em 1.25em 0} |
|||
.imageblock.right{margin:.25em 0 1.25em .625em} |
|||
.imageblock>.title{margin-bottom:0} |
|||
.imageblock.thumb,.imageblock.th{border-width:6px} |
|||
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
|||
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
|||
.image.left{margin-right:.625em} |
|||
.image.right{margin-left:.625em} |
|||
a.image{text-decoration:none;display:inline-block} |
|||
a.image object{pointer-events:none} |
|||
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
|||
sup.footnote a,sup.footnoteref a{text-decoration:none} |
|||
sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} |
|||
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
|||
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} |
|||
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} |
|||
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} |
|||
#footnotes .footnote:last-of-type{margin-bottom:0} |
|||
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
|||
.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} |
|||
.gist .file-data>table td.line-data{width:99%} |
|||
div.unbreakable{page-break-inside:avoid} |
|||
.big{font-size:larger} |
|||
.small{font-size:smaller} |
|||
.underline{text-decoration:underline} |
|||
.overline{text-decoration:overline} |
|||
.line-through{text-decoration:line-through} |
|||
.aqua{color:#00bfbf} |
|||
.aqua-background{background:#00fafa} |
|||
.black{color:#000} |
|||
.black-background{background:#000} |
|||
.blue{color:#0000bf} |
|||
.blue-background{background:#0000fa} |
|||
.fuchsia{color:#bf00bf} |
|||
.fuchsia-background{background:#fa00fa} |
|||
.gray{color:#606060} |
|||
.gray-background{background:#7d7d7d} |
|||
.green{color:#006000} |
|||
.green-background{background:#007d00} |
|||
.lime{color:#00bf00} |
|||
.lime-background{background:#00fa00} |
|||
.maroon{color:#600000} |
|||
.maroon-background{background:#7d0000} |
|||
.navy{color:#000060} |
|||
.navy-background{background:#00007d} |
|||
.olive{color:#606000} |
|||
.olive-background{background:#7d7d00} |
|||
.purple{color:#600060} |
|||
.purple-background{background:#7d007d} |
|||
.red{color:#bf0000} |
|||
.red-background{background:#fa0000} |
|||
.silver{color:#909090} |
|||
.silver-background{background:#bcbcbc} |
|||
.teal{color:#006060} |
|||
.teal-background{background:#007d7d} |
|||
.white{color:#bfbfbf} |
|||
.white-background{background:#fafafa} |
|||
.yellow{color:#bfbf00} |
|||
.yellow-background{background:#fafa00} |
|||
span.icon>.fa{cursor:default} |
|||
a span.icon>.fa{cursor:inherit} |
|||
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
|||
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} |
|||
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
|||
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} |
|||
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} |
|||
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} |
|||
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} |
|||
.conum[data-value] *{color:#fff!important} |
|||
.conum[data-value]+b{display:none} |
|||
.conum[data-value]::after{content:attr(data-value)} |
|||
pre .conum[data-value]{position:relative;top:-.125em} |
|||
b.conum *{color:inherit!important} |
|||
.conum:not([data-value]):empty{display:none} |
|||
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
|||
h1,h2,p,td.content,span.alt{letter-spacing:-.01em} |
|||
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
|||
p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} |
|||
p{margin-bottom:1.25rem} |
|||
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
|||
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
|||
.print-only{display:none!important} |
|||
@page{margin:1.25cm .75cm} |
|||
@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
|||
html{font-size:80%} |
|||
a{color:inherit!important;text-decoration:underline!important} |
|||
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
|||
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
|||
abbr[title]::after{content:" (" attr(title) ")"} |
|||
pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
|||
thead{display:table-header-group} |
|||
svg{max-width:100%} |
|||
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
|||
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
|||
#toc,.sidebarblock,.exampleblock>.content{background:none!important} |
|||
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} |
|||
body.book #header{text-align:center} |
|||
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} |
|||
body.book #header .details{border:0!important;display:block;padding:0!important} |
|||
body.book #header .details span:first-child{margin-left:0!important} |
|||
body.book #header .details br{display:block} |
|||
body.book #header .details br+span::before{content:none!important} |
|||
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
|||
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
|||
.listingblock code[data-lang]::before{display:block} |
|||
#footer{padding:0 .9375em} |
|||
.hide-on-print{display:none!important} |
|||
.print-only{display:block!important} |
|||
.hide-for-print{display:none!important} |
|||
.show-for-print{display:inherit!important}} |
|||
@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} |
|||
.sect1{padding:0!important} |
|||
.sect1+.sect1{border:0} |
|||
#footer{background:none} |
|||
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}} |
|||
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} |
|||
</style> |
|||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> |
|||
</head> |
|||
<body class="article toc2 toc-right"> |
|||
<div id="header"> |
|||
<h1>QuickStart !</h1> |
|||
<div class="details"> |
|||
<span id="author" class="author">Apostolos rootApostolos@swarmlab.io</span><br> |
|||
</div> |
|||
<div id="toc" class="toc2"> |
|||
<div id="toctitle">Πίνακας περιεχομένων</div> |
|||
<ul class="sectlevel1"> |
|||
<li><a href="#cheat-Ascii">1. Install (swarmlab-adoc)</a></li> |
|||
<li><a href="#cheat-useadoc">2. Create project</a></li> |
|||
<li><a href="#_copy_paste_asciidoc_source">3. Copy-Paste asciidoc source</a></li> |
|||
<li><a href="#_run">4. Run</a></li> |
|||
<li><a href="#_using_a_web_browser">5. Using a web browser</a></li> |
|||
<li><a href="#_view_result">6. view result</a> |
|||
<ul class="sectlevel2"> |
|||
<li><a href="#_level_2_section_title">6.1. Level 2 Section Title</a> |
|||
<ul class="sectlevel3"> |
|||
<li><a href="#_level_3_section_title">6.1.1. Level 3 Section Title</a> |
|||
<ul class="sectlevel4"> |
|||
<li><a href="#_level_4_section_title">Level 4 Section Title</a></li> |
|||
</ul> |
|||
</li> |
|||
</ul> |
|||
</li> |
|||
<li><a href="#_the_greatest">6.2. The Greatest</a></li> |
|||
<li><a href="#_pipe_de_oro">6.3. pipe de oro</a></li> |
|||
</ul> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
</div> |
|||
<div id="content"> |
|||
<div id="preamble"> |
|||
<div class="sectionbody"> |
|||
<table class="tableblock frame-all grid-all stretch"> |
|||
<colgroup> |
|||
<col style="width: 33.3333%;"> |
|||
<col style="width: 33.3333%;"> |
|||
<col style="width: 33.3334%;"> |
|||
</colgroup> |
|||
<thead> |
|||
<tr> |
|||
<th class="tableblock halign-left valign-top"><a href="http://docs.swarmlab.io">Home</a> <span class="icon"><a class="image" href="http://docs.swarmlab.io" target="_self"><i class="fa fa-home"></i></a></span></th> |
|||
<th class="tableblock halign-left valign-top"><a href="http://docs.swarmlab.io/Howtos">HowTos</a> <span class="icon"><a class="image" href="http://docs.swarmlab.io/Howtos" target="_self"><i class="fa fa-wpbeginner"></i></a></span></th> |
|||
<th class="tableblock halign-left valign-top"><a href="http://docs.swarmlab.io/lab">Labs</a> <span class="icon"><a class="image" href="http://docs.swarmlab.io/lab" target="_self"><i class="fa fa-mixcloud"></i></a></span></th> |
|||
</tr> |
|||
</thead> |
|||
</table> |
|||
<div class="paragraph right text-center"> |
|||
<p><br></p> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect1"> |
|||
<h2 id="cheat-Ascii">1. Install (swarmlab-adoc)</h2> |
|||
<div class="sectionbody"> |
|||
<div class="paragraph"> |
|||
<p><a href="https://git.swarmlab.io:3000/swarmlab/swarmlab-adoc" class="bare" target="_blank" rel="noopener">https://git.swarmlab.io:3000/swarmlab/swarmlab-adoc</a></p> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect1"> |
|||
<h2 id="cheat-useadoc">2. Create project</h2> |
|||
<div class="sectionbody"> |
|||
<div class="ulist"> |
|||
<ul> |
|||
<li> |
|||
<p>Open a console</p> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
<div class="listingblock"> |
|||
<div class="content"> |
|||
<pre class="highlight"><code class="language-bash" data-lang="bash">mkdir mytest |
|||
cd mytest |
|||
swarmlab-adoc</code></pre> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect1"> |
|||
<h2 id="_copy_paste_asciidoc_source">3. Copy-Paste asciidoc source</h2> |
|||
<div class="sectionbody"> |
|||
<div class="listingblock"> |
|||
<div class="title">copy-paste source</div> |
|||
<div class="content"> |
|||
<pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">Paragraphs don't require any special markup in AsciiDoc. |
|||
A paragraph is just one or more lines of consecutive text. |
|||
|
|||
To begin a new paragraph, separate it by at least one blank line. |
|||
Newlines within a paragraph are not displayed. |
|||
A paragraph offset by at least one space becomes a literal paragraph. |
|||
All lines in a literal paragraph must be adjacent. |
|||
|
|||
A literal paragraph is displayed as preformatted text. |
|||
The text is shown in a fixed-width font. |
|||
Spaces and newlines, |
|||
like the ones in this sentence, |
|||
are preserved. |
|||
|
|||
NOTE: An admonition paragraph draws the reader's attention to |
|||
auxiliary information. |
|||
Its purpose is determined by the label |
|||
at the beginning of the paragraph. |
|||
|
|||
Here are the other built-in admonition types: |
|||
|
|||
TIP: Pro tip... |
|||
|
|||
IMPORTANT: Don't forget... |
|||
|
|||
WARNING: Watch out for... |
|||
|
|||
CAUTION: Ensure that... |
|||
|
|||
bold *constrained* & **un**constrained |
|||
|
|||
italic _constrained_ & __un__constrained |
|||
|
|||
bold italic *_constrained_* & **__un__**constrained |
|||
|
|||
monospace `constrained` & ``un``constrained |
|||
|
|||
monospace bold `*constrained*` & ``**un**``constrained |
|||
|
|||
monospace italic `_constrained_` & ``__un__``constrained |
|||
|
|||
monospace bold italic `*_constrained_*` & ``**__un__**``constrained |
|||
|
|||
|
|||
=== Level 2 Section Title |
|||
|
|||
==== Level 3 Section Title |
|||
|
|||
===== Level 4 Section Title |
|||
|
|||
====== Level 5 Section Title |
|||
|
|||
|
|||
Rubies are red, + |
|||
Topazes are blue. |
|||
|
|||
[%hardbreaks] |
|||
Ruby is red. |
|||
|
|||
|
|||
|
|||
* Edgar Allen Poe |
|||
* Sheri S. Tepper |
|||
* Bill Bryson |
|||
|
|||
Unordered, basic (alt) |
|||
|
|||
- Edgar Allen Poe |
|||
- Sheri S. Tepper |
|||
- Bill Bryson |
|||
|
|||
* [*] checked |
|||
* [x] also checked |
|||
* [ ] not checked |
|||
* normal list item |
|||
|
|||
https://asciidoctor.org - automatic! |
|||
|
|||
https://asciidoctor.org[Asciidoctor] |
|||
|
|||
https://github.com/asciidoctor[Asciidoctor @ *GitHub*] |
|||
|
|||
image::sunset.jpg[] |
|||
|
|||
image::sunset.jpg[Sunset] |
|||
|
|||
.A mountain sunset |
|||
[#img-sunset] |
|||
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655] |
|||
image::sunset.jpg[Sunset,300,200] |
|||
|
|||
|
|||
|
|||
video::video_file.mp4[] |
|||
|
|||
video::video_file.mp4[width=640, start=60, end=140, options=autoplay] |
|||
|
|||
=== The Greatest |
|||
|
|||
Embedded Youtube video |
|||
|
|||
video::axMLZZNINCU[youtube] |
|||
|
|||
=== pipe de oro |
|||
|
|||
Embedded Vimeo video |
|||
|
|||
video::154836263[vimeo]</code></pre> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect1"> |
|||
<h2 id="_run">4. Run</h2> |
|||
<div class="sectionbody"> |
|||
<div class="ulist"> |
|||
<div class="title">run</div> |
|||
<ul> |
|||
<li> |
|||
<p>Create a file.adoc in mytest directory</p> |
|||
</li> |
|||
<li> |
|||
<p>Paste code</p> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
<div class="listingblock"> |
|||
<div class="content"> |
|||
<pre class="highlight"><code class="language-bash" data-lang="bash">cd mytest |
|||
swarmlab-adoc</code></pre> |
|||
</div> |
|||
</div> |
|||
<div class="admonitionblock tip"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-tip" title="Tip"></i> |
|||
</td> |
|||
<td class="content"> |
|||
swarmlab-adoc convert all *.adoc files recursiv in html5 and pdf |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
<div class="admonitionblock note"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-note" title="Note"></i> |
|||
</td> |
|||
<td class="content"> |
|||
<div class="title">If you need to convert only one file</div> |
|||
<div class="listingblock"> |
|||
<div class="content"> |
|||
<pre class="highlight"><code>docker run --rm -v $(pwd):/documents/ registry.vlabs.uniwa.gr:5080/swarmlab-asciidoctor asciidoctor --safe -b html5 -a theme=flask -a toc2 -a toc-placement=right -o ./path/to/FILENAME.html ./path/from/FILENAME.adoc</code></pre> |
|||
</div> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>Please note, there is a <strong>.</strong> in ./path</p> |
|||
</div> |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect1"> |
|||
<h2 id="_using_a_web_browser">5. Using a web browser</h2> |
|||
<div class="sectionbody"> |
|||
<div class="paragraph"> |
|||
<p>You can see the file rendered as HTML just by visiting it!</p> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect1"> |
|||
<h2 id="_view_result">6. view result</h2> |
|||
<div class="sectionbody"> |
|||
<div class="paragraph"> |
|||
<div class="title">view result</div> |
|||
<p>Paragraphs don’t require any special markup in AsciiDoc. |
|||
A paragraph is just one or more lines of consecutive text.</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>To begin a new paragraph, separate it by at least one blank line. |
|||
Newlines within a paragraph are not displayed. |
|||
A paragraph offset by at least one space becomes a literal paragraph. |
|||
All lines in a literal paragraph must be adjacent.</p> |
|||
</div> |
|||
<div class="literalblock"> |
|||
<div class="content"> |
|||
<pre>A literal paragraph is displayed as preformatted text. |
|||
The text is shown in a fixed-width font. |
|||
Spaces and newlines, |
|||
like the ones in this sentence, |
|||
are preserved.</pre> |
|||
</div> |
|||
</div> |
|||
<div class="admonitionblock note"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-note" title="Note"></i> |
|||
</td> |
|||
<td class="content"> |
|||
An admonition paragraph draws the reader’s attention to |
|||
auxiliary information. |
|||
Its purpose is determined by the label |
|||
at the beginning of the paragraph. |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>Here are the other built-in admonition types:</p> |
|||
</div> |
|||
<div class="admonitionblock tip"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-tip" title="Tip"></i> |
|||
</td> |
|||
<td class="content"> |
|||
Pro tip…​ |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
<div class="admonitionblock important"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-important" title="Important"></i> |
|||
</td> |
|||
<td class="content"> |
|||
Don’t forget…​ |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
<div class="admonitionblock warning"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-warning" title="Warning"></i> |
|||
</td> |
|||
<td class="content"> |
|||
Watch out for…​ |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
<div class="admonitionblock caution"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-caution" title="Caution"></i> |
|||
</td> |
|||
<td class="content"> |
|||
Ensure that…​ |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>bold <strong>constrained</strong> & <strong>un</strong>constrained</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>italic <em>constrained</em> & <em>un</em>constrained</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>bold italic <strong><em>constrained</em></strong> & <strong><em>un</em></strong>constrained</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>monospace <code>constrained</code> & <code>un</code>constrained</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>monospace bold <code><strong>constrained</strong></code> & <code><strong>un</strong></code>constrained</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>monospace italic <code><em>constrained</em></code> & <code><em>un</em></code>constrained</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>monospace bold italic <code><strong><em>constrained</em></strong></code> & <code><strong><em>un</em></strong></code>constrained</p> |
|||
</div> |
|||
<div class="sect2"> |
|||
<h3 id="_level_2_section_title">6.1. Level 2 Section Title</h3> |
|||
<div class="sect3"> |
|||
<h4 id="_level_3_section_title">6.1.1. Level 3 Section Title</h4> |
|||
<div class="sect4"> |
|||
<h5 id="_level_4_section_title">Level 4 Section Title</h5> |
|||
<div class="sect5"> |
|||
<h6 id="_level_5_section_title">Level 5 Section Title</h6> |
|||
<div class="paragraph"> |
|||
<p>Rubies are red,<br> |
|||
Topazes are blue.</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>Ruby is red.</p> |
|||
</div> |
|||
<div class="ulist"> |
|||
<ul> |
|||
<li> |
|||
<p>Edgar Allen Poe</p> |
|||
</li> |
|||
<li> |
|||
<p>Sheri S. Tepper</p> |
|||
</li> |
|||
<li> |
|||
<p>Bill Bryson</p> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>Unordered, basic (alt)</p> |
|||
</div> |
|||
<div class="ulist"> |
|||
<ul> |
|||
<li> |
|||
<p>Edgar Allen Poe</p> |
|||
</li> |
|||
<li> |
|||
<p>Sheri S. Tepper</p> |
|||
</li> |
|||
<li> |
|||
<p>Bill Bryson</p> |
|||
<div class="ulist checklist"> |
|||
<ul class="checklist"> |
|||
<li> |
|||
<p><i class="fa fa-check-square-o"></i> checked</p> |
|||
</li> |
|||
<li> |
|||
<p><i class="fa fa-check-square-o"></i> also checked</p> |
|||
</li> |
|||
<li> |
|||
<p><i class="fa fa-square-o"></i> not checked</p> |
|||
</li> |
|||
<li> |
|||
<p>normal list item</p> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
</li> |
|||
</ul> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p><a href="https://asciidoctor.org" class="bare">https://asciidoctor.org</a> - automatic!</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p><a href="https://asciidoctor.org">Asciidoctor</a></p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p><a href="https://github.com/asciidoctor">Asciidoctor @ <strong>GitHub</strong></a></p> |
|||
</div> |
|||
<div class="imageblock"> |
|||
<div class="content"> |
|||
<img src="data:image/jpg;base64," alt="sunset"> |
|||
</div> |
|||
</div> |
|||
<div class="imageblock"> |
|||
<div class="content"> |
|||
<img src="data:image/jpg;base64," alt="Sunset"> |
|||
</div> |
|||
</div> |
|||
<div id="img-sunset" class="imageblock"> |
|||
<div class="content"> |
|||
<a class="image" href="https://www.flickr.com/photos/javh/5448336655"><img src="data:image/jpg;base64," alt="Sunset" width="300" height="200"></a> |
|||
</div> |
|||
<div class="title">Figure 1: A mountain sunset</div> |
|||
</div> |
|||
<div class="videoblock"> |
|||
<div class="content"> |
|||
<video src="video_file.mp4" controls> |
|||
Your browser does not support the video tag. |
|||
</video> |
|||
</div> |
|||
</div> |
|||
<div class="videoblock"> |
|||
<div class="content"> |
|||
<video src="video_file.mp4#t=60,140" width="640" autoplay controls> |
|||
Your browser does not support the video tag. |
|||
</video> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect2"> |
|||
<h3 id="_the_greatest">6.2. The Greatest</h3> |
|||
<div class="paragraph"> |
|||
<p>Embedded Youtube video</p> |
|||
</div> |
|||
<div class="videoblock"> |
|||
<div class="content"> |
|||
<iframe src="https://www.youtube.com/embed/axMLZZNINCU?rel=0" frameborder="0" allowfullscreen></iframe> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div class="sect2"> |
|||
<h3 id="_pipe_de_oro">6.3. pipe de oro</h3> |
|||
<div class="paragraph"> |
|||
<p>Embedded Vimeo video</p> |
|||
</div> |
|||
<div class="videoblock"> |
|||
<div class="content"> |
|||
<iframe src="https://player.vimeo.com/video/154836263" frameborder="0" allowfullscreen></iframe> |
|||
</div> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p><br> |
|||
<br> |
|||
</p> |
|||
</div> |
|||
<hr> |
|||
<div class="admonitionblock note"> |
|||
<table> |
|||
<tr> |
|||
<td class="icon"> |
|||
<i class="fa icon-note" title="Note"></i> |
|||
</td> |
|||
<td class="content"> |
|||
<div class="title">Reminder</div> |
|||
<div class="paragraph"> |
|||
<p>Caminante, no hay camino,<br> |
|||
se hace camino al andar.</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p>Wanderer, there is no path,<br> |
|||
the path is made by walking.</p> |
|||
</div> |
|||
<div class="paragraph"> |
|||
<p><strong>Antonio Machado</strong> Campos de Castilla</p> |
|||
</div> |
|||
</td> |
|||
</tr> |
|||
</table> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
</div> |
|||
<div id="footer"> |
|||
<div id="footer-text"> |
|||
Last updated 2020-07-09 15:05:53 UTC |
|||
</div> |
|||
</div> |
|||
</body> |
|||
</html> |
|||
File diff suppressed because it is too large
@ -0,0 +1,34 @@ |
|||
//// |
|||
user manual |
|||
//// |
|||
|
|||
== What is Asciidoctor? |
|||
|
|||
//// |
|||
{homepage}[Asciidoctor] is an open source text processor and publishing toolchain for transforming AsciiDoc markup into HTML 5, EPUB3, PDF, DocBook 5.0 and 4.5, slidedecks, and other custom formats. |
|||
Asciidoctor is written entirely in Ruby, packaged as a RubyGem and published to {gem}[RubyGems.org]. |
|||
There are also Fedora, Debian and Ubuntu packages available for installing Asciidoctor. |
|||
The git repositories for the project are hosted under the {gh-org}[Asciidoctor organization on GitHub]. |
|||
//// |
|||
|
|||
Asciidoctor is a _fast_ text processor and publishing toolchain for converting AsciiDoc content to HTML5, EPUB3, PDF, DocBook 5 (or 4.5) slidedecks and other formats. |
|||
Asciidoctor is written in Ruby, packaged as a RubyGem and published to {uri-gem}[RubyGems.org]. |
|||
The gem is also packaged in several Linux distributions, including Fedora, Debian and Ubuntu. |
|||
Asciidoctor is open source, {uri-repo}[hosted on GitHub], and released under the MIT license. |
|||
|
|||
=== The Big Picture |
|||
|
|||
Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. |
|||
Asciidoctor adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant out-of-the-box experience. |
|||
|
|||
image::zen-screenshot.png[Preview of AsciiDoc source and corresponding HTML] |
|||
|
|||
=== Asciidoctor on the JVM |
|||
|
|||
You can run Asciidoctor on the JVM using JRuby. |
|||
You can also use {uri-asciidoctorj}[AsciidoctorJ] to invoke Asciidoctor's APIs from Java and other JVM languages. |
|||
|
|||
=== Asciidoctor.js |
|||
|
|||
Asciidoctor can be used in JavaScript. |
|||
https://opalrb.com[Opal] is used to transcompile the code from Ruby to JavaScript to make {uri-asciidoctorjs}[Asciidoctor.js], which can be used wherever JavaScript runs, such as in a web browser or on Node.js. |
|||
@ -0,0 +1,76 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
An abstract is a concise overview of an article or of a chapter in a book. |
|||
They are frequently found in the frontmatter of academic, research, and analytical papers. |
|||
//Abstracts with subheadings are structured abstracts, whereas abstracts without subheadings are unstructured. |
|||
//^ Not relevant for AsciiDoc |
|||
A complete (i.e., informative) abstract states the key topics and findings while a limited (i.e., descriptive) abstract briefly describes the structure of the content. |
|||
|
|||
The abstract may be written using a section, open block, or paragraph and must bear the abstract style. |
|||
If used, the abstract must appear before the first section of an article (at the start of the <<Preamble,preamble>>) or at the start of a chapter in a book. |
|||
An abstract may not be used _before_ a part or chapter in a book. |
|||
|
|||
Here's an example of an abstract at the beginning of an article, defined using a section: |
|||
|
|||
[source] |
|||
---- |
|||
= Article Title |
|||
|
|||
[abstract] |
|||
== Abstract |
|||
|
|||
Documentation is a distillation of many long, squiggly adventures. |
|||
|
|||
== First Section |
|||
---- |
|||
|
|||
Here's an example of the same abstract defined using a paragraph: |
|||
|
|||
[source] |
|||
---- |
|||
= Article Title |
|||
|
|||
[abstract] |
|||
.Abstract |
|||
Documentation is a distillation of many long, squiggly adventures. |
|||
|
|||
== First Section |
|||
---- |
|||
|
|||
In the book doctype, the abstract section must be a level below the chapter. |
|||
|
|||
[source] |
|||
---- |
|||
== Chapter Title |
|||
|
|||
[abstract] |
|||
=== Chapter Abstract |
|||
|
|||
Documentation is a distillation of many long, squiggly adventures. |
|||
|
|||
=== First Section |
|||
---- |
|||
|
|||
An abstract defined using an open block or paragraph does not require a title and does not depend on a subsequent section to terminate. |
|||
|
|||
[source] |
|||
---- |
|||
= Article Title |
|||
|
|||
[abstract] |
|||
.Optional Abstract Title |
|||
-- |
|||
This article will take you on a wonderful adventure of knowledge. |
|||
|
|||
You'll start with the basics. |
|||
Beyond that, where you go is up to you. |
|||
-- |
|||
|
|||
Your journey begins here. |
|||
---- |
|||
|
|||
TIP: To include a quote at the beginning of a chapter in a book, wrap the quote block inside an abstract block. |
|||
@ -0,0 +1,87 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Admonition |
|||
- writers-guide: admonition |
|||
//// |
|||
|
|||
// tag::intro[] |
|||
There are certain statements you may want to draw attention to by taking them out of the content's flow and labeling them with a priority. |
|||
These are called admonitions. |
|||
It's rendered style is determined by the assigned label (i.e., value). |
|||
Asciidoctor provides five admonition style labels: |
|||
|
|||
* `NOTE` |
|||
* `TIP` |
|||
* `IMPORTANT` |
|||
* `CAUTION` |
|||
* `WARNING` |
|||
|
|||
.Caution vs. Warning |
|||
**** |
|||
When choosing the admonition type, you may find yourself getting confused between "caution" and "warning" as these words are often used interchangeably. |
|||
Here's a simple rule to help you differentiate the two: |
|||
|
|||
* Use *CAUTION* to advise the reader to _act_ carefully (i.e., exercise care). |
|||
* Use *WARNING* to inform the reader of danger, harm, or consequences that exist. |
|||
|
|||
To find a deeper analysis, see https://www.differencebetween.com/difference-between-caution-and-vs-warning/. |
|||
**** |
|||
|
|||
When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use. |
|||
The label must be uppercase and followed by a colon (`:`). |
|||
|
|||
.Admonition paragraph syntax |
|||
[source] |
|||
---- |
|||
include::ex-admon.adoc[tag=para-c] |
|||
---- |
|||
<1> The label must be uppercase and immediately followed by a colon (`:`). |
|||
<2> Separate the first line of the paragraph from the label by a single space. |
|||
// end::intro[] |
|||
|
|||
:icons!: |
|||
// tag::icon[] |
|||
.Result: Admonition paragraph |
|||
==== |
|||
include::ex-admon.adoc[tag=para] |
|||
==== |
|||
// end::icon[] |
|||
:icons: font |
|||
|
|||
When you want to apply an admonition to complex content, set the label as a style attribute on a block. |
|||
As seen in the next example, admonition labels are commonly set on example blocks. |
|||
This behavior is referred to as *masquerading*. |
|||
The label must be uppercase when set as an attribute on a block. |
|||
|
|||
.Admonition block syntax |
|||
[source] |
|||
---- |
|||
include::ex-admon.adoc[tag=bl-c] |
|||
---- |
|||
<1> Set the label in an attribute list on a delimited block. The label must be uppercase. |
|||
<2> Admonition styles are commonly set on example blocks. Example blocks are delimited by four equal signs (`====`). |
|||
|
|||
:icons!: |
|||
.Result: Admonition block |
|||
==== |
|||
include::ex-admon.adoc[tag=bl-nest] |
|||
==== |
|||
:icons: font |
|||
|
|||
In the examples above, the admonition is rendered in a callout box with the style label in the gutter. |
|||
You can replace the textual labels with icons by setting the `icons` attribute on the document. |
|||
This is how the WARNING admonition paragraph renders when icons is set and assigned the `font` value. |
|||
|
|||
.Admonition paragraph with icons set |
|||
[source] |
|||
---- |
|||
include::ex-admon.adoc[tag=para] |
|||
---- |
|||
|
|||
.Result: Admonition paragraph with icons set |
|||
==== |
|||
include::ex-admon.adoc[tag=para] |
|||
==== |
|||
|
|||
Learn more about using Font Awesome or custom icons with admonitions in the <<user-manual#icons,icons>> section. |
|||
@ -0,0 +1,11 @@ |
|||
//// |
|||
API introduction for Asciidoctor |
|||
This file is included in the user-manual documents |
|||
//// |
|||
|
|||
In addition to the command line interface, Asciidoctor provides a Ruby API. |
|||
The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub. |
|||
|
|||
Asciidoctor also has a Java API that mirrors the Ruby API. |
|||
The Java API calls through to the Ruby API using an embedded JRuby runtime. |
|||
See the {doc-asciidoctorj}[AsciidoctorJ project] for more information. |
|||
@ -0,0 +1,79 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
You can indicate that a section, part, or chapter is an appendix by adding an `[appendix]` line above the section title. |
|||
|
|||
[source] |
|||
---- |
|||
[appendix] |
|||
== Copyright and License |
|||
---- |
|||
|
|||
While the AsciiDoc structure allows appendices to be placed anywhere, it's customary to place them at the end of the document, after all other sections. |
|||
|
|||
Sections marked as appendix have a different title, which is built as follows: |
|||
|
|||
* A fixed prefix (taken from the value of the `appendix-caption` attribute, which defaults to "`Appendix`") |
|||
* A letter that represents the number of this appendix within the sequence of appendices (A, B, C, ...) |
|||
* A colon |
|||
* The original section title |
|||
|
|||
For example: |
|||
|
|||
Appendix A: Copyright and License |
|||
|
|||
The prefix can be modified by defining the `appendix-caption` attribute. |
|||
This value can be changed using: |
|||
|
|||
[source] |
|||
---- |
|||
:appendix-caption: Appx |
|||
---- |
|||
|
|||
Or it can be unset using: |
|||
|
|||
[source] |
|||
---- |
|||
:appendix-caption!: |
|||
---- |
|||
|
|||
Appendices can have subsections. |
|||
However, there are some rules to follow depending on which type of document you are creating. |
|||
|
|||
For articles, the appendix must be defined as a level-1 section. |
|||
(If a level-0 section is used, a level-1 section is implied). |
|||
For example: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-appendix.adoc[tag=appx-article] |
|||
---- |
|||
|
|||
The table of contents will appear as follows: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-appendix.adoc[tag=appx-article-out] |
|||
---- |
|||
|
|||
For books, the appendix must be defined as a level-1 section if you want the appendix to be a adjacent to other chapters (and in the current part if the book has multiple parts). |
|||
In a multi-part book, if you want the appendix to be adjacent to other parts, the appendix must be defined as a level-0 section. |
|||
In either case, the first subsection of the appendix must be a level-3 section, not a level-2 section. |
|||
That's because an appendix cannot contain chapters. |
|||
|
|||
The following example shows how to define an appendix for a multi-book (take away the part title if you're creating a simple book): |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-appendix.adoc[tag=appx-book] |
|||
---- |
|||
|
|||
The table of contents will appear as follows: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-appendix.adoc[tag=appx-book-out] |
|||
---- |
|||
@ -0,0 +1,93 @@ |
|||
//// |
|||
Custom Themes |
|||
Applying a theme |
|||
|
|||
This document is included in: |
|||
|
|||
- user-manual |
|||
- produce-custom-themes-using-asciidoctor-stylesheet-factory |
|||
//// |
|||
|
|||
A custom stylesheet can be stored in the same directory as your document or in a separate directory. |
|||
Like the default stylesheet, you can have the output document link to your custom stylesheet or embed it. |
|||
|
|||
If the stylesheet is in the same directory as your document, you can apply it when converting your document to HTML from the CLI. |
|||
|
|||
$ asciidoctor -a stylesheet=mystyles.css mysample.adoc |
|||
|
|||
. Save your custom stylesheet in the same directory as `mysample.adoc` |
|||
. Call the `asciidoctor` processor |
|||
. Set `-a` (`--attribute`) and `stylesheet` |
|||
. Assign the stylesheet file's name to the `stylesheet` attribute |
|||
. Enter your document file's name. |
|||
|
|||
Alternatively, let's set the `stylesheet` attribute in the header of `mysample.adoc`. |
|||
|
|||
---- |
|||
include::mysample-stylesheet.adoc[] |
|||
---- |
|||
|
|||
==== |
|||
image::mysample-stylesheet.png[] |
|||
==== |
|||
|
|||
When your document and the stylesheet are stored in different directories, you need to tell Asciidoctor where to look for the stylesheet in relation to your document. |
|||
Asciidoctor uses the relative or absolute path you assign to the `stylesdir` attribute to find the stylesheet. |
|||
Let's move `mystyles.css` into `mydocuments/mystylesheets/`. |
|||
Our AsciiDoc document, `mysample.adoc`, is saved in the `mydocuments/` directory. |
|||
|
|||
---- |
|||
include::mysample-stylesdir.adoc[] |
|||
---- |
|||
|
|||
After processing `mysample.adoc`, its HTML output (`mysample.html`), which includes the embedded `mystyles.css` stylesheet, is created in the `mydocuments/` directory. |
|||
|
|||
==== |
|||
image::mysample-stylesdir-dir.png[] |
|||
==== |
|||
|
|||
You can also set `stylesdir` in the CLI. |
|||
|
|||
$ asciidoctor -a stylesdir=mystylesheets/ -a stylesheet=mystyles.css mysample.adoc |
|||
|
|||
If you don't want to embed the `mystyles.css` stylesheet into your HTML output, make sure to set `linkcss`. |
|||
|
|||
---- |
|||
include::mysample-stylesdir-link.adoc[] |
|||
---- |
|||
|
|||
After your document is converted, notice that a copy of `mystyles.css` was not created in the `mydocuments/` directory. |
|||
Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved. |
|||
|
|||
[#style-nest-doc] |
|||
.Stylesheets and processing multiple nested documents |
|||
**** |
|||
When you are <<user-manual.adoc#process-multiple-source-files-from-the-cli,running Asciidoctor once across a nested set of documents>>, it's currently not possible to specify a single relative path for the `stylesdir` attribute that would work for all of the documents. |
|||
This is because the relative depth of the stylesheet's location differs for the documents in the subdirectories. |
|||
One way to solve this problem is to maintain the path to `stylesdir` in each document. |
|||
|
|||
Let's say you have three AsciiDoc documents saved in the following directory structure: |
|||
|
|||
---- |
|||
/mydocuments |
|||
a.adoc |
|||
b.adoc |
|||
/mynesteddocuments |
|||
c.adoc |
|||
/mystylesheets |
|||
---- |
|||
|
|||
For `a.adoc` and `b.adoc`, set `stylesdir` to: |
|||
|
|||
---- |
|||
:stylesdir: mystylesheets |
|||
---- |
|||
|
|||
For `c.adoc`, set `stylesdir` to: |
|||
|
|||
---- |
|||
:stylesdir: ../mystylesheets |
|||
---- |
|||
|
|||
If you're serving your documents from a webserver, you can solve this problem by providing an absolute path to the stylesheet. |
|||
**** |
|||
@ -0,0 +1,91 @@ |
|||
= AsciiDoc Article Title |
|||
Firstname Lastname <author@asciidoctor.org> |
|||
1.0, July 29, 2014, Asciidoctor 1.5 article template |
|||
:toc: |
|||
:icons: font |
|||
:quick-uri: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ |
|||
|
|||
Content entered directly below the header but before the first section heading is called the preamble. |
|||
|
|||
== First level heading |
|||
|
|||
This is a paragraph with a *bold* word and an _italicized_ word. |
|||
|
|||
.Image caption |
|||
image::image-file-name.png[I am the image alt text.] |
|||
|
|||
This is another paragraph.footnote:[I am footnote text and will be displayed at the bottom of the article.] |
|||
|
|||
=== Second level heading |
|||
|
|||
.Unordered list title |
|||
* list item 1 |
|||
** nested list item |
|||
*** nested nested list item 1 |
|||
*** nested nested list item 2 |
|||
* list item 2 |
|||
|
|||
This is a paragraph. |
|||
|
|||
.Example block title |
|||
==== |
|||
Content in an example block is subject to normal substitutions. |
|||
==== |
|||
|
|||
.Sidebar title |
|||
**** |
|||
Sidebars contain aside text and are subject to normal substitutions. |
|||
**** |
|||
|
|||
==== Third level heading |
|||
|
|||
[#id-for-listing-block] |
|||
.Listing block title |
|||
---- |
|||
Content in a listing block is subject to verbatim substitutions. |
|||
Listing block content is commonly used to preserve code input. |
|||
---- |
|||
|
|||
===== Fourth level heading |
|||
|
|||
.Table title |
|||
|=== |
|||
|Column heading 1 |Column heading 2 |
|||
|
|||
|Column 1, row 1 |
|||
|Column 2, row 1 |
|||
|
|||
|Column 1, row 2 |
|||
|Column 2, row 2 |
|||
|=== |
|||
|
|||
====== Fifth level heading |
|||
|
|||
[quote, firstname lastname, movie title] |
|||
____ |
|||
I am a block quote or a prose excerpt. |
|||
I am subject to normal substitutions. |
|||
____ |
|||
|
|||
[verse, firstname lastname, poem title and more] |
|||
____ |
|||
I am a verse block. |
|||
Indents and endlines are preserved in verse blocks. |
|||
____ |
|||
|
|||
== First level heading |
|||
|
|||
TIP: There are five admonition labels: Tip, Note, Important, Caution and Warning. |
|||
|
|||
// I am a comment and won't be rendered. |
|||
|
|||
. ordered list item |
|||
.. nested ordered list item |
|||
. ordered list item |
|||
|
|||
The text at the end of this sentence is cross referenced to <<_third_level_heading,the third level heading>> |
|||
|
|||
== First level heading |
|||
|
|||
This is a link to the https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]. |
|||
This is an attribute reference {quick-uri}[which links this text to the Asciidoctor Quick Reference Guide]. |
|||
@ -0,0 +1,22 @@ |
|||
//== Apache Ant |
|||
|
|||
The `asciidoctor-ant` task is an all-in-one solution for running Asciidoctor from Ant. |
|||
It is based on AsciidoctorJ and JRuby, both of which are encapsulated in a single jar file. |
|||
|
|||
Usage is: |
|||
|
|||
[source,xml] |
|||
-- |
|||
<project xmlns:asciidoctor="antlib:org.asciidoctor.ant"> |
|||
... |
|||
<target name="doc"> |
|||
<taskdef uri="antlib:org.asciidoctor.ant" |
|||
resource="org/asciidoctor/ant/antlib.xml" |
|||
classpath="lib/asciidoctor-ant.jar"/> |
|||
<asciidoctor:convert sourceDirectory="src/asciidoc" outputDirectory="target"/> |
|||
</target> |
|||
... |
|||
</project> |
|||
-- |
|||
|
|||
For more details, see {uri-anttask}[asciidoctor-ant on GitHub]. |
|||
@ -0,0 +1,310 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Attributes: Setting attributes on a document |
|||
//// |
|||
|
|||
An [.term]_attribute entry_ is the primary mechanism for defining a document attribute in an AsciiDoc document. |
|||
You can think of an attribute entry as a global variable assignment for AsciiDoc. |
|||
The document attribute it creates becomes available from that point forward in the document. |
|||
Attribute entries are also frequently used to toggle features. |
|||
|
|||
An attribute entry consists of two parts: an attribute name and an attribute value. |
|||
The attribute name comes first. |
|||
It must be at the start of the line and must be enclosed in colons (e.g., `:name:`). |
|||
If present, the attribute value is offset from the name part by at least one space (e.g., `:name: value`). |
|||
Be aware that substitutions automatically get applied to the value by default, as described in <<user-manual#attribute-entry-subs,Substitutions in an attribute entry>>. |
|||
|
|||
.Anatomy of an attribute entry |
|||
[source] |
|||
---- |
|||
:name: value |
|||
---- |
|||
|
|||
The attribute value is optional. |
|||
A blank value is often used to set (i.e., activate) a boolean attribute (thus making a blank value implicitly true). |
|||
|
|||
.Anatomy of an attribute entry to set a boolean attribute |
|||
[source] |
|||
---- |
|||
:name: |
|||
---- |
|||
|
|||
An exclamation point (`!`) before (or after) the attribute name unsets the attribute. |
|||
In this case, the value is ignored. |
|||
|
|||
.Anatomy of an attribue entry to unset an attribute |
|||
[source] |
|||
---- |
|||
:!name: |
|||
---- |
|||
|
|||
Attribute entries have the following characteristics: |
|||
|
|||
Attributes entries can: :: |
|||
* be assigned to a document: |
|||
** through the CLI or API |
|||
** in the document's header |
|||
** in the document's body |
|||
* be unset (turned off) with a leading (or trailing) `!` added to the name |
|||
* have default values (in the case of a built-in attribute) |
|||
* have alternate values (in the case of a built-in attribute) |
|||
* span multiple, contiguous lines |
|||
* include inline AsciiDoc content |
|||
|
|||
Attribute entries can not: :: |
|||
* override locked attributes assigned from the command line |
|||
* include AsciiDoc block content (such as, bulleted lists or other types of whitespace-dependent markup) |
|||
|
|||
Attributes are typically defined in the document header, though they may also be defined in the body of the document. |
|||
Once set, an attribute (and its value) are available for use for the remainder of the document. |
|||
Unless locked by the API, attributes may be reassigned at any subsequent point in the document. |
|||
|
|||
==== Attribute entry use cases |
|||
|
|||
Attributes entries serve three main purposes: |
|||
|
|||
. Toggle or configure built-in features |
|||
. Set built-in asset locations |
|||
. Content reuse |
|||
|
|||
===== Setting built-in attributes |
|||
|
|||
Numerous attribute are reserved for special purposes. |
|||
These built-in attributes can be used to toggle behavior, such as the table of contents, or control the generated output, such as selecting or configuring a converter. |
|||
Many built-in attributes only take effect when defined in the document header. |
|||
|
|||
For example, to enable the built-in table of contents, you can define (i.e., set) the `toc` attribute using an attribute entry in the document header as follows: |
|||
|
|||
[source] |
|||
---- |
|||
:toc: |
|||
---- |
|||
|
|||
When the value following an attribute is left empty, as it is in the example above, the default value will be assigned (if any). |
|||
The default value for `toc` is `auto`. |
|||
Therefore, the table of contents will be placed in the default location (below the document's title) when the document is converted. |
|||
|
|||
If you want the table of contents to be placed on the right side of the document, you must assign the attribute a new value. |
|||
|
|||
[source] |
|||
---- |
|||
:toc: right |
|||
---- |
|||
|
|||
The `right` value will override the default value of `auto`. |
|||
The value assigned to an attribute in the document header replaces the intrinsic value (assuming the attribute is not locked). |
|||
|
|||
===== Setting asset locations |
|||
|
|||
You can also use attributes to set the base path to images (default: _empty_), icons (default: `./images/icons`), and stylesheets (default: `./stylesheets`). |
|||
|
|||
.Base asset path configuration example |
|||
[source] |
|||
---- |
|||
:imagesdir: ./images |
|||
:iconsdir: ./icons |
|||
:stylesdir: ./styles |
|||
---- |
|||
|
|||
===== Content reuse |
|||
|
|||
If you're familiar with writing in XML, you might recognize a document attribute as a user-defined entity. |
|||
When you find yourself typing the same text repeatedly, or text that often needs to be updated, consider assigning it to a document attribute and use that instead. |
|||
|
|||
A prime use case for attribute entries is to promote frequently used URLs and links to the top of the document. |
|||
|
|||
.URL attribute entry |
|||
[source] |
|||
---- |
|||
:url-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor |
|||
---- |
|||
|
|||
Now you can refer to this attribute entry anywhere in the document (where attribute substitution is performed) by surrounding its name in curly braces. |
|||
|
|||
Instead of having to type the URL out longhand in the link macro, as follows: |
|||
|
|||
.A case for using an attribute reference |
|||
[source] |
|||
---- |
|||
Did you know there's an https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]? |
|||
---- |
|||
|
|||
We can replace the target side of the link macro with a reference to our attribute. |
|||
|
|||
.url-fedpkg attribute usage example |
|||
[source] |
|||
---- |
|||
Did you know there's an {url-fedpkg}[Asciidoctor package for Fedora]? |
|||
---- |
|||
|
|||
To save even more typing, you can store the whole link in an attribute value. |
|||
|
|||
.Link attribute entry |
|||
[source] |
|||
---- |
|||
:link-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora] |
|||
---- |
|||
|
|||
Now you insert this link anywhere in the document using an attribute reference. |
|||
|
|||
.link-fedpkg attribute usage example |
|||
[source] |
|||
---- |
|||
Did you know there's an {link-fedpkg}? |
|||
---- |
|||
|
|||
Note that the link substitution occurs _after_ the attribute reference is resolved. |
|||
This works thanks to the default order of substitutions on a paragraph. |
|||
If you want the link macro to be resolved eagerly at the time the attribute is assigned, you need to enclose it in a pass macro. |
|||
|
|||
.Link attribute entry resolved eagerly |
|||
[source] |
|||
---- |
|||
:link-fedpkg: pass:m[https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]] |
|||
---- |
|||
|
|||
Now you can use this link in a section title (where the order of substitutions is different). |
|||
Let's dive deeper into which substitutions are applied to an attribute entry and how to alter them. |
|||
|
|||
[#attribute-entry-subs] |
|||
==== Substitutions in an attribute entry |
|||
|
|||
The AsciiDoc processor automatically applies substitutions from the header substitution group to the value of an attribute entry prior to the assignment (regardless of where the attribute entry is declared in the document). |
|||
The header substitution group replaces <<user-manual#special-characters,special characters>> and <<user-manual#attributes-2,attribute references>>. |
|||
This is the same group that gets applied to metadata lines (author and revision information) in the document header. |
|||
To learn about how these substitutions work, refer to the <<user-manual#subs,Substitutions>> chapter. |
|||
|
|||
==== Altering attribute entry substitutions |
|||
|
|||
If you want the value of an attribute entry to be used *as is* (not subject to substitutions), or you want to alter the substitutions that are applied, you can enclose the value in the <<user-manual#pass-macros,inline pass macro>> (i.e., `\pass:[]`). |
|||
The inline pass macro accepts a list of zero or more substitutions in the target slot, which can be used to control which substitutions are applied to the value. |
|||
If no substitutions are specified, no substitutions will be applied. |
|||
|
|||
In order for the inline macro to work in this context, it must completely surround the attribute value. |
|||
If it's used anywhere else in the value, it is ignored. |
|||
|
|||
Here's how to prevent substitutions from being applied to the value of an attribute entry: |
|||
|
|||
[source] |
|||
---- |
|||
:cols: pass:[.>2,.>4] |
|||
---- |
|||
|
|||
This might be useful if you're referencing the attribute in a place that depends on the unaltered text, such as the value of the `cols` attribute on a table. |
|||
|
|||
Here's how to apply the <<user-manual#quotes,quotes substitution>> to the value of an attribute entry: |
|||
|
|||
[source] |
|||
---- |
|||
:app-name: pass:quotes[MyApp^2^] |
|||
---- |
|||
|
|||
Internally, the value is stored as `MyApp<sup>2</sup>`. |
|||
You can inspect the value stored in an attribute using this trick: |
|||
|
|||
[listing] |
|||
.... |
|||
[subs=attributes+] |
|||
---- |
|||
{app-name} |
|||
---- |
|||
.... |
|||
|
|||
You can also specify the substitution using the single-character alias, `q`. |
|||
|
|||
[source] |
|||
---- |
|||
:app-name: pass:q[MyApp^2^] |
|||
---- |
|||
|
|||
The inline pass macro kind of works like an attribute value preprocessor. |
|||
If the processor detects that an inline pass macro completely surrounds the attribute value, it: |
|||
|
|||
. reads the list of substitutions from the target slot of the macro |
|||
. unwraps the value from the macro |
|||
. applies the substitutions to the value |
|||
|
|||
If the macro is absent, the value is processed with the header substitution group. |
|||
|
|||
You can also change the substitutions that are applied to an attribute at the time it is resolved. |
|||
This is done by manipulating the substitutions applied to the text where it is referenced. |
|||
For example, here's how we could get the processor to apply quote substitutions to the value of an attribute: |
|||
|
|||
[source] |
|||
---- |
|||
:app-name: MyApp^2^ |
|||
|
|||
[subs="specialchars,attributes,quotes,replacements,macros,post_replacements"] |
|||
The application is called {app-name}. |
|||
---- |
|||
|
|||
Notice that we've swapped the order of the `attributes` and `quotes` substitutions. |
|||
This strategy is akin to postprocessing the attribute value. |
|||
|
|||
==== Splitting attribute values over multiple lines |
|||
|
|||
When an attribute value is very long, it's possible to split it (i.e., soft-wrap) across multiple lines. |
|||
|
|||
Let's assume we are working with the following attribute entry: |
|||
|
|||
.A long, single-line attribute |
|||
[source] |
|||
---- |
|||
:long-value: If you have a very long line of text that you need to substitute regularly in a document, you may find it easier to split it neatly in the header so it remains readable to the next person reading your docs code. |
|||
---- |
|||
|
|||
You can split the value over multiple lines to make it more readable by inserting a space followed by a backslash (i.e., `{sp}\`) at the end of each continuing line. |
|||
|
|||
.A long, multiline attribute (soft wrapped) |
|||
[source] |
|||
---- |
|||
:long-value: If you have a very long line of text \ |
|||
that you need to substitute regularly in a document, \ |
|||
you may find it easier to split it neatly in the header \ |
|||
so it remains readable to folks reading your docs code. |
|||
---- |
|||
|
|||
The backslash and the newline that follows will be removed from the attribute value when the attribute entry is parsed, making this second example effectively the same as the first. |
|||
The space before the backslash is preserved, so you have to use this technique at a natural break point in the content. |
|||
|
|||
You can force an attribute value to hard wrap by adding a plus surrounded by spaces before the backslash. |
|||
|
|||
.An attribute value with hard line breaks |
|||
[source] |
|||
---- |
|||
:haiku: Write your docs in text, + \ |
|||
AsciiDoc makes it easy, + \ |
|||
Now get back to work! |
|||
---- |
|||
|
|||
This syntax ensures that the newlines are preserved in the output document as hard line breaks. |
|||
|
|||
==== Attribute limitations |
|||
|
|||
Attributes let you do a surprising amount of formatting for what is fundamentally a text replacement tool. |
|||
|
|||
It may be tempting to try and extend attributes to be used for complex replaceable markup. |
|||
|
|||
Supported:: |
|||
Basic in-line AsciiDoc markup is permitted in attribute values, such as: |
|||
+ |
|||
* attribute references |
|||
* text formatting (usually wrapped in a pass macro) |
|||
* inline macros (usually wrapped in a pass macro) |
|||
|
|||
Unsupported:: |
|||
Complex AsciiDoc markup is not permitted in attribute values, such as: |
|||
+ |
|||
* lists |
|||
* multiple paragraphs |
|||
* other whitespace-dependent markup types |
|||
|
|||
//// |
|||
TODO: This section actually might make more sense in the header section. |
|||
|
|||
The main focus of the learning for this documentation is how to use inline formatting in an attribute value. Normally, inline formatting in an attribute value is not interpreted because: |
|||
|
|||
a. Inline formatting is not applied when an attribute is set (attribute holds raw value) |
|||
b. Inline formatting is not applied when an attribute is referenced since the relevant substitutions come before attributes are resolved |
|||
//// |
|||
@ -0,0 +1,63 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Attributes: Setting attributes on an element |
|||
//// |
|||
|
|||
// tag::intro[] |
|||
An attribute list can apply to blocks, inline quotes text, and macros. |
|||
The attributes and their values contained in the list will take precedence over attribute entries. |
|||
|
|||
.Anatomy of an attribute list |
|||
[positional_attribute1,positional_attribute2,name_attribute1="value"] |
|||
|
|||
Attribute lists: |
|||
|
|||
. apply to blocks as well as macros and inline quoted text |
|||
. can contain positional and named attributes |
|||
. take precedence over global attributes |
|||
// end::intro[] |
|||
|
|||
==== Positional attribute |
|||
// tag::pos[] |
|||
Positional attributes are un-named values at the start of the attribute list. |
|||
The attribute that they are assigned to depends on the type of the element: |
|||
|
|||
* `icon:` (1) size |
|||
* `image:` and `image::` (1) alt text, (2) width, (3) height |
|||
* Delimited blocks: (1) block name (aka style) |
|||
* Other inline quoted text: (1) role |
|||
|
|||
For example, the following two image macros are equivalent. |
|||
|
|||
[source,asciidoc] |
|||
---- |
|||
image::sunset.jpg[Sunset,300,400] |
|||
|
|||
image::sunset.jpg[alt=Sunset,width=300,height=400] |
|||
---- |
|||
|
|||
The second macro is just a duplicate of the first macro written out longhand. |
|||
// end::pos[] |
|||
|
|||
==== Named attribute |
|||
// tag::name[] |
|||
A named attribute consists of a name and a value separated by an `=` character (e.g., `name=value`). |
|||
|
|||
If the value contains a space, comma, or quote character, it must be enclosed in double or single quotes (e.g., `name="value with space"`). |
|||
In all other cases, the surrounding quotes are optional. |
|||
If present, the enclosing quotes are dropped from the parsed value. |
|||
|
|||
To undefine a named attribute, set the value to `None` (case sensitive). |
|||
// end::name[] |
|||
|
|||
==== Attribute List Substitutions |
|||
// tag::subs[] |
|||
Attribute references are expanded before the block attribute list is processed. |
|||
Therefore, it's not necessary to force substitutions to be applied if you simply want to use a document attribute reference in a block attribute. |
|||
|
|||
If the attribute name (for a positional attribute) or value (for a named attribute) is enclosed in single quotes (e.g., `+title='Processed by https://asciidoctor.org[Asciidoctor]'+`), <<subs,normal substitutions>> are applied to the value at assignment time (with some exceptions). |
|||
No special processing is performed if the value is not enclosed in quotes or is enclosed in double quotes. |
|||
|
|||
If the attribute value contains the same quote character being used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., `title="\"Dark Horse\" is a song by George Harrison"`). |
|||
// end::subs[] |
|||
@ -0,0 +1,91 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Catch a missing or undefined attribute |
|||
//// |
|||
|
|||
As a result of a misconfigured document or inadvertent substitution, an attribute reference may point to a non-existent attribute (e.g., `+{does-not-exist}+`). |
|||
It could be that the attribute reference itself undefines the attribute (e.g., `+{set:attribute-no-more!}+`). |
|||
You'll want to think about how you want the processor to handle these situations and configure it accordingly. |
|||
|
|||
AsciiDoc Python simply drops any line that contains a reference to a missing attribute. |
|||
This "`feature`" was designed with AsciiDoc Python's own template language in mind, which is also based on the AsciiDoc syntax. |
|||
However, this behavior was never really intended for use in regular AsciiDoc documents. |
|||
The behavior is frustrating for the author, editor, or reader because it's not immediately obvious when a line goes missing. |
|||
Discovering the absence of certain line often requires a painstaking read-through of the document or section, if it's even noticed at all. |
|||
|
|||
Asciidoctor offers two attributes to alleviate this inconvenience: `attribute-missing` and `attribute-undefined`. |
|||
|
|||
===== Missing attribute |
|||
|
|||
The `attribute-missing` attribute controls how missing (i.e., unresolved) references are handled. |
|||
By default, missing references are left intact so the integrity of the document is preserved (`skip`). |
|||
However, that mode doesn't help the author track down these references. |
|||
|
|||
To help with that task, Asciidoctor can be configured to warn when a missing reference is encountered (`warn`). |
|||
Asciidoctor can also emulate the behavior of AsciiDoc Python (`drop-line`), or offer something in between (`drop`). |
|||
|
|||
Here are the four possible values of the `attribute-missing` attribute: |
|||
|
|||
`skip`:: leaves the reference intact without issuing a warning (default setting) |
|||
`drop`:: drops the reference, but not the whole line |
|||
`drop-line`:: drops the whole line on which the reference occurs (matches behavior of AsciiDoc Python) |
|||
`warn`:: leaves the reference intact, but also prints a warning about the missing attribute (recommended) |
|||
|
|||
Consider the following line of AsciiDoc: |
|||
|
|||
[source] |
|||
---- |
|||
Hello, {name}! |
|||
---- |
|||
|
|||
Here's how the line is handled in each case, assuming the `name` attribute is not defined: |
|||
|
|||
[horizontal] |
|||
`skip`:: Hello, \{name}! |
|||
`drop`:: Hello, ! |
|||
`drop-line`:: {empty} |
|||
`warn`:: |
|||
+ |
|||
---- |
|||
asciidoctor: WARNING: skipping reference to missing attribute: name |
|||
---- |
|||
|
|||
If you want the processor to fail when the document contains a missing attribute, set the `attribute-missing` attribute to `warn` and pass the `--failure-level=WARN` option to the processor. |
|||
|
|||
$ asciidoctor -a attribute-missing=warn --failure-level=WARN doc.adoc |
|||
|
|||
When using the API, you can consult the logger for the max severity of all messages reported or look for specific messages in the stack. |
|||
|
|||
There are several exceptions when the `attribute-missing` attribute is not strictly honored. |
|||
One of those cases is the include directive. |
|||
If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute and drop the include directive. |
|||
This behavior was chosen because showing the unresolved include directive to the reader is messy. |
|||
|
|||
Another case is the block image macro. |
|||
If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute, but leave the image macro unresolved so as to show it as alt text. |
|||
|
|||
A missing attribute reference can safely be used in an ifeval clause without any side effects (i.e., `drop`) since often the purpose of that statement is to determine whether an attribute resolves to a value. |
|||
|
|||
===== Undefined attribute |
|||
|
|||
The attribute attribute-undefined controls how expressions that undefine an attribute are handled. |
|||
By default, the line is dropped since the expression is a statement, not content. |
|||
|
|||
This attribute has two possible values: |
|||
|
|||
`drop`:: substitute the expression with an empty string after processing it |
|||
`drop-line`:: drop the line that contains this expression (default setting; matches behavior of AsciiDoc Python) |
|||
|
|||
The option `skip` doesn't make sense here since the statement is not intended to produce content. |
|||
|
|||
Consider the following declaration: |
|||
|
|||
``` |
|||
{set:name!} |
|||
``` |
|||
|
|||
Depending on whether attribute-undefined is `drop` or `drop-line`, either the statement or the line that contains it will be discarded. |
|||
It's reasonable to stick with the compliant behavior, drop-line, in this case. |
|||
|
|||
TIP: We recommend putting any statement that undefines an attribute on a line by itself. |
|||
@ -0,0 +1,95 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Attributes: Style |
|||
//// |
|||
|
|||
// tag::intro[] |
|||
The style attribute is the first positional attribute in an attribute list. |
|||
It specifies a predefined set of characteristics that should apply to a block element or macro. |
|||
|
|||
For example, a paragraph block can be assigned one of the following built-in style attributes: |
|||
|
|||
* normal (default, so does not need to be set) |
|||
* literal |
|||
* verse |
|||
* quote |
|||
* listing |
|||
* TIP |
|||
* NOTE |
|||
* IMPORTANT |
|||
* WARNING |
|||
* CAUTION |
|||
* abstract |
|||
* partintro |
|||
* comment |
|||
* example |
|||
* sidebar |
|||
* source |
|||
|
|||
// end::intro[] |
|||
|
|||
==== Id |
|||
// tag::id[] |
|||
The id attribute specifies a unique name for an element. |
|||
That name can only be used once in a document. |
|||
|
|||
An id has two purposes: |
|||
|
|||
. to provide an internal link or cross reference anchor for the element |
|||
. to reference a style or script used by the output processor |
|||
// end::id[] |
|||
|
|||
//// |
|||
BlockId |
|||
|
|||
NOTE: Section pending |
|||
//// |
|||
|
|||
===== Block assignment |
|||
// tag::bl[] |
|||
In an attribute list, there are two ways to assign an id attribute to a block element. |
|||
|
|||
. Prefixing the name with a hash (`#`). |
|||
. Specifying the name with `id=<name>`. |
|||
|
|||
[source] |
|||
---- |
|||
[#goals] |
|||
* Goal 1 |
|||
* Goal 2 |
|||
---- |
|||
|
|||
Let's say you want to create a blockquote from an open block and assign it an ID and role. |
|||
You add `quote` (the block style) in front of the `#` (the ID) in the first attribute position, as this example shows: |
|||
|
|||
[source] |
|||
---- |
|||
[quote#roads, Dr. Emmett Brown] |
|||
____ |
|||
Roads? Where we're going, we don't need roads. |
|||
____ |
|||
---- |
|||
|
|||
TIP: The order of ID and role values in the shorthand syntax does not matter. |
|||
|
|||
CAUTION: If the ID contains a `.`, you must define it using either a longhand assignment (e.g., `id=classname.propertyname`) or the anchor shorthand (e.g., `+[[classname.propertyname]]+`). |
|||
This is necessary since the `.` character in the shorthand syntax is the delimiter for a role, and thus gets misinterpreted as such. |
|||
// end::bl[] |
|||
|
|||
===== Inline assignment |
|||
// tag::in[] |
|||
The id (`#`) shorthand can be used on inline quoted text. |
|||
|
|||
.Quoted text block with id assignment using Asciidoctor shorthand |
|||
---- |
|||
[#free_the_world]*free the world* |
|||
---- |
|||
// end::in[] |
|||
|
|||
//// |
|||
.Quoted text block with `id` assignment using traditional AsciiDoc syntax |
|||
---- |
|||
[[free_the_world]]*free the world* |
|||
---- |
|||
//// |
|||
@ -0,0 +1,54 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Using attributes: set, assign, and reference |
|||
//// |
|||
|
|||
Before you can use an attribute in your document, it must be set. |
|||
(Sometimes referred to as "`toggling on`" the attribute). |
|||
|
|||
Some attributes are automatically set when {adr} processes a document. |
|||
You can also set (or override) an attribute for a document by declaring an attribute entry. |
|||
For example: |
|||
|
|||
:sectnums: |
|||
|
|||
Many attributes can be assigned a value at the same time: |
|||
|
|||
:leveloffset: 3 |
|||
|
|||
The value may be empty, a string (of characters) or a number. |
|||
A string value may include references to other attributes. |
|||
|
|||
Attributes can be unset using the bang symbol (`!`). |
|||
The `!` can be placed either before or after the attribute's name. |
|||
|
|||
For example, both: |
|||
|
|||
:sectnums!: |
|||
|
|||
and |
|||
|
|||
:!sectnums: |
|||
|
|||
mean unset the `sectnums` attribute. |
|||
In this case, it tells Asciidoctor to not number the sections. |
|||
|
|||
To soft unset an attribute from the CLI or API, you can use the following syntax: |
|||
|
|||
!name=@ |
|||
|
|||
The leading `!` unsets the attribute while the `@` lowers the precedence of the assignment. |
|||
This assignment is almost always used to unset a default value while still allowing the document to assign a new one. |
|||
One such example is `sectids`, which is enabled by default. |
|||
`!sectids=@` switches the setting off. |
|||
|
|||
An [.term]_attribute reference_ is an inline element composed of the name of the attribute enclosed in curly brackets. |
|||
For example: |
|||
|
|||
The value of leveloffset is {leveloffset}. |
|||
|
|||
The attribute reference is replaced by the attribute's value when Asciidoctor processes the document. |
|||
Referencing an attribute that is not set is considered an error and is handled specially by the processor. |
|||
|
|||
The following sections will show you how to use attributes on your whole document, individual blocks, and inline elements. |
|||
@ -0,0 +1,99 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Attributes |
|||
//// |
|||
|
|||
// tag::intro[] |
|||
Attributes are one of the features that sets Asciidoctor apart from other lightweight markup languages. |
|||
Attributes can activate features (behaviors, styles, integrations, etc) or hold replacement (i.e., variable) content. |
|||
|
|||
In Asciidoctor, attributes are classified as: |
|||
|
|||
* <<env-attributes,Environment attributes>> |
|||
* <<builtin-attributes,Built-in attributes>> |
|||
* <<charref-attributes,Predefined attributes>> |
|||
* <<glossary,User-defined attributes>> |
|||
* <<attribute-assignment-precedence,API and Command Line Attributes>> |
|||
* <<setting-attributes-on-an-element,Element Attributes>> |
|||
// end::intro[] |
|||
|
|||
// tag::attributesyntax[] |
|||
=== Attribute Restrictions |
|||
|
|||
All attributes have a name and a value (though the value may be implicit). |
|||
|
|||
The attribute name: |
|||
|
|||
* must be at least one character long, |
|||
* must begin with a word character (A-Z, a-z, 0-9 or _) and |
|||
* must only contain word characters and hyphens. |
|||
|
|||
In other words, the name cannot contain dots or spaces. |
|||
|
|||
Although uppercase characters are permitted in an attribute entry (the place where an attribute is defined), the attribute name is converted to lowercase before being stored. |
|||
The attribute name in an attribute reference is also converted to lowercase before the attribute is resolved. |
|||
For example, `URI`, `Uri` and `uRI` are all treated as `uri`. |
|||
(See https://github.com/asciidoctor/asciidoctor/issues/509[issue #509] for a proposed change to this restriction). |
|||
A best practice is to only use lowercase for letters in the name and avoid starting the name with a number. |
|||
|
|||
The attribute value: |
|||
|
|||
* can be any inline content and |
|||
* can only contain line breaks if an explicit line continuation is used. |
|||
|
|||
Certain attributes have a restricted range of allowable values. |
|||
See the entries in the <<attribute-catalog>> for details. |
|||
// end::attributesyntax[] |
|||
|
|||
=== Attribute Assignment Precedence |
|||
// tag::order[] |
|||
The attribute assignment precedence, listed from highest to lowest, is as follows: |
|||
|
|||
* An attribute defined using the API or CLI |
|||
* An attribute defined in the document |
|||
* The default value of the attribute, if applicable |
|||
|
|||
Let's use the `imagesdir` attribute to show how precedence works. |
|||
|
|||
The default value for the `imagesdir` attribute is an empty string. |
|||
Therefore, if the `imagesdir` attribute is not assigned a value (either in the document, API, or CLI), the processor will assign it the default value of empty string. |
|||
If the `imagesdir` attribute is set in the document (meaning assigned a new value, such as `images`), that value will override the default value. |
|||
Finally, if a value is assigned to the `imagesdir` attribute via the API or CLI, that value will override both the default value and the value assigned in the document. |
|||
|
|||
It's possible to alter this order of precedence using a modifier, covered in the next section. |
|||
|
|||
==== Altering the Attribute Assignment Precedence |
|||
|
|||
You can allow the document to reassign an attribute that is defined via the API or CLI by adding the `@` precedence modifier to the end of the attribute value (or, since 1.5.7, the end of the attribute name). |
|||
Adding this modifier lowers the precedence so that an assignment in the document still wins out. |
|||
We sometimes refer to this as "`soft setting`" the attribute. |
|||
This feature can be useful for assigning default values for attribute, but still letting the document control its own fate. |
|||
|
|||
NOTE: The `@` modifier is removed before the assignment is made. |
|||
|
|||
Here's an example that shows how to set the `imagesdir` from the CLI with a lower precedence: |
|||
|
|||
$ asciidoctor -a imagesdir=images@ doc.adoc |
|||
|
|||
Since 1.5.7, you can place the modifier at the end of the attribute name: |
|||
|
|||
$ asciidoctor -a imagesdir@=images doc.adoc |
|||
|
|||
It's now possible to override the value of the `imagesdir` attribute from within the document: |
|||
|
|||
[source,asciidoc] |
|||
---- |
|||
= Document Title |
|||
:imagesdir: new/path/to/images |
|||
---- |
|||
|
|||
Let's update the attribute assignment precedence list defined earlier to reflect this additional rule: |
|||
|
|||
* An attribute passed to the API or CLI |
|||
* An attribute defined in the document |
|||
* An attribute passed to the API or CLI whose value (or, since 1.5.7, name) ends in `@` |
|||
* The default value of the attribute, if applicable |
|||
|
|||
Regardless of whether the precedence modifier is applied, an attribute assignment always overrides the default value. |
|||
// end::order[] |
|||
File diff suppressed because it is too large
@ -0,0 +1,144 @@ |
|||
[#charref-attributes] |
|||
= Predefined Attributes for Character Replacements |
|||
|
|||
[#charref-attributes-table] |
|||
// tag::table[] |
|||
.Predefined attributes for character replacements ^[1][2][3]^ |
|||
[width="75%", cols="^4m,^3l,^3"] |
|||
|=== |
|||
|Attribute name |Replacement text |Appearance |
|||
|
|||
|blank |
|||
e|nothing |
|||
|{empty} |
|||
|
|||
|empty |
|||
e|nothing |
|||
|{empty} |
|||
|
|||
|sp |
|||
e|single space |
|||
|{sp} |
|||
|
|||
|nbsp |
|||
|  |
|||
|{nbsp} |
|||
|
|||
|zwsp^[4]^ |
|||
|​ |
|||
|{zwsp} |
|||
|
|||
|wj^[5]^ |
|||
|⁠ |
|||
|{wj} |
|||
|
|||
|apos |
|||
|' |
|||
|{apos} |
|||
|
|||
|quot |
|||
|" |
|||
|{quot} |
|||
|
|||
|lsquo |
|||
|‘ |
|||
|{lsquo} |
|||
|
|||
|rsquo |
|||
|’ |
|||
|{rsquo} |
|||
|
|||
|ldquo |
|||
|“ |
|||
|{ldquo} |
|||
|
|||
|rdquo |
|||
|” |
|||
|{rdquo} |
|||
|
|||
|deg |
|||
|° |
|||
|{deg} |
|||
|
|||
|plus |
|||
|+ |
|||
|{plus} |
|||
|
|||
|brvbar |
|||
|¦ |
|||
|¦ |
|||
|
|||
|vbar |
|||
|\| |
|||
|{vbar} |
|||
|
|||
|amp |
|||
|& |
|||
|& |
|||
|
|||
|lt |
|||
|< |
|||
|< |
|||
|
|||
|gt |
|||
|> |
|||
|> |
|||
|
|||
|startsb |
|||
|[ |
|||
|[ |
|||
|
|||
|endsb |
|||
|] |
|||
|] |
|||
|
|||
|caret |
|||
|^ |
|||
|^ |
|||
|
|||
|asterisk |
|||
|* |
|||
|* |
|||
|
|||
|tilde |
|||
|~ |
|||
|~ |
|||
|
|||
|backslash |
|||
|\ |
|||
|\ |
|||
|
|||
|backtick |
|||
|` |
|||
|` |
|||
|
|||
|two-colons |
|||
|:: |
|||
|:: |
|||
|
|||
|two-semicolons |
|||
|;; |
|||
|;; |
|||
|
|||
|cpp |
|||
|C++ |
|||
|C++ |
|||
|=== |
|||
|
|||
^[1]^ Some replacements are Unicode characters, whereas others are numeric character references (e.g., \"). |
|||
These character references are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser). |
|||
It's up to the converter to transform the reference into something the renderer understands (something both the man page and PDF converter handle). |
|||
|
|||
^[2]^ Asciidoctor does not prevent you from reassigning predefined attributes. |
|||
However, it's best to treat them as read-only unless the output format requires the use of a different encoding scheme. |
|||
These attributes are an effective tool for decoupling content and presentation. |
|||
|
|||
^[3]^ Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., \€ resolves to €). |
|||
However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. |
|||
Our recommendation is avoid using named character references--with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). |
|||
Instead, use numeric character references (e.g., \€). |
|||
|
|||
^[4]^ The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary. |
|||
|
|||
^[5]^ The word joiner (WJ) is a code point in Unicode that prevents a line break at its position. |
|||
// end::table[] |
|||
@ -0,0 +1,156 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual appendix B attribute calatog |
|||
//// |
|||
[#env-attributes] |
|||
= Environment Attributes |
|||
|
|||
Asciidoctor automatically assigns values to various document attributes whenever a document is loaded or converted. |
|||
These attributes, termed [.term]_environment attributes_, provide information about the runtime environment, such as how, where and when the document is being processed. |
|||
Like other document attributes, environment attributes can be referenced whereever attribute references are permitted. |
|||
It's recommended that you treat these attributes as read only. |
|||
|
|||
[#env-attributes-table] |
|||
// tag::table[] |
|||
.Environment attributes |
|||
[cols="1m,2,1m"] |
|||
|=== |
|||
|Attribute |Description |Example Value |
|||
|
|||
|asciidoctor |
|||
|Set if the current processor is Asciidoctor. |
|||
|{asciidoctor} |
|||
|
|||
|asciidoctor-version |
|||
|Asciidoctor version. |
|||
|{asciidoctor-version} |
|||
|
|||
|backend |
|||
|Backend used to create the output file. |
|||
|html5 |
|||
|
|||
|basebackend |
|||
|The backend value minus any trailing numbers. |
|||
For example, if the backend is `docbook5`, the basebackend is `docbook`. |
|||
|html |
|||
|
|||
|docdate |
|||
|Last modified date of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ |
|||
|2019-01-04 |
|||
|
|||
|docdatetime |
|||
|Last modified date and time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ |
|||
|2019-01-04 19:26:06 UTC |
|||
|
|||
|docdir |
|||
|Full path of the directory that contains the source document. |
|||
|/home/user/docs |
|||
|
|||
|docfile |
|||
|Full path of the source document. |
|||
|/home/user/docs/userguide.adoc |
|||
|
|||
|docfilesuffix |
|||
|File extension of the source document, including the leading period. |
|||
_Introduced in 1.5.6._ |
|||
|.adoc |
|||
|
|||
|docname |
|||
|Root name of the source document (no leading path or file extension). |
|||
|userguide |
|||
|
|||
|doctime |
|||
|Last modified time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ |
|||
|19:26:06 UTC |
|||
|
|||
|doctype |
|||
|Document type (article, book or manpage). |
|||
|article |
|||
|
|||
|docyear |
|||
|Year that the document was last modified.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^ |
|||
|2018 |
|||
|
|||
|embedded |
|||
|Set if content is being converted to an embeddable document (body only). |
|||
| |
|||
|
|||
|filetype |
|||
|File extension of the output file name (without leading period). |
|||
|html |
|||
|
|||
|htmlsyntax |
|||
|Syntax used when generating the HTML output (html or xhtml). |
|||
|html |
|||
|
|||
|localdate |
|||
|Date when the document was converted.^[<<note_sourcedateepoch,2>>]^ |
|||
|2019-02-17 |
|||
|
|||
|localdatetime |
|||
|Date and time when the document was converted.^[<<note_sourcedateepoch,2>>]^ |
|||
|2019-02-17 19:31:05 UTC |
|||
|
|||
|localtime |
|||
|Time when the document was converted.^[<<note_sourcedateepoch,2>>]^ |
|||
|19:31:05 UTC |
|||
|
|||
|localyear |
|||
|Year when the document was converted.^[<<note_sourcedateepoch,2>>]^ |
|||
|2018 |
|||
|
|||
|outdir |
|||
|Full path of the output directory. |
|||
|/home/user/docs/dist |
|||
|
|||
|outfile |
|||
|Full path of the output file. |
|||
|/home/user/docs/dist/userguide.html |
|||
|
|||
|outfilesuffix |
|||
|File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.). |
|||
(The value is not updated to match the file extension of the output file when one is specified explicitly). |
|||
_Safe to modify._ |
|||
|.html |
|||
|
|||
|safe-mode-level |
|||
|Numeric value of the safe mode setting. |
|||
(UNSAFE=0, SAFE=10, SERVER=10, SECURE=20). |
|||
|20 |
|||
|
|||
|safe-mode-name |
|||
|Textual value of the safe mode setting. |
|||
|SERVER |
|||
|
|||
|safe-mode-unsafe |
|||
|Set if the safe mode is UNSAFE. |
|||
| |
|||
|
|||
|safe-mode-safe |
|||
|Set if the safe mode is SAFE. |
|||
| |
|||
|
|||
|safe-mode-server |
|||
|Set if the safe mode is SERVER. |
|||
| |
|||
|
|||
|safe-mode-secure |
|||
|Set if the safe mode is SECURE. |
|||
| |
|||
|
|||
|user-home |
|||
|Home directory of the current user. |
|||
Resolves to `.` if the safe mode is SERVER or greater. |
|||
|/home/user |
|||
|=== |
|||
|
|||
[[note_docdatetime]]^[1]^ Only reflects the last modified time of the source document file. |
|||
It does not consider the last modified time of files which are included. |
|||
|
|||
[[note_sourcedateepoch]]^[2]^ If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable. |
|||
This override offers one way to make the conversion reproducible. |
|||
See https://reproducible-builds.org/specs/source-date-epoch/ for more information about the SOURCE_DATE_EPOCH environment variable. |
|||
Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., `-0600`) or UTC if the time zone offset is 0). |
|||
To force the use of UTC, set the `TZ=UTC` environment variable when invoking Asciidoctor. |
|||
// end::table[] |
|||
@ -0,0 +1,118 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Header |
|||
//// |
|||
|
|||
The author of a document is listed on the line beneath the document's title. |
|||
An optional email address or URL can follow an author's name inside angle brackets. |
|||
|
|||
Let's add an author with her email address to the document below. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-author.adoc[tag=base] |
|||
---- |
|||
|
|||
.Result: Rendered author and email information displayed on the byline and referenced in the document's body |
|||
==== |
|||
image::author-email.png[Author and email attributes] |
|||
==== |
|||
|
|||
As you can see in the example above, Asciidoctor uses the author's name and email to assign values to a number of built-in attributes that can be used throughout the document's body. |
|||
These attributes include: |
|||
|
|||
`author`:: |
|||
The author's full name, which includes all of the characters or words prior to a semicolon (`;`), angle bracket (`<`) or the end of the line. |
|||
|
|||
`firstname`:: |
|||
The first word in the author attribute. |
|||
|
|||
`lastname`:: |
|||
The last word in the author attribute. |
|||
|
|||
`middlename`:: |
|||
If a firstname and lastname are present, any remaining words or characters found between these attributes are assigned to the middlename attribute. |
|||
|
|||
`authorinitials`:: |
|||
The first character of the firstname, middlename, and lastname attributes. |
|||
|
|||
`email`:: |
|||
An email address, delimited by angle brackets (`<>`). |
|||
|
|||
If one or more of the author's names consists of more than one word, use an underscore (`_`) between the words you want to adjoin. |
|||
For example, the author of the following document has a compound last name. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-author.adoc[tag=2-mid] |
|||
---- |
|||
|
|||
.Result: Rendered author information when author has a compound name |
|||
==== |
|||
image::author-compound.png[Compound author name attributes] |
|||
==== |
|||
|
|||
Alternatively, the author and email attributes can be set explicitly in the header. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-author.adoc[tag=attr] |
|||
---- |
|||
|
|||
.Result: Rendered author information when author and email attributes are explicitly set |
|||
==== |
|||
image::author-email-long.png[Author and email attributes] |
|||
==== |
|||
|
|||
The `html5` and `docbook` converters can convert documents with multiple authors. |
|||
Multiple authors and their emails are separated by semicolons (`;`) when they're listed on the same line. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-author.adoc[tag=multi] |
|||
---- |
|||
<1> To reference the additional authors in the document body, the author attributes are appended with an underscore (`+_+`) followed by the position of the author in the author information list (i.e. Lazarus het Draeke is the second author in the list so his author attributes are appended with a 2). |
|||
|
|||
.Result: Rendered author information when document has multiple authors |
|||
==== |
|||
image::multi-author.png[Multiple author and email attributes] |
|||
==== |
|||
|
|||
//// |
|||
If you want to enter multiple authors and their emails as attribute entries, the attribute names are as follows: |
|||
|
|||
[source] |
|||
---- |
|||
include::multi-author-email-long.adoc[] |
|||
---- |
|||
|
|||
.Result |
|||
==== |
|||
image::multi-author-email-long.png[Multiple author and email attributes] |
|||
==== |
|||
|
|||
Where does `authored` (empty string '' if {author} or {email} defined) fit in? |
|||
//// |
|||
|
|||
==== Attribute references in the author line |
|||
|
|||
The implicit author line was not intended to support arbitrary placement of attribute references. |
|||
While attribute references are replaced in the author line (as part of the header substitution group), they aren't substituted until _after_ the line is parsed. |
|||
This ordering can sometimes produce undesirable or surprising results. |
|||
It's best to use the author line strictly as a shorthand for defining a fixed author and email. |
|||
|
|||
If you do need to use attribute references in the author or email value, you should revert to defining the attributes explicitly using attribute entries. |
|||
|
|||
.Using attribute references to set author and email |
|||
[source] |
|||
---- |
|||
= Document Title |
|||
:author_name: ACME Industries |
|||
:author_email: info@acme.com |
|||
:author: {author_name} |
|||
:email: {author_email} |
|||
---- |
|||
|
|||
Just remember that the author line is for static text. |
|||
Once you graduate beyond static text, you should switch to using attribute entries to define the built-in author attributes, which will give you much more power. |
|||
@ -0,0 +1,68 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Asciidoctor's most notable benefits |
|||
|
|||
The primary benefits and supporting features of the application. |
|||
//// |
|||
|
|||
While Asciidoctor aims to offer full compliance with the AsciiDoc syntax, it's more than just a clone. |
|||
|
|||
.Built-in and custom templates |
|||
Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook output that is structurally equivalent to what AsciiDoc produces. |
|||
Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem. |
|||
Custom template rendering is handled by the {uri-tilt}[Tilt] template abstraction library. |
|||
Tilt is one of the most popular gems in the Ruby ecosystem. |
|||
|
|||
.Parser and object model |
|||
Leveraging the Ruby stack isn't the only benefit of Asciidoctor. |
|||
Unlike the AsciiDoc Python implementation, Asciidoctor parses and converts the source document in discrete steps. |
|||
This makes conversion optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles. |
|||
Developers can use the full power of the Ruby programming language to play with the content in the document. |
|||
|
|||
.Performance and security |
|||
No coverage of Asciidoctor would be complete without mention of its _speed_. |
|||
Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. |
|||
It loads, parses, and converts documents a *100 times as fast* as the Python implementation. |
|||
That's good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. |
|||
Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments. |
|||
|
|||
.Beyond Ruby |
|||
Asciidoctor's usage is not limited to the Ruby community. |
|||
Thanks to {uri-jruby}[JRuby], a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well. |
|||
Plugins are available for {uri-org}/asciidoctor-maven-plugin[Apache Maven], {uri-org}/asciidoctor-gradle-plugin[Gradle], and {uri-rewrite}[Rewrite]. |
|||
These plugins are based on the {uri-asciidoctorj}[AsciidoctorJ] for Asciidoctor. |
|||
|
|||
Asciidoctor also ships with a command line interface (CLI). |
|||
The Asciidoctor CLI, {uri-man}[asciidoctor], is a drop-in replacement for the `asciidoc.py` script from the AsciiDoc Python distribution. |
|||
|
|||
//// |
|||
|
|||
AsciiDoc is about being able to focus on expressing your ideas, writing with ease and passing on knowledge without the distraction of complex applications or angle brackets. |
|||
In other words, it's about discovering _writing zen_. |
|||
|
|||
AsciiDoc works because: |
|||
|
|||
- It's readable |
|||
- It's concise |
|||
- It's comprehensive |
|||
- It's extensible |
|||
- It produces beautiful output (HTML, DocBook, PDF, ePub and more) |
|||
|
|||
AsciiDoc is both easy to write and easy to read (in raw form). |
|||
It's also easy to proof and edit. |
|||
After all, it's plain text, just like that familiar e-mail. |
|||
|
|||
The AsciiDoc syntax is intuitive because it recognizes time-tested, plain text conventions for marking up or structuring the text. |
|||
The punctuation was carefully chosen to look like what it means. |
|||
A user unfamiliar with AsciiDoc can figure out the structure and semantics (i.e., what you mean) just by looking at it. |
|||
Best of all, *it only requires a text editor to read or write*. |
|||
|
|||
AsciiDoc allows you to focus on the actual writing and only worry about tweaking the output when you are ready to render the document. |
|||
The plain-text of an AsciiDoc document is easily converted into a variety of output formats, beautifully formatted, without having to rewrite the content. |
|||
|
|||
Copy text from an e-mail into a document and see how quickly you can turn it into documentation. |
|||
Almost immediately, you'll find your writing zen and enjoy the rewarding experience of sharing knowledge. |
|||
|
|||
Live or die by documentation? Live. |
|||
//// |
|||
@ -0,0 +1,48 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Bibliography |
|||
//// |
|||
|
|||
AsciiDoc has basic support for bibliographies. |
|||
AsciiDoc doesn't concern itself with the structure of the bibliography entry itself, which is entirely freeform. |
|||
What it does is provide a way to make references to the entries from the same document and output the bibliography with proper semantics for processing by other toolchains (such as DocBook). |
|||
|
|||
In order to reference a bibliography entry, you need to assign a _non-numeric_ label to the entry. |
|||
To assign this label, prefix the entry with the label enclosed in a pair of triple square brackets (e.g., `+[[[label]]]+`). |
|||
We call this a bibliography anchor. |
|||
Using this label, you can then reference the entry from anywhere above the bibliography in the same document using the normal cross reference syntax (e.g., `+<<label>>+`). |
|||
|
|||
By default, the bibliography anchor and reference to the bibliography entry is converted to `[<label>]`, where <label> is the ID of the entry. |
|||
If you specify xreftext on the bibliography anchor (e.g., `+[[[label,xreftext]]]+`), the bibliography anchor and reference to the bibliography entry converts to `[<xreftext>]` instead. |
|||
|
|||
If you want the bibliography anchor and reference to appear as a number, assign the number of the entry using the xreftext. |
|||
For example, `+[[[label,1]]]+` will be converted to `[1]`. |
|||
|
|||
The bibliography entries themselves are declared as items in an unordered list. |
|||
You promote a normal unordered list to a bibliography list by adding the `bibliography` style. |
|||
However, to be conforming, bibliography lists must be contained inside a bibliography section. |
|||
A bibliography section is a section with the special `bibliography` style. |
|||
By adding the `bibliography` style to the section, you implicitly add it to each unordered list in that section. |
|||
|
|||
WARNING: If the bibliography style is used on an unordered list outside of a bibliography section, the resulting behavior is undefined. |
|||
|
|||
Let's consider an example. |
|||
|
|||
.Bibliography with inbound references |
|||
[source] |
|||
---- |
|||
include::ex-biblio.adoc[tag=base] |
|||
---- |
|||
|
|||
This renders as: |
|||
|
|||
|=== |
|||
a| |
|||
include::ex-biblio.adoc[tag=base] |
|||
|=== |
|||
|
|||
If you want more advanced features such as automatic numbering and custom citation styles, try the {uri-org}/asciidoctor-bibtex[asciidoctor-bibtex] project. |
|||
|
|||
TIP: To escape a bibliography anchor anywhere in the text, use the syntax `[\[[word]]]`. |
|||
This prevents the anchor from being matched as a bibliography anchor or a normal anchor. |
|||
@ -0,0 +1,94 @@ |
|||
//// |
|||
Table of blocks, block names, block delimiters, and their substitutions |
|||
|
|||
User Manual: Blocks |
|||
//// |
|||
|
|||
[cols="1,1m,1m,3,1"] |
|||
|=== |
|||
|Block |Block Name |Delimiter |Purpose |Substitutions |
|||
|
|||
|Admonition |
|||
|++[<LABEL>]++ |
|||
|++====++ |
|||
|Aside content that demands special attention; often labeled with a tag or icon |
|||
|Normal |
|||
|
|||
|Comment |
|||
d|N/A |
|||
|++////++ |
|||
|Private notes that are not displayed in the output |
|||
|None |
|||
|
|||
|Example |
|||
|++[example]++ |
|||
|++====++ |
|||
|Designates example content or defines an admonition block |
|||
|Normal |
|||
|
|||
|Fenced |
|||
d|N/A |
|||
|++```++ |
|||
|Source code or keyboard input is displayed as entered |
|||
|Verbatim |
|||
|
|||
|Listing |
|||
|++[listing]++ |
|||
|++----++ |
|||
|Source code or keyboard input is displayed as entered |
|||
|Verbatim |
|||
|
|||
|Literal |
|||
|++[literal]++ |
|||
|++....++ |
|||
|Output text is displayed exactly as entered |
|||
|Verbatim |
|||
|
|||
|Open |
|||
d|Most block names |
|||
|++--++ |
|||
|Anonymous block that can act as any block except _passthrough_ or _table_ blocks |
|||
|Varies |
|||
|
|||
|Passthrough |
|||
|++[pass]++ |
|||
|pass:[++++] |
|||
|Unprocessed content that is sent directly to the output |
|||
|None |
|||
|
|||
|Quote |
|||
|++[quote]++ |
|||
|++____++ |
|||
|A quotation with optional attribution |
|||
|Normal |
|||
|
|||
|Sidebar |
|||
|++[sidebar]++ |
|||
|++****++ |
|||
|Aside text and content displayed outside the flow of the document |
|||
|Normal |
|||
|
|||
|Source |
|||
|++[source]++ |
|||
|++----++ |
|||
|Source code or keyboard input to be displayed as entered |
|||
|Verbatim |
|||
|
|||
|Stem |
|||
|++[stem]++ |
|||
|pass:[++++] |
|||
|Unprocessed content that is sent directly to an interpreter (such as AsciiMath or LaTeX math) |
|||
|None |
|||
|
|||
|Table |
|||
d|N/A |
|||
|++\|===++ |
|||
|Displays tabular content |
|||
|Varies |
|||
|
|||
|Verse |
|||
|++[verse]++ |
|||
|++____++ |
|||
|A verse with optional attribution |
|||
|Normal |
|||
|=== |
|||
@ -0,0 +1,151 @@ |
|||
//// |
|||
General Block Documentation |
|||
|
|||
User manual: Blocks |
|||
//// |
|||
|
|||
NOTE: Section Pending |
|||
|
|||
=== Title |
|||
|
|||
You can assign a title to any paragraph, list, delimited block, or block macro. |
|||
In most cases, the title is displayed immediately above the content. |
|||
If the content is a figure or image, the title is displayed below the content. |
|||
|
|||
A block title is defined on a line above the element. |
|||
The line must begin with a dot (`.`) and be followed immediately by the title text. |
|||
|
|||
Here's an example of a list with a title: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-block.adoc[tag=list-title] |
|||
---- |
|||
|
|||
=== Metadata |
|||
|
|||
In addition to a title, a block can be assigned additional metadata including: |
|||
|
|||
* Id (i.e., anchor) |
|||
* Block name (first positional attribute) |
|||
* Block attributes |
|||
|
|||
Here's an example of a quote block with metadata: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-block.adoc[tag=meta-co] |
|||
---- |
|||
<1> Title: Gettysburg Address |
|||
<2> ID: gettysburg, see <<anchordef>> |
|||
<3> Block name: quote |
|||
<4> attribution: Abraham Lincoln (Named block attribute) |
|||
<5> citetitle: Address delivered at the dedication of the Cemetery at Gettysburg (Named block attribute) |
|||
|
|||
TIP: A block can have multiple block attribute lines. |
|||
The attributes will be aggregated. |
|||
If there is a name conflict, the last attribute defined wins. |
|||
|
|||
Some metadata is used as supplementary content, such as the title, whereas other metadata controls how the block is converted, such as the block name. |
|||
|
|||
//// |
|||
Block id |
|||
|
|||
NOTE: Pending |
|||
|
|||
Block Style |
|||
|
|||
A block style is the first positional attribute in the block attribute list. |
|||
//// |
|||
|
|||
=== Delimited blocks |
|||
|
|||
The AsciiDoc syntax provides a set of components for including non-paragraph text, such as block quotes, source code listings, sidebars and tables, in your document. |
|||
These components are referred to as _delimited blocks_ because they are surrounded by delimiter lines (e.g., `+****+`). |
|||
|
|||
Here's an example of a sidebar block: |
|||
|
|||
---- |
|||
**** |
|||
sidebar block |
|||
**** |
|||
---- |
|||
|
|||
Within the boundaries of a delimited block, you can enter any content or blank lines. |
|||
The block doesn't end until the ending delimiter is found. |
|||
The delimiters around the block determine the type of block, how the content is processed and converted, and what elements are used to wrap the content in the output. |
|||
|
|||
==== Delimiter lines |
|||
|
|||
The boundaries of a delimited block _must be balanced_. |
|||
In other words, the opening delimiter line must be the same length as the closing delimiter line. |
|||
|
|||
For example, the following delimited block is not balanced and therefore invalid: |
|||
|
|||
---- |
|||
******** |
|||
invalid sidebar block |
|||
**** |
|||
---- |
|||
|
|||
When the processor encounters the previous example, it will put the remainder of the content in the document inside the delimited block (without warning, currently). |
|||
As far as the processor is concerned, the closing delimiter is just a line of content. |
|||
If you want the closing delimiter to be matched, it must be the same length as the opening delimiter. |
|||
|
|||
---- |
|||
**** |
|||
valid sidebar block |
|||
**** |
|||
---- |
|||
|
|||
The AsciiDoc Python processor did not require the delimiters to be balanced, but also never documented that this was permissible. |
|||
We view AsciiDoc Python's behavior of matching unbalanced delimited blocks to be a bug and therefore do not allow it in Asciidoctor. |
|||
|
|||
==== Optional delimiters |
|||
|
|||
If the content is contiguous (not interrupted by blank lines), you can forgo the use of the block delimiters and instead use the block name above a paragraph to repurpose it as one of the delimited block types. |
|||
|
|||
This format is often used for single-line listings: |
|||
|
|||
[source] |
|||
.... |
|||
include::ex-block.adoc[tag=opt-listing] |
|||
.... |
|||
|
|||
or single-line quotes: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-block.adoc[tag=quote-name] |
|||
---- |
|||
|
|||
==== Masquerading blocks |
|||
|
|||
Some blocks can masquerade as other blocks, a feature which is controlled by the block name. |
|||
|
|||
==== Nesting blocks |
|||
|
|||
You can nest blocks inside each other. |
|||
To nest blocks of the same type, add a pair of extra symbols to the delimiter. |
|||
For example: |
|||
|
|||
---- |
|||
==== |
|||
This is an example |
|||
====== |
|||
This is an example inside an example |
|||
====== |
|||
==== |
|||
---- |
|||
|
|||
=== Built-in blocks summary |
|||
|
|||
The following table identifies the built-in block names and delimited blocks syntax, their purposes, and the substitutions performed on their contents. |
|||
|
|||
include::block-name-table.adoc[] |
|||
|
|||
This table shows the substitutions performed by each substitution group referenced in the previous table. |
|||
|
|||
include::subs-group-table.adoc[] |
|||
|
|||
TIP: Surround an attribute value with single quotes in order to apply normal substitutions. |
|||
@ -0,0 +1,44 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
You may group the sections of your document into parts when you set the `doctype` to `book`. |
|||
In fact, parts can only be used when the `doctype` is `book`. |
|||
|
|||
When a document has its `doctype` set to `book` and contains at least one part, it implicitly becomes a multi-part book. |
|||
There is no dedicated doctype value for a multi-part book to distinguish it from a regular book. |
|||
That distinction is made by the content. |
|||
|
|||
Part titles are specified with a single equals sign (`=`), the equivalent to the structure of a document title (i.e., level-0 section). |
|||
Each part must contain at least one section (a chapter or special section). |
|||
Immediately after the part title, you may insert an optional introduction, which is designated by the `partintro` style. |
|||
|
|||
[source] |
|||
---- |
|||
[partintro] |
|||
.Optional part introduction title |
|||
-- |
|||
Optional part introduction goes here. |
|||
-- |
|||
---- |
|||
|
|||
A part can also include its own preface, bibliography, glossary and index. |
|||
|
|||
[source] |
|||
---- |
|||
include::multi-special-ex.adoc[tag=part] |
|||
---- |
|||
|
|||
When using the PDF converter (i.e., Asciidoctor PDF), the value of the `chapter-label` attribute (followed by a space) is automatically added to the beginning of the chapter title. |
|||
A chapter title is a level-1 section title when the doctype is book. |
|||
|
|||
You can modify this prefix by redefining the `chapter-label` attribute. |
|||
|
|||
[source] |
|||
---- |
|||
:chapter-label: Chapter ~ |
|||
---- |
|||
|
|||
To use no prefix, set the value to blank. |
|||
@ -0,0 +1,27 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: callouts: Callouts don't get caught in copy |
|||
//// |
|||
|
|||
In versions prior to Asciidoctor 0.1.4, when a reader visiting an HTML page generated by Asciidoctor selected source code from a listing that contained callouts and copied it, the callout numbers would get caught up in the copied text. |
|||
If the reader pasted that code and tried to run it, likely the extra characters from the callouts would cause compile or runtime errors. |
|||
|
|||
Asciidoctor uses CSS to prevent callouts from being selected. |
|||
|
|||
On the other side of the coin, you don't want the callout annotations or CSS messing up your raw source code either. |
|||
You can tuck your callouts neatly behind line comments. |
|||
Asciidoctor will recognize the line comments characters in front of a callout number, optionally offset by a space, and remove them when converting the document. |
|||
|
|||
Here are the line comments that are supported: |
|||
|
|||
[source,subs=specialcharacters] |
|||
.... |
|||
include::ex-callout.adoc[tag=b-nonselect] |
|||
.... |
|||
|
|||
Here's how it looks when rendered: |
|||
|
|||
==== |
|||
include::ex-callout.adoc[tag=b-nonselect] |
|||
==== |
|||
@ -0,0 +1,14 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: callouts: Callout icons |
|||
//// |
|||
|
|||
The font icons setting also enables callout icons drawn using CSS. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-callout.adoc[tag=co-icon] |
|||
---- |
|||
<1> Activates the font-based icons in the HTML5 backend. |
|||
<2> Admonition block that uses a font-based icon. |
|||
@ -0,0 +1,24 @@ |
|||
Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block. |
|||
|
|||
Each callout number used in a verbatim block must appear twice. |
|||
The first use, which goes within the verbatim block, marks the line being annotated (i.e., the target). |
|||
The second use, which goes below the verbatim block, defines the annotation text. |
|||
Multiple callout numbers may be used on a single line. |
|||
|
|||
IMPORTANT: The callout number (at the target) must be placed at the end of the line. |
|||
|
|||
Here's a basic example of a verbatim block that uses callouts: |
|||
|
|||
[source,subs=-callouts] |
|||
.... |
|||
include::ex-callout.adoc[tag=basic] |
|||
.... |
|||
|
|||
Here's how this example gets rendered: |
|||
|
|||
==== |
|||
include::ex-callout.adoc[tag=basic] |
|||
==== |
|||
|
|||
Since callout number can interfere with the syntax of the code they are annotating, Asciidoctor provides several features to hide the callout numbers from both the source and the converted document. |
|||
The sections that follow detail these features. |
|||
@ -0,0 +1,25 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: callouts: XML-friendly callouts |
|||
//// |
|||
|
|||
XML doesn't have line comments, so our "`tuck the callout behind a line comment`" trick doesn't work here. |
|||
To use callouts in XML, you must place the callout's angled brackets around the the XML comment and callout number. |
|||
|
|||
Here's how it appears in a listing: |
|||
|
|||
[source,subs=specialcharacters] |
|||
.... |
|||
include::ex-callout.adoc[tag=source-xml] |
|||
.... |
|||
|
|||
Here's how it looks when rendered: |
|||
|
|||
==== |
|||
include::ex-callout.adoc[tag=source-xml] |
|||
==== |
|||
|
|||
Notice the comment has been replaced with a circled number that cannot be selected (if not using font icons it will be |
|||
rendered differently and selectable). |
|||
Now both you and the reader can copy and paste XML source code containing callouts without worrying about errors. |
|||
@ -0,0 +1,49 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Unordered lists: Checklists |
|||
//// |
|||
|
|||
List items can be marked complete using checklists. |
|||
|
|||
Checklists (i.e., task lists) are unordered lists that have items marked as checked (`[*]` or `[x]`) or unchecked (`[ ]`). |
|||
Here's an example: |
|||
|
|||
.Checklist syntax |
|||
[source] |
|||
---- |
|||
include::ex-ulist.adoc[tag=check] |
|||
---- |
|||
|
|||
.Rendered checklist |
|||
==== |
|||
include::ex-ulist.adoc[tag=check] |
|||
==== |
|||
|
|||
TIP: Not all items in the list have to be checklist items, as the previous example shows. |
|||
|
|||
When checklists are converted to HTML, the checkbox markup is transformed into an HTML checkbox with the appropriate checked state. |
|||
The `data-item-complete` attribute on the checkbox is set to 1 if the item is checked, 0 if not. |
|||
The checkbox is used in place of the item's bullet. |
|||
|
|||
Since HTML generated by Asciidoctor is usually static, the checkbox is set as disabled to make it appear as a simple mark. |
|||
If you want to make the checkbox interactive (i.e., clickable), add the `interactive` option to the checklist (shown here using the shorthand syntax for <<Options>>): |
|||
|
|||
.Checklist with interactive checkboxes |
|||
[source] |
|||
---- |
|||
include::ex-ulist.adoc[tag=check-int] |
|||
---- |
|||
|
|||
.Rendered checklist with interactive checkboxes |
|||
==== |
|||
include::ex-ulist.adoc[tag=check-int] |
|||
==== |
|||
|
|||
As a bonus, if you enable font-based icons, the checkbox markup (in non-interactive lists) is transformed into a font-based icon! |
|||
|
|||
.Checklist with font-based checkboxes |
|||
[source] |
|||
---- |
|||
include::ex-ulist.adoc[tag=check-icon] |
|||
---- |
|||
@ -0,0 +1,136 @@ |
|||
//== Ruby CLI Options |
|||
|
|||
// DO NOT EDIT THIS FILE |
|||
// Copy the content from asciidoctor/man/asciidoctor.adoc |
|||
|
|||
=== Security Settings |
|||
|
|||
*-B, --base-dir*=_DIR_:: |
|||
Base directory containing the document and resources. |
|||
Defaults to the directory containing the source file, or the working directory if the source is read from a stream. |
|||
When combined with the safe mode setting, can be used to chroot the execution of the program. |
|||
|
|||
*-S, --safe-mode*=_SAFE_MODE_:: |
|||
Set safe mode level: _unsafe_, _safe_, _server_ or _secure_. |
|||
Disables potentially dangerous macros in source files, such as `include::[]`. |
|||
If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script. |
|||
|
|||
*--safe*:: |
|||
Set safe mode level to _safe_. |
|||
Enables include directives, but prevents access to ancestor paths of source file. |
|||
Provided for compatibility with the asciidoc command. |
|||
If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script. |
|||
|
|||
=== Document Settings |
|||
|
|||
*-a, --attribute*=_ATTRIBUTE_:: |
|||
Define, override or delete a document attribute. |
|||
Command-line attributes take precedence over attributes defined in the source file unless the value ends with _@_. |
|||
+ |
|||
_ATTRIBUTE_ is normally formatted as a key-value pair, in the form _NAME=VALUE_. |
|||
Alternate acceptable forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unassigns the _NAME_ attribute) and _NAME=VALUE@_ (where _VALUE_ does not override value of _NAME_ attribute if it's already defined in the source document). |
|||
Values containing spaces should be enclosed in quotes. |
|||
+ |
|||
This option may be specified more than once. |
|||
|
|||
*-b, --backend*=_BACKEND_:: |
|||
Backend output file format: _html5_, _docbook5_, _docbook45_ and _manpage_ are supported out of the box. |
|||
You can also use the backend alias names _html_ (aliased to _html5_) or _docbook_ (aliased to _docbook5_). |
|||
Other values can be passed, but if Asciidoctor cannot resolve the backend to a converter, it will fail. |
|||
Defaults to _html5_. |
|||
|
|||
*-d, --doctype*=_DOCTYPE_:: |
|||
Document type: _article_, _book_, _manpage_ or _inline_. |
|||
Sets the root element when using the _docbook_ backend and the style class on the HTML body element when using the _html_ backend. |
|||
The _book_ document type allows multiple level-0 section titles in a single document. |
|||
The _manpage_ document type enables parsing of metadata necessary to produce a man page. |
|||
The _inline_ document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element. |
|||
Defaults to _article_. |
|||
|
|||
=== Document Conversion |
|||
|
|||
*-D, --destination-dir*=_DIR_:: |
|||
Destination output directory. |
|||
Defaults to the directory containing the source file, or the working directory if the source is read from a stream. |
|||
If specified, the directory is resolved relative to the working directory. |
|||
|
|||
*-E, --template-engine*=_NAME_:: |
|||
Template engine to use for the custom converter templates. |
|||
The gem with the same name as the engine will be loaded automatically. |
|||
This name is also used to build the full path to the custom converter templates. |
|||
If a template engine is not specified, it will be auto-detected based on the file extension of the custom converter templates found. |
|||
|
|||
*-e, --eruby*:: |
|||
Specifies the eRuby implementation to use for executing the custom converter templates written in ERB. |
|||
Supported values are _erb_ and _erubis_. |
|||
Defaults to _erb_. |
|||
|
|||
*-I, --load-path*=_DIRECTORY_:: |
|||
Add the specified directory to the load path, so that _-r_ can load extensions from outside the default Ruby load path. |
|||
This option may be specified more than once. |
|||
|
|||
*-n, --section-numbers*:: |
|||
Auto-number section titles. |
|||
Synonym for *--attribute sectnums*. |
|||
|
|||
*-o, --out-file*=_OUT_FILE_:: |
|||
Write output to file _OUT_FILE_. |
|||
Defaults to the base name of the input file suffixed with _backend_ extension. |
|||
The file is resolved relative to the working directory. |
|||
If the input is read from standard input or a named pipe (fifo), then the output file defaults to stdout. |
|||
If _OUT_FILE_ is _-_, then the output file is written to standard output. |
|||
|
|||
*-R, --source-dir*=_DIR_:: |
|||
Source directory. |
|||
Currently only used if the destination directory is also specified. |
|||
Used to preserve the directory structure of files converted within this directory in the destination directory. |
|||
If specified, the directory is resolved relative to the working directory. |
|||
|
|||
*-r, --require*=_LIBRARY_:: |
|||
Require the specified library before executing the processor, using the standard Ruby require. |
|||
This option may be specified more than once. |
|||
|
|||
*-s, --no-header-footer*:: |
|||
Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. |
|||
This option is useful for producing documents that can be inserted into an external template. |
|||
|
|||
*-T, --template-dir*=_DIR_:: |
|||
A directory containing custom converter templates that override one or more templates from the built-in set. |
|||
(requires _tilt_ gem) |
|||
+ |
|||
If there is a subfolder that matches the engine name (if specified), that folder is appended to the template directory path. |
|||
Similarly, if there is a subfolder in the resulting template directory that matches the name of the backend, that folder is appended to the template directory path. |
|||
+ |
|||
This option may be specified more than once. |
|||
Matching templates found in subsequent directories override ones previously discovered. |
|||
|
|||
=== Processing Information |
|||
|
|||
*--failure-level*=_LEVEL_:: |
|||
The minimum logging level that triggers a non-zero exit code (failure). |
|||
If this option is not set (default: FATAL), the program exits with a status code zero even if warnings or errors have been logged. |
|||
|
|||
*-q, --quiet*:: |
|||
Silence warnings. |
|||
|
|||
*--trace*:: |
|||
Include backtrace information on errors. |
|||
Not enabled by default. |
|||
|
|||
*-v, --verbose*:: |
|||
Verbosely print processing information and configuration file checks to stderr. |
|||
|
|||
*-t, --timings*:: |
|||
Display timings information (time to read, parse and convert). |
|||
|
|||
=== Program Information |
|||
|
|||
*-h, --help* [_TOPIC_]:: |
|||
Print the help message. |
|||
Show the command usage if _TOPIC_ is not specified (or not recognized). |
|||
Dump the Asciidoctor man page (in troff/groff format) if _TOPIC_ is _manpage_. |
|||
|
|||
*-V, --version*:: |
|||
Print program version number. |
|||
+ |
|||
`-v` can also be used if no other flags or arguments are present. |
|||
@ -0,0 +1,13 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
Book colophons list information such as the ISBN, publishing house, edition and copyright dates, legal notices and disclaimers, cover art, design, and book layout credits, and any significant production notes. |
|||
In most mass market books, the colophon is on the verso (back side) of the title page, but it can also be located at the end of the book. |
|||
|
|||
[source] |
|||
---- |
|||
include::multi-special-ex.adoc[tag=colophon] |
|||
---- |
|||
@ -0,0 +1,30 @@ |
|||
//// |
|||
Command line usage quick start for Asciidoctor |
|||
This file is included in the install-toolchain and user-manual documents |
|||
//// |
|||
|
|||
Asciidoctor's command line interface (CLI) is a drop-in replacement for the `asciidoc.py` command from the Python implementation. |
|||
|
|||
If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH. |
|||
To confirm that Asciidoctor is available, execute: |
|||
|
|||
$ asciidoctor --version |
|||
|
|||
The following information should be output in your terminal: |
|||
|
|||
Asciidoctor 1.5.6.2 [https://asciidoctor.org] |
|||
|
|||
To invoke Asciidoctor from the CLI and convert an `.adoc` file, execute: |
|||
|
|||
$ asciidoctor <asciidoc_file> |
|||
|
|||
This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the `.html` extension. |
|||
|
|||
There are many other options available, listed in <<cli-options>>. |
|||
|
|||
Full help is provided in the {uri-man}[man page] or via: |
|||
|
|||
$ asciidoctor --help |
|||
|
|||
There is also an `asciidoctor-safe` command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file. |
|||
This mode is very similar to the safe mode of `asciidoc.py`. |
|||
@ -0,0 +1,17 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: comments |
|||
//// |
|||
|
|||
.Line |
|||
---- |
|||
include::ex-comment.adoc[tag=line] |
|||
---- |
|||
|
|||
TIP: Single-line comments can be used to divide elements, such as two adjacent lists. |
|||
|
|||
.Block |
|||
---- |
|||
include::ex-comment.adoc[tag=bl] |
|||
---- |
|||
@ -0,0 +1,210 @@ |
|||
//// |
|||
== Conditional Preprocessor Directives |
|||
|
|||
Included in: |
|||
|
|||
- User manual |
|||
//// |
|||
You can include or exclude lines of text in your document using one of the following conditional preprocessor directives: |
|||
|
|||
* ifdef |
|||
* ifndef |
|||
* ifeval |
|||
|
|||
These directives tell the processor whether to include the enclosed content based on certain conditions. |
|||
The conditions are based on the presence or value of document attributes. |
|||
|
|||
For example, say you want to include a certain section of content only when converting to HTML. |
|||
Conditional preprocessor directives make this possible. |
|||
You simply check for the presence of the `basebackend-html` attribute using an `ifdef` directive. |
|||
Details of this example, as well as others, are described in the following sections. |
|||
|
|||
=== Processing |
|||
|
|||
Although a conditional preprocessor directive looks like a block macro, it's not a macro and therefore not processed like one. |
|||
Instead, it's a _preprocessor_ directive, just like `include`. |
|||
It's important to understand the distinction. |
|||
|
|||
A preprocessor directive is processed when the lines are read, but before the document structure is parsed. |
|||
Therefore, it's _not_ aware of the surrounding document structure. |
|||
A preprocessor directive merely adds lines to the reader or takes lines away. |
|||
The conditional preprocessor directives determine which lines to add and which ones to take away based on the condition. |
|||
|
|||
If you don't want a conditional preprocessor directive to be processed, you must escape it using a backslash. |
|||
|
|||
\ifdef::just-an-example[] |
|||
|
|||
Escaping the directive is necessary _even if it appears in a verbatim block_ since it's not aware of the surrounding document structure. |
|||
|
|||
=== ifdef Directive |
|||
|
|||
Content between the `ifdef` and `endif` directives gets included if the specified attribute is set: |
|||
|
|||
.ifdef example |
|||
---- |
|||
\ifdef::env-github[] |
|||
This content is for GitHub only. |
|||
\endif::[] |
|||
---- |
|||
|
|||
The syntax of the start directive is `ifdef::<attribute>[]`, where `<attribute>` is the name of an attribute. |
|||
|
|||
Keep in mind that the content is not limited to a single line. |
|||
You can have any amount of content between the `ifdef` and `endif` directives. |
|||
|
|||
If you have a large amount of content inside the `ifdef` directive, you may find it more readable to use the long-form version of the directive, in which the attribute (aka condition) is referenced again in the `endif` directive. |
|||
|
|||
.ifdef long-form example |
|||
---- |
|||
\ifdef::env-github[] |
|||
This content is for GitHub only. |
|||
|
|||
So much content in this section, I'd get confused reading the source without the closing `ifdef` directive. |
|||
|
|||
It isn't necessary for short blocks, but if you are conditionally including a section it may be something worth considering. |
|||
|
|||
Other readers reviewing your docs source code may go cross-eyed when reading your source docs if you don't. |
|||
\endif::env-github[] |
|||
---- |
|||
|
|||
TIP: A great example of long-form conditional formatting is the source of this user manual! |
|||
We use it to show and hide entire sections when building individual content for separate guides. |
|||
|
|||
If you're only dealing with a single line of text, you can put the content directly inside the square brackets and drop the `endif` directive. |
|||
|
|||
.ifdef single line example |
|||
---- |
|||
\ifdef::revnumber[This document has a version number of {revnumber}.] |
|||
---- |
|||
|
|||
The single-line block above is equivalent to this formal `ifdef` directive: |
|||
|
|||
[source] |
|||
---- |
|||
\ifdef::revnumber[] |
|||
This document has a version number of {revnumber}. |
|||
\endif::[] |
|||
---- |
|||
|
|||
=== ifndef Directive |
|||
|
|||
`ifndef` is the logical opposite of `ifdef`. |
|||
Content between `ifndef` and `endif` gets included only if the specified attribute is _not_ set: |
|||
|
|||
.ifndef Example |
|||
---- |
|||
\ifndef::env-github[] |
|||
This content is not shown on GitHub. |
|||
\endif::[] |
|||
---- |
|||
|
|||
The syntax of the start directive is `ifndef::<attribute>[]`, where `<attribute>` is the name of an attribute. |
|||
|
|||
The `ifndef` directive supports the same single-line and long-form variants as `ifdef`. |
|||
|
|||
=== Checking multiple attributes (ifdef and ifndef only) |
|||
|
|||
Both the `ifdef` and `ifndef` directives accept multiple attribute names. |
|||
The combinator can be "`and`" or "`or`". |
|||
|
|||
Any attribute (or):: |
|||
Multiple comma-separated (,) directive names evaluate to true, allowing the content to be included, if one or more of the directives is defined. |
|||
Otherwise the content is not included. |
|||
+ |
|||
.Any attribute example |
|||
---- |
|||
\ifdef::backend-html5,backend-docbook5[Only shown when converting to HTML5 or DocBook 5.] |
|||
---- |
|||
|
|||
All attributes (and):: |
|||
Multiple plus-separated (+) directive names evaluate to true, allowing the content to be included, if all of the directives are defined. |
|||
Otherwise the content is not included. |
|||
+ |
|||
.All attributes example |
|||
---- |
|||
\ifdef::env-github+backend-html5[Only shown when converting to HTML5 on GitHub.] |
|||
---- |
|||
|
|||
The `ifndef` directive negates the results of the expression. |
|||
|
|||
WARNING: Starting in Asciidoctor 1.5.6, the operator logic in the `ifndef` directive changed to align with the behavior of AsciiDoc Python. |
|||
Specifically, when attributes are separated by commas, content is only included if none of the attributes are defined. |
|||
When attributes are separated by pluses, content is included if at least one of the attributes is undefined. |
|||
See https://github.com/asciidoctor/asciidoctor/issues/1983[issue #1983] to find the discussion about this behavior and the rationale for the change. |
|||
|
|||
=== ifeval directive |
|||
|
|||
Content between `ifeval` and `endif` gets included if the expression inside the square brackets evaluates to true. |
|||
|
|||
.ifeval example |
|||
---- |
|||
\ifeval::[{sectnumlevels} == 3] |
|||
If the `sectnumlevels` attribute has the value 3, this sentence is included. |
|||
\endif::[] |
|||
---- |
|||
|
|||
The `ifeval` directive does not have a single-line or long-form variant like `ifdef` and `ifndef`. |
|||
|
|||
==== Anatomy |
|||
|
|||
The expression consists of a left-hand value and a right-hand value with an operator in between. |
|||
|
|||
.ifeval expression examples |
|||
---- |
|||
\ifeval::[2 > 1] |
|||
... |
|||
\endif::[] |
|||
|
|||
\ifeval::["{backend}" == "html5"] |
|||
... |
|||
\endif::[] |
|||
|
|||
\ifeval::[{sectnumlevels} == 3] |
|||
... |
|||
\endif::[] |
|||
|
|||
// the value of outfilesuffix includes a leading period (e.g., .html) |
|||
\ifeval::["{docname}{outfilesuffix}" == "master.html"] |
|||
... |
|||
\endif::[] |
|||
---- |
|||
|
|||
==== Values |
|||
|
|||
Each expression value can reference the name of zero or more AsciiDoc attribute using the attribute reference syntax (for example, `+{backend}+`). |
|||
|
|||
Attribute references are resolved (substituted) first. |
|||
Once attributes references have been resolved, each value is coerced to a recognized type. |
|||
|
|||
When the expected value is a string (i.e., a string of characters), we recommend that you enclose the expression in quotes. |
|||
|
|||
The following values types are recognized: |
|||
|
|||
number:: Either an integer or floating-point value. |
|||
quoted string:: Enclosed in either single (') or double (") quotes. |
|||
boolean:: Literal value of `true` or `false`. |
|||
|
|||
===== How value type coercion works |
|||
|
|||
If a value is enclosed in quotes, the characters between the quotes are preserved and coerced to a string. |
|||
|
|||
If a value is not enclosed in quotes, it is subject to the following type coercion rules: |
|||
|
|||
* an empty value becomes nil (aka null). |
|||
* a value of `true` or `false` becomes a boolean value. |
|||
* a value of only repeating whitespace becomes a single whitespace string. |
|||
* a value containing a period becomes a floating-point number. |
|||
* any other value is coerced to an integer value. |
|||
|
|||
==== Operators |
|||
|
|||
The value on each side is compared using the operator to derive an outcome. |
|||
|
|||
`==`:: Checks if the two values are equal. |
|||
`!=`:: Checks if the two values are not equal. |
|||
`<`:: Checks whether the left-hand side is less than the right-hand side. |
|||
`+<=+`:: Checks whether the left-hand side is less than or equal to the right-hand side. |
|||
`>`:: Checks whether the left-hand side is greater than the right-hand side. |
|||
`+>=+`:: Checks whether the left-hand side is greater than or equal to the right-hand side. |
|||
|
|||
NOTE: The operators follow the same rules as operators in Ruby. |
|||
@ -0,0 +1,32 @@ |
|||
//// |
|||
Header: Convert Confluence XHTML to AsciiDoc |
|||
|
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
You can convert Atlassian Confluence XHTML pages to Asciidoctor using this http://www.groovy-lang.org/download.html[Groovy] script. |
|||
|
|||
The script calls https://pandoc.org/[Pandoc] to convert single or multiple HTML files exported from Confluence to AsciiDoc files. |
|||
You'll need Pandoc installed before running this script. |
|||
|
|||
NOTE: If you have trouble running this script, you can use the Pandoc command referenced inside the script to convert XHTML files to AsciiDoc manually. |
|||
|
|||
.convert.groovy |
|||
[source,groovy] |
|||
---- |
|||
include::https://gist.githubusercontent.com/melix/6020336/raw/059d83a3dae933de71d585c3f6b229a3c62fa857/convert.groovy[] |
|||
---- |
|||
|
|||
The script is designed to be run locally on HTML files or directories containing HTML files exported from Confluence. |
|||
|
|||
.Usage |
|||
. Save the script contents to a `convert.groovy` file in a working directory. |
|||
. Make the file executable according to your specific OS requirements. |
|||
. Place individual files, or a directory containing files into the working directory. |
|||
. Run `groovy convert filename.html` to convert a single file. |
|||
. Confirm the output file meets requirements |
|||
. Recurse through a directory by using this command pattern: `groovy convert directory/*.html` |
|||
|
|||
This script was created by Cédric Champeau (https://gist.github.com/melix[melix]). |
|||
You can find the source of this script hosted at this https://gist.github.com/melix/6020336[GitHub Gist]. |
|||
@ -0,0 +1,92 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Counters |
|||
//// |
|||
|
|||
// document attributes and counters are NOT the same thing, but modifying a document attribute with the same name as the counter modifies the counter at the same time. |
|||
|
|||
Counters are used to store and display ad-hoc sequences of numbers or latin characters. |
|||
They are designed for simple use cases. |
|||
Possible uses include inline itemized lists, paragraph numbers and serial item numbers. |
|||
|
|||
A counter is implemented as a specialized document attribute. |
|||
You declare and display a counter using an augmented attribute reference, in which the attribute name is prefixed with `counter:` (e.g., `+{counter:name}+`). |
|||
Since counters are attributes, counter names follow the same rules as <<attribute-restrictions,attribute names>>. |
|||
The most important rule to note is that letters in counter names _must be lowercase_. |
|||
|
|||
The counter value is incremented and displayed every time the `counter:` attribute reference is used. |
|||
The term [.term]_increment_ means advance to the next value in the sequence. |
|||
If the counter value is an integer, add 1. |
|||
If the counter value is a character, move to the next letter in the Latin alphabet. |
|||
The default start value of a counter is 1. |
|||
|
|||
To create a sequence starting at 1, use the simple form `+{counter:name}+` as shown here: |
|||
|
|||
[source] |
|||
The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. |
|||
|
|||
Here's the resulting output: |
|||
|
|||
==== |
|||
:!seq1: |
|||
The salad calls for {counter:seq1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. |
|||
==== |
|||
|
|||
To increment the counter without displaying it (i.e., to skip an item in the sequence), use the `counter2` prefix instead: |
|||
|
|||
[source] |
|||
{counter2:seq1} |
|||
|
|||
WARNING: A `counter2` attribute reference on a line by itself will produce an empty paragraph. |
|||
You'll need to adjoin it to the nearest content to avoid this side effect. |
|||
|
|||
To display the current value of the counter without incrementing it, reference the counter name as you would any other attribute: |
|||
|
|||
[source] |
|||
{counter2:pnum}This is paragraph {pnum}. |
|||
|
|||
To create a character sequence, or start a number sequence with a value other than 1, specify a start value by appending it to the first use of the counter: |
|||
|
|||
[source] |
|||
Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries. |
|||
|
|||
CAUTION: Character sequences either run from a,b,c,...x,y,z,{,|... or A,B,C,...,X,Y,Z,[,... depending on the start value. |
|||
Therefore, they aren't really useful for more than 26 items. |
|||
|
|||
The start value of a counter is only recognized if the counter is _unset_ at that point in the document. |
|||
Otherwise, the start value is ignored. |
|||
|
|||
To reset a counter attribute, unset the corresponding attribute using an attribute entry. |
|||
The attribute entry must be adjacent to a block or else it is ignored. |
|||
|
|||
[source] |
|||
---- |
|||
The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. |
|||
|
|||
:!seq1: |
|||
Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries. |
|||
---- |
|||
|
|||
This gives: |
|||
|
|||
==== |
|||
:!seq1: |
|||
The salad calls for {counter:seq1:1}) apples, {counter:seq1}) oranges and {counter:seq1}) pears. |
|||
|
|||
:!seq1: |
|||
Dessert calls for {counter:seq1:A}) mangoes, {counter:seq1}) grapes and {counter:seq1}) cherries. |
|||
==== |
|||
|
|||
Here's a full example that shows how to use a counter for part numbers in a table. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-counter.adoc[tag=base] |
|||
---- |
|||
|
|||
Here's the output of that table: |
|||
|
|||
==== |
|||
include::ex-counter.adoc[tag=base] |
|||
==== |
|||
@ -0,0 +1,40 @@ |
|||
//// |
|||
Custom Themes |
|||
Creating a theme |
|||
|
|||
This document is included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
You can create your own themes to apply to your documents. |
|||
|
|||
Themes go in the [.path]_sass/_ folder. |
|||
To create a new theme, let's call it `hipster`, start by creating two new files: |
|||
|
|||
[.path]_sass/hipster.scss_:: |
|||
* Imports the theme settings, which includes default variables and resets |
|||
* Imports the AsciiDoc components |
|||
* Defines any explicit customization |
|||
|
|||
[.path]_sass/settings/_hipster.scss_:: |
|||
* Sets variables that customize Foundation 4 and the AsciiDoc CSS components |
|||
|
|||
Here's a minimal version of [.path]_sass/hipster.scss_: |
|||
|
|||
[source,scss] |
|||
---- |
|||
@import "settings/hipster"; |
|||
@import "components/asciidoc"; |
|||
@import "components/awesome-icons"; |
|||
---- |
|||
|
|||
NOTE: You don't have to include the underscore prefix when importing files. |
|||
|
|||
NOTE: The `awesome-icons` component is only applicable to HTML generated by Asciidoctor > 0.1.2 with the `icons` attribute set to `font`. |
|||
|
|||
You can add any explicit customization below the import lines. |
|||
|
|||
The variables you can set in [.path]_sass/settings/_hipster.scss_ are a combination of the {factory-ref}/blob/master/sass/settings/_settings.scss.dist[Foundation 4 built-in global settings] and {factory-ref}/blob/master/sass/settings/_defaults.scss[global settings and imports for the AsciiDoc components]. |
|||
|
|||
Once you've created your custom theme, it's time to apply it to your document. |
|||
@ -0,0 +1,12 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
The dedication page is where the author expresses gratitude toward a person. |
|||
|
|||
[source] |
|||
---- |
|||
include::multi-special-ex.adoc[tag=dedicate] |
|||
---- |
|||
@ -0,0 +1,33 @@ |
|||
//// |
|||
Sections |
|||
|
|||
Included in: |
|||
|
|||
- user-manual |
|||
//// |
|||
|
|||
To make a discrete heading, you add the `discrete` attribute to any <<Sections,section title>>. |
|||
//This demotes the section title to a normal heading. |
|||
A discrete heading is styled in a manner similar to a section title, but is not part of the section hierarchy (i.e., and thus excluded from section nesting requirements), it does not enclose subsequent blocks, and it is not included in the table of contents. |
|||
The `discrete` style effectively demotes the section title to a normal heading. |
|||
|
|||
NOTE: Alternately, you may use the `float` attribute to identify a discrete heading. |
|||
In this context, the term "`float`" does not imply layout, meaning it does not float to the left or right of other content blocks. |
|||
It just means it's not anchored to the section hierarchy. |
|||
|
|||
Here's an example of a discrete heading in use. |
|||
|
|||
[source] |
|||
---- |
|||
**** // <1> |
|||
Discrete headings are useful for making headings inside of other blocks, like this sidebar. |
|||
|
|||
[discrete] // <2> |
|||
== Discrete Heading // <3> |
|||
|
|||
Discrete headings can be used where sections are not permitted. |
|||
**** |
|||
---- |
|||
<1> A delimiter line that indicates the start of a sidebar block. |
|||
<2> Set the `discrete` attribute above the section title to demote it to a discrete heading. |
|||
<3> The discrete heading title is designated by one to six equal signs, just like a section title. |
|||
@ -0,0 +1,15 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Question and answer style list |
|||
//// |
|||
|
|||
.Q&A |
|||
[source] |
|||
---- |
|||
include::ex-dlist.adoc[tag=qa] |
|||
---- |
|||
|
|||
==== |
|||
include::ex-dlist.adoc[tag=qa] |
|||
==== |
|||
@ -0,0 +1,84 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Description lists |
|||
- writers-guide: description lists |
|||
- writers-guide: hybrid lists |
|||
//// |
|||
|
|||
// tag::description[] |
|||
A description list (often abbreviate as dlist) is useful when you need to include a description or supporting text for one or more terms. |
|||
Each item in a description list consists of: |
|||
|
|||
* one or more terms |
|||
* a separator following each term (typically a double colon, `::`) |
|||
* at least one space or endline |
|||
* the supporting content (either text, attached blocks, or both) |
|||
|
|||
Here's an example of a description list that identifies parts of a computer: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-dlist.adoc[tag=base] |
|||
---- |
|||
|
|||
By default, the content of each item is displayed below the description when rendered. |
|||
Here's a preview of how this list is rendered: |
|||
|
|||
.A basic description list |
|||
==== |
|||
include::ex-dlist.adoc[tag=base] |
|||
==== |
|||
|
|||
If you want the description and content to appear on the same line, add the horizontal style to the list. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-dlist.adoc[tag=base-horz] |
|||
---- |
|||
|
|||
==== |
|||
include::ex-dlist.adoc[tag=base-horz] |
|||
==== |
|||
|
|||
The content of a description list can be any AsciiDoc element. |
|||
For instance, we could rewrite the grocery list from above so that each aisle is a description rather than a parent outline list item. |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-dlist.adoc[tag=base-mix] |
|||
---- |
|||
|
|||
==== |
|||
include::ex-dlist.adoc[tag=base-mix] |
|||
==== |
|||
|
|||
Description lists are quite lenient about whitespace, so you can spread the items out and even indent the content if that makes it more readable for you: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-dlist.adoc[tag=base-mix-alt] |
|||
---- |
|||
// end::description[] |
|||
|
|||
// tag::hybrid[] |
|||
[#three-hybrid] |
|||
Finally, you can mix and match the three list types within a single hybrid list. |
|||
Asciidoctor works hard to infer the relationships between the items that are most intuitive to us humans. |
|||
|
|||
Here's a list that mixes description, ordered, and unordered list items: |
|||
|
|||
[source] |
|||
---- |
|||
include::ex-dlist.adoc[tag=3-mix] |
|||
---- |
|||
|
|||
Here's how the list is rendered: |
|||
|
|||
.A hybrid list |
|||
==== |
|||
include::ex-dlist.adoc[tag=3-mix] |
|||
==== |
|||
|
|||
You can include more complex content in a list item as well. |
|||
// end::hybrid[] |
|||
@ -0,0 +1,84 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: DocBook |
|||
//// |
|||
|
|||
Asciidoctor can produce DocBook 5.0 output. |
|||
Since the AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good. |
|||
There's a corresponding DocBook element for each markup in the AsciiDoc syntax. |
|||
|
|||
To convert the `mysample.adoc` document to DocBook 5.0 format, call the processor with the backend flag set to `docbook`. |
|||
|
|||
$ asciidoctor -b docbook mysample.adoc |
|||
|
|||
A new XML document, named `mysample.xml`, will now be present in the current directory. |
|||
|
|||
$ ls |
|||
mysample.adoc mysample.html mysample.xml |
|||
|
|||
Here's a snippet of the XML generated by the DocBook converter. |
|||
|
|||
.XML generated from AsciiDoc |
|||
[source,xml] |
|||
---- |
|||
<?xml version="1.0" encoding="UTF-8"?> |
|||
<article xmlns="http://docbook.org/ns/docbook" |
|||
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> |
|||
<info> |
|||
<title>Hello, AsciiDoc!</title> |
|||
<date>2013-09-03</date> |
|||
<author> |
|||
<personname> |
|||
<firstname>Doc</firstname> |
|||
<surname>Writer</surname> |
|||
</personname> |
|||
<email>doc@example.com</email> |
|||
</author> |
|||
<authorinitials>DW</authorinitials> |
|||
</info> |
|||
<simpara> |
|||
An introduction to <link xl:href="http://asciidoc.org">AsciiDoc</link>. |
|||
</simpara> |
|||
<section xml:id="_first_section"> |
|||
<title>First Section</title> |
|||
<itemizedlist> |
|||
<listitem> |
|||
<simpara>item 1</simpara> |
|||
</listitem> |
|||
<listitem> |
|||
<simpara>item 2</simpara> |
|||
</listitem> |
|||
</itemizedlist> |
|||
</section> |
|||
</article> |
|||
---- |
|||
|
|||
If you're on Linux, you can view the DocBook file with {uri-yelp}[Yelp]. |
|||
|
|||
$ yelp mysample.xml |
|||
|
|||
And of course, if you're using the Asciidoctor Ruby API, you can generate a DocBook document directly from your application. |
|||
|
|||
.Generate DocBook output from the API |
|||
[source,ruby] |
|||
---- |
|||
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook' |
|||
---- |
|||
|
|||
By default, the docbook converter produces DocBook 5.0 output that is compliant to the DocBook 5.0 specification. |
|||
|
|||
A summary of the differences are as follows: |
|||
|
|||
* XSD declarations are used on the document root instead of a DTD |
|||
* `<info>` elements for document info instead of `<articleinfo>` and `<bookinfo>` |
|||
* elements that hold the author's name are wrapped in a `<personname>` element |
|||
* the id for an element is defined using an `xml:id` attribute |
|||
* `<link>` is used for links instead of `<ulink>` |
|||
* the URL for a link is defined using the `xl:href` attribute |
|||
|
|||
Refer to {uri-docbook5}[What's new in DocBook v5.0?] for more details about how DocBook 5.0 differs from DocBook 4.5. |
|||
|
|||
If you need to output DocBook 4.5, you may find the community-supported {uri-docbook45}[DocBook 4.5 Converter] useful. |
|||
|
|||
$ asciidoctor -b docbook45 mysample.adoc |
|||
@ -0,0 +1,20 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Convert DocBook XML to AsciiDoc |
|||
//// |
|||
|
|||
One of the things Asciidoctor excels at is converting AsciiDoc source into valid and well-formed DocBook XML content. |
|||
|
|||
What if you're in the position where you need to go the other way: migrate all your legacy DocBook XML content to AsciiDoc? |
|||
The prescription (℞) you need to get rid of your DocBook pains could be https://github.com/opendevise/docbookrx[DocBookRx]. |
|||
|
|||
DocBookRx is an early version of a DocBook to AsciiDoc converter written in Ruby. |
|||
This converter is far from perfect at the moment, but it improves with each document it converts. |
|||
|
|||
The plan is to evolve it into a robust library for performing this conversion in a reliable way. |
|||
You can read more about this initiative in the https://github.com/opendevise/docbookrx/blob/master/README.adoc[README]. |
|||
|
|||
The best thing about this tool is all the active users who are putting it through its paces. |
|||
The more advanced the DocBook XML this tool tackles, and the more feedback we receive, the better the tool will become. |
|||
Use it today to escape from XML hell! |
|||
@ -0,0 +1,246 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: docinfo |
|||
//// |
|||
|
|||
You can add custom content to the head or footer of an output document using docinfo files. |
|||
Docinfo files are useful for injecting auxiliary metadata, stylesheet, and script information into the output not added by the converter. |
|||
|
|||
Different docinfo files get used depending on whether you are converting to HTML or DocBook (but don't yet apply when converting to PDF). |
|||
|
|||
=== Head docinfo files |
|||
|
|||
The content of head docinfo files gets injected into the top of the document. |
|||
For HTML, the content is append to the `<head>` element. |
|||
For DocBook, the content is appended to the root `<info>` element. |
|||
|
|||
The docinfo file for HTML output may contain valid elements to populate the HTML `<head>` element, including: |
|||
|
|||
* `<base>` |
|||
* `<link>` |
|||
* `<meta>` |
|||
* `<noscript>` |
|||
* `<script>` |
|||
* `<style>` |
|||
|
|||
CAUTION: Use of the `<title>` element is not recommend as it's already emitted by the converter. |
|||
|
|||
You do not need to include the enclosing `<head>` tag as it's assumed to be the envelope. |
|||
|
|||
Here's an example: |
|||
|
|||
.A head docinfo file for HTML output |
|||
[source,html] |
|||
---- |
|||
<meta name="keywords" content="open source, documentation"> |
|||
<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team."> |
|||
<link rel="stylesheet" href="basejump.css"> |
|||
<script src="map.js"></script> |
|||
---- |
|||
|
|||
Docinfo files for HTML output must be saved with the `.html` file extension. |
|||
See <<Naming docinfo files>> for more details. |
|||
|
|||
The docinfo file for DocBook 5.0 output may include any of the {docbook-info-ref}[`<info>` element's children], such as: |
|||
|
|||
* `<address>` |
|||
* `<copyright>` |
|||
* `<edition>` |
|||
* `<keywordset>` |
|||
* `<publisher>` |
|||
* `<subtitle>` |
|||
* `<revhistory>` |
|||
|
|||
The following example shows some of the content a docinfo file for DocBook might contain. |
|||
|
|||
.A docinfo file for DocBook 5.0 output |
|||
[source,xml] |
|||
---- |
|||
<author> |
|||
<personname> |
|||
<firstname>Karma</firstname> |
|||
<surname>Chameleon</surname> |
|||
</personname> |
|||
<affiliation> |
|||
<jobtitle>Word SWAT Team Leader</jobtitle> |
|||
</affiliation> |
|||
</author> |
|||
|
|||
<keywordset> |
|||
<keyword>open source</keyword> |
|||
<keyword>documentation</keyword> |
|||
<keyword>adventure</keyword> |
|||
</keywordset> |
|||
|
|||
<printhistory> |
|||
<para>April, 2019. Twenty-sixth printing.</para> |
|||
</printhistory> |
|||
---- |
|||
|
|||
Docinfo files for DocBook output must be saved with the `.xml` file extension. |
|||
See <<Naming docinfo files>> for more details. |
|||
|
|||
To see a real-world example of a docinfo file for DocBook, checkout the {richfaces-docinfo}[RichFaces Developer Guide docinfo file]. |
|||
|
|||
=== Footer docinfo files |
|||
|
|||
Footer docinfo files are differentiated from head docinfo files by the addition of `-footer` to the file name. |
|||
In the HTML output, the footer content is inserted immediately after the footer div (i.e., `<div id="footer">`). |
|||
In the DocBook output, the footer content is inserted immediately before the ending tag (e.g., `</article>` or `</book>`). |
|||
|
|||
TIP: One possible use of the footer docinfo file is to completely replace the default footer in the standard stylesheet. |
|||
Just set the attribute `nofooter`, then apply a custom footer docinfo file. |
|||
|
|||
// Not here! Good info, but does nothing to clarify the previous paragraphs and could confuse. |
|||
//// |
|||
TIP: To change the text in the "Last updated" line in the footer, set the text in the attribute `last-update-label` (for example, `:last-update-label: <your text> Last Updated`). + |
|||
To disable the "Last updated" line in the footer, unassign the attribute `last-update-label` (however, this leaves an empty footer div). + |
|||
To disable the footer completely, set the attribute `nofooter`. Then having a footer docinfo file effectively replaces the default footer with your custom footer. |
|||
//// |
|||
|
|||
=== Naming docinfo files |
|||
|
|||
The file that gets selected to provide the docinfo depends on which converter is in use (html, docbook, etc) and whether the docinfo scope is configured for a specific document ("`private`") or for all documents in the same directory ("`shared`"). |
|||
The file extension of the docinfo file must match the file extension of the output file (as specified by the `outfilesuffix` attribute, a value which always begins with a period (`.`)). |
|||
|
|||
.Docinfo file naming |
|||
[cols="<10,<20,<30,<30"] |
|||
|==== |
|||
|Mode |Location |Behavior |Docinfo file name |
|||
|
|||
.2+|Private |
|||
|Head |
|||
|Adds content to `<head>`/`<info>` for <docname>.adoc files. |
|||
|`<docname>-docinfo<outfilesuffix>` |
|||
|
|||
|Footer |
|||
|Adds content to end of document for <docname>.adoc files. |
|||
|`<docname>-docinfo-footer<outfilesuffix>` |
|||
|
|||
.2+|Shared |
|||
|Head |
|||
|Adds content to `<head>`/`<info>` for any document in same directory. |
|||
|`docinfo<outfilesuffix>` |
|||
|
|||
|Footer |
|||
|Adds content to end of document for any document in same directory. |
|||
|`docinfo-footer<outfilesuffix>` |
|||
|==== |
|||
|
|||
To specify which file(s) you want to apply, set the `docinfo` attribute to any combination of these values: |
|||
|
|||
* `private-head` |
|||
* `private-footer` |
|||
* `private` (alias for `private-head,private-footer`) |
|||
* `shared-head` |
|||
* `shared-footer` |
|||
* `shared` (alias for `shared-head,shared-footer`) |
|||
|
|||
Setting `docinfo` with no value is equivalent to setting the value to `private`. |
|||
|
|||
For example: |
|||
|
|||
[source] |
|||
---- |
|||
:docinfo: shared,private-footer |
|||
---- |
|||
|
|||
This docinfo configuration will apply the shared docinfo head and footer files, if they exist, as well as the private footer file, if it exists. |
|||
|
|||
// NOTE migrate this NOTE to the migration guide once 1.6 is released |
|||
[NOTE] |
|||
==== |
|||
|
|||
`docinfo` attribute values were introduced in Asciidoctor 1.5.5 to replace the less descriptive `docinfo1` and `docinfo2` attributes. |
|||
Here are the equivalents of the old attributes using the new values: |
|||
|
|||
* `:docinfo:` = `:docinfo: private` |
|||
* `:docinfo1:` = `:docinfo: shared` |
|||
* `:docinfo2:` = `:docinfo: shared,private` |
|||
==== |
|||
|
|||
Let's apply this to an example: |
|||
|
|||
You have two AsciiDoc documents, adventure.adoc and insurance.adoc, saved in the same folder. |
|||
You want to add the same content to the head of both documents when they're converted to HTML. |
|||
|
|||
. Create a docinfo file containing `<head>` elements. |
|||
. Save it as docinfo.html. |
|||
. Set the `docinfo` attribute in adventure.adoc and insurance.adoc to `shared`. |
|||
|
|||
You also want to include some additional content, but only to the head of adventure.adoc. |
|||
|
|||
. Create *another* docinfo file containing `<head>` elements. |
|||
. Save it as adventure-docinfo.html. |
|||
. Set the `docinfo` attribute in adventure.adoc to `shared,private-head` |
|||
|
|||
If other AsciiDoc files are added to the same folder, and `docinfo` is set to `shared` in those files, only the docinfo.html file will be added when converting those files. |
|||
|
|||
=== Locating docinfo files |
|||
|
|||
By default, docinfo files are searched for in the same folder as the document file. |
|||
If you want to keep them anywhere else, set the `docinfodir` attribute to their location: |
|||
|
|||
[source] |
|||
---- |
|||
:docinfodir: common/meta |
|||
---- |
|||
|
|||
Note that if you use this attribute, only the specified folder will be searched; docinfo files in the document folder will no longer be found. |
|||
|
|||
=== Attribute substitution in docinfo files |
|||
|
|||
Docinfo files may include attribute references. |
|||
Which substitutions get applied is controlled by the `docinfosubs` attribute, which takes a comma-separated list of substitution names. |
|||
The value of this attribute defaults to `attributes`. |
|||
|
|||
For example, if you created the following docinfo file: |
|||
|
|||
.Docinfo file containing a revnumber attribute reference |
|||
[source,xml] |
|||
---- |
|||
<edition>{revnumber}</edition> |
|||
---- |
|||
|
|||
And this source document: |
|||
|
|||
.Source document including a revision number |
|||
[source,asciidoc] |
|||
---- |
|||
= Document Title |
|||
Author Name |
|||
v1.0, 2019-06-01 |
|||
:doctype: book |
|||
:backend: docbook |
|||
:docinfo: |
|||
---- |
|||
|
|||
Then the converted DocBook output would be: |
|||
|
|||
[source,xml] |
|||
---- |
|||
<?xml version="1.0" encoding="UTF-8"?> |
|||
<book xmlns="http://docbook.org/ns/docbook" |
|||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" lang="en"> |
|||
<info> |
|||
<title>Document Title</title> |
|||
<date>2019-06-01</date> |
|||
<author> |
|||
<personname> |
|||
<firstname>Author</firstname> |
|||
<surname>Name</surname> |
|||
</personname> |
|||
</author> |
|||
<authorinitials>AN</authorinitials> |
|||
<revhistory> |
|||
<revision> |
|||
<revnumber>1.0</revnumber> <!--1--> |
|||
<date>2019-06-01</date> |
|||
<authorinitials>AN</authorinitials> |
|||
</revision> |
|||
</revhistory> |
|||
</info> |
|||
</book> |
|||
---- |
|||
<1> The revnumber attribute reference was replaced by the source document's revision number in the converted output. |
|||
@ -0,0 +1,44 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Document Types |
|||
//// |
|||
|
|||
Article (keyword: `article`):: |
|||
The default doctype. |
|||
In DocBook, includes the appendix, abstract, bibliography, glossary, and index sections. |
|||
|
|||
Book (keyword: `book`):: |
|||
Builds on the article doctype with the additional ability to use a top-level title as part titles, includes the appendix, dedication, preface, bibliography, glossary, index, and colophon. |
|||
There's also the concept of a multi-part book, but the distinction from a regular book is determined by the content. |
|||
A book only has chapters and special sections, whereas a multi-part book is divided by parts that each contain one or more chapters or special sections. |
|||
|
|||
Man page (keyword: `manpage`):: |
|||
Used for producing a roff or HTML-formatted https://en.wikipedia.org/wiki/Man_page[man page] (short for manual page) for Unix and Unix-like operating systems. |
|||
This doctype instructs the parser to recognize a special document header and section naming conventions for organizing the AsciiDoc content as a manual page. |
|||
Refer to <<man-pages>> for details on how to compose AsciiDoc for this purpose. |
|||
|
|||
Inline (keyword: `inline`):: |
|||
Asciidoctor only. |
|||
There may be cases when you only want to apply inline AsciiDoc formatting to input text without wrapping it in a block element. |
|||
For example, in the {asciidoclet-ref}[Asciidoclet project] (AsciiDoc in Javadoc), only the inline formatting is needed for the text in Javadoc tags. |
|||
|
|||
=== Inline doctype |
|||
|
|||
The rules for the inline doctype are as follows: |
|||
|
|||
* Only a single paragraph is read from the AsciiDoc source. |
|||
* Inline formatting is applied. |
|||
* The output is not wrapped in the normal paragraph tags. |
|||
|
|||
Given the following input: |
|||
|
|||
[source,asciidoc] |
|||
http://asciidoc.org[AsciiDoc] is a _lightweight_ markup language... |
|||
|
|||
Processing it with the options `doctype=inline` and `backend=html5` produces: |
|||
|
|||
[source,html] |
|||
<a href="http://asciidoc.org">AsciiDoc</a> is a <em>lightweight</em> markup language… |
|||
|
|||
The inline doctype allows the Asciidoctor processor to cover the full range of applications, from unstructured (inline) text to full, standalone documents! |
|||
@ -0,0 +1,55 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Elements |
|||
//// |
|||
|
|||
One or more lines of text in a document are defined as a block element. |
|||
Block elements can be nested within block elements. |
|||
|
|||
A document can include the following block elements: |
|||
|
|||
* Header |
|||
* Title |
|||
* Author Info |
|||
* First Name |
|||
* Middle Name |
|||
* Last Name |
|||
* Email Address |
|||
* Revision Info |
|||
* Revision Number |
|||
* Revision Date |
|||
* Revision Remark |
|||
* Attribute Entry |
|||
* Preamble |
|||
* Section Title |
|||
* Section Body |
|||
* BlockId |
|||
* Block Title |
|||
* Block Macro |
|||
* Block |
|||
* Paragraph |
|||
* Delimited Block |
|||
* Table |
|||
* List |
|||
* Bulleted List |
|||
* Numbered List |
|||
* Description List |
|||
* Callout List |
|||
* List Entry |
|||
* List Label |
|||
* List Item |
|||
* Item Text |
|||
* List Paragraph |
|||
* List Continuation |
|||
|
|||
An inline element performs an operation on a subset of the content within a block element. |
|||
|
|||
Inline elements include: |
|||
|
|||
* Quotes |
|||
* Replacements |
|||
* Special characters |
|||
* Special words |
|||
* Attribute references |
|||
* Inline macros |
|||
@ -0,0 +1,83 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Admonition |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::para-c[] |
|||
WARNING: Wolpertingers are known to nest in server racks. // <1> <2> |
|||
Enter at your own risk. |
|||
// end::para-c[] |
|||
|
|||
// tag::para[] |
|||
WARNING: Wolpertingers are known to nest in server racks. |
|||
Enter at your own risk. |
|||
// end::para[] |
|||
|
|||
// tag::bl[] |
|||
[IMPORTANT] |
|||
.Feeding the Werewolves |
|||
==== |
|||
While werewolves are hardy community members, keep in mind the following dietary concerns: |
|||
|
|||
. They are allergic to cinnamon. |
|||
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens. |
|||
. Celery makes them sad. |
|||
==== |
|||
// end::bl[] |
|||
|
|||
// tag::bl-c[] |
|||
[IMPORTANT] // <1> |
|||
.Feeding the Werewolves |
|||
==== // <2> |
|||
While werewolves are hardy community members, keep in mind the following dietary concerns: |
|||
|
|||
. They are allergic to cinnamon. |
|||
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens. |
|||
. Celery makes them sad. |
|||
==== |
|||
// end::bl-c[] |
|||
|
|||
// tag::bl-nest[] |
|||
[IMPORTANT] |
|||
.Feeding the Werewolves |
|||
====== |
|||
While werewolves are hardy community members, keep in mind the following dietary concerns: |
|||
|
|||
. They are allergic to cinnamon. |
|||
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens. |
|||
. Celery makes them sad. |
|||
====== |
|||
// end::bl-nest[] |
|||
|
|||
// tag::b-para[] |
|||
NOTE: An admonition paragraph draws the reader's attention to |
|||
auxiliary information. |
|||
Its purpose is determined by the label |
|||
at the beginning of the paragraph. |
|||
|
|||
Here are the other built-in admonition types: |
|||
|
|||
TIP: Pro tip... |
|||
|
|||
IMPORTANT: Don't forget... |
|||
|
|||
WARNING: Watch out for... |
|||
|
|||
CAUTION: Ensure that... |
|||
// end::b-para[] |
|||
|
|||
// tag::b-bl[] |
|||
[NOTE] |
|||
==== |
|||
An admonition block may contain complex content. |
|||
|
|||
.A list |
|||
- one |
|||
- two |
|||
- three |
|||
|
|||
Another paragraph. |
|||
==== |
|||
// end::b-bl[] |
|||
@ -0,0 +1,73 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Appendix |
|||
//// |
|||
|
|||
// tag::appx-article[] |
|||
= Article Title |
|||
:appendix-caption: Appx |
|||
:sectnums: |
|||
:toc: |
|||
|
|||
== First Section |
|||
|
|||
=== Subsection |
|||
|
|||
[appendix] |
|||
== First Appendix |
|||
|
|||
=== First Subsection |
|||
|
|||
=== Second Subsection |
|||
|
|||
[appendix] |
|||
== Second Appendix |
|||
// end::appx-article[] |
|||
|
|||
.... |
|||
// tag::appx-article-out[] |
|||
1. First Section |
|||
1.1. Subsection |
|||
Appx A: First Appendix |
|||
1.1. First Subsection |
|||
1.2. Second Subsection |
|||
Appx B: Second Appendix |
|||
// end::appx-article-out[] |
|||
.... |
|||
|
|||
// tag::appx-book[] |
|||
= Book Title |
|||
:doctype: book |
|||
:appendix-caption: Appx |
|||
:sectnums: |
|||
:toc: |
|||
|
|||
= First Part |
|||
|
|||
== First Chapter |
|||
|
|||
=== Subsection |
|||
|
|||
[appendix] |
|||
= First Appendix |
|||
|
|||
=== First Subsection |
|||
|
|||
=== Second Subsection |
|||
|
|||
[appendix] |
|||
= Second Appendix |
|||
// end::appx-book[] |
|||
|
|||
.... |
|||
// tag::appx-book-out[] |
|||
First Part |
|||
1. First Chapter |
|||
1.1. Subsection |
|||
Appx A: First Appendix |
|||
1.1. First Subsection |
|||
1.2. Second Subsection |
|||
Appx B: Second Appendix |
|||
// end::appx-book-out[] |
|||
.... |
|||
@ -0,0 +1,82 @@ |
|||
//// |
|||
Example |
|||
|
|||
Included in: |
|||
|
|||
- user-manual: Header |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
Kismet Rainbow Chameleon <kismet@asciidoctor.org> |
|||
|
|||
This journey begins... |
|||
|
|||
== About the Author |
|||
|
|||
You can contact {author} at {email}. |
|||
{firstname} loves to hear from other chroniclers. |
|||
|
|||
P.S. And yes, my middle name really is {middlename}. |
|||
What else would you expect from a member of the Rocky Mountain {lastname} Clan? |
|||
|
|||
{authorinitials} |
|||
// end::base[] |
|||
|
|||
// tag::b-base[] |
|||
= My Document's Title |
|||
Doc Writer <doc.writer@asciidoctor.org> |
|||
|
|||
My document provides... |
|||
// end::b-base[] |
|||
|
|||
// tag::2-mid[] |
|||
= The Unbearable Lightness of Nomenclature |
|||
Jan Hendrik van_den_Berg |
|||
|
|||
My first name is {firstname}. |
|||
|
|||
My middle name is {middlename}. |
|||
|
|||
My last name is {lastname}. |
|||
|
|||
My initials are {authorinitials}. |
|||
// end::2-mid[] |
|||
|
|||
// tag::attr[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
:author: Kismet Rainbow Chameleon |
|||
:email: kismet@asciidoctor.org |
|||
|
|||
This journey begins... |
|||
|
|||
== About the Author |
|||
|
|||
You can contact {author} at {email}. |
|||
{firstname} loves to hear from other chroniclers. |
|||
|
|||
P.S. And yes, my middle name really is {middlename}. |
|||
What else would you expect from a member of the Rocky Mountain {lastname} Clan? |
|||
|
|||
{authorinitials} |
|||
// end::attr[] |
|||
|
|||
// tag::multi[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
Kismet Rainbow Chameleon <kismet@asciidoctor.org>; Lazarus het_Draeke <lazarus@asciidoctor.org> |
|||
|
|||
This journey begins... |
|||
|
|||
== About the Authors |
|||
|
|||
You can contact {author} at {email}. |
|||
{firstname} loves to hear from other chroniclers. |
|||
|
|||
{author_2} specializes in burning down automation obstacles. // <1> |
|||
Email {lastname_2} at {email_2}. |
|||
|
|||
Until our next adventure! |
|||
|
|||
{authorinitials} & {authorinitials_2} |
|||
// end::multi[] |
|||
@ -0,0 +1,19 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Bibliography |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
_The Pragmatic Programmer_ <<pp>> should be required reading for all developers. |
|||
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>. |
|||
|
|||
[bibliography] |
|||
== References |
|||
|
|||
- [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer: |
|||
From Journeyman to Master. Addison-Wesley. 1999. |
|||
- [[[gof,2]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: |
|||
Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994. |
|||
// end::base[] |
|||
@ -0,0 +1,36 @@ |
|||
//// |
|||
Generic Block example snippets |
|||
|
|||
User Manual: Blocks |
|||
//// |
|||
|
|||
// tag::list-title[] |
|||
.TODO list |
|||
- Learn the AsciiDoc syntax |
|||
- Install Asciidoctor |
|||
- Write my document |
|||
// end::list-title[] |
|||
|
|||
// tag::meta-co[] |
|||
.Gettysburg Address // <1> |
|||
[#gettysburg] // <2> |
|||
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg] // <3> <4> <5> |
|||
____ |
|||
Four score and seven years ago our fathers brought forth |
|||
on this continent a new nation... |
|||
|
|||
Now we are engaged in a great civil war, testing whether |
|||
that nation, or any nation so conceived and so dedicated, |
|||
can long endure. ... |
|||
____ |
|||
// end::meta-co[] |
|||
|
|||
// tag::opt-listing[] |
|||
[listing] |
|||
sudo dnf install asciidoc |
|||
// end::opt-listing[] |
|||
|
|||
// tag::quote-name[] |
|||
[quote] |
|||
Never do today what you can put off `'til tomorrow. |
|||
// end::quote-name[] |
|||
@ -0,0 +1,62 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Callouts |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::b-nonselect[] |
|||
---- |
|||
line of code // <1> |
|||
line of code # <2> |
|||
line of code ;; <3> |
|||
---- |
|||
<1> A callout behind a line comment for C-style languages. |
|||
<2> A callout behind a line comment for Ruby, Python, Perl, etc. |
|||
<3> A callout behind a line comment for Clojure. |
|||
// end::b-nonselect[] |
|||
|
|||
// tag::source-xml[] |
|||
[source,xml] |
|||
---- |
|||
<section> |
|||
<title>Section Title</title> <!--1--> |
|||
</section> |
|||
---- |
|||
<1> The section title is required. |
|||
// end::source-xml[] |
|||
|
|||
// tag::basic[] |
|||
[source,ruby] |
|||
---- |
|||
require 'sinatra' <1> |
|||
|
|||
get '/hi' do <2> <3> |
|||
"Hello World!" |
|||
end |
|||
---- |
|||
<1> Library import |
|||
<2> URL mapping |
|||
<3> Response block |
|||
// end::basic[] |
|||
|
|||
// tag::b-src[] |
|||
[source,ruby] |
|||
---- |
|||
require 'sinatra' // <1> |
|||
|
|||
get '/hi' do // <2> |
|||
"Hello World!" // <3> |
|||
end |
|||
---- |
|||
<1> Library import |
|||
<2> URL mapping |
|||
<3> HTTP response body |
|||
// end::b-src[] |
|||
|
|||
// tag::co-icon[] |
|||
= Document Title |
|||
:icons: font // <1> |
|||
|
|||
NOTE: Asciidoctor now supports font-based admonition icons, powered by Font Awesome! // <2> |
|||
// end::co-icon[] |
|||
@ -0,0 +1,18 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Comments |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::line[] |
|||
// A single-line comment. |
|||
// end::line[] |
|||
|
|||
// tag::bl[] |
|||
//// |
|||
A multi-line comment. |
|||
|
|||
Notice it's a delimited block. |
|||
//// |
|||
// end::bl[] |
|||
@ -0,0 +1,20 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Counter Attributes |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
[caption=""] |
|||
.Parts{counter2:index:0} |
|||
|=== |
|||
|Part Id |Description |
|||
|
|||
|PX-{counter:index} |
|||
|Description of PX-{index} |
|||
|
|||
|PX-{counter:index} |
|||
|Description of PX-{index} |
|||
|=== |
|||
// end::base[] |
|||
@ -0,0 +1,55 @@ |
|||
//// |
|||
User Manual - Description metadata example |
|||
|
|||
//// |
|||
|
|||
// tag::desc-base[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
Kismet Rainbow Chameleon <kismet@asciidoctor.org>; Lazarus het_Draeke <lazarus@asciidoctor.org> |
|||
:description: A story chronicling the inexplicable hazards and vicious beasts a \ // <1> |
|||
documentation team must surmount and vanquish on their journey to finding an \ |
|||
open source project's true power. |
|||
|
|||
This journey begins on a bleary Monday morning. |
|||
// end::desc-base[] |
|||
Our intrepid team is in desperate need of double shot mochas, but the milk expired eight days ago. |
|||
A trip to the dairy was out of the question. |
|||
On Friday night, a mutant, script-injecting warlock had infected the Shetland cattle herd with a ravenous craving for tags and annotations. |
|||
The security wolves were at a trust building retreat in Katchanga, and no one in the village could locate their defensive operations manual. |
|||
|
|||
Weak daylight trickled across the stripped pasture, chased by distant bovine screams... |
|||
|
|||
== Cavern Glow |
|||
|
|||
The river rages through the cavern, rattling its content... |
|||
|
|||
== The Ravages of Writing |
|||
|
|||
Her finger socks had been vaporized by crystalline nuggets of... |
|||
|
|||
=== A Recipe for Potion |
|||
|
|||
Two fresh Burdockian leaves, harvested by the light of the teal moons... |
|||
|
|||
==== Searching for Burdockian |
|||
|
|||
Crawling through the twisted understory... |
|||
|
|||
== Dawn on the Plateau |
|||
|
|||
Hanging from... |
|||
|
|||
// tag::desc-html[] |
|||
[source,xml] |
|||
---- |
|||
<!DOCTYPE html> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
|||
<meta name="generator" content="Asciidoctor 1.5.6.2"> |
|||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
|||
<meta name="description" content="A story chronicling the inexplicable hazards and vicious beasts a documentation team must surmount and vanquish on their journey to finding an open source project's true power."> |
|||
<title>The Dangerous and Thrilling Documentation Chronicles</title> |
|||
<style> |
|||
---- |
|||
// end::desc-html[] |
|||
@ -0,0 +1,101 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Description list |
|||
- quick-ref |
|||
|
|||
.Description list |
|||
[source] |
|||
---- |
|||
CPU:: <1> |
|||
The brain of the computer. <2> |
|||
<3> |
|||
Hard drive:: |
|||
Permanent storage for operating system and/or user files. |
|||
---- |
|||
<1> Follow each term with two colons. |
|||
<2> Enter the definition text on a new line below the term. |
|||
<3> Enter a single blank line between each term/definition pair. |
|||
|
|||
//// |
|||
|
|||
// tag::base[] |
|||
CPU:: The brain of the computer. |
|||
Hard drive:: Permanent storage for operating system and/or user files. |
|||
RAM:: Temporarily stores information the CPU uses during operation. |
|||
Keyboard:: Used to enter text or control items on the screen. |
|||
Mouse:: Used to point to and select items on your computer screen. |
|||
Monitor:: Displays information in visual form using text and graphics. |
|||
// end::base[] |
|||
|
|||
// tag::base-horz[] |
|||
[horizontal] |
|||
CPU:: The brain of the computer. |
|||
Hard drive:: Permanent storage for operating system and/or user files. |
|||
RAM:: Temporarily stores information the CPU uses during operation. |
|||
// end::base-horz[] |
|||
|
|||
// tag::b-base[] |
|||
first term:: definition of first term |
|||
second term:: definition of second term |
|||
// end::b-base[] |
|||
|
|||
// tag::b-base-multi[] |
|||
first term:: |
|||
definition of first term |
|||
second term:: |
|||
definition of second term |
|||
// end::b-base-multi[] |
|||
|
|||
// tag::base-mix[] |
|||
Dairy:: |
|||
* Milk |
|||
* Eggs |
|||
Bakery:: |
|||
* Bread |
|||
Produce:: |
|||
* Bananas |
|||
// end::base-mix[] |
|||
|
|||
// tag::base-mix-alt[] |
|||
Dairy:: |
|||
|
|||
* Milk |
|||
* Eggs |
|||
|
|||
Bakery:: |
|||
|
|||
* Bread |
|||
|
|||
Produce:: |
|||
|
|||
* Bananas |
|||
// end::base-mix-alt[] |
|||
|
|||
// tag::3-mix[] |
|||
Operating Systems:: |
|||
Linux::: |
|||
. Fedora |
|||
* Desktop |
|||
. Ubuntu |
|||
* Desktop |
|||
* Server |
|||
BSD::: |
|||
. FreeBSD |
|||
. NetBSD |
|||
|
|||
Cloud Providers:: |
|||
PaaS::: |
|||
. OpenShift |
|||
. CloudBees |
|||
IaaS::: |
|||
. Amazon EC2 |
|||
. Rackspace |
|||
// end::3-mix[] |
|||
|
|||
// tag::qa[] |
|||
[qanda] |
|||
What is Asciidoctor?:: |
|||
An implementation of the AsciiDoc processor in Ruby. |
|||
What is the answer to the Ultimate Question?:: 42 |
|||
// end::qa[] |
|||
@ -0,0 +1,24 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Example |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
.Sample document |
|||
==== |
|||
Here's a sample AsciiDoc document: |
|||
|
|||
[listing] |
|||
.... |
|||
= Title of Document |
|||
Doc Writer |
|||
:toc: |
|||
|
|||
This guide provides... |
|||
.... |
|||
|
|||
The document header is useful, but not required. |
|||
==== |
|||
// end::base[] |
|||
@ -0,0 +1,41 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Footnotes |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base-c[] |
|||
The hail-and-rainbow protocol can be initiated at five levels: |
|||
double, tertiary, supernumerary, supermassive, and apocalyptic party.footnote:[The double hail-and-rainbow level makes my toes tingle.] <1> <2> |
|||
A bold statement!footnote:disclaimer[Opinions are my own.] <3> |
|||
|
|||
Another outrageous statement.footnote:disclaimer[] <4> |
|||
// end::base-c[] |
|||
|
|||
// tag::base-x[] |
|||
The hail-and-rainbow protocol can be initiated at five levels: |
|||
double, tertiary, supernumerary, supermassive, and apocalyptic party.footnote:[The double hail-and-rainbow level makes my toes tingle.] |
|||
A bold statement!footnote:disclaimer[Opinions are my own.] |
|||
|
|||
Another outrageous statement.footnote:disclaimer[] |
|||
// end::base-x[] |
|||
|
|||
// tag::externalized[] |
|||
:fn-hail-and-rainbow: footnote:[The double hail-and-rainbow level makes my toes tingle.] |
|||
:fn-disclaimer: footnote:disclaimer[Opinions are my own.] |
|||
|
|||
The hail-and-rainbow protocol can be initiated at five levels: |
|||
double, tertiary, supernumerary, supermassive, and apocalyptic party.{fn-hail-and-rainbow} |
|||
A bold statement!{fn-disclaimer} |
|||
|
|||
Another outrageous statement.{fn-disclaimer} |
|||
// end::externalized[] |
|||
|
|||
// tag::base[] |
|||
A statement.footnote:[Clarification about this statement.] |
|||
|
|||
A bold statement!footnote:disclaimer[Opinions are my own.] |
|||
|
|||
Another bold statement.footnote:disclaimer[] |
|||
// end::base[] |
|||
@ -0,0 +1,37 @@ |
|||
//// |
|||
Example |
|||
|
|||
Included in: |
|||
|
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::b-base[] |
|||
= My Document's Title |
|||
Doc Writer <doc.writer@asciidoctor.org> |
|||
v1.0, 2018-04-11 |
|||
:toc: |
|||
:imagesdir: assets/images |
|||
:homepage: https://asciidoctor.org |
|||
|
|||
My document provides... |
|||
// end::b-base[] |
|||
|
|||
// tag::b-attr[] |
|||
:url-home: https://asciidoctor.org |
|||
:link-docs: https://asciidoctor.org/docs[documentation] |
|||
:summary: Asciidoctor is a mature, plain-text document format for \ |
|||
writing notes, articles, documentation, books, and more. \ |
|||
It's also a text processor & toolchain for translating \ |
|||
documents into various output formats (i.e., backends), \ |
|||
including HTML, DocBook, PDF and ePub. |
|||
:checkedbox: pass:normal[{startsb}✔{endsb}] |
|||
|
|||
Check out {url-home}[Asciidoctor]! |
|||
|
|||
{summary} |
|||
|
|||
Be sure to read the {link-docs} too! |
|||
|
|||
{checkedbox} That's done! |
|||
// end::b-attr[] |
|||
@ -0,0 +1,45 @@ |
|||
//// |
|||
Example |
|||
|
|||
Included in: |
|||
|
|||
- user-manual: Header |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
|
|||
This journey begins on a bleary Monday morning. |
|||
// end::base[] |
|||
|
|||
// tag::b-base[] |
|||
= My Document's Title |
|||
|
|||
My document provides... |
|||
// end::b-base[] |
|||
|
|||
// tag::doc[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
|
|||
{doctitle} begins on a bleary Monday morning. |
|||
// end::doc[] |
|||
|
|||
// tag::sub-1[] |
|||
= The Dangerous and Thrilling Documentation Chronicles: A Tale of Caffeine and Words |
|||
|
|||
It began on a bleary Monday morning. |
|||
// end::sub-1[] |
|||
|
|||
// tag::sub-2[] |
|||
= A Cautionary Tale: The Dangerous and Thrilling Documentation Chronicles: A Tale of Caffeine and Words |
|||
|
|||
It began on a bleary Monday morning. |
|||
// end::sub-2[] |
|||
|
|||
// tag::sub-3[] |
|||
:title-separator: {sp}| |
|||
= The Dangerous and Thrilling Documentation Chronicles | A Tale of Caffeine and Words |
|||
|
|||
It began on a bleary Monday morning. |
|||
// end::sub-3[] |
|||
@ -0,0 +1,28 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Horizontal Rule |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
''' |
|||
// end::base[] |
|||
|
|||
// tag::in-between[] |
|||
before |
|||
|
|||
''' |
|||
|
|||
after |
|||
// end::in-between[] |
|||
|
|||
// tag::md[] |
|||
--- |
|||
|
|||
- - - |
|||
|
|||
*** |
|||
|
|||
* * * |
|||
// end::md[] |
|||
@ -0,0 +1,82 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Images |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
image::sunset.jpg[] |
|||
// end::base[] |
|||
|
|||
// tag::alt[] |
|||
image::sunset.jpg[Sunset] |
|||
// end::alt[] |
|||
|
|||
// tag::attr-co[] |
|||
[#img-sunset] <1> |
|||
.A mountain sunset <2> |
|||
[link=https://www.flickr.com/photos/javh/5448336655] <3> |
|||
image::sunset.jpg[Sunset,300,200] <4> <5> |
|||
// end::attr-co[] |
|||
|
|||
// tag::attr[] |
|||
.A mountain sunset |
|||
[#img-sunset] |
|||
[caption="Figure 1: ",link=https://www.flickr.com/photos/javh/5448336655] |
|||
image::sunset.jpg[Sunset,300,200] |
|||
// end::attr[] |
|||
|
|||
// tag::in[] |
|||
Click image:icons/play.png[Play, title="Play"] to get the party started. |
|||
|
|||
Click image:icons/pause.png[title="Pause"] when you need a break. |
|||
// end::in[] |
|||
|
|||
// tag::in-role[] |
|||
image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset! |
|||
// end::in-role[] |
|||
|
|||
// tag::role[] |
|||
[.right.text-center] |
|||
image::tiger.png[Tiger,200,200] |
|||
// end::role[] |
|||
|
|||
// tag::float[] |
|||
image::tiger.png[Tiger,200,200,float="right",align="center"] |
|||
// end::float[] |
|||
|
|||
// tag::in-float[] |
|||
image:linux.png[Linux,150,150,float="right"] |
|||
You can find Linux everywhere these days! |
|||
// end::in-float[] |
|||
|
|||
// tag::frame[] |
|||
image:logo.png[role="related thumb right"] Here's text that will wrap around the image to the left. |
|||
// end::frame[] |
|||
|
|||
// tag::url[] |
|||
image::https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Tux,250,350] |
|||
// end::url[] |
|||
|
|||
// tag::in-url[] |
|||
You can find image:https://upload.wikimedia.org/wikipedia/commons/3/35/Tux.svg[Linux,25,35] everywhere these days. |
|||
// end::in-url[] |
|||
|
|||
// tag::base-url[] |
|||
:imagesdir-old: {imagesdir} |
|||
:imagesdir: https://upload.wikimedia.org/wikipedia/commons |
|||
|
|||
image::3/35/Tux.svg[Tux,250,350] |
|||
|
|||
:imagesdir: {imagesdir-old} |
|||
// end::base-url[] |
|||
|
|||
// tag::ab-url[] |
|||
image::https://asciidoctor.org/images/octocat.jpg[GitHub mascot] |
|||
// end::ab-url[] |
|||
|
|||
// tag::data[] |
|||
= Document Title |
|||
:data-uri: |
|||
// end::data[] |
|||
@ -0,0 +1,96 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Include Directive |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
= Reference Documentation |
|||
Lead Developer |
|||
|
|||
This is documentation for project X. |
|||
|
|||
\include::basics.adoc[] |
|||
|
|||
\include::installation.adoc[] |
|||
|
|||
\include::example.adoc[] |
|||
// end::base[] |
|||
|
|||
// tag::line[] |
|||
\include::filename.txt[lines=5..10] |
|||
// end::line[] |
|||
|
|||
// tag::m-line-comma[] |
|||
\include::filename.txt[lines="1..10,15..20"] |
|||
// end::m-line-comma[] |
|||
|
|||
// tag::m-line[] |
|||
\include::filename.txt[lines=7;14..25;28..43] |
|||
// end::m-line[] |
|||
|
|||
// tag::last[] |
|||
\include::filename.txt[lines=12..-1] |
|||
// end::last[] |
|||
|
|||
[source,ruby] |
|||
---- |
|||
// tag::tag-co[] |
|||
# tag::timings[{blank}] <1> <2> |
|||
if timings |
|||
timings.record :read |
|||
timings.start :parse |
|||
end |
|||
# end::timings[{blank}] <3> <4> |
|||
# tag::parse[{blank}] <5> |
|||
doc = (options[:parse] == false ? (Document.new lines, options) : |
|||
(Document.new lines,options).parse) |
|||
timings.record :parse if timings |
|||
doc |
|||
# end::parse[{blank}] <6> |
|||
// end::tag-co[] |
|||
---- |
|||
|
|||
// tag::target-co[] |
|||
[source,ruby] |
|||
---- |
|||
include::core.rb[tag=parse] // <1> |
|||
---- |
|||
// end::target-co[] |
|||
|
|||
// tag::target-co-multiple[] |
|||
[source,ruby] |
|||
---- |
|||
\include::core.rb[tags=timings;parse] |
|||
---- |
|||
// end::target-co-multiple[] |
|||
|
|||
// tag::tag[] |
|||
[source,groovy] |
|||
-- |
|||
\include::example.groovy[tag=classdef] |
|||
-- |
|||
// end::tag[] |
|||
|
|||
// tag::target[] |
|||
import foo |
|||
// tag::classdef[] |
|||
class Bar { |
|||
// ... |
|||
} |
|||
// end::classdef[] |
|||
// end::target[] |
|||
|
|||
// tag::out[] |
|||
[source,groovy] |
|||
-- |
|||
class Bar { |
|||
// ... |
|||
} |
|||
-- |
|||
// end::out[] |
|||
|
|||
// tag::uri[] |
|||
\include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/README.adoc[] |
|||
// end::uri[] |
|||
@ -0,0 +1,27 @@ |
|||
//// |
|||
User Manual - keyword metadata example |
|||
|
|||
//// |
|||
|
|||
// tag::key-base[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
Kismet Rainbow Chameleon <kismet@asciidoctor.org>; Lazarus het_Draeke <lazarus@asciidoctor.org> |
|||
:keywords: documentation, team, obstacles, journey, victory |
|||
|
|||
This journey begins on a bleary Monday morning. |
|||
// end::key-base[] |
|||
|
|||
// tag::key-html[] |
|||
[source,xml] |
|||
---- |
|||
<!DOCTYPE html> |
|||
<html lang="en"> |
|||
<head> |
|||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
|||
<meta name="generator" content="Asciidoctor 1.5.6.1"> |
|||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
|||
<meta name="keywords" content="documentation, team, obstacles, journey, victory"> |
|||
<title>The Dangerous and Thrilling Documentation Chronicles</title> |
|||
<style> |
|||
---- |
|||
// end::key-html[] |
|||
@ -0,0 +1,77 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Listing |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::para[] |
|||
[listing] |
|||
This is an example of a paragraph styled with `listing`. |
|||
Notice that the monospace markup is preserved in the output. |
|||
// end::para[] |
|||
|
|||
// tag::bl[] |
|||
---- |
|||
This is an example of a _listing block_. |
|||
The content inside is displayed as <pre> text. |
|||
---- |
|||
// end::bl[] |
|||
|
|||
// tag::b-base[] |
|||
.Gemfile.lock |
|||
---- |
|||
GEM |
|||
remote: https://rubygems.org/ |
|||
specs: |
|||
asciidoctor (1.5.6.1) |
|||
|
|||
PLATFORMS |
|||
ruby |
|||
|
|||
DEPENDENCIES |
|||
asciidoctor (~> 1.5.6.1) |
|||
---- |
|||
// end::b-base[] |
|||
|
|||
// tag::subs[] |
|||
:version: 1.5.6.1 |
|||
|
|||
[source,xml,subs="verbatim,attributes"] |
|||
---- |
|||
<dependency> |
|||
<groupId>org.asciidoctor</groupId> |
|||
<artifactId>asciidoctor-java-integration</artifactId> |
|||
<version>{version}</version> |
|||
</dependency> |
|||
---- |
|||
// end::subs[] |
|||
|
|||
// tag::subs-out[] |
|||
[source,xml] |
|||
---- |
|||
<dependency> |
|||
<groupId>org.asciidoctor</groupId> |
|||
<artifactId>asciidoctor-java-integration</artifactId> |
|||
<version>1.5.6.1</version> |
|||
</dependency> |
|||
---- |
|||
// end::subs-out[] |
|||
|
|||
// tag::nowrap[] |
|||
[source%nowrap,java] |
|||
---- |
|||
public class ApplicationConfigurationProvider extends HttpConfigurationProvider |
|||
{ |
|||
@Override |
|||
public Configuration getConfiguration(ServletContext context) |
|||
{ |
|||
return ConfigurationBuilder.begin() |
|||
.addRule() |
|||
.when(Direction.isInbound().and(Path.matches("/{path}"))) |
|||
.perform(Log.message(Level.INFO, "Client requested path: {path}")) |
|||
.where("path").matches(".*"); |
|||
} |
|||
} |
|||
---- |
|||
// end::nowrap[] |
|||
@ -0,0 +1,58 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Literal Text and Blocks |
|||
- quick-syntax |
|||
//// |
|||
|
|||
// tag::imp[] |
|||
~/secure/vault/defops |
|||
// end::imp[] |
|||
|
|||
// tag::b-imp[] |
|||
A normal paragraph. |
|||
|
|||
A paragraph offset by at least one space becomes a literal paragraph. |
|||
All lines in a literal paragraph must be adjacent. |
|||
|
|||
A literal paragraph is displayed as preformatted text. |
|||
The text is shown in a fixed-width font. |
|||
Spaces and newlines, |
|||
like the ones in this sentence, |
|||
are preserved. |
|||
|
|||
Another normal paragraph. |
|||
// end::b-imp[] |
|||
|
|||
// tag::b-imp-code[] |
|||
Indent the line one space to insert a code snippet |
|||
// end::b-imp-code[] |
|||
|
|||
// tag::para[] |
|||
[literal] |
|||
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual |
|||
absolutely fatal: operation initiation lost in the dodecahedron of doom |
|||
would you like to die again? y/n |
|||
// end::para[] |
|||
|
|||
// tag::block[] |
|||
.... |
|||
Lazarus: Where is the *defensive operations manual*? |
|||
|
|||
Computer: Calculating ... |
|||
Can not locate object that you are not authorized to know exists. |
|||
Would you like to ask another question? |
|||
|
|||
Lazarus: Did the werewolves tell you to say that? |
|||
|
|||
Computer: Calculating ... |
|||
.... |
|||
// end::block[] |
|||
|
|||
// tag::b-block[] |
|||
.... |
|||
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual |
|||
absolutely fatal: operation initiation lost in the dodecahedron of doom |
|||
would you like to die again? y/n |
|||
.... |
|||
// end::b-block[] |
|||
@ -0,0 +1,42 @@ |
|||
= eve(1) |
|||
Andrew Stanton |
|||
v1.0.0 |
|||
:doctype: manpage |
|||
:manmanual: EVE |
|||
:mansource: EVE |
|||
:man-linkstyle: pass:[blue R < >] |
|||
|
|||
== Name |
|||
|
|||
eve - analyzes an image to determine if it's a picture of a life form |
|||
|
|||
== Synopsis |
|||
|
|||
*eve* [_OPTION_]... _FILE_... |
|||
|
|||
== Options |
|||
|
|||
*-o, --out-file*=_OUT_FILE_:: |
|||
Write result to file _OUT_FILE_. |
|||
|
|||
*-c, --capture*:: |
|||
Capture specimen if it's a picture of a life form. |
|||
|
|||
== Exit status |
|||
|
|||
*0*:: |
|||
Success. |
|||
Image is a picture of a life form. |
|||
|
|||
*1*:: |
|||
Failure. |
|||
Image is not a picture of a life form. |
|||
|
|||
== Resources |
|||
|
|||
*Project web site:* http://eve.example.org |
|||
|
|||
== Copying |
|||
|
|||
Copyright (C) 2008 {author}. + |
|||
Free use of this software is granted under the terms of the MIT License. |
|||
@ -0,0 +1,104 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Ordered list |
|||
- quick-ref |
|||
- writers guide |
|||
//// |
|||
|
|||
// tag::b-base[] |
|||
. Step 1 |
|||
. Step 2 |
|||
. Step 3 |
|||
// end::b-base[] |
|||
|
|||
// tag::base[] |
|||
. Protons |
|||
. Electrons |
|||
. Neutrons |
|||
// end::base[] |
|||
|
|||
// tag::base-start[] |
|||
[start=4] |
|||
. Step four |
|||
. Step five |
|||
. Step six |
|||
// end::base-start[] |
|||
|
|||
// tag::base-num[] |
|||
1. Protons |
|||
2. Electrons |
|||
3. Neutrons |
|||
// end::base-num[] |
|||
|
|||
// tag::base-num-start[] |
|||
4. Step four |
|||
5. Step five |
|||
6. Step six |
|||
// end::base-num-start[] |
|||
|
|||
// tag::base-t[] |
|||
.Parts of an atom |
|||
. Protons |
|||
. Electrons |
|||
. Neutrons |
|||
// end::base-t[] |
|||
|
|||
// tag::reversed[] |
|||
[%reversed] |
|||
.Parts of an atom |
|||
. Protons |
|||
. Electrons |
|||
. Neutrons |
|||
// end::reversed[] |
|||
|
|||
// tag::nest[] |
|||
. Step 1 |
|||
. Step 2 |
|||
.. Step 2a |
|||
.. Step 2b |
|||
. Step 3 |
|||
// end::nest[] |
|||
|
|||
// tag::max[] |
|||
. level 1 |
|||
.. level 2 |
|||
... level 3 |
|||
.... level 4 |
|||
..... level 5 |
|||
. level 1 |
|||
// end::max[] |
|||
|
|||
// tag::num[] |
|||
["lowerroman", start=5] |
|||
. Five |
|||
. Six |
|||
[loweralpha] |
|||
.. a |
|||
.. b |
|||
.. c |
|||
. Seven |
|||
// end::num[] |
|||
|
|||
// tag::mix[] |
|||
. Linux |
|||
* Fedora |
|||
* Ubuntu |
|||
* Slackware |
|||
. BSD |
|||
* FreeBSD |
|||
* NetBSD |
|||
// end::mix[] |
|||
|
|||
// tag::mix-alt[] |
|||
. Linux |
|||
|
|||
* Fedora |
|||
* Ubuntu |
|||
* Slackware |
|||
|
|||
. BSD |
|||
|
|||
* FreeBSD |
|||
* NetBSD |
|||
// end::mix-alt[] |
|||
@ -0,0 +1,30 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Open Block |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
-- |
|||
An open block can be an anonymous container, |
|||
or it can masquerade as any other block. |
|||
-- |
|||
// end::base[] |
|||
|
|||
// tag::src[] |
|||
[source] |
|||
-- |
|||
puts "I'm a source block!" |
|||
-- |
|||
// end::src[] |
|||
|
|||
// tag::sb[] |
|||
[sidebar] |
|||
.Related information |
|||
-- |
|||
This is aside text. |
|||
|
|||
It is used to present information related to the main content. |
|||
-- |
|||
// end::sb[] |
|||
@ -0,0 +1,112 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Macro and Block Passthroughs |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::dollar[] |
|||
$$*Stars*$$ will not be bold. |
|||
// end::dollar[] |
|||
|
|||
// tag::b-dollar[] |
|||
$$*Stars*$$ is not rendered as bold text. |
|||
The asterisks around the word are preserved. |
|||
|
|||
$$&$$ renders as an XML entity instead of &. |
|||
// end::b-dollar[] |
|||
|
|||
// tag::in-macro[] |
|||
The text pass:[<u>underline me</u>] is underlined. |
|||
// end::in-macro[] |
|||
|
|||
// tag::s-macro[] |
|||
The text pass:q[<u>underline *me*</u>] is underlined and the word "`me`" is bold. |
|||
// end::s-macro[] |
|||
|
|||
// tag::3p[] |
|||
The text +++<u>underline me</u>+++ is underlined. |
|||
// end::3p[] |
|||
|
|||
// tag::b-3p-macro[] |
|||
+++<u>underline me</u>+++ is underlined. |
|||
|
|||
pass:[<u>underline me</u>] is also underlined. |
|||
// end::b-3p-macro[] |
|||
|
|||
// tag::tick[] |
|||
This java code: `System.out.println("No *bold* here");` will appear in a monospace font but without any other text formatting. |
|||
// end::tick[] |
|||
|
|||
// tag::plus[] |
|||
Text between + characters, such as +/user/{name}+, is not substituted. |
|||
However, special characters like +<+ and +>+ are still escaped. |
|||
|
|||
You can write `C++{plus}{plus}++` as `+{cpp}+`. |
|||
// end::plus[] |
|||
|
|||
// tag::backtick-plus[] |
|||
Output literal monospace text such as `+{backtick}+` by |
|||
enclosing the text in pluses, then in backticks. |
|||
// end::backtick-plus[] |
|||
|
|||
// tag::b-tick[] |
|||
`Text in {backticks}` renders exactly as entered, in `monospace`. |
|||
The attribute reference is not resolved. |
|||
// end::b-tick[] |
|||
|
|||
// tag::sub-in[] |
|||
[subs=+macros] <1> |
|||
---- |
|||
I better not contain *bold* or _italic_ text. |
|||
pass:quotes[But I should contain *bold* text.] <2> |
|||
---- |
|||
// end::sub-in[] |
|||
|
|||
// tag::sub-out[] |
|||
[subs=+macros] |
|||
---- |
|||
I better not contain *bold* or _italic_ text. |
|||
pass:quotes[But I should contain *bold* text.] |
|||
---- |
|||
// end::sub-out[] |
|||
|
|||
// tag::bl[] |
|||
++++ |
|||
<video poster="images/movie-reel.png"> |
|||
<source src="videos/writing-zen.webm" type="video/webm"> |
|||
</video> |
|||
++++ |
|||
// end::bl[] |
|||
|
|||
// tag::b-bl[] |
|||
++++ |
|||
<p> |
|||
Content in a passthrough block is passed to the output unprocessed. |
|||
That means you can include raw HTML, like this embedded Gist: |
|||
</p> |
|||
|
|||
<script src="https://gist.github.com/mojavelinux/5333524.js"> |
|||
</script> |
|||
++++ |
|||
// end::b-bl[] |
|||
|
|||
// tag::subs-bl[] |
|||
[subs=attributes] |
|||
++++ |
|||
{name} |
|||
image:tiger.png[] |
|||
++++ |
|||
// end::subs-bl[] |
|||
|
|||
// tag::no-para[] |
|||
[subs=normal] |
|||
++++ |
|||
Normal content which is not enclosed in a paragraph. |
|||
++++ |
|||
// end::no-para[] |
|||
|
|||
// tag::pass-style[] |
|||
[pass] |
|||
<u>underline me</u> is underlined. |
|||
// end::pass-style[] |
|||
@ -0,0 +1,99 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Quotes |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::bl[] |
|||
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg] |
|||
____ |
|||
Four score and seven years ago our fathers brought forth |
|||
on this continent a new nation... |
|||
____ |
|||
// end::bl[] |
|||
|
|||
// tag::bl-alt[] |
|||
[quote, Thomas Jefferson, Papers of Thomas Jefferson: Volume 11] |
|||
____ |
|||
I hold it that a little rebellion now and then is a good thing, |
|||
and as necessary in the political world as storms in the physical. |
|||
____ |
|||
// end::bl-alt[] |
|||
|
|||
// tag::para[] |
|||
[quote, Albert Einstein] |
|||
A person who never made a mistake never tried anything new. |
|||
// end::para[] |
|||
|
|||
// tag::para2-c[] |
|||
.After landing the cloaked Klingon bird of prey in Golden Gate park: // <1> |
|||
[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home] // <2> <3> <4> |
|||
Everybody remember where we parked. // <5> |
|||
// end::para2-c[] |
|||
|
|||
// tag::para2[] |
|||
.After landing the cloaked Klingon bird of prey in Golden Gate park: |
|||
[quote, Captain James T. Kirk, Star Trek IV: The Voyage Home] |
|||
Everybody remember where we parked. |
|||
// end::para2[] |
|||
|
|||
// tag::comp[] |
|||
[quote, Monty Python and the Holy Grail] |
|||
____ |
|||
Dennis: Come and see the violence inherent in the system. Help! Help! I'm being repressed! |
|||
|
|||
King Arthur: Bloody peasant! |
|||
|
|||
Dennis: Oh, what a giveaway! Did you hear that? Did you hear that, eh? That's what I'm on about! Did you see him repressing me? You saw him, Didn't you? |
|||
____ |
|||
// end::comp[] |
|||
|
|||
// tag::no-cite[] |
|||
____ |
|||
A person who never made a mistake never tried anything new. |
|||
____ |
|||
// end::no-cite[] |
|||
|
|||
// tag::abbr[] |
|||
"I hold it that a little rebellion now and then is a good thing, |
|||
and as necessary in the political world as storms in the physical." |
|||
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11 |
|||
// end::abbr[] |
|||
|
|||
// tag::air[] |
|||
[, James Baldwin] |
|||
"" |
|||
Not everything that is faced can be changed. |
|||
But nothing can be changed until it is faced. |
|||
"" |
|||
// end::air[] |
|||
|
|||
// tag::md[] |
|||
> I hold it that a little rebellion now and then is a good thing, |
|||
> and as necessary in the political world as storms in the physical. |
|||
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11 |
|||
// end::md[] |
|||
|
|||
// tag::md-alt[] |
|||
> > What's new? |
|||
> |
|||
> I've got Markdown in my AsciiDoc! |
|||
> |
|||
> > Like what? |
|||
> |
|||
> * Blockquotes |
|||
> * Headings |
|||
> * Fenced code blocks |
|||
> |
|||
> > Is there more? |
|||
> |
|||
> Yep. AsciiDoc and Markdown share a lot of common syntax already. |
|||
// end::md-alt[] |
|||
|
|||
// tag::link-text[] |
|||
[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as https://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]'] |
|||
____ |
|||
If you don't know where you are going, any road will get you there. |
|||
____ |
|||
// end::link-text[] |
|||
@ -0,0 +1,51 @@ |
|||
//// |
|||
Example |
|||
|
|||
Included in: |
|||
|
|||
- user-manual: Header |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
Kismet Chameleon <kismet@asciidoctor.org> |
|||
v1.0, October 2, 2013: First incarnation // <1> <2> <3> |
|||
|
|||
This journey begins... |
|||
|
|||
== Colophon |
|||
|
|||
Version: {revnumber} |
|||
|
|||
Version Date: {revdate} |
|||
|
|||
Version Notes: {revremark} |
|||
// end::base[] |
|||
|
|||
// tag::b-base[] |
|||
= My Document's Title |
|||
Doc Writer <doc.writer@asciidoctor.org> |
|||
v1.0, 2014-01-01 |
|||
|
|||
My document provides... |
|||
// end::b-base[] |
|||
|
|||
// tag::attr[] |
|||
= The Dangerous and Thrilling Documentation Chronicles |
|||
Kismet Chameleon <kismet@asciidoctor.org> |
|||
:revnumber: 1.0 // <1> |
|||
:revdate: 10-02-2013 |
|||
:revremark: The first incarnation of {doctitle} // <2> |
|||
:version-label!: // <3> |
|||
|
|||
This journey begins... |
|||
|
|||
== Colophon |
|||
|
|||
Version: {revnumber} |
|||
|
|||
Version Date: {revdate} |
|||
|
|||
Version Notes: {revremark} |
|||
// end::attr[] |
|||
@ -0,0 +1,203 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Sections |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
= Document Title (Level 0) |
|||
|
|||
== Level 1 Section Title |
|||
|
|||
=== Level 2 Section Title |
|||
|
|||
==== Level 3 Section Title |
|||
|
|||
===== Level 4 Section Title |
|||
|
|||
====== Level 5 Section Title |
|||
|
|||
== Another Level 1 Section Title |
|||
// end::base[] |
|||
|
|||
// tag::b-base[] |
|||
// the float style is required to create standalone (non-section) headings |
|||
[float] |
|||
= Document Title (Level 0) |
|||
|
|||
[float] |
|||
== Level 1 Section Title |
|||
|
|||
[float] |
|||
=== Level 2 Section Title |
|||
|
|||
[float] |
|||
==== Level 3 Section Title |
|||
|
|||
[float] |
|||
===== Level 4 Section Title |
|||
|
|||
[float] |
|||
====== Level 5 Section Title |
|||
|
|||
[float] |
|||
== Another Level 1 Section Title |
|||
// end::b-base[] |
|||
|
|||
// tag::bad[] |
|||
= Document Title |
|||
|
|||
= Illegal Level 0 Section (violates rule #1) |
|||
|
|||
== First Section |
|||
|
|||
==== Illegal Nested Section (violates rule #2) |
|||
// end::bad[] |
|||
|
|||
// tag::content[] |
|||
== First Section |
|||
|
|||
Content of first section |
|||
|
|||
=== Nested Section |
|||
|
|||
Content of nested section |
|||
|
|||
== Second Section |
|||
|
|||
Content of second section |
|||
// end::content[] |
|||
|
|||
// tag::book[] |
|||
= Document Title (Level 0) |
|||
|
|||
== Section Level 1 |
|||
|
|||
=== Section Level 2 |
|||
|
|||
==== Section Level 3 |
|||
|
|||
===== Section Level 4 |
|||
|
|||
====== Section Level 5 |
|||
|
|||
= Section Level 0 |
|||
// end::book[] |
|||
|
|||
// tag::b-book[] |
|||
// the float style is required to create standalone (non-section) headings |
|||
[float] |
|||
= Document Title (Level 0) |
|||
|
|||
[float] |
|||
== Section Level 1 |
|||
|
|||
[float] |
|||
=== Section Level 2 |
|||
|
|||
[float] |
|||
==== Section Level 3 |
|||
|
|||
[float] |
|||
===== Section Level 4 |
|||
|
|||
[float] |
|||
====== Section Level 5 |
|||
|
|||
[float] |
|||
= Section Level 0 |
|||
// end::b-book[] |
|||
|
|||
// tag::with-anchor-shorthand[] |
|||
[#tiger-subspecies] |
|||
=== Subspecies of Tiger |
|||
// end::with-anchor-shorthand[] |
|||
|
|||
// tag::with-anchor-and-reftext[] |
|||
[[tiger-subspecies,Tigers]] |
|||
=== Subspecies of Tiger |
|||
// end::with-anchor-and-reftext[] |
|||
|
|||
// tag::with-anchor-and-reftext-shorthand[] |
|||
[#tiger-subspecies,reftext=Tigers] |
|||
=== Subspecies of Tiger |
|||
// end::with-anchor-and-reftext-shorthand[] |
|||
|
|||
// tag::num-off[] |
|||
:sectnums!: |
|||
|
|||
== Unnumbered Section |
|||
// end::num-off[] |
|||
|
|||
// tag::num[] |
|||
= Document Title |
|||
|
|||
:sectnums!: |
|||
|
|||
== Colophon Section |
|||
|
|||
== Another Colophon Section |
|||
|
|||
== Last Colophon Section |
|||
|
|||
:sectnums: |
|||
|
|||
== Section One |
|||
|
|||
== Section Two |
|||
|
|||
== Section Three |
|||
// end::num[] |
|||
|
|||
// tag::num-out[] |
|||
Colophon Section |
|||
|
|||
Another Colophon Section |
|||
|
|||
Last Colophon Section |
|||
|
|||
1. Section One |
|||
|
|||
2. Section Two |
|||
|
|||
3. Section Three |
|||
// end::num-out[] |
|||
|
|||
// tag::sectnuml[] |
|||
:sectnumlevels: 2 // <1> |
|||
// end::sectnuml[] |
|||
|
|||
// tag::md[] |
|||
# Document Title (Level 0) |
|||
|
|||
## Section Level 1 |
|||
|
|||
### Section Level 2 |
|||
|
|||
#### Section Level 3 |
|||
|
|||
##### Section Level 4 |
|||
|
|||
###### Section Level 5 |
|||
// end::md[] |
|||
|
|||
// tag::b-md[] |
|||
[float] |
|||
# Document Title (Level 0) |
|||
|
|||
[float] |
|||
## Section Level 1 |
|||
|
|||
[float] |
|||
### Section Level 2 |
|||
|
|||
[float] |
|||
#### Section Level 3 |
|||
|
|||
[float] |
|||
##### Section Level 4 |
|||
|
|||
[float] |
|||
###### Section Level 5 |
|||
// end::b-md[] |
|||
@ -0,0 +1,24 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Sidebar |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base-c[] |
|||
.AsciiDoc history // <1> |
|||
**** // <2> |
|||
AsciiDoc was first released in Nov 2002 by Stuart Rackham. |
|||
It was designed from the start to be a shorthand syntax |
|||
for producing professional documents like DocBook and LaTeX. |
|||
**** |
|||
// end::base-c[] |
|||
|
|||
// tag::base[] |
|||
.AsciiDoc history |
|||
**** |
|||
AsciiDoc was first released in Nov 2002 by Stuart Rackham. |
|||
It was designed from the start to be a shorthand syntax |
|||
for producing professional documents like DocBook and LaTeX. |
|||
**** |
|||
// end::base[] |
|||
@ -0,0 +1,110 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Source blocks |
|||
//// |
|||
|
|||
// tag::src-base[] |
|||
.app.rb |
|||
[source,ruby] |
|||
---- |
|||
require 'sinatra' |
|||
|
|||
get '/hi' do |
|||
"Hello World!" |
|||
end |
|||
---- |
|||
// end::src-base[] |
|||
|
|||
// tag::src-base-co[] |
|||
.app.rb // <1> |
|||
[#src-listing] <2> |
|||
[source,ruby] // <3> <4> |
|||
---- // <5> |
|||
require 'sinatra' |
|||
|
|||
get '/hi' do |
|||
"Hello World!" |
|||
end |
|||
---- |
|||
// end::src-base-co[] |
|||
|
|||
// src-base-co-res is the result of src-base-co |
|||
// tag::src-base-co-res[] |
|||
[#src-listing] |
|||
[source,ruby] |
|||
.app.rb |
|||
---- |
|||
require 'sinatra' |
|||
|
|||
get '/hi' do |
|||
"Hello World!" |
|||
end |
|||
---- |
|||
// end::src-base-co-res[] |
|||
|
|||
// tag::src-para-co[] |
|||
[source,xml] <!--1--> |
|||
<meta name="viewport" |
|||
content="width=device-width, initial-scale=1.0"> |
|||
|
|||
This is normal content. // <2> |
|||
// end::src-para-co[] |
|||
|
|||
// tag::src-para[] |
|||
[source,xml] |
|||
<meta name="viewport" |
|||
content="width=device-width, initial-scale=1.0"> |
|||
|
|||
This is normal content. |
|||
// end::src-para[] |
|||
|
|||
// tag::src-lang[] |
|||
:source-highlighter: pygments |
|||
:source-language: java |
|||
|
|||
[source] |
|||
---- |
|||
public void setAttributes(Attributes attributes) { |
|||
this.options.put(ATTRIBUTES, attributes.map()); |
|||
} |
|||
---- |
|||
|
|||
You can override the global source language by specifying a source language on the block. |
|||
|
|||
[source,ruby] |
|||
require 'sinatra' |
|||
// end::src-lang[] |
|||
|
|||
// tag::src-inc[] |
|||
[source,ruby] |
|||
---- |
|||
\include::app.rb[] |
|||
---- |
|||
// end::src-inc[] |
|||
|
|||
// tag::rel[] |
|||
:sourcedir: src/main/java |
|||
|
|||
[source,java] |
|||
---- |
|||
\include::{sourcedir}/org/asciidoctor/Asciidoctor.java[] |
|||
---- |
|||
// end::rel[] |
|||
|
|||
// tag::ind[] |
|||
[source,ruby,indent=0] |
|||
---- |
|||
\include::lib/document.rb[lines=5..10] |
|||
---- |
|||
// end::ind[] |
|||
|
|||
// tag::fence[] |
|||
```ruby |
|||
require 'sinatra' |
|||
|
|||
get '/hi' do |
|||
"Hello World!" |
|||
end |
|||
``` |
|||
// end::fence[] |
|||
@ -0,0 +1,74 @@ |
|||
//// |
|||
Used in: |
|||
|
|||
User manual: Equations and Formulas |
|||
//// |
|||
|
|||
// tag::base-co[] |
|||
= My Diabolical Mathmatical Opus |
|||
Jamie Moriarty |
|||
:stem: // <1> |
|||
// end::base-co[] |
|||
|
|||
// tag::base-alt[] |
|||
= My Diabolical Mathmatical Opus |
|||
Jamie Moriarty |
|||
:stem: latexmath |
|||
// end::base-alt[] |
|||
|
|||
// tag::in-co[] |
|||
stem:[sqrt(4) = 2] // <1> <2> |
|||
|
|||
Water (stem:[H_2O]) is a critical component. |
|||
// end::in-co[] |
|||
|
|||
// tag::in[] |
|||
stem:[sqrt(4) = 2] |
|||
|
|||
Water (stem:[H_2O]) is a critical component. |
|||
// end::in[] |
|||
|
|||
// tag::in-sb[] |
|||
A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))]. |
|||
// end::in-sb[] |
|||
|
|||
// tag::bl-macro[] |
|||
.Exponential growth |
|||
stem::[x_0(1 + r)^2] |
|||
// end::bl-macro[] |
|||
|
|||
// tag::bl-co[] |
|||
[stem] // <1> |
|||
++++ // <2> |
|||
sqrt(4) = 2 |
|||
++++ |
|||
// end::bl-co[] |
|||
|
|||
// tag::bl[] |
|||
[stem] |
|||
++++ |
|||
sqrt(4) = 2 |
|||
++++ |
|||
// end::bl[] |
|||
|
|||
// tag::bl-alt[] |
|||
[latexmath] |
|||
++++ |
|||
x = {-b \pm \sqrt{b^2-4ac} \over 2a} |
|||
++++ |
|||
// end:: bl-alt[] |
|||
|
|||
// tag::multi-l[] |
|||
latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon] |
|||
// end::multi-l[] |
|||
|
|||
// tag::multi-a[] |
|||
= My Diabolical Mathmatical Opus |
|||
Jamie Moriarty |
|||
:stem: latexmath |
|||
|
|||
[asciimath] |
|||
++++ |
|||
sqrt(4) = 2 |
|||
++++ |
|||
// end::multi-a[] |
|||
@ -0,0 +1,89 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Text Substitutions: Preventing substitutions |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::slash[] |
|||
\*Stars* will appear as *Stars*, not as bold text. |
|||
|
|||
\§ will appear as an entity, not the § symbol. |
|||
|
|||
\\__func__ will appear as __func__, not as emphasized text. |
|||
|
|||
\{two-semicolons} will appear {two-semicolons}, not resolved as ;;. |
|||
// end::slash[] |
|||
|
|||
// tag::b-slash[] |
|||
\*Stars* is not rendered as bold text. |
|||
The asterisks around the word are preserved. |
|||
|
|||
\{author} is not resolved to the author name. |
|||
The curly brackets around the word are preserved. |
|||
|
|||
`A\--Z` connects A to Z in monospace using two dashes. |
|||
The dashes are not replaced by an em dash. |
|||
|
|||
\=> is an equal sign followed by a greater than sign. |
|||
The two characters are not combined to form a double arrow. |
|||
|
|||
\[[Word]] is not interpreted as an anchor. |
|||
The double brackets around the word are preserved. |
|||
|
|||
[\[[Word]]] is not interpreted as a bibliography anchor. |
|||
The triple brackets around the word are preserved. |
|||
|
|||
In these cases, the backslash character is automatically removed. |
|||
// end::b-slash[] |
|||
|
|||
// tag::subs-in[] |
|||
[source,java,subs="verbatim,quotes"] <1> |
|||
---- |
|||
System.out.println("Hello *bold* text"). <2> |
|||
---- |
|||
// end::subs-in[] |
|||
|
|||
// tag::subs-out[] |
|||
[source,java,subs="verbatim,quotes"] |
|||
---- |
|||
System.out.println("Hello *bold* text"). <1> <2> |
|||
---- |
|||
// end::subs-out[] |
|||
|
|||
// tag::subs-add[] |
|||
[source,xml,subs="attributes+"] |
|||
---- |
|||
<version>{version}</version> |
|||
---- |
|||
// end::subs-add[] |
|||
|
|||
// tag::subs-sub[] |
|||
[source,xml,subs="-callouts"] |
|||
.An illegal XML tag |
|||
---- |
|||
<1> |
|||
content inside "1" tag |
|||
</1> |
|||
---- |
|||
// end::subs-sub[] |
|||
|
|||
// tag::subs-multi[] |
|||
[source,xml,subs="attributes+,+replacements,-callouts"] |
|||
---- |
|||
<version>{version}</version> |
|||
<copyright>(C) ACME</copyright> |
|||
<1> |
|||
content inside "1" tag |
|||
</1> |
|||
---- |
|||
// end::subs-multi[] |
|||
|
|||
// tag::subs-attr[] |
|||
:markup-in-source: verbatim,quotes |
|||
|
|||
[source,java,subs="{markup-in-source}"] |
|||
---- |
|||
System.out.println("Hello *bold* text"). |
|||
---- |
|||
// end::subs-attr[] |
|||
@ -0,0 +1,157 @@ |
|||
//// |
|||
Examples for table sections, cell specifiers |
|||
//// |
|||
|
|||
// tag::3dup[] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 |
|||
|
|||
3*|Same cell content in columns 1, 2, and 3 |
|||
|
|||
|Cell in column 1, row 3 |
|||
|Cell in column 2, row 3 |
|||
|Cell in column 3, row 3 |
|||
|
|||
|=== |
|||
// end::3dup[] |
|||
|
|||
// tag::3span[] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 |
|||
|
|||
3+|Content in a single cell that spans columns 1, 2, and 3 |
|||
|
|||
|Cell in column 1, row 3 |
|||
|Cell in column 2, row 3 |
|||
|Cell in column 3, row 3 |
|||
|
|||
|=== |
|||
// end::3span[] |
|||
|
|||
// tag::2span-r[] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 |
|||
|
|||
.2+|Content in a single cell that spans rows 2 and 3 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|
|||
|Cell in column 2, row 3 |
|||
|Cell in column 3, row 3 |
|||
|
|||
|=== |
|||
// end::2span-r[] |
|||
|
|||
// tag::span-cr[] |
|||
|=== |
|||
|
|||
|Column 1, row 1 |Column 2, row 1 |Column 3, row 1 |Column 4, row 1 |
|||
|
|||
|Column 1, row 2 |
|||
2.3+|Content in a single cell that spans over rows and columns |
|||
|Column 4, row 2 |
|||
|
|||
|Column 1, row 3 |
|||
|Column 4, row 3 |
|||
|
|||
|Column 1, row 4 |
|||
|Column 4, row 4 |
|||
|=== |
|||
// end::span-cr[] |
|||
|
|||
// tag::cell-align[] |
|||
[cols="3"] |
|||
|=== |
|||
^|Prefix the `{vbar}` with `{caret}` to center content horizontally |
|||
<|Prefix the `{vbar}` with `<` to align the content to the left horizontally |
|||
>|Prefix the `{vbar}` with `>` to align the content to the right horizontally |
|||
|
|||
.^|Prefix the `{vbar}` with a `.` and `{caret}` to center the content in the cell vertically |
|||
.<|Prefix the `{vbar}` with a `.` and `<` to align the content to the top of the cell |
|||
.>|Prefix the `{vbar}` with a `.` and `>` to align the content to the bottom of the cell |
|||
|
|||
3+^.^|This content spans three columns (`3{plus}`) and is centered horizontally (`{caret}`) and vertically (`.{caret}`) within the cell. |
|||
|
|||
|=== |
|||
// end::cell-align[] |
|||
|
|||
// tag::cell-ad[] |
|||
[cols="2"] |
|||
|=== |
|||
|
|||
a|This cell is prefixed with an `a`, so the processor interpets the following lines as an AsciiDoc list. |
|||
|
|||
* List item 1 |
|||
* List item 2 |
|||
* List item 3 |
|||
|This cell *is not* prefixed with an `a`, so the processor does not interpret the following lines as an AsciiDoc list. |
|||
|
|||
* List item 1 |
|||
* List item 2 |
|||
* List item 3 |
|||
|
|||
a|This cell is prefixed with an `a`, so the processor honors the `lead` style on the following paragraph. |
|||
|
|||
[.lead] |
|||
I am a paragraph styled with the lead attribute. |
|||
|This cell *is not* prefixed with an `a`, so the processor does not honor the `lead` style on the following paragraph. |
|||
|
|||
[.lead] |
|||
I am a paragraph styled with the lead attribute. |
|||
|=== |
|||
// end::cell-ad[] |
|||
|
|||
// tag::cell-v[] |
|||
|=== |
|||
|
|||
2*>m|This content is duplicated across two columns. |
|||
|
|||
It is aligned right horizontally. |
|||
|
|||
And it is monospaced. |
|||
|
|||
.3+^.>s|This cell spans 3 rows. The content is centered horizontally, aligned to the bottom of the cell, and strong. |
|||
e|This content is emphasized. |
|||
|
|||
.^l|This content is aligned to the top of the cell and literal. |
|||
|
|||
v|This cell contains a verse |
|||
that may one day expound on the |
|||
wonders of tables in an |
|||
epic sonnet. |
|||
|
|||
|=== |
|||
// end::cell-v[] |
|||
|
|||
// tag::b-spec[] |
|||
[cols="e,m,^,>s", width="25%"] |
|||
|=== |
|||
|1 >s|2 |3 |4 |
|||
^|5 2.2+^.^|6 .3+<.>m|7 |
|||
^|8 |
|||
|9 2+>|10 |
|||
|=== |
|||
// end::b-spec[] |
|||
|
|||
// tag::cell-src[] |
|||
|=== |
|||
|Source Code 1 |Source Code 2 |
|||
|
|||
a| |
|||
[source,python] |
|||
---- |
|||
import os |
|||
print "%s" %(os.uname()) |
|||
---- |
|||
|
|||
a| |
|||
[source,python] |
|||
---- |
|||
import os |
|||
print ("%s" %(os.uname())) |
|||
---- |
|||
|=== |
|||
// end::cell-src[] |
|||
@ -0,0 +1,43 @@ |
|||
//// |
|||
Examples for table data format section |
|||
//// |
|||
|
|||
// tag::csv[] |
|||
[%header,format=csv] |
|||
|=== |
|||
Artist,Track,Genre |
|||
Baauer,Harlem Shake,Hip Hop |
|||
The Lumineers,Ho Hey,Folk Rock |
|||
|=== |
|||
// end::csv[] |
|||
|
|||
// tag::dsv[] |
|||
[%header,format=dsv] |
|||
|=== |
|||
Artist:Track:Genre |
|||
Robyn:Indestructable:Dance |
|||
The Piano Guys:Code Name Vivaldi:Classical |
|||
|=== |
|||
// end::dsv[] |
|||
|
|||
// tag::s-csv[] |
|||
,=== |
|||
Artist,Track,Genre |
|||
|
|||
Baauer,Harlem Shake,Hip Hop |
|||
,=== |
|||
// end::s-csv[] |
|||
|
|||
// tag::s-dsv[] |
|||
:=== |
|||
Artist:Track:Genre |
|||
|
|||
Robyn:Indestructable:Dance |
|||
:=== |
|||
// end::s-dsv[] |
|||
|
|||
// tag::i-csv[] |
|||
|=== |
|||
\include::customers.csv[] |
|||
|=== |
|||
// end::i-csv[] |
|||
@ -0,0 +1,362 @@ |
|||
//// |
|||
Examples for table sections |
|||
//// |
|||
|
|||
// tag::base-co[] |
|||
|=== <1> |
|||
<2> |
|||
| Cell in column 1, row 1 | Cell in column 2, row 1 <3> |
|||
<4> |
|||
| Cell in column 1, row 2 | Cell in column 2, row 2 |
|||
|
|||
| Cell in column 1, row 3 | Cell in column 2, row 3 |
|||
|
|||
|=== <1> |
|||
// end::base-co[] |
|||
|
|||
// tag::base-alt[] |
|||
[width="90"] |
|||
|=== |
|||
|
|||
| Cell in column 1, row 1 | Cell in column 2, row 1 |
|||
|
|||
| Cell in column 1, row 2 | Cell in column 2, row 2 |
|||
|
|||
| Cell in column 1, row 3 | Cell in column 2, row 3 |
|||
|
|||
|=== |
|||
// end::base-alt[] |
|||
|
|||
// tag::base-rolename[] |
|||
[.rolename] |
|||
|=== |
|||
|
|||
| Cell in column 1, row 1 | Cell in column 2, row 1 | Cell in column 3, row 1 |
|||
|
|||
| Cell in column 1, row 2 | Cell in column 2, row 2 | Cell in column 3, row 2 |
|||
|
|||
|=== |
|||
// end::base-rolename[] |
|||
|
|||
// tag::base[] |
|||
|=== |
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|=== |
|||
// end::base[] |
|||
|
|||
// tag::cell1[] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1|Cell in column 2, row 1 |
|||
|
|||
|=== |
|||
// end::cell1[] |
|||
|
|||
// tag::cell2[] |
|||
|=== |
|||
|
|||
| Cell in column 1, row 1 | Cell in column 2, row 1 |
|||
|
|||
|=== |
|||
// end::cell2[] |
|||
|
|||
|
|||
// tag::same[] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1 |Cell in column 2, row 1 |Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |Cell in column 2, row 2 |Cell in column 3, row 2 |
|||
|
|||
|=== |
|||
// end::same[] |
|||
|
|||
// tag::indv-co[] |
|||
[cols="3*"] <1> |
|||
|=== |
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|=== |
|||
// end::indv-co[] |
|||
|
|||
// tag::indv[] |
|||
[cols="3*"] |
|||
|=== |
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|=== |
|||
// end::indv[] |
|||
|
|||
// tag::same-indv[] |
|||
[cols="3*"] |
|||
|=== |
|||
|Cell in column 1, row 1 |Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |Cell in column 3, row 2 |
|||
|=== |
|||
// end::same-indv[] |
|||
|
|||
// tag::2col-alt[] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1 |Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|
|||
|=== |
|||
// end::2col-alt[] |
|||
|
|||
// tag::2col[] |
|||
[cols="2*"] |
|||
|=== |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|
|||
|=== |
|||
// end::2col[] |
|||
|
|||
// tag::base-xtr[] |
|||
|=== |
|||
|Cell in column 1, row 1 with lots and lots and lots and lots of content |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 and another bucket of content, and then a jelly roll of content |
|||
|=== |
|||
// end::base-xtr[] |
|||
|
|||
// tag::4col[] |
|||
|=== |
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|Cell in column 4, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|Cell in column 4, row 2 |
|||
|=== |
|||
// end::4col[] |
|||
|
|||
// tag::opt-h[] |
|||
[cols=2*,options="header"] |
|||
|=== |
|||
|Name of Column 1 |
|||
|Name of Column 2 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|=== |
|||
// end::opt-h[] |
|||
|
|||
// tag::impl-h[] |
|||
|=== |
|||
|Name of Column 1 |Name of Column 2 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|=== |
|||
// end::impl-h[] |
|||
|
|||
// tag::opt-f[] |
|||
[options="footer"] |
|||
|=== |
|||
|Name of Column 1 |Name of Column 2 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|
|||
|Footer in column 1, row 3 |
|||
|Footer in column 2, row 3 |
|||
|=== |
|||
// end::opt-f[] |
|||
|
|||
// tag::base-h[] |
|||
|=== |
|||
|Name of Column 1 |Name of Column 2 |Name of Column 3 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|=== |
|||
// end::base-h[] |
|||
|
|||
// tag::b-base-h-co[] |
|||
.Table Title |
|||
|=== |
|||
|Name of Column 1 |Name of Column 2 |Name of Column 3 <1> |
|||
<2> |
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|=== |
|||
// end::b-base-h-co[] |
|||
|
|||
// tag::b-base-h[] |
|||
.Table Title |
|||
|=== |
|||
|Name of Column 1 |Name of Column 2 |Name of Column 3 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|Cell in column 3, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|Cell in column 3, row 2 |
|||
|=== |
|||
// end::b-base-h[] |
|||
|
|||
// tag::b-col-h-co[] |
|||
[%header,cols=2*] <1> |
|||
|=== |
|||
|Name of Column 1 |
|||
|Name of Column 2 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|=== |
|||
// end::b-col-h-co[] |
|||
|
|||
// tag::b-col-h[] |
|||
[%header,cols=2*] |
|||
|=== |
|||
|Name of Column 1 |
|||
|Name of Column 2 |
|||
|
|||
|Cell in column 1, row 1 |
|||
|Cell in column 2, row 1 |
|||
|
|||
|Cell in column 1, row 2 |
|||
|Cell in column 2, row 2 |
|||
|=== |
|||
// end::b-col-h[] |
|||
|
|||
// tag::b-col-indv-co[] |
|||
[cols="1,1,2", options="header"] <1> |
|||
.Applications |
|||
|=== |
|||
|Name |
|||
|Category |
|||
|Description |
|||
|
|||
|Firefox |
|||
|Browser |
|||
|Mozilla Firefox is an open-source web browser. |
|||
It's designed for standards compliance, |
|||
performance, portability. |
|||
|
|||
|Arquillian |
|||
|Testing |
|||
|An innovative and highly extensible testing platform. |
|||
Empowers developers to easily create real, automated tests. |
|||
|=== |
|||
// end::b-col-indv-co[] |
|||
|
|||
// tag::b-col-indv[] |
|||
[cols="1,1,2", options="header"] |
|||
.Applications |
|||
|=== |
|||
|Name |
|||
|Category |
|||
|Description |
|||
|
|||
|Firefox |
|||
|Browser |
|||
|Mozilla Firefox is an open-source web browser. |
|||
It's designed for standards compliance, |
|||
performance, portability. |
|||
|
|||
|Arquillian |
|||
|Testing |
|||
|An innovative and highly extensible testing platform. |
|||
Empowers developers to easily create real, automated tests. |
|||
|=== |
|||
// end::b-col-indv[] |
|||
|
|||
// tag::b-col-a[] |
|||
[cols="2,2,5a"] |
|||
|=== |
|||
|Firefox |
|||
|Browser |
|||
|Mozilla Firefox is an open-source web browser. |
|||
|
|||
It's designed for: |
|||
|
|||
* standards compliance |
|||
* performance |
|||
* portability |
|||
|
|||
https://www.mozilla.org/en-US/firefox/new[Get Firefox]! |
|||
|=== |
|||
// end::b-col-a[] |
|||
|
|||
|
|||
// tag::nested[] |
|||
[cols="1,2a"] |
|||
|=== |
|||
| Col 1 | Col 2 |
|||
|
|||
| Cell 1.1 |
|||
| Cell 1.2 |
|||
|
|||
| Cell 2.1 |
|||
| Cell 2.2 |
|||
|
|||
[cols="2,1"] |
|||
!=== |
|||
! Col1 ! Col2 |
|||
|
|||
! C11 |
|||
! C12 |
|||
|
|||
!=== |
|||
|
|||
|=== |
|||
// end::nested[] |
|||
@ -0,0 +1,207 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Paragraphs |
|||
- user-manual: Text formatting |
|||
- quick-syntax |
|||
- writers-guide: quoted text |
|||
//// |
|||
|
|||
// tag::para[] |
|||
This journey begins one late Monday afternoon in Antwerp. |
|||
Our team desperately needs coffee, but none of us dare open the office door. |
|||
|
|||
To leave means code dismemberment and certain death. |
|||
// end::para[] |
|||
|
|||
// tag::b-para[] |
|||
Paragraphs don't require any special markup in AsciiDoc. |
|||
A paragraph is just one or more lines of consecutive text. |
|||
|
|||
To begin a new paragraph, separate it by at least one blank line. |
|||
Newlines within a paragraph are not displayed. |
|||
// end::b-para[] |
|||
|
|||
// tag::hb-all[] |
|||
Rubies are red, + |
|||
Topazes are blue. |
|||
|
|||
[%hardbreaks] |
|||
Ruby is red. |
|||
Java is black. |
|||
// end::hb-all[] |
|||
|
|||
// tag::hb[] |
|||
Rubies are red, + |
|||
Topazes are blue. |
|||
// end::hb[] |
|||
|
|||
// tag::hb-p[] |
|||
[%hardbreaks] |
|||
Ruby is red. |
|||
Java is black. |
|||
// end::hb-p[] |
|||
|
|||
// tag::b-hb[] |
|||
To preserve a line break, end the line in a space followed by a plus sign. + |
|||
This results in a visible line break (e.g., `<br>`) between the lines. |
|||
// end::b-hb[] |
|||
|
|||
// tag::hb-attr[] |
|||
= Line Break Doc Title |
|||
:hardbreaks: |
|||
|
|||
Rubies are red, |
|||
Topazes are blue. |
|||
// end::hb-attr[] |
|||
|
|||
// tag::lead[] |
|||
[.lead] |
|||
This is the ultimate paragraph. |
|||
// end::lead[] |
|||
|
|||
// tag::no-lead[] |
|||
[.normal] |
|||
This is a normal paragraph, regardless of its position in the document. |
|||
// end::no-lead[] |
|||
|
|||
// tag::b-lead[] |
|||
[.lead] |
|||
This text will be styled as a lead paragraph (i.e., larger font). |
|||
// end::b-lead[] |
|||
|
|||
// tag::b-i[] |
|||
_To tame_ the wild wolpertingers we needed to build a *charm*. |
|||
But **u**ltimate victory could only be won if we divined the *_true name_* of the __war__lock. |
|||
// end::b-i[] |
|||
|
|||
// tag::b-i-n[] |
|||
_To tame_ the wild wolpertingers we needed to build a *charm*. |
|||
But **u**ltimate victory could only be won if we divined the *_true name_* of the __war__lock. |
|||
// end::b-i-n[] |
|||
|
|||
// tag::b-bold-italic-mono[] |
|||
bold *constrained* & **un**constrained |
|||
|
|||
italic _constrained_ & __un__constrained |
|||
|
|||
bold italic *_constrained_* & **__un__**constrained |
|||
|
|||
monospace `constrained` & ``un``constrained |
|||
|
|||
monospace bold `*constrained*` & ``**un**``constrained |
|||
|
|||
monospace italic `_constrained_` & ``__un__``constrained |
|||
|
|||
monospace bold italic `*_constrained_*` & ``**__un__**``constrained |
|||
// end::b-bold-italic-mono[] |
|||
|
|||
// tag::monospace-vs-codespan[] |
|||
`{cpp}` is valid syntax in the programming language by the same name. |
|||
|
|||
`+WHERE id <= 20 AND value = "{name}"+` is a SQL WHERE clause. |
|||
// end::monospace-vs-codespan[] |
|||
|
|||
// tag::c-quote-co[] |
|||
"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`" // <1> |
|||
|
|||
Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewolves.`" // <2> |
|||
// end::c-quote-co[] |
|||
|
|||
// tag::c-quote[] |
|||
"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`" |
|||
|
|||
Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewolves.`" |
|||
// end::c-quote[] |
|||
|
|||
// tag::b-c-quote[] |
|||
"`double curved quotes`" |
|||
|
|||
'`single curved quotes`' |
|||
|
|||
Olaf's desk was a mess. |
|||
|
|||
All of the werewolves`' desks were a mess. |
|||
|
|||
Olaf had been with the company since the `'60s. |
|||
// end::b-c-quote[] |
|||
|
|||
// tag::apos[] |
|||
Olaf had been with the company since the `'60s. |
|||
His desk overflowed with heaps of paper, apple cores and squeaky toys. |
|||
We couldn't find Olaf's keyboard. |
|||
The state of his desk was replicated, in triplicate, across all of the werewolves`' desks. |
|||
// end::apos[] |
|||
|
|||
// tag::sub-sup[] |
|||
"`Well the H~2~O formula written on their whiteboard could be part of a shopping list, but I don't think the local bodega sells E=mc^2^,`" Lazarus replied. |
|||
// end::sub-sup[] |
|||
|
|||
// tag::b-sub-sup[] |
|||
^super^script phrase |
|||
|
|||
~sub~script phrase |
|||
// end::b-sub-sup[] |
|||
|
|||
// tag::mono[] |
|||
"`Wait!`" Indigo plucked a small vial from her desk's top drawer and held it toward us. |
|||
The vial's label read: `E=mc^2^`; the `_E_` represents _energy_, but also pure _genius!_ |
|||
// end::mono[] |
|||
|
|||
// tag::literal-mono[] |
|||
You can reference the value of a document attribute using the syntax `+{name}+`, where `name` is the attribute name. |
|||
// end::literal-mono[] |
|||
|
|||
// tag::literal-mono-with-plus[] |
|||
`pass:[++]` is the increment operator in C. |
|||
// end::literal-mono-with-plus[] |
|||
|
|||
// tag::b-mono-code[] |
|||
Reference code like `types` or `methods` inline. |
|||
|
|||
Do not pass arbitrary ``Object``s to methods that accept ``String``s! |
|||
// end::b-mono-code[] |
|||
|
|||
// tag::highlight[] |
|||
Werewolves are #allergic to cinnamon#. |
|||
// end::highlight[] |
|||
|
|||
// tag::highlight-html[] |
|||
<mark>mark element</mark> |
|||
// end::highlight-html[] |
|||
|
|||
// tag::css-co[] |
|||
Do werewolves believe in [small]#small print#? // <1> |
|||
|
|||
[big]##O##nce upon an infinite loop. |
|||
// end::css-co[] |
|||
|
|||
// tag::css[] |
|||
Do werewolves believe in [small]#small print#? |
|||
|
|||
[big]##O##nce upon an infinite loop. |
|||
// end::css[] |
|||
|
|||
// tag::css-all[] |
|||
Werewolves are allergic to #cassia cinnamon#. |
|||
|
|||
Did the werewolves read the [.small]#small print#? |
|||
|
|||
Where did all the [.underline]#cores# run off to? |
|||
|
|||
We need [.line-through]#ten# make that twenty VMs. |
|||
|
|||
[.big]##O##nce upon an infinite loop. |
|||
// end::css-all[] |
|||
|
|||
// tag::css-custom[] |
|||
Type the word [.userinput]#asciidoctor# into the search bar. |
|||
// end::css-custom[] |
|||
|
|||
// tag::css-custom-html[] |
|||
<span class="userinput">asciidoctor</span> |
|||
// end::css-custom-html[] |
|||
|
|||
//// |
|||
phrase styled by CSS class .small# |
|||
//// |
|||
@ -0,0 +1,20 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
= AsciiDoc Writer's Guide |
|||
Doc Writer <doc.writer@asciidoctor.org> |
|||
v1.0, 2013-08-01 |
|||
:toc: |
|||
// end::base[] |
|||
|
|||
// tag::pos[] |
|||
= AsciiDoc Writer's Guide |
|||
Doc Writer <doc.writer@asciidoctor.org> |
|||
v1.0, 2014-08-01 |
|||
:toc: right |
|||
// end::pos[] |
|||
@ -0,0 +1,42 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: User Interface Macros |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::key[] |
|||
|=== |
|||
|Shortcut |Purpose |
|||
|
|||
|kbd:[F11] |
|||
|Toggle fullscreen |
|||
|
|||
|kbd:[Ctrl+T] |
|||
|Open a new tab |
|||
|
|||
|kbd:[Ctrl+Shift+N] |
|||
|New incognito window |
|||
|
|||
|kbd:[\ ] |
|||
|Used to escape characters |
|||
|
|||
|kbd:[Ctrl+\]] |
|||
|Jump to keyword |
|||
|
|||
|kbd:[Ctrl + +] |
|||
|Increase zoom |
|||
|=== |
|||
// end::key[] |
|||
|
|||
// tag::menu[] |
|||
To save the file, select menu:File[Save]. |
|||
|
|||
Select menu:View[Zoom > Reset] to reset the zoom level to the default setting. |
|||
// end::menu[] |
|||
|
|||
// tag::button[] |
|||
Press the btn:[OK] button when you are finished. |
|||
|
|||
Select a file in the file navigator and click btn:[Open]. |
|||
// end::button[] |
|||
@ -0,0 +1,205 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Unordered list |
|||
- user-manual: checklist |
|||
- quick-ref |
|||
- writers guide |
|||
//// |
|||
|
|||
// tag::base[] |
|||
* Edgar Allen Poe |
|||
* Sheri S. Tepper |
|||
* Bill Bryson |
|||
// end::base[] |
|||
|
|||
// tag::base-t[] |
|||
.Kizmet's Favorite Authors |
|||
* Edgar Allen Poe |
|||
* Sheri S. Tepper |
|||
* Bill Bryson |
|||
// end::base-t[] |
|||
|
|||
// tag::base-alt[] |
|||
- Edgar Allen Poe |
|||
- Sheri S. Tepper |
|||
- Bill Bryson |
|||
// end::base-alt[] |
|||
|
|||
// tag::divide[] |
|||
* Apples |
|||
* Oranges |
|||
|
|||
//- |
|||
|
|||
* Walnuts |
|||
* Almonds |
|||
// end::divide[] |
|||
|
|||
// tag::nest[] |
|||
.Possible DefOps manual locations |
|||
* West wood maze |
|||
** Maze heart |
|||
*** Reflection pool |
|||
** Secret exit |
|||
* Untracked file in git repository |
|||
// end::nest[] |
|||
|
|||
// tag::max[] |
|||
* level 1 |
|||
** level 2 |
|||
*** level 3 |
|||
**** level 4 |
|||
***** level 5 |
|||
* level 1 |
|||
// end::max[] |
|||
|
|||
// tag::square[] |
|||
[square] |
|||
* one |
|||
* two |
|||
* three |
|||
// end::square[] |
|||
|
|||
// tag::check[] |
|||
* [*] checked |
|||
* [x] also checked |
|||
* [ ] not checked |
|||
* normal list item |
|||
// end::check[] |
|||
|
|||
// tag::check-int[] |
|||
[%interactive] |
|||
* [*] checked |
|||
* [x] also checked |
|||
* [ ] not checked |
|||
* normal list item |
|||
// end::check-int[] |
|||
|
|||
// tag::check-icon[] |
|||
[%interactive] |
|||
* [*] checked |
|||
* [x] also checked |
|||
* [ ] not checked |
|||
* normal list item |
|||
// end::check-icon[] |
|||
|
|||
// tag::indent[] |
|||
* The header in AsciiDoc is optional, but if |
|||
it is used it must start with a document title. |
|||
|
|||
* 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. |
|||
// end::indent[] |
|||
|
|||
// tag::cont[] |
|||
* The header in AsciiDoc must start with a document title. |
|||
+ |
|||
The header is optional. |
|||
// end::cont[] |
|||
|
|||
// tag::complex[] |
|||
* The header in AsciiDoc must start with a document title. |
|||
+ |
|||
---- |
|||
= Document Title |
|||
---- |
|||
+ |
|||
Keep in mind that the header is optional. |
|||
|
|||
* Optional Author and Revision information immediately follows the header title. |
|||
+ |
|||
---- |
|||
= Document Title |
|||
Doc Writer <doc.writer@asciidoc.org> |
|||
v1.0, 2013-01-01 |
|||
---- |
|||
// end::complex[] |
|||
|
|||
// tag::complex-o[] |
|||
* The header in AsciiDoc must start with a document title. |
|||
+ |
|||
-- |
|||
Here's an example of a document title: |
|||
|
|||
---- |
|||
= Document Title |
|||
---- |
|||
|
|||
NOTE: The header is optional. |
|||
-- |
|||
// end::complex-o[] |
|||
|
|||
// tag::b-complex[] |
|||
* Every list item has at least one paragraph of content, |
|||
which may be wrapped, even using a hanging indent. |
|||
+ |
|||
Additional paragraphs or blocks are adjoined by putting |
|||
a list continuation on a line adjacent to both blocks. |
|||
+ |
|||
list continuation:: a plus sign (`{plus}`) on a line by itself |
|||
|
|||
* A literal paragraph does not require a list continuation. |
|||
|
|||
$ gem install asciidoctor |
|||
|
|||
* AsciiDoc lists may contain any complex content. |
|||
+ |
|||
[cols="2", options="header"] |
|||
|=== |
|||
|Application |
|||
|Language |
|||
|
|||
|AsciiDoc |
|||
|Python |
|||
|
|||
|Asciidoctor |
|||
|Ruby |
|||
|=== |
|||
// end::b-complex[] |
|||
|
|||
// tag::complex-parent[] |
|||
* parent list item |
|||
** child list item |
|||
|
|||
+ |
|||
paragraph attached to parent list item |
|||
// end::complex-parent[] |
|||
|
|||
// tag::complex-grandparent[] |
|||
* grandparent list item |
|||
** parent list item |
|||
*** child list item |
|||
|
|||
|
|||
+ |
|||
paragraph attached to grandparent list item |
|||
// end::complex-grandparent[] |
|||
|
|||
// tag::complex-enclosed[] |
|||
* grandparent list item |
|||
+ |
|||
-- |
|||
** parent list item |
|||
*** child list item |
|||
-- |
|||
+ |
|||
paragraph attached to grandparent list item |
|||
// end::complex-enclosed[] |
|||
|
|||
// tag::complex-only[] |
|||
. {blank} |
|||
+ |
|||
---- |
|||
print("one") |
|||
---- |
|||
. {blank} |
|||
+ |
|||
---- |
|||
print("one") |
|||
---- |
|||
// end::complex-only[] |
|||
@ -0,0 +1,96 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: URL |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
The homepage for the Asciidoctor Project is https://asciidoctor.org. |
|||
|
|||
Chat with other Fedora users in the irc://irc.freenode.org/#fedora[Fedora IRC channel]. |
|||
|
|||
Ask questions on the http://discuss.asciidoctor.org/[*mailing list*]. |
|||
// end::base[] |
|||
|
|||
// tag::base-co[] |
|||
The homepage for the Asciidoctor Project is https://asciidoctor.org. // <1> |
|||
// end::base-co[] |
|||
|
|||
// tag::irc[] |
|||
Chat with other Fedora users in the irc://irc.freenode.org/#fedora[Fedora IRC channel]. |
|||
// end::irc[] |
|||
|
|||
// tag::text[] |
|||
Ask questions on the http://discuss.asciidoctor.org/[*mailing list*]. |
|||
// end::text[] |
|||
|
|||
// tag::scheme[] |
|||
To see information about your browser, navigate to the link:about:[About Page]. |
|||
// end::scheme[] |
|||
|
|||
// tag::unconstrained[] |
|||
search/link:https://ecosia.org[Ecosia] |
|||
// end::unconstrained[] |
|||
|
|||
// tag::linkattrs-h[] |
|||
= Asciidoctor Document Title |
|||
|
|||
Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage,window=_blank]. |
|||
// end::linkattrs-h[] |
|||
|
|||
// tag::linkattrs[] |
|||
Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage,window=_blank]. |
|||
// end::linkattrs[] |
|||
|
|||
// tag::linkattrs-s[] |
|||
Let's view the raw HTML of the link:view-source:asciidoctor.org[Asciidoctor homepage^]. |
|||
// end::linkattrs-s[] |
|||
|
|||
// tag::css[] |
|||
Chat with other Asciidoctor users on the http://discuss.asciidoctor.org/[*mailing list*^,role=green]. |
|||
// end::css[] |
|||
|
|||
// tag::link[] |
|||
link:protocol.json[Open the JSON file] |
|||
// end::link[] |
|||
|
|||
// tag::hash[] |
|||
link:external.html#livereload[LiveReload] |
|||
// end::hash[] |
|||
|
|||
// tag::b-base[] |
|||
https://asciidoctor.org - automatic! |
|||
|
|||
https://asciidoctor.org[Asciidoctor] |
|||
|
|||
https://github.com/asciidoctor[Asciidoctor @ *GitHub*] |
|||
// end::b-base[] |
|||
|
|||
// tag::b-scheme[] |
|||
devel@discuss.arquillian.org |
|||
|
|||
mailto:devel@discuss.arquillian.org[Discuss Arquillian] |
|||
|
|||
mailto:devel-join@discuss.arquillian.org[Subscribe,Subscribe me,I want to join!] |
|||
|
|||
irc://irc.freenode.org/#fedora |
|||
// end::b-scheme[] |
|||
|
|||
// tag::b-linkattrs[] |
|||
http://discuss.asciidoctor.org[Discuss Asciidoctor,role=external,window=_blank] |
|||
|
|||
http://discuss.asciidoctor.org[Discuss Asciidoctor^] |
|||
|
|||
https://example.org["Google, Yahoo, Bing^",role=teal] |
|||
// end::b-linkattrs[] |
|||
|
|||
// tag::b-spaces[] |
|||
link:++https://example.org/?q=[a b]++[URL with special characters] |
|||
|
|||
link:https://example.org/?q=%5Ba%20b%5D[URL with special characters] |
|||
// end::b-spaces[] |
|||
|
|||
// tag::b-windows[] |
|||
link:\\server\share\whitepaper.pdf[Whitepaper] |
|||
// end::b-windows[] |
|||
@ -0,0 +1,24 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Quotes |
|||
//// |
|||
|
|||
// tag::para[] |
|||
[verse, Carl Sandburg, two lines from the poem Fog] |
|||
The fog comes |
|||
on little cat feet. |
|||
// end::para[] |
|||
|
|||
// tag::bl[] |
|||
[verse, Carl Sandburg, Fog] |
|||
____ |
|||
The fog comes |
|||
on little cat feet. |
|||
|
|||
It sits looking |
|||
over harbor and city |
|||
on silent haunches |
|||
and then moves on. |
|||
____ |
|||
// end::bl[] |
|||
@ -0,0 +1,27 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Video |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
video::video_file.mp4[] |
|||
// end::base[] |
|||
|
|||
// tag::attr[] |
|||
video::video_file.mp4[width=640, start=60, end=140, options=autoplay] |
|||
// end::attr[] |
|||
|
|||
// tag::caption[] |
|||
.A walkthrough of the product |
|||
video::video_file.mp4[] |
|||
// end::caption[] |
|||
|
|||
// tag::you[] |
|||
video::rPQoq7ThGAU[youtube] |
|||
// end::you[] |
|||
|
|||
// tag::vim[] |
|||
video::67480300[vimeo] |
|||
// end::vim[] |
|||
@ -0,0 +1,98 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: URL: Internal cross References |
|||
- quick-ref |
|||
//// |
|||
|
|||
// tag::base[] |
|||
The section <<images>> describes how to insert images into your document. |
|||
// end::base[] |
|||
|
|||
// tag::text[] |
|||
Learn how to <<link-macro-attributes,use attributes within the link macro>>. |
|||
// end::text[] |
|||
|
|||
// tag::xref-macro[] |
|||
Learn how to xref:link-macro-attributes[use attributes within the link macro]. |
|||
// end::xref-macro[] |
|||
|
|||
// tag::bad[] |
|||
Refer to link:document-b.html#section-b[Section B] for more information. |
|||
// end::bad[] |
|||
|
|||
// tag::base-inter-top[] |
|||
Refer to <<document-b.adoc#,Document B>> for more information. |
|||
// end::base-inter-top[] |
|||
|
|||
// tag::base-inter[] |
|||
Refer to <<document-b.adoc#section-b,Section B>> for more information. |
|||
// end::base-inter[] |
|||
|
|||
// tag::b-base[] |
|||
See <<paragraphs>> to learn how to write paragraphs. |
|||
|
|||
Learn how to organize the document into <<section-titles,sections>>. |
|||
// end::b-base[] |
|||
|
|||
// tag::b-inter[] |
|||
Refer to <<document-b.adoc#section-b,Section B>> for more information. |
|||
|
|||
See you when you get back from <<document-b#section-b,Section B>>! |
|||
// end::b-inter[] |
|||
|
|||
// tag::block-id-brackets[] |
|||
[[notice]] |
|||
This paragraph gets a lot of attention. |
|||
// end::block-id-brackets[] |
|||
|
|||
// tag::block-id-shorthand[] |
|||
[#notice] |
|||
This paragraph gets a lot of attention. |
|||
// end::block-id-shorthand[] |
|||
|
|||
// tag::anchor[] |
|||
// tag::anchor-brackets[] |
|||
[[bookmark-a]]Inline anchors make arbitrary content referenceable. |
|||
// end::anchor-brackets[] |
|||
|
|||
// tag::anchor-shorthand[] |
|||
[#bookmark-b]#Inline anchors can be applied to a phrase like this one.# |
|||
// end::anchor-shorthand[] |
|||
|
|||
anchor:bookmark-c[]Use a cross reference to link to this location. |
|||
|
|||
[[bookmark-d,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link. |
|||
// end::anchor[] |
|||
|
|||
// tag::anchor-wrong[] |
|||
[[anchor-point]]* list item text |
|||
// end::anchor-wrong[] |
|||
|
|||
// tag::anchor-list[] |
|||
* Fist item |
|||
* [[step2]]Second item |
|||
* Third item |
|||
// end::anchor-list[] |
|||
|
|||
// tag::anchor-header[] |
|||
=== Version 4.9 [[version-4_9]] |
|||
// end::anchor-header[] |
|||
|
|||
// tag::anchor-header-extra[] |
|||
=== [[current]]Version 4.9 [[version-4_9]] |
|||
// end::anchor-header-extra[] |
|||
|
|||
// tag::anchor-xreflabel[] |
|||
[[tiger-image,Image of a tiger]] |
|||
.This image represents a Bengal tiger also called the Indian tiger |
|||
image::tiger.png[] |
|||
// end::anchor-xreflabel[] |
|||
|
|||
// tag::anchor-macro[] |
|||
anchor:tiger-image[Image of a tiger] |
|||
// end::anchor-macro[] |
|||
|
|||
// tag::xref-title[] |
|||
Refer to <<Internal Cross References>>. |
|||
// end::xref-title[] |
|||
@ -0,0 +1,16 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: example |
|||
//// |
|||
|
|||
.Example syntax |
|||
[source] |
|||
---- |
|||
include::ex-example.adoc[tag=base] |
|||
---- |
|||
|
|||
.Result: Example block |
|||
-- |
|||
include::ex-example.adoc[tag=base] |
|||
-- |
|||
@ -0,0 +1,59 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Extensions: Compound Block Processor Example |
|||
//// |
|||
|
|||
Purpose:: |
|||
Register a custom block named `collapsiblelisting` that transforms a listing block into a compound block composed of the following: |
|||
|
|||
* an example block with the collapsible option enabled |
|||
* the original listing block |
|||
* the listing block is promoted to a source block if a language is specified using the second positional attribute. |
|||
|
|||
.sample-with-collapsiblelisting-block.adoc |
|||
[source] |
|||
.... |
|||
.Show JSON |
|||
[collapsiblelisting,json] |
|||
---- |
|||
{ |
|||
"foo": "bar" |
|||
} |
|||
---- |
|||
.... |
|||
|
|||
.CollapsibleListingBlock |
|||
[source,ruby] |
|||
---- |
|||
class CollapsibleListingBlock < Asciidoctor::Extensions::BlockProcessor |
|||
enable_dsl |
|||
on_context :listing |
|||
positional_attributes 'language' |
|||
|
|||
def process parent, reader, attrs |
|||
lang = attrs.delete 'language' |
|||
attrs['title'] ||= 'Show Listing' |
|||
example = create_example_block parent, [], attrs, content_model: :compound |
|||
example.set_option 'collapsible' |
|||
listing = create_listing_block example, reader.readlines, nil |
|||
if lang |
|||
listing.style = 'source' |
|||
listing.set_attr 'language', lang |
|||
listing.commit_subs |
|||
end |
|||
example << listing |
|||
example |
|||
end |
|||
end |
|||
|
|||
Asciidoctor::Extensions.register do |
|||
block CollapsibleListingBlock, :collapsiblelisting |
|||
end |
|||
---- |
|||
|
|||
.Usage |
|||
$ asciidoctor -r ./collapsiblelisting.rb sample-with-collapsiblelisting-block.adoc |
|||
|
|||
NOTE: This extension mimics the builtin `collapsible` option on the example block, but consolidates it to a single block. |
|||
The purpose of this extension is to show how to assemble a compound block in an extenesion. |
|||
@ -0,0 +1,48 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Extensions: Block processor example |
|||
//// |
|||
|
|||
Purpose:: |
|||
Register a custom block style named `shout` that uppercases all the words and converts periods to exclamation points. |
|||
|
|||
.sample-with-shout-block.adoc |
|||
|
|||
``` |
|||
[shout] |
|||
The time is now. Get a move on. |
|||
``` |
|||
|
|||
.ShoutBlock |
|||
|
|||
```ruby |
|||
require 'asciidoctor' |
|||
require 'asciidoctor/extensions' |
|||
|
|||
class ShoutBlock < Asciidoctor::Extensions::BlockProcessor |
|||
PeriodRx = /\.(?= |$)/ |
|||
|
|||
use_dsl |
|||
|
|||
named :shout |
|||
on_context :paragraph |
|||
name_positional_attributes 'vol' |
|||
parse_content_as :simple |
|||
|
|||
def process parent, reader, attrs |
|||
volume = ((attrs.delete 'vol') || 1).to_i |
|||
create_paragraph parent, (reader.lines.map {|l| l.upcase.gsub PeriodRx, '!' * volume }), attrs |
|||
end |
|||
end |
|||
``` |
|||
|
|||
.Usage |
|||
|
|||
```ruby |
|||
Asciidoctor::Extensions.register do |
|||
block ShoutBlock |
|||
end |
|||
|
|||
Asciidoctor.convert_file 'sample-with-shout-block.adoc', :safe => :safe |
|||
``` |
|||
@ -0,0 +1,39 @@ |
|||
//// |
|||
Included in: |
|||
|
|||
- user-manual: Extensions: Docinfo Processor example |
|||
//// |
|||
|
|||
Purpose:: |
|||
Appends the Google Analytics tracking code to the bottom of an HTML document. |
|||
|
|||
.GoogleAnalyticsDocinfoProcessor |
|||
|
|||
```ruby |
|||
class GoogleAnalyticsDocinfoProcessor < Asciidoctor::Extensions::DocinfoProcessor |
|||
use_dsl |
|||
at_location :footer |
|||
def process document |
|||
return unless (ga_account_id = document.attr 'google-analytics-account') |
|||
%(<script> |
|||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
|||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
|||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
|||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); |
|||
ga('create','#{ga_account_id}','auto'); |
|||
ga('send','pageview'); |
|||
</script>) |
|||
end |
|||
end |
|||
``` |
|||
|
|||
.Usage |
|||
|
|||
```ruby |
|||
Asciidoctor::Extensions.register do |
|||
docinfo_processor GoogleAnalyticsDocinfoProcessor |
|||
end |
|||
|
|||
Asciidoctor.convert_file 'sample.adoc', :safe => :safe, |
|||
:attributes => 'UA-ABCXYZ123' |
|||
``` |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue