annotate README.txt @ 123:8db34885ebe4

tame that beast called doctest
author Jeff Hammel <jhammel@mozilla.com>
date Thu, 19 May 2011 10:56:16 -0700
parents 3eb34cad5858
children a7a7c364568a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 Make It So!
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
2 ===========
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
3
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
4 templates for the people
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
5
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
6 So people generally do things the easiest way possible. If you try to
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
7 get people to send you a file with, say, a "one-off" script, they will
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
8 probably hard code a bunch of stuff in it. Then, you're not really
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
9 sure what needs to be changed and because you're human you might make
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
10 a mistake. Worse, its a perl script and you're a python programmer.
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
11 You don't know what that script does!
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
12
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
13 And this is the time of the iceberg. If it really is a one-off, who
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
14 cares? But quickly one-offs become a deployment story, and not a very
324a70edb73c add a README stub
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
15 efficient one.
91
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
16
92
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
17
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
18 Making a New Template
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
19 ---------------------
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
20
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
21
91
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
22 Variable Conventions
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
23 --------------------
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
24
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
25 MakeItSo! provides a few variables for you. You can include another
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
26 file or URL using {{include(URI)}}, where URI is the file path or the
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
27 URL (of course, internet is required to include remote resources). The
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
28 included resource is not included.
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
29
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
30 Files and URLS being interpolated also have the variable %(here)s,
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
31 which is the parent of their resource. Therefor, using sensible path
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
32 conventions, a neighboring file may be (e.g.) included like
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
33
672d2d3ee322 document a bit and add a test for an include example
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
34 {{include(here + 'foo.txt')}}
92
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
35
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
36 The python template asserts several conventions:
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
37
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
38 - project: the project chosen
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
39 - author: author of a project
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
40 - email: author's email
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
41 - url: url of the project
97
3eb34cad5858 update variable conventions with {{repo}}
Jeff Hammel <jhammel@mozilla.com>
parents: 92
diff changeset
42 - repo: the repository of the project; this will be used for the URL
3eb34cad5858 update variable conventions with {{repo}}
Jeff Hammel <jhammel@mozilla.com>
parents: 92
diff changeset
43 if it is given and the URL is not
92
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
44
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
45
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
46 Adding a License to a Template
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
47 ------------------------------
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
48
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
49 [TODO]
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
50
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
51
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
52 Web Service
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
53 -----------
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
54
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
55 python has the ability to run files from stdin. This means you can
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
56 run makeitso directly from the web::
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
57
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
58 python <(curl http://k0s.org/mozilla/hg/MakeItSo/raw-file/tip/makeitso/makeitso.py) [URI]
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
59
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
60 This uses the bash shell. If you have another shell you may have to
bfab7367eb56 add some more documentation tidbits
Jeff Hammel <jhammel@mozilla.com>
parents: 91
diff changeset
61 use another syntax, download the file, or install the package.