commit 0d0469d8cae4e9efd8f9669dfd35619aa26e6999
parent b2b56c3d241151afc013790007ab0b4a26955ac4
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Sun, 28 Sep 2025 16:21:24 +0200
Start writing the Star-Typesetting manual
It aims to be the reference documentation explaining its logic,
toolchain, file formats, the expected structure of a website source
tree, its various resources, etc.
In this commit, the description of Star-Typesetting is written. The
content structure is partially complete: its general presentation is
finished, as is the description of the section content, but the
documentation relating to the menu.tsv and index.tsv file formats is
missing. Nothing is written about the compilation system and there is
no detailed description of hooks or a "quick start" example to get
started with.
Diffstat:
1 file changed, 192 insertions(+), 0 deletions(-)
diff --git a/doc/star-typesetting.7 b/doc/star-typesetting.7
@@ -0,0 +1,192 @@
+.\" Copyright (C) 2017, 2025 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" 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/>.
+.Dd September 28, 2025
+.Dt STAR-TYPESETTING 7
+.Os
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm star-typesetting
+.Nd generate static content for online publication
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+.Nm
+is a toolchain that automates the creation of online publications
+and aims for simplicity and portability.
+First, by using Markdown syntax for author content, a simple,
+lightweight, human-readable markup language that offers only minimal
+formatting of text and images.
+Second, thanks to its generated content, which is pure HTML laid out by
+a single CSS file.
+And finally, thanks to the tools it relies on, based on well-established
+standards such as POSIX shell and POSIX make.
+All this with the goal of helping authors focus solely on the content
+they want to write, rather than on layout, the generation process,
+tool-related tricks, or long-term portability issues.
+.Pp
+Behind its apparent rigidity and simple appearance,
+.Nm
+offers great flexibility to authors who wish to go beyond simply
+publishing handwritten texts with default style.
+The CSS has been written in a readable manner to encourage authors to
+update it if necessary.
+In addition, the Markdown syntax supports inline HTML for those who find
+its syntax alone too restrictive.
+It is also possible to write shell scripts that dynamically generate
+content when creating the website, for example to compose a page from
+external resources or to generate a list of downloadable archives from
+published files.
+Finally,
+.Nm
+offers a system of hooks, i.e. shell scripts executed before content
+generation, for example, to sign files offered for download or retrieve
+external content used to dynamically generate a web page.
+Hooks are ultimately a very versatile mechanism that can be used in many
+ways, far beyond those for which they were originally designed.
+.Pp
+This reference documentation describes the structure of a website as
+managed by
+.Nm ,
+the syntax of the files used to describe its navigation menu, and the
+toolchain it relies on to generate and publish a website.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh CONTENT STRUCTURE
+A well-formed
+.Nm
+content consists of a set of directories, called
+.Em sections ,
+in which the section content is stored.
+.Pp
+The section directories are referenced in the mandatory
+.Pa menu.tsv
+file located at the root of the
+.Nm
+content, called the
+.Em working directory .
+The content indexed in each section is listed in the section's
+.Pa index.tsv
+file, also required by
+.Nm .
+.Pp
+The
+.Pa menu.tsv
+file and the
+.Pa index.tsv
+files for each section are used by
+.Nm
+to generate the site's navigation menu.
+The first level of the menu lists the labels of the sections referenced in
+.Pa menu.tsv .
+The second level of the menu lists the content indexed in the section
+selected in the first level, as listed in its
+.Pa index.tsv
+file.
+.Pp
+The order of the labels in the first or second level menu follows the
+order of the entries in the
+.Pa menu.tsv
+and
+.Pa index.tsv
+files.
+.\"""""""""""""""""""""""""""""
+.Ss menu.tsv
+.\"""""""""""""""""""""""""""""
+.Ss index.tsv
+.\"""""""""""""""""""""""""""""
+.Ss Section content
+Each section must have an
+.Pa index.tsv
+file that lists the contents of the section indexed by the navigation
+menu.
+.Pp
+A section must also store the sources of its content, written in
+Markdown syntax and suffixed by the
+.Dq .md
+extension to be automatically detected, then processed and converted to
+HTML by
+.Nm .
+The file it generates has the same name as its Markdown sources,
+except that the
+.Dq .md
+extension is replaced by
+.Dq .html .
+.Pp
+Files with the
+.Dq .sh
+extension in the root directory of a section are considered shell
+scripts intended to dynamically generate the Markdown sources of web
+pages.
+.Nm
+executes them and redirects their standard output to intermediate
+Markdown files named after their script, with the
+.Dq .sh
+extension replaced by
+.Dq .md .
+These files are then processed by
+.Nm
+as normal Markdown sources, i.e. converted to HTML files as described
+above.
+.Pp
+In principle, the root of a section should contain a Markdown file
+.Pq or a shell script
+corresponding to each entry in the
+.Pa index.tsv
+file.
+However, there may be more than this, as several pages may not be
+directly accessible from the menu;
+several of them may only be referenced by other pages.
+.Pp
+Finally, four subdirectories have significance for
+.Nm
+when they are
+present in a section:
+.Bl -tag -width Ds
+.It Pa downloads
+is supposed to store downloadable content for the section, such as
+archives, PDFs, etc.
+.It Pa hooks
+stores scripts to be executed by sty before generating the section's
+content.
+Refer to the section of the manual devoted to hooks for a complete
+description.
+.It Pa images
+is intended to store full-size images.
+.It Pa thumbs
+store thumbnails of images stored in the images directory.
+Authors should use these thumbnails to provide a preview of the images
+and thus limit the bandwidth required to display a page.
+They can then provide a link to the full-resolution image for those who
+wish to access it.
+.El
+.Pp
+With the notable exception of the
+.Pa hooks
+subdirectory
+.Po see
+.Dq HOOKS
+section
+.Pc ,
+the other subdirectories are taken as is by
+.Nm ,
+which publishes them with their complete content when deploying the
+website.
+In other words, these are simply directories used to semantically
+describe the content they store, automatically copied when the website
+is deployed.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr sty-genhead 1 ,
+.Xr sty-hooks 1 ,
+.Xr sty-index 1 ,
+.Xr sty-lists 1
