html.mk

static html creation framework using make(1) and cpp(1)
git clone git://0x30.net/html.mk
Log | Files | Refs | README | LICENSE

html.mk.5 (5464B)


      1 .\"
      2 .\" Copyright (c) 2021 Kyle Milz <milz@0x30.net>
      3 .\"
      4 .\" Permission to use, copy, modify, and distribute this software for any
      5 .\" purpose with or without fee is hereby granted, provided that the above
      6 .\" copyright notice and this permission notice appear in all copies.
      7 .\"
      8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
      9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
     10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
     11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
     12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
     13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
     14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
     15 .\"
     16 .Dd $Mdocdate: September 9 2021 $
     17 .Dt HTML.MK 5
     18 .Os
     19 .Sh NAME
     20 .Nm html.mk
     21 .Nd html.mk master Makefile fragment
     22 .Sh SYNOPSIS
     23 .Fd .include <bsd.html.mk>
     24 .Sh DESCRIPTION
     25 .Nm
     26 contains an HTML content creation framework using
     27 .Xr make 1
     28 and
     29 .Xr cpp 1 .
     30 .Pp
     31 This documentation contains sections covering targets, variables,
     32 ordered in alphabetical order, followed
     33 by a secion covering out of tree builds, and a section covering
     34 include suffixes.
     35 .Sh TARGETS
     36 .Bl -tag -width Ds
     37 .It Cm all
     38 The default target. Reads any input files listed in the
     39 .Ev SRCS
     40 array, creates their dependencies, then preprocesses the files
     41 into complete HTML documents.
     42 If an out of tree build is occurring, then any files in the
     43 .Ev CP_OBJ
     44 array are copied to
     45 .Ev BSDOBJDIR .
     46 .It Cm depend
     47 Creates
     48 .Pa .d
     49 files that contain dependency rules for any files in the
     50 .Ev SRCS
     51 array. Must be invoked before the 'all' target.
     52 .It Cm obj
     53 If the value of
     54 .Ev BSDOBJDIR
     55 is a directory that exists on the system, then create a new directory in
     56 .Ev BSDOBJDIR with the same name as the current directory and
     57 create a symbolic link
     58 .Pa obj
     59 in the current directory that points to the newly created directory.
     60 Otherwise create a new directory
     61 .Pa obj
     62 in the current directory.
     63 See
     64 .Sx OUT OF TREE BUILDS .
     65 .El
     66 .Sh VARIABLES
     67 The following
     68 .Pa Makefile
     69 variables influence
     70 .Nm
     71 behavior.
     72 .Bl -tag -width Ds
     73 .It Ev BSDSRCDIR
     74 This variable is only useful for
     75 .Sx OUT OF TREE BUILDS .
     76 Must contain an absolute path to the current directories parent.
     77 .It Ev BSDOBJDIR
     78 This variable is only useful for
     79 .Sx OUT OF TREE BUILDS .
     80 The destination output directory for any created objects. If the path
     81 specified does not exist, or is not a directory, the current directory
     82 is used instead.
     83 .It Ev CP_OBJ
     84 This variable is only useful for
     85 .Sx OUT OF TREE BUILDS .
     86 Any files in this array will be copied from the current directory
     87 into
     88 .Pa obj .
     89 If a file does not exist then
     90 .Xr make 1
     91 will error.
     92 .It Ev CPPFLAGS
     93 This variable is passed to all
     94 .Xr cpp 1
     95 invocations.
     96 .It Ev SRCS
     97 Any files in this array will be preprocessed by
     98 .Xr cpp 1
     99 into HTML documents. If a file specified does not exist then
    100 .Xr make 1
    101 will error.
    102 All files must have a
    103 .Pa .in
    104 suffix. After preprocessing the files will have an
    105 .Pa .html 
    106 suffix.
    107 .It Ev SUBDIR
    108 .Xr make 1
    109 will enter any directories found in this array after it has
    110 finished building the current directory. If a directory specified does not
    111 exist
    112 .Xr make 1
    113 will error.
    114 .It Ev WOBJMASK
    115 This variable is only useful for
    116 .Sx OUT OF TREE BUILDS .
    117 The umask for any created files.
    118 .El
    119 .Sh OUT OF TREE BUILDS
    120 .Nm
    121 can create many intermediate and output files and it may be desirable
    122 to put them all in a different location. This is the idea behind an
    123 out of tree build, and is similar to how other programs are built.
    124 .Pp
    125 This feature is enabled by calling the
    126 .Ic obj
    127 target. A directory tree identical to the current one
    128 .Xr make 1
    129 knows about (through
    130 .Ev SUBDIR
    131 variables) will be created under
    132 .Ev BSDOBJDIR .
    133 Any further intermediate or output files created will be placed there,
    134 instead of the current directory.
    135 .Sh INCLUDE SUFFIXES
    136 .Nm
    137 can generate HTML fragments for inclusion in source files using the
    138 .Xr cpp 1 
    139 #include directive.
    140 These fragments will depend on existing files, but have special file names.
    141 Specifically these file names will have a different suffix.
    142 What that suffix is will change what
    143 .Nm
    144 does to transform the existing file into an HTML fragment.
    145 .Pp
    146 The following suffixes are supported:
    147 .Bl -tag -width Ds
    148 .It Cm Pa .img_html
    149 The following source file suffixes are supported:
    150 .Pp
    151 .Bl -bullet -compact
    152 .It
    153 .Pa .jpg
    154 .It
    155 .Pa .jpeg
    156 .It
    157 .Pa .png
    158 .El
    159 .Pp
    160 Copies a source file with one of the above suffixes into the object
    161 directory and uses
    162 .Pa convert
    163 to create a thumbnail.
    164 Emits HTML of the form:
    165 .Bd -literal
    166 	<a href="pic_cp.jpg"><img src="pic_thumb.jpg"
    167 .Ed
    168 .Pp
    169 Note you must manually close this tag, preferably with:
    170 .Bd -literal
    171 	alt=""  /></a>
    172 .Ed
    173 .It Cm Pa .video_html
    174 The following source file suffixes are supported:
    175 .Pp
    176 .Bl -bullet -compact
    177 .It
    178 .Pa .mov
    179 .It
    180 .Pa .mp4
    181 .El
    182 .Pp
    183 Copies source video file into object directory.
    184 Emits HTML of the form:
    185 .Bd -literal
    186 <video controls>
    187 	<source src='movie.mov' type='video/mp4'>
    188 </video>
    189 .Ed
    190 .It Cm Pa .xliterate
    191 The following source file suffixes are supported:
    192 .Pp
    193 .Bl -bullet -compact
    194 .It
    195 .Pa .c
    196 .It
    197 .Pa .html
    198 .It
    199 .Pa .sh
    200 .It
    201 .Pa .txt
    202 .El
    203 .Pp
    204 Transliterates entire source file, transforming various special characters
    205 into HTML named character references. Specifically:
    206 .Pp
    207 .Bl -bullet -compact
    208 .It
    209 .Sq <
    210 .It
    211 .Sq >
    212 .It
    213 .Sq \\
    214 .It
    215 .Sq #
    216 .El
    217 .El
    218 .Sh EXIT STATUS
    219 .Ex -std
    220 .Sh SEE ALSO
    221 .Xr cpp 1
    222 .Xr make 1