w_title(gather_stx_titles)dnl
w_doc_id(gstman)dnl
w_section(1)dnl
w_author(Panu A. Kalliokoski)dnl
w_man_desc(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 w_author.