build the docs: move to getting started so it will render on GitHub readme

README.adoc

@@ -1346,6 +1346,43 @@ The following subjects are particularly important:
 * <<tracing>>
 * <<baremetal-gdb-step-debug>>
 
+=== Build the documentation
+
+You don't need to depend on GitHub.
+
+For a quick and dirty build, install https://asciidoctor.org/[Asciidoctor] however you like and build:
+
+....
+asciidotor README.adoc
+xdg-open README.html
+....
+
+For development, you will want to do a more controlled build with extra error checking as follows.
+
+For the initial build do:
+
+....
+./build --download-dependencies docs
+....
+
+which also downloads build dependencies.
+
+Then the following times just to the faster:
+
+....
+./build-doc
+....
+
+Source: link:build-doc[]
+
+The HTML output is located at:
+
+....
+xdg-open out/README.html
+....
+
+More information about our documentation internals can be found at: xref:documentation[xrefstyle=full]
+
 [[gdb]]
 == GDB step debug
 
@@ -16207,40 +16244,9 @@ To get a list of all global options that you can use, try:
 
 but note that this does not include script specific options.
 
-=== Build the documentation
+=== Documentation
 
-You don't need to depend on GitHub.
+To learn how to build the documentation see: xref:build-the-documentation[xrefstyle=full].
-
-For a quick and dirty build, install https://asciidoctor.org/[Asciidoctor] however you like and build:
-
-....
-asciidotor README.adoc
-xdg-open README.html
-....
-
-For development, you will want to do a more controlled build with extra error checking as follows.
-
-For the initial build do:
-
-....
-./build --download-dependencies docs
-....
-
-which also downloads build dependencies.
-
-Then the following times just to the faster:
-
-....
-./build-doc
-....
-
-Source: link:build-doc[]
-
-The HTML output is located at:
-
-....
-xdg-open out/README.html
-....
 
 ==== Documentation verification