Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 288 lines (222 sloc) 8.866 kb
52f3521 added mowyw to the repository
moritz authored
1 mowyw - mowyw writes your websites (or: Moritz writes your websites ;-)
2
3 For license of this file see the notice at the end of the file
4
dd0da06 [mowyw] monster commit
moritz authored
5 mowyw is an offline CMS, that means it process sources files and generates
52f3521 added mowyw to the repository
moritz authored
6 output files from them, usually HTML files, but php files and others are
7 possible as well (with some limitations though).
8
dd0da06 [mowyw] monster commit
moritz authored
9 For a formal and more complete description see the manpage at
10 <http://perlgeek.de/software/mowyw.1>
52f3521 added mowyw to the repository
moritz authored
11
12 SHORT HOWTO:
13 -----------
14
15 choose an empty directory, and there create the three directories
16 includes/
17 source/
18 online/
19
20 The `source/' directory contains the source files that will be processed by
21 mowyw. Each file in the `source/' directory is mapped to one file in the
22 `online/' directory. You should not write files into the `online/' directory
23 since they may be deleted or overwritten, and you should not modify existing
24 files in that directory since all changes are lost during the next run.
25 All files that might be included by others (including menus) should be in the
26 `includes' directory.
27
28 Now place a file index.html (or whatever you want it to be called) in the
29 'source/' directory.
30
31 If all your HTML files have a common header/footer, you may want to place them
32 in in the files `includes/header' and `includes/footer'.
33
34 For example `inlcudes/header' may contain
35
36 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
37 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
38
39 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
40 <head>
41 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
42 <link rel="stylesheet" type="text/css" media="screen, projection" href="style.css" />
43 <link rel="stylesheet" type="text/css" media="print" href="print.css" />
44
dd0da06 [mowyw] monster commit
moritz authored
45 and `includes/footer' may contain
52f3521 added mowyw to the repository
moritz authored
46
47 </body>
48 </html>
49
50 and perhaps an additional footer line to be displayed in all pages.
51
52 Now write some content in the file `source/index.html' and then run mowyw.
53 You should get an output like that:
54
55 Processing File 'source/index.html'... DONE.
56
57 Now point your browser at source/index.html and see if it worked.
58 Files not ending in .html, .htm, .shtml, .xhtml etc. are not processed, just
59 copyied.
60
d255aa6 * prefixes and postfix are now configurable
moritz authored
61 You can change the default pathes with the following command line options to
62 mowyw:
63 --postfix=html
64 --includes-prefix=incl/
65 --source-prefix=src/
66 --destination-prefix=out/
67 --menu-prefix=incl/menu/
dd0da06 [mowyw] monster commit
moritz authored
68 Note that if you want the prefixes to be directories you have to include the
d255aa6 * prefixes and postfix are now configurable
moritz authored
69 trailing slash (or whatever the directory separator on your OS is).
70
71 If you didn't change any heaer/footer/included files you can save processing
72 time by adding the command line option '--make', in which case mowyw will
73 compare the timestamps of the source file and designated output file and will
74 only process the source file if it is newer.
75
52f3521 added mowyw to the repository
moritz authored
76
77 INCLUDES:
78
79 So far mowyw didn't do much work for you, it just added header and footer
80 sections to all html files.
81 But it can do more for you: includes.
82 Just use the line
83
84 [[[include foo]]]
85
5195608 [mowyw] introduced [% ... %] as tag delimiter
moritz authored
86 or
87
88 [% include foo %]
89
52f3521 added mowyw to the repository
moritz authored
90 in your files, and the line will be replaced with the content of the file
91 `includes/foo'. It works pretty much like #inlcude "includes/foo" with a C pre
92 processor or <!-- #include virtual="includes/foo"--> with Server Side Includes
93 (SSI).
94
5195608 [mowyw] introduced [% ... %] as tag delimiter
moritz authored
95 Note that everywhere the [[[ ... ]]] delimiters can be exchanged by [% .. %].
96
dd0da06 [mowyw] monster commit
moritz authored
97 If the file includes/global exisits, it is processed before each source file.
98 Its output is discarded, but options and variables defined in that file are
99 available in all source files.
100
52f3521 added mowyw to the repository
moritz authored
101 MENUS:
102
103 Suppose you want to write a navigation menu in your html files that look like
104 this:
105
106 menu
107 |
108 +-- foo
109 |
110 +-- bar
111 |
112 +-- baz
113
114 and if you click on foo, a sub menu opens:
115
116 menu
117 |
118 +-- foo
119 | |
120 | +-foo1
121 | +-foo2
122 | +-foo3
123 |
124 +-- bar
125 |
126 +-- baz
127
128 The way you do this with mowyw is simple:
129 create a file called `includes/menu-navigation' and fill it with something
130 like this:
131
132 <div class="menu">
133 Navigation:
134 <ul>
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
135 [% item foo <li><a href="foo.html" {{class="#active"}}>foo</a>
52f3521 added mowyw to the repository
moritz authored
136 {{<ul>
137 <li><a href="foo1">foo1</a></li>
138 <li><a href="foo2">foo2</a></li>
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
139 </ul>}}</li> %]
140 [% item bar <li><a href="bar.html" {{class="#active"}}>bar</a></li> %]
141 [% item baz <li><a href="baz.html" {{class="#active"}}>baz</a></li> %]
52f3521 added mowyw to the repository
moritz authored
142 </ul>
143 </div>
144
145 now in your file foo.html, you use the line
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
146 [% menu navigation foo %].
52f3521 added mowyw to the repository
moritz authored
147 This line will be replaced by mowyw with:
148
149 <div class="menu">
150 Navigation:
151 <ul>
152 <li><a href="foo.html" class="#active">foo</a>
153 <ul>
154 <li><a href="foo1">foo1</a></li>
155 <li><a href="foo2">foo2</a></li>
156 </ul></li>
157 <li><a href="bar.html" >bar</a></li>
158 <li><a href="baz.html" >baz</a></li>
159 </ul>
160 </div>
161
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
162 Each menu item looks like this: [% item label1 some_text %]. If it is called as
163 [% menu label1 %] it will produce some_text, and all double curly brackets {{ }}
52f3521 added mowyw to the repository
moritz authored
164 are simply stripped, but the text between them remains.
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
165 If it is called with a different name, say [% menu label2 %] the curly brackets
52f3521 added mowyw to the repository
moritz authored
166 and the text between them are stripped.
167
d255aa6 * prefixes and postfix are now configurable
moritz authored
168 SYNTAX HILIGHTING
169
170 If you have both the Perl module Text::VimColor and Vim installed, you can use
171 the follwing construct to automagically generate syntax hilighted HTML markup:
172
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
173 <pre>[% syntax perl %]
d255aa6 * prefixes and postfix are now configurable
moritz authored
174 #!/usr/bin/perl
175
176 sub blubb {
177 print "This sub only prints this stupid message\n";
178 }
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
179 [% endsyntax %]pre>
d255aa6 * prefixes and postfix are now configurable
moritz authored
180
b498570 * added Changelog to prepare release of 0.3.0
moritz authored
181 If you don't have Text::VimColor installed, the characters '&', '<' and '>'
182 will still be automatically escaped.
183
d255aa6 * prefixes and postfix are now configurable
moritz authored
184 The only argument to 'syntax' is the language that the code is in, if you use
185 a value that vim doesn't know it will try to guess the language.
186
187 The standard CSS classes are:
188 .synComment { color: #0000FF }
189 .synConstant { color: #FF00FF }
190 .synIdentifier { color: #008B8B }
191 .synStatement { color: #A52A2A ; font-weight: bold }
192 .synPreProc { color: #A020F0 }
193 .synType { color: #2E8B57 ; font-weight: bold }
194 .synSpecial { color: #6A5ACD }
195 .synUnderlined { color: #000000 ; text-decoration: underline }
196 .synError { color: #FFFFFF ; background: #FF0000 none }
197 .synTodo { color: #0000FF ; background: #FFFF00 none }
198
199 (taken from Text::VimColor)
200
201
52f3521 added mowyw to the repository
moritz authored
202 VERBATIM OUTPUT
203
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
204 If your website includes string like [% or %] etc., you can use the
52f3521 added mowyw to the repository
moritz authored
205 verbatim-construct to prevent it from parsing:
206
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
207 [% verbatim foobarbaz %]
52f3521 added mowyw to the repository
moritz authored
208 Things here inbetween will be printed out exactly as they stand here, you can
209 safely write things like
210 "in perl6 [...] returns array refs:
211 my $a = [2, [4, 5, [8, 9,10]]];"
212 note that the ']]]' will not cause any harm.
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
213 [% endverbatim foobarbaz %]
52f3521 added mowyw to the repository
moritz authored
214
215 the name in the verbatim and in the endverbatim-package have to agree exactly
216 and my consist of alphabetic characters and numbers.
217
d255aa6 * prefixes and postfix are now configurable
moritz authored
218 COMMENTS
219
220 You can exclude parts entirly from showing up in the output by putting them
221 inside a comment:
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
222 [% comment anything inside here will not show up in the output %]
d255aa6 * prefixes and postfix are now configurable
moritz authored
223 In a comment everything but ']]]' is allowed.
224
52f3521 added mowyw to the repository
moritz authored
225
226 OMITTING HEADER AND FOOTER
227
228 If you include a line like this:
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
229 [% option no-header %]
52f3521 added mowyw to the repository
moritz authored
230 the header is _not_ prepended as usual.
231 You can achieve the following functionality for the footer with the line
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
232 [% option no-footer %]
52f3521 added mowyw to the repository
moritz authored
233
234
8e20ed2 desribed setvar, readvar and scoping
moritz authored
235 SETTING AND READING VARIABLES
236
237 Suppose you want to add a different <title> to every page, but you want all
238 your HTML header to be in one specific place.
239 A way to achive this is with the setvar and readvar constructs. Place this in
240 your header file:
241 <html>
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
242 <head><title>[% readvar title %]</title>/head>
8e20ed2 desribed setvar, readvar and scoping
moritz authored
243 <body>
244 (of course you should use a doctype ;-)
245 And then in each source file you can use
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
246 [% setvar title This is the title of this stupid page %]
8e20ed2 desribed setvar, readvar and scoping
moritz authored
247 to set the title. If you forget to set a variable before using it a warning
248 will be emitted.
249
250 Scoping:
251 Variables are scoped in the sense that when you enter a new scope (by using
252 include, menu, item or automatically by including the header and footer) the
253 variables from the higher level scope are still available, but if you modify
254 them in local scope they will still be unmodified in the outer scope.
255 Example:
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
256 [% setvar foo bar %]
257 [% include somefile %]
258 [% redavar foo %] --- gives bar
8e20ed2 desribed setvar, readvar and scoping
moritz authored
259 In file somfile:
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
260 [% readvar foo %] --- gives bar
261 [% setvar foo baz %]
262 [% readvar foo %] --- gives baz
8e20ed2 desribed setvar, readvar and scoping
moritz authored
263 Therefore you can change the header's and footer's output by defining
264 variables in the main source file, but not the other way round.
265
266
d255aa6 * prefixes and postfix are now configurable
moritz authored
267 SYNTAX CHANGE
268 -------------
269 Version 0.0.3 and before used only double square brackets
270 (like [[include foo]]), but I noticed that double closing square brackets
271 are part of a typical CDATA declaration in xml files (and xhtml) like this:
272 <style type="text/css">
273 /*<![CDATA[*/
274 CSS Declarations
275 /*]]>*/
276 </style>
277
a56968c [mowyw] changed [[[ ... ]]] to [% ... %] in README
moritz authored
278 Now tripple square brackets (like [[[ include foo]]] ) or, preferred,
279 [% ... %] are used.
52f3521 added mowyw to the repository
moritz authored
280
281
282 LICENSE:
283 This README file is covered by the GPL (2 or later), however
284 the code examples in this file are public domain, e.g. you may use it
285 however you like.
286 The program mowyw is published under the GPL, for details see the
287 executable
Something went wrong with that request. Please try again.