gather_stx_titles [ -f from-suffix ] [ -t to-suffix ] [ m4 options ] file [ file … ]
gather_stx_titles digs out Stx metadata declarations from the listed files, and dumps the title and document ID information as m4 definitions into standard output. This information can later be used by w_crosslink to link the documents by their metadata.
Why is this useful? Well, imagine that you have a large site with a lot of cross-linking. A document's name will appear in many places: in the link menu (if you have one), and in the body of different pages where it is cross-linked from. gather_stx_titles lets you put all the information in one place and where it belongs, i.e. the file itself. You'll be glad if you did, when the time comes to change document titles or move the documents around; especially so if your website has multilingual magic.
gather_stx_titles uses m4 internally and will accept any option m4 accepts. In addition to those, it takes the following options:
traditionalregexp, whereas in BSD m4 it is an
extendedregexp. Default to no suffix (nothing to take away).
I guess most of the time you will want to automate the use of gather_stx_titles, for example with a Makefile like this:
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, drop the .html dependency on titles.m4 or titles.m4 dependency on SOURCES. Using temporary files is not necessary: this should also work:
$ gather_stx_titles `*'.stx | stx2any - mydoc.stx
This page is written by Panu A. Kalliokoski.