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.