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 23include $(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 42doc-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 47doc-man: doc-man-doxygen 48 cp -R ${doxygen_outdir}/man ./libstdc++-api.man 49 50# PDF 51doc-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 56doc-texinfo: doc-texinfo-docbook 57 58# XML 59doc-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 66doxygen_script=${top_srcdir}/scripts/run_doxygen 67doxygen_outdir = ${glibcxx_builddir}/doc/doxygen 68 69doc-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 75doc-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 81doc-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 87api_xml = ${doxygen_outdir}/xml/libstdc++-api-single.xml 88doc-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 93doc-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. 104doxygen_pdf = ${doxygen_outdir}/latex/refman.pdf 105api_pdf = ${doxygen_outdir}/pdf/libstdc++-api.pdf 106 107${doxygen_outdir}/pdf: 108 mkdir -p ${doxygen_outdir}/pdf 109 110doc-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 121stamp-pdf-doxygen: 122 @if [ ! -f stamp-pdf-doxygen ]; then \ 123 $(MAKE) doc-pdf-doxygen; \ 124 fi 125 $(STAMP) stamp-pdf-doxygen 126 127stamp-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 134stamp-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 148docbook_outdir = ${glibcxx_builddir}/doc/docbook 149xml_dir = ${glibcxx_srcdir}/doc/xml 150 151xml_sources_basic = \ 152 ${xml_dir}/spine.xml \ 153 ${xml_dir}/authors.xml \ 154 ${xml_dir}/api.xml \ 155 ${xml_dir}/faq.xml 156 157xml_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 205xml_sources_extra = \ 206 ${xml_dir}/gnu/fdl-1.2.xml \ 207 ${xml_dir}/gnu/gpl-3.0.xml 208 209xml_sources = \ 210 ${xml_sources_basic} \ 211 ${xml_sources_manual} \ 212 ${xml_sources_extra} 213 214xml_noinst = \ 215 ${xml_dir}/book.txml \ 216 ${xml_dir}/chapter.txml \ 217 ${xml_dir}/class.txml 218 219XSLTPROC = xsltproc 220XSLTPROC_FLAGS = --nonet --xinclude 221XSL_STYLE_DIR = /usr/share/sgml/docbook/xsl-stylesheets 222XSL_FO_STYLE = $(XSL_STYLE_DIR)/fo/docbook.xsl 223XSL_HTML_STYLE = $(XSL_STYLE_DIR)/xhtml/chunk.xsl 224#XSL_HTML_SINGLE_STYLE = $(XSL_STYLE_DIR)/xhtml/onechunk.xsl 225XSL_HTML_SINGLE_STYLE = $(XSL_STYLE_DIR)/xhtml/docbook.xsl 226 227${docbook_outdir}/fo: 228 mkdir -p ${docbook_outdir}/fo 229 230${docbook_outdir}/html: 231 mkdir -p ${docbook_outdir}/html 232 233${docbook_outdir}/pdf: 234 mkdir -p ${docbook_outdir}/pdf 235 236${docbook_outdir}/texinfo: 237 mkdir -p ${docbook_outdir}/texinfo 238 239${docbook_outdir}/xml: 240 mkdir -p ${docbook_outdir}/xml 241 242# Validate existing XML structure. 243XMLLINT = xmllint 244#LINT_FLAGS = --debug --nonet --xinclude --nsclean --postvalid --nowarning 245#LINT_FLAGS = --noblanks --noout --xinclude --postvalid --noent 246LINT_FLAGS = --postvalid --debug --xinclude --noent --noblanks --nonet --noout 247DTD_FLAGS = --dtdvalid http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd 248XMLLINT_FLAGS = $(LINT_FLAGS) $(DTD_FLAGS) 249doc-xml-validate-docbook: $(xml_sources) 250 @echo "Generating XML validation log..." 251 $(XMLLINT) $(XMLLINT_FLAGS) ${top_srcdir}/doc/xml/spine.xml 252 253# XML, all one page 254# Some info on canonicalization 255# http://www.mail-archive.com/help-texinfo@gnu.org/msg00864.html 256manual_xml = ${docbook_outdir}/xml/libstdc++-manual-single.xml 257doc-xml-single-docbook: $(xml_sources) ${docbook_outdir}/xml 258 @echo "Generating XML single..." 259 $(XMLLINT) --xinclude --noent --noblanks --nocdata --nsclean --c14n \ 260 ${top_srcdir}/doc/xml/manual/spine.xml > ${manual_xml} 261 262# HTML, index plus chapters 263doc-html-docbook: $(xml_sources) ${docbook_outdir}/html 264 @echo "Generating html files..." 265 $(XSLTPROC) $(XSLTPROC_FLAGS) -o ${docbook_outdir}/html/ \ 266 $(XSL_HTML_STYLE) ${top_srcdir}/doc/xml/spine.xml 267 268# HTML, all one page 269manual_html = ${docbook_outdir}/html/libstdc++-manual-single.html 270doc-html-single-docbook: $(xml_sources) ${docbook_outdir}/html 271 @echo "Generating html single file..." 272 $(XSLTPROC) $(XSLTPROC_FLAGS) -o ${manual_html} \ 273 $(XSL_HTML_SINGLE_STYLE) ${top_srcdir}/doc/xml/spine.xml 274 275# FO 276doc-fo-docbook: $(xml_sources) ${docbook_outdir}/fo 277 @echo "Generating FO files..." 278 $(XSLTPROC) $(XSLTPROC_FLAGS) -o ${docbook_outdir}/fo/spine.fo \ 279 $(XSL_FO_STYLE) ${top_srcdir}/doc/xml/spine.xml 280 281# PDF, via dblatex 282manual_pdf = ${docbook_outdir}/pdf/libstdc++-manual.pdf 283DBLATEX_FLAGS = --dump --verbose --pdf -o ${manual_pdf} 284doc-pdf-docbook: doc-pdf-dblatex-docbook 285 286doc-pdf-dblatex-docbook: $(xml_sources) ${docbook_outdir}/pdf 287 @echo "Generating pdf dblatex files..." 288 dblatex $(DBLATEX_FLAGS) ${top_srcdir}/doc/xml/spine.xml 289 290# Texinfo, via docbook2X 291DB2TEXI_FLAGS = \ 292 --encoding=utf-8//TRANSLIT \ 293 --string-param output-file="libstdc++-manual" \ 294 --string-param directory-category="GNU C++ Library" \ 295 --string-param explicit-node-names=true 296doc-texinfo-docbook: doc-xml-single-docbook ${docbook_outdir}/texinfo 297 @echo "Generating texinfo files..." 298 db2x_docbook2texi $(DB2TEXI_FLAGS) ${manual_xml} 299 300 301# Performance doc and graph configuration. 302# Assumes pychart, beautiful soup installed. 303# Generates the plots and graphs for performance testing. 304doc_performance_script=${top_srcdir}/scripts/make_graphs.py 305doc-html-performance: 306 -@(chmod + ${doc_performance_script}; \ 307 ${doc_performance_script} ${top_srcdir} \ 308 ${glibcxx_builddir}/testsuite \ 309 ${top_srcdir}/testsuite/data/make_graph_htmls.xml \ 310 ${top_srcdir}/testsuite/data/make_graph_test_infos.xml local g++) 311 312 313.PHONY: doc-doxygen-html doc-doxygen-man doc-performance 314 315# By adding these files here, automake will remove them for 'make clean' 316CLEANFILES = *.log 317 318# To remove directories. 319clean-local: 320 rm -rf man html pdf fo xml doxygen docbook stamp* ./libstdc++-* db2t* 321