Document meshing algorithm

CMakeLists.txt

@@ -39,13 +39,13 @@ message( STATUS "Build type: ${CMAKE_BUILD_TYPE}" )
 option( CPM_DISABLE "Don't use CPM to retrieve dependencies" "$ENV{CPM_DISABLE}" )
 option( OEMSH_PORTABILITY_TWEAKS "Enable some portability tweaks" OFF )
 
+list( APPEND CMAKE_MODULE_PATH
+	"${CMAKE_SOURCE_DIR}/cmake"
+	)
+
 if( NOT CPM_DISABLE )
 	message( STATUS "Downloading dependencies with CPM" )
 
-	list( APPEND CMAKE_MODULE_PATH
-		"${CMAKE_SOURCE_DIR}/cmake"
-		)
-
 	include( CPM )
 
 	CPMAddPackage(
@@ -126,12 +126,20 @@ else()
 	message( STATUS "Not found D2: Some parts of doc disabled" )
 endif()
 
+find_program( PDF2SVG NAMES pdf2svg )
+if( PDF2SVG )
+	message( STATUS "Found pdf2svg: ${PDF2SVG}" )
+else()
+	message( STATUS "Not found pdf2svg: Some parts of doc disabled" )
+endif()
+
 if( CMakeUtils_FOUND )
 	set( CMAKE_UTILS * )
 	set( COVERAGE_GLOBAL_ONLY ON )
 	include( CMakeUtils )
 endif()
 
+include( ConfigureFileBuildTime )
 include( GNUInstallDirs )
 
 set( CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS

cmake/ConfigureFileBuildTime.cmake

@@ -0,0 +1,33 @@
+
+################################################################################
+function( configure_file_build_time INPUT OUTPUT )
+	set( OPTIONS )
+	set( ONEVALUEARGS )
+	set( MULTIVALUEARGS VARS )
+#	set( MULTIVALUEARGS ARGS VARS )
+	cmake_parse_arguments( CFBT
+		"${OPTIONS}"
+		"${ONEVALUEARGS}"
+		"${MULTIVALUEARGS}"
+		${ARGN}
+		)
+
+	while( CFBT_VARS )
+		list( POP_FRONT CFBT_VARS VAR VAL )
+		list( APPEND VARS "-D${VAR}=\"${VAL}\"" )
+	endwhile()
+
+	file( WRITE
+		"${OUTPUT}.cmake"
+		"configure_file(\"${INPUT}\" \"${OUTPUT}\" ${CFBT_UNPARSED_ARGUMENTS})"
+#		"configure_file(\"${INPUT}\" \"${OUTPUT}\" ${CFBT_ARGS})"
+		)
+
+	add_custom_command(
+		OUTPUT ${OUTPUT}
+		DEPENDS ${INPUT}
+		COMMAND ${CMAKE_COMMAND}
+			${VARS}
+			-P "${OUTPUT}.cmake"
+		)
+endfunction()

default.nix

@@ -4,11 +4,14 @@
 , cmake-utils
 , git
 , texlive
+, pdf2svg
 , cli11
 , indicators
 , pugixml
 , qtbase
 , wrapQtAppsHook
+, fetchzip
+, runCommand
 , withPortabilityTweaks ? false
 }:
 
@@ -40,8 +43,45 @@ stdenv.mkDerivation {
     cmake-utils
     git
     wrapQtAppsHook
+    pdf2svg
     (texlive.combine {
-      inherit (texlive) scheme-small standalone pgfplots;
+      inherit (texlive) scheme-small standalone pgfplots unicode-math;
+      # https://ctan.org/tex-archive/fonts/lete-sans-math
+      # TODO use buildTeXLivePackage
+#      lete-sans-math = pkgs.texlivePackages.buildTeXLivePackage {
+##        revision = 64540;
+#        shortdesc = "Lato-based OpenType Math font for LuaTeX and XeTeX";
+##        stripPrefix = 0;
+##        fontMaps = [
+##          "Map andika.map"
+##        ];
+##        sha512.run = "4da9904459345033aa87deeb0019c8c4a39fbafcd59d973717ed2c4a410ece528944c69669b6a5ecf6ef8bb790f60bba909468e001485c405e7cf8775b7533e5";
+##        sha512.doc = "50684857dc25ad942aff18eedec04c9e27e4e408f748c208f8527c5096e600d26769ec6f82e2f02e72ab472dfb662f12bb009156293a12daa2dc0676d63ed446";
+#        hasRunfiles = false;
+#        license = [ "lppl13c" ];
+#        version = "0.41";
+#      };
+      lete-sans-math = {
+        pkgs = [
+          (runCommand "lete-sans-math" rec {
+            src = fetchzip {
+              url = "https://github.com/abccsss/LeteSansMath/archive/refs/tags/v${passthru.version}.zip";
+              hash = "sha256-q+WwdSUeHIffpgrJ6GKzyQz+iNxUTeHr4GQZsT0r1Kw=";
+            };
+            passthru = {
+              pname = "lete-sans-math";
+              version = "0.50";
+              tlType = "run";
+            };
+          } ''
+            mkdir -p \
+              $out/tex/latex/lete-sans-math/ \
+              $out/fonts/opentype/public/lete-sans-math/
+            cp $src/*.sty $src/*.ltx $out/tex/latex/lete-sans-math/
+            cp $src/*.otf $out/fonts/opentype/public/lete-sans-math/
+          '')
+        ];
+      };
     })
   ];
 

doc/CMakeLists.txt

@@ -1,5 +1,38 @@
 add_custom_target( doc )
 
+if( CMakeUtils_Latex_FOUND AND PDF2SVG )
+	compile_latex_file( "interval"
+		OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/interval.svg"
+		SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/latex"
+		TEXINPUTS "${CMAKE_CURRENT_SOURCE_DIR}/latex"
+		REGISTER_TO "INTERVAL_FILES"
+		SHELL_ESCAPE
+		)
+endif()
+
+configure_file_build_time(
+	"${CMAKE_CURRENT_SOURCE_DIR}/interval.md.in"
+	"${CMAKE_CURRENT_BINARY_DIR}/interval.md"
+	@ONLY
+	VARS
+		INTERVAL_SVG "./latex/interval.svg"
+	)
+
+add_custom_target( interval
+	DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/interval.md" ${INTERVAL_FILES}
+	)
+
+add_dependencies( doc interval )
+
+install(
+	FILES
+		"${CMAKE_CURRENT_BINARY_DIR}/interval.md"
+		${INTERVAL_FILES}
+	DESTINATION "${CMAKE_INSTALL_DOCDIR}"
+	CONFIGURATIONS Release
+	OPTIONAL
+	)
+
 configure_file(
 	"${CMAKE_CURRENT_SOURCE_DIR}/openemsh.1.in"
 	"${CMAKE_CURRENT_BINARY_DIR}/openemsh.1"

doc/interval.md.in

@@ -0,0 +1,42 @@
+# Meshing algorithm
+
+## Scope
+
+The meshing process consists of two parts:
+- The geometrical analysis that, given a structure, outputs some `MeshlinePolicies` ("Here is something of interest that must be meshed according those rules", typically an `Edge` must be meshed according Thirds rule) and some `Interval` in between.
+- The `Meshline` generation, that consist of filling each `Interval` while respecting enclosing `MeshlinePolicies`' specific rules.
+
+Despite being actually just the last step of the whole process, this explanatory document is about the generation of `Meshlines` at `Interval` level.
+
+## Reference
+
+<img src="@INTERVAL_SVG@" width="100%" title="reference_schematic"/>
+
+- `x`: Position of `MeshlinePolicies`.
+- `m`: Position of the middle of the `Interval` between two `MeshlinePolicies`.
+- `h`: Half of the Interval between two `MeshlinePolicies`.
+- `f`: Smoothness factor `[1;2]`.
+- `d`: Distance between the two lines around a `MeshlinePolicy`.
+- `dinit`: Space between `x` and the first line (may not be the half of `d`).
+- `dmax`: Maximal authorized space between two lines.
+- `s`: Space to fill of lines.
+- `z`: Distance from the first line (belonging to `MeshlinePolicy`) to the last line before `m` (the middle of the `Interval`).
+- `lz`: Number of lines before the middle of the `Interval` (minus the line belonging to the `MeshlinePolicy`).
+
+<span style="color:orange">Orange</span> lines belong to `MeshlinePolicies`, <span style="color:lime">green</span> lines belong to `Interval`.
+
+## Algorithm
+
+### Rules
+
+- Axes are meshed `Interval` by `Interval`, smallest first.
+- `Intervals` are meshed **half by half**.
+- Spaces between lines, including `d` are always bounded to `dmax`.
+- Space between lines cannot exceed adjacent spaces multiplied by the smoothness factor.
+
+### Steps
+
+- Choose `dmax` among `Interval`'s `dmax` and projection from both sides' `d` of `f**(lz+1)`, so the sizes of the two cells around `m` (belonging to both sides) will respect the smoothness factor (`f`).
+- Reduce `d` until enough lines are in the half (`lz >= lmin`).
+- Reduce the smoothness factor (which augments the spaces between lines, except `d`) until `z` matches `s`, that is to say until the last line of the half overlaps with `m` (actually just passed `m`).
+- Trim out the last line, that overlaps `m` (a line at `m`, that will count for both halves, will be placed instead).