This change includes the following:

* Restructures the landing page (_index.md) to simplify the layout and bring the table of contents to the left side
* Removes the `optional` keyword from examples in the editions/features.md topic
* In /editions/overview.md:
  * Clarifies that 2023 is the latest released edition
  * Adds missing `package` syntax from proto examples
  * Adds a reserved keyword to the proto examples to show the syntax difference between proto2/proto3 and editions
  * Corrects syntax for enums in proto examples
* Corrects the example from the `list_people` command’s unit tests in getting-started/gotutorial.md
* Replaces an outdated link to OKRs with a link to codelabs in /overview.md
* Adds information about `ruby_package` to /programming-guides/dos-donts.md
* Corrects misspellings in several topics
* Reorganizes the content in the presence table in /programming-guides/field_presence.md
* Corrects instances of `[[]` that should have been `[` throughout C++ API documentation
* Minor text changes in /cpp/arenas.md
* Removes some outdated references to `has_foo()` being proto2-only in /cpp/cpp-generated.md
* Adds information about `ruby_package` to /reference/ruby/ruby-generated.md
* Removes reference to cross-domain mixing of protobuf gencode and runtime from the external docs, since it applies only internally

PiperOrigin-RevId: 644492325
Change-Id: I651afbc2d6049818a1b579b4d0e779779cb06c57

content/_index.md

@@ -7,20 +7,21 @@ type = "docs"
 no_list = "true"
 +++
 
-<!--* css: "//depot/includes/suppress-nav.css" *-->
+## What Are Protocol Buffers?
 
-<style>
-.row .highlight {
-    margin-top: 2rem;
-    margin-right: 0;
-    margin-bottom: 0;
-    margin-left: 0;
-    padding: 0;
-}
-</style>
+Protocol buffers are Google's language-neutral, platform-neutral, extensible
+mechanism for serializing structured data – think XML, but smaller, faster, and
+simpler. You define how you want your data to be structured once, then you can
+use special generated source code to easily write and read your structured data
+to and from a variety of data streams and using a variety of languages.
+
+## Pick Your Favorite Language
+
+Protocol buffers support generated code in C++, C#, Dart, Go, Java,
+Kotlin,
+Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
 
-<div class="row">
-<div class="col-md">
+## Example Implementation
 
 ```proto
 message Person {
@@ -30,9 +31,7 @@ message Person {
 }
 ```
 
-<p class="caption">A proto definition.</>
-</div>
-<div class="col-md">
+**Figure 1.** A proto definition.
 
 ```java
 // Java code
@@ -43,12 +42,9 @@ Person john = Person.newBuilder()
     .build();
 output = new FileOutputStream(args[0]);
 john.writeTo(output);
-
 ```
 
-<p class="caption">Using a generated class to persist data.</p>
-</div>
-<div class="col-md">
+**Figure 2.** Using a generated class to persist data.
 
 ```cpp
 // C++ code
@@ -59,34 +55,9 @@ john.ParseFromIstream(&input);
 id = john.id();
 name = john.name();
 email = john.email();
-
 ```
 
-<p class="caption">Using a generated class to parse persisted data.</p>
-</div>
-</div>
-<div class="row">
-<div class="col-md">
-
-## What Are Protocol Buffers?
-
-Protocol buffers are Google's language-neutral, platform-neutral, extensible
-mechanism for serializing structured data – think XML, but smaller, faster, and
-simpler. You define how you want your data to be structured once, then you can
-use special generated source code to easily write and read your structured data
-to and from a variety of data streams and using a variety of languages.
-
-</div>
-<div class="col-md">
-
-## Pick Your Favorite Language
-
-Protocol buffers support generated code in C++, C#, Dart, Go, Java,
-Kotlin,
-Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
-
-</div>
-<div class="col-md">
+**Figure 3.** Using a generated class to parse persisted data.
 
 ## How Do I Start?
 
@@ -106,6 +77,3 @@ Objective-C, Python, and Ruby. With proto3, you can also work with PHP.
     chosen language.
   </li>
 </ol>
-
-</div>
-</div>

content/editions/features.md

@@ -285,7 +285,7 @@ edition = "2023";
 
 message Foo {
   message Bar {
-    optional int32 x = 1;
+    int32 x = 1;
     repeated int32 y = 2;
   }
   Bar bar = 1 [features.message_encoding = DELIMITED];
@@ -509,8 +509,8 @@ edition = "2023";
 import "google/protobuf/cpp_features.proto";
 
 message Foo {
-  optional string bar = 6;
-  optional string baz = 7 [features.(pb.cpp).string_type = CORD];
+  string bar = 6;
+  string baz = 7 [features.(pb.cpp).string_type = CORD];
 }
 ```
 

content/editions/overview.md

@@ -9,7 +9,7 @@ type = "docs"
 Protobuf Editions replace the proto2 and proto3 designations that we have used
 for Protocol Buffers. Instead of adding `syntax = "proto2"` or `syntax =
 "proto3"` at the top of proto definition files, you use an edition number, such
-as `edition = "2024"`, to specify the default behaviors your file will have.
+as `edition = "2023"`, to specify the default behaviors your file will have.
 Editions enable the language to evolve incrementally over time.
 
 Instead of the hardcoded behaviors that older versions have had, editions
@@ -22,6 +22,8 @@ the default behavior for the edition you've selected. You can also override your
 overrides. The [section later in this topic on lexical scoping](#scoping) goes
 into more detail on that.
 
+*The latest released edition is 2023.*
+
 ## Lifecycle of a Feature {#lifecycles}
 
 Editions provide the fundamental increments for the lifecycle of a feature.
@@ -93,6 +95,8 @@ Prototiller tool to change the definition files to use Protobuf Editions syntax.
 // proto2 file
 syntax = "proto2";
 
+package com.example;
+
 message Player {
   // in proto2, optional fields have explicit presence
   optional string name = 1;
@@ -110,6 +114,8 @@ message Player {
 
   // in proto2 enums are closed
   optional Handed handed = 4;
+
+  reserved "gender";
 }
 ```
 
@@ -119,6 +125,8 @@ message Player {
 // Edition version of proto2 file
 edition = "2023";
 
+package com.example;
+
 message Player {
   // fields have explicit presence, so no explicit setting needed
   string name = 1;
@@ -137,6 +145,8 @@ message Player {
   }
 
   Handed handed = 4;
+
+  reserved gender;
 }
 ```
 
@@ -155,6 +165,8 @@ Prototiller tool to change the definition files to use Protobuf Editions syntax.
 // proto3 file
 syntax = "proto3";
 
+package com.example;
+
 message Player {
   // in proto3, optional fields have explicit presence
   optional string name = 1;
@@ -172,6 +184,8 @@ message Player {
 
   // in proto3 enums are open
   optional Handed handed = 4;
+
+  reserved "gender";
 }
 ```
 
@@ -181,6 +195,8 @@ message Player {
 // Editions version of proto3 file
 edition = "2023";
 
+package com.example;
+
 message Player {
   // fields have explicit presence, so no explicit setting needed
   string name = 1;
@@ -197,6 +213,8 @@ message Player {
   }
 
   Handed handed = 4;
+
+  reserved gender;
 }
 ```
 
@@ -229,16 +247,16 @@ message Person {
   int32 id = 2 [features.presence = IMPLICIT];
 
   enum Pay_Type {
-    PAY_TYPE_UNSPECIFIED = 1,
-    PAY_TYPE_SALARY = 2,
-    PAY_TYPE_HOURLY = 3
+    PAY_TYPE_UNSPECIFIED = 1;
+    PAY_TYPE_SALARY = 2;
+    PAY_TYPE_HOURLY = 3;
   }
 
   enum Employment {
     option features.enum_type = OPEN;
-    EMPLOYMENT_UNSPECIFIED = 0,
-    EMPLOYMENT_FULLTIME = 1,
-    EMPLOYMENT_PARTTIME = 2,
+    EMPLOYMENT_UNSPECIFIED = 0;
+    EMPLOYMENT_FULLTIME = 1;
+    EMPLOYMENT_PARTTIME = 2;
   }
   Employment employment = 4;
 }
@@ -270,9 +288,9 @@ definition files, and vice versa:
 syntax = "proto2";
 
 enum Employment {
-  EMPLOYMENT_UNSPECIFIED = 0,
-  EMPLOYMENT_FULLTIME = 1,
-  EMPLOYMENT_PARTTIME = 2,
+  EMPLOYMENT_UNSPECIFIED = 0;
+  EMPLOYMENT_FULLTIME = 1;
+  EMPLOYMENT_PARTTIME = 2;
 }
 ```
 

content/getting-started/gotutorial.md

@@ -232,7 +232,7 @@ p := pb.Person{
     Name:  "John Doe",
     Email: "[email protected]",
     Phones: []*pb.Person_PhoneNumber{
-        {Number: "555-4321", Type: pb.Person_PHONE_TYPE_HOME},
+        {Number: "555-4321", Type: pb.PhoneType_PHONE_TYPE_HOME},
     },
 }
 ```

content/overview.md

@@ -305,3 +305,4 @@ protobuf developers and users,
 ## Additional Resources {#additional-resources}
 
 *   [Protocol Buffers GitHub](https://github.com/protocolbuffers/protobuf/)
+*   [Codelabs](/getting-started/codelabs)

content/programming-guides/dos-donts.md

@@ -196,6 +196,9 @@ For example:
     https://google.github.io/styleguide/cppguide.html#Namespace_Names.
     If these style guides conflict, use `java_package` for Java.
 
+*   `ruby_package` should be in the form `Foo::Bar::Baz` rather than
+    `Foo.Bar.Baz`.
+
 <a id="never-use-text-format-messages-for-interchange"></a>
 
 ## **Don't** use Text Format Messages for Interchange {#text-format-interchange}

content/programming-guides/enum.md

@@ -49,7 +49,7 @@ question:
 
 ## Implications of *Closed* Enums
 
-The behavior of *closed* enums has unexpected consquences when parsing a
+The behavior of *closed* enums has unexpected consequences when parsing a
 repeated field. When a `repeated Enum` field is parsed all unknown values will
 be placed in the
 [unknown field](/programming-guides/proto3/#unknowns)

content/programming-guides/field_presence.md

@@ -157,13 +157,13 @@ for generated APIs and using dynamic reflection):
 Field type                                   | `optional` | Explicit Presence
 -------------------------------------------- | ---------- | -----------------
 Singular numeric (integer or floating point) | No         |
-Singular enum                                | No         |
-Singular string or bytes                     | No         |
 Singular numeric (integer or floating point) | Yes        | ✔️
+Singular enum                                | No         |
 Singular enum                                | Yes        | ✔️
+Singular string or bytes                     | No         |
 Singular string or bytes                     | Yes        | ✔️
-Singular message                             | Yes        | ✔️
 Singular message                             | No         | ✔️
+Singular message                             | Yes        | ✔️
 Repeated                                     | N/A        |
 Oneofs                                       | N/A        | ✔️
 Maps                                         | N/A        |

content/programming-guides/proto2.md

@@ -1939,8 +1939,8 @@ Here are a few of the most commonly used options:
         message types. This code is highly optimized.
     *   `CODE_SIZE`: The protocol buffer compiler will generate minimal classes
         and will rely on shared, reflection-based code to implement
-        serialialization, parsing, and various other operations. The generated
-        code will thus be much smaller than with `SPEED`, but operations will be
+        serialization, parsing, and various other operations. The generated code
+        will thus be much smaller than with `SPEED`, but operations will be
         slower. Classes will still implement exactly the same public API as they
         do in `SPEED` mode. This mode is most useful in apps that contain a very
         large number of `.proto` files and do not need all of them to be

content/programming-guides/proto3.md

@@ -1487,8 +1487,8 @@ Here are a few of the most commonly used options:
         message types. This code is highly optimized.
     *   `CODE_SIZE`: The protocol buffer compiler will generate minimal classes
         and will rely on shared, reflection-based code to implement
-        serialialization, parsing, and various other operations. The generated
-        code will thus be much smaller than with `SPEED`, but operations will be
+        serialization, parsing, and various other operations. The generated code
+        will thus be much smaller than with `SPEED`, but operations will be
         slower. Classes will still implement exactly the same public API as they
         do in `SPEED` mode. This mode is most useful in apps that contain a very
         large number of `.proto` files and do not need all of them to be

content/reference/cpp/api-docs/google.protobuf.arena.md

@@ -49,7 +49,7 @@ type = "docs"
 <p>This function also accepts any type T that satisfies the arena message allocation protocol, documented above. </p>
 </div> <hr><h3 id="Arena.Create.details"><code>template static PROTOBUF_NDEBUG_INLINE T * <br>&nbsp;&nbsp;&nbsp;&nbsp;Arena::Create(<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href='#Arena'>Arena</a> * arena,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Args &amp;&amp;... args)</code></h3><div style="margin-left: 16px"><p>API to create any objects on the arena. </p><p>Note that only the object will be created on the arena; the underlying ptrs (in case of a proto2 message) will be still heap allocated. Proto messages should usually be allocated with <a href='#Arena.CreateMessage'>CreateMessage&lt;T&gt;()</a> instead.</p>
 <p>Note that even if T satisfies the arena message construction protocol (InternalArenaConstructable_ trait and optional DestructorSkippable_ trait), as described above, this function does not follow the protocol; instead, it treats T as a black-box type, just as if it did not have these traits. Specifically, T's constructor arguments will always be only those passed to <a href='#Arena.Create'>Create&lt;T&gt;()</a> &ndash; no additional arena pointer is implicitly added. Furthermore, the destructor will always be called at arena destruction time (unless the destructor is trivial). Hence, from T's point of view, it is as if the object were allocated on the heap (except that the underlying memory is obtained from the arena). </p>
-</div> <hr><h3 id="Arena.CreateArray.details"><code>template static PROTOBUF_NDEBUG_INLINE T * <br>&nbsp;&nbsp;&nbsp;&nbsp;Arena::CreateArray(<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href='#Arena'>Arena</a> * arena,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t num_elements)</code></h3><div style="margin-left: 16px"><p>Create an array of object type T on the arena <i>without</i> invoking the constructor of T. </p><p>If <code>arena</code> is null, then the return value should be freed with <code>delete[[]] x;</code> (or <code>::operator delete[[]](x);</code>). To ensure safe uses, this function checks at compile time (when compiled as C++11) that T is trivially default-constructible and trivially destructible. </p>
+</div> <hr><h3 id="Arena.CreateArray.details"><code>template static PROTOBUF_NDEBUG_INLINE T * <br>&nbsp;&nbsp;&nbsp;&nbsp;Arena::CreateArray(<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href='#Arena'>Arena</a> * arena,<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t num_elements)</code></h3><div style="margin-left: 16px"><p>Create an array of object type T on the arena <i>without</i> invoking the constructor of T. </p><p>If <code>arena</code> is null, then the return value should be freed with <code>delete[] x;</code> (or <code>::operator delete[](x);</code>). To ensure safe uses, this function checks at compile time (when compiled as C++11) that T is trivially default-constructible and trivially destructible. </p>
 </div> <hr><h3 id="Arena.GetArena.details"><code>template static <a href='#Arena'>Arena</a> * Arena::GetArena(<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const T * value)</code></h3><div style="margin-left: 16px"><p>Retrieves the arena associated with |value| if |value| is an arena-capable message, or NULL otherwise. </p><p>If possible, the call resolves at compile time. Note that we can often devirtualize calls to <code>value-&gt;<a href='#Arena.GetArena'>GetArena()</a></code> so usually calling this method is unnecessary. </p>
 </div><h2 id="Arena.InternalHelper">template class Arena::InternalHelper</h2><p><code>#include &lt;<a href="#">google/protobuf/arena.h</a>&gt;<br>namespace <a href="#google.protobuf">google::protobuf</a><br><br>template &lt;typename &gt;</code></p><p></p><table><tr><th colspan="2"><h3 style="margin-top: 4px">Members</h3></th></tr><tr><td style="border-right-width: 0px; text-align: right;"><code>static <a href='#Arena'>Arena</a> *</code></td><td style="border-left-width: 0px"id="Arena.InternalHelper.GetOwningArena"><div style="padding-left: 16px; text-indent: -16px"><code><b>GetOwningArena</b>(const T * p)</code></div><div style="font-style: italic; margin-top: 4px; margin-left: 16px;">Provides access to protected GetOwningArena to generated messages. </div></td></tr><tr><td style="border-right-width: 0px; text-align: right;"><code>static <a href='#Arena'>Arena</a> *</code></td><td style="border-left-width: 0px"id="Arena.InternalHelper.GetArenaForAllocation"><div style="padding-left: 16px; text-indent: -16px"><code><b>GetArenaForAllocation</b>(const T * p)</code></div><div style="font-style: italic; margin-top: 4px; margin-left: 16px;">Provides access to protected GetArenaForAllocation to generated messages. </div></td></tr></table><h2 id="Arena.is_arena_constructable">template struct Arena::is_arena_constructable</h2><p><code>#include &lt;<a href="#">google/protobuf/arena.h</a>&gt;<br>namespace <a href="#google.protobuf">google::protobuf</a><br><br>template &lt;typename &gt;</code></p><p>Helper typetraits that indicates support for arenas in a type T at compile time. </p><p>This is public only to allow construction of higher-level templated utilities.</p>
 <p>is_arena_constructable&lt;T&gt;::value is true if the message type T has arena support enabled, and false otherwise.</p>

content/reference/cpp/api-docs/google.protobuf.compiler.command_line_interface.md

@@ -8,7 +8,7 @@ type = "docs"
 
 <p><code>#include &lt;google/protobuf/compiler/command_line_interface.h&gt;<br>namespace <a href="#google.protobuf.compiler">google::protobuf::compiler</a></code></p><p>Implements the Protocol Compiler front-end such that it may be reused by custom compilers written to support other languages. </p><table width="100%"><tr><th colspan="2"><h3 style="margin-top: 4px">Classes in this file</h3></th></tr><tr><td><div><code><a href="#CommandLineInterface">CommandLineInterface</a></code></div><div style="font-style: italic; margin-top: 4px; margin-left: 16px;">This class implements the command-line interface to the protocol compiler. </div></td></tr></table><h2 id="CommandLineInterface">class CommandLineInterface</h2><p><code>#include &lt;<a href="#">google/protobuf/compiler/command_line_interface.h</a>&gt;<br>namespace <a href="#google.protobuf.compiler">google::protobuf::compiler</a></code></p><p>This class implements the command-line interface to the protocol compiler. </p><p>It is designed to make it very easy to create a custom protocol compiler supporting the languages of your choice. For example, if you wanted to create a custom protocol compiler binary which includes both the regular C++ support plus support for your own custom output "Foo", you would write a class "FooGenerator" which implements the <a href='google.protobuf.compiler.code_generator#CodeGenerator'>CodeGenerator</a> interface, then write a main() procedure like this:</p>
 
-<pre>int main(int argc, char* argv[[]]) {
+<pre>int main(int argc, char* argv[]) {
   google::protobuf::compiler::CommandLineInterface cli;
 
   // Support generation of C++ source and headers.
@@ -54,7 +54,7 @@ type = "docs"
 </div> <hr><h3 id="CommandLineInterface.AllowPlugins.details"><code>void CommandLineInterface::AllowPlugins(<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const std::string &amp; exe_name_prefix)</code></h3><div style="margin-left: 16px"><p>Enables "plugins". </p><p>In this mode, if a command-line flag ends with "_out" but does not match any registered generator, the compiler will attempt to find a "plugin" to implement the generator. Plugins are just executables. They should live somewhere in the PATH.</p>
 <p>The compiler determines the executable name to search for by concatenating exe_name_prefix with the unrecognized flag name, removing "_out". So, for example, if exe_name_prefix is "protoc-" and you pass the flag &ndash;foo_out, the compiler will try to run the program "protoc-gen-foo".</p>
 <p>The plugin program should implement the following usage: </p>
-<pre>plugin [[]--out=OUTDIR] [[]--parameter=PARAMETER] PROTO_FILES &lt; DESCRIPTORS</pre>
+<pre>plugin [--out=OUTDIR] [--parameter=PARAMETER] PROTO_FILES &lt; DESCRIPTORS</pre>
 <p>&ndash;out indicates the output directory (as passed to the &ndash;foo_out parameter); if omitted, the current directory should be used. &ndash;parameter gives the generator parameter, if any was provided (see below). The PROTO_FILES list the .proto files which were given on the compiler command-line; these are the files for which the plugin is expected to generate output code. Finally, DESCRIPTORS is an encoded FileDescriptorSet (as defined in descriptor.proto). This is piped to the plugin's stdin. The set will include descriptors for all the files listed in PROTO_FILES as well as all files that they import. The plugin MUST NOT attempt to read the PROTO_FILES directly &ndash; it must use the FileDescriptorSet.</p>
 <p>The plugin should generate whatever files are necessary, as code generators normally do. It should write the names of all files it generates to stdout. The names should be relative to the output directory, NOT absolute names or relative to the current directory. If any errors occur, error messages should be written to stderr. If an error is fatal, the plugin should exit with a non-zero exit code.</p>
 <p>Plugins can have generator parameters similar to normal built-in generators. Extra generator parameters can be passed in via a matching "_opt" parameter. For example: </p>