It's a Makefile. I use Makefiles now. Makefiles are cool

RafeKettler · Jul 4, 2011 · 966bb82 · 966bb82
1 parent cd7a5db
commit 966bb82
Show file tree

Hide file tree

Showing 6 changed files with 31 additions and 63 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,17 @@
+docs: magicmethods.html magicmethods.pdf clean
+
+html: magicmethods.html
+
+pdf: magicmethods.pdf 
+
+magicmethods.html: markedup.html
+	cat header.html markedup.html footer.html > magicmethods.html
+
+markedup.html: table.markdown magicmethods.markdown table.markdown
+	python magicmarkdown.py
+
+magicmethods.pdf: magicmethods.tex
+	pdflatex magicmethods.tex
+
+clean:
+	rm -f markedup.html magicmethods.log magicmethods.dvi magicmethods.aux
diff --git a/README.markdown b/README.markdown
@@ -6,4 +6,4 @@ Licensed under Creative Commons CC--NC-BY-SA (see http://creativecommons.org/lic
 Can be seen at http://www.rafekettler.com/magicmethods.html in relatively up to date form.
 
 ## For forkers: ##
-Edit magicmethods.mkd, run `python magicmarkdown.py`, and then `cat header.html markedup.html footer.html > magicmethods.html`. The magicmarkdown script requires markdown, just issue `pip install markdown` and you'll have it.
+Edit magicmethods.mkd/magicmethods.tex, then run `make docs`. The build script requires the Python Markdown module, so you'll have to run `pip install markdown` if you don't already have it. Happy hacking!
diff --git a/magicmarkdown.py b/magicmarkdown.py
@@ -1,48 +1,21 @@
-# magicmarkdown.py
-# utility script for changing markdown from magic methods guide into HTML
+"""
+ magicmarkdown.py
+utility script for changing markdown from magic methods guide into HTML
+"""
 
 import markdown
 
-header = """<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>A Guide to Python's Magic Methods &laquo; rafekettler.com</title>
-<meta name="description" content="A guide to all the Magic Methods in Python" />
-<meta name="keywords" content="python, programming, magic methods, object-oriented, oop" />
-<link href="style.css" rel="stylesheet" type="text/css" />
-</head>
-
-<body>"""
-
-footer = """<script type="text/javascript">
-
-  var _gaq = _gaq || [];
-  _gaq.push(['_setAccount', 'UA-18615621-3']);
-  _gaq.push(['_trackPageview']);
-
-  (function() {
-    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
-  })();
-</script>
-</body>
-
-</html>"""
-
-table = open('table.mkd').read()
-body = open('magicmethods.mkd').read()
-appendix = open('appendix.mkd').read()
+table = open('table.markdown').read()
+body = open('magicmethods.markdown').read()
+appendix = open('appendix.markdown').read()
 
 table_text = markdown.markdown(table)
 body_text = markdown.markdown(body, 
                          ['def_list', 'codehilite'])
 appendix_text = markdown.markdown(appendix, ['tables'])
 
 with open('magicmethods.html', 'w') as out:
-    out.write(header)
     out.write(table_text)
     out.write(body_text)
     out.write(appendix_text)
-    out.write(footer)
 
diff --git a/magicmethods.html b/magicmethods.html
@@ -1,16 +1,7 @@
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>A Guide to Python's Magic Methods &laquo; rafekettler.com</title>
-<meta name="description" content="A guide to all the Magic Methods in Python" />
-<meta name="keywords" content="python, programming, magic methods, object-oriented, oop" />
-<link href="style.css" rel="stylesheet" type="text/css" />
-</head>
-
-<body><h1>A Guide to Python's Magic Methods</h1>
+<h1>A Guide to Python's Magic Methods</h1>
 <h3>Rafe Kettler</h3>
 <p>Copyright &copy; 2011 Rafe Kettler</p>
-<p>Version 1.12</p>
+<p>Version 1.13</p>
 <p>A PDF version of this guide can be obtained from <a href="http://www.rafekettler.com/magicmethods.pdf">my site</a> or <a href="https://github.com/RafeKettler/magicmethods/raw/master/magicmethods.pdf">Github</a>. The magic methods guide has <a href="http://www.github.com/RafeKettler/magicmethods">a git repository at http://www.github.com/RafeKettler/magicmethods</a>. Any issues can be reported 
 there, along with comments, (or even contributions!).</p>
 <p><strong><a id="table" href="#table">Table of Contents</a></strong></p>
@@ -537,7 +528,7 @@ <h2><a id="descriptor" href="#descriptor">Building Descriptor Objects</a></h2>
 
 
 <h2><a id="pickling" href="#pickling">Pickling Your Objects</a></h2>
-<p>If you spend time with other Pythonistas, chances are you've at least heard of pickling. Pickling is a serialization process for Python data structures, and can be incredibly useful when you need to store an object and retrieve it later. It's also a major source of worries and confusion.</p>
+<p>If you spend time with other Pythonistas, chances are you've at least heard of pickling. Pickling is a serialization process for Python data structures, and can be incredibly useful when you need to store an object and retrieve it later (usually for caching). It's also a major source of worries and confusion.</p>
 <p>Pickling is so important that it doesn't just have its own module (<code>pickle</code>), but its own <em>protocol</em> and the magic methods to go with it. But first, a brief word on how to pickle existing types(feel free to skip it if you already know).</p>
 <h3>Pickling: A Quick Soak in the Brine</h3>
 <p>Let's dive into pickling. Say you have a dictionary that you want to store and retrieve later. You couldwrite it's contents to a file, carefully making sure that you write correct syntax, then retrieve it using either <code>exec()</code> or processing the file input. But this is precarious at best: if you store important data in plain text, it could be corrupted or changed in any number of ways to make your program crash or worse run malicious code on your computer. Instead, we're going to pickle it:</p>
@@ -563,6 +554,7 @@ <h3>Pickling: A Quick Soak in the Brine</h3>
 
 
 <p>What happens? Exactly what you expect. It's just like we had <code>data</code> all along.</p>
+<p>Now, for a word of caution: pickling is not perfect. Pickle files are easily corrupted on accident and on purpose. Pickling may be more secure than using flat text files, but it still can be used to run malicious code. It's also incompatible across versions of Python, so don't expect to distribute pickled objects and expect people to be able to open them. However, it can also be a powerful tool for caching and other common serialization tasks.</p>
 <h3>Pickling your own Objects</h3>
 <p>Pickling isn't just for built-in types. It's for any class that follows the pickle protocol. The pickle protocol has four optional methods for Python objects to customize how they act (it's a bit different for C extensions, but that's not in our scope):</p>
 <dl>
@@ -741,18 +733,4 @@ <h2><a id="conclusion" href="#conclusion">Conclusion</a></h2>
 </tr>
 </tbody>
 </table>
-<p>Hopefully, this table should have cleared up any questions you might have had about what syntax invokes which magic method.</p><script type="text/javascript">
-
-  var _gaq = _gaq || [];
-  _gaq.push(['_setAccount', 'UA-18615621-3']);
-  _gaq.push(['_trackPageview']);
-
-  (function() {
-    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
-  })();
-</script>
-</body>
-
-</html>
+<p>Hopefully, this table should have cleared up any questions you might have had about what syntax invokes which magic method.</p>
diff --git a/magicmethods.pdf b/magicmethods.pdf
diff --git a/table.markdown b/table.markdown
@@ -4,7 +4,7 @@
 
 Copyright &copy; 2011 Rafe Kettler
 
-Version 1.12
+Version 1.13
 
 A PDF version of this guide can be obtained from [my site](http://www.rafekettler.com/magicmethods.pdf) or [Github](https://github.com/RafeKettler/magicmethods/raw/master/magicmethods.pdf). The magic methods guide has [a git repository at http://www.github.com/RafeKettler/magicmethods](http://www.github.com/RafeKettler/magicmethods). Any issues can be reported 
 there, along with comments, (or even contributions!).