You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/24 09:53:07 UTC
[14/17] isis-site git commit: ISIS-1521: documentation patches
http://git-wip-us.apache.org/repos/asf/isis-site/blob/b7de7baf/content/guides/dg.html
----------------------------------------------------------------------
diff --git a/content/guides/dg.html b/content/guides/dg.html
index b42621d..ba37b71 100644
--- a/content/guides/dg.html
+++ b/content/guides/dg.html
@@ -485,7 +485,7 @@ table.CodeRay td.code>pre{padding:0}
<li> <p><a href="ugfun.html">Fundamentals</a></p> </li>
<li> <p><a href="ugvw.html">Wicket viewer</a></p> </li>
<li> <p><a href="ugvro.html">Restful Objects viewer</a></p> </li>
- <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="ugodn.html">DataNucleus object store</a></p> </li>
<li> <p><a href="ugsec.html">Security</a></p> </li>
<li> <p><a href="ugtst.html">Testing</a></p> </li>
<li> <p><a href="ugbtb.html">Beyond the Basics</a></p> </li>
@@ -2263,32 +2263,18 @@ bundle install</code></pre>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">sh monitor.sh</code></pre>
+ <pre class="CodeRay highlight"><code data-lang="bash">sh preview-html.sh</code></pre>
</div>
</div>
<div class="paragraph">
- <p>This script simply runs <code>mvn clean compile && ruby monitor.rb -b</code>. The <code>mvn</code> command performs a clean rebuild of the site, and then the ruby script monitors for any further changes under <code>src/main/asciidoc</code>.</p>
+ <p>This script just runs <code>mvn compile</code> for HTML files only, then calls <code>python</code> to start the web browser and run a simple web server (on port 8000).</p>
</div>
<div class="paragraph">
- <p>The script also starts up a web server on port 4000 so you can review results. If any <code>.adoc</code> changes, then the appropriate HTML will be regenerated. And, if any new assets (CSS, images etc) are added, they will be copied across. The <code>-b</code> flag passed through means that the script also starts a web browser pointing at the newly generated docs.</p>
- </div>
- <div class="paragraph">
- <p>The <code>monitor.rb</code> script has a couple of other options, use <code>-h</code> flag for usage:</p>
- </div>
- <div class="listingblock">
- <div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">ruby monitor.rb -h</code></pre>
- </div>
- </div>
- <div class="paragraph">
- <p>which should print:</p>
+ <p>If you want to double-check the PDFs also, then use:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code>usage: monitor.rb [options]
- -p, --port port (default: 4000)
- -b, --browser launch browser
- -h, --help help</code></pre>
+ <pre class="CodeRay highlight"><code data-lang="bash">sh preview-pdf.sh</code></pre>
</div>
</div>
</div>
@@ -2817,180 +2803,1655 @@ git commit -m "ISIS-nnn: yada yada"</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_if_you_ve_accidentally_worked_on_code_master_code_branch">6.10. If you\u2019ve accidentally worked on <code>master</code> branch</h3>
+ <h3 id="_if_you_ve_accidentally_worked_on_code_master_code_branch">6.10. If you\u2019ve accidentally worked on <code>master</code> branch</h3>
+ <div class="paragraph">
+ <p>If at any time the <code>git pull</code> from your upstream fails, it most likely means that you must have made commits on the <code>master</code> branch. You can use <code>gitk --all</code> to confirm; at some point in time both <code>master</code> and <code>origin\master</code> will have a common ancestor.</p>
+ </div>
+ <div class="paragraph">
+ <p>You can retrospectively create a topic branch for the work you\u2019ve accidentally done on <code>master</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>First, create a branch for your current commit:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">git branch <i>newbranch</i></code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">git stash</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Finally, locate the shaId of the commit you want to roll back to (easily obtained in <code>gitk -all</code>), and wind <code>master</code> branch back to that commit:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">git checkout master
+git reset --hard <i>shaId</i> # move master branch shaId of common ancestor</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_if_you_ve_forgotten_to_prefix_your_commits_but_not_pushed">6.11. If you\u2019ve forgotten to prefix your commits (but not pushed)</h3>
+ <div class="paragraph">
+ <p>One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow. Using one of these, <code>git prefix</code>, you can just commit with proper message without bothering about prefix and add prefix only in the end <strong>before</strong> the final push.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, to prefix all not yet prefixed commits <code>master..isis/666</code> with <code>ISIS-666</code> prefix, use:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">git prefix ISIS-666 master..isis/666</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>You can grab this utility, and others, from <a href="https://github.com/themalkolm/git-boots">this repo</a>.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_dg_working-with-many-repos">7. Appendix: Working with Many Repos</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_dg_working-with-many-repos.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>Applications built with Apache Isis often (should) consist of multiple modules, each in separate git repositories. For example, there are the various (non-ASF) <a href="http://isisaddons.org">Isis Addons</a> that provide various cross-cutting concerns/technical services (security, mail-merge etc), as well the modules eg as provided by the (non-ASF) <a href="http://catalog.incode.org">Incode Catalog</a>, which provides generic business subdomains (communication channels, documents etc).</p>
+ </div>
+ <div class="paragraph">
+ <p>In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the <a href="ugbtb.html#_ugbtb_decoupling_event-bus">event bus</a> and <a href="ugbtb.html#_ugbtb_decoupling_mixins">mixins</a> so that these modules are decoupled from each other.</p>
+ </div>
+ <div class="paragraph">
+ <p>All of which is a preamble to say that you will likely have multiple directories on your local development computer, for each such git repository that you contribute to.</p>
+ </div>
+ <div class="paragraph">
+ <p>In this appendix we provide some simple but useful bash scripts to help you manage each such.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_prerequisites">7.1. Prerequisites</h3>
+ <div class="paragraph">
+ <p>We recommend that you adopt a convention for your directories. For example, open source repositories (such as the Isis Addons and Incode Catalog mentioned above) reside in <a href="https://github.com/">github.com</a>, while your own proprietary code might reside in some other service, eg <a href="https://bitbucket.org/">bitbucket</a>. For example:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>/users/home/me/
+ BITBUCKET/
+ mycompany/
+ myapp-moduleA
+ myapp-moduleB
+ myapp
+ GITHUB/
+ isisaddons/
+ isis-module-docx
+ isis-module-security
+ incodehq/
+ incode-module-commchannel
+ incode-module-classification</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="__code_repos_txt_code">7.2. <code>_repos.txt</code></h3>
+ <div class="paragraph">
+ <p>Create a file <code>_repos.txt</code> that catalogues the repositories, eg:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>#
+# our code
+#
+/users/home/me/BITBUCKET/mycompany/myapp-moduleA
+/users/home/me/BITBUCKET/mycompany/myapp-moduleB
+/users/home/me/BITBUCKET/mycompany/myapp
+#
+# open source modules
+#
+/users/home/me/GITHUB/isisaddons/isis-module-docx
+/users/home/me/GITHUB/isisaddons/isis-module-security
+/users/home/me/GITHUB/incodehq/incode-module-commchannel
+/users/home/me/GITHUB/incodehq/incode-module-classification</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_bash_functions">7.3. Bash functions</h3>
+ <div class="paragraph">
+ <p>The <code>.bash_functions</code> file (downloadable from this <a href="https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c91cb">gist</a>) provides the following two functions:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>repo</code><br></p>
+ <div class="paragraph">
+ <p>Switches (using <code>pushd</code>) to the specified directory (as listed in the <code>_repos.txt</code> file).</p>
+ </div> </li>
+ <li> <p><code>foreach</code><br></p>
+ <div class="paragraph">
+ <p>Runs the specified command for all (or matching) repositories (as listed in <code>_repos.txt</code> file).</p>
+ </div> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>For example,</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">repo doc</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>would switch to <code>/users/home/me/GITHUB/isisaddons/isis-module-docx</code>, the first module that matches the fragment.</p>
+ </div>
+ <div class="paragraph">
+ <p>Meanwhile:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">foreach git status</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>would perform a <code>git status</code> on every git repository, while</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">foreach -g isisaddons git fetch</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>would perform a <code>git fetch</code> but only to those repositories which match "isisaddons" (<code>-g</code> flag standing for <code>grep</code>).</p>
+ </div>
+ <div class="paragraph">
+ <p>To load the functions into your profile (<code>.bashrc</code> or <code>.profile</code> or similar), use:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="bash">. ~/.bash_functions</code></pre>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_dg_asciidoc-syntax">8. Appendix: Asciidoc Syntax</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-syntax.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>This appendix describes the main syntax conventions when writing Asciidoctor/Asciidoc.</p>
+ </div>
+ <div class="paragraph">
+ <p>For more info, see:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="_resources/asciidoc-syntax-quick-reference.pdf">asciidoc-syntax-quick-reference.pdf</a></p> </li>
+ <li> <p><a href="_resources/asciidoc-writers-guide.pdf">asciidoc-writers-guide.pdf</a></p> </li>
+ <li> <p><a href="https://powerman.name/doc/asciidoc">online cheat sheet</a></p> </li>
+ <li> <p><a href="http://asciidoctor.org/docs/user-manual/">asciidoctor online user manual</a></p> </li>
+ <li> <p><a href="http://www.methods.co.nz/asciidoc/userguide.html">asciidoc online user manual</a></p> </li>
+ </ul>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_headings">8.1. Headings</h3>
+ <div class="paragraph">
+ <p>The number of preceding <code>=</code> signs indicates the heading level.</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 60%;">
+ <col style="width: 40%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Syntax</th>
+ <th class="tableblock halign-left valign-top">Meaning</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>= Level 1</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>There can only be one level 1 per .adoc (at the very top).</p>
+ </div>
+ <div class="paragraph">
+ <p>The paragraph immediately following the heading is the "preamble", and is rendered in a larger font. It\u2019s therefore a good place to summarize the content of the document.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>== Level 2</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Level 2</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>=== Level 3</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Level 3</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>==== Level 4</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Level 4</p>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_paragraphs">8.2. Paragraphs</h3>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 60%;">
+ <col style="width: 40%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Syntax</th>
+ <th class="tableblock halign-left valign-top">Example</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>Paragraphs are separated by one or more blank lines.
+
+So, this is a separate paragraph.</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Paragraphs are separated by one or more blank lines.</p>
+ </div>
+ <div class="paragraph">
+ <p>So, this is a separate paragraph.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>All consecutive sentences are rendered in the same paragraph.
+This is another sentence in the para.
+And another one.
+Yet another.</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Sentences without a blank line are in the same paragraph. Don\u2019t worry about word wrapping, just start the next sentence on the next line.</p>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>In general, there\u2019s no need to indent paragraphs; keep things left-aligned. Let the markup specify the logical indentation.</p>
+ </div>
+ <div class="sidebarblock">
+ <div class="content">
+ <div class="title">
+ Start each sentence on a new line
+ </div>
+ <div class="paragraph">
+ <p>Don\u2019t worry about wrapping sentences at 80 characters, just start each new sentence on a new line. Asciidoc will take care of the rendering.</p>
+ </div>
+ <div class="paragraph">
+ <p>This simple tip has a number of other benefits:</p>
+ </div>
+ <div class="olist arabic">
+ <ol class="arabic">
+ <li> <p>when the document is edited (eg correct a typo or insert a missing word), then only a single line in the file is changed.<br></p>
+ <div class="paragraph">
+ <p>This will reduce change of merge conflicts, too.</p>
+ </div> </li>
+ <li> <p>You can easily see if a sentence is too long, and should be split</p> </li>
+ <li> <p>You can easily see if all sentences are the same length: good writing should vary the length of sentences</p> </li>
+ <li> <p>You can easily see if successive sentences start with the same phrase (that might be a good thing, or a bad thing, depending).</p> </li>
+ </ol>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_bulleted-lists">8.3. Bulleted lists</h3>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 60%;">
+ <col style="width: 40%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Syntax</th>
+ <th class="tableblock halign-left valign-top">Example</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>The blank line after this para is required:
+
+* Bullet 1 +
++
+Indented paragraph (note the '+' to to chain this para with the bullet)
+
+* Bullet 2
+
+** Child bullets +
++
+More indenting
+
+** Another child bullet
+
+* Bullet 3</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>The blank line after this para is required:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>Bullet 1<br></p>
+ <div class="paragraph">
+ <p>Indented paragraph (note the '+' to chain this para with the bullet)</p>
+ </div> </li>
+ <li> <p>Bullet 2</p>
+ <div class="ulist">
+ <ul>
+ <li> <p>Child bullets<br></p>
+ <div class="paragraph">
+ <p>More indenting</p>
+ </div> </li>
+ <li> <p>Another child bullet</p> </li>
+ </ul>
+ </div> </li>
+ <li> <p>Bullet 3</p> </li>
+ </ul>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_numbered-lists">8.4. Numbered lists</h3>
+ <div class="paragraph">
+ <p>There\u2019s no need to keep track of numbers, just use '1' or 'a' etc:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 60%;">
+ <col style="width: 40%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Syntax</th>
+ <th class="tableblock halign-left valign-top">Example</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>The blank line after this para is required:
+
+1. Bullet 1 +
++
+Indented paragraph
+
+2. Bullet 2
+
+a. Child bullets +
++
+More indenting
+
+b. Another child bullet
+
+3. Bullet 3</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>The blank line after this para is required:</p>
+ </div>
+ <div class="olist arabic">
+ <ol class="arabic">
+ <li> <p>Bullet 1<br></p>
+ <div class="paragraph">
+ <p>Indented paragraph</p>
+ </div> </li>
+ <li> <p>Bullet 2</p>
+ <div class="olist loweralpha">
+ <ol class="loweralpha" type="a">
+ <li> <p>Child bullets<br></p>
+ <div class="paragraph">
+ <p>More indenting</p>
+ </div> </li>
+ <li> <p>Another child bullet</p> </li>
+ </ol>
+ </div> </li>
+ <li> <p>Bullet 3</p> </li>
+ </ol>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>While it isn\u2019t necessary to maintain the ordering manually (could just use '1' for all bullets), this does generate warnings when the document is built.</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_links-and-xrefs">8.5. Links and Cross-references</h3>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 37.5%;">
+ <col style="width: 25%;">
+ <col style="width: 37.5%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Syntax</th>
+ <th class="tableblock halign-left valign-top">Example</th>
+ <th class="tableblock halign-left valign-top">Purpose</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>link:http://ciserver:8080[CI Server]</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><a href="http://ciserver:8080">CI Server</a></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Link to an external hyperlink</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>link:http://ciserver:8080[CI Server^]</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><a href="http://ciserver:8080" target="_blank">CI Server</a></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Link to an external hyperlink, with <code>target=blank</code></p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>xref:_markup-docs_background[background]</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><a href="#_markup-docs_background">background</a></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Cross-reference to section in same asciidoc document</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>xref:../../setting-up/concepts/concepts.adoc#[concepts]</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><a href="../../setting-up/concepts/concepts.html">concepts</a></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Cross-reference to top-level of different asciidoc document</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>xref:../../setting-up/concepts/concepts.adoc#_concepts_ci-as-a-service[CI as a service]</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><a href="../../setting-up/concepts/concepts.html#_concepts_ci-as-a-service">CI as a service</a></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Cross-reference to section within different asciidoc document</p>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_tables">8.6. Tables</h3>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Some table
+[cols="3a,2a", options="header"]
+|===
+
+| Header col 1
+| Header col 2
+
+| Row 1 col 1
+| Row 1 col 2
+
+| Row 2 col 1
+| Row 2 col 2
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 1. Some table
+ </caption>
+ <colgroup>
+ <col style="width: 60%;">
+ <col style="width: 40%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Header col 1</th>
+ <th class="tableblock halign-left valign-top">Header col 2</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Row 1 col 1</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Row 1 col 2</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Row 2 col 1</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Row 2 col 2</p>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>where:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>the <code>cols</code> attribute says how many columns there are and their respective widths.</p> </li>
+ <li> <p>the "a" suffix indicates that the contents is parsed as Asciidoc</p> </li>
+ </ul>
+ </div>
+ <div class="sect3">
+ <h4 id="_column_attributes">8.6.1. Column Attributes</h4>
+ <div class="paragraph">
+ <p>Other options are (<a href="http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-styling-columns-and.html">credit</a>):</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>e: emphasized</p> </li>
+ <li> <p>a: Asciidoc markup</p> </li>
+ <li> <p>m: monospace</p> </li>
+ <li> <p>h: header style, all column values are styled as header</p> </li>
+ <li> <p>s: strong</p> </li>
+ <li> <p>l: literal, text is shown in monospace font and line breaks are kept</p> </li>
+ <li> <p>d: default</p> </li>
+ <li> <p>v: verse, keeps line breaks</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Table with column style e,a,m
+[cols="e,a,m"]
+|===
+| Emphasized (e) | Asciidoc (a) | Monospaced (m)
+
+| Asciidoctor
+| NOTE: *Awesome* way to write documentation
+| It is just code
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 2. Table with column style e,a,m
+ </caption>
+ <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">Emphasized (e)</th>
+ <th class="tableblock halign-left valign-top">Asciidoc (a)</th>
+ <th class="tableblock halign-left valign-top">Monospaced (m)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><em>Asciidoctor</em></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content"> <strong>Awesome</strong> way to write documentation </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>It is just code</code></p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>and:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Table with column style h,s,l
+[cols="h,s,l"]
+|===
+| Header (h) | Strong (s) | Literal (l)
+
+| Asciidoctor
+| Awesome way to write documentation
+| It is
+just code
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 3. Table with column style h,s,l
+ </caption>
+ <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">Header (h)</th>
+ <th class="tableblock halign-left valign-top">Strong (s)</th>
+ <th class="tableblock halign-left valign-top">Literal (l)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <th class="tableblock halign-left valign-top"><p class="tableblock">Asciidoctor</p></th>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Awesome way to write documentation</strong></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div class="literal">
+ <pre>It is
+just code</pre>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>and:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Table with column style d,v
+[cols="d,v"]
+|===
+| Default (d) | Verse (v)
+
+| Asciidoctor
+| Awesome way
+to write
+documentation
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 4. Table with column style d,v
+ </caption>
+ <colgroup>
+ <col style="width: 50%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Default (d)</th>
+ <th class="tableblock halign-left valign-top">Verse (v)</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Asciidoctor</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div class="verse">
+ Awesome way to write documentation
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect3">
+ <h4 id="_column_alignment">8.6.2. Column Alignment</h4>
+ <div class="paragraph">
+ <p>This can be combined with alignment markers (<a href="http://mrhaki.blogspot.co.uk/2014/11/awesome-asciidoctor-table-column-and.html">credit</a>):</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><: top align values (default)</p> </li>
+ <li> <p>>: bottom align values</p> </li>
+ <li> <p>^: center values</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[cols="^.>,<.<,>.^", options="header"]
+|===
+
+| Name
+| Description
+| Version
+
+| Asciidoctor
+| Awesome way to write documentation
+| 1.5.0
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3334%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-center valign-bottom">Name</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ <th class="tableblock halign-right valign-middle">Version</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-center valign-bottom"><p class="tableblock">Asciidoctor</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Awesome way to write documentation</p></td>
+ <td class="tableblock halign-right valign-middle"><p class="tableblock">1.5.0</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>where:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>the first column is centered and bottom aligned,</p> </li>
+ <li> <p>the second column is left and top aligned and</p> </li>
+ <li> <p>the third column is right aligned and centered vertically.</p> </li>
+ </ul>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_column_row_spanning">8.6.3. Column/Row Spanning</h4>
+ <div class="paragraph">
+ <p>We can also have columns or rows spanning multiple cells (<a href="http://mrhaki.blogspot.co.uk/2014/12/awesome-asciidoctor-span-cell-over-rows.html">credit</a>):</p>
+ </div>
+ <div class="paragraph">
+ <p>For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Cell spans columns
+|===
+| Name | Description
+
+| Asciidoctor
+| Awesome way to write documentation
+
+2+| The statements above say it all
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 5. Cell spans columns
+ </caption>
+ <colgroup>
+ <col style="width: 50%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Asciidoctor</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Awesome way to write documentation</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock">The statements above say it all</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>The <code>N+</code> sign notation tells Asciidoctor to span this cell over N columns.</p>
+ </div>
+ <div class="paragraph">
+ <p>while:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Cell spans rows
+|===
+| Name | Description
+
+.2+| Asciidoctor
+| Awesome way to write documentation
+
+| Works on the JVM
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 6. Cell spans rows
+ </caption>
+ <colgroup>
+ <col style="width: 50%;">
+ <col style="width: 50%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Name</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top" rowspan="2"><p class="tableblock">Asciidoctor</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Awesome way to write documentation</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Works on the JVM</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>The <code>.N+</code> notation tells Asciidoctor to span this cell over N rows.</p>
+ </div>
+ <div class="paragraph">
+ <p>and:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>.Cell spans both rows and columns
+|===
+
+| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3
+
+2.2+| Cell spans 2 cols, 2 rows
+| Row 2, Col 3
+| Row 3, Col 3
+
+|===</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 7. Cell spans both rows and columns
+ </caption>
+ <colgroup>
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3334%;">
+ </colgroup>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Row 1, Col 1</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Row 1, Col 2</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Row 1, Col 3</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top" colspan="2" rowspan="2"><p class="tableblock">Cell spans 2 cols, 2 rows</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Row 2, Col 3</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Row 3, Col 3</p></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>The <code>N.M+</code> notation tells Asciidoctor to span this cell over N columns and M rows.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_admonitions">8.7. Admonitions</h3>
+ <div class="paragraph">
+ <p>Callout or highlight content of particular note.</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 60%;">
+ <col style="width: 40%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Syntax</th>
+ <th class="tableblock halign-left valign-top">Example</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>NOTE: the entire note must be a single sentence.</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content"> the entire note must be a single sentence. </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[NOTE]
+====
+the note is multiple paragraphs, and can have all the usual styling,
+* eg bullet points:
+* etc etc
+====</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>the note is multiple paragraphs, and can have all the usual styling,</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>eg bullet points:</p> </li>
+ <li> <p>etc etc</p> </li>
+ </ul>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[TIP]
+====
+Here's something worth knowing...
+====</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Here\u2019s something worth knowing\u2026\u200b</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[WARNING]
+====
+Be careful...
+====</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="admonitionblock warning">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Be careful\u2026\u200b</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[IMPORTANT]
+====
+Don't forget...
+====</pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="admonitionblock important">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Don\u2019t forget\u2026\u200b</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_source-code">8.8. Source code</h3>
+ <div class="paragraph">
+ <p>Use <code>[source]</code> macro to specify source content:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[source,powershell]
+----
+get-command -module BomiArtifact
+----</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will render as:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="powershell">get-command -module BomiArtifact</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Some languages support syntax highlighting. For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[source,java]
+----
+public class SomeClass extends SomeOtherClass {
+ ...
+}
+----</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will render as:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SomeClass</span> <span class="directive">extends</span> SomeOtherClass {
+ ...
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Callouts can also be added using an appropriate comment syntax. For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[source,java]
+----
+public class SomeClass
+ extends SomeOtherClass { // <1>
+ public static void main(String[] args) { // <2>
+ ...
+ }
+}
+----
+<1> inherits from `SomeOtherClass`
+<2> entry point into the program</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will render as:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">SomeClass</span>
+ <span class="directive">extends</span> SomeOtherClass { <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">void</span> main(<span class="predefined-type">String</span><span class="type">[]</span> args) { <i class="conum" data-value="2"></i><b>(2)</b>
+ ...
+ }
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>inherits from <code>SomeOtherClass</code></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>entry point into the program</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>and</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[source,xml]
+----
+<a>
+ <b c="foo"> <!--1-->
+</a>
+----
+<1> some comment</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><a></span>
+ <span class="tag"><b</span> <span class="attribute-name">c</span>=<span class="string"><span class="delimiter">"</span><span class="content">foo</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="tag"></a></span></code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>some comment</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>It\u2019s also possible to include source code snippets; see the guides linked previously</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_images">8.9. Images</h3>
+ <div class="paragraph">
+ <p>Use the <code>image:</code> macro to reference images. For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>image:_images/vscode.png[]</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will render as:</p>
+ </div>
+ <div class="paragraph">
+ <p><span class="image"><img src="_images/vscode.png" alt="vscode"></span></p>
+ </div>
+ <div class="paragraph">
+ <p>to make the image clickable, add in the <code>link</code> attribute:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>image:_images/vscode.png[link="_images/vscode.png"]</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will render as:</p>
+ </div>
+ <div class="paragraph">
+ <p><span class="image"><a class="image" href="_images/vscode.png"><img src="_images/vscode.png" alt="vscode"></a></span></p>
+ </div>
+ <div class="paragraph">
+ <p>to make the image clickable, add in the <code>link</code> attribute:</p>
+ </div>
+ <div class="paragraph">
+ <p>It\u2019s also possible to specify the width using <code>scaledwidth</code> (for PDF/HTML) or <code>width</code> and <code>height</code> (for HTML only).</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_child-documents">8.10. Child Documents</h3>
<div class="paragraph">
- <p>If at any time the <code>git pull</code> from your upstream fails, it most likely means that you must have made commits on the <code>master</code> branch. You can use <code>gitk --all</code> to confirm; at some point in time both <code>master</code> and <code>origin\master</code> will have a common ancestor.</p>
+ <p>Use the <code>include:</code> macro to break up a document into multiple sections.</p>
</div>
<div class="paragraph">
- <p>You can retrospectively create a topic branch for the work you\u2019ve accidentally done on <code>master</code>.</p>
+ <p>For example, the <a href="../../setting-up/concepts/concepts.html">concepts</a> document is broken into several files:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>concepts.adoc
+_concepts_why-a-new-platform.adoc
+_concepts_ci-as-a-service.adoc
+_concepts_git-intro.adoc</pre>
+ </div>
</div>
<div class="paragraph">
- <p>First, create a branch for your current commit:</p>
+ <p>and so on.</p>
+ </div>
+ <div class="paragraph">
+ <p>These are included using:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">git branch <i>newbranch</i></code></pre>
+ <pre class="CodeRay highlight"><code data-lang="asciidoc">include::_concepts_why-a-new-platform.adoc[leveloffset=+1]
+include::_concepts_ci-as-a-service.adoc[leveloffset=+1]
+include::_concepts_git-intro.adoc[leveloffset=+1]</code></pre>
</div>
</div>
<div class="paragraph">
- <p>Next, make sure you have no outstanding edits. If you do, you should commit them or stash them:</p>
+ <p>The <code>leveloffset=+1</code> means that each included file\u2019s heading levels are automatically adjusted. The net effect is that all documents can and should use heading 1 as their top-level.</p>
+ </div>
+ <div class="paragraph">
+ <p>Child documents should have '_' as prefix. This ensures that they are ignored by the build; only .html and PDF files are created for the top-level parent documents.</p>
+ </div>
+ <div class="paragraph">
+ <p>The CI/documentation platform also supports the "Improve this doc" button, allowing any document to be edited via the TFS portal; very useful for small fixes. To make this work, it relies upon the following naming conventions:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>every document should have an id anchor for its level heading corresponding to its file name</p> </li>
+ <li> <p>every child document\u2019s name should be an '_ followed by the name of its parent.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>For example, <code>concepts.adoc</code> is:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">git stash</code></pre>
+ <pre class="CodeRay highlight"><code data-lang="asciidoc">[[concepts]]
+= Concepts
+...</code></pre>
</div>
</div>
<div class="paragraph">
- <p>Finally, locate the shaId of the commit you want to roll back to (easily obtained in <code>gitk -all</code>), and wind <code>master</code> branch back to that commit:</p>
+ <p>while its child document <code>_concepts_why-a-new-platform.adoc</code> starts with:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">git checkout master
-git reset --hard <i>shaId</i> # move master branch shaId of common ancestor</code></pre>
+ <pre class="CodeRay highlight"><code data-lang="asciidoc">[[_concepts_why-a-new-platform]]
+= Why a new platform?
+...</code></pre>
</div>
</div>
- </div>
- <div class="sect2">
- <h3 id="_if_you_ve_forgotten_to_prefix_your_commits_but_not_pushed">6.11. If you\u2019ve forgotten to prefix your commits (but not pushed)</h3>
- <div class="paragraph">
- <p>One of our committers, Alexander Krasnukhin, has put together some git scripts to help his workflow. Using one of these, <code>git prefix</code>, you can just commit with proper message without bothering about prefix and add prefix only in the end <strong>before</strong> the final push.</p>
- </div>
<div class="paragraph">
- <p>For example, to prefix all not yet prefixed commits <code>master..isis/666</code> with <code>ISIS-666</code> prefix, use:</p>
+ <p>In general, we use '_' to separate out the logical hierarchy:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">git prefix ISIS-666 master..isis/666</code></pre>
+ <pre class="CodeRay highlight"><code>xxx-xxx/xxx-xxx.adoc
+ _xxx-xxx_ppp-ppp.adoc
+ _xxx-xxx_qqq-qqq.adoc
+ _xxx-xxx_qqq-qqq_mmm-mmm.adoc
+ _xxx-xxx_qqq-qqq_nnn-nnn.adoc</code></pre>
</div>
</div>
<div class="paragraph">
- <p>You can grab this utility, and others, from <a href="https://github.com/themalkolm/git-boots">this repo</a>.</p>
- </div>
- </div>
- </div>
- </div>
- <div class="sect1">
- <h2 id="_dg_working-with-many-repos">7. Appendix: Working with Many Repos</h2>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_dg_working-with-many-repos.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <div class="sectionbody">
- <div class="paragraph">
- <p>Applications built with Apache Isis often (should) consist of multiple modules, each in separate git repositories. For example, there are the various (non-ASF) <a href="http://isisaddons.org">Isis Addons</a> that provide various cross-cutting concerns/technical services (security, mail-merge etc), as well the modules eg as provided by the (non-ASF) <a href="http://catalog.incode.org">Incode Catalog</a>, which provides generic business subdomains (communication channels, documents etc).</p>
- </div>
- <div class="paragraph">
- <p>In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the <a href="ugbtb.html#_ugbtb_decoupling_event-bus">event bus</a> and <a href="ugbtb.html#_ugbtb_decoupling_mixins">mixins</a> so that these modules are decoupled from each other.</p>
- </div>
- <div class="paragraph">
- <p>All of which is a preamble to say that you will likely have multiple directories on your local development computer, for each such git repository that you contribute to.</p>
- </div>
- <div class="paragraph">
- <p>In this appendix we provide some simple but useful bash scripts to help you manage each such.</p>
- </div>
- <div class="sect2">
- <h3 id="_prerequisites">7.1. Prerequisites</h3>
- <div class="paragraph">
- <p>We recommend that you adopt a convention for your directories. For example, open source repositories (such as the Isis Addons and Incode Catalog mentioned above) reside in <a href="https://github.com/">github.com</a>, while your own proprietary code might reside in some other service, eg <a href="https://bitbucket.org/">bitbucket</a>. For example:</p>
+ <p>Any referenced images should be in subdirectories of the <code>_images</code> directory:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code>/users/home/me/
- BITBUCKET/
- mycompany/
- myapp-moduleA
- myapp-moduleB
- myapp
- GITHUB/
- isisaddons/
- isis-module-docx
- isis-module-security
- incodehq/
- incode-module-commchannel
- incode-module-classification</code></pre>
+ <pre class="CodeRay highlight"><code>xxx-xxx/_images/.
+ /ppp-ppp/.
+ /qqq-qqq/.
+ /mmm-mmm
+ /nnn-nnn</code></pre>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="__code_repos_txt_code">7.2. <code>_repos.txt</code></h3>
+ <h3 id="__markup-docs_asciidoc_metadata">8.11. Metadata</h3>
<div class="paragraph">
- <p>Create a file <code>_repos.txt</code> that catalogues the repositories, eg:</p>
+ <p>The top-level document must include the <code>_basedir</code> attribute; this points to the parent directory <code>src/main/asciidoc</code>. This attribute is set immediately after the top-level heading.</p>
+ </div>
+ <div class="paragraph">
+ <p>In addition, the <code>:toc:</code> adds a table of contents.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, the <code>setting-up/concepts/concepts.adoc</code> file starts:</p>
</div>
<div class="listingblock">
<div class="content">
- <pre class="CodeRay highlight"><code>#
-# our code
-#
-/users/home/me/BITBUCKET/mycompany/myapp-moduleA
-/users/home/me/BITBUCKET/mycompany/myapp-moduleB
-/users/home/me/BITBUCKET/mycompany/myapp
-#
-# open source modules
-#
-/users/home/me/GITHUB/isisaddons/isis-module-docx
-/users/home/me/GITHUB/isisaddons/isis-module-security
-/users/home/me/GITHUB/incodehq/incode-module-commchannel
-/users/home/me/GITHUB/incodehq/incode-module-classification</code></pre>
+ <pre class="CodeRay highlight"><code data-lang="asciidoc">[[concepts]]
+= Concepts
+:_basedir: ../../
+:toc: right
+...</code></pre>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="_bash_functions">7.3. Bash functions</h3>
+ <h3 id="__markup-docs_asciidoc_uml">8.12. UML diagrams</h3>
<div class="paragraph">
- <p>The <code>.bash_functions</code> file (downloadable from this <a href="https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c91cb">gist</a>) provides the following two functions:</p>
+ <p>Asciidoctor includes support for the <a href="http://plantuml.com/">plantuml</a>, allowing simple UML diagrams to be easily sketched.</p>
</div>
- <div class="ulist">
- <ul>
- <li> <p><code>repo</code><br></p>
- <div class="paragraph">
- <p>Switches (using <code>pushd</code>) to the specified directory (as listed in the <code>_repos.txt</code> file).</p>
- </div> </li>
- <li> <p><code>foreach</code><br></p>
- <div class="paragraph">
- <p>Runs the specified command for all (or matching) repositories (as listed in <code>_repos.txt</code> file).</p>
- </div> </li>
- </ul>
+ <div class="paragraph">
+ <p>For example:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[plantuml,_images/mydiagram,png]
+--
+class Car
+
+Driver - Car : drives >
+Car *- Wheel : have 4 >
+Car -- Person : < owns
+--</pre>
+ </div>
</div>
<div class="paragraph">
- <p>For example,</p>
+ <p>renders as:</p>
</div>
- <div class="listingblock">
+ <div class="imageblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">repo doc</code></pre>
+ <img src="_images/mydiagram.png" alt="mydiagram" width="369" height="193">
</div>
</div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_ditaa">8.13. Ditaa diagrams</h3>
<div class="paragraph">
- <p>would switch to <code>/users/home/me/GITHUB/isisaddons/isis-module-docx</code>, the first module that matches the fragment.</p>
+ <p>Asciidoctor includes support for the <a href="http://ditaa.sourceforge.net/">ditaa</a>, allowing boxes-and-lines diagrams to be easily sketched.</p>
</div>
<div class="paragraph">
- <p>Meanwhile:</p>
+ <p>For example:</p>
</div>
- <div class="listingblock">
+ <div class="literalblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">foreach git status</code></pre>
+ <pre>[ditaa]
+----
+ +--------+ +-------+ +-------+
+ | | --+ ditaa +--> | |
+ | Text | +-------+ |diagram|
+ |Document| |!magic!| | |
+ | {d}| | | | |
+ +---+----+ +-------+ +-------+
+ : ^
+ | Lots of work |
+ +-------------------------+
+----</pre>
</div>
</div>
<div class="paragraph">
- <p>would perform a <code>git status</code> on every git repository, while</p>
+ <p>renders as:</p>
</div>
- <div class="listingblock">
+ <div class="imageblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">foreach -g isisaddons git fetch</code></pre>
+ <img src="diag-67cafa2550ee7f6c333238e1926d1666.png" alt="diag 67cafa2550ee7f6c333238e1926d1666" width="430" height="182">
</div>
</div>
+ </div>
+ <div class="sect2">
+ <h3 id="__markup-docs_asciidoc_graphviz">8.14. Graphviz diagrams</h3>
<div class="paragraph">
- <p>would perform a <code>git fetch</code> but only to those repositories which match "isisaddons" (<code>-g</code> flag standing for <code>grep</code>).</p>
+ <p>Asciidoctor includes support for the <a href="http://ditaa.sourceforge.net/">ditaa</a>, allowing boxes-and-lines diagrams to be easily sketched.</p>
</div>
<div class="paragraph">
- <p>To load the functions into your profile (<code>.bashrc</code> or <code>.profile</code> or similar), use:</p>
+ <p>For example:</p>
</div>
- <div class="listingblock">
+ <div class="literalblock">
<div class="content">
- <pre class="CodeRay highlight"><code data-lang="bash">. ~/.bash_functions</code></pre>
+ <pre>[graphviz]
+----
+digraph automata_0 {
+ size ="8.5, 11";
+ node [shape = circle];
+ 0 [ style = filled, color=lightgrey ];
+ 2 [ shape = doublecircle ];
+ 0 -> 2 [ label = "a " ];
+ 0 -> 1 [ label = "other " ];
+ 1 -> 2 [ label = "a " ];
+ 1 -> 1 [ label = "other " ];
+ 2 -> 2 [ label = "a " ];
+ 2 -> 1 [ label = "other " ];
+ "Machine: a" [ shape = plaintext ];
+}
+----</pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>renders as:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="diag-835a00f4a78fc652938f41539d751d16.png" alt="diag 835a00f4a78fc652938f41539d751d16" width="269" height="301">
</div>
</div>
+ <div class="admonitionblock important">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>This requires graphviz to be installed and the <code>dot.exe</code> on the PATH. Alternatively, specify the location, eg using:</p>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>:graphvizdot: c:\Program Files (x86)\Graphviz2.38\bin\dot.exe</pre>
+ </div>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
</div>
</div>
</div>
<div class="sect1">
- <h2 id="_dg_asciidoc-templates">8. Appendix: Asciidoc Templates</h2>
+ <h2 id="_dg_asciidoc-templates">9. Appendix: Asciidoc Templates</h2>
<button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
<div class="sectionbody">
<div class="paragraph">
@@ -3000,10 +4461,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
<p>In the examples below the text <code>xxx</code>, <code>yyy</code>, <code>zzz</code> are correspond to template variables (ie placeholders).</p>
</div>
<div class="sect2">
- <h3 id="_callouts">8.1. Callouts</h3>
- <div class="paragraph">
- <p>The Asciidoctor terminology is an "admonition".</p>
- </div>
+ <h3 id="_admonitions_callouts">9.1. Admonitions (Callouts)</h3>
<table class="tableblock frame-all grid-all spread">
<colgroup>
<col style="width: 14.2857%;">
@@ -3020,7 +4478,17 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmimportant</code></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[IMPORTANT]<br> ====<br> xxx<br> ====</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[IMPORTANT]
+====
+xxx
+====</pre>
+ </div>
+ </div>
+ </div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock important">
@@ -3040,7 +4508,17 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmnote</code></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[NOTE]<br> ====<br> xxx<br> ====</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[NOTE]
+====
+xxx
+====</pre>
+ </div>
+ </div>
+ </div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock note">
@@ -3055,12 +4533,27 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</tr>
</tbody>
</table>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre></pre>
+ </div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmtip</code></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[TIP]<br> ====<br> xxx<br> ====</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[TIP]
+====
+xxx
+====</pre>
+ </div>
+ </div>
+ </div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock tip">
@@ -3075,12 +4568,27 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</tr>
</tbody>
</table>
+ </div>
+ <div class="literalblock">
+ <div class="content">
+ <pre></pre>
+ </div>
</div>
</div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adadmwarning</code></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[WARNING]<br> ====<br> xxx<br> ====</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="literalblock">
+ <div class="content">
+ <pre>[WARNING]
+====
+xxx
+====</pre>
+ </div>
+ </div>
+ </div></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="admonitionblock warning">
@@ -3102,7 +4610,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</table>
</div>
<div class="sect2">
- <h3 id="_todo_notes">8.2. TODO notes</h3>
+ <h3 id="_todo_notes">9.2. TODO notes</h3>
<div class="paragraph">
<p>Add as a placeholder for documentation still to be written or which is work-in-progress.</p>
</div>
@@ -3124,10 +4632,10 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adtodo</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
- <div class="paragraph">
- <p></p>
- <pre>NOTE: TODO</pre>
- <p></p>
+ <div class="literalblock">
+ <div class="content">
+ <pre>NOTE: TODO</pre>
+ </div>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
@@ -3148,10 +4656,10 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>adwip</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
- <div class="paragraph">
- <p></p>
- <pre>NOTE: WIP - xxx</pre>
- <p></p>
+ <div class="literalblock">
+ <div class="content">
+ <pre>NOTE: WIP - xxx</pre>
+ </div>
</div>
<div class="paragraph">
<p>where:</p>
@@ -3180,7 +4688,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</table>
</div>
<div class="sect2">
- <h3 id="_xref_to_guides">8.3. Xref to Guides</h3>
+ <h3 id="_xref_to_guides">9.3. Xref to Guides</h3>
<div class="paragraph">
<p>Cross-references (links) to the various guides</p>
</div>
@@ -3203,9 +4711,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
- <p></p>
- <pre>xref:cgcom.adoc#xxx[ttt]</pre>
- <p></p>
+ <p><code>xref:cgcom.adoc#xxx[ttt]</code></p>
</div>
<div class="paragraph">
<p>a hyperlink to a bookmark within the committers' guide, where:</p>
@@ -3220,9 +4726,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
<p>for example:</p>
</div>
<div class="paragraph">
- <p></p>
- <pre>xref:dg.adoc#_cgcom_cutting-a-release[Cutting a release]</pre>
- <p></p>
+ <p><code>xref:dg.adoc#_cgcom_cutting-a-release[Cutting a release\]</code></p>
</div>
</div></td>
<td class="tableblock halign-left valign-top">
@@ -3233,7 +4737,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</div></td>
</tr>
<tr>
- <td class="tableblock halign-left valign-top"><p class="tableblock"></p><pre>xref:dg.adoc#xxx[ttt]</pre> <p></p><p class="tableblock">a hyperlink to a bookmark within the developers' guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark\u2019s anchor * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"></p><pre>xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates]</pre><p></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:dg.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the developers' guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark\u2019s anchor * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:dg.adoc#_dg_asciidoc-templates[Asciidoc templates\]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
@@ -3248,7 +4752,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</div></td>
</tr>
<tr>
- <td class="tableblock halign-left valign-top"><p class="tableblock"></p><pre>xref:rgant.adoc#xxx[ttt]</pre> <p></p><p class="tableblock">a hyperlink to a bookmark within the reference guide for annotations, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"></p><pre>xref:rgant.adoc#_rgant-aaa_main[Core annotations]</pre><p></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:rgant.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for annotations, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:rgant.adoc#_rgant-aaa_main[Core annotations]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
@@ -3263,7 +4767,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</div></td>
</tr>
<tr>
- <td class="tableblock halign-left valign-top"><p class="tableblock"></p><pre>xref:rgcfg.adoc#xxx[ttt]</pre> <p></p><p class="tableblock">a hyperlink to a bookmark within the reference guide for configuration properties guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"></p><pre>xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]</pre><p></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:rgcfg.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for configuration properties guide, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:rgcfg.adoc#_rgcfg_configuring-core[Configuring Core]</code></p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
@@ -3278,7 +4782,7 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</div></td>
</tr>
<tr>
- <td class="tableblock halign-left valign-top"><p class="tableblock"></p><pre>xref:rgcms.adoc#xxx[ttt]</pre> <p></p><p class="tableblock">a hyperlink to a bookmark within the reference guide for classes, methods and schema, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"></p><pre>xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService`]</pre><p></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:rgcms.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for classes, methods and schema, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:rgcms.adoc#_rgcms_classes_super_AbstractService[`AbstractService</code>]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
@@ -3293,11 +4797,11 @@ git reset --hard <i>shaId</i> # move master branch shaId of com
</div></td>
</tr>
<tr>
- <td class="tableblock halign-left valign-top"><p class="tableblock"></p><pre>xref:rgsvc.adoc#xxx[ttt]</pre> <p></p><p class="tableblock">a hyperlink to a bookmark within the reference guide for domain services, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"></p><pre>xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest` bootstrapping]</pre><p></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>xref:rgsvc.adoc#xxx[ttt]</code> </p><p class="tableblock">a hyperlink to a bookmark within the reference guide for domain services, where: </p><p class="tableblock">* <code>xxx</code> is the bookmark * <code>ttt</code> is the text to display as the hyperlink </p><p class="tableblock">for example: </p><p class="tableblock"><code>xref:rgsvc.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest</code> bootstrapping]`</p></td>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
- <p><a href="xref:r
<TRUNCATED>