HBASE-12902 Post-asciidoc conversion fix-ups
Project: http://git-wip-us.apache.org/repos/asf/hbase/repo Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/5fbf80ee Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/5fbf80ee Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/5fbf80ee Branch: refs/heads/master Commit: 5fbf80ee5ecb288804d2d2d042199dcd834ae848 Parents: 38701ea Author: Misty Stanley-Jones <[email protected]> Authored: Thu Jan 22 13:29:21 2015 +1000 Committer: Misty Stanley-Jones <[email protected]> Committed: Fri Jan 23 13:12:02 2015 +1000 ---------------------------------------------------------------------- .../asciidoc/_chapters/appendix_acl_matrix.adoc | 6 +- .../appendix_contributing_to_documentation.adoc | 169 ++--- .../_chapters/appendix_hfile_format.adoc | 10 +- src/main/asciidoc/_chapters/architecture.adoc | 654 ++++++++----------- src/main/asciidoc/_chapters/case_studies.adoc | 12 +- src/main/asciidoc/_chapters/compression.adoc | 47 +- src/main/asciidoc/_chapters/configuration.adoc | 197 +++--- src/main/asciidoc/_chapters/cp.adoc | 14 +- src/main/asciidoc/_chapters/datamodel.adoc | 122 ++-- src/main/asciidoc/_chapters/developer.adoc | 363 +++++----- .../asciidoc/_chapters/getting_started.adoc | 164 +++-- src/main/asciidoc/_chapters/hbck_in_depth.adoc | 34 +- src/main/asciidoc/_chapters/mapreduce.adoc | 80 ++- src/main/asciidoc/_chapters/ops_mgt.adoc | 188 +++--- src/main/asciidoc/_chapters/performance.adoc | 166 +++-- src/main/asciidoc/_chapters/preface.adoc | 4 +- src/main/asciidoc/_chapters/rpc.adoc | 14 +- src/main/asciidoc/_chapters/schema_design.adoc | 24 +- src/main/asciidoc/_chapters/security.adoc | 242 ++++--- src/main/asciidoc/_chapters/shell.adoc | 51 +- .../_chapters/thrift_filter_language.adoc | 38 +- src/main/asciidoc/_chapters/tracing.adoc | 20 +- .../asciidoc/_chapters/troubleshooting.adoc | 118 ++-- src/main/asciidoc/_chapters/unit_testing.adoc | 16 +- src/main/asciidoc/_chapters/upgrading.adoc | 43 +- src/main/asciidoc/_chapters/zookeeper.adoc | 92 +-- src/main/asciidoc/book.adoc | 2 +- .../xslt/configuration_to_asciidoc_chapter.xsl | 39 +- 28 files changed, 1372 insertions(+), 1557 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hbase/blob/5fbf80ee/src/main/asciidoc/_chapters/appendix_acl_matrix.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/appendix_acl_matrix.adoc b/src/main/asciidoc/_chapters/appendix_acl_matrix.adoc index e89738a..7cf70b2 100644 --- a/src/main/asciidoc/_chapters/appendix_acl_matrix.adoc +++ b/src/main/asciidoc/_chapters/appendix_acl_matrix.adoc @@ -68,11 +68,11 @@ Having Write permission does not imply Read permission.:: It is possible and sometimes desirable for a user to be able to write data that same user cannot read. One such example is a log-writing process. The [systemitem]+hbase:meta+ table is readable by every user, regardless of the user's other grants or restrictions.:: This is a requirement for HBase to function correctly. -[code]+CheckAndPut+ and [code]+CheckAndDelete+ operations will fail if the user does not have both Write and Read permission.:: -[code]+Increment+ and [code]+Append+ operations do not require Read access.:: +`CheckAndPut` and `CheckAndDelete` operations will fail if the user does not have both Write and Read permission.:: +`Increment` and `Append` operations do not require Read access.:: The following table is sorted by the interface that provides each operation. -In case the table goes out of date, the unit tests which check for accuracy of permissions can be found in [path]_hbase-server/src/test/java/org/apache/hadoop/hbase/security/access/TestAccessController.java_, and the access controls themselves can be examined in [path]_hbase-server/src/main/java/org/apache/hadoop/hbase/security/access/AccessController.java_. +In case the table goes out of date, the unit tests which check for accuracy of permissions can be found in _hbase-server/src/test/java/org/apache/hadoop/hbase/security/access/TestAccessController.java_, and the access controls themselves can be examined in _hbase-server/src/main/java/org/apache/hadoop/hbase/security/access/AccessController.java_. .ACL Matrix [cols="1,1,1,1", frame="all", options="header"] http://git-wip-us.apache.org/repos/asf/hbase/blob/5fbf80ee/src/main/asciidoc/_chapters/appendix_contributing_to_documentation.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/appendix_contributing_to_documentation.adoc b/src/main/asciidoc/_chapters/appendix_contributing_to_documentation.adoc index 9cf21e5..6b31059 100644 --- a/src/main/asciidoc/_chapters/appendix_contributing_to_documentation.adoc +++ b/src/main/asciidoc/_chapters/appendix_contributing_to_documentation.adoc @@ -59,7 +59,7 @@ Contact one of the HBase committers, who can either give you access or refer you === 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 [literal]+Documentation+ in addition any other involved components. +Be sure to set the component to `Documentation` in addition 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. @@ -73,7 +73,7 @@ This procedure goes into more detail than Git pros will need, but is included in . 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 [code]+git pull+ command, while your master branch is checked out. +. Fairly often, pull remote changes into your local repository by using the `git pull` command, while your master 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: + @@ -84,9 +84,9 @@ $ git checkout -b HBASE-123456 . 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. . When you are ready to submit your patch, first be sure that HBase builds cleanly and behaves as expected in your modified branch. - If you have made documentation changes, be sure the documentation and website builds. + If you have made documentation changes, be sure the documentation and website builds by running `mvn clean site`. + -NOTE: Before you use the [literal]+site+ target the very first time, be sure you have built HBase at least once, in order to fetch all the Maven dependencies you need. +NOTE: Before you use the `site` target the very first time, be sure you have built HBase at least once, in order to fetch all the Maven dependencies you need. + ---- $ mvn clean install -DskipTests # Builds HBase @@ -107,10 +107,10 @@ $ git rebase origin/master ---- . Generate your patch against the remote master. - Run the following command from the top level of your git repository (usually called [literal]+hbase+): + Run the following command from the top level of your git repository (usually called `hbase`): + ---- -$ git diff --no-prefix origin/master > HBASE-123456.patch +$ git format-patch --stdout origin/master > HBASE-123456.patch ---- + The name of the patch should contain the JIRA ID. @@ -120,12 +120,12 @@ A reviewer will review your patch. 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. . After a change has been committed, there is no need to keep your local branch around. - Instead you should run +git pull+ to get the new change into your master branch. + Instead you should run `git pull` to get the new change into your master branch. === Editing the HBase Website -The source for the HBase website is in the HBase source, in the [path]_src/main/site/_ directory. -Within this directory, source for the individual pages is in the [path]_xdocs/_ directory, and images referenced in those pages are in the [path]_images/_ directory. +The source for the HBase website is in the HBase source, in the _src/main/site/_ directory. +Within this directory, source for the individual pages is in the _xdocs/_ directory, and images referenced in those pages are in the _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 link:http://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs.html. @@ -133,12 +133,12 @@ You can edit these files in a plain-text editor, an IDE, or an XML editor such a To preview your changes, build the website using the +mvn clean site -DskipTests+ command. -The HTML output resides in the [path]_target/site/_ directory. +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. === HBase Reference Guide Style Guide and Cheat Sheet -We may be converting the HBase Reference Guide to use link:http://asciidoctor.org[AsciiDoctor]. In case that happens, the following cheat sheet is included for your reference. More nuanced and comprehensive documentation is available at link:http://asciidoctor.org/docs/user-manual/. To skip down to the Docbook stuff, see <<docbook.editing>>. +The HBase Reference Guide is written in Asciidoc and built using link:http://asciidoctor.org[AsciiDoctor]. The following cheat sheet is included for your reference. More nuanced and comprehensive documentation is available at link:http://asciidoctor.org/docs/user-manual/. .AsciiDoc Cheat Sheet [cols="1,1,a",options="header"] @@ -189,7 +189,7 @@ link:http://www.google.com[Google] ---- <<anchor_name,Anchor Text>> ---- -| An block image | The image with alt text | +| A block image | The image with alt text | ---- image::sunset.jpg[Alt Text] ---- @@ -310,9 +310,7 @@ include::[/path/to/file.adoc] For plenty of examples. see _book.adoc_. | A table | a table | See http://asciidoctor.org/docs/user-manual/#tables. Generally rows are separated by newlines and columns by pipes | Comment out a single line | A line is skipped during rendering | ----- -// This line won't show up ----- +`+//+ This line won't show up` | Comment out a block | A section of the file is skipped during rendering | ---- //// @@ -325,64 +323,40 @@ Test between #hash marks# is highlighted yellow. ---- |=== -[[docbook.editing]] -=== Editing the HBase Reference Guide - -The source for the HBase Reference Guide is in the HBase source, in the [path]_src/main/docbkx/_ directory. -It is written in link:http://www.docbook.org/[Docbook] XML. -Docbook can be intimidating, but you can typically follow the formatting of the surrounding file to get an idea of the mark-up. -You can edit Docbook XML files using a plain-text editor, an XML-aware IDE, or a specialized XML editor. - -Docbook's syntax can be picky. -Before submitting a patch, be sure to build the output locally using the +mvn site+ command. -If you do not get any build errors, that means that the XML is well-formed, which means that each opening tag is balanced by a closing tag. -Well-formedness is not exactly the same as validity. -Check the output in [path]_target/docbkx/_ for any surprises before submitting a patch. === 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 [path]_src/main/xslt/configuration_to_docbook_section.xsl_. -This transforms the [path]_hbase-common/src/main/resources/hbase-default.xml_ file into a Docbook output which can be included in the Reference Guide. +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. -=== Multi-Page and Single-Page Output - -You can examine the [literal]+site+ target in the Maven [path]_pom.xml_ file included at the top level of the HBase source for details on the process of building the website and documentation. -The Reference Guide is built twice, once as a single-page output and once with one HTML file per chapter. -The single-page output is located in [path]_target/docbkx/book.html_, while the multi-page output's index page is at [path]_target/docbkx/book/book.html_. -Each of these outputs has its own [path]_images/_ and [path]_css/_ directories, which are created at build time. === Images in the HBase Reference Guide -You can include images in the HBase Reference Guide. -For accessibility reasons, it is recommended that you use a <figure> Docbook element for an image. +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 a <figure> element. +The following is an example of an image with a title and alternate text. Notice the double colon. -[source,xml] +[source,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. + +[source,asciidoc] ---- -<figure> - <title>HFile Version 1</title> - <mediaobject> - <imageobject> - <imagedata fileref="timeline_consistency.png" /> - </imageobject> - <textobject> - <phrase>HFile Version 1</phrase> - </textobject> - </mediaobject> -</figure> +image:sunset.jpg[Alt Text] ---- -The <textobject> can contain a few sentences describing the image, rather than simply reiterating the title. -You can optionally specify alignment and size options in the <imagedata> element. -When doing a local build, save the image to the [path]_src/main/site/resources/images/_ directory. -In the <imagedata> element, refer to the image as above, with no directory component. +When doing a local build, save the image to the _src/main/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. @@ -390,89 +364,32 @@ If the committer asks where the image should be committed, it should go into the === 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 and title elements near the top of the file. +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 [path]_book.xml_ file, which is the main file for the HBase Reference Guide, and use an <xi:include> element to include your new chapter in the appropriate location. +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. -Note that the [path]_book.xml_ file currently contains many chapters. -You can only include a chapter at the same nesting levels as the other chapters in the file. + When in doubt, check to see how other files have been included. -=== Docbook Common Issues +=== Common Documentation Issues -The following Docbook issues come up often. +The following documentation issues come up often. Some of these are preferences, but others can create mysterious build errors or other problems. [qanda] -What can go where?:: - There is often confusion about which child elements are valid in a given context. When in doubt, Docbook: The Definitive Guide is the best resource. It has an appendix which is indexed by element and contains all valid child and parent elements of any given element. If you edit Docbook often, a schema-aware XML editor makes things easier. - -Paragraphs and Admonitions:: - It is a common pattern, and it is technically valid, to put an admonition such as a <note> inside a <para> element. Because admonitions render as block-level elements (they take the whole width of the page), it is better to mark them up as siblings to the paragraphs around them, like this: -+ -[source,xml] ----- -<para>This is the paragraph.</para> -<note> - <para>This is an admonition which occurs after the paragraph.</para> -</note> ----- - -Wrap textual <listitem> and <entry> contents in <para> elements.:: - Because the contents of a <listitem> (an element in an itemized, ordered, or variable list) or an <entry> (a cell in a table) can consist of things other than plain text, they need to be wrapped in some element. If they are plain text, they need to be inclosed in <para> tags. This is tedious but necessary for validity. -+ -[source,xml] ----- -<itemizedlist> - <listitem> - <para>This is a paragraph.</para> - </listitem> - <listitem> - <screen>This is screen output.</screen> - </listitem> -</itemizedlist> ----- - -When to use <command>, <code>, <programlisting>, <screen>?:: - The first two are in-line tags, which can occur within the flow of paragraphs or titles. The second two are block elements. -+ -Use <command> to mention a command such as hbase shell in the flow of a sentence. Use <code> for other inline text referring to code. Incidentally, use <literal> to specify literal strings that should be typed or entered exactly as shown. Within a <screen> listing, it can be helpful to use the <userinput> and <computeroutput> elements to mark up the text further. -+ -Use <screen> to display input and output as the user would see it on the screen, in a log file, etc. Use <programlisting> only for blocks of code that occur within a file, such as Java or XML code, or a Bash shell script. - -How to escape XML elements so that they show up as XML?:: - For one-off instances or short in-line mentions, use the `<` and `>` encoded characters. For longer mentions, or blocks of code, enclose it with `<![CDATA[]]>`, which is much easier to maintain and parse in the source files. +Isolate Changes for Easy Diff Review.:: + 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. -Tips and tricks for making screen output look good:: - Text within <screen> and <programlisting> elements is shown exactly as it appears in the source, including indentation, tabs, and line wrap. -+ -Indent the starting and closing XML elements, but do not indent the content. Also, to avoid having an extra blank line at the beginning of the programlisting output, do not put the CDATA element on its own line. For example: +Syntax Highlighting:: + 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] ---- - <programlisting> -case $1 in - --cleanZk|--cleanHdfs|--cleanAll) - matches="yes" ;; - *) ;; -esac - </programlisting> +<name>My Name</name> ---- +........ + -After pasting code into a programlisting, fix the indentation manually, using two spaces per desired indentation. For screen output, be sure to include line breaks so that the text is no longer than 100 characters. +Several syntax types are supported. The most interesting ones for the HBase Reference Guide are `java`, `xml`, `sql`, and `bash`. -Isolate Changes for Easy Diff Review.:: - 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. - -Syntax Highlighting:: - The HBase Reference Guide uses the XSLT Syntax Highlighting Maven module for syntax highlighting. To enable syntax highlighting for a given <programlisting> or <screen> (or possibly other elements), add the attribute language=LANGUAGE_OF_CHOICE to the element, as in the following example: - + - [source,xml] - ---- -<programlisting language="xml"> - <foo>bar</foo> - <bar>foo</bar> -</programlisting> - ---- - + - Several syntax types are supported. The most interesting ones for the HBase Reference Guide are java, xml, sql, and bourne (for BASH shell output or Linux command-line examples). http://git-wip-us.apache.org/repos/asf/hbase/blob/5fbf80ee/src/main/asciidoc/_chapters/appendix_hfile_format.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/appendix_hfile_format.adoc b/src/main/asciidoc/_chapters/appendix_hfile_format.adoc index c2b0709..b74763c 100644 --- a/src/main/asciidoc/_chapters/appendix_hfile_format.adoc +++ b/src/main/asciidoc/_chapters/appendix_hfile_format.adoc @@ -312,12 +312,12 @@ Version 3 added two additional pieces of information to the reserved keys in the | hfile.TAGS_COMPRESSED | Does the block encoder for this hfile compress tags? (boolean). Should only be present if hfile.MAX_TAGS_LEN is also present. |=== -When reading a Version 3 HFile the presence of [class]+MAX_TAGS_LEN+ is used to determine how to deserialize the cells within a data block. +When reading a Version 3 HFile the presence of `MAX_TAGS_LEN` is used to determine how to deserialize the cells within a data block. Therefore, consumers must read the file's info block prior to reading any data blocks. -When writing a Version 3 HFile, HBase will always include [class]+MAX_TAGS_LEN + when flushing the memstore to underlying filesystem and when using prefix tree encoding for data blocks, as described in <<compression,compression>>. +When writing a Version 3 HFile, HBase will always include `MAX_TAGS_LEN ` when flushing the memstore to underlying filesystem and when using prefix tree encoding for data blocks, as described in <<compression,compression>>. -When compacting extant files, the default writer will omit [class]+MAX_TAGS_LEN+ if all of the files selected do not themselves contain any cells with tags. +When compacting extant files, the default writer will omit `MAX_TAGS_LEN` if all of the files selected do not themselves contain any cells with tags. See <<compaction,compaction>> for details on the compaction file selection algorithm. @@ -338,11 +338,11 @@ Within an HFile, HBase cells are stored in data blocks as a sequence of KeyValue | | Tags bytes (variable) |=== -If the info block for a given HFile contains an entry for [class]+MAX_TAGS_LEN+ each cell will have the length of that cell's tags included, even if that length is zero. +If the info block for a given HFile contains an entry for `MAX_TAGS_LEN` each cell will have the length of that cell's tags included, even if that length is zero. The actual tags are stored as a sequence of tag length (2 bytes), tag type (1 byte), tag bytes (variable). The format an individual tag's bytes depends on the tag type. Note that the dependence on the contents of the info block implies that prior to reading any data blocks you must first process a file's info block. -It also implies that prior to writing a data block you must know if the file's info block will include [class]+MAX_TAGS_LEN+. +It also implies that prior to writing a data block you must know if the file's info block will include `MAX_TAGS_LEN`. [[hfilev3.fixedtrailer]] ==== Fixed File Trailer in Version 3
