Rollup merge of documentation improvements

Merge (full or partial) of !173, !219, and !303.

Signed-off-by: Rahix <rahix@rahix.de>

Documentation/how-to-build.rst

@@ -144,6 +144,15 @@ In order to do a rebuild you can issue a clean command to ninja via
 
 Otherwise, rerunning ``./bootstrap.sh`` will also clean the build-directory.
 
+.. note::
+
+   **macOS**: If ``strip`` fails to work on the freshly compiled ``mpy-cross``:
+   "strip: object: (...)/lib/micropython/micropython/mpy-cross/mpy-cross
+   malformed object (unknown load command 9)", you a likely not using the
+   `strip` that matches to your ``clang``. Do ``which strip && which clang``,
+   and if the paths don't match, clean up your PATHs, or as a quick hack,
+   create a symlink for strip.
+
 .. note::
 
    If you try to flash pycardium_epicardium.bin (renamed to card10.bin) 
@@ -152,4 +161,4 @@ Otherwise, rerunning ``./bootstrap.sh`` will also clean the build-directory.
    was >1MB. This was caused by the ``tr`` tool in the build process 
    (it's supposed to create a large file with 0xff in it) - this requires the 
    LC_ALL environment variable to be not set, or set to "C" 
-   (but not UTF8 or similar).
\ No newline at end of file
+   (but not UTF8 or similar).

Documentation/overview.rst

@@ -48,13 +48,15 @@ Pycardium, take a look at the :ref:`pycardium_guide` guide.
 L0dables
 --------
 Next to Pycardium, other bare-metal code can also run on core 1.  For example,
-a Rustcardium or C-cardium.  These l0dables must be compiled using our special
+a `Rustcardium`_ or C-cardium.  These l0dables must be compiled using our special
 linker script and should link against the api-caller library so they can
 interface with the :ref:`epicardium_api`.
 Note: this feature is disabled by default and has to be enabled at build time.
 To do this, run ``bootstrap.sh`` with the option ``-Djailbreak_card10=true``
 and rebuild the firmware as described in :ref:`how_to_build`.
 
+.. _Rustcardium: https://git.card10.badge.events.ccc.de/astro/rust-card10
+
 .. todo::
 
    Provide more details how this works

Documentation/pycardium/overview.rst

@@ -49,10 +49,19 @@ and power it on::
 
    leds.set_rocket(0, 31)
 
+.. note::
+
+   If you're using iOS/Mac then you can connect to your serial console using:
+
+   .. code-block:: shell-session
+
+      screen /dev/tty.usbmodem* 115200
+
+   You can now see in your console what buttons you have pressed and your
+   console outputs/logs.  With ``CTRL+C`` you exit the console.
 
 REPL modes
 ^^^^^^^^^^
-
 MicroPython supports a different REPL modes over the serial console. The modes
 can be changed on every new line.
 
@@ -77,5 +86,3 @@ or give you tracebacks if an error occured.
 
 You can use **pycard10** (tools/pycard10.py) to execute python files from your
 PC directly on the card10.
-
-