[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"MopGnW6k8i":3},"\nMathematics in Lean Source\n==========================\n\nThis repository is used to generate the textbook and user repository for\n[Mathematics in Lean](https://leanprover-community.github.io/mathematics_in_lean/).\n\nOur build process applies rudimentary scripts to marked up Lean files to generate\n- source files for the textbook,\n- Lean exercise files, and\n- Lean solution files,\n\nand put them all in the right places.\n\nWe use [Sphinx](https://www.sphinx-doc.org/en/master/)\n and the [Read the Docs theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/) to generate\n the HTML and PDF versions of the textbook.\n\nFinally, we use another script to deploy the contents to the\n[user repository](https://github.com/leanprover-community/mathematics_in_lean).\n\n\nSetup\n-----\n\nTo edit the Lean files, you need to have Lean, github, and friends installed.\nSee the instructions on the [Lean community web pages](https://leanprover-community.github.io/) .\nIn particular, don't forget to use\n```\nlake exe cache get\n```\nafter fetching this repository to get the compiled version of Mathlib.\n\nTo build the textbook, you need to have\n[Sphinx and ReadTheDocs](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/install.html)\ninstalled, as well as the Python `regex` package.\nIdeally, `pip install -r scripts/requirements.txt` should suffice.\n\n\nOverview\n--------\n\nThe Lean source files are in the `MIL` directory. There is a folder for each chapter, the\nname of which begins with the letter `C` and the chapter number.\nThe scripts sort the chapters and ignore folders that do not begin with `C`.\n\nEach folder should contain an `.rst` file with the same name, which has the chapter header\nfor Sphinx. Each folder also has a Lean source file for each section,\nthe name of which begins with `S` and the section number.\nThe scripts ignore Lean files that do not begin with `S`.\nThe markup that is used to generate the content is described below.\n\nThe folder `sphinx_source` contains files that are automatically added to a generated folder\ncalled `source`, which is used by Sphinx.\nIt includes, in particular, a folder for any figures you want to use in the textbook.\n\nThe folder `user_repo_source` contains files that are automatically added to a generated\nfolder called `user_repo`, which is used to build the user repository.\nIt includes, in particular, the `README` file for that repository.\n\n\nBuild\n-----\n\nRunning `scripts/mkall.py` does the following:\n- It creates and initializes a `source` directory, for use by Sphinx.\n- It creates and initializes a `user_repo` directory with files that will be\n  deployed to the user repository.\n- It updates the file `MIL.lean` to match the contents of the `MIL` folder.\n\nWith the `source` directory in place, you can use `make html` and `make latexpdf` to\ncall Sphinx to build the HTML and PDF versions of the book, respectively.\nSphinx puts these in a generated `build` directory.\n\nRunning `scripts/deploy.sh leanprover-community mathematics_in_lean` calls all three of the\nprevious scripts, copies the HTML and PDF versions of the book to `user_repo`,\nand deploys the user repository to the github repository `leanprover-community/mathematics_in_lean`.\nYou can deploy to another destination for testing.\n\nRunning `scripts/clean.py` deletes the `source`, `user_repo`, and `build` directories.\n\n\nMarkup\n------\n\nThe Lean files in the `MIL` folder generate three types of files:\n- Source files for the Sphinx textbook.\n- Files with examples (and exercises) for the user repository.\n- Files with solutions for the user repository.\nA line of text from the Lean file may go to any combination of these destinations simultaneously,\nor nowhere at all, as determined by simple markup directives in the file.\n\nWhen `scripts/mkall.py` starts processing a file,\nit sends output to both the associated examples file and the associated solutions file by default.\nThis makes sense, for example, for the import lines.\n\nThe following markup specifies material for the textbook:\n```\n/- TEXT:\nStuff for the textbook goes here.\nTEXT. -/\n```\nThe lines between the comments are sent only to the associated Sphinx source file.\n\nAfter the line `TEXT. -/`, by default, lines of text are sent only to the\nexamples file.\nYou can replace the last line with `EXAMPLES: -/`, which has the same effect,\n`SOLUTIONS: -/` to send the lines to the solutions file,\n`BOTH: -/` to send the lines to the both files,\nor `OMIT: -/` to send the lines to neither.\n\nYou can subsequently modify the behavior with the additional comment lines\n`-- EXAMPLES:`, `-- SOLUTIONS:`, `-- BOTH:`, and `-- OMIT:`.\nThe behavior stays in effect until another directive changes it.\n\nWhile the script is processing lines of Lean code, you can specify that a sequence of lines\nshould be added to the textbook as a block quote by enclosing it as follows:\n```\n-- QUOTE:\nexample : 1 + 1 = 2 := by rfl\n-- QUOTE.\n```\nNote the use of the period to mark the end of the quote.\n\nIn such a quote block, any lines that are designated to go only to the solutions file are not\nincluded in the quote. Thus you can only quote lines that are sent to the examples file,\nsent to both the examples and solutions files, or omitted from both.\nThe behavior of the `QUOTE` directives is otherwise independent of the behavior of the\n`EXAMPLES`, `SOLUTIONS`, `BOTH`, and `OMIT` directives.\nFor example, you can switch output from the examples file to both the examples and solutions\nfile in the middle of a quote.\nIt doesn't make a difference whether one of the latter directives occurs just before or\njust after a `QUOTE` directive.\n\nYou can also use `/- EXAMPLES:`, `/- SOLUTIONS:`, `/- BOTH:`, and `/- OMIT:` to put text\nin a block comment that is sent to one of the files accordingly.\nThis provides a handy way to specify a `sorry` in an examples file\nthat is replaced by a solution in the solution file.\nHere's an example of how these are used:\n```\n/- TEXT:\nHere is an example of the way that ``rintro`` is used:\nTEXT. -/\n-- QUOTE:\nexample : s ∩ (t ∪ u) ⊆ s ∩ t ∪ s ∩ u := by\n  rintro x ⟨xs, xt | xu⟩\n  · left; exact ⟨xs, xt⟩\n  · right; exact ⟨xs, xu⟩\n-- QUOTE.\n\n/- TEXT:\nAs an exercise, try proving the other inclusion:\nBOTH: -/\n-- QUOTE:\ntheorem foo : s ∩ t ∪ s ∩ u ⊆ s ∩ (t ∪ u) := by\n/- EXAMPLES:\n  sorry\nSOLUTIONS: -/\n  rintro x (⟨xs, xt⟩ | ⟨xs, xu⟩)\n  · use xs; left; exact xt\n  · use xs; right; exact xu\n-- QUOTE.\n\n```\nThe second text block represents a common idiom for presenting exercises:\nafter the textbook prose, a `theorem` or `example` line is sent to both the examples\nand the solutions file.\nThe examples file contains only a `sorry`, whereas the solutions file contains the full solution.\nThe solution is checked by Lean in the source file, but it is not included in the quote.\n\nNote also the useful convention that if a blank line is needed in the examples or\nsolutions file, it is specified *after* the relevant segment, so that the next\ntime output is enabled no blank line is needed.\nSo, in the example above, there is no blank line before or after `-- QUOTE:`\nbecause we assume that prior input has already inserted a blank line,\nbut there is a blank line after `-- QUOTE.`\n\nIt is common to use sections to declare and scope variables in the examples and solutions\nfiles, but to omit the section commands from quote.\nThus you might use the following pattern:\n```\n/- TEXT:\nHere is an example of the way that ``rintro`` is used:\nBOTH: -/\nsection\nvariable (s t u : Set α)\n\n-- EXAMPLES:\n-- QUOTE:\nexample : s ∩ (t ∪ u) ⊆ s ∩ t ∪ s ∩ u := by\n  rintro x ⟨xs, xt | xu⟩\n  · left; exact ⟨xs, xt⟩\n  · right; exact ⟨xs, xu⟩\n-- QUOTE.\n\n```\nJust make sure that, later in the file, the matching `end` and a blank line after are sent to\nboth outputs.\n\nThe weird pair of characters `αα` in a Lean input file is simply deleted from any\noutput produced by the script.\nThis is a little hack that allows you to produce the same identifier in the examples\nand solutions files. For example, the exercise above could have been written\nas follows:\n```\n/- TEXT:\nAs an exercise, try proving the other inclusion:\nEXAMPLES: -/\n-- QUOTE:\ntheorem foo : s ∩ t ∪ s ∩ u ⊆ s ∩ (t ∪ u) := by\n  sorry\n-- QUOTE.\n\n-- SOLUTIONS:\ntheorem fooαα : s ∩ t ∪ s ∩ u ⊆ s ∩ (t ∪ u) := by\n  rintro x (⟨xs, xt⟩ | ⟨xs, xu⟩)\n  · use xs; left; exact xt\n  · use xs; right; exact xu\n\n```\nThe theorem is named `foo` in both the examples and the solutions, but Lean doesn't\ncomplain about a duplicate identifier in the source file.\n\nFinally, there is a mechanism that allows you to quote any part of the file\nin the textbook, before or after it appears in the Lean source file.\nThis can be used, for example, to present a long proof and then refer back to parts of it.\nEncode the lines you want to quote with a pair of tags:\n```\ntheorem foo : s ∩ t ∪ s ∩ u ⊆ s ∩ (t ∪ u) := by\n-- TAG: my_tag\n  rintro x (⟨xs, xt⟩ | ⟨xs, xu⟩)\n  · use xs; left; exact xt\n  · use xs; right; exact xu\n-- TAG: end\n```\nThe first tag can have any label you want in place of `my_tag`, whereas the second should\nbe exactly as shown. Adding the line\n```\n-- LITERALINCLUDE: my_tag\n```\nin the middle of a text block anywhere in the file will insert the tagged text as a\nblock quote in the textbook,\nusing a Sphinx directive that is designed for exactly that purpose.\n\n\nTesting\n-------\n\nAfter running `scripts/mkall.py`, you can use `lake build` to compile all the lean source files.\nThis will print all the output generated by `#check`, `#eval`, and other commands found in the\nsource files, as well as a warning for each `sorry`, and so on. Scanning the output provides\na way to detect whether all the definitions, theorems, and proofs are well formed.\nThis does not, however, confirm that the examples files and solutions files that are generated\nfrom the lean source files are well formed.\n\nTo test the examples, use `scripts/examples_test.py`.\nThis compiles all the lean source files as with `scripts/mkall.py`,\nbut then it copies the Lean files from `user_repo` into a folder `MIL/Test` and\nconstructs `MIL.lean` to import each of those.\nUse `lake build` to compile them.\n\nSimilarly, use `scripts/solutions_test.py` followed by `lake build` to test all the solutions files.\n\nUse `scripts/clean_test.py` to remove the directory `MIL/Test` and restore `MIL.lean` to import the\nLean source files.\n\n\nProcessing one section\n----------------------\n\nInstead of building everything, you can test build a single section with `scripts/mksection.py`.\nFor example,\n```\n  scripts/mksection.py C03_Logic S02_The_Existential_Quantifier\n```\ncreates the examples file, the solutions file, and the Sphinx restructured text file\nfor the section indicated.\n\n\nHow to contribute\n-----------------\n\nThe textbook is still a work in progress, but feedback and corrections are welcome.\nYou can open a pull request,\nfind us on the [Lean Zulip channel](https://leanprover.zulipchat.com/),\nor contact us by email.\nPlease contact us before making a pull request for substantial expository or stylistic\nchanges.\n",1792350314866]