commit d610599c9010ae471ff09705bbecb45914ce6ec0
parent b423efed61a6db8d835cbaa8af2bcad0df3e0383
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 12 Nov 2025 15:48:35 +0100
Finalize the star-typesetting documentation
Document the build system and CSS. Write the "examples" section.
Diffstat:
1 file changed, 155 insertions(+), 0 deletions(-)
diff --git a/doc/star-typesetting.7 b/doc/star-typesetting.7
@@ -374,7 +374,162 @@ 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 BUILD SYSTEM
+The
+.Nm
+conductor is a POSIX makefile consisting of a few lines that automates
+the generation of the website.
+Assuming
+.Nm
+has been installed in
+.Pa /usr/local
+.Pq default behavior ,
+the user can retrieve this makefile from the
+.Pa /usr/local/share/star-ty
+directory, along with its
+.Pa config.mk
+file, which controls the behavior of the makefile using a set of macros.
+.Pp
+The macros defined in
+.Pa config.mk
+are as follows:
+.Bl -tag -width Ds
+.It Va PREFIX
+Destination URL where content is deployed with
+.Xr rsync 1 .
+The supported URL syntax is therefore that of rsync.
+By default, this is a dummy URL that the user must update, presumably
+with a remote directory served by an http[s] server.
+.It Va MD2HTML
+Tool used to convert Markdown sources to HTML.
+The default value is
+.Xr md2html 1 .
+.It Va GROUP
+Group to which the website content belongs once deployed on
+.Va PREFIX .
+The group is used to give write access to all members who belong to it.
+This means that different users can update the website, provided they
+belong to
+.Va GROUP .
+.It Va RESOURCES
+List of additional resources to be deployed on
+.Va PREFIX ,
+which are not already managed by
+.Nm .
+.El
+.Pp
+The makefile targets are as follows:
+.Bl -tag -width Ds
+.It Cm build
+Generate the whole website.
+This is the default target, i.e., the one runs when running make(1)
+without any argument.
+.It Cm clean
+Delete generated content such as HTML pages, dynamically generated
+intermediate Markdown files, or temporary files used internally by
+.Nm .
+.Pp
+It is recommended to run the
+.Cm clean
+target before a
+.Cm build ,
+to ensure that all content is regenerated, thus taking into
+account all the latest updates.
+Indeed, while source updates can be managed automatically, this
+is not the case for intermediate files, which are managed by user
+scripts.
+.Pp
+Note that not all intermediate content is necessarily deleted
+if it is not directly managed by
+.Nm ,
+such as temporary content generated by hook scripts
+.Po
+see the
+.Sx HOOKS
+section
+.Pc .
+.It Cm lint
+Use
+.Xr tidy 1
+to verify that the generated HTML pages are well-formed, and
+.Xr shellcheck 1
+to verify the accuracy of shell scripts, whether they are used to
+generate dynamic content or by hooks.
+Both tools must therefore be available.
+.It Cm install
+Copy the generated website to the URL defined by the
+.Va PREFIX
+macro.
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh CASCADING STYLE SHEETS
+Each HTML page generated by
+.Nm
+searches for a CSS file named
+.Pa sty.css
+at the root of the working directory.
+Like the build system files, a template for this style sheet can be
+retrieved from the example installed with
+.Nm ,
+which is installed by default in
+.Pa /usr/local/share/star-ty .
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+.Nm
+is installed with an example that not only provides the compilation
+system files and a the style sheet, but also illustrates how to write
+content in
+.Nm .
+.Pp
+Assuming
+.Nm
+is installed in
+.Pa /usr/local
+.Pq default behavior ,
+start by copying it locally.
+It will be the working directory:
+.Bd -literal -offset Ds
+cp -r /usr/local/share/star-ty my_web_site
+cd my_web_site
+.Ed
+.Pp
+Run make to generate the content:
+.Bd -literal -offset Ds
+make
+.Ed
+.Pp
+The resulting website can be viewed locally, either in the working
+directory itself:
+.Bd -literal -offset Ds
+"${BROWSER:-lynx}" ./home/about.html
+.Ed
+.Pp
+or deployed to a temporary directory:
+.Bd -literal -offset Ds
+tmp="${TMPDIR:-/tmp}/www"
+make PREFIX="${tmp}" GROUP="$(id -gn)" install
+"${BROWSER:-lynx}" "${tmp}/home/about.html
+.Ed
+.Pp
+Modify the content as needed, then, once finished, publish the website
+by deploying its content to a remote machine that publicly serves its
+local
+.Pa /srv/www
+directory via an http[s] server:
+.Bd -literal -offset Ds
+make clean
+make PREFIX=remote:/srv/www GROUP=www install
+.Ed
+.Pp
+Note the
+.Dq make clean
+directive used to force complete regeneration of the content on
+.Dq make install
+to ensure that it is up to date with the latest changes.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
+.Xr make 1 ,
+.Xr rsync 1 ,
.Xr sty-genhead 1 ,
.Xr sty-hooks 1 ,
.Xr sty-index 1 ,
