Mercurial > hg > decoupage

annotate README.txt @ 78:5330cd62e179

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
something about hash marks in filenames
author Jeff Hammel <jhammel@mozilla.com>
date Tue, 16 Apr 2013 00:45:31 -0700
parents 9ba237db4cde
children 2c7c4fda1a14
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
1 decoupage
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
2 =========
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
3
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
4 what is it?
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
5 -----------
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
6
78
5330cd62e179 something about hash marks in filenames
Jeff Hammel <jhammel@mozilla.com>
parents: 36
diff changeset
7 `decoupage` is a *dynamic* file server that allows for index pages
0
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
8 configurable with genshi templates and .ini files. I mainly wrote it
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
9 because i was tired of using apache for serving my website and
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
10 generating index.html files by hand. Decoupage provides views into
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
11 the filesystem.
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
12
0
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
13
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
14 how do i use it?
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
15 ----------------
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
16
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
17 Set up a `paste <http://pythonpaste.org>`_ .ini file that specifies the
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
18 directory to serve (``decoupage.directory``) and, optionally, a
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
19 configuration file .ini file (``decoupage.configuraton``) which
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
20 specifies the labels for the files based on directory. An example of a
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
21 `paste <http://pythonpaste.org>`_ .ini file is in
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
22 ``decoupage.ini``. Note the ``[app:decoupage]`` section::
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
23
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
24 [app:decoupage]
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
25 paste.app_factory = decoupage.factory:factory
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
26 decoupage.directory = %(here)s/example
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
27 decoupage.configuration = %(here)s/example.ini
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
28
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
29 The labels for files are in ``example.ini``, specified by sections as
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
30 directories::
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
31
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
32 [/]
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
33 foo.txt = a file about cats
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
34
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
35 [/cats]
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
36 lilly.txt = lilly
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
37 hobbes.txt = a file about Hobbes
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
38
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
39 You can specify the entire layout from here. Alternately, you can
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
40 have an ``index.ini`` in a directory which, if present, overrides the
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
41 default configuration. Such a file is in the ``fleem`` subdirectory
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
42 of ``example``::
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
43
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
44 /template = index.html
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
45 fleem.txt = some fleem for ya
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
46
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
47 Try it out! Install decoupage and run ``paster serve decoupage.ini``
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
48 and point your browser to the URL it gives you.
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
49
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
50
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
51 how do i do more with decoupage?
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
52 --------------------------------
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
53
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
54 Since filenames can't start with a ``/`` (just try it!), the
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
55 functionality of decoupage may be extended with ``/`` commands in a
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
56 section. This is done by adding a setuptools ``entry_point`` to
fa2005f769eb adding decoupage from http://my-svn.assembla.com/svn/arbez/decoupage r355
k0s <k0scist@gmail.com>
parents:
diff changeset
57 ``[decoupage.formatters]``. See the decoupage ``setup.py`` and
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
58 ``decoupage.formatters`` for examples. For instance,
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
59
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
60 Running `decoupage-formatters` from the command line gives the list of
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
61 formatters that are available (which are pluggable setuptools extension points
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
62 at [decoupage.formatters]). For example: /include = site.html could
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
63 include the site.html genshi template at the top of the body.
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
64
27
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
65 Formatters:
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
66
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
67 sort:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
68 determines how to sort the files in a directory;
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
69 right now only by case-insensitive alphabetically
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
70 * reverse : reverse the order of the sorting
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
71
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
72 all:
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
73 only pass files of a certain pattern;
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
74 the inverse of ignore
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
75 calling all with no arguments means only files with descriptions
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
76 are used
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
77
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
78 title:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
79 splits a description into a title and a description via a
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
80 separator in
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
81 the description. The template will now have an additional
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
82 variable,
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
83 'title', per file
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
84 Arguments:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
85 * separator: what separator to use (':' by default)
78
5330cd62e179 something about hash marks in filenames
Jeff Hammel <jhammel@mozilla.com>
parents: 36
diff changeset
86
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
87 describe:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
88 obtain the description from the filename
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
89 the file extension (if any) will be dropped and
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
90 spaces will be substituted for underscores
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
91
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
92 ignore:
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
93 ignore files of a glob patterns.
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
94 These files will not be linked to in the template.
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
95 e.g. /ignore = .* *.pdf # don't list dotfiles and PDFs
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
96
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
97 include: include a file at the top of the body
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
98 css: specify CSS used (whitespace separated list)
18
ebc1a802f9b8 update documentation
k0s <k0scist@gmail.com>
parents: 0
diff changeset
99
27
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
100 Decoupage also makes use of other special intrinsic keywords:
9e86c5cb111a minor documentation updates
k0s <k0scist@gmail.com>
parents: 18
diff changeset
101
28
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
102 formatters: ordered list of formatters to apply
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
103
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
104 inherit: inherit configuration from a certain directory (instead of
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
105 the parent
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
106
fc1c479296c3 more docmentation updates
k0s <k0scist@gmail.com>
parents: 27
diff changeset
107 transform: a list of transformers for contenttransformer
36
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
108
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
109
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
110 TODO
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
111 ----
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
112
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
113 * allow transformers to be configurable on a per-directory basis
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
114 * add a ``?format=rss`` query string argument
9ba237db4cde adding TODO items
k0s <k0scist@gmail.com>
parents: 29
diff changeset
115 * add a ``?template=foo.html`` query string argument