Contributing to Documentation

The Apache HBase project welcomes contributions to all aspects of the project, including the documentation.

In HBase, documentation includes the following areas, and probably some others:

The HBase Reference Guide (this book)
The HBase website
API documentation
Command-line utility output and help text
Web UI strings, explicit help text, context-sensitive strings, and others
Log messages
Comments in source files, configuration files, and others
Localization of any of the above into target languages other than English

No matter which area you want to help out with, the first step is almost always to download (typically by cloning the Git repository) and familiarize yourself with the HBase source code. For information on downloading and building the source, see developer.

Contributing to Documentation or Other Strings

If you spot an error in a string in a UI, utility, script, log message, or elsewhere, or you think something could be made more clear, or you think text needs to be added where it doesn’t currently exist, the first step is to file a JIRA. Be sure to set the component to Documentation in addition to any other involved components. Most components have one or more default owners, who monitor new issues which come into those queues. Regardless of whether you feel able to fix the bug, you should still file bugs where you see them.

If you want to try your hand at fixing your newly-filed bug, assign it to yourself. You will need to clone the HBase Git repository to your local system and work on the issue there. When you have developed a potential fix, submit it for review. If it addresses the issue and is seen as an improvement, one of the HBase committers will commit it to one or more branches, as appropriate.

Procedure: Suggested Work flow for Submitting Patches

This procedure goes into more detail than Git pros will need, but is included in this appendix so that people unfamiliar with Git can feel confident contributing to HBase while they learn.

If you have not already done so, clone the Git repository locally. You only need to do this once.
Fairly often, pull remote changes into your local repository by using the git pull command, while your tracking branch is checked out.
For each issue you work on, create a new branch. One convention that works well for naming the branches is to name a given branch the same as the JIRA it relates to:

``` java
$ git checkout -b HBASE-123456


4.  Make your suggested changes on your branch, committing your changes to your local repository often. If you need to switch to working on a different issue, remember to check out the appropriate branch.

5.  When you are ready to submit your patch, first be sure that HBase builds cleanly and behaves as expected in your modified branch.

6.  If you have made documentation changes, be sure the documentation and website builds by running `mvn clean site`.

7.  If it takes you several days or weeks to implement your fix, or you know that the area of the code you are working in has had a lot of changes lately, make sure you rebase your branch against the remote master and take care of any conflicts before submitting your patch.

$ git checkout HBASE-123456
$ git rebase origin/master


8.  Generate your patch against the remote master. Run the following command from the top level of your git repository (usually called `hbase`):

$ git format-patch --stdout origin/master > HBASE-123456.patch

The name of the patch should contain the JIRA ID.


9.  Look over the patch file to be sure that you did not change any additional files by accident and that there are no other surprises.

10. When you are satisfied, attach the patch to the JIRA and click the Patch Available button. A reviewer will review your patch.

11. If you need to submit a new version of the patch, leave the old one on the JIRA and add a version number to the name of the new patch.

12. After a change has been committed, there is no need to keep your local branch around.

# Editing the HBase Website

The source for the HBase website is in the HBase source, in the *src/site/* directory. Within this directory, source for the individual pages is in the *xdocs/* directory, and images referenced in those pages are in the *resources/images/* directory. This directory also stores images used in the HBase Reference Guide.

The website’s pages are written in an HTML-like XML dialect called xdoc, which has a reference guide at [https://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs.html](https://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs.html). You can edit these files in a plain-text editor, an IDE, or an XML editor such as XML Mind XML Editor (XXE) or Oxygen XML Author.

To preview your changes, build the website using the `mvn clean site -DskipTests` command. The HTML output resides in the *target/site/* directory. When you are satisfied with your changes, follow the procedure in [submit doc patch procedure](#submit_doc_patch_procedure) to submit your patch.

# Publishing the HBase Website and Documentation

HBase uses the ASF’s `gitpubsub` mechanism. A Jenkins job runs the `dev-support/jenkins-scripts/generate-hbase-website.sh` script, which runs the `mvn clean site site:stage` against the `master` branch of the `hbase` repository and commits the built artifacts to the `asf-site` branch of the `hbase-site` repository. When the commit is pushed, the website is redeployed automatically. If the script encounters an error, an email is sent to the developer mailing list. You can run the script manually or examine it to see the steps involved.

# Checking the HBase Website for Broken Links

A Jenkins job runs periodically to check HBase website for broken links, using the `dev-support/jenkins-scripts/check-website-links.sh` script. This script uses a tool called `linklint` to check for bad links and create a report. If broken links are found, an email is sent to the developer mailing list. You can run the script manually or examine it to see the steps involved.

# HBase Reference Guide Style Guide and Cheat Sheet

The HBase Reference Guide is written in Asciidoc and built using [AsciiDoctor](http://asciidoctor.org). The following cheat sheet is included for your reference. More nuanced and comprehensive documentation is available at [http://asciidoctor.org/docs/user-manual/](http://asciidoctor.org/docs/user-manual/).

<table>
<caption>AsciiDoc Cheat Sheet</caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr>
<th style="text-align: left;">Element Type</th>
<th style="text-align: left;">Desired Rendering</th>
<th style="text-align: left;">How to do it</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;"><p>A paragraph</p></td>
<td style="text-align: left;"><p>a paragraph</p></td>
<td style="text-align: left;"><p>Just type some text with a blank line at the top and bottom.</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Add line breaks within a paragraph without adding blank lines</p></td>
<td style="text-align: left;"><p>Manual line breaks</p></td>
<td style="text-align: left;"><p>This will break + at the plus sign. Or prefix the whole paragraph with a line containing '[%hardbreaks]'</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Give a title to anything</p></td>
<td style="text-align: left;"><p>Colored italic bold differently-sized text</p></td>
<td style="text-align: left;"></td>
</tr>
<tr>
<td style="text-align: left;"><p>In-Line Code or commands</p></td>
<td style="text-align: left;"><p>monospace</p></td>
<td style="text-align: left;"><p>`text`</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>In-line literal content (things to be typed exactly as shown)</p></td>
<td style="text-align: left;"><p>bold mono</p></td>
<td style="text-align: left;"><p>*`typethis`*</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>In-line replaceable content (things to substitute with your own values)</p></td>
<td style="text-align: left;"><p>bold italic mono</p></td>
<td style="text-align: left;"><p>*_typesomething_*</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Code blocks with highlighting</p></td>
<td style="text-align: left;"><p>monospace, highlighted, preserve space</p></td>
<td style="text-align: left;"><pre><code>{`[source,java]
----
  myAwesomeCode() {
}
----`}</code></pre></td>
</tr>
<tr>
<td style="text-align: left;"><p>Code block included from a separate file</p></td>
<td style="text-align: left;"><p>included just as though it were part of the main file</p></td>
<td style="text-align: left;"><pre><code>{`[source,ruby]
----
include\::path/to/app.rb[]
----`}</code></pre></td>
</tr>
<tr>
<td style="text-align: left;"><p>Include only part of a separate file</p></td>
<td style="text-align: left;"><p>Similar to Javadoc</p></td>
<td style="text-align: left;"><p>See <a href="http://asciidoctor.org/docs/user-manual/#by-tagged-regions">http://asciidoctor.org/docs/user-manual/#by-tagged-regions</a></p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Filenames, directory names, new terms</p></td>
<td style="text-align: left;"><p>italic</p></td>
<td style="text-align: left;"><p>_hbase-default.xml_</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>External naked URLs</p></td>
<td style="text-align: left;"><p>A link with the URL as link text</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb3"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>link<span className="op">:</span>http<span className="op">:</span><span className="co">//www.google.com</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>External URLs with text</p></td>
<td style="text-align: left;"><p>A link with arbitrary link text</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb4"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a>link<span className="op">:</span>http<span className="op">:</span><span className="co">//www.google.com[Google]</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Create an internal anchor to cross-reference</p></td>
<td style="text-align: left;"><p>not rendered</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb5"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span className="op">[[</span>anchor_name<span className="op">]]</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Cross-reference an existing anchor using its default title</p></td>
<td style="text-align: left;"><p>an internal hyperlink using the element title if available, otherwise using the anchor name</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb6"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span className="op">&lt;&lt;</span>anchor_name<span className="op">&gt;&gt;</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Cross-reference an existing anchor using custom text</p></td>
<td style="text-align: left;"><p>an internal hyperlink using arbitrary text</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb7"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span className="op">&lt;&lt;</span>anchor_name<span className="op">,</span>Anchor <span className="bu">Text</span><span className="op">&gt;&gt;</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>A block image</p></td>
<td style="text-align: left;"><p>The image with alt text</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb8"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a>image<span className="op">::</span>sunset<span className="op">.</span><span className="fu">jpg</span><span className="op">[</span>Alt <span className="bu">Text</span><span className="op">]</span></span></code></pre></div>
<p>(put the image in the src/site/resources/images directory)</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>An inline image</p></td>
<td style="text-align: left;"><p>The image with alt text, as part of the text flow</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb9"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a>image<span className="op">:</span>sunset<span className="op">.</span><span className="fu">jpg</span> <span className="op">[</span>Alt <span className="bu">Text</span><span className="op">]</span></span></code></pre></div>
<p>(only one colon)</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Link to a remote image</p></td>
<td style="text-align: left;"><p>show an image hosted elsewhere</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb10"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>image<span className="op">::</span>http<span className="op">:</span><span className="co">//inkscape.org/doc/examples/tux.svg[Tux,250,350]</span></span></code></pre></div>
<p>(or <code>image:</code>)</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Add dimensions or a URL to the image</p></td>
<td style="text-align: left;"><p>depends</p></td>
<td style="text-align: left;"><p>inside the brackets after the alt text, specify width, height and/or link="http://my_link.com"</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>A footnote</p></td>
<td style="text-align: left;"><p>subscript link which takes you to the footnote</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb11"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>Some text<span className="op">.</span><span className="fu">footnote</span><span className="op">:[</span>The footnote text<span className="op">.]</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>A note or warning with no title</p></td>
<td style="text-align: left;"><p>The admonition image followed by the admonition</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb12"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a>NOTE<span className="op">:</span>My note here</span></code></pre></div>
<div className="sourceCode" id="cb13"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>WARNING<span className="op">:</span>My warning here</span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>A complex note</p></td>
<td style="text-align: left;"><p>The note has a title and/or multiple paragraphs and/or code blocks or lists, etc</p></td>
<td style="text-align: left;"><pre><code>{`.The Title
[NOTE]
====
Here is the note text. Everything until the second set of four equals signs is part of the note.
----
some source code
----
====`}</code></pre></td>
</tr>
<tr>
<td style="text-align: left;"><p>Bullet lists</p></td>
<td style="text-align: left;"><p>bullet lists</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb15"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span className="op">*</span> list item <span className="dv">1</span></span></code></pre></div>
<p>(see <a href="http://asciidoctor.org/docs/user-manual/#unordered-lists">http://asciidoctor.org/docs/user-manual/#unordered-lists</a>)</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Numbered lists</p></td>
<td style="text-align: left;"><p>numbered list</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb16"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span className="op">.</span> <span className="fu">list</span> item <span className="dv">2</span></span></code></pre></div>
<p>(see <a href="http://asciidoctor.org/docs/user-manual/#ordered-lists">http://asciidoctor.org/docs/user-manual/#ordered-lists</a>)</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Checklists</p></td>
<td style="text-align: left;"><p>Checked or unchecked boxes</p></td>
<td style="text-align: left;"><p>Checked:</p>
<div className="sourceCode" id="cb17"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span className="op">-</span> <span className="op">[*]</span></span></code></pre></div>
<p>Unchecked:</p>
<div className="sourceCode" id="cb18"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span className="op">-</span> <span className="op">[</span> <span className="op">]</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Multiple levels of lists</p></td>
<td style="text-align: left;"><p>bulleted or numbered or combo</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb19"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span className="op">.</span> <span className="fu">Numbered</span> <span className="op">(</span><span className="dv">1</span><span className="op">),</span> at top level</span>
<span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span className="op">*</span> <span className="fu">Bullet</span> <span className="op">(</span><span className="dv">2</span><span className="op">),</span> nested under <span className="dv">1</span></span>
<span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a><span className="op">*</span> <span className="fu">Bullet</span> <span className="op">(</span><span className="dv">3</span><span className="op">),</span> nested under <span className="dv">1</span></span>
<span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a><span className="op">.</span> <span className="fu">Numbered</span> <span className="op">(</span><span className="dv">4</span><span className="op">),</span> at top level</span>
<span id="cb19-5"><a href="#cb19-5" aria-hidden="true" tabindex="-1"></a><span className="op">*</span> <span className="fu">Bullet</span> <span className="op">(</span><span className="dv">5</span><span className="op">),</span> nested under <span className="dv">4</span></span>
<span id="cb19-6"><a href="#cb19-6" aria-hidden="true" tabindex="-1"></a><span className="op">**</span> <span className="fu">Bullet</span> <span className="op">(</span><span className="dv">6</span><span className="op">),</span> nested under <span className="dv">5</span></span>
<span id="cb19-7"><a href="#cb19-7" aria-hidden="true" tabindex="-1"></a><span className="op">-</span> <span className="op">[</span>x<span className="op">]</span> <span className="fu">Checked</span> <span className="op">(</span><span className="dv">7</span><span className="op">),</span> at top level</span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Labelled lists / variablelists</p></td>
<td style="text-align: left;"><p>a list item title or summary followed by content</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb20"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a>Title<span className="op">::</span> content</span>
<span id="cb20-2"><a href="#cb20-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb20-3"><a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>Title<span className="op">::</span></span>
<span id="cb20-4"><a href="#cb20-4" aria-hidden="true" tabindex="-1"></a>  content</span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Sidebars, quotes, or other blocks of text</p></td>
<td style="text-align: left;"><p>a block of text, formatted differently from the default</p></td>
<td style="text-align: left;"><p>Delimited using different delimiters, see <a href="http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary">http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary</a>. Some of the examples above use delimiters like ...., ----,====.</p>
<pre><code>{`[example]
====
This is an example block.
====
&#10;[source]
----
This is a source block.
----
&#10;[note]
====
This is a note block.
====
&#10;[quote]
____
This is a quote block.
____`}</code></pre>
<p>If you want to insert literal Asciidoc content that keeps being interpreted, when in doubt, use eight dots as the delimiter at the top and bottom.</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Nested Sections</p></td>
<td style="text-align: left;"><p>chapter, section, sub-section, etc</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb22"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span className="op">=</span> <span className="bu">Book</span> <span className="op">(</span>or chapter <span className="cf">if</span> the chapter can be built alone<span className="op">,</span> see the leveloffset info below<span className="op">)</span></span>
<span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span className="op">==</span> <span className="fu">Chapter</span> <span className="op">(</span>or section <span className="cf">if</span> the chapter is standalone<span className="op">)</span></span>
<span id="cb22-4"><a href="#cb22-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-5"><a href="#cb22-5" aria-hidden="true" tabindex="-1"></a><span className="op">===</span> <span className="fu">Section</span> <span className="op">(</span>or subsection<span className="op">,</span> etc<span className="op">)</span></span>
<span id="cb22-6"><a href="#cb22-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb22-7"><a href="#cb22-7" aria-hidden="true" tabindex="-1"></a><span className="op">====</span> Subsection</span></code></pre></div>
<p>and so on up to 6 levels (think carefully about going deeper than 4 levels, maybe you can just titled paragraphs or lists instead). Note that you can include a book inside another book by adding the <code>:leveloffset:+1</code> macro directive directly before your include, and resetting it to 0 directly after. See the <em>book.adoc</em> source for examples, as this is how this guide handles chapters. <strong>Don’t do it for prefaces, glossaries, appendixes, or other special types of chapters.</strong></p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Include one file from another</p></td>
<td style="text-align: left;"><p>Content is included as though it were inline</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb23"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a>include<span className="op">::[/</span>path<span className="op">/</span>to<span className="op">/</span>file<span className="op">.</span><span className="fu">adoc</span><span className="op">]</span></span></code></pre></div>
<p>For plenty of examples. see <em>book.adoc</em>.</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>A table</p></td>
<td style="text-align: left;"><p>a table</p></td>
<td style="text-align: left;"><p>See <a href="http://asciidoctor.org/docs/user-manual/#tables">http://asciidoctor.org/docs/user-manual/#tables</a>. Generally rows are separated by newlines and columns by pipes</p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Comment out a single line</p></td>
<td style="text-align: left;"><p>A line is skipped during rendering</p></td>
<td style="text-align: left;"><p><code>// This line won’t show up</code></p></td>
</tr>
<tr>
<td style="text-align: left;"><p>Comment out a block</p></td>
<td style="text-align: left;"><p>A section of the file is skipped during rendering</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb24"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span className="co">////</span></span>
<span id="cb24-2"><a href="#cb24-2" aria-hidden="true" tabindex="-1"></a>Nothing between the slashes will show up<span className="op">.</span></span>
<span id="cb24-3"><a href="#cb24-3" aria-hidden="true" tabindex="-1"></a><span className="co">////</span></span></code></pre></div></td>
</tr>
<tr>
<td style="text-align: left;"><p>Highlight text for review</p></td>
<td style="text-align: left;"><p>text shows up with yellow background</p></td>
<td style="text-align: left;"><div className="sourceCode" id="cb25"><pre class="sourceCode java"><code class="sourceCode java"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a>Test between #hash marks# is highlighted yellow<span className="op">.</span></span></code></pre></div></td>
</tr>
</tbody>
</table>

# Auto-Generated Content

Some parts of the HBase Reference Guide, most notably [config.files](#config.files), are generated automatically, so that this area of the documentation stays in sync with the code. This is done by means of an XSLT transform, which you can examine in the source at *src/main/xslt/configuration_to_asciidoc_chapter.xsl*. This transforms the *hbase-common/src/main/resources/hbase-default.xml* file into an Asciidoc output which can be included in the Reference Guide.

Sometimes, it is necessary to add configuration parameters or modify their descriptions. Make the modifications to the source file, and they will be included in the Reference Guide when it is rebuilt.

It is possible that other types of content can and will be automatically generated from HBase source files in the future.

# Images in the HBase Reference Guide

You can include images in the HBase Reference Guide. It is important to include an image title if possible, and alternate text always. This allows screen readers to navigate to the image and also provides alternative text for the image. The following is an example of an image with a title and alternate text. Notice the double colon.

``` asciidoc
.My Image Title
image::sunset.jpg[Alt Text]

Here is an example of an inline image with alternate text. Notice the single colon. Inline images cannot have titles. They are generally small images like GUI buttons.

image:sunset.jpg[Alt Text]

When doing a local build, save the image to the src/site/resources/images/ directory. When you link to the image, do not include the directory portion of the path. The image will be copied to the appropriate target location during the build of the output.

When you submit a patch which includes adding an image to the HBase Reference Guide, attach the image to the JIRA. If the committer asks where the image should be committed, it should go into the above directory.

Adding a New Chapter to the HBase Reference Guide

If you want to add a new chapter to the HBase Reference Guide, the easiest way is to copy an existing chapter file, rename it, and change the ID (in double brackets) and title. Chapters are located in the src/main/asciidoc/_chapters/ directory.

Delete the existing content and create the new content. Then open the src/main/asciidoc/book.adoc file, which is the main file for the HBase Reference Guide, and copy an existing include element to include your new chapter in the appropriate location. Be sure to add your new file to your Git repository before creating your patch.

When in doubt, check to see how other files have been included.

Common Documentation Issues

The following documentation issues come up often. Some of these are preferences, but others can create mysterious build errors or other problems.

Q: Isolate Changes for Easy Diff Review.

A: Be careful with pretty-printing or re-formatting an entire XML file, even if the formatting has degraded over time. If you need to reformat a file, do that in a separate JIRA where you do not change any content. Be careful because some XML editors do a bulk-reformat when you open a new file, especially if you use GUI mode in the editor.

Q: Syntax Highlighting

A: The HBase Reference Guide uses coderay for syntax highlighting. To enable syntax highlighting for a given code listing, use the following type of syntax:

[source,xml]
----
\<name\>My Name</name>
----

Several syntax types are supported. The most interesting ones for the HBase Reference Guide are java, xml, sql, and bash.

Appendix: Contributing to Documentation

Contributing to Documentation

Contributing to Documentation or Other Strings

Adding a New Chapter to the HBase Reference Guide

Common Documentation Issues

On this page