html.mk

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

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