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
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.
OPTIONS
gather_stx_titles uses m4 internally and will accept any option m4
accepts. In addition to those, it takes the following options:
-f from-suffix
In the filename data, substitute away the suffix from-suffix.
Actually, from_suffix may be a regular expression; stupid but
true, in GNU m4 it is a “traditional” regexp, whereas in BSD
m4 it is an “extended” regexp. Default to no suffix (nothing
to take away).
-t to-suffix
In the filename data, substitute the suffix taken away by
from-suffix with to-suffix. If from-suffix is nil (the
default), append to-suffix to all filenames.
-p prefix
Strip away the prefix given by (regular expression) prefix
from filenames. The equivalent of -t for this does not
exist, because you can specify a directory prefix to
w_crosslink by w_base.
--version, -V
Just show version information and exit.
--help, -?
Just show a short help message and exit.
EXAMPLES
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
SEE ALSO
stx2any (1).
AUTHOR
This page is written by Panu A. Kalliokoski.