README (5107B)
1 html.mk(5) is a static HTML content creation framework using 2 make(1) and cpp(1). 3 4 It was born out of frustration after using many complicated web "frameworks". 5 html.mk(5) re-uses existing tools and ideas as much as possible. 6 7 8 CONTENTS 9 --------- 10 11 1. Releases 12 2. Introduction 13 3. Requirements 14 4. Design 15 5. Testing 16 17 18 1. Releases 19 ------------ 20 21 Latest release: 69 on July 26, 2021 22 Download: git://0x30.net/public/html.mk 23 Install: # make install 24 Documentation: $ man html.mk 25 26 27 2. Introduction 28 ---------------- 29 30 Many static HTML content creation frameworks are in existence already 31 and a sampling of the state of the art shows hundreds of options. 32 33 The HyperText Markup Language has limited functionality and is 34 rather verbose. Other technologies like Cascading Style Sheets and 35 JavaScript attempt to give the flexibility and functionality that 36 content creators require that is not available in HTML. 37 38 html.mk(5) tries to make HTML usable without resorting 39 to dynamic client side processing in JavaScript. 40 It has two main features that make it useful: 41 42 - Preprocessing 43 - Dependency management 44 45 46 3. Requirements 47 ---------------- 48 49 - Build in tree or out of tree 50 - No duplicated boiler plate 51 - Command line driven 52 - <img> support 53 - <video> support 54 - Parallel building 55 - Customizable 56 - Testable 57 - Documented 58 - Releasable 59 60 61 4. Design 62 ---------- 63 64 Content creators sometimes have multiple pages that include similar 65 or identical content. Synchronizing that content can be laborious 66 if it cannot be stored centrally. A similar problem exists in C 67 source code: header files. This was solved with the invention of 68 the C preprocessor. While the C preprocessor is meant to be used 69 on code, it can be abused for other purposes as well. 70 71 Not only can the C preprocessor #include other text files verbatim, 72 it is also a macro processor with many other useful features. All 73 of these features are available in html.mk(5) source files. 74 75 Because the C preprocessor transforms input files to output files, 76 another utility is needed to keep track of out of date file 77 dependencies. The make(1) utility has this feature and can be 78 taught how to transform the html.mk(5) input files into output 79 files. 80 81 cpp(1) can also create dependency graphs of output files that make(1) 82 can understand to efficiently rebuild out of date output files, or 83 targets. 84 85 Content creators sometimes want images included in their pages. 86 Including full size images into a page is a waste of resources 87 because images are usually many times the resolution of displays. 88 On pages with many pictures, or on older devices, this can be a 89 problem. A solution to this is downsampling images that are included 90 in pages, but having the full resolution image available as a link 91 the downsampled thumbnail. This is a best of both worlds solution 92 as the page loads quickly and takes up minimal resources while if 93 needed the 94 user still has access to the full resolution image. 95 96 html.mk(5) uses image utilities to downsample originals before 97 including them into a page. The original is always available as a 98 link on the downsampled thumbnail. 99 100 Content creators will often organize their pages using directories. 101 html.mk(5) can accommodate this by using the bsd.subdir.mk system 102 Makefile fragment. By placing SUBDIR variable arrays in a Makefile, 103 html.mk(5) will enter those directories after it is finished in the 104 current one. 105 106 Content creators sometimes want to place output files in a completely 107 different location than the source files. html.mk(5) can accommodate 108 this by using the bsd.obj.mk system Makefile fragment. 109 110 Because html.mk(5) lives beside and uses many operating system 111 utilities using the same documentation system makes sense. The 112 mdoc(7) semantic markup language provides a great platform to write 113 documentation in. All aspects of how to use html.mk(5) are included 114 in its manual. 115 116 Automated testing ensures regression free development and easy 117 porting to new platforms. html.mk(5) uses perl(1) exclusively for 118 testing because it is very flexible and has many feature rich testing 119 modules available. All features and their error paths are intended 120 to be tested. 121 122 Releases are accomplished through use of an archive. When unpacked, 123 html.mk(5) contains an install target that will install that release 124 on the users machine. 125 126 127 5. Testing 128 129 t/_skel.t ............. skipped: template 130 t/bug_cp_xliterate.t .. ok 131 t/clean.t ............. ok 132 t/cp_happy.t .......... ok 133 t/cp_multiple.t ....... ok 134 t/cp_nodest.t ......... ok 135 t/cp_unhappy.t ........ ok 136 t/dep_complex.t ....... ok 137 t/dep_simple.t ........ ok 138 t/gen_created.t ....... ok 139 t/gen_timestamp.t ..... ok 140 t/gen_updated.t ....... skipped: not yet 141 t/img_html.t .......... ok 142 t/include_comments.t .. ok 143 t/include_subdir.t .... ok 144 t/obj_destdir.t ....... ok 145 t/smoke.t ............. ok 146 t/srcs_empty.t ........ ok 147 t/srcs_missing.t ...... ok 148 t/srcs_multiple.t ..... ok 149 t/srcs_suffix.t ....... ok 150 t/subdir_unhappy.t .... ok 151 t/xliterate.t ......... ok 152 All tests successful. 153 Files=23, Tests=183, 44 wallclock secs ( 0.62 usr 0.67 sys + 26.71 cusr 12.98 csys = 40.98 CPU) 154 Result: PASS