static html creation framework using make(1) and cpp(1)
Log | Files | Refs | README | LICENSE

commit 815889ae684b9e5ac72f8cdc693e7d210738e146
parent f57d931dce4d4b50b52f522b151f6b5cd41ec5fb
Author: Kyle Milz <>
Date:   Wed, 17 Nov 2021 05:23:59 +0000


contents are from the old html page

AREADME | 160+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 160 insertions(+), 0 deletions(-)

diff --git a/README b/README @@ -0,0 +1,160 @@ is a static HTML content creation framework using +make(1) and cpp(1). + +It was born out of frustration after using many complicated web "frameworks". re-uses existing tools and ideas as much as possible. + + + CONTENTS +--------- + + 1. Releases + 2. Introduction + 3. Requirements + 4. Design + 5. Testing + + + 1. Releases +------------ + +Latest release: 69 on July 26, 2021 +Download: git:// +Install: # make install +Documentation: $ man + + + 2. Introduction +---------------- + +Many static HTML content creation frameworks are in existence already +and a sampling of the state of the art shows hundreds of options. + +The HyperText Markup Language has limited functionality and is +rather verbose. Other technologies like Cascading Style Sheets and +JavaScript attempt to give the flexibility and functionality that +content creators require that is not available in HTML. + tries to make HTML usable without resorting +to dynamic client side processing in JavaScript. +It has two main features that make it useful: + + - Preprocessing + - Dependency management + + + 3. Requirements +---------------- + + - Build in tree or out of tree + - No duplicated boiler plate + - Command line driven + - &lt;img&gt; support + - &lt;video&gt; support + - Parallel building + - Customizable + - Testable + - Documented + - Releasable + + + 4. Design +---------- + +Content creators sometimes have multiple pages that include similar or +identical content. Synchronizing that content can be laborious if it +cannot be stored centrally. +A similar problem exists in C source code: header files. +This was solved with the +invention of the C preprocessor. While the C preprocessor is meant +to be used on code, it can be abused for other purposes as well. + +Not only can the C preprocessor #include other text +files verbatim, it is also a macro processor with many other useful +features. All of these features are available in source files. + +Because the C preprocessor transforms input files to output files, +another utility is needed to keep track of out of date file +dependencies. +The make(1) utility has this feature and can be taught +how to transform the input files into output +files. + +cpp(1) can also create dependency graphs of output files +that +make(1) can understand to efficiently rebuild out of date +output files, or targets. + +Content creators sometimes want images included in their pages. +Including full size images into a page is a waste of resources +because images are usually many times the resolution of displays. +On pages with many pictures, or on older devices, this can be a +problem. A solution to this is downsampling images that are included +in pages, but having the full resolution image available as a link +the downsampled thumbnail. This is a best of both worlds solution +as the page loads quickly and takes up minimal resources while if +needed the +user still has access to the full resolution image. + uses image utilities to downsample originals +before including them into a page. The original is always available +as a link on the downsampled thumbnail. + +Content creators will often organize their pages using directories. can accommodate this by using the system Makefile fragment. By placing +SUBDIR variable arrays in a Makefile, will enter those directories after it is +finished in the current one. + +Content creators sometimes want to place output files in a completely +different location than the source files. +can accommodate this by using the system +Makefile fragment. + +Because lives beside and uses many operating +system utilities using the same documentation system makes sense. +The mdoc(7) semantic markup language provides a great +platform to write documentation in. All aspects of how to use are included in its manual. + +Automated testing ensures regression free development and easy +porting to new platforms. uses +perl(1) exclusively for testing because it is very +flexible and has many feature rich testing modules available. +All features and their error paths are intended to be tested. + +Releases are accomplished through use of an archive. When unpacked, contains an install target that +will install that release on the users machine. + + + 5. Testing + +t/_skel.t ............. skipped: template +t/bug_cp_xliterate.t .. ok +t/clean.t ............. ok +t/cp_happy.t .......... ok +t/cp_multiple.t ....... ok +t/cp_nodest.t ......... ok +t/cp_unhappy.t ........ ok +t/dep_complex.t ....... ok +t/dep_simple.t ........ ok +t/gen_created.t ....... ok +t/gen_timestamp.t ..... ok +t/gen_updated.t ....... skipped: not yet +t/img_html.t .......... ok +t/include_comments.t .. ok +t/include_subdir.t .... ok +t/obj_destdir.t ....... ok +t/smoke.t ............. ok +t/srcs_empty.t ........ ok +t/srcs_missing.t ...... ok +t/srcs_multiple.t ..... ok +t/srcs_suffix.t ....... ok +t/subdir_unhappy.t .... ok +t/xliterate.t ......... ok +All tests successful. +Files=23, Tests=183, 44 wallclock secs ( 0.62 usr 0.67 sys + 26.71 cusr 12.98 csys = 40.98 CPU) +Result: PASS