Man Linux: Main Page and Category List


       gather_stx_titles - gather title declarations from Stx documents


       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:

          -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.


       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


       stx2any (1).


       This page is written by Panu A. Kalliokoski.