commit 56b695a538a4d468d522f05bb5128c9326ac40bc
parent fe60662d41ac9b56bd8bfdc4b85693fd0b948abd
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 20 Jun 2025 14:47:01 +0200
Solstice: complete Markdown translation
Diffstat:
8 files changed, 165 insertions(+), 269 deletions(-)
diff --git a/solstice/.gitignore b/solstice/.gitignore
@@ -1,8 +1,4 @@
-solstice.html
-solstice-docs.html
-solstice-downloads.html
-solstice-resources.html
-solstice-release-notes.html.in
-solstice-pp-release-notes.html.in
+*.html
+solstice-downloads.md
Solstice-*-GNU-Linux64/
Solstice-PP-Sources-*/
diff --git a/solstice/Makefile b/solstice/Makefile
@@ -26,13 +26,6 @@ SOLSTICE_README=$(SOLSTICE_DIR)/share/doc/solstice/README.md
SOLPP_ARCH=downloads/Solstice-PP-Sources-$(SOLPP_VERSION).tar.gz
SOLPP_README=Solstice-PP-Sources-$(SOLPP_VERSION)/README.md
-SOLPP_PKG=\
- downloads/Solstice-PP-Sources-0.3.1.tar.gz\
- downloads/Solstice-PP-Sources-0.3.0.tar.gz\
- downloads/Solstice-PP-Sources-0.2.0.tar.gz\
- downloads/Solstice-PP-Sources-0.1.0.tar.gz
-SOLPP_SIG=$(SOLPP_PKG:=.sig)
-
SOLSTICE_PKG=\
downloads/Solstice-0.9.1-Sources.zip\
downloads/Solstice-0.9.1-GNU-Linux64.tar.gz\
@@ -81,16 +74,14 @@ build_all: $(HTML) man
clean:
@echo "Cleaning generated files"
- @rm -rf man
+ @rm -rf man solstice-downloads.md
@rm -f .sig .lint .man $(HTML) $(HTML:=.err)
distclean: clean
@echo "Cleaning PGP signatures and extracted files"
@rm -f \
$(SOLSTICE_SIG)\
- $(SOLPP_SIG) \
$(MAN) \
- $(SOLPP_README) \
$(SOLSTICE_README)
install: build
@@ -99,8 +90,6 @@ install: build
$(IMG)\
$(SOLSTICE_PKG)\
$(SOLSTICE_SIG)\
- $(SOLPP_PKG)\
- $(SOLPP_SIG)\
downloads/Solstice-ABG.pdf\
downloads/Solstice-ABG-rsrc.zip\
$$(find man -name "*.html")\
@@ -119,16 +108,20 @@ solstice.html: solstice.md.in themis.png solstice_build.sh Makefile
################################################################################
# Reference documentation
################################################################################
-solstice-docs.html: solstice-docs.html.in solstice_build.sh
+solstice-docs.html: solstice-docs.md solstice_build.sh
@echo "Building $@"
@$(SHELL) solstice_build.sh documentations > $@
################################################################################
# Downloads web page
################################################################################
-solstice-downloads.html: $(SOLSTICE_SIG) $(SOLSTICE_README) solstice_build.sh
+solstice-downloads.html: solstice-downloads.md solstice_build.sh
+ @echo "Building $@"
+ @$(SHELL) solstice_build.sh downloads > $@
+
+solstice-downloads.md: $(SOLSTICE_SIG) $(SOLSTICE_README) solstice_build.sh
@echo "Building $@"
- @$(SHELL) solstice_build.sh downloads $(SOLSTICE_README) > $@
+ @$(SHELL) solstice_build.sh downloads2 $(SOLSTICE_README) > $@
$(SOLSTICE_README) $(MAN):
@echo "Extracting data from $(SOLSTICE_ARCH)"
@@ -137,16 +130,9 @@ $(SOLSTICE_README) $(MAN):
################################################################################
# Additional resources
################################################################################
-solstice-resources.html: $(SOLPP_SIG) $(SOLPP_README) \
- solstice-abg.html.in \
- solstice-pp.html.in \
- solstice_build.sh
+solstice-resources.html: solstice-resources.md solstice_build.sh
@echo "Building $@"
- @$(SHELL) solstice_build.sh resources $(SOLPP_README) $(SOLPP_VERSION) > $@
-
-$(SOLPP_README):
- @echo "Extracting $@ from $(SOLPP_ARCH)"
- @tar -xz -f $(SOLPP_ARCH) $(SOLPP_README)
+ @$(SHELL) solstice_build.sh resources > $@
################################################################################
# Check files
@@ -164,7 +150,7 @@ lint_shells:
################################################################################
.sig: Makefile ../configure_targets.sh
@echo "Setup .sig"
- @$(SHELL) ../configure_targets.sh sig $(SOLSTICE_PKG) $(SOLPP_PKG) > .sig
+ @$(SHELL) ../configure_targets.sh sig $(SOLSTICE_PKG) > .sig
.lint: Makefile ../configure_targets.sh
@echo "Setup .lint"
diff --git a/solstice/solstice-abg.html.in b/solstice/solstice-abg.html.in
@@ -1,21 +0,0 @@
-<h2 id="ABG">Beginner's guide</h2>
-
-<p>
-The <b>Solstice Absolute Beginner's Guide</b> is designed to introduce enough
-concepts and functionalities that you will be able to autonomously use the
-Solstice program. The tutorial itself is provided in a pdf file while the
-Solstice resources on which it relies - i.e. input files - are available in a
-separate archive.
-</p>
-
-<table class="list">
- <tr>
- <th>Beginner's guide</th>
- <th>Resources</th>
- </tr>
- <tr>
- <td>[<a href="downloads/Solstice-ABG.pdf">pdf</a>]</td>
- <td>[<a href="downloads/Solstice-ABG-rsrc.zip">zip</a>]</td>
- </tr>
-</table>
-
diff --git a/solstice/solstice-docs.html.in b/solstice/solstice-docs.html.in
@@ -1,14 +0,0 @@
-<header>
- <h1>Solstice
- <span class=subtitle>
- Reference documentation
- </span>
- </h1>
-</header>
-
-<ul>
- <li><a href=man/man1/solstice.1.html>solstice(1)</a></li>
- <li><a href=man/man5/solstice-input.5.html>solstice-input(5)</a></li>
- <li><a href=man/man5/solstice-output.5.html>solstice-output(5)</a></li>
- <li><a href=man/man5/solstice-receiver.5.html>solstice-receiver(5)</a></li>
-</ul>
diff --git a/solstice/solstice-docs.md b/solstice/solstice-docs.md
@@ -0,0 +1,6 @@
+# Reference documentation
+
+- [solstice(1)](man/man1/solstice.1.html)
+- [solstice-input(5)](man/man5/solstice-input.5.html)
+- [solstice-output(5)](man/man5/solstice-output.5.html)
+- [solstice-receiver(5)](man/man5/solstice-receiver.5.html)
diff --git a/solstice/solstice-pp.html.in b/solstice/solstice-pp.html.in
@@ -1,153 +0,0 @@
-<h2>Post-Processes</h2>
-
-<div class="news">
- <p><b>Solstice PP ${VERSION} is available</b></p>
- <ul>
- <li>Sources:
- <a href="downloads/Solstice-PP-Sources-${VERSION}.tar.gz">tarball</a> /
- <a href="downloads/Solstice-PP-Sources-${VERSION}.tar.gz.sig">pgp</a>
- </li>
- </ul>
-</div>
-
-<p>Solstice Post-Process is a collection of command-line tools that
-post-process the outputs of Solstice. These programs illustrate how the
-raw-results of Solstice can be processed with respect to the user needs.</p>
-
-<p>The provided tools are provided as it, without additional support. They are
-free software written in standard C, without external dependency, and released
-under the GPLv3+ license. You can thus easily study, modify or extend them
-according to your needs. You are also welcome to redistribute them under
-certain conditions; refer to the <a
-href="https://www.gnu.org/licenses/gpl.html">license</a> for details.</p>
-
-<p>To use these tools, download the provided archive and verify its integrity
-against its <a href="../misc/pgp_signatures.html">PGP signature</a>. This
-archive contains the sources of the program and a GNU/Makefile to simplify the
-build process on GNU/Linux and on Windows through <a
-href="http://www.mingw.org/">MinGW</a>. Extract it and run <code>make</code> to
-build the programs. Note that even though this archive targets GNU-compliant
-systems, the provided sources can be compiled by any C compiler that supports
-the C99 standard.</p>
-
-<pre class="code">
-$ tar xzvf Solstice-PP-Sources-${VERSION}.tar.gz
-$ cd Solstice-PP-Sources
-$ make
-</pre>
-
-<p>A description of each generated tools is given in the following
-sections.</p>
-
-<h3>solppraw</h3>
-
-<p>The <code>solppraw</code> program reads the Solstice outputs from a file or
-the standard input whether a filename is provided as an argument or not,
-respectively. For each simulated sun direction, it formats the raw results in a
-human readable text file, simplifying the analysis of the results.
-</p>
-
-<p>The following example invokes Solstice to simulate two sun directions and
-write the results in the <code>output</code> file that is then post-processed
-by the <code>solppraw</code> tool.</p>
-
-<pre class="code">
-$ solstice -D45,70:50,75 -R rcvs.yaml -o output input.yaml
-$ solppraw output
-Writing `45-70-raw-results.txt'
-Writing `50-75-raw-results.txt'
-</pre>
-
-<p>Note that one can directly pipe the results of <code>solstice</code> to
-<code>solppraw</code> without any intermediary <code>output</code> file.</p>
-
-<pre class="code">
-$ solstice -D45,70:50,75 -R rcvs.yaml input.yaml | solppraw
-Writing `45-70-raw-results.txt'
-Writing `50-75-raw-results.txt'
-</pre>
-
-<h3>solmaps</h3>
-
-<p>The <code>solmaps</code> command line takes as input the results of a
-regular Solstice simulation. These data are read from a file or from standard
-input whether a filename is provided as an argument or not, respectively.
-<code>solmaps</code> extracts the maps of incoming flux computed by Solstice
-for the receivers whose <code>per_primitive</code> flag is enabled (see <a
-href="man/man5/solstice-receiver.5.html">solstice-receiver</a>(5) for more
-informations). Each map is then saved in a specific <a
-href="http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf">VTK</a>
-file.</p>
-
-<p>The following example pipes <code>solstice</code> with <code>solmaps</code>
-to save the maps of the receivers <code>target_a</code> and
-<code>target_b</code> computed by solstice for each provided sun
-direction.</p>
-
-<pre class="code">
-$ solstice -n10000 -D45,70:50,75 -R rcvs.yaml input.yaml | solmaps
-Writing `45-70-target_a.vtk'
-Writing `45-70-target_b.vtk'
-Writing `50-75-target_a.vtk'
-Writing `50-75-target_b.vtk'
-</pre>
-
-<h3>solpaths</h3>
-
-<p>The <code>solpaths</code> tool reads the radiative paths dumped by Solstice
-when it is invoked with the <code>-p</code> option. The radiative paths are read
-from a file or from the standard input, whether a filename is provided as an
-argument or not, respectively. For each simulated sun direction, it generates a
-<a
-href="http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf">VTK</a>
-file of the radiative paths that can be then visualized in <a
-href="https://www.paraview.org">Paraview</a>.</p>
-
-<p>The following example illustrates how <code>solpaths</code> is piped with
-<code>solstice</code> to generate two VTK files, one per simulated sun
-direction.</p>
-
-<pre class="code">
-$ solstice -n100 -D45,70:50,75 -R rcvs.yaml -p default input.yaml | solpaths
-Writing `45-70-paths.vtk'
-Writing `50-75-paths.vtk'
-</pre>
-
-<h3>solpp</h3>
-
-<p>The <code>solpp</code> program takes two input files: the geometry of a
-solar plant output by Solstice when it is invoked with the <code>-g</code>
-option, and the results of a legacy Solstice simulation. For each simulated sun
-direction, it writes three files. The first one, is a
-<a
-href="http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf">VTK</a>
-file that maps to the
-meshes of the primary geometries (i.e. the reflectors) their associated
-simulation results; for instance their respective cosine factor or the amount
-of flux that reaches a receiver and comes from them. The second output file,
-is another VTK file that stores the geometry of the receivers and their
-simulation results as their incoming flux or their efficiency. Finally, the third
-file is an <a href="http://www.martinreddy.net/gfx/3d/OBJ.spec">OBJ</a> file
-that stores the meshes of the miscellaneous geometries, i.e. the geometries
-that are neither receivers nor primary geometries. These files can then be
-visualised and analysed in <a href="https://www.paraview.org">Paraview</a>.</p>
-
-<p>In the following example, <code>solstice</code> is invoked to simulate two
-sun directions on the solar plant described in the <code>input.yaml</code>
-file. We then rerun <code>solstice</code> with the <code>-g</code> option to
-export the geometry of this solar plant with respect to the aforementioned sun
-directions. We finally invoke <code>solpp</code> to post-process the previous
-outputs saved in the <code>simul</code> and <code>geom</code> files.</p>
-
-<pre class="code">
-$ solstice -D45,70:50,75 -R rcvs.yaml -o simul input.yaml
-$ solstice -D45,70:50,75 -g format=obj -o geom input.yaml
-$ solpp geom simul
-Writing `45-70-primaries.vtk'
-Writing `45-70-receivers.vtk'
-Writing `45-70-miscellaneous.obj'
-Writing `50-75-primaries.vtk'
-Writing `50-75-receivers.vtk'
-Writing `50-75-miscellaneous.obj'
-</pre>
-
diff --git a/solstice/solstice-resources.md b/solstice/solstice-resources.md
@@ -0,0 +1,132 @@
+# Resources
+
+<span id="ABG"/>
+
+## Beginner's guide
+
+The *Solstice Absolute Beginner's Guide* is designed to introduce enough
+concepts and functionalities that you will be able to autonomously use
+the Solstice program.
+The tutorial itself is provided in a pdf file while the Solstice
+resources on which it relies - i.e. input files \- are available in a
+separate archive.
+
+### Downloads
+
+- [Beginner's Guide](downloads/Solstice-ABG.pdf)
+- [Resources](downloads/Solstice-ABG-rsrc.zip)
+
+## Post-Processes
+
+Solstice Post-Process is a collection of command-line tools that
+post-process the outputs of Solstice.
+These programs illustrate how the raw-results of Solstice can be
+processed with respect to the user needs.
+
+They are free software written in standard C, without external
+dependency, and released under the GPLv3+ license.
+You can thus easily study, modify or extend them according to your
+needs.
+You are also welcome to redistribute them under certain conditions;
+refer to the [license](https://www.gnu.org/licenses/gpl.html)
+for details.
+
+### Installation
+
+To use these tools, they must be built and installed from their source
+tree:
+
+ git clone https://gitlab.com/meso-star/solstice-pp.git
+ cd solstice-pp
+ make install
+
+A description of each tools is given in the following sections.
+
+### solppraw
+
+The `solppraw` program reads the Solstice outputs from a file or
+the standard input whether a filename is provided as an argument or not,
+respectively.
+For each simulated sun direction, it formats the raw results in a human
+readable text file, simplifying the analysis of the results.
+
+The following example invokes Solstice to simulate two sun directions
+and write the results in the `output` file that is then post-processed
+by the `solppraw` tool.
+
+ solstice -D45,70:50,75 -R rcvs.yaml -o output input.yaml
+ solppraw output
+
+Note that one can directly pipe the results of `solstice` to `solppraw`
+without any intermediary `output` file.
+
+ solstice -D45,70:50,75 -R rcvs.yaml input.yaml | solppraw
+
+### solmaps
+
+The `solmaps` command line takes as input the results of a
+regular Solstice simulation.
+These data are read from a file or from standard input whether a
+filename is provided as an argument or not, respectively.
+`solmaps` extracts the maps of incoming flux computed by Solstice
+for the receivers whose `per_primitive` flag is enabled
+(see [solstice-receiver(5)](man/man5/solstice-receiver.5.html) for more
+informations).
+Each map is then saved in a specific
+[VTK](http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf)
+file.
+
+The following example pipes `solstice` with `solmaps` to save the maps
+of the receivers `target_a` and `target_b` computed by solstice for each
+provided sun direction.
+
+ solstice -n10000 -D45,70:50,75 -R rcvs.yaml input.yaml | solmaps
+
+### solpaths
+
+The `solpaths` tool reads the radiative paths dumped by Solstice when it
+is invoked with the `-p` option.
+The radiative paths are read from a file or from the standard input,
+whether a filename is provided as an argument or not, respectively.
+For each simulated sun direction, it generates a
+[VTK](http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf)
+file of the radiative paths.
+
+The following example illustrates how `solpaths` is piped with
+`solstice` to generate two VTK files, one per simulated sun direction.
+
+ solstice -n100 -D45,70:50,75 -R rcvs.yaml -p default input.yaml | solpaths
+
+### solpp
+
+The `solpp` program takes two input files: the geometry of a
+solar plant output by Solstice when it is invoked with the `-g`
+option, and the results of a legacy Solstice simulation.
+For each simulated sun direction, it writes three files.
+The first one, is a
+[VTK](http://www.vtk.org/wp-content/uploads/2015/04/file-formats.pdf)
+file that maps to the meshes of the primary geometries (i.e. the
+reflectors) their associated simulation results; for instance their
+respective cosine factor or the amount of flux that reaches a receiver
+and comes from them.
+The second output file, is another VTK file that stores the geometry of
+the receivers and their simulation results as their incoming flux or
+their efficiency.
+Finally, the third file is an
+[OBJ](http://www.martinreddy.net/gfx/3d/OBJ.spec) file that stores the
+meshes of the miscellaneous geometries, i.e. the geometries that are
+neither receivers nor primary geometries.
+These files can then be visualised and analysed in a data visualization
+tool such as [Paraview](https://www.paraview.org).
+
+In the following example, `solstice` is invoked to simulate two
+sun directions on the solar plant described in the `input.yaml`
+file.
+Then `solstice` run with the `-g` option to export the geometry of
+this solar plant with respect to the aforementioned sun directions.
+Finally `solpp` is invoked to post-process the previous outputs saved in
+the `simul` and `geom` files.
+
+ solstice -D45,70:50,75 -R rcvs.yaml -o simul input.yaml
+ solstice -D45,70:50,75 -g format=obj -o geom input.yaml
+ solpp geom simul
diff --git a/solstice/solstice_build.sh b/solstice/solstice_build.sh
@@ -33,73 +33,37 @@ overview()
documentations()
{
print_header -s Solstice -n Documentations -r ../
- cat solstice-docs.html.in
+ md2html solstice-docs.md
print_footer
}
-# Build the downloads page
downloads()
{
- if [ $# -lt 1 ]; then
- printf "Usage: %s downloads <readme>\n" "$0" >&2
- exit 1
- fi
-
- release_notes=$(${markdown} "$1" \
- | sed -n '/^<h2>Release notes<\/h2>/,/^<h2>License<\/h2>/p' | sed '$d')
-
print_header -s Solstice -n Downloads -r ../
- echo "<header><h1>Download Solstice</h1></header>"
- print_downloads Solstice
- echo "${release_notes}"
+ md2html solstice-downloads.md
print_footer
}
-print_pp_downloads()
+# Build the downloads page
+downloads2()
{
- echo "<table class=\"list\">"
- echo " <tr>"
- echo " <th>Version</th>"
- echo " <th>Sources</th>"
- echo " </tr>"
-
-
- find downloads -regex ".*/Solstice-PP-Sources-.*\.tar.gz" | sort -r | \
- while read -r i; do
- version=$(echo "${i}" | sed "s/.*Solstice-PP-Sources-\(.*\)\.tar.gz/\1/g")
+ if [ $# -lt 1 ]; then
+ printf "Usage: %s downloads <readme>\n" "$0" >&2
+ exit 1
+ fi
- echo " <tr>"
- echo " <td>${version}</td>"
- echo " <td>"
- echo " [<a href=\"${i}\">tarball</a>]"
- if [ -f "${i}.sig" ]; then
- echo " [<a href=\"${i}.sig\">pgp</a>]"
- fi
- echo " </td>"
- echo " </tr>"
- done
- echo '</table>'
+ printf '# Downloads\n'
+ printf '\n'
+ print_downloads Solstice
+ printf '\n'
+ sed -n '/^## Release notes/,/^## License/p' "$1" | sed '$d'
}
# Build the resources page
resources()
{
- if [ $# -lt 2 ]; then
- printf "Usage: %s resources <solpp-readme> <solpp-version>\n" "$0" >&2
- exit 1
- fi
-
- solpp_release_notes=$(${markdown} "$1" \
- | sed -n '/^<h2>Release notes<\/h2>/,/^<h2>License<\/h2>/p' \
- | sed -e '$d' -e 's/\<h3\>/h4/g')
-
print_header -s Solstice -n Resources -r ../
- echo "<header><h1>Additional resources</h1></header>"
- cat solstice-abg.html.in
- VERSION=$2 envsubst < solstice-pp.html.in
- echo "<h3>Download Post-Processes</h3>"
- print_pp_downloads
- echo "${solpp_release_notes}"
+ md2html solstice-resources.md
print_footer
}
