commit 4f18aff63b6396ee31d204a577e9694a06edbfed
parent 80113aa887d19f6c01a713dd518b96079b6bc4f1
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 22 Sep 2025 16:00:11 +0200
Update the example
Add an introduction page describing the content writing logic when using
star-ty to generate web content.
Move the Lorem Ipsum example to a new "Examples" section to illustrate
that multiple sections can be used.
Diffstat:
8 files changed, 96 insertions(+), 9 deletions(-)
diff --git a/Makefile b/Makefile
@@ -44,12 +44,18 @@ install: sty-genhead
install 755 "$(DESTDIR)$(BINPREFIX)" src/sty-index; \
install 755 "$(DESTDIR)$(BINPREFIX)" src/sty-list; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-ty" README.md; \
- install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-ty" COPYING
- # Example
- mkdir -p "$(DESTDIR)$(APPPREFIX)/star-ty"
- cp -r example/* "$(DESTDIR)$(APPPREFIX)/star-ty"
- find "$(DESTDIR)$(APPPREFIX)/star-ty" -type f -exec chmod 644 {} +
- find "$(DESTDIR)$(APPPREFIX)/star-ty" -type d -exec chmod 755 {} +
+ install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-ty" COPYING; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty" example/Makefile; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty" example/config.mk; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty" example/sty.css; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty" example/menu.tsv; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/home" example/home/index.tsv; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/home" example/home/overview.md; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/examples" example/examples/index.tsv; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/examples" example/examples/lorem-ipsum-fr.md; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/examples" example/examples/lorem-ipsum-la.md; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/examples/images" example/examples/images/prompt.png; \
+ install 644 "$(DESTDIR)$(APPPREFIX)/star-ty/templates" example/templates/footer.html
sed 's#@README@#$(DESTDIR)$(PREFIX)/share/doc/star-ty/README.md#g' \
example/home/about.sh.in > "$(DESTDIR)$(APPPREFIX)/star-ty/home/about.sh"
chmod 644 "$(DESTDIR)$(APPPREFIX)/star-ty/home/about.sh"
@@ -62,7 +68,18 @@ uninstall:
rm -f "$(DESTDIR)$(BINPREFIX)/sty-list"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-ty/README.md"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-ty/COPYING"
- rm -rf "$(DESTDIR)$(APPPREFIX)/star-ty"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/Makefile"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/config.mk"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/sty.css"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/menu.tsv"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/home/index.tsv"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/home/about.sh"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/home/overview.md"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/examples/index.tsv"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/examples/lorem-ipsum-fr.md"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/examples/lorem-ipsum-la.md"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/examples/images/prompt.png"
+ rm -f "$(DESTDIR)$(APPPREFIX)/star-ty/templates/footer.html"
clean:
rm -f src/sty-genhead.o sty-genhead
diff --git a/example/home/images/prompt.png b/example/examples/images/prompt.png
Binary files differ.
diff --git a/example/examples/index.tsv b/example/examples/index.tsv
@@ -0,0 +1 @@
+Legacy lorem-ipsum-@LANG@.html la:fr
diff --git a/example/home/lorem-ipsum-fr.md b/example/examples/lorem-ipsum-fr.md
diff --git a/example/home/lorem-ipsum-la.md b/example/examples/lorem-ipsum-la.md
diff --git a/example/home/index.tsv b/example/home/index.tsv
@@ -1,3 +1,3 @@
# Label web-page [languages]
Star Typesetting about.html
-Lorem Ipsum lorem-ipsum-@LANG@.html la:fr
+How to? overview.html
diff --git a/example/home/overview.md b/example/home/overview.md
@@ -0,0 +1,68 @@
+# Writing a web site
+
+## Structure
+
+A website consists of a set of *sections* listed in the `menu.tsv` file
+at the root of the repository.
+This is a TSV (Tab Separated Value) file in which each line first
+defines the section label as it will appear in the menu, followed by the
+targeted content.
+
+The sections indexed in the menu can be an external HTTP[S] URL, a
+remote directory managed elsewhere, or, more commonly, a subdirectory of
+the repository.
+In this case, this subdirectory must contain an `index.tsv` file that
+lists the content indexed in the second-level menu.
+
+As with the `menu.tsv` file, this index is a Tab Separated Value file in
+which each line first defines the submenu label, followed by its target,
+i.e. local content (such as an HTML page) or an http[s] URL.
+This target can be multilingual by using the `@LANG@` macro in its name.
+It will be replaced by one of the languages listed in the third field of
+the line.
+For example, for content available in French and English, the third
+field will have the value `fr:en`.
+This last field is only mandatory in the case of multilingual content.
+Refer to the `examples/index.tsv` file for an example of multilingual
+indexing.
+
+## Content
+
+The website content is defined by section.
+Regular pages are written in
+[Markdown](https://daringfireball.net/projects/markdown/syntax).
+Each .md file in the section's directory is automatically considered
+website content and therefore converted to HTML during automatic website
+generation.
+
+Shell scripts are also automatically detected as site content.
+They are supposed to dynamically generate a Markdown file converted to
+HTML by the build system.
+The resulting file name is that of the script, with the `.sh` extension
+simply replaced by `.html`.
+
+## Additional Resources
+
+The other resources in the section can be stored in three subdirectories
+specific to the section.
+
+- `images` for storing full-size images;
+- `thumbs` for storing thumbnails of images, providing a preview while
+ limiting bandwidth and speeding up web page loading;
+- `downloads` for storing other downloadable content, such as archives,
+ PDFs, etc.
+
+## Hooks
+
+The `hooks` subdirectory of each section contains shell scripts to be
+executed before the section content is generated.
+Their names must begin with a two-digit priority number that defines
+their order of execution, followed by the character '-'.
+If necessary, they display on standard output the additional files that
+must be deployed with the rest of the site.
+
+Hooks can be used, for example, to convert manual pages to HTML, extract
+the contents of an archive used by section scripts to dynamically
+generate the content of a web page, etc.
+It is ultimately a very versatile mechanism that can be used in many
+ways.
diff --git a/example/menu.tsv b/example/menu.tsv
@@ -1,2 +1,3 @@
# Label directory
-Home home
+About home
+Examples examples
