commit 815889ae684b9e5ac72f8cdc693e7d210738e146
parent f57d931dce4d4b50b52f522b151f6b5cd41ec5fb
Author: Kyle Milz <krwmilz@gmail.com>
Date: Wed, 17 Nov 2021 05:23:59 +0000
add README
contents are from the old html page
Diffstat:
| A | README | | | 160 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 160 insertions(+), 0 deletions(-)
diff --git a/README b/README
@@ -0,0 +1,160 @@
+html.mk(5) 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".
+html.mk(5) 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://0x30.net/public/html.mk
+Install: # make install
+Documentation: $ man html.mk
+
+
+ 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.
+
+html.mk(5) 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
+ - <img> support
+ - <video> 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
+html.mk(5) 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 html.mk(5) 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.
+
+html.mk(5) 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.
+html.mk(5) can accommodate this by using the
+bsd.subdir.mk system Makefile fragment. By placing
+SUBDIR variable arrays in a Makefile,
+html.mk(5) 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. html.mk(5)
+can accommodate this by using the bsd.obj.mk system
+Makefile fragment.
+
+Because html.mk(5) 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
+html.mk(5) are included in its manual.
+
+Automated testing ensures regression free development and easy
+porting to new platforms. html.mk(5) 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,
+html.mk(5) 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
