13.2.7 Doc Insertion

To process a .twerp file into a .texi file, use the twerp2texi program (see guile-tools twerp2texi). For example, the following is used for the Guile reference manual Makefile.am:

     BUILT_SOURCES = doc-index-prep
     
     doc-index-prep:
             ( cd $(top_builddir)/libguile ; $(MAKE) .doc-index )
             ( cd $(top_builddir)/ice-9 ; $(MAKE) .doc-index )
             ( cd $(top_builddir)/srfi ; $(MAKE) .doc-index )
     
     dotdocindexes = \
      -I $(top_builddir)/libguile/.doc-index \
      -I $(top_builddir)/ice-9/.doc-index \
      -I $(top_builddir)/srfi/.doc-index
     
     .twerp.texi:
             guile-tools twerp2texi $(dotdocindexes) \
                 -d .deps/$*.Ptexi \
                 -o $(srcdir)/$*.texi \
                    $<

The BUILT_SOURCES directive means to build doc-index-prep first, in other words make sure all docstrings have been properly extracted (see Doc Snarfing Overview) and indexed (see Doc Indexing). The indexes are left in their own directories and referenced using the relative path top_builddir set by the auto* tools. Finally, the .twerp.texi rule uses twerp2texi to do the insertions, writing the output in the srcdir, and collecting dependency tracking information into the subdirectory .deps.

You can omit the -d option but then there is no way to guarantee rebuild on source file change, except by touching all the .twerp files. See Doc Methodology Insinuation.