+
+# commitid.scad.pl - a program for annotating solid models with commit info
+# Copyright (C)2016 Ian Jackson. See below. There is NO WARRANTY.
+
+
+# USAGE
+# =====
+#
+# .../commitid.scad.pl [OPTION...] [STRING...] >commitid.scad.new \
+# && mv -f commitid.scad.new commitid.scad
+#
+# Run without arguments, commitid.scad.pl will output an openscad file
+# which contains 2D and 3D models of the current git commit count and
+# commit object id (commit hash), useful for identifying printed
+# parts.
+#
+# See below for details. You probably want these two sections, as a
+# quick starting point:
+# General form of provided openscad modules
+# Autoscaling modules
+#
+# We can also generate models of short mainly-numeric strings
+# specified on the command line.
+#
+#
+# Options:
+#
+# --git Generate git commit indications, as shown below
+# (this is the default if no strings are requested with -t).
+# Ie, produce the `Autoscaling modules' and `Specific layouts'.
+#
+# --git=objid
+# Generate git commit indication based on commit object only
+# (ie avoid counting commits). Ie, do not generate `Small'
+# and `Full' layouts (and never select them for `Best').
+#
+# -i Do not generate `+' dirty indication if git-untracked files
+# are present (ie, missing .gitignore entries). The `*'
+# dirty tree indication (for modified files) cannot be disabled.
+#
+# [-t[LAYOUT]] TEXT
+# Generate a layout LAYOUT containing TEXT. TEXT can
+# contain newlines (a final newline usually undesirable, as
+# it will generate a blank line). If LAYOUT is not specified,
+# generates Arg0, Arg1, Arg2, etc., for successive such
+# TEXTs. The permissible character set in is TEXT is:
+# space 0-9 a-f + *
+#
+#
+# OPENSCAD INTERFACE
+# ==================
+#
+# Dynamic variables for configuration
+# -----------------------------------
+#
+# We honour the following variables to control various scaling factors:
+#
+# default value notes
+# $Commitid_pixelsz 0.8 \ multiplied together
+# $Commitid_scale 1.0 /
+# $Commitid_depth pixelsz/2 \ multiplied together
+# $Commitid_depth_scale 1.0 /
+# $Commitid_max_best_scale 2.0 limits XY scaling in *Best*
+#
+# FYI the font is nominally 3x5 pixels, with 1-pixel inter-line and
+# inter-character gaps. (It's not strictly speaking a 3x5 bitmap
+# font, size it contains partial pixels and diagonals.)
+#
+#
+# Non-`module'-specific functions
+# -------------------------------
+#
+# We provide the following functions (which depend on the config
+# variables, but not on anything else) and compute useful values:
+#
+# function Commitid_pixelsz() Actual size of each nominal pixel
+# function Commitid_depth() Depth to use (the amount characters
+# should be raised or sunken)
+#
+# General form of provided openscad modules
+# -----------------------------------------
+#
+# module Commitid_MODULE_2D(...) Collection of polygons forming characters
+# module Commitid_MODULE(...) The above, extruded up and down in Z
+# module Commitid_MODULE_M_2D(...) Mirror writing
+# module Commitid_MODULE_M(...) 3D mirror writing
+# function Commitid_MODULE_sz() A 2-vector giving the X,Y size
+#
+# Except for *Best* modules, the XY origin is in the bottom left
+# corner without any margin. Likewise Commitid_MODULE_sz does not
+# include any margin.
+#
+# For 3D versions, the model is 2*depth deep and the XY plane bisects
+# the model. This means it's convenient to either add or subtract from
+# a workpiece whose face is in the XY plane.
+#
+# The _M versions are provided to avoid doing inconvenient translation
+# and rotation to get the flipped version in the right place.
+#
+#
+# Autoscaling modules
+# -------------------
+#
+# These modules take a specification of the available XY space, and
+# select and generate a suitable specific identification layout:
+#
+# module Commitid_BestCount_2D (max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestCount (max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestCount_M_2D(max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestCount_M (max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestObjid_2D (max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestObjid (max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestObjid_M_2D(max_sz, margin=Commitid_pixelsz())
+# module Commitid_BestObjid_M (max_sz, margin=Commitid_pixelsz())
+#
+# max_sz should be [x,y].
+#
+# BestCount includes (as much as it can of) the git commit count,
+# ie the result of
+# git rev-list --first-parent --count HEAD
+# (and it may include some of the git revision ID too).
+#
+# BestObjid includes as much as it can of the git commit object hash,
+# and never includes any of the count.
+#
+# All of these will autoscale and autorotate the selected model, and
+# will include an internal margin of the specified size (by default,
+# one pixel around each edge). If no margin is needed, pass margin=0.
+#
+# There are no `function Commitid_Best*_sz'. If they existed they
+# would simply return max_sz.
+#
+#
+# Output format
+# -------------
+#
+# In general the output, although it may be over multiple lines,
+# is always in this order
+# git commit object id (hash)
+# dirty indicator
+# git commit count
+#
+# Not all layouts have all these parts. The commit object id may
+# sometimes be split over multiple lines, but the count will not be.
+# If both commit id and commit count appear they will be separated
+# by (at least) a newline, or a dirty indicator, or a space.
+#
+# The commit id is truncated to fit, from the right.
+#
+# The commit count is truncated from the _left_, leaving the least
+# significant decimal digits.
+#
+# The dirty indicator can be
+#
+# * meaning the working tree contains differences from HEAD
+#
+# + meaning the working tree contains untracked files
+# (ie files you have failed to `git add' and also failed
+# to add to gitignore). (But see the -i option.)
+#
+#
+# Specific layouts
+# ----------------
+#
+# If you want to control the exact layout (and make space for it in
+# your design), you can use these:
+#
+# module Commitid_LAYOUT_2D()
+# module Commitid_LAYOUT()
+# module Commitid_LAYOUT_M_2D()
+# module Commitid_LAYOUT_M()
+# function Commitid_LAYOUT_sz()
+#
+# Here LAYOUT is one of the following (giving for example, `module
+# Commitid_Full8_2D'). In the examples, we will assume that the tree
+# is dirty, the commit count is 123456, and the commit object id
+# starts abcdeffedbcaabcdef... In the examples `_' shows where a
+# space would be printed.
+#
+# Small2 Small3 ... Small9 Small10 Small12 Small14 Small16
+# A single line containing as much of the count will fit, eg:
+# Small5 3456*
+# Small8 _*123456
+# The objectid is included if more than one character of of it
+# will fit without makign the output ambiguous:
+# Small9 ab*123456
+#
+# Small2S Small4S ... Small16S
+# Small3T Small9T Small12T
+# Same as Small but split into two lines (S)
+# or three lines (T). Eg:
+# Small4S *4 Small6T _*
+# 56 34
+# 56
+# Git2 Git3 ... Git9 Git10 Git12 Git14 Git16
+# Git4S Git6S ... Git16S
+# Git6T Git9T Git12T
+# Just the commit object hash, in one, two (S) or three (T)
+# lines. E.g.:
+# Git5 abcd*
+#
+# Full4 Full6 ... Full20:
+# The commit object hash plus the commit count, on
+# separate lines, eg:
+# Full12 abcdef Full16 abcdeffe
+# *23456 _*123456
+#
+# Full6T Full9T ... Full30T
+# As Full but the commit object id is split over two lines
+# producing a 3-line layout, eg:
+# Full9T abc Full21T abcdeff
+# de* edbcaa*
+# 456 _123456
+#
+# Other LAYOUTs
+# -------------
+#
+# FontDemo
+#
+# A demonstration of the built-in 18-character font
+#
+# Arg0 Arg1, ...
+#
+# Strings passed on command line (without -t, or bare -t,
+# rather than with -tLAYOUT).
+#
+# LAYOUT
+#
+# Generated by passing -tLAYOUT on the command line.
+#
+
+
+# COPYRIGHT, LICENCE AND LACK-OF-WARRANTY INFORMATION
+# ===================================================
+#
+# This program is Free Software and a Free Cultural Work.
+#
+# You can redistribute it and/or modify it under the terms of the
+# GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+# Alternatively, at your option:
+#
+# This work is licensed under the Creative Commons
+# Attribution-ShareAlike 4.0 International License.
+#
+# There is NO WARRANTY.
+
+