commit 2683af1d701ea328b26c2ba07c27bc6c58af8268
parent 949fcc292c320d9dedcc886acba683fb67aa7670
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 12 Nov 2025 10:00:29 +0100
Document the "hooks"
Diffstat:
1 file changed, 55 insertions(+), 2 deletions(-)
diff --git a/doc/star-typesetting.7 b/doc/star-typesetting.7
@@ -12,7 +12,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
-.Dd September 28, 2025
+.Dd November 12, 2025
.Dt STAR-TYPESETTING 7
.Os
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -172,7 +172,7 @@ With the notable exception of the
.Pa hooks
subdirectory
.Po see
-.Dq HOOKS
+.Sx HOOKS
section
.Pc ,
the other subdirectories are taken as is by
@@ -321,6 +321,59 @@ Legal notice legal-@LANG@.html en:fr
Super Dimension Fortress https://sdf.org/
.Ed
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh HOOKS
+Each section indexed by the
+.Pa menu.tsv
+file can contain a
+.Pa hooks
+subdirectory.
+This subdirectory should contain shell scripts to be executed before
+generating the section content.
+.Pp
+It may seem strange to use hooks when shell scripts can already be used
+to generate dynamic content
+.Po
+see
+.Sx Section content
+.Pc .
+However, this mechanism alone not only fails to properly separate the
+different tasks, but also remains limited.
+An automatic generation script is associated with a web page, so any
+additional content it might generate would not be tracked by the build
+system, which would therefore be unable to deploy it.
+Furthermore, there is no way to prioritize the execution of the various
+generation scripts, which are, by design, independent of each other.
+Hence kook scripts, which are much more versatile than generation
+scripts.
+.Pp
+The name of a hook script must begin with a two-digit prefix followed by
+a dash
+.Pq - ,
+and end with the extension
+.Dq .sh .
+The two-digit prefix is used to prioritize the execution of hooks: the
+smaller the number, the higher the priority.
+Thus, hook scripts with the prefix
+.Dq 00
+will be executed first, while those with the prefix
+.Dq 99
+will be executed last.
+.Pp
+On output, a hook script must write the paths to the files it has
+generated and which must be deployed with the website.
+These paths must be relative to the working directory
+.Po
+i.e., the
+directory of the
+.Pa menu.tsv
+file
+.Pc ,
+and not to the directory of the section to which the hook script
+belongs.
+Each line of the output must contain only one path, so that the number
+of lines written corresponds to the number of files generated by the
+hook that must be deployed.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr sty-genhead 1 ,
.Xr sty-hooks 1 ,
