From: Ian Jackson Date: Fri, 5 Feb 2016 23:10:56 +0000 (+0000) Subject: commitid: update docs X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=reprap-play.git;a=commitdiff_plain;h=dc45b6569107263f7a539990bf208f2efb6e4e0e;hp=c66f67af18830c44747f7bfc3819f86c36a97e47 commitid: update docs --- diff --git a/commitid.scad.pl b/commitid.scad.pl index 65963be..1ee20e8 100755 --- a/commitid.scad.pl +++ b/commitid.scad.pl @@ -1,116 +1,228 @@ #!/usr/bin/perl -w -use strict; -$SIG{__WARN__} = sub { die @_; }; +# commitid.scad.pl - a program for annotating solid models with commit info +# Copyright (C)2016 Ian Jackson. See below. There is NO WARRANTY. -# xxx much of the comment below is TODO -# -# Usage: + +# 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) +# --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) +# 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(...) A collection of polygons forming characters +# module Commitid_MODULE(...) The above, extruded up and down in Z +# 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. # -# -i do not generate `+' if git-untracked files are present +# 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. # -# [-t[FORM]] TEXT -# generate a form FORM containing TEXT -# TEXT can contain newlines (final newline usually undesirable) -# if FORM not specified, generates Arg0 Arg1 Arg2 in sequence -# character set is SPC 0-9 a-f + * # -# We generate a physical indication of which commit was used. +# Autoscaling modules +# ------------------- # -# We provide for scaling factors with dynamic variables: -# $Commitid_pixelsz if not set, we use 0.8 } multiplied -# $Commitid_scale if not set, we use 1.0 } together -# $Commitid_depth if not set, we use xy pixel size from above / 2 -# $Commitid_depth_scale if not set, we use 1.0 (multiplies depth above) -# $Commitid_max_best_scale if not set, we use 2.0 (max mult of xy in Best) +# 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_BestObjid_2D(max_sz, margin=Commitid_pixelsz()) +# module Commitid_BestObjid (max_sz, margin=Commitid_pixelsz()) # -# We have auto-sizing modules: +# max_sz should be [x,y]. # -# module Commitid_BestCount_2D(max_sz, margin=Commitid_pixelsz()) { ... } -# module Commitid_BestCount (max_sz, margin=Commitid_pixelsz()) { ... } -# module Commitid_BestObjid_2D(max_sz, margin=Commitid_pixelsz()) { ... } -# module Commitid_BestObjid (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). # -# For each form we have +# BestObjid includes as much as it can of the git commit object hash, +# and never includes any of the count. # -# module Commitid_Form_2D() { ... } -# module Commitid_Form() { ... } -# function Commitid_Form_sz() => [ x, y ] +# 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. # -# These have their origin in the bottom left corner. The 3D model -# is a positive, has its origin halfway through, and is twice the -# depth in height, so it can be added or subtracted. +# There are no `function Commitid_Best*_sz'. If they existed they +# would simply return max_sz. # -# And we provide # -# function Commitid_pixelsz() // $Commitid_pixelsz * $Commitid_scale -# function Commitid_depth() // see above +# Output format +# ------------- # -# We can generate these forms: +# 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 # -# In each case: -# if tree is dirty, * is suffixed or prefixed to count or commitid -# if tree has untracked files, + is added -# (where it is added depends on the Form; in any case it does not -# change the size, but steals space from digits) +# 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. # -# Small2 Small3 ... Small10: -# git rev-list --first-parent --count HEAD -# typically 3-4 characters but we allow for up to 6 -# padded with zeroes; if too long we reduce mod 10^n -# eg if the count is 123456 +# 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() +# 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 ... Small10 +# A single line containing as much of the count will fit, eg: # Small5 3456* -# Small8 _*123456 (where _ are spaces) -# the git objectid is included if it will fit -# unambiguously and usefully eg +# 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 ... Small10S: -# Small3T Small9T: -# same but split into two lines (S) or three lines (T) eg -# Small4S 45 Small6T _3 -# 6* 45 -# 6* -# -# Git2 Git3 ... Git10: -# Git4S Git6S ... Git10S: -# Git6T Git9T: -# git-rev-parse HEAD (prefix of requested length) -# eg if the commitid is abcdef0123... +# Small2S Small4S ... Small10S +# Small3T Small9T +# Same as Small but split into two lines (S) +# or three lines (T). Eg: +# Small4S *4 Small6T _* +# 56 34 +# 56 +# Git2 Git3 ... Git10 +# Git4S Git6S ... Git10S +# Git6T Git9T +# Just the commit object hash, in one, two (S) or three (T) +# lines. E.g.: # Git5 abcd* - +# # Full4 Full6 ... Full20: -# git-rev-list --first-parent --count HEAD -# git-rev-parse HEAD -# (all on two lines) -# eg -# Full6 abcdef Full8 abcdef01 -# 23456* _123456* +# The commit object hash plus the commit count, on +# separate lines, eg: +# Full6 abcdef Full8 abcdeffe +# *23456 _*123456 # # Full6T Full9T ... Full30T -# as Full but commit is split over two lines -# for a 3-line message; eg -# Full9T abc -# de* -# 456 +# 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 # -# Arg0, Arg1, ... -# Strings passed on command line +# 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. +# + + +use strict; + +$SIG{__WARN__} = sub { die @_; }; sub p { print @_ or die $!; }