commit 150af92f56e1ffc5831b0d32b8ddfd6d9ec2ec26
parent e8385d81bf9a73abc0d90359ef7880485ed75eb3
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Sun, 5 Oct 2025 22:03:09 +0200
Update the star-typesetting man structure.
Move the menu.tsv subsection from the "Content Structure" section to its
own section. This makes the description clearer while following the
structure announced in the manual page.
Its content is also updated to list its fields separated by tabs rather
than content type. The visual structure of the line fields is more
important than visually listing the related content type.
Diffstat:
1 file changed, 69 insertions(+), 61 deletions(-)
diff --git a/doc/star-typesetting.7 b/doc/star-typesetting.7
@@ -100,67 +100,6 @@ and
.Pa index.tsv
files.
.\"""""""""""""""""""""""""""""
-.Ss menu.tsv
-The menu.tsv file is mandatory for
-.Nm .
-It must be located at the root of the working directory.
-In fact, it is the presence of this file that defines a directory as the
-working directory for
-.Nm .
-.Pp
-This file defines the top-level entries in the navigation menu.
-It is a simple text file where each line is formatted into two fields
-separated by a tab which define the label of the entry followed by the
-content it targets, respectively.
-.Pp
-The linked content can be:
-.Bl -dash -offset Ds
-.It
-a local subdirectory, i.e. a section directory containing an
-.Pa index.tsv
-file
-.Po
-see the
-.Sx index.tsv
-section
-.Pc .
-.It
-a remote directory that remains relative to the current working
-directory once installed, but managed elsewhere.
-.It
-an external http[s] URL
-.El
-.Pp
-Empty lines are ignored, as are comments, i.e., text after the hash
-character
-.Pq # .
-Finally, the entries in the navigation menu follow the order of entries
-defined in the
-.Pa menu.tsv
-file.
-.Pp
-Below is an example of a
-.Pa menu.tsv
-file that defines four entries: two targeting sections, one external
-URL, and the last one a remote directory, local to the working tree
-once deployed, but managed elsewhere.
-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.
-.Bd -literal -offset Ds
-# Regular sections
-About my_section
-Doc man_pages
-
-# External link to the content license
-License http://creativecommons.org/licenses/by-nd/4.0/
-
-# Web interface for git repositories
-Git git
-.Ed
-.\"""""""""""""""""""""""""""""
-.Ss index.tsv
-.\"""""""""""""""""""""""""""""
.Ss Section content
Each section must have an
.Pa index.tsv
@@ -244,6 +183,75 @@ In other words, these are simply directories used to semantically
describe the content they store, automatically copied when the website
is deployed.
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh MENU.TSV
+The
+.Nm
+file is mandatory for
+.Nm .
+It must be located at the root of the working directory.
+In fact, it is the presence of this file that defines a directory as the
+working directory for
+.Nm .
+.Pp
+This file defines the top-level entries of the navigation menu, in the
+order in which they are listed there.
+It is a simple text file where each line is formatted into two fields
+separated by a tab, namely:
+.Bl -enum -offset Ds
+.It
+the
+.Em label ,
+i.e., the name of the entry as it appears in the navigation
+menu.
+.It
+the
+.Em content
+targeted by the label.
+This may include:
+.Bl -dash -compact
+.It
+a local subdirectory, i.e. a section directory containing an
+.Pa index.tsv
+file
+.Po
+see the
+.Sx index.tsv
+section
+.Pc ,
+.It
+a remote directory that remains relative to the current working
+directory once installed, but managed elsewhere,
+.It
+an http[s] URL.
+.El
+.El
+.Pp
+Empty lines are ignored, as are comments, i.e., text after the hash
+character
+.Pq # .
+.\"""""""""""""""""""""""""""""
+.Ss Example
+Below is an example of a
+.Pa menu.tsv
+file that defines four entries: two targeting sections, one external
+URL, and the last one a remote directory, local to the working tree
+once deployed, but managed elsewhere.
+.Bd -literal -offset Ds
+# Regular sections
+About my_section
+Doc man_pages
+
+# External link to the content license
+License http://creativecommons.org/licenses/by-nd/4.0/
+
+# Web interface for git repositories
+Git git
+.Ed
+.Pp
+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 SEE ALSO
.Xr sty-genhead 1 ,
.Xr sty-hooks 1 ,
