From 044b1b6cd5189d0738f9c1382d5971eff717bae1 Mon Sep 17 00:00:00 2001
From: Adrien Hopkins <adrien.p.hopkins@gmail.com>
Date: Sat, 24 Feb 2024 20:22:03 -0500
Subject: Add specification for data files

I will have to change a few things to fit this specification; all the
better that I made it instead of leaving behaviour unspecified!
---
 docs/data_spec.tex | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/data_spec.tex

(limited to 'docs/data_spec.tex')

diff --git a/docs/data_spec.tex b/docs/data_spec.tex
new file mode 100644
index 0000000..9bcbe14
--- /dev/null
+++ b/docs/data_spec.tex
@@ -0,0 +1,74 @@
+% Created 2024-03-03 Sun 10:48
+% Intended LaTeX compiler: pdflatex
+\documentclass[11pt]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{graphicx}
+\usepackage{longtable}
+\usepackage{wrapfig}
+\usepackage{rotating}
+\usepackage[normalem]{ulem}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{capt-of}
+\usepackage{hyperref}
+\usepackage[a4paper, lmargin=25mm, rmargin=25mm, tmargin=25mm, bmargin=25mm]{geometry}
+\date{2024 February 24}
+\title{7Units Datafile Specification\\\medskip
+\large For Version 0.5.0}
+\hypersetup{
+ pdfauthor={},
+ pdftitle={7Units Datafile Specification},
+ pdfkeywords={},
+ pdfsubject={},
+ pdfcreator={Emacs 29.2 (Org mode 9.6.15)}, 
+ pdflang={English}}
+\begin{document}
+
+\maketitle
+\tableofcontents
+
+\newpage
+\section{Unit and Prefix Files}
+\label{sec:org2a50c60}
+Unit and prefix files specify the units and prefixes that are available to 7Units.  Their format is intended to be compatible with 7Units's inspiration, \href{https://www.gnu.org/software/units/}{GNU Units}.
+
+Each unit or prefix is specified by a line in the following format:
+\begin{verbatim}
+<name><one or more whitespace><definition>
+\end{verbatim}
+
+The name may not contain whitespace, but the definition can and often will.  Lines can be separated by either a line feed (0x0A) or a carriage return followed by a line feed (0x0D 0x0A).
+\subsection{Ignored Lines \& Comments}
+\label{sec:orgf5f4195}
+All of the following should be ignored:
+\begin{itemize}
+\item Any line containing only whitespace
+\item Any trailing whitespace
+\item Any characters between a \texttt{\#} (0x23) character and the end of the line.
+\end{itemize}
+
+This allows unit and prefix files to be easily organized and divided.
+\subsection{Unit Expressions}
+\label{sec:org7ab7828}
+The definition part of a unit's line is a unit expression - the same sort of expression you would use in the complex unit converter.
+
+Expressions should be a standard mathematical expression, which can operate on either numbers or units.  The following operators are supported: addition (+), subtraction (-), multiplication (\texttt{*} or no operator), division (\texttt{/}), exponentation (\texttt{\textasciicircum{}}; exponent must be a number).  Brackets (\texttt{(} and \texttt{)}) may be used to change order of operations, but otherwise standard BEDMAS order is followed (exponentation first, then multiplication and division, then addition and subtraction), with one exception: if a number is multiplied by a unit using spaces, the multiplication will have precedence over division.  For example, "2 m / 1 m" is equal to the dimensionless value 2, not 2 m\textsuperscript{2}.  An example of a line defining a unit is:
+\begin{verbatim}
+yard	9 dm + 1.4 cm + 4 mm^2 / 10 mm
+\end{verbatim}
+
+If the definition is an exclamation mark (\texttt{!}), this defines a base unit, which is expected to already be stored in the system.
+\subsection{Prefixes \& Prefix Expressions}
+\label{sec:orgf36901d}
+If a line's name part ends in the ASCII dash (\texttt{-}, 0x2D), it defines a prefix instead of a unit (this dash is not included in the prefix's name).  Prefix expressions are like unit expressions, but the operands are prefixes and numbers, not units and numbers.  Because prefixes do not have a dimension, there are no base prefixes - the exclamation mark is forbidden in prefix expressions.
+\section{Dimension Files}
+\label{sec:org42d746d}
+Dimension files give names to unit dimensions, so they can be selected in the unit converter to determine which units are shown.  Dimension files are similar to unit and prefix files, except that they use a different set of base \emph{dimensions} (defined with ! as usual), and that addition and subtraction are not supported in dimension expressions.
+\section{Metric Exception Files}
+\label{sec:org2390d67}
+Metric exception files list exceptions to the One-Way Conversion rule.  Units included in these files are always shown on both sides of the unit converter, even if One Way Conversion is enabled.  They are just a list of units, one per line.  Ignored lines and comments work the same way as in other data files.
+\section{Configuration Files}
+\label{sec:orgef3d7a7}
+A configuration file contains one line for each configuration setting, in the format \texttt{key=value}.  Check the user manual for the list of configurable setting keys.  Ignored lines and comments work the same way as in other data files.
+\end{document}
-- 
cgit v1.2.3

