pythonizing general guidelines

Pythonizing: General Guidelines

Delete the old LaTeX bindings

First thing to note: we are replacing all the LaTeX bindings with Pythonized bindings. Meaning: delete the old LaTeX bindings after you create and verify new Pythonized bindings. Absolutely do not just comment out the old LaTeX bindings.

• Leaving the old LaTeX bindings in the text just clutters up the document and makes it harder to maintain over time.
• The old LaTeX bindings are available in git history if we ever need them.

Let's be 100% clear: the goal is to delete the old LaTeX bindings. Do not just comment them out.

General notes

Here's a few general notes about the {mpi-bindings} sections:

1. When you make (either a full document or an individual chapter), this section will automatically be replaced by generated LaTeX for you.
2. The generated LaTeX will include appropriate index references, etc. (just like the old hard-coded LaTeX bindings).
3. {mpi-binding} blocks are only for MPI bindings. They are not for constants, typedefs, examples, or any other type of code blocks. All of those must still be hard-coded in LaTeX with the appropriate macros.
4. You may only define one MPI routine per {mpi-binding} block
5. Everything between \begin{mpi-binding} and \end{mpi-binding} is Python.
   1. The contents of this section are actually given to a Python interpreter to execute. As a direct consequence, you must obey Python syntax inside {mpi-bindings} sections! This includes whitespace, line breaks, etc. For example:
      • Blank lines are fine.
      • You must consistently whitespace-indent all your code lines to the same level.
      • You may actually use any valid Python code in this block (but this probably isn't too useful).
        • No Python state is shared between different {mpi-binding} sections; each {mpi-binding} section is interpreted in its own, unique Python interpreter.
      • Comments can begin with # (you can even use the """-style Python "comments", if desired). Just like in LaTeX, there are sometimes complicated situations where leaving comments for future authors are helpful.
      • Do not use LaTeX escaping in {mpi-binding} sections; use Python escaping. In particular, do not escape underscores (_); the Python code will escape all of those for you when rendering the final LaTeX.
   2. If you do not use correct Python syntax, you will actually get a Python syntax error during make. There is unfortunately not good debugging output to indicate which {mpi-binding} block caused the syntax error; you'll have to rely on context from the Python error output to discover the location of your error.