pw_string: Revise front page content

Change-Id: Iacd4ca3d947145e229f244f8563fde2f3fc2f97d
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/140490
Reviewed-by: Kayce Basques <kayce@google.com>
Commit-Queue: Chad Norvell <chadnorvell@google.com>

2 files changed, 77 insertions, 83 deletions

diff --git a/pw_string/docs.rst b/pw_string/docs.rst
index 299906ccc..1e7ab58b2 100644
--- a/pw_string/docs.rst
+++ b/pw_string/docs.rst
@@ -51,116 +51,76 @@ pw_string
 
    Check out :ref:`module-pw_string-guide` for more code samples.
 
-----------
-Background
-----------
 String manipulation on embedded systems can be surprisingly challenging.
-C strings are light weight but come with many pitfalls for those who don't know
-the standard library deeply. C++ provides string classes that are safe and easy
-to use, but they consume way too much code space and are designed to be used
-with dynamic memory allocation.
 
-Embedded systems need string functionality that is both safe and suitable for
-resource-constrained platforms.
+- **C strings?** They're light-weight but come with many pitfalls for those who
+  don't know the standard library deeply.
 
-------------
-Our solution
-------------
-``pw_string`` provides safe string handling functionality with an API that
-closely matches that of ``std::string``, but without dynamic memory allocation
-and with a *much* smaller :ref:`binary size impact <module-pw_string-size-reports>`.
+- **C++ strings?** STL string classes are safe and easy to use, but they consume
+  way too much code space and are designed to be used with dynamic memory
+  allocation.
 
----------------
-Who this is for
----------------
-``pw_string`` is useful any time you need to handle strings in embedded C++.
+- **Roll your own strings?** You don't have time! You have a product to ship!
+
+Embedded systems need string functionality that is both *safe* and *suitable*
+for resource-constrained platforms.
+
+.. rst-class:: key-text
+
+   ``pw_string`` provides safe string handling functionality with an API that
+   closely matches that of ``std::string``, but without dynamic memory
+   allocation and with a *much* smaller :ref:`binary size impact<module-pw_string-size-reports>`.
 
 --------------------
 Is it right for you?
 --------------------
+.. rst-class:: key-text
+
+   ``pw_string`` is useful any time you need to handle strings in embedded C++.
+
 If your project written in C, ``pw_string`` is not a good fit since we don't
 currently expose a C API.
 
-For larger platforms where code space isn't in short supply and dynamic memory
-allocation isn't a problem, you may find that ``std::string`` meets your needs.
+On the other hand, for larger platforms where code space isn't in short supply
+and dynamic memory allocation isn't a problem, you may find that ``std::string``
+meets your needs.
 
 .. tip::
    ``pw_string`` works just as well on larger embedded platforms and host
-   systems. Using ``pw_string`` even when you might get away with ``std:string``
+   systems. Using ``pw_string`` even when you could get away with ``std:string``
    gives you the flexibility to move to smaller platforms later with much less
    rework.
 
-Here are some size reports that may affect whether ``pw_string`` is right for
-you.
-
-.. _module-pw_string-size-reports:
-
-Size comparison: snprintf versus pw::StringBuilder
---------------------------------------------------
-:cpp:type:`pw::StringBuilder` is safe, flexible, and results in much smaller
-code size than using ``std::ostringstream``. However, applications sensitive to
-code size should use :cpp:type:`pw::StringBuilder` with care.
-
-The fixed code size cost of :cpp:type:`pw::StringBuilder` is significant, though
-smaller than ``std::snprintf``. Using :cpp:type:`pw::StringBuilder`'s ``<<`` and
-``append`` methods exclusively in place of ``snprintf`` reduces code size, but
-``snprintf`` may be difficult to avoid.
-
-The incremental code size cost of :cpp:type:`pw::StringBuilder` is comparable to
-``snprintf`` if errors are handled. Each argument to
-:cpp:type:`pw::StringBuilder`'s ``<<`` method expands to a function call, but
-one or two :cpp:type:`pw::StringBuilder` appends may have a smaller code size
-impact than a single ``snprintf`` call.
-
-.. include:: string_builder_size_report
-
-Size comparison: snprintf versus pw::string::Format
----------------------------------------------------
-The ``pw::string::Format`` functions have a small, fixed code size
-cost. However, relative to equivalent ``std::snprintf`` calls, there is no
-incremental code size cost to using ``pw::string::Format``.
-
-.. include:: format_size_report
-
-Roadmap
--------
-* StringBuilder's fixed size cost can be dramatically reduced by limiting
-  support for 64-bit integers.
-* Consider integrating with the tokenizer module.
-
-Compatibility
--------------
-C++17, C++14 (:cpp:type:`pw::InlineString`)
-
 .. _module-pw_string-get-started:
 
 ---------------
-Getting started
+Getting Started
 ---------------
 
-GN
---
+.. tabs::
+
+   .. group-tab:: GN
+
+      Add ``$dir_pw_string`` to the ``deps`` list in your ``pw_executable()``
+      build target:
 
-Add ``$dir_pw_string`` to the ``deps`` list in your ``pw_executable()`` build
-target:
+      .. code::
 
-.. code::
+         pw_executable("...") {
+           # ...
+           deps = [
+             # ...
+             "$dir_pw_string",
+             # ...
+           ]
+         }
 
-  pw_executable("...") {
-    # ...
-    deps = [
-      # ...
-      "$dir_pw_string",
-      # ...
-    ]
-  }
+      See `//source/BUILD.gn <https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/main/source/BUILD.gn>`_
+      in the Pigweed Sample Project for an example.
 
-See `//source/BUILD.gn <https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/main/source/BUILD.gn>`_
-in the Pigweed Sample Project for an example.
+   .. group-tab:: Zephyr
 
-Zephyr
-------
-Add ``CONFIG_PIGWEED_STRING=y`` to the Zephyr project's configuration.
+      Add ``CONFIG_PIGWEED_STRING=y`` to the Zephyr project's configuration.
 
 -------
 Roadmap
diff --git a/pw_string/guide.rst b/pw_string/guide.rst
index 7e3d93c62..fe80849f9 100644
--- a/pw_string/guide.rst
+++ b/pw_string/guide.rst
@@ -254,3 +254,37 @@ This example shows how to specialize ``pw::ToString``:
   }
 
   }  // namespace pw
+
+.. _module-pw_string-size-reports:
+
+Saving code space by replacing ``snprintf``
+===========================================
+The C standard library function ``snprintf`` is commonly used for string
+formatting. However, it isn't optimized for embedded systems, and using it will
+bring in a lot of other standard library code that will inflate your binary
+size.
+
+Size comparison: snprintf versus pw::StringBuilder
+--------------------------------------------------
+The fixed code size cost of :cpp:type:`pw::StringBuilder` is smaller than
+that of ``std::snprintf``. Using only :cpp:type:`pw::StringBuilder`'s ``<<`` and
+``append`` methods instead of ``snprintf`` leads to significant code size
+reductions.
+
+However, there are cases when the incremental code size cost of
+:cpp:type:`pw::StringBuilder` is similar to that of ``snprintf``. For example,
+each argument to :cpp:type:`pw::StringBuilder`'s ``<<`` method expands to a
+function call, but one or two :cpp:type:`pw::StringBuilder` appends may still
+have a smaller code size impact than a single ``snprintf`` call. Using
+:cpp:type:`pw::StringBuilder` error handling will also impact code size in a
+way that is comparable to ``snprintf``.
+
+.. include:: string_builder_size_report
+
+Size comparison: snprintf versus pw::string::Format
+---------------------------------------------------
+The ``pw::string::Format`` functions have a small, fixed code size
+cost. However, relative to equivalent ``std::snprintf`` calls, there is no
+incremental code size cost to using ``pw::string::Format``.
+
+.. include:: format_size_report