1 c590d32c 2022-09-29 op .\" Copyright (c) 2022 Omar Polo <op@openbsd.org>
 2 c590d32c 2022-09-29 op .\"
 3 c590d32c 2022-09-29 op .\" Permission to use, copy, modify, and distribute this software for any
 4 c590d32c 2022-09-29 op .\" purpose with or without fee is hereby granted, provided that the above
 5 c590d32c 2022-09-29 op .\" copyright notice and this permission notice appear in all copies.
 6 c590d32c 2022-09-29 op .\"
 7 c590d32c 2022-09-29 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 8 c590d32c 2022-09-29 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 9 c590d32c 2022-09-29 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 c590d32c 2022-09-29 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 c590d32c 2022-09-29 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 c590d32c 2022-09-29 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 c590d32c 2022-09-29 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 c590d32c 2022-09-29 op .\"
15 c590d32c 2022-09-29 op .Dd September 27, 2022
16 c590d32c 2022-09-29 op .Dt TEMPLATE 1
17 c590d32c 2022-09-29 op .Os
18 c590d32c 2022-09-29 op .Sh NAME
19 c590d32c 2022-09-29 op .Nm template
20 c590d32c 2022-09-29 op .Nd templating system compiler
21 c590d32c 2022-09-29 op .Sh SYNOPSIS
22 c590d32c 2022-09-29 op .Nm
23 c590d32c 2022-09-29 op .Op Fl G
24 c590d32c 2022-09-29 op .Op Ar
25 c590d32c 2022-09-29 op .Sh DESCRIPTION
26 c590d32c 2022-09-29 op .Nm
27 c590d32c 2022-09-29 op is an utility that converts files written in the
28 c590d32c 2022-09-29 op .Xr template 7
29 c590d32c 2022-09-29 op format format to a set of routine writtens in the C programming
30 c590d32c 2022-09-29 op language.
31 c590d32c 2022-09-29 op .Nm
32 c590d32c 2022-09-29 op converts the files given as arguments or from standard input, and
33 c590d32c 2022-09-29 op writes to standard output.
34 c590d32c 2022-09-29 op .Pp
35 c590d32c 2022-09-29 op The options are as follows:
36 c590d32c 2022-09-29 op .Bl -tag -width Ds
37 c590d32c 2022-09-29 op .It Fl G
38 c590d32c 2022-09-29 op Do not emit debug info in the generated source.
39 c590d32c 2022-09-29 op It's disabled by default, unless
40 c590d32c 2022-09-29 op .Nm
41 c590d32c 2022-09-29 op is reading from standard input.
42 c590d32c 2022-09-29 op .El
43 c590d32c 2022-09-29 op .Sh EXIT STATUS
44 c590d32c 2022-09-29 op .Ex
45 c590d32c 2022-09-29 op .Sh EXAMPLES
46 c590d32c 2022-09-29 op The following example shows how to use
47 c590d32c 2022-09-29 op .Nm
48 c590d32c 2022-09-29 op in a Makefile:
49 c590d32c 2022-09-29 op .Bd -literal -offset indent
50 c590d32c 2022-09-29 op \&.SUFFIXES: .c .tmpl
51 c590d32c 2022-09-29 op \&.c.tmpl:
52 c590d32c 2022-09-29 op 	template $< > $@ || rm \-f $@
53 c590d32c 2022-09-29 op .Ed
54 c590d32c 2022-09-29 op .Sh SEE ALSO
55 c590d32c 2022-09-29 op .Xr template 7
56 c590d32c 2022-09-29 op .Sh AUTHORS
57 c590d32c 2022-09-29 op .An -nosplit
58 c590d32c 2022-09-29 op The
59 c590d32c 2022-09-29 op .Nm
60 c590d32c 2022-09-29 op utility was written by
61 c590d32c 2022-09-29 op .An Omar Polo Aq Mt op@openbsd.org .
62 c590d32c 2022-09-29 op .Sh CAVEATS
63 c590d32c 2022-09-29 op The compiler is very naive, so there are quite a few shortcomings:
64 c590d32c 2022-09-29 op .Bl -bullet -compact
65 c590d32c 2022-09-29 op .It
66 c590d32c 2022-09-29 op No attempt is made to validate the C code provided inline, nor the
67 c590d32c 2022-09-29 op validity of the arguments to many constructs.
68 c590d32c 2022-09-29 op .It
69 c590d32c 2022-09-29 op The generated code assumes that a variable called
70 c590d32c 2022-09-29 op .Va tp
71 c590d32c 2022-09-29 op of type
72 c590d32c 2022-09-29 op .Vt struct template *
73 c590d32c 2022-09-29 op is in scope inside the template.
74 c590d32c 2022-09-29 op .It
75 c590d32c 2022-09-29 op Each block may have additional variables used for the template
76 c590d32c 2022-09-29 op generation: to avoid clashes, don't define variables with the
77 c590d32c 2022-09-29 op .Sq tp_
78 c590d32c 2022-09-29 op prefix.
79 c590d32c 2022-09-29 op .It
80 c590d32c 2022-09-29 op Blanks are, in most cases, trimmed.
81 c590d32c 2022-09-29 op Normally this is not a problem, but a workaround is needed in case
82 c590d32c 2022-09-29 op they need to be preserved, for e.g.:
83 c590d32c 2022-09-29 op .Bd -literal -offset indent
84 c590d32c 2022-09-29 op Name: {{ " " }} {{ render name_field(tp) }}
85 c590d32c 2022-09-29 op .Ed
86 c590d32c 2022-09-29 op .El