commit 2fcffbb95a9673b17aad1818296c2b781df13bee
parent b92b25b4462cea91346d039f7a807094e3797b34
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 3 Feb 2026 16:52:00 +0100
Start writing the sphin.3 manual page
Only a first draft of the sphin library description has been written. It
is a repetition of the README file, with the significant addition of a
description of its dynamic memory management model.
This last part may go into too much detail and therefore does not belong
in this documentation. Nevertheless, it describes behavior that is
common to the entire library and could therefore be a feature worth
describing. Critical review is welcome.
Diffstat:
3 files changed, 78 insertions(+), 3 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -12,8 +12,9 @@ spectral_property.txt
source_spec.txt
tags
star-phor-input.5
-sphin-lint.1
sphin-lint
+sphin-lint.1
+sphin.3
test_sphin
test_sphin_load_geometry
test_sphin_load_prop_rad
diff --git a/Makefile b/Makefile
@@ -124,9 +124,10 @@ pkg:
sphin.pc.in > sphin.pc
sphin-lint.1: doc/sphin-lint.1.scd
+sphin.3: doc/sphin.3.scd
star-phor-input.5: doc/star-phor-input.5.scd
-sphin-lint.1 star-phor-input.5:
+sphin-lint.1 sphin.3 star-phor-input.5:
scdoc < doc/$@.scd > $@
sphin-local.pc: sphin.pc.in
@@ -149,6 +150,7 @@ install: library tool pkg star-phor-input.5 sphin-lint.1
install 644 "$(DESTDIR)$(LIBPREFIX)/pkgconfig" sphin.pc; \
install 644 "$(DESTDIR)$(INCPREFIX)/star" src/sphin.h; \
install 644 "$(DESTDIR)$(MANPREFIX)/man1" sphin-lint.1; \
+ install 644 "$(DESTDIR)$(MANPREFIX)/man3" sphin.3; \
install 644 "$(DESTDIR)$(MANPREFIX)/man5" star-phor-input.5; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-phor-input" COPYING; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-phor-input" README.md
@@ -165,7 +167,8 @@ uninstall:
clean: clean_test clean_tool
rm -f $(DEP) $(OBJ) $(LIBNAME)
- rm -f .config sphin-local.pc sphin.pc star-phor-input.5 sphin-lint.1
+ rm -f .config sphin-local.pc sphin.pc
+ rm -f sphin-lint.1 sphin.3 star-phor-input.5
################################################################################
# Tests
diff --git a/doc/sphin.3.scd b/doc/sphin.3.scd
@@ -0,0 +1,71 @@
+sphin(3) "UNIX"
+
+; Copyright (C) 2024-2026 Centre National de la Recherche Scientifique
+; Copyright (C) 2024-2026 Clermont Auvergne INP
+; Copyright (C) 2024-2026 INSA Lyon
+; Copyright (C) 2024-2026 Institut Mines Télécom Albi-Carmaux
+; Copyright (C) 2024-2026 Institut National Polytechnique de Toulouse
+; Copyright (C) 2024-2026 |Méso|Star> (contact@meso-star.com)
+; Copyright (C) 2024-2026 PhotonLyX (info@photonlyx.com)
+; Copyright (C) 2024-2026 Université de Lorraine
+; Copyright (C) 2024-2026 Université Paul Sabatier
+; Copyright (C) 2024-2026 Université Toulouse - Jean Jaurès
+;
+; This program is free software: 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/>.
+
+# NAME
+
+sphin - sphin library definitions
+
+# SYNOPSIS
+
+*#include <sphin.h>*
+
+# DESCRIPTION
+
+The *sphin* C library provides functions to parse, load and expose data of a
+photoreactive system as described in the *star-phor-input*(5) file format.
+
+It provides a unified data representation that abstract original format used
+to saved data on disk.
+For example, geometries are all stored in a consistent structure - primarly
+using one-dimensional arrays - regardless of their original file format.
+
+Once loaded, the data is intended to be independent of any specific numerical
+method.
+In other words, the library is designed to be independent of a solver but
+nevertheless aims to provide all the data (geometric and physical) necessary for
+a numerical simulation.
+The data is said to be unstructured with regard to a resolution method.
+A deterministic solver would therefore be responsible for meshing the
+integration domains, while a statistical solver would have to build structures
+capable of accelerating random access to the system data.
+
+The library's dynamic memory management is based on reference counting.
+Each API object allocated by the library has a reference counter, initialized
+when it is created: the caller is therefore the owner.
+The caller can then obtain other references or release them as needed.
+However, other dynamically allocated API objects can also obtain additional
+references to the API objects on which they depend and which they need
+throughout their lifetime.
+An object is effectively released once all its references have been released,
+either by the caller or by the other objects that depend on it.
+Thus, unlike a manual allocation/deallocation policy, the caller can release the
+references it holds without having to worry about the order of release;
+the actual deallocation of an object only occurs once all references have been
+released.
+
+# SEE ALSO
+
+*star-phor-input*(5)
