POM website

author: pommicket <pommicket@gmail.com> 2025-09-23 14:26:18 -0400
committer: pommicket <pommicket@gmail.com> 2025-09-23 14:26:18 -0400
commit: ee57036c9cfdff27a81a38a9c5abc3b631f3a83c (patch)
tree: 812ad4393c68b0575c4010d9b25d39e20ceefb1c
parent: 6ae91130c7c2ff1c11ecfe5798d8037954a4d570 (diff)
13 files changed, 222 insertions, 50 deletions
diff --git a/pre-commit.sh b/pre-commit.sh
index 5930194..86f6dac 100755
--- a/pre-commit.sh
+++ b/pre-commit.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 # Check with Nu validator (https://github.com/validator/validator) if installed
-which vnu >/dev/null && vnu site/*.html || exit 1
-for file in site/*.html; do
+which vnu >/dev/null && vnu site/*.html site/tests/*.html || exit 1
+for file in site/*.html site/tests/*.html; do
 	# /dev/null is to force file names to be printed (grep -H is a GNU extension)
 	if grep -n '\s$' /dev/null $file; then
 		echo "$file has trailing white space."
diff --git a/site/index.html b/site/index.html
index e1d086a..b3b96de 100644
--- a/site/index.html
+++ b/site/index.html
@@ -1,12 +1,80 @@
 <!DOCTYPE html>
+<!--TODO:
+- make icon
+-->
 <html lang="en">
 <head>
 	<meta charset="utf-8">
 	<meta content="width=device-width,initial-scale=1" name="viewport">
 	<title>POM Configuration Language</title>
-	<link rel="icon" href="data:,"><!--TODO-->
+	<link rel="icon" href="/icon.png">
 </head>
 <body>
-	<h3>Coming soon</h3>
+	<h1>POM Configuration Language</h1>
+	<ul>
+		<li><a href="/spec.html">Specification (v. 0.1.0)</a></li>
+		<li><a href="/tests/index.html">Test suite</a></li>
+	</ul>
+	<p>
+		The POM configuration language (short for property object model, or perhaps, pommicket’s obvious-<i>er</i> markup)
+		is a “markup” language designed for writing software configurations. Unlike other markup languages,
+		which have overwrought syntax and strange corner cases, POM’s syntax is designed to be as simple as possible,
+		to minimize confusion and to make it easier to write a parser for it.
+		For example, the official Python library is under 600 lines of code, including documentation.
+	</p>
+	<p>
+		At its core, a POM configuration is an association between keys and values.
+		Keys are string identifiers chosen by the application to refer to settings in the configuration;
+		these can use <code>a-zA-Z0-9_./*-</code> and non-ASCII characters.
+		Values can be any Unicode strings not containing a null character.
+	</p>
+	<pre><code># A POM configuration for a text editor
+
+indentation-type = tabs
+show-line-numbers = yes
+tab-size = 4
+font-size = 18
+
+file-extensions.python = .py
+[file-extensions]
+C = .c, .h
+Cpp = .cpp, .hpp, .cc, .hh
+
+[plug-in.edit-over-ssh]
+path = "~/misc/edit-over-ssh.so"
+enabled = yes
+
+[plug-in.wrap-text]
+path = "~/misc/wrap_text_v3.5.7.so"
+enabled = no
+	</code></pre>
+	<p>
+		The POM syntax has no distinction between different types of data (numbers, strings, booleans).
+		Instead, this is handled in the code which reads the configuration, using different
+		functions/methods to parse values as various data types.
+		The mapping from string values to signed and unsigned integers, floating-point numbers,
+		booleans, and lists is defined in the specification.
+	</p>
+	<h2>Libraries</h2>
+	<p>
+		Currently the following official POM parsing libraries exist:
+	</p>
+	<ul>
+		<li>C/C++: <a href="https://github.com/pommicket/pom-c">libpom/libpom++</a></li>
+		<li>Python: <a href="https://pypi.org/project/pom-parser">pom_parser</a></li>
+		<li>Rust: <a href="https://crates.io/crates/pom-parser">pom-parser</a></li>
+	</ul>
+	<h2>Contributing</h2>
+	<p>
+		Contributions are welcome! Some particular areas where you might want to help out:
+	</p>
+	<ul>
+		<li>Clarifying any ambiguities you might find in the specification.</li>
+		<li>Writing more examples for POM parsing libraries.</li>
+		<li>Writing more <a href="/tests/index.html">tests</a> to handle cases that aren’t currently covered.</li>
+		<li>Fixing typos in documentation.</li>
+		<li>Fixing bugs in parsing libraries.</li>
+		<li>Writing parsing libraries (or bindings to existing ones) for more programming languages.</li>
+	</ul>
 </body>
 </html>
diff --git a/site/spec.html b/site/spec.html
index 704395b..64b3802 100644
--- a/site/spec.html
+++ b/site/spec.html
@@ -13,7 +13,7 @@
 	}
 	</style>
 	<title>POM Language Specification</title>
-	<link rel="icon" href="data:,"><!--TODO-->
+	<link rel="icon" href="/icon.png">
 </head>
 
 <body>
diff --git a/site/tests/errors.html b/site/tests/errors.html
new file mode 100644
index 0000000..eeaacfa
--- /dev/null
+++ b/site/tests/errors.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta content="width=device-width,initial-scale=1" name="viewport">
+	<title>POM error tests</title>
+	<link rel="icon" href="/icon.png">
+</head>
+<body>
+<p>
+	<a href="/index.html">POM homepage</a> · <a href="/tests/index.html">POM tests</a>
+</p>
+<h2>Error tests for POM</h2>
+
+<p>
+	These tests are found in the <code>tests/errors</code> directory of the main POM repository.
+</p>
+<p>
+	These tests are for checking that error conditions are
+	detected and gracefully handled.
+</p>
+<p>
+	Each test in this directory has an error,
+	and should be rejected by a compliant parser.
+</p>
+
+</body>
+</html>
diff --git a/site/tests/index.html b/site/tests/index.html
new file mode 100644
index 0000000..40642b0
--- /dev/null
+++ b/site/tests/index.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta content="width=device-width,initial-scale=1" name="viewport">
+	<title>POM tests</title>
+	<link rel="icon" href="/icon.png">
+</head>
+<body>
+<p>
+	<a href="/index.html">POM homepage</a>
+</p>
+<h2>Tests for POM</h2>
+<p>
+  The tests listed below are freely available for checking that POM configuration parsers are implemented correctly.
+</p>
+<p>
+  There are currently four test suites for POM parsing:
+</p>
+<ul>
+  <li><a href="/tests/parsing.html"><code>parsing</code></a> — for testing that key-value pairs are correct</li>
+  <li><a href="/tests/location.html"><code>location</code></a> — for testing that definition location of keys is correctly determined</li>
+  <li><a href="/tests/errors.html"><code>errors</code></a> — for testing that error conditions are detected and gracefully handled</li>
+  <li><a href="/tests/interpretation.html"><code>interpretation</code></a> — for testing that numbers, booleans, and lists are parsed correctly</li>
+</ul>
+
+</body>
+</html>
diff --git a/site/tests/interpretation.html b/site/tests/interpretation.html
new file mode 100644
index 0000000..0bc4a5c
--- /dev/null
+++ b/site/tests/interpretation.html
@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta content="width=device-width,initial-scale=1" name="viewport">
+	<title>POM interpretation tests</title>
+	<link rel="icon" href="/icon.png">
+</head>
+<body>
+<p>
+	<a href="/index.html">POM homepage</a> · <a href="/tests/index.html">POM tests</a>
+</p>
+<h2>Interpretation tests for POM</h2>
+<p>
+	These tests are found in the <code>tests/location</code> directory of the main POM repository.
+</p>
+<p>
+	These tests check that booleans, numbers, floats, and lists are interpreted correctly.
+</p>
+<ul>
+	<li>
+		int.pom, uint.pom, float.pom, bool.pom — These files contain two sections,
+		<code>[good]</code> and <code>[bad]</code>.
+		The keys in <code>good</code> are in pairs <i>k</i>.a and <i>k</i>.b. Their values must
+		parse to the same int/uint/float/boolean as each other.
+		The values in <code>bad</code> are all invalid int/uint/float/booleans, and parsing them should
+		return an error.
+	</li>
+	<li>
+		list.pom — The keys in this file are in pairs <i>k</i>.list and <i>k</i>.sep.
+		<i>k</i>.list is a POM list, and <i>k</i>.sep is the concatenation of <i>x</i><code>;</code> for each entry
+		<i>x</i> in the list (none of the entries have `;` in them, so this representation is
+		unambiguous).
+	</li>
+</ul>
diff --git a/site/tests/location.html b/site/tests/location.html
new file mode 100644
index 0000000..3a1ec39
--- /dev/null
+++ b/site/tests/location.html
@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta content="width=device-width,initial-scale=1" name="viewport">
+	<title>POM location tests</title>
+	<link rel="icon" href="/icon.png">
+</head>
+<body>
+<p>
+	<a href="/index.html">POM homepage</a> · <a href="/tests/index.html">POM tests</a>
+</p>
+<h2>Location tests for POM</h2>
+<p>
+	These tests are found in the <code>tests/location</code> directory of the main POM repository.
+</p>
+<p>
+	These tests are for checking that definition location information
+	is correctly recorded.
+</p>
+<p>
+	Each test consists of a file <i>x</i>.pom and a file <i>x</i>.locations.pom.
+	For every key in <i>x</i>.pom, there’s a corresponding key in <i>x</i>.locations.pom
+	which is set to the line number where the key was defined in <i>x</i>.pom.
+</p>
+</body>
+</html>
diff --git a/site/tests/parsing.html b/site/tests/parsing.html
new file mode 100644
index 0000000..00058ed
--- /dev/null
+++ b/site/tests/parsing.html
@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta content="width=device-width,initial-scale=1" name="viewport">
+	<title>POM parsing tests</title>
+	<link rel="icon" href="/icon.png">
+</head>
+<body>
+<p>
+	<a href="/index.html">POM homepage</a> · <a href="/tests/index.html">POM tests</a>
+</p>
+<h2>Parsing tests for POM</h2>
+<p>
+	These tests are found in the <code>tests/parsing</code> directory of the main POM repository.
+</p>
+<p>
+	These tests are for checking that key-value pairs are parsed correctly.
+</p>
+<p>
+	Each test <i>x</i> consists of two files, <i>x</i>.pom and <i>x</i>.flat.pom. These
+	files should produce the exact same schema, but <i>x</i>.flat.pom is formatted
+	in a simple way without any section headers, and only using doubly-quoted single-line strings.
+</p>
+
+</body>
+</html>
diff --git a/tests/README.md b/tests/README.md
index 82c3eb3..8646a0d 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,9 +1 @@
-# Tests for POM
-
-Each subdirectory of this directory contains a type of test for POM parsers.
-They are described below:
-
-- [`parsing/`](parsing/README.md) — for testing that key-value pairs are correct
-- [`location/`](location/README.md) — for testing that definition location of keys is correctly determined
-- [`errors/`](errors/README.md) — for testing that error conditions are detected and gracefully handled
-- [`interpretation/`](interpretation/README.md) — for testing that numbers, booleans, and lists are parsed correctly
+See <https://pom.computer/tests/index.html>.
diff --git a/tests/errors/README.md b/tests/errors/README.md
index 7351033..c89eded 100644
--- a/tests/errors/README.md
+++ b/tests/errors/README.md
@@ -1,7 +1 @@
-# Error tests
-
-These tests are for checking that error conditions are
-detected and gracefully handled.
-
-Each test in this file has an error,
-and should be rejected by a compliant parser.
+See <https://pom.computer/tests/errors.html>.
diff --git a/tests/interpretation/README.md b/tests/interpretation/README.md
index 1691757..b39988c 100644
--- a/tests/interpretation/README.md
+++ b/tests/interpretation/README.md
@@ -1,14 +1 @@
-# Interpretation tests
-
-These tests check that booleans, numbers, floats, and lists are interpreted correctly.
-
-`int.pom`, `uint.pom`, `float.pom`, `bool.pom` — These files contain two sections,
-`[good]` and `[bad]`. The keys in `good` are in pairs `k.a` and `k.b`. Their values must
-parse to the same int/uint/float/boolean as each other.
-The values in `bad` are all invalid int/uint/float/booleans, and parsing them should
-return an error.
-
-`list.pom` — The keys in this file are in pairs `k.list` and `k.sep`.
-`k.list` is a POM list, and `k.sep` is the concatenation of `x;` for each entry
-`x` in the list with no leading/trailing whitespace (none of the entries have `;` in them, so this representation is
-unambiguous).
+See <https://pom.computer/tests/interpretation.html>.
diff --git a/tests/location/README.md b/tests/location/README.md
index caa8b6a..da79a41 100644
--- a/tests/location/README.md
+++ b/tests/location/README.md
@@ -1,8 +1 @@
-# Location tests
-
-These tests are for checking that definition location information
-is correctly recorded.
-
-Each test consists of a file `x.pom` and a file `x.locations.pom`.
-For every key in `x.pom`, there’s a corresponding key in `x.locations.pom`
-which is set to the line number where the key was defined in `x.pom`.
+See <https://pom.computer/tests/location.html>.
diff --git a/tests/parsing/README.md b/tests/parsing/README.md
deleted file mode 100644
index 2279c04..0000000
--- a/tests/parsing/README.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Parsing tests
-
-These tests are for checking that key-value pairs are parsed correctly.
-
-Each test `x` consists of two files, `x.pom` and `x.flat.pom`. These
-files should produce the exact same schema, but `x.flat.pom` is formatted
-in a simple way without any section headers, and only using doubly-quoted single-line strings.
author	pommicket <pommicket@gmail.com>	2025-09-23 14:26:18 -0400
committer	pommicket <pommicket@gmail.com>	2025-09-23 14:26:18 -0400
commit	ee57036c9cfdff27a81a38a9c5abc3b631f3a83c (patch)
tree	812ad4393c68b0575c4010d9b25d39e20ceefb1c
parent	6ae91130c7c2ff1c11ecfe5798d8037954a4d570 (diff)