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