template/template.1

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