gather_stx_titles(1)

💖 gather_stx_titles 💖

okay bestie, welcome to a General Commands Manual page — the star of the show is gather_stx_titles, and yes she's a section 1 girlie (general commands, we love her). let's get into it 🫶

---

🌸 NAME 🌸

gather_stx_titles — gather title declarations from Stx documents ✨

---

🎀 SYNOPSIS 🎀

gather_stx_titles [ -f from-suffix ] [ -t to-suffix ] [ m4 options ]
file [ file ... ]

---

💅 DESCRIPTION 💅

so what does she do? gather_stx_titles digs out Stx metadata declarations from the files you list, and dumps the title and document ID information as m4 definitions straight into standard output. then later, w_crosslink can use all that info to link your documents up by their metadata. iconic behaviour, honestly. 👑

why is this useful tho? okay imagine this: you've got a big site with a LOT of cross-linking. a document's name is gonna show up in so many places — in the link menu (if you have one), and in the body of all the different pages that cross-link to it. gather_stx_titles lets you put all that info in one place, and in the place where it actually belongs: the file itself. and bestie, you will be so glad you did when the time comes to change document titles or move documents around — especially if your website has multilingual magic going on. 🧚

---

✨ OPTIONS ✨

heads up: gather_stx_titles uses m4 internally, so she'll accept any option m4 accepts. on top of those, she takes the following:

• -f from-suffix — in the filename data, substitute away the suffix from-suffix. and okay, plot twist: from_suffix may actually be a regular expression. stupid but true, bestie 😭 in GNU m4 it's a "traditional" regexp, whereas in BSD m4 it's an "extended" regexp. defaults to no suffix (nothing to take away).
• -t to-suffix — in the filename data, substitute the suffix that was taken away by from-suffix with to-suffix. if from-suffix is nil (which is the default), then to-suffix just gets appended to all filenames. 💫
• -p prefix — strip away the prefix given by (regular expression) prefix from filenames. the equivalent of -t for this one does not exist, because you can specify a directory prefix to w_crosslink via w_base. iykyk 🤷
• --version, -V — just show version information and exit. short and sweet. 💁
• --help, -? — just show a short help message and exit. 🎀

---

🌈 EXAMPLES 🌈

ngl, most of the time you're gonna want to automate gather_stx_titles — for example, with a Makefile like this one:

SOURCES = $(wildcard *.stx)
TARGETS = $(SOURCES:.stx=.html)

all: $(TARGETS)

titles.m4: $(SOURCES)
    gather_stx_titles -f stx -t html $^ > $@

%.html: %.stx titles.m4
    stx2any -T html titles.m4 $< > $@

if you don't want to be quite so correct about it, you can drop the .html dependency on titles.m4, or the titles.m4 dependency on SOURCES. 🙈

and using temporary files is not necessary — this should also work:

$ gather_stx_titles *.stx | stx2any - mydoc.stx

---

👀 SEE ALSO 👀

stx2any (1).

---

🦋 AUTHOR 🦋

this page is written by Panu A. Kalliokoski.

---

okay and that's the whole page bestie, you ate it 💅 big love to Panu A. Kalliokoski for writing this one, and this was the gather_stx_titles(1) page from the General Commands Manual — now go gather those titles, periodt. 💖✨🎀