libstdc++-v3/doc/Makefile.am

   1 ## Makefile for the doc subdirectory of the GNU C++ Standard library.
   2 ##
   3 ## Copyright (C) 2008, 2009, 2010 Free Software Foundation, Inc.
   4 ##
   5 ## This file is part of the libstdc++ version 3 distribution.
   6 ## Process this file with automake to produce Makefile.in.
   7
   8 ## This file is part of the GNU ISO C++ Library.  This library is free
   9 ## software; you can redistribute it and/or modify it under the
  10 ## terms of the GNU General Public License as published by the
  11 ## Free Software Foundation; either version 3, or (at your option)
  12 ## any later version.
  13
  14 ## This library is distributed in the hope that it will be useful,
  15 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ## GNU General Public License for more details.
  18
  19 ## You should have received a copy of the GNU General Public License along
  20 ## with this library; see the file COPYING3.  If not see
  21 ## <http://www.gnu.org/licenses/>.
  22
  23 include $(top_srcdir)/fragment.am
  24
  25 # Documentation Overview
  26 #
  27 # There are two main source materials for libstdc++ documentation.
  28 # The first is the doxygen markup in libstdc++ sources, which is a
  29 # reference to the API. And the second is the docbook markup in
  30 # doc/xml/.
  31 #
  32 # A third and more obscure option deals with charting
  33 # performance tests, and should be considered experimental.
  34
  35 # Default rules.
  36 #
  37 # Point to best sub-rule for the requested documentation target,
  38 # create, and then copy into toplevel directory with standardized names
  39 # and layouts.
  40
  41 # HTML
  42 doc-html: doc-html-docbook doc-html-doxygen
  43         cp -R ${docbook_outdir}/html ./libstdc++-manual.html
  44         cp -R ${doxygen_outdir}/html ./libstdc++-api.html
  45
  46 # MAN
  47 doc-man: doc-man-doxygen
  48         cp -R ${doxygen_outdir}/man ./libstdc++-api.man
  49
  50 # PDF
  51 doc-pdf: doc-pdf-docbook doc-pdf-doxygen
  52         cp ${docbook_outdir}/pdf/libstdc++-manual.pdf .
  53         cp ${doxygen_outdir}/pdf/libstdc++-api.pdf .
  54
  55 # TEXINFO
  56 doc-texinfo: doc-texinfo-docbook
  57
  58 # XML
  59 doc-xml: doc-xml-single-docbook doc-xml-single-doxygen
  60         cp ${manual_xml} .
  61         cp ${api_xml} .
  62
  63
  64 # Doxygen configuration
  65 # Assumes doxygen, graphviz (with dot), pdflatex installed
  66 doxygen_script=${top_srcdir}/scripts/run_doxygen
  67 doxygen_outdir = ${glibcxx_builddir}/doc/doxygen
  68
  69 doc-html-doxygen:
  70         -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
  71           builddir=`cd ..; ${PWD_COMMAND}`; \
  72           ${SHELL} ${doxygen_script} \
  73           --host_alias=${host_alias} --mode=html $${srcdir} $${builddir} YES)
  74
  75 doc-man-doxygen:
  76         -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
  77           builddir=`cd ..; ${PWD_COMMAND}`; \
  78           ${SHELL} ${doxygen_script} \
  79           --host_alias=${host_alias} --mode=man $${srcdir} $${builddir} YES)
  80
  81 doc-xml-doxygen:
  82         -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
  83           builddir=`cd ..; ${PWD_COMMAND}`; \
  84           ${SHELL} ${doxygen_script} \
  85           --host_alias=${host_alias} --mode=xml $${srcdir} $${builddir} NO)
  86
  87 api_xml = ${doxygen_outdir}/xml/libstdc++-api-single.xml
  88 doc-xml-single-doxygen: doc-xml-doxygen
  89         @echo "Generating doxygen xml single file..."
  90         $(XSLTPROC) ${doxygen_outdir}/xml/combine.xslt \
  91         ${doxygen_outdir}/xml/index.xml > ${api_xml};
  92
  93 doc-latex-doxygen:
  94         -(srcdir=`cd ${top_srcdir}; ${PWD_COMMAND}`; \
  95           builddir=`cd ..; ${PWD_COMMAND}`; \
  96           ${SHELL} ${doxygen_script} \
  97           --host_alias=${host_alias} --mode=latex $${srcdir} $${builddir} NO)
  98
  99 # Chance of loooooonnggg creation time on this rule.  Iff this fails,
 100 # look at refman.log and see if TeX's memory is exhausted. Symptoms
 101 # include asking a wizard to enlarge capacity. If this is the case,
 102 # find texmf.cnf and add a zero for pool_size, string_vacancies,
 103 # max_strings, and pool_free values.
 104 doxygen_pdf = ${doxygen_outdir}/latex/refman.pdf
 105 api_pdf = ${doxygen_outdir}/pdf/libstdc++-api.pdf
 106
 107 ${doxygen_outdir}/pdf:
 108         mkdir -p ${doxygen_outdir}/pdf
 109
 110 doc-pdf-doxygen: stamp-latex-doxygen ${doxygen_outdir}/pdf
 111         -(cd ${doxygen_outdir}/latex && $(MAKE) -i pdf;)
 112         echo "Generating doxygen pdf file...";
 113         if [ -f ${doxygen_pdf} ]; then \
 114           mv ${doxygen_pdf} ${api_pdf} ; \
 115           echo ":: PDF file is ${api_pdf}"; \
 116         else \
 117           echo "... error"; \
 118           exit 12; \
 119         fi
 120
 121 stamp-pdf-doxygen:
 122         @if [ ! -f stamp-pdf-doxygen ]; then \
 123           $(MAKE) doc-pdf-doxygen; \
 124         fi
 125         $(STAMP) stamp-pdf-doxygen
 126
 127 stamp-xml-doxygen:
 128         @if [ ! -f stamp-xml-doxygen ]; then \
 129           $(MAKE) doc-xml-doxygen; \
 130           $(MAKE) doc-xml-single-doxygen; \
 131         fi
 132         $(STAMP) stamp-xml-doxygen
 133
 134 stamp-latex-doxygen:
 135         @if [ ! -f stamp-latex-doxygen ]; then \
 136           $(MAKE) doc-latex-doxygen; \
 137         fi
 138         $(STAMP) stamp-latex-doxygen
 139
 140 # Docbook configuration.
 141 # Assumes
 142 # libxslt
 143 # dblatex
 144 # pdflatex
 145 # docbook-style-xsl
 146 # emacs-nxml-mode
 147 # xmlto passivetex
 148 docbook_outdir = ${glibcxx_builddir}/doc/docbook
 149 xml_dir = ${glibcxx_srcdir}/doc/xml
 150
 151 xml_sources_basic = \
 152         ${xml_dir}/spine.xml \
 153         ${xml_dir}/authors.xml \
 154         ${xml_dir}/api.xml \
 155         ${xml_dir}/faq.xml
 156
 157 xml_sources_manual = \
 158         ${xml_dir}/manual/abi.xml \
 159         ${xml_dir}/manual/algorithms.xml \
 160         ${xml_dir}/manual/allocator.xml \
 161         ${xml_dir}/manual/auto_ptr.xml \
 162         ${xml_dir}/manual/atomics.xml \
 163         ${xml_dir}/manual/backwards_compatibility.xml \
 164         ${xml_dir}/manual/bitmap_allocator.xml \
 165         ${xml_dir}/manual/build_hacking.xml \
 166         ${xml_dir}/manual/codecvt.xml \
 167         ${xml_dir}/manual/concurrency.xml \
 168         ${xml_dir}/manual/concurrency_extensions.xml \
 169         ${xml_dir}/manual/configure.xml \
 170         ${xml_dir}/manual/containers.xml \
 171         ${xml_dir}/manual/ctype.xml \
 172         ${xml_dir}/manual/debug_mode.xml \
 173         ${xml_dir}/manual/debug.xml \
 174         ${xml_dir}/manual/diagnostics.xml \
 175         ${xml_dir}/manual/evolution.xml \
 176         ${xml_dir}/manual/extensions.xml \
 177         ${xml_dir}/manual/internals.xml \
 178         ${xml_dir}/manual/intro.xml \
 179         ${xml_dir}/manual/io.xml \
 180         ${xml_dir}/manual/iterators.xml \
 181         ${xml_dir}/manual/locale.xml \
 182         ${xml_dir}/manual/localization.xml \
 183         ${xml_dir}/manual/messages.xml \
 184         ${xml_dir}/manual/mt_allocator.xml \
 185         ${xml_dir}/manual/numerics.xml \
 186         ${xml_dir}/manual/parallel_mode.xml \
 187         ${xml_dir}/manual/prerequisites.xml \
 188         ${xml_dir}/manual/profile_mode.xml \
 189         ${xml_dir}/manual/shared_ptr.xml \
 190         ${xml_dir}/manual/spine.xml \
 191         ${xml_dir}/manual/status_cxx1998.xml \
 192         ${xml_dir}/manual/status_cxx200x.xml \
 193         ${xml_dir}/manual/status_cxxtr1.xml \
 194         ${xml_dir}/manual/status_cxxtr24733.xml \
 195         ${xml_dir}/manual/strings.xml \
 196         ${xml_dir}/manual/support.xml \
 197         ${xml_dir}/manual/test.xml \
 198         ${xml_dir}/manual/using.xml \
 199         ${xml_dir}/manual/using_exceptions.xml \
 200         ${xml_dir}/manual/utilities.xml \
 201         ${xml_dir}/manual/appendix_free.xml \
 202         ${xml_dir}/manual/appendix_contributing.xml \
 203         ${xml_dir}/manual/appendix_porting.xml
 204
 205 xml_sources_extra = \
 206         ${xml_dir}/gnu/fdl-1.2.xml \
 207         ${xml_dir}/gnu/fdl-1.3.xml \
 208         ${xml_dir}/gnu/gpl-2.0.xml \
 209         ${xml_dir}/gnu/gpl-3.0.xml
 210
 211 xml_sources = \
 212         ${xml_sources_basic} \
 213         ${xml_sources_manual} \
 214         ${xml_sources_extra}
 215
 216 xml_noinst = \
 217         ${xml_dir}/book.txml \
 218         ${xml_dir}/chapter.txml \
 219         ${xml_dir}/class.txml
 220
 221 XSLTPROC       = xsltproc
 222 XSLTPROC_FLAGS = --nonet --xinclude
 223 XSL_STYLE_DIR = /usr/share/sgml/docbook/xsl-ns-stylesheets
 224 XSL_FO_STYLE = $(XSL_STYLE_DIR)/fo/docbook.xsl
 225 XSL_HTML_STYLE = $(XSL_STYLE_DIR)/xhtml/chunk.xsl
 226 #XSL_HTML_SINGLE_STYLE = $(XSL_STYLE_DIR)/xhtml/onechunk.xsl
 227 XSL_HTML_SINGLE_STYLE = $(XSL_STYLE_DIR)/xhtml/docbook.xsl
 228
 229 ${docbook_outdir}/fo:
 230         mkdir -p ${docbook_outdir}/fo
 231
 232 ${docbook_outdir}/html:
 233         mkdir -p ${docbook_outdir}/html
 234
 235 ${docbook_outdir}/pdf:
 236         mkdir -p ${docbook_outdir}/pdf
 237
 238 ${docbook_outdir}/texinfo:
 239         mkdir -p ${docbook_outdir}/texinfo
 240
 241 ${docbook_outdir}/xml:
 242         mkdir -p ${docbook_outdir}/xml
 243
 244 # Validate existing XML structure.
 245 XMLLINT = xmllint
 246 #LINT_FLAGS = --debug --nonet --xinclude --nsclean --postvalid --nowarning
 247 #LINT_FLAGS = --noblanks --noout --xinclude --postvalid --noent
 248 LINT_FLAGS = --debug --xinclude --noent --noblanks  --nonet --noout
 249 #SCHEMA_FLAGS = --relaxng /usr/share/xml/docbook5/schema/rng/5.0/docbookxi.rng
 250 SCHEMA_FLAGS = --dtdvalid /usr/share/xml/docbook5/schema/dtd/5.0/docbook.dtd
 251 XMLLINT_FLAGS = $(LINT_FLAGS) $(SCHEMA_FLAGS)
 252 doc-xml-validate-docbook: $(xml_sources)
 253         @echo "Generating XML validation log..."
 254         $(XMLLINT) $(XMLLINT_FLAGS) ${top_srcdir}/doc/xml/spine.xml
 255
 256 # XML, all one page
 257 # Some info on canonicalization
 258 # http://www.mail-archive.com/help-texinfo@gnu.org/msg00864.html
 259 manual_xml = ${docbook_outdir}/xml/libstdc++-manual-single.xml
 260 doc-xml-single-docbook: $(xml_sources) ${docbook_outdir}/xml
 261         @echo "Generating XML single..."
 262         $(XMLLINT) --xinclude --noent --noblanks --nocdata --nsclean --c14n \
 263         ${top_srcdir}/doc/xml/manual/spine.xml > ${manual_xml}
 264
 265 # HTML, index plus chapters
 266 doc-html-docbook: $(xml_sources) ${docbook_outdir}/html
 267         @echo "Generating html files..."
 268         $(XSLTPROC) $(XSLTPROC_FLAGS) -o ${docbook_outdir}/html/ \
 269         $(XSL_HTML_STYLE) ${top_srcdir}/doc/xml/spine.xml
 270
 271 # HTML, all one page
 272 manual_html = ${docbook_outdir}/html/libstdc++-manual-single.html
 273 doc-html-single-docbook: $(xml_sources) ${docbook_outdir}/html
 274         @echo "Generating html single file..."
 275         $(XSLTPROC) $(XSLTPROC_FLAGS) -o ${manual_html} \
 276         $(XSL_HTML_SINGLE_STYLE) ${top_srcdir}/doc/xml/spine.xml
 277
 278 # FO
 279 doc-fo-docbook: $(xml_sources) ${docbook_outdir}/fo
 280         @echo "Generating FO files..."
 281         $(XSLTPROC) $(XSLTPROC_FLAGS) -o ${docbook_outdir}/fo/spine.fo \
 282         $(XSL_FO_STYLE) ${top_srcdir}/doc/xml/spine.xml
 283
 284 # PDF, via dblatex
 285 manual_pdf = ${docbook_outdir}/pdf/libstdc++-manual.pdf
 286 DBLATEX_FLAGS = --dump --verbose --pdf -o ${manual_pdf}
 287 doc-pdf-docbook: doc-pdf-dblatex-docbook
 288
 289 doc-pdf-dblatex-docbook: $(xml_sources) ${docbook_outdir}/pdf
 290         @echo "Generating pdf dblatex files..."
 291         dblatex $(DBLATEX_FLAGS) ${top_srcdir}/doc/xml/spine.xml
 292
 293 # Texinfo, via docbook2X
 294 DB2TEXI_FLAGS = \
 295         --encoding=utf-8//TRANSLIT \
 296         --string-param output-file="libstdc++-manual" \
 297         --string-param directory-category="GNU C++ Library" \
 298         --string-param explicit-node-names=true
 299 doc-texinfo-docbook: doc-xml-single-docbook ${docbook_outdir}/texinfo
 300         @echo "Generating texinfo files..."
 301         db2x_docbook2texi $(DB2TEXI_FLAGS) ${manual_xml}
 302
 303
 304 # Performance doc and graph configuration.
 305 # Assumes pychart, beautiful soup installed.
 306 # Generates the plots and graphs for performance testing.
 307 doc_performance_script=${top_srcdir}/scripts/make_graphs.py
 308 doc-html-performance:
 309         -@(chmod + ${doc_performance_script}; \
 310         ${doc_performance_script} ${top_srcdir} \
 311         ${glibcxx_builddir}/testsuite \
 312         ${top_srcdir}/testsuite/data/make_graph_htmls.xml \
 313         ${top_srcdir}/testsuite/data/make_graph_test_infos.xml local g++)
 314
 315
 316 .PHONY: doc-doxygen-html doc-doxygen-man doc-performance
 317
 318 # By adding these files here, automake will remove them for 'make clean'
 319 CLEANFILES = *.log
 320
 321 # To remove directories.
 322 clean-local:
 323         rm -rf man html pdf fo xml doxygen docbook stamp* ./libstdc++-* db2t*