# $Id$

BSPPFit
=======

A taxonomy of British Standard Pipe Parallel (BSPP) fittings, paired
with a 3D model library suitable for fabrication via FDM 3D printing.

The project pursues two intertwined goals:

  1. /Taxonomy/ --- making the BSPP fittings domain intelligible to a
     non-specialist. BSPT and NPT are present as adjacent classes
     for confusion-avoidance; they are not the focus.

  2. /3D model library/ --- producing printable parametric models for
     the fittings the taxonomy describes. The modeling foundation is
     OpenSCAD with the BOSL2 library, in particular BOSL2's BSPP
     threading module (commit e5b0fcf, January 2026).


Documents
---------

All project documents live under Doc/ in Org-mode format. PDF and
HTML are produced by the build system; the .org files are the
canonical sources.

  Doc/Concept.org             Project goal, scope, deliverables
  Doc/Constitution.org        Collaboration rules (read-only)
  Doc/DevelopmentStandard.org Coding and documentation conventions
  Doc/Taxonomy.org            The BSPP taxonomy (Phase 1 seed)
  Doc/ResearchJournal.org     Decisions, dead ends, rationale
  Doc/FutureResearch.org      Open questions, pending investigations


Build prerequisites
-------------------

Required (configure will fail if absent):

  * GNU autotools (autoconf, automake)
  * GNU Make (the project uses %-style pattern rules)
  * Emacs with Org-mode (for PDF/HTML export of documents)
  * LuaLaTeX with the packages listed in Doc/Preamble.tex
    (in particular: fontspec, unicode-math, hyperref, svninfo,
    booktabs, enumitem, fancyhdr, xcolor)

Recommended (configure will warn; build falls back to a four-pass
LuaLaTeX run for stable cross-references):

  * latexmk

Optional --- only needed by documents that use the corresponding
diagram source language:

  * Graphviz (dot) --- taxonomy trees and dependency graphs
  * PlantUML --- sequence and state diagrams
  * Inkscape --- annotated SVG illustrations
  * TikZ (via texlive-pictures, texlive-science) --- dimensioned
    drawings and thread cross-sections

For the eventual 3D model library:

  * OpenSCAD
  * BOSL2 library (see "BOSL2 setup" below)

For colorised source blocks in HTML export, install /htmlize.el/
version 1.34 or later (e.g. via MELPA). Without it, source blocks
fall back to plain text without warnings.


Build
-----

From a fresh checkout:

  ./bootstrap        # autoreconf --install --symlink (developer)
  ./configure        # checks tools; ends with a summary of paths
  make               # build the PDF documents (default target)

From a distribution tarball produced by "make dist", the bootstrap
step is not needed; ./configure is already shipped.

Useful targets:

  make               # default: build PDFs of all Doc/*.org documents
  make pdf           # same as the default
  make html          # generate HTML of all Doc/*.org documents
  make dist          # produce BSPPFit-VERSION.tar.xz (autotools form)
  make clean         # remove build artifacts
  make maintainer-clean
                     # remove everything regeneratable, including
                     # autotools-generated files


BOSL2 setup
-----------

The 3D model library depends on the BSPP threading module shipped
with BOSL2 since commit e5b0fcf (January 2026). Install procedure:

  1. Clone BOSL2 to a stable location:

       git clone https://github.com/BelfrySCAD/BOSL2 \
                 ~/somewhere/BOSL2

  2. Make it visible to OpenSCAD via a symbolic link in OpenSCAD's
     standard library directory:

       cd ~/.local/share/OpenSCAD/libraries
       ln -s ~/somewhere/BOSL2 BOSL2

  3. Confirm reachability from a test .scad file:

       include <BOSL2/std.scad>
       include <BOSL2/threading.scad>

The BSPP API in BOSL2 is stable and not subject to breaking changes
(per ResearchJournal.org).


Two archive forms
-----------------

The project ships in two archive forms, intentionally:

  * /Distribution archive/ (autotools "make dist") ---
    BSPPFit-VERSION.tar.xz with a wrapped BSPPFit-VERSION/ top
    directory, per the autotools convention. Suitable for
    redistribution.

  * /Collaboration delivery archive/ ---
    BSPPFit-VERSION.tar.xz produced by

      tar cJf BSPPFit-VERSION.tar.xz \
              --exclude-from=.tar-exclude \
              -C BSPPFit-VERSION .

    /without/ the wrapping directory, so files extract directly
    into the current directory. Used for iteration deliveries
    where the recipient integrates the contents into a working
    tree.

Both forms are documented in the Development Standard.


License
-------

GNU General Public License, version 3 or later. See COPYING for the
full text.


Authors
-------

See AUTHORS.
