doc/DocBook/Makefile

   1 ###
   2 # This makefile is used to generate the kernel documentation,
   3 # primarily based on in-line comments in various source files.
   4 # See doc/kernel-doc-nano-HOWTO.txt for instruction in how
   5 # to document the SRC - and how to read it.
   6 # To add a new book the only step required is to add the book to the
   7 # list of DOCBOOKS.
   8
   9 include $(TOPDIR)/config.mk
  10
  11 DOCBOOKS := fs.xml linker_lists.xml stdio.xml
  12
  13 ###
  14 # The build process is as follows (targets):
  15 #              (xmldocs) [by docproc]
  16 # file.tmpl --> file.xml +--> file.ps   (psdocs)   [by db2ps or xmlto]
  17 #                        +--> file.pdf  (pdfdocs)  [by db2pdf or xmlto]
  18 #                        +--> DIR=file  (htmldocs) [by xmlto]
  19 #                        +--> man/      (mandocs)  [by xmlto]
  20
  21
  22 # for PDF and PS output you can choose between xmlto and docbook-utils tools
  23 PDF_METHOD      = $(prefer-db2x)
  24 PS_METHOD       = $(prefer-db2x)
  25
  26
  27 ###
  28 # The targets that may be used.
  29 PHONY += $(obj).depend xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
  30
  31 BOOKS := $(addprefix $(OBJTREE)/doc/DocBook/,$(DOCBOOKS))
  32 xmldocs: $(BOOKS)
  33 sgmldocs: xmldocs
  34
  35 PS := $(patsubst %.xml, %.ps, $(BOOKS))
  36 psdocs: $(PS)
  37
  38 PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
  39 pdfdocs: $(PDF)
  40
  41 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
  42 htmldocs: $(HTML)
  43         $(call build_main_index)
  44         $(call build_images)
  45         $(call install_media_images)
  46
  47 MAN := $(patsubst %.xml, %.9, $(BOOKS))
  48 mandocs: $(MAN)
  49
  50 installmandocs: mandocs
  51         mkdir -p /usr/local/man/man9/
  52         install doc/DocBook/man/*.9.gz /usr/local/man/man9/
  53
  54 ###
  55 #External programs used
  56 KERNELDOC = $(SRCTREE)/tools/kernel-doc/kernel-doc
  57 DOCPROC   = $(OBJTREE)/tools/kernel-doc/docproc
  58
  59 XMLTOFLAGS = -m $(SRCTREE)/doc/DocBook/stylesheet.xsl
  60 XMLTOFLAGS += --skip-validation
  61
  62 ###
  63 # DOCPROC is used for two purposes:
  64 # 1) To generate a dependency list for a .tmpl file
  65 # 2) To preprocess a .tmpl file and call kernel-doc with
  66 #     appropriate parameters.
  67 # The following rules are used to generate the .xml documentation
  68 # required to generate the final targets. (ps, pdf, html).
  69 %.xml: %.tmpl
  70         $(DOCPROC) doc $< >$@
  71
  72 ifeq ($@, "cleandocs")
  73 sinclude $(obj).depend
  74 $(obj).depend: $(patsubst %.xml, %.tmpl, $(DOCBOOKS))
  75         rm -f $(obj).depend ;                                   \
  76         touch $(obj).depend ;                                   \
  77         for file in $^ ; do                                     \
  78                 xmlfile=`echo "$${file}" |                      \
  79                         sed "s/tmpl$$/xml/"` ;                  \
  80                 echo -n "$${xmlfile}: ">> $(obj).depend ;       \
  81                 $(DOCPROC) depend $$file >> $(obj).depend ;     \
  82                 echo -e "\n\t$(DOCPROC) doc $< >$${xmlfile} " >>        \
  83                         $(obj).depend ;                         \
  84         done
  85 endif
  86
  87 ###
  88 # Changes in kernel-doc force a rebuild of all documentation
  89 $(BOOKS): $(KERNELDOC)
  90
  91 notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
  92                    exit 1
  93 db2xtemplate = db2TYPE -o $(dir $@) $<
  94 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
  95
  96 # determine which methods are available
  97 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
  98         use-db2x = db2x
  99         prefer-db2x = db2x
 100 else
 101         use-db2x = notfound
 102         prefer-db2x = $(use-xmlto)
 103 endif
 104 ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
 105         use-xmlto = xmlto
 106         prefer-xmlto = xmlto
 107 else
 108         use-xmlto = notfound
 109         prefer-xmlto = $(use-db2x)
 110 endif
 111
 112 # the commands, generated from the chosen template
 113 quiet_cmd_db2ps = PS      $@
 114       cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
 115 %.ps : %.xml
 116         $(call cmd_db2ps)
 117
 118 quiet_cmd_db2pdf = PDF     $@
 119       cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
 120 %.pdf : %.xml
 121         $(call cmd_db2pdf)
 122
 123
 124 index = index.html
 125 main_idx = $(index)
 126 build_main_index = rm -rf $(main_idx); \
 127                    echo '<h1>U-Boot Bootloader HTML Documentation</h1>' >> $(main_idx) && \
 128                    echo '<h2>U-Boot Version: $(U_BOOT_VERSION)</h2>' >> $(main_idx) && \
 129                    cat $(HTML) >> $(main_idx)
 130
 131 # To work around bug [1] in docbook-xsl-stylesheets 1.76.1 , generate only html
 132 # docs instead of xhtml with xmlto.
 133 # [1] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=654338
 134 quiet_cmd_db2html = HTML    $@
 135       cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
 136                 echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
 137         $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
 138
 139 %.html: %.xml
 140         @(which xmlto > /dev/null 2>&1) || \
 141          (echo "*** You need to install xmlto ***"; \
 142           exit 1)
 143         @rm -rf $@ $(patsubst %.html,%,$@)
 144         $(call cmd_db2html)
 145         @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
 146             cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
 147
 148 quiet_cmd_db2man = MAN     $@
 149       cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
 150 %.9 : %.xml
 151         @(which xmlto > /dev/null 2>&1) || \
 152          (echo "*** You need to install xmlto ***"; \
 153           exit 1)
 154         $(Q)mkdir -p $(obj)man
 155         $(call cmd_db2man)
 156         @touch $@
 157
 158 ###
 159 # Rules to generate postscripts and PNG images from .fig format files
 160 quiet_cmd_fig2eps = FIG2EPS $@
 161       cmd_fig2eps = fig2dev -Leps $< $@
 162
 163 %.eps: %.fig
 164         @(which fig2dev > /dev/null 2>&1) || \
 165          (echo "*** You need to install transfig ***"; \
 166           exit 1)
 167         $(call cmd_fig2eps)
 168
 169 quiet_cmd_fig2png = FIG2PNG $@
 170       cmd_fig2png = fig2dev -Lpng $< $@
 171
 172 %.png: %.fig
 173         @(which fig2dev > /dev/null 2>&1) || \
 174          (echo "*** You need to install transfig ***"; \
 175           exit 1)
 176         $(call cmd_fig2png)
 177
 178 ###
 179 # Rule to convert a .c file to inline XML documentation
 180        gen_xml = :
 181  quiet_gen_xml = echo '  GEN     $@'
 182 silent_gen_xml = :
 183 %.xml: %.c
 184         @$($(quiet)gen_xml)
 185         @(                            \
 186            echo "<programlisting>";   \
 187            expand --tabs=8 < $< |     \
 188            sed -e "s/&/\\&amp;/g"     \
 189                -e "s/</\\&lt;/g"      \
 190                -e "s/>/\\&gt;/g";     \
 191            echo "</programlisting>")  > $@
 192
 193 ###
 194 # Help targets as used by the top-level makefile
 195 dochelp:
 196         @echo  ' U-Boot bootloader internal documentation in different formats:'
 197         @echo  '  htmldocs        - HTML'
 198         @echo  '  pdfdocs         - PDF'
 199         @echo  '  psdocs          - Postscript'
 200         @echo  '  xmldocs         - XML DocBook'
 201         @echo  '  mandocs         - man pages'
 202         @echo  '  installmandocs  - install man pages generated by mandocs'
 203         @echo  '  cleandocs       - clean all generated DocBook files'
 204
 205 ###
 206 # Temporary files left by various tools
 207 clean-files := $(DOCBOOKS) \
 208         $(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
 209         $(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
 210         $(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
 211         $(patsubst %.xml, %.log,  $(DOCBOOKS)) \
 212         $(patsubst %.xml, %.out,  $(DOCBOOKS)) \
 213         $(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
 214         $(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
 215         $(patsubst %.xml, %.html, $(DOCBOOKS)) \
 216         $(patsubst %.xml, %.9,    $(DOCBOOKS)) \
 217         $(index)
 218
 219 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
 220
 221 cleandocs:
 222         @rm -f $(obj).depend
 223         @$(Q)rm -f $(call objectify, $(clean-files))
 224         @$(Q)rm -rf $(call objectify, $(clean-dirs))
 225
 226 # Declare the contents of the .PHONY variable as phony.  We keep that
 227 # information in a variable se we can use it in if_changed and friends.
 228
 229 .PHONY: $(PHONY)