Reorg the book (#7952)

* Move application-oriented docs

* Reorg the book

* Fix build

* Apply review feedback

* verb-noun

book/build-cli-usage.sh

@@ -5,9 +5,9 @@ cd "$(dirname "$0")"
 
 usage=$(cargo -q run -p solana-cli -- -C ~/.foo --help | sed 's|'"$HOME"'|~|g')
 
-out=${1:-src/api-reference/cli.md}
+out=${1:-src/cli/usage.md}
 
-cat src/api-reference/.cli.md.header > "$out"
+cat src/cli/.usage.md.header > "$out"
 
 section() {
   declare mark=${2:-"###"}

book/src/SUMMARY.md

@@ -1,12 +1,31 @@
 # Table of contents
 
-* [The Solana Codebase](introduction.md)
+* [Introduction](introduction.md)
-* [Building from Source](getting-started/README.md)
+* [Using Solana from the Command-line](cli/README.md)
-  * [Example Client: Web Wallet](getting-started/webwallet.md)
+  * [Command-line Usage](cli/usage.md)
-* [Programming Model](programs/README.md)
+  * [Paper Wallet](paper-wallet/README.md)
-  * [Example: Tic-Tac-Toe](programs/tictactoe.md)
+    * [Installation](paper-wallet/installation.md)
-  * [Drones](programs/drones.md)
+    * [Paper Wallet Usage](paper-wallet/usage.md)
-* [A Solana Cluster](cluster/README.md)
+  * [Offline Signing](offline-signing/README.md)
+    * [Durable Transaction Nonces](offline-signing/durable-nonce.md)
+* [Developing Applications](apps/README.md)
+  * [Example: Web Wallet](apps/webwallet.md)
+  * [Example: Tic-Tac-Toe](apps/tictactoe.md)
+  * [Drones](apps/drones.md)
+  * [Anatomy of a Transaction](transaction.md)
+  * [JSON RPC API](apps/jsonrpc-api.md)
+  * [JavaScript API](apps/javascript-api.md)
+* [Running a Validator](running-validator/README.md)
+  * [Validator Requirements](running-validator/validator-reqs.md)
+  * [Choosing a Testnet](running-validator/validator-testnet.md)
+  * [Installing the Validator Software](running-validator/validator-software.md)
+  * [Starting a Validator](running-validator/validator-start.md)
+  * [Staking](running-validator/validator-stake.md)
+  * [Monitoring a Validator](running-validator/validator-monitor.md)
+  * [Publishing Validator Info](running-validator/validator-info.md)
+  * [Troubleshooting](running-validator/validator-troubleshoot.md)
+* [Running an Archiver](running-archiver.md)
+* [Understanding Solana's Architecture](cluster/README.md)
   * [Synchronization](cluster/synchronization.md)
   * [Leader Rotation](cluster/leader-rotation.md)
   * [Fork Generation](cluster/fork-generation.md)
@@ -22,41 +41,8 @@
   * [Blockstore](validator/blockstore.md)
   * [Gossip Service](validator/gossip.md)
   * [The Runtime](validator/runtime.md)
-* [Anatomy of a Transaction](transaction.md)
+* [Building from Source](building-from-source.md)
-* [Running a Validator](running-validator/README.md)
-  * [Validator Requirements](running-validator/validator-reqs.md)
-  * [Choosing a Testnet](running-validator/validator-testnet.md)
-  * [Installing the Validator Software](running-validator/validator-software.md)
-  * [Starting a Validator](running-validator/validator-start.md)
-  * [Staking](running-validator/validator-stake.md)
-  * [Monitoring a Validator](running-validator/validator-monitor.md)
-  * [Publishing Validator Info](running-validator/validator-info.md)
-  * [Troubleshooting](running-validator/validator-troubleshoot.md)
-* [Running an Archiver](running-archiver.md)
-* [Paper Wallet](paper-wallet/README.md)
-  * [Installation](paper-wallet/installation.md)
-  * [Paper Wallet Usage](paper-wallet/usage.md)
-* [Offline Signing](offline-signing/README.md)
-  * [Durable Transaction Nonces](offline-signing/durable-nonce.md)
-* [API Reference](api-reference/README.md)
-  * [JSON RPC API](api-reference/jsonrpc-api.md)
-  * [JavaScript API](api-reference/javascript-api.md)
-  * [solana CLI](api-reference/cli.md)
 * [Terminology](terminology.md)
-* [Accepted Design Proposals](proposals/README.md)
-  * [Ledger Replication](proposals/ledger-replication-to-implement.md)
-  * [Secure Vote Signing](proposals/vote-signing-to-implement.md)
-  * [Cluster Test Framework](proposals/cluster-test-framework.md)
-  * [Validator](proposals/validator-proposal.md)
-  * [Simple Payment and State Verification](proposals/simple-payment-and-state-verification.md)
-  * [Cross-Program Invocation](proposals/cross-program-invocation.md)
-  * [Inter-chain Transaction Verification](proposals/interchain-transaction-verification.md)
-  * [Snapshot Verification](proposals/snapshot-verification.md)
-  * [Bankless Leader](proposals/bankless-leader.md)
-  * [Slashing](proposals/slashing.md)
-  * [Tick Verification](proposals/tick-verification.md)
-  * [Block Confirmation](proposals/block-confirmation.md)
-  * [ABI Management](proposals/abi-management.md)
 * [Implemented Design Proposals](implemented-proposals/README.md)
   * [Cluster Software Installation and Updates](implemented-proposals/installer.md)
   * [Cluster Economics](implemented-proposals/ed_overview/README.md)
@@ -89,3 +75,17 @@
   * [Validator Timestamp Oracle](implemented-proposals/validator-timestamp-oracle.md)
   * [Commitment](implemented-proposals/commitment.md)
   * [Snapshot Verification](implemented-proposals/snapshot-verification.md)
+* [Accepted Design Proposals](proposals/README.md)
+  * [Ledger Replication](proposals/ledger-replication-to-implement.md)
+  * [Secure Vote Signing](proposals/vote-signing-to-implement.md)
+  * [Cluster Test Framework](proposals/cluster-test-framework.md)
+  * [Validator](proposals/validator-proposal.md)
+  * [Simple Payment and State Verification](proposals/simple-payment-and-state-verification.md)
+  * [Cross-Program Invocation](proposals/cross-program-invocation.md)
+  * [Inter-chain Transaction Verification](proposals/interchain-transaction-verification.md)
+  * [Snapshot Verification](proposals/snapshot-verification.md)
+  * [Bankless Leader](proposals/bankless-leader.md)
+  * [Slashing](proposals/slashing.md)
+  * [Tick Verification](proposals/tick-verification.md)
+  * [Block Confirmation](proposals/block-confirmation.md)
+  * [ABI Management](proposals/abi-management.md)

book/src/api-reference/README.md

@@ -1,4 +0,0 @@
-# API Reference
-
-The following sections contain API references material you may find useful when developing applications utilizing a Solana cluster.
-

book/src/apps/README.md

@@ -1,6 +1,6 @@
 # Programming Model
 
-A client _app_ interacts with a Solana cluster by sending it _transactions_ with one or more _instructions_. The Solana _runtime_ passes those instructions to user-contributed _programs_. An instruction might, for example, tell a program to transfer _lamports_ from one _account_ to another or create an interactive contract that governs how lamports are transfered. Instructions are executed sequentially and atomically. If any instruction is invalid, any changes made within the transaction are discarded.
+An _app_ interacts with a Solana cluster by sending it _transactions_ with one or more _instructions_. The Solana _runtime_ passes those instructions to user-contributed _programs_. An instruction might, for example, tell a program to transfer _lamports_ from one _account_ to another or create an interactive contract that governs how lamports are transfered. Instructions are executed sequentially and atomically. If any instruction is invalid, any changes made within the transaction are discarded.
 
 ### Accounts and Signatures
 

book/src/building-from-source.md

@@ -1,4 +1,4 @@
-# Getting Started
+# Building from Source
 
 The Solana git repository contains all the scripts you might need to spin up your own local testnet. Depending on what you're looking to achieve, you may want to run a different variation, as the full-fledged, performance-enhanced multinode testnet is considerably more complex to set up than a Rust-only, singlenode testnode. If you are looking to develop high-level features, such as experimenting with smart contracts, save yourself some setup headaches and stick to the Rust-only singlenode demo. If you're doing performance optimization of the transaction pipeline, consider the enhanced singlenode demo. If you're doing consensus work, you'll need at least a Rust-only multinode demo. If you want to reproduce our TPS metrics, run the enhanced multinode demo.
 

book/src/cli/README.md

@@ -0,0 +1,5 @@
+# Using Solana from the Command-line
+
+This chapter describes the command-line tools for interacting with Solana. One
+could use these tools to send payments, stake validators, and check account
+balances.