commit db8658bcab5dd70fc02f9e39789fe8071e6f028e
parent 150af92f56e1ffc5831b0d32b8ddfd6d9ec2ec26
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Sun, 5 Oct 2025 22:08:08 +0200
Document the index.tsv file in star-typesetting man
Diffstat:
1 file changed, 69 insertions(+), 0 deletions(-)
diff --git a/doc/star-typesetting.7 b/doc/star-typesetting.7
@@ -252,6 +252,75 @@ Note that there is no difference between normal sections and the git
entry, except that the latter targets a directory that is not local to
the working tree before it is deployed to the remote server.
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh INDEX.TSV
+Each section, i.e. each local subdirectory referenced in the
+.Pa menu.tsv
+file, must contain an
+.Pa index.tsv
+file.
+It defines the second-level entries in the navigation menu, i.e. the
+content indexed in the section selected in the first-level menu.
+.Pp
+This file is formatted as a set of three values separated by tabs, which
+are in the following order:
+.Bl -enum -offset Ds
+.It
+the
+.Em label
+of the indexed content, as it appears in the navigation menu.
+.It
+the
+.Em content
+indexed by the label, which can be an HTML page related to
+the section or an http[s] URL.
+This content can be multilingual by using the
+.Dq @LANG@
+macro in its name.
+This macro will be replaced by one of the languages listed in the third
+field of the line, namely:
+.It
+a
+.Em list of languages
+in which the indexed content is available.
+This is mandatory only for multilingual content.
+Each entry in the list, separated from the previous one by a colon
+.Pq \&:
+defines one of the possible values of the
+.Dq @LANG@
+macro in the content name.
+The available languages appear in the second-level menu in the order in
+which they are listed.
+The first language in the list is the default language used when
+multilingual content is selected via the menu.
+.El
+.Pp
+Empty lines are ignored, as are comments, i.e., text after the hash
+character
+.Pq # .
+.\"""""""""""""""""""""""""""""
+.Ss Example
+Here is an example of an
+.Pa index.tsv
+file indexing three content items:
+the first is a standard page;
+the second is multilingual content provided in English and French.
+Both pages have the same name, except for the suffix indicating their
+language, namely
+.Pa legal-en.html
+and
+.Pa legal-fr.html ;
+the third and final link redirects to an https URL.
+.Bd -literal -offset Ds
+# Regular content
+Home about.html
+
+# Multilingual content
+Legal notice legal-@LANG@.html en:fr
+
+# External link
+Super Dimension Fortress https://sdf.org/
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr sty-genhead 1 ,
.Xr sty-hooks 1 ,
