From e561315cb556fba8adc1d81cab868e59b61c5934 Mon Sep 17 00:00:00 2001
From: Tue Herlau <tuhe@dtu.dk>
Date: Sun, 5 Sep 2021 18:49:47 +0200
Subject: [PATCH] Refactor citation + tags and update README.md
---
README.md | 20 ++++++++++----------
docs/README.jinja.md | 20 ++++++++++----------
docs/build_docs.py | 4 ++--
3 files changed, 22 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index 7d5e1b0..d8a650d 100644
--- a/README.md
+++ b/README.md
@@ -210,8 +210,8 @@ Note that apparently there
is no library for converting python code to shell sessions so I had to write it myself, which means it can properly get confused with multi-line statements (lists, etc.). On the plus-side, it will automatically insert newlines after the end of scopes.
My parse is also known to be a bit confused if your code outputs `...` since it has to manually parse the interactive python session and this normally indicates a new line.
-## References and citations (`\ref` and `\cite`)
-One of the most annoying parts of maintaining student code is to constantly write "see equation on slide 41 bottom" only to have the reference go stale because slide 23 got removed. Well now anymore, now you can direcly refence anything with a bibtex or aux file!
+# References and citations (`\ref` and `\cite`)
+One of the most annoying parts of maintaining student code is to constantly write *"see equation on slide 41 bottom"* only to have the reference go stale because slide 23 got removed. Well not anymore, now you can direcly refence anything with a bibtex or aux file!
Let's consider the following example of a simple document with a couple of references: (see `examples/latex/index.pdf`):
@@ -297,7 +297,7 @@ Since the aux/bibtex databases are just dictionaries it is easy to join them tog
I have written reference tags to lecture and exercise material as well as my notes and it makes reference management very easy.
-## Advanced block processing
+# Partial solutions
The default behavior for code removal (#!b and #!f-tags) is to simply remove the code and insert the number of missing lines.
We can easily create more interesting behavior. The code for the following example can be found in `examples/b_example.py` and will deal with the following problem:
```python
@@ -314,10 +314,10 @@ def primes_sieve(limit):
return primes #!b
# Example use: print(primes_sieve(42))
```
-The example shows how we can easily define custom functions for processing the code which is to be removed.
-All such a function need is to take a list of lines (to be obfuscated) and return a new list of lines (the obfuscated code).
-A couple of short examples:
-### Permute lines
+The examples below shows how we can easily define custom functions for processing the code which is to be removed; I have not included the functions here for brevity,
+but they are all just a few lines long and all they do is take a list of lines (to be obfuscated) and return a new list of lines (the obfuscated code).
+
+### Example 1: Permute lines
This example simple randomly permutes the line and prefix them with a comment tag to ensure the code still compiles
```python
import numpy as np
@@ -335,7 +335,7 @@ def primes_sieve(limit):
# Example use: print(primes_sieve(42))
raise NotImplementedError('Complete the above program')
```
-### Partial replacement
+### Example 2: Partial replacement
This example replaces non-keyword, non-special-symbol parts of the lines:
```python
import numpy as np
@@ -354,8 +354,8 @@ def primes_sieve(limit):
raise NotImplementedError('Complete the above program')
```
-### Half of the solution
-The final solution display half of the proposed solution:
+### Example 3: Half of the solution
+The final example displays half of the proposed solution:
```python
import numpy as np
# Implement a sieve here.
diff --git a/docs/README.jinja.md b/docs/README.jinja.md
index 19ad495..63e1837 100644
--- a/docs/README.jinja.md
+++ b/docs/README.jinja.md
@@ -121,8 +121,8 @@ Note that apparently there
is no library for converting python code to shell sessions so I had to write it myself, which means it can properly get confused with multi-line statements (lists, etc.). On the plus-side, it will automatically insert newlines after the end of scopes.
My parse is also known to be a bit confused if your code outputs `...` since it has to manually parse the interactive python session and this normally indicates a new line.
-## References and citations (`\ref` and `\cite`)
-One of the most annoying parts of maintaining student code is to constantly write "see equation on slide 41 bottom" only to have the reference go stale because slide 23 got removed. Well now anymore, now you can direcly refence anything with a bibtex or aux file!
+# References and citations (`\ref` and `\cite`)
+One of the most annoying parts of maintaining student code is to constantly write *"see equation on slide 41 bottom"* only to have the reference go stale because slide 23 got removed. Well not anymore, now you can direcly refence anything with a bibtex or aux file!
Let's consider the following example of a simple document with a couple of references: (see `examples/latex/index.pdf`):
@@ -156,28 +156,28 @@ Since the aux/bibtex databases are just dictionaries it is easy to join them tog
I have written reference tags to lecture and exercise material as well as my notes and it makes reference management very easy.
-## Advanced block processing
+# Partial solutions
The default behavior for code removal (#!b and #!f-tags) is to simply remove the code and insert the number of missing lines.
We can easily create more interesting behavior. The code for the following example can be found in `examples/b_example.py` and will deal with the following problem:
```python
{{ cs101_output.sieve_py }}
```
-The example shows how we can easily define custom functions for processing the code which is to be removed.
-All such a function need is to take a list of lines (to be obfuscated) and return a new list of lines (the obfuscated code).
-A couple of short examples:
-### Permute lines
+The examples below shows how we can easily define custom functions for processing the code which is to be removed; I have not included the functions here for brevity,
+but they are all just a few lines long and all they do is take a list of lines (to be obfuscated) and return a new list of lines (the obfuscated code).
+
+### Example 1: Permute lines
This example simple randomly permutes the line and prefix them with a comment tag to ensure the code still compiles
```python
{{ cs101_output.obscure_1_py }}
```
-### Partial replacement
+### Example 2: Partial replacement
This example replaces non-keyword, non-special-symbol parts of the lines:
```python
{{ cs101_output.obscure_2_py }}
```
-### Half of the solution
-The final solution display half of the proposed solution:
+### Example 3: Half of the solution
+The final example displays half of the proposed solution:
```python
{{ cs101_output.obscure_3_py }}
```
diff --git a/docs/build_docs.py b/docs/build_docs.py
index fc76bca..30e7f4c 100644
--- a/docs/build_docs.py
+++ b/docs/build_docs.py
@@ -51,8 +51,8 @@ if __name__ == "__main__":
# Build the docs.
import glob
- with open("../examples/citations.py", 'r') as f:
- data['citations_orig_py'] = f.read()
+ # with open("../examples/citations.py", 'r') as f:
+ # data['citations_orig_py'] = f.read()
# for file in glob.glob("../examples/output/*.*"):
# with open(file, 'r') as f:
# data[os.path.basename(file).replace(".", "_")] = f.read()
--
GitLab