Refactor citation + tags and update README.md

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`):
 
 ![LaTeX sample](https://gitlab.compute.dtu.dk/tuhe/snipper/-/raw/main/docs/index.png)
@@ -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.

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`):
 
 ![LaTeX sample]({{resources}}/docs/index.png)
@@ -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 }}
 ```

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()