Subversion Repositories wpwmm4

Rev

Rev 18 | Rev 25 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 zsolt 1
.TH wpwmm4 1 "21 Dec 2016" "" "wpwmm4 man page"
2
.SH NAME
3
wpwmm4 \- Web Page With Make and M4
4
 
5
.SH SYNOPSIS
6
Simple use the make command. The Makefile is compatible with FreeBSD's and GNU make too.
7
 
8
.SH DESCRIPTION
9
With wpwmm4 can create static web pages from
10
.I m4
11
files. The generating is done by `make'. You can use external scripts or
12
commands.
13
 
14
.SH USAGE
15
You should create a
16
.B config.mk
17
file in a directory and set the following variables inside this file. You can use
18
.I include
19
in your
20
.I config.mk
21
of course.
22
 
11 zsolt 23
.IP COMMON_DIR
24
Where the
25
.B 00_defines.m4
26
is. Commonly is the same directory as
27
.B Makefile
28
 
13 zsolt 29
.IP INCLUDE_DIR
30
The directory where the user-based includes m4 are.
31
It's relative the main source directory.
32
 
2 zsolt 33
.IP SRC_DIR
34
This variable points to the source directory where the source files (usually *.m4)
35
are. It can contain subdirectories.
36
.IP ASSETS_DIR
37
In this directory are the static files (*.css, *.js, etc.).
38
.IP DEST_DIR
39
The compiled (created) HTML's place. The subdirectory tree of
40
.I SRC_DIR
41
is created in this directory by
42
.I make.
43
.IP LAYOUT_DIR
44
Here are the layouts.
45
.IP VIRT_DIR
46
This directory contains the templates of virtual pages.
47
.IP TARGETS
48
The space-seperated list of static files (virtual pages aren't included)
49
what should create. Don't include the
50
.I ${DEST_DIR}
51
because it's included by the building system. You can
52
use directories of course.
7 zsolt 53
 
54
Its automated requirement is the same file in
55
.I ${SRC_DIR}
56
replacing
57
.I html
58
extension to
59
.I m4
60
extension.
61
 
8 zsolt 62
Tip: you can use
63
.B !=
64
assingment (run a shell command and its output will the value). In
65
this case you shouldn't add every file, you can use the
66
.I find
67
command (for example).
5 zsolt 68
.IP GREQ
69
Global requirement. It's needed by
70
.I every
71
target.
2 zsolt 72
.IP foo.html_REQ
73
Additional requirements of
74
.I foo.html
75
which is included in
76
.I ${TARGETS}
77
variable (see above). The
78
.I foo.m4
79
is automatically added. These variables are optional.
80
 
81
.IP M4
82
The
83
.I m4
84
command. In most cases can set simply to
85
.I m4
86
(in PATH). This variable is optional, default value is `m4'.
87
 
88
.IP M4_PARAMS
89
Parameters of
90
.I m4
91
command. The default value is
92
 
93
.B -P -I include -D_SRC_DIR=${SRC_DIR}
94
 
95
Please note that option
96
.B -P
97
is neccessary because we use builtin macros with
98
.I m4_
99
prefix.
100
 
101
.SH VIRTUALS
102
The virtual pages haven't source (m4) files.
103
It's useful when you want create similar pages with similar content (for example
104
listing of PDF files, listing images, ...).
105
 
106
You should create groups of
107
.B VIRTUALS
108
(you can add only ONE virtual to a group). You can do it with the following variables:
109
 
110
.IP VIRTUALS
111
Contains the name of the categories. E.g.
112
 
113
.B VIRTUALS=cat1 cat2
114
 
115
The categories is separated by a space character.
116
 
117
.IP VIRTUALTEMPLATE_*
118
You can set (following the example above)
119
.B VIRTUALTEMPLATE_cat1
120
and
121
.B VIRTUALTEMPLATE_cat2
122
variables.
123
Their values say which template should use to generate the virtual pages.
124
The templates are stored in
125
.I VIRT_DIR
126
directory.
127
 
128
In your template files you can use dynamically created variables, see
129
.B VARIABLES INSIDE SOURCES
130
section below.
131
 
132
.IP VIRTUALDIR_*
133
This variable points to the target directory where the generated pages should
134
appear. You have to set every category, so you have to set
135
.B VIRTUALDIR_cat1
136
and
137
.B VIRTUALDIR_cat2
138
too.
139
 
140
.IP VIRTUALOUT_*
141
The output filenames. For example
142
 
143
.B VIRTUALOUT_cat1=foo1.html foo2.html
144
 
145
In this case you will have
146
.I ${VIRTUALDIR_cat1}/foo1.html
147
and
148
.I ${VIRTUALDIR_cat1}/foo2.html
149
files.
150
 
151
.IP VIRTUALREQ_*
152
Additional requirements to the virtual category. The ${VIRTUALTEMPLATE_*}.m4 is added
153
automatically.
154
 
3 zsolt 155
.IP VIRTUALREQRULE_*
156
A simple transformation rule to define a requirement by file. The transformation rule
157
is applied on the elements of
158
.B VIRTUALOUT_*
159
variable. For example
160
 
161
.B VIRTUALREQ_foo=C,.html,.dat,
162
 
163
rule will transform every
164
.I .html
165
extension into
166
.I .dat
167
extension: the
168
.I ${DESTDIR}/foodir/bar.html
169
will depend on
170
.I foodir/bar.dat
171
file. Please note that the value of
172
.B ${VIRTUALDIR_*}
173
isn't included automatically so if you want it you should do it!
174
 
175
Be careful about recursive dependencies!
176
 
177
See the possible modifiers in the manual of
178
.I make
179
command!
180
 
2 zsolt 181
.SH SPECIAL TARGETS
182
You can define some special targets in your `config.mk'.
183
.IP pre-everything
184
This target will execute
185
.I before
186
any other target (except `clean' of course).
187
For example you can run a script which creates some files, even a file what is
188
used in wpwmm4. With this target can emulate the
189
.I tags
190
feature (using
191
.B VIRTUALS
192
feature).
193
 
194
Another idea is automatically generate the
195
.I ${TARGETS}
196
variable (with the `find' command).
197
 
6 zsolt 198
.IP clean-other
199
When you run
200
.I clean
201
target (which deletes everything in
202
.I ${DEST_DIR}
203
directory) it will run too.
204
 
14 zsolt 205
.SH INFORMATION TARGETS
206
There are some special targets to help debug your config.
207
.IP show-config
208
Show the main variables.
24 zsolt 209
.IP show-targets
210
Show the targets (including virtual targets).
211
.IP show-req
212
Show the targets with their requirements. The target begins a line without any
213
whitespace, the requirements are prefixed by two spaces. Between the
214
latest requirement and the next target is an empty line inserted.
14 zsolt 215
.IP show-virtuals
216
This target will show the defined virtuals and their configs.
217
 
2 zsolt 218
.SH VARIABLES INSIDE SOURCES
219
The following variables are created dynamically during building and
220
you can use them in your m4 sources and templates.
221
.IP _DIRECTORY
222
The target directory inside
223
.I ${DEST_DIR}
224
(without ${DEST_DIR} prefix). The root of
225
.I ${DEST_DIR}
226
is "." (dot).
227
.IP _FILE
228
The target filename which is under generating (without any extension).
229
 
230
.SH HELPERS
231
The system ships some helpers which you can use in your files. They are
232
defined in
233
.B 00_defines.m4
234
file. Here is the list of helpers:
235
.IP _BODY(options,content)
236
Produces <body $options>$content</body>
237
.IP _CHARSET(charset)
238
Produces <meta charset="$charset">.
239
.IP _CLASS(class1,class2,...)
240
Produces class="$class1 $class2 ..."
241
.IP _CSS(cssfile)
242
Produces <link rel="stylesheet" href=$cssfile>.
243
.IP _DIV(class,content,options)
244
Produces <div class=$class $options>$content</div>
245
.IP _HEAD(options,content)
246
Produces <head $options>$content</head>
247
.IP _HREF(url,text,options,title)
248
Produces <a href=$url $options title=$title>text</a>
249
.IP _META(parameters)
250
Produces <meta $parameters)
251
.IP _STAG(tagname,parameters)
252
Produces <$tagname $parameters>
253
.IP _TAG(tagname,content,options)
254
Produces <$tagname $options>$content</$tagname>.
255
.IP _TITLE(title,options)
256
Produces <title $options>$title</title>
257
 
258
.SH BUILT-IN COMMANDS
259
There are some commands which can help. They are defined in
260
.B 00_defines.m4
261
too. Here is the list:
262
.IP _SCRIPT(command)
263
Executes $command and paste its output (stdout and stderr too). It
264
uses the m4's
265
.B esyscmd
266
macro.
18 zsolt 267
.IP _LAYOUT(layout,VarName1,Var1,VarName2,Var2,...)
2 zsolt 268
Load the $layout layout. It uses m4's
269
.B include
270
macro. You can define the web page layout at the beginning of source file.
18 zsolt 271
 
272
This command will assign the variables VarName1, VarName2,... with values Var1, Var2.
17 zsolt 273
.IP _LAYOUT_PRE(pre)
274
The $pre is printed before the included content.
275
.IP _LAYOUT_POST(post)
276
The $post is printed after the included content.
9 zsolt 277
.IP _INCL(file)
278
Includes a $file. The
279
.B divert
280
is -1 so this macro doesn't produce any output. It's ideal to load
281
a file with macro definitions.
282
.IP _2_BODY(*)
283
The $* will into the
284
.I body
285
tag. This macro collects all inputs and doesn't print
286
anything. With
287
.B _PR_BODY
288
can print (and empty) the content (a simple
289
.B undivert
290
macro).
291
.IP _2_HEAD(*)
292
Same as
293
.B _2_BODY
294
but it collects into
295
.I head
296
tag.
297
.IP _PR_HEAD
298
Similar as PR_BODY.
299
.IP _PR_ALL
300
It prints
301
.I <!DOCTYPE html><html>
302
after calls
303
.B _PR_HEAD
304
and
305
.B _PR_BODY
306
and after close the
307
.I html
308
tag.
2 zsolt 309
.SH FILES
310
config.mk
311
 
312
.SH SEE ALSO
313
.B m4(1)
3 zsolt 314
.B make(1)
2 zsolt 315
 
316
.SH AUTHOR
317
Zsolt Udvari (udvzsolt@gmail.com, www.uzsolt.hu)