You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kudu.apache.org by ab...@apache.org on 2018/08/17 15:14:42 UTC
kudu git commit: [docs] KUDU-1951 Fix links in docs
Repository: kudu
Updated Branches:
refs/heads/master dfa465265 -> 37a81b82c
[docs] KUDU-1951 Fix links in docs
The "site_tool proof" tool was showing lots of errors making it hard to
see new issues being introduced in the documentation or the site.
This commit fixes the broken links in the documentation:
- several trivial changes due to some past reorganizations
- developing.adoc includes a tag from installation.adoc which has links
to anchors, which for some reason didn't work properly when included
from a developing.html - this is fixed by changing the anchors to
relative links to installation.html#<id>
- transaction_semantics.adoc had bibliography references that were
syntactically incorrect
Change-Id: I2c498c8a7f9d957a737c12c08d1b313df3d68007
Reviewed-on: http://gerrit.cloudera.org:8080/11239
Tested-by: Attila Bukor <ab...@apache.org>
Reviewed-by: Grant Henke <gr...@apache.org>
Project: http://git-wip-us.apache.org/repos/asf/kudu/repo
Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/37a81b82
Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/37a81b82
Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/37a81b82
Branch: refs/heads/master
Commit: 37a81b82cc2e5e1ca9ad7291740b4e963e609bcc
Parents: dfa4652
Author: Attila Bukor <ab...@apache.org>
Authored: Thu Aug 16 00:04:53 2018 +0200
Committer: Attila Bukor <ab...@apache.org>
Committed: Fri Aug 17 15:14:04 2018 +0000
----------------------------------------------------------------------
docs/configuration.adoc | 4 ++--
docs/contributing.adoc | 24 +++++++++++++-----------
docs/installation.adoc | 16 +++++++++-------
docs/prior_release_notes.adoc | 4 ----
docs/quickstart.adoc | 2 +-
docs/schema_design.adoc | 2 +-
docs/support/scripts/make_site.sh | 2 +-
docs/transaction_semantics.adoc | 23 ++++++++++++-----------
8 files changed, 39 insertions(+), 38 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/configuration.adoc
----------------------------------------------------------------------
diff --git a/docs/configuration.adoc b/docs/configuration.adoc
index 390fc22..6a0a7f0 100644
--- a/docs/configuration.adoc
+++ b/docs/configuration.adoc
@@ -108,7 +108,7 @@ addresses for Master consensus-configuration. If not specified, assumes a standa
|===
For the full list of flags for masters, see the
-link:configuration_reference.html#master_configuration_reference[Kudu Master Configuration Reference].
+link:configuration_reference.html#kudu-master_supported[Kudu Master Configuration Reference].
=== Configuring Tablet Servers
To see all available configuration options for the `kudu-tserver` executable,
@@ -133,7 +133,7 @@ do not read this flag.
|===
For the full list of flags for tablet servers, see the
-link:configuration_reference.html#tablet_server_configuration_reference[Kudu Tablet Server Configuration Reference].
+link:configuration_reference.html#kudu-tserver_supported[Kudu Tablet Server Configuration Reference].
== Next Steps
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/contributing.adoc
----------------------------------------------------------------------
diff --git a/docs/contributing.adoc b/docs/contributing.adoc
index c1c393d..e182c4e 100644
--- a/docs/contributing.adoc
+++ b/docs/contributing.adoc
@@ -152,7 +152,9 @@ submit a patch to the review, even if you were not the original reviewer.
Gerrit allows you to vote on a review. A vote of `+2` from at least one committer
(besides the submitter) is required before the patch can be merged.
-== {cpp} Code Style
+== Code Style
+
+=== {cpp} Code Style
Get familiar with these guidelines so that your contributions can be reviewed and
integrated quickly and easily.
@@ -161,7 +163,7 @@ In general, Kudu follows the
link:https://google.github.io/styleguide/cppguide.html[Google {cpp} Style Guide],
with the following exceptions:
-=== Notes on {cpp} 11
+==== Notes on {cpp} 11
Kudu uses {cpp} 11. Check out this handy guide to {cpp} 11 move semantics and rvalue
references: https://www.chromium.org/rvalue-references
@@ -169,7 +171,7 @@ references: https://www.chromium.org/rvalue-references
We aim to follow most of the same guidelines, such as, where possible, migrating
away from `foo.Pass()` in favor of `std::move(foo)`.
-=== Limitations on `boost` Use
+==== Limitations on `boost` Use
`boost` classes from header-only libraries can be used in cases where a suitable
replacement does not exist in the Kudu code base. However:
@@ -188,12 +190,12 @@ replacement does not exist in the Kudu code base. However:
When in doubt about introducing a new dependency on any `boost` functionality,
it is best to email `dev@kudu.apache.org` to start a discussion.
-=== Line length
+==== Line length
The Kudu team allows line lengths of 100 characters per line, rather than Google's standard of 80. Try to
keep under 80 where possible, but you can spill over to 100 or so if necessary.
-=== Pointers
+==== Pointers
.Smart Pointers and Singly-Owned Pointers
@@ -282,7 +284,7 @@ Since `scoped_refptr` is generally faster and smaller, try to use it
rather than `shared_ptr` in new code. Existing code uses `shared_ptr`
in many places. When interfacing with that code, you can continue to use `shared_ptr`.
-=== Function Binding and Callbacks
+==== Function Binding and Callbacks
Existing code uses `boost::bind` and `boost::function` for function binding and
callbacks. For new code, use the `Callback` and `Bind` classes in `gutil` instead.
@@ -295,7 +297,7 @@ and decremented when the `Callback` goes out of scope.
See the large file comment in _gutil/callback.h_ for more details, and
_util/callback_bind-test.cc_ for examples.
-=== GFlags
+==== GFlags
Kudu uses gflags for both command-line and file-based configuration. Use these guidelines
to add a new gflag. All new gflags must conform to these
@@ -356,9 +358,9 @@ comment in _flag_tags.h_ for guidelines.
creating `foo_wal_dir` and `bar_wal_dir` gflags, better to have a single
`kudu_wal_dir` gflag for use universally.
-== Java Code Style
+=== Java Code Style
-=== Preconditions vs assert in the Kudu Java client
+==== Preconditions vs assert in the Kudu Java client
Use `assert` for verification of the static (i.e. non-runtime) internal
invariants. Internal means the pre- and post-conditions which are
@@ -397,11 +399,11 @@ if (!isCriticalConditionSatisfied) {
}
----
-==== References
+===== References
* link:https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html[Programming With Assertions]
* link:https://github.com/google/guava/wiki/PreconditionsExplained[Guava Preconditions Explained]
-== `CMake` Style Guide
+=== `CMake` Style Guide
`CMake` allows commands in lower, upper, or mixed case. To keep
the CMake files consistent, please use the following guidelines:
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/installation.adoc
----------------------------------------------------------------------
diff --git a/docs/installation.adoc b/docs/installation.adoc
index 236c325..4b2fc84 100644
--- a/docs/installation.adoc
+++ b/docs/installation.adoc
@@ -686,10 +686,11 @@ see `java/README.md`.
// tag::view_api[]
.C++ API Documentation
-You can view the link:../cpp-client-api/index.html[C++ client API documentation]
-online. Alternatively, after <<build_from_source,building Kudu from source>>,
-you can additionally build the `doxygen` target (e.g., run `make doxygen`
-if using make) and use the locally generated API documentation by opening
+You can view the link:../cpp-client-api/index.html[C++ client API
+documentation] online. Alternatively, after
+link:installation.html#build_from_source[building Kudu from source], you can
+additionally build the `doxygen` target (e.g., run `make doxygen` if using
+make) and use the locally generated API documentation by opening
`docs/doxygen/client_api/html/index.html` file in your favorite Web browser.
NOTE: In order to build the `doxygen` target, it's necessary to have
@@ -699,9 +700,10 @@ you installed doxygen after building Kudu from source, you will need to run
targets.
.Java API Documentation
-You can view the link:../apidocs/index.html[Java API documentation] online. Alternatively,
-after <<build_java_client,building the Java client>>, Java API documentation is available
-in `java/kudu-client/target/apidocs/index.html`.
+You can view the link:../apidocs/index.html[Java API documentation] online.
+Alternatively, after link:installation.html#build_java_client[building the Java
+client], Java API documentation is available in
+`java/kudu-client/target/apidocs/index.html`.
// end::view_api[]
[[upgrade]]
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/prior_release_notes.adoc
----------------------------------------------------------------------
diff --git a/docs/prior_release_notes.adoc b/docs/prior_release_notes.adoc
index d03067c..00c618e 100644
--- a/docs/prior_release_notes.adoc
+++ b/docs/prior_release_notes.adoc
@@ -1573,8 +1573,6 @@ See also +++<a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20
for Kudu 0.10.0</a>+++ and +++<a href="https://github.com/apache/kudu/compare/0.9.1...0.10.0">Git
changes between 0.9.1 and 0.10.0</a>+++.
-To upgrade to Kudu 0.10.0, see <<rn_0.10.0_upgrade>>.
-
[[rn_0.10.0_incompatible_changes]]
=== Incompatible changes and deprecated APIs in 0.10.0
@@ -1775,8 +1773,6 @@ See also +++<a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20
for Kudu 0.9.0</a>+++ and +++<a href="https://github.com/apache/kudu/compare/0.8.0...0.9.0">Git
changes between 0.8.0 and 0.9.0</a>+++.
-To upgrade to Kudu 0.10.0, see <<rn_0.9.0_upgrade>>.
-
[[rn_0.9.0_incompatible_changes]]
=== Incompatible changes
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/quickstart.adoc
----------------------------------------------------------------------
diff --git a/docs/quickstart.adoc b/docs/quickstart.adoc
index 42d9a2b..3c3d83e 100644
--- a/docs/quickstart.adoc
+++ b/docs/quickstart.adoc
@@ -175,7 +175,7 @@ Fetched 1 row(s) in 5.75s
----
+
The created table uses a composite primary key. See
-<<kudu_impala_integration.adoc#kudu_impala,Kudu Impala Integration>> for a more detailed
+<<kudu_impala_integration.adoc#,Kudu Impala Integration>> for a more detailed
introduction to the extended SQL syntax for Impala.
== Read and Modify Data
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/schema_design.adoc
----------------------------------------------------------------------
diff --git a/docs/schema_design.adoc b/docs/schema_design.adoc
index 02d05ea..2d71c4e 100644
--- a/docs/schema_design.adoc
+++ b/docs/schema_design.adoc
@@ -35,7 +35,7 @@ effective schema design philosophies for Kudu, paying particular attention to
where they differ from approaches used for traditional RDBMS schemas.
At a high level, there are three concerns when creating Kudu tables:
-<<column-design,column design>>, <<primary-key,primary key design>>, and
+<<column-design,column design>>, <<primary-keys,primary key design>>, and
<<partitioning,partitioning design>>. Of these, only partitioning will be a new
concept for those familiar with traditional non-distributed relational
databases. The final sections discuss <<alter-schema,altering the schema>> of an
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/support/scripts/make_site.sh
----------------------------------------------------------------------
diff --git a/docs/support/scripts/make_site.sh b/docs/support/scripts/make_site.sh
index 8d7cefa..e645b6c 100755
--- a/docs/support/scripts/make_site.sh
+++ b/docs/support/scripts/make_site.sh
@@ -119,7 +119,7 @@ if [ -n "$OPT_JAVADOC" ]; then
fi
rm -Rf "$SITE_OUTPUT_DIR/$JAVADOC_SUBDIR"
- cp -au "$SOURCE_ROOT/java/target/site/$JAVADOC_SUBDIR" "$SITE_OUTPUT_DIR/"
+ cp -a "$SOURCE_ROOT/java/target/site/$JAVADOC_SUBDIR" "$SITE_OUTPUT_DIR/"
fi
if [ -n "$OPT_DOXYGEN" ]; then
http://git-wip-us.apache.org/repos/asf/kudu/blob/37a81b82/docs/transaction_semantics.adoc
----------------------------------------------------------------------
diff --git a/docs/transaction_semantics.adoc b/docs/transaction_semantics.adoc
index 9ed2739..f1fb301 100644
--- a/docs/transaction_semantics.adoc
+++ b/docs/transaction_semantics.adoc
@@ -31,11 +31,11 @@
****
This is a brief introduction to Kudu's transaction and consistency semantics. For an
in-depth technical exposition of most of what is mentioned here, and why it is correct,
-see the technical report <<1>>.
+see the technical report <<ht>>.
****
Kudu's transactional semantics and architecture are inspired by state-of-the-art
-systems such as Spanner <<2>> and Calvin <<3>>. Kudu builds upon decades of database
+systems such as Spanner <<spanner>> and Calvin <<fdt>>. Kudu builds upon decades of database
research. The core philosophy is to make the lives of developers easier by providing transactions with
simple, strong semantics, without sacrificing performance or the ability to tune to different
requirements.
@@ -74,8 +74,9 @@ may differ.
== Single tablet write operations
-Kudu employs _Multiversion Concurrency Control (MVCC)_ and the _Raft consensus_ algorithm <<4>>.
-Each write operation in Kudu must go through the tablet's leader.
+Kudu employs _Multiversion Concurrency Control (MVCC)_ and the _Raft consensus_
+algorithm <<consensus>>. Each write operation in Kudu must go through the
+tablet's leader.
. The leader acquires all locks for the rows that it will change.
. The leader assigns the write a timestamp before the write is submitted for
@@ -114,7 +115,7 @@ independent write operation with its own timestamp. However, the client API prov
the option to impose some constraints on the assigned timestamps and on how writes to
different tablets can be observed by clients.
-Kudu, like Spanner, was designed to be externally consistent <<5>>, preserving consistency
+Kudu, like Spanner, was designed to be externally consistent <<consistency>>, preserving consistency
when operations span multiple tablets and even multiple data centers. In practice this
means that, if a write operation changes item _x_ at tablet _A_, and a following write
operation changes item _y_ at tablet _B_, you might want to enforce that if
@@ -126,7 +127,7 @@ timestamps so that the causal relationship between them is captured.
.`CLIENT_PROPAGATED` Consistency
Kudu's default external consistency mode is called `CLIENT_PROPAGATED`.
-See <<1>> for an extensive explanation on how it works. In brief, this mode causes writes
+See <<ht>> for an extensive explanation on how it works. In brief, this mode causes writes
from _a single client_ to be automatically externally consistent. In the clickstream scenario
above, if the two clicks are submitted by different client instances, the application must
manually propagate timestamps from one client to the other for the causal relationship
@@ -276,8 +277,8 @@ frequently.
[bibliography]
== References
-- [[[1]]] David Alves, Todd Lipcon and Vijay Garg. Technical Report: HybridTime - Accessible Global Consistency with High Clock Uncertainty. April, 2014. http://users.ece.utexas.edu/~garg/pdslab/david/hybrid-time-tech-report-01.pdf
-- [[[2]]] James C. Corbett, Jeffrey Dean, Michael Epstein, Andrew Fikes, Christopher Frost, J. J. Furman, Sanjay Ghemawat, Andrey Gubarev, Christopher Heiser, Peter Hochschild, Wilson Hsieh, Sebastian Kanthak, Eugene Kogan, Hongyi Li, Alexander Lloyd, Sergey Melnik, David Mwaura, David Nagle, Sean Quinlan, Rajesh Rao, Lindsay Rolig, Yasushi Saito, Michal Szymaniak, Christopher Taylor, Ruth Wang, and Dale Woodford. 2012. Spanner: Google's globally-distributed database. In Proceedings of the 10th USENIX conference on Operating Systems Design and Implementation (OSDI'12). USENIX Association, Berkeley, CA, USA, 251-264.
-- [[[3]]] Alexander Thomson, Thaddeus Diamond, Shu-Chun Weng, Kun Ren, Philip Shao, and Daniel J. Abadi. 2012. Calvin: fast distributed transactions for partitioned database systems. In Proceedings of the 2012 ACM SIGMOD International Conference on Management of Data (SIGMOD '12). ACM, New York, NY, USA, 1-12. DOI=10.1145/2213836.2213838 http://doi.acm.org/10.1145/2213836.2213838
-- [[[4]]] Diego Ongaro and John Ousterhout. 2014. In search of an understandable consensus algorithm. In Proceedings of the 2014 USENIX conference on USENIX Annual Technical Conference (USENIX ATC'14), Garth Gibson and Nickolai Zeldovich (Eds.). USENIX Association, Berkeley, CA, USA, 305-320.
-- [[[5]]] Kwei-Jay Lin, "Consistency issues in real-time database systems," in System Sciences, 1989. Vol.II: Software Track, Proceedings of the Twenty-Second Annual Hawaii International Conference on , vol.2, no., pp.654-661 vol.2, 3-6 Jan 1989 doi: 10.1109/HICSS.1989.48069
+- [[[ht,1]]] David Alves, Todd Lipcon and Vijay Garg. Technical Report: HybridTime - Accessible Global Consistency with High Clock Uncertainty. April, 2014. http://users.ece.utexas.edu/~garg/pdslab/david/hybrid-time-tech-report-01.pdf
+- [[[spanner,2]]] James C. Corbett, Jeffrey Dean, Michael Epstein, Andrew Fikes, Christopher Frost, J. J. Furman, Sanjay Ghemawat, Andrey Gubarev, Christopher Heiser, Peter Hochschild, Wilson Hsieh, Sebastian Kanthak, Eugene Kogan, Hongyi Li, Alexander Lloyd, Sergey Melnik, David Mwaura, David Nagle, Sean Quinlan, Rajesh Rao, Lindsay Rolig, Yasushi Saito, Michal Szymaniak, Christopher Taylor, Ruth Wang, and Dale Woodford. 2012. Spanner: Google's globally-distributed database. In Proceedings of the 10th USENIX conference on Operating Systems Design and Implementation (OSDI'12). USENIX Association, Berkeley, CA, USA, 251-264.
+- [[[fdt,3]]] Alexander Thomson, Thaddeus Diamond, Shu-Chun Weng, Kun Ren, Philip Shao, and Daniel J. Abadi. 2012. Calvin: fast distributed transactions for partitioned database systems. In Proceedings of the 2012 ACM SIGMOD International Conference on Management of Data (SIGMOD '12). ACM, New York, NY, USA, 1-12. DOI=10.1145/2213836.2213838 http://doi.acm.org/10.1145/2213836.2213838
+- [[[consensus,4]]] Diego Ongaro and John Ousterhout. 2014. In search of an understandable consensus algorithm. In Proceedings of the 2014 USENIX conference on USENIX Annual Technical Conference (USENIX ATC'14), Garth Gibson and Nickolai Zeldovich (Eds.). USENIX Association, Berkeley, CA, USA, 305-320.
+- [[[consistency,5]]] Kwei-Jay Lin, "Consistency issues in real-time database systems," in System Sciences, 1989. Vol.II: Software Track, Proceedings of the Twenty-Second Annual Hawaii International Conference on , vol.2, no., pp.654-661 vol.2, 3-6 Jan 1989 doi: 10.1109/HICSS.1989.48069