docs/Makefile.am

   1
   2 ##-------------------------------------------------------------
   3 ## HACK: stuff to avoid making the print docs if installing the
   4 ## tools to do so is impractical / too difficult
   5 ##-------------------------------------------------------------
   6
   7 # Comment out the next line to skip building print docs.  The default
   8 # is not to skip building print docs.  Note, after changing it
   9 # you need to re-run autogen.sh and configure to make it take effect.
  10 BUILD_ALL_DOCS=yes
  11
  12 # Whether to run xmlto pdf --with-fop
  13 # This is de fault, set to empty to use the default fo to pdf
  14 # processor that xmlto uses (which might be pdfxmltex, which is
  15 # known to be broken).
  16 WITH_FOP=--with-fop
  17
  18 ##-------------------------------------------------------------
  19 ## END OF HACK
  20 ##-------------------------------------------------------------
  21
  22 EXTRA_DIST = \
  23         README \
  24         images/home.png \
  25         images/next.png \
  26         images/prev.png \
  27         images/up.png \
  28         images/kcachegrind_xtree.png \
  29         images/dh-tree.png \
  30         internals/3_0_BUGSTATUS.txt \
  31         internals/3_1_BUGSTATUS.txt \
  32         internals/3_2_BUGSTATUS.txt \
  33         internals/3_3_BUGSTATUS.txt \
  34         internals/3_4_BUGSTATUS.txt \
  35         internals/3_5_BUGSTATUS.txt \
  36         internals/3_7_BUGSTATUS.txt \
  37         internals/3_8_BUGSTATUS.txt \
  38         internals/3_9_BUGSTATUS.txt \
  39         internals/3_10_BUGSTATUS.txt \
  40         internals/3_11_BUGSTATUS.txt \
  41         internals/3_12_BUGSTATUS.txt \
  42         internals/3_13_BUGSTATUS.txt \
  43         internals/3_14_BUGSTATUS.txt \
  44         internals/3_15_BUGSTATUS.txt \
  45         internals/MERGE_3_10_1.txt \
  46         internals/arm_thumb_notes_gdbserver.txt \
  47         internals/avx-notes.txt \
  48         internals/BIG_APP_NOTES.txt \
  49         internals/Darwin-debug.txt \
  50         internals/Darwin-notes.txt \
  51         internals/SPEC-notes.txt \
  52         internals/directory-structure.txt \
  53         internals/howto_BUILD_KDE42.txt \
  54         internals/howto_oprofile.txt \
  55         internals/m_replacemalloc.txt \
  56         internals/m_syswrap.txt \
  57         internals/module-structure.txt \
  58         internals/multiple-architectures.txt \
  59         internals/notes.txt \
  60         internals/performance.txt \
  61         internals/porting-HOWTO.txt \
  62         internals/mpi2entries.txt \
  63         internals/porting-to-ARM.txt \
  64         internals/qemu-aarch64-linux-HOWTO.txt \
  65         internals/qemu-mips64-linux-HOWTO.txt \
  66         internals/register-uses.txt \
  67         internals/s390-opcodes.csv \
  68         internals/release-HOWTO.txt \
  69         internals/segments-seginfos.txt \
  70         internals/t-chaining-notes.txt \
  71         internals/threads-syscalls-signals.txt \
  72         internals/tm-mutexstates.dot \
  73         internals/tm-threadstates.dot \
  74         internals/tracking-fn-entry-exit.txt \
  75         internals/why-no-libc.txt \
  76         internals/xml-output.txt \
  77         internals/xml-output-protocol4.txt \
  78         lib/line-wrap.xsl \
  79         lib/vg_basic.css \
  80         lib/vg-fo.xsl \
  81         lib/vg-faq2txt.xsl \
  82         lib/vg-html-chunk.xsl \
  83         lib/vg-html-website.xsl \
  84         lib/vg-html-common.xsl \
  85         xml/FAQ.xml \
  86         xml/dist-docs.xml \
  87         xml/index.xml \
  88         xml/licenses.xml \
  89         xml/manpages-index.xml \
  90         xml/manual.xml \
  91         xml/manual-intro.xml \
  92         xml/manual-core.xml \
  93         xml/manual-core-adv.xml \
  94         xml/manual-writing-tools.xml \
  95         xml/design-impl.xml \
  96         xml/quick-start-guide.xml \
  97         xml/tech-docs.xml \
  98         xml/valgrind-manpage.xml \
  99         xml/vg-entities.xml \
 100         xml/xml_help.txt
 101
 102
 103 ##-------------------------------------------------------------------
 104 ## Below here is more ordinary make stuff...
 105 ##-------------------------------------------------------------------
 106 myxmldir   = $(top_srcdir)/docs/xml
 107 myimgdir   = $(top_srcdir)/docs/images
 108 mylibdir   = $(top_srcdir)/docs/lib
 109
 110 myhtmldir  = $(top_builddir)/docs/html
 111 myprintdir = $(top_builddir)/docs/print
 112
 113 websitedir   = $(top_builddir)/docs/website
 114 valkyriedir  = $(top_builddir)/docs/vg-html
 115 downloadsdir = $(top_builddir)/docs/downloads
 116 vgdir        = $(top_builddir)/docs/valgrind
 117
 118 if VGCONF_OS_IS_FREEBSD
 119 XML_CATALOG_FILES = /usr/local/share/xml/catalog
 120 else
 121 XML_CATALOG_FILES = /etc/xml/catalog
 122 endif
 123
 124 # file to log print output to
 125 LOGFILE = print.log
 126
 127 # validation stuff
 128 XMLLINT       = xmllint
 129 XMLLINT_FLAGS = --noblanks --noout --xinclude --postvalid --noent \
 130                 --path $(top_builddir)/docs/xml
 131
 132 # stylesheet processor
 133 XSLTPROC       = xsltproc
 134 XSLTPROC_FLAGS = --nonet --xinclude --path $(top_builddir)/docs/xml
 135
 136 # stylesheets
 137 XSL_HTML_CHUNK_STYLE  = $(mylibdir)/vg-html-chunk.xsl
 138 XSL_FO_STYLE          = $(mylibdir)/vg-fo.xsl
 139 XSL_TEXT_STYLE        = $(mylibdir)/vg-faq2txt.xsl
 140 XSL_WEBSITE_STYLE     = $(mylibdir)/vg-html-website.xsl
 141 XSL_MAN_STYLES = \
 142     /usr/local/share/xsl/docbook/manpages/docbook.xsl \
 143     /usr/share/sgml/docbook/xsl-stylesheets/manpages/docbook.xsl \
 144     /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl \
 145     /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
 146
 147 # Input files for valid-manual and valid-manpages
 148 MANUAL_XML_FILES = $(myxmldir)/index.xml \
 149                      $(top_builddir)/docs/xml/vg-entities.xml \
 150                      $(myxmldir)/quick-start-guide.xml \
 151                      $(myxmldir)/manual.xml \
 152                        $(myxmldir)/manual-intro.xml \
 153                        $(myxmldir)/manual-core.xml \
 154                        $(myxmldir)/manual-core-adv.xml \
 155                      $(top_srcdir)/*/docs/*-manual.xml \
 156                      $(myxmldir)/quick-start-guide.xml \
 157                      $(myxmldir)/FAQ.xml \
 158                      $(myxmldir)/tech-docs.xml \
 159                        $(myxmldir)/design-impl.xml \
 160                        $(myxmldir)/manual-writing-tools.xml \
 161                        $(top_srcdir)/callgrind/docs/cl-format.xml \
 162                      $(myxmldir)/dist-docs.xml \
 163                        $(top_srcdir)/AUTHORS \
 164                        $(top_srcdir)/NEWS \
 165                        $(top_srcdir)/NEWS.old \
 166                        $(top_srcdir)/README \
 167                        $(top_srcdir)/README_MISSING_SYSCALL_OR_IOCTL \
 168                        $(top_srcdir)/README_DEVELOPERS \
 169                        $(top_srcdir)/README_PACKAGERS \
 170                        $(top_srcdir)/README.s390 \
 171                        $(top_srcdir)/README.android \
 172                        $(top_srcdir)/README.android_emulator \
 173                        $(top_srcdir)/README.mips \
 174                        $(top_srcdir)/README.solaris \
 175                      $(myxmldir)/licenses.xml \
 176                        $(top_srcdir)/COPYING \
 177                        $(top_srcdir)/COPYING.DOCS
 178
 179 MANPAGES_XML_FILES = $(myxmldir)/manpages-index.xml \
 180                        $(myxmldir)/valgrind-manpage.xml \
 181                          $(myxmldir)/manual-core.xml \
 182                        $(top_srcdir)/*/docs/*-manual.xml
 183
 184 all-docs: FAQ.txt man-pages html-docs print-docs
 185
 186 valid-manual: $(MANUAL_XML_FILES)
 187         if type $(XMLLINT) 2>/dev/null; then \
 188           $(XMLLINT) $(XMLLINT_FLAGS) $(myxmldir)/index.xml && \
 189           touch $@; \
 190         fi
 191
 192 valid-manpages: $(MANPAGES_XML_FILES)
 193         if type $(XMLLINT) 2>/dev/null; then \
 194           $(XMLLINT) $(XMLLINT_FLAGS) $(myxmldir)/manpages-index.xml && \
 195           touch $@; \
 196         fi
 197
 198 check-local: valid-manual valid-manpages
 199
 200 # The text version of the FAQ.
 201 FAQ.txt:
 202         @echo "Generating the text version of the FAQ ..."
 203         export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
 204         $(XSLTPROC) $(XSLTPROC_FLAGS) -o ./FAQ.txt $(XSL_TEXT_STYLE) $(myxmldir)/FAQ.xml
 205
 206 # the valgrind manpages
 207 man-pages:
 208         set -e; \
 209         for x in $(XSL_MAN_STYLES) ; do \
 210             if test -f $$x; then \
 211                 echo "Using manpage stylesheet: $$x"; \
 212                 export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
 213                 $(XSLTPROC) $(XSLTPROC_FLAGS) -o ./ $$x $(myxmldir)/manpages-index.xml; \
 214                 exit 0; \
 215             fi; \
 216         done; \
 217         echo ""; \
 218         echo "Error: I can't find the XSL_MAN_STYLE file";     \
 219         echo "Please check where it lives on your system, and"      \
 220              "amend the line 'XSL_MAN_STYLES = ' in this Makefile."; \
 221         exit 1;
 222
 223 # chunked html, on a chapter-by-chapter basis
 224 html-docs:
 225         @echo "Generating html files..."
 226         export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
 227         mkdir -p $(myhtmldir) && \
 228         /bin/rm -fr $(myhtmldir)/ && \
 229         mkdir -p $(myhtmldir)/ && \
 230         mkdir -p $(myhtmldir)/images && \
 231         cp $(mylibdir)/vg_basic.css $(myhtmldir)/ && \
 232         cp $(myimgdir)/*.png $(myhtmldir)/images && \
 233         $(XSLTPROC) $(XSLTPROC_FLAGS) -o $(myhtmldir)/ $(XSL_HTML_CHUNK_STYLE) $(myxmldir)/index.xml
 234
 235 # pdf and postscript
 236 print-docs:
 237         @echo "Generating PDF file: $(myprintdir)/index.pdf (please be patient)...";
 238         export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
 239         mkdir -p $(myprintdir) && \
 240         mkdir -p $(myprintdir)/images && \
 241         cp $(myimgdir)/*.png $(myprintdir)/images && \
 242         xmlto -v $(WITH_FOP) --stringparam=keep.relative.image.uris="1" \
 243               -x $(XSL_FO_STYLE) \
 244               --searchpath $(top_builddir)/docs/xml:print \
 245               pdf $(myxmldir)/index.xml &> $(LOGFILE) && \
 246         echo "Generating PS file: $(myprintdir)/index.ps ..." && \
 247         pdftops index.pdf && \
 248         mv index.pdf index.ps $(myprintdir) && \
 249         rm $(LOGFILE)
 250
 251 # If the docs have been built, install them.  But don't worry if they have
 252 # not -- developers do 'make install' not from a 'make dist'-ified distro all
 253 # the time.
 254 #
 255 # Note: this is done at 'make install' time.
 256 # Note 2: the ifeq/else/endif have to be indented one space
 257 # because otherwise it seems that automake thinks it should
 258 # be the one to handle the else/endif parts, not GNU make
 259 # as we intend.
 260 install-data-hook:
 261         set -e; \
 262         if test -r html ; then \
 263                 mkdir -p $(DESTDIR)$(datadir)/doc/valgrind; \
 264                 cp -r html $(DESTDIR)$(datadir)/doc/valgrind; \
 265         fi
 266         for f in *.1 ; do \
 267                 if test -r $$f ; then \
 268                         mkdir -p $(DESTDIR)$(mandir)/man1; \
 269                         cp $$f $(DESTDIR)$(mandir)/man1; \
 270                 fi \
 271         done
 272  ifeq ($(BUILD_ALL_DOCS),yes)
 273         set -e; \
 274         if test -r index.pdf ; then \
 275                 mkdir -p $(DESTDIR)$(datadir)/doc/valgrind; \
 276                 cp index.pdf $(DESTDIR)$(datadir)/doc/valgrind/valgrind_manual.pdf; \
 277         fi
 278         set -e; \
 279         if test -r index.ps ; then \
 280                 mkdir -p $(DESTDIR)$(datadir)/doc/valgrind; \
 281                 cp index.ps $(DESTDIR)$(datadir)/doc/valgrind/valgrind_manual.ps; \
 282         fi
 283  endif
 284
 285 # This is done at 'make dist' time.  It builds the html docs, print
 286 # docs and man pages and copies them into the docs/ directory in the
 287 # tarball.
 288  ifeq ($(BUILD_ALL_DOCS),yes)
 289 dist-hook: FAQ.txt html-docs man-pages print-docs
 290         cp -r html $(distdir)
 291         cp FAQ.txt $(distdir)/..
 292         cp *.1 $(distdir)
 293         cp print/index.pdf $(distdir)
 294         cp print/index.ps $(distdir)
 295  else
 296 dist-hook: FAQ.txt html-docs man-pages
 297         cp -r html $(distdir)
 298         cp FAQ.txt $(distdir)/..
 299         cp *.1 $(distdir)
 300  endif
 301
 302 distclean-local:
 303         rm -rf html print
 304         rm -f FAQ.txt
 305         rm -f $(top_builddir)/FAQ.txt $(top_builddir)/docs/*.1
 306
 307 clean-local:
 308         rm -f valid-manual valid-manpages
 309
 310
 311 # -----------------------------------------------------------------------
 312 # Note: the rest of this file is nothing to do with the normal build
 313 # tree.  The stuff below contains special targets for web-site
 314 # artefacts.
 315
 316 # chunked html with no html/body tags, css, or top nav, to fit into the website
 317 website-docs:
 318         @echo "Generating website html files ..."
 319         export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
 320         /bin/rm -fr $(websitedir)
 321         mkdir -p $(websitedir)
 322         $(XSLTPROC) $(XSLTPROC_FLAGS) -o $(websitedir)/ $(XSL_WEBSITE_STYLE) $(myxmldir)/index.xml
 323
 324 # valkyrie carries around her own copy of the valgrind manual
 325 valkyrie-docs:
 326         @echo "Generating a set of valgrind docs for valkyrie..."
 327         export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
 328         /bin/rm -fr $(valkyriedir)
 329         mkdir -p $(valkyriedir)
 330         mkdir -p $(valkyriedir)/images
 331         cp $(mylibdir)/vg_basic.css $(valkyriedir)/
 332         cp $(myimgdir)/*.png $(valkyriedir)/images/
 333         $(XSLTPROC) $(XSLTPROC_FLAGS) -o $(valkyriedir)/ $(XSL_HTML_CHUNK_STYLE) $(myxmldir)/index.xml
 334
 335 # html.tar.bz2, .pdf, .ps.bz2 files for downloading from the website
 336 download-docs:
 337         export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
 338         /bin/rm -fr $(downloadsdir)
 339         mkdir -p $(downloadsdir)
 340         @echo ""
 341         @echo "Generating valgrind_manual.html.tar.bz2 ..."
 342         export XML_CATALOG_FILES=$(XML_CATALOG_FILES)
 343         /bin/rm -fr $(vgdir)
 344         mkdir -p $(vgdir)
 345         mkdir -p $(vgdir)/html
 346         mkdir -p $(vgdir)/html/images
 347         cp $(mylibdir)/vg_basic.css $(vgdir)/html/
 348         cp $(myimgdir)/*.png $(vgdir)/html/images/
 349         $(XSLTPROC) $(XSLTPROC_FLAGS) -o $(vgdir)/html/ $(XSL_HTML_CHUNK_STYLE) $(myxmldir)/index.xml
 350         (cd $(top_builddir)/docs/ && \
 351                 (tar cfj $(downloadsdir)/valgrind_manual.html.tar.bz2 ./valgrind/html/ ) )
 352         /bin/rm -fr $(vgdir)/html/
 353         @echo ""
 354         @echo "Generating valgrind_manual.pdf ..."
 355         mkdir -p $(vgdir)/print
 356         mkdir -p $(vgdir)/print/images
 357         cp $(myimgdir)/*.png $(vgdir)/print/images/
 358         xmlto -v $(WITH_FOP) --stringparam=keep.relative.image.uris="1" \
 359               -x $(XSL_FO_STYLE) \
 360               --searchpath $(top_builddir)/docs/xml:print \
 361               pdf $(myxmldir)/index.xml &> $(LOGFILE)
 362         mv index.pdf $(vgdir)/print/manual.pdf
 363         @echo ""
 364         @echo "Generating valgrind_manual.ps.bz2 ..."
 365         (cd $(vgdir)/print/ && \
 366                 ( pdftops manual.pdf ) )
 367         mv $(vgdir)/print/manual.pdf $(downloadsdir)/valgrind_manual.pdf
 368         mv $(vgdir)/print/manual.ps $(downloadsdir)/valgrind_manual.ps
 369         bzip2 $(downloadsdir)/valgrind_manual.ps
 370         /bin/rm -fr $(vgdir) $(LOGFILE)