Outputs as OurBigBook Markup, i.e. the same format as the input itself!
While using -O bigb is not a common use case, the existence of this format has the following applications:
  • automatic source code formatting e.g. with --format-source. The recommended format, including several edge cases, can be seen in the test file test_bigb_output.bigb, which should be left unchanged by a bigb conversion.
  • manipulating source code on OurBigBook Web to allow editing either individual sections separatelly, or multiple sections at once
  • this could be adapted to allows us to migrate updates with breaking changes to the source code more easily. Alternatively on OurBigBook Web, we might just start storing the AST instead of source, and just rendering the source whenever users want to edit it.
Can be tested interactively with:
ourbigbook --no-db -O bigb --stdout --log=ast-simple test_bigb_output.bigb
One important property of the bigb conversion is that is must not alter the AST, and therefore neither the final output, in any way.
One good test is:
ourbigbook README.bigb &&
mv out/html/index.html out/html/old.html &&
ourbigbook --format-source README.bigb  &&
ourbigbook README.bigb &&
diff -u out/html/old.html out/html/index.html