1###
2# This makefile is used to generate the kernel documentation,
3# primarily based on in-line comments in various source files.
4# See Documentation/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
9DOCBOOKS := z8530book.xml device-drivers.xml \
10	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11	    writing_usb_driver.xml networking.xml \
12	    kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15	    80211.xml debugobjects.xml sh.xml regulator.xml \
16	    alsa-driver-api.xml writing-an-alsa-driver.xml \
17	    tracepoint.xml drm.xml media_api.xml w1.xml \
18	    writing_musb_glue_layer.xml crypto-API.xml
19
20include Documentation/DocBook/media/Makefile
21
22###
23# The build process is as follows (targets):
24#              (xmldocs) [by docproc]
25# file.tmpl --> file.xml +--> file.ps   (psdocs)   [by db2ps or xmlto]
26#                        +--> file.pdf  (pdfdocs)  [by db2pdf or xmlto]
27#                        +--> DIR=file  (htmldocs) [by xmlto]
28#                        +--> man/      (mandocs)  [by xmlto]
29
30
31# for PDF and PS output you can choose between xmlto and docbook-utils tools
32PDF_METHOD	= $(prefer-db2x)
33PS_METHOD	= $(prefer-db2x)
34
35
36###
37# The targets that may be used.
38PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
39
40targets += $(DOCBOOKS)
41BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
42xmldocs: $(BOOKS)
43sgmldocs: xmldocs
44
45PS := $(patsubst %.xml, %.ps, $(BOOKS))
46psdocs: $(PS)
47
48PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
49pdfdocs: $(PDF)
50
51HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
52htmldocs: $(HTML)
53	$(call build_main_index)
54	$(call build_images)
55	$(call install_media_images)
56
57MAN := $(patsubst %.xml, %.9, $(BOOKS))
58mandocs: $(MAN)
59	find $(obj)/man -name '*.9' | xargs gzip -f
60
61installmandocs: mandocs
62	mkdir -p /usr/local/man/man9/
63	install $(obj)/man/*.9.gz /usr/local/man/man9/
64
65###
66#External programs used
67KERNELDOC = $(srctree)/scripts/kernel-doc
68DOCPROC   = $(objtree)/scripts/docproc
69
70XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
71XMLTOFLAGS += --skip-validation
72
73###
74# DOCPROC is used for two purposes:
75# 1) To generate a dependency list for a .tmpl file
76# 2) To preprocess a .tmpl file and call kernel-doc with
77#     appropriate parameters.
78# The following rules are used to generate the .xml documentation
79# required to generate the final targets. (ps, pdf, html).
80quiet_cmd_docproc = DOCPROC $@
81      cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
82define rule_docproc
83	set -e;								\
84        $(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';) 	\
85        $(cmd_$(1)); 							\
86        ( 								\
87          echo 'cmd_$@ := $(cmd_$(1))'; 				\
88          echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; 		\
89        ) > $(dir $@).$(notdir $@).cmd
90endef
91
92%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
93	$(call if_changed_rule,docproc)
94
95# Tell kbuild to always build the programs
96always := $(hostprogs-y)
97
98notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
99		   exit 1
100db2xtemplate = db2TYPE -o $(dir $@) $<
101xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
102
103# determine which methods are available
104ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
105	use-db2x = db2x
106	prefer-db2x = db2x
107else
108	use-db2x = notfound
109	prefer-db2x = $(use-xmlto)
110endif
111ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
112	use-xmlto = xmlto
113	prefer-xmlto = xmlto
114else
115	use-xmlto = notfound
116	prefer-xmlto = $(use-db2x)
117endif
118
119# the commands, generated from the chosen template
120quiet_cmd_db2ps = PS      $@
121      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
122%.ps : %.xml
123	$(call cmd,db2ps)
124
125quiet_cmd_db2pdf = PDF     $@
126      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
127%.pdf : %.xml
128	$(call cmd,db2pdf)
129
130
131index = index.html
132main_idx = $(obj)/$(index)
133build_main_index = rm -rf $(main_idx); \
134		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
135		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
136		   cat $(HTML) >> $(main_idx)
137
138quiet_cmd_db2html = HTML    $@
139      cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
140		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
141		$(patsubst %.html,%,$(notdir $@))</a><p>' > $@
142
143%.html:	%.xml
144	@(which xmlto > /dev/null 2>&1) || \
145	 (echo "*** You need to install xmlto ***"; \
146	  exit 1)
147	@rm -rf $@ $(patsubst %.html,%,$@)
148	$(call cmd,db2html)
149	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
150            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
151
152quiet_cmd_db2man = MAN     $@
153      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; fi
154%.9 : %.xml
155	@(which xmlto > /dev/null 2>&1) || \
156	 (echo "*** You need to install xmlto ***"; \
157	  exit 1)
158	$(Q)mkdir -p $(obj)/man
159	$(call cmd,db2man)
160	@touch $@
161
162###
163# Rules to generate postscripts and PNG images from .fig format files
164quiet_cmd_fig2eps = FIG2EPS $@
165      cmd_fig2eps = fig2dev -Leps $< $@
166
167%.eps: %.fig
168	@(which fig2dev > /dev/null 2>&1) || \
169	 (echo "*** You need to install transfig ***"; \
170	  exit 1)
171	$(call cmd,fig2eps)
172
173quiet_cmd_fig2png = FIG2PNG $@
174      cmd_fig2png = fig2dev -Lpng $< $@
175
176%.png: %.fig
177	@(which fig2dev > /dev/null 2>&1) || \
178	 (echo "*** You need to install transfig ***"; \
179	  exit 1)
180	$(call cmd,fig2png)
181
182###
183# Rule to convert a .c file to inline XML documentation
184       gen_xml = :
185 quiet_gen_xml = echo '  GEN     $@'
186silent_gen_xml = :
187%.xml: %.c
188	@$($(quiet)gen_xml)
189	@(                            \
190	   echo "<programlisting>";   \
191	   expand --tabs=8 < $< |     \
192	   sed -e "s/&/\\&amp;/g"     \
193	       -e "s/</\\&lt;/g"      \
194	       -e "s/>/\\&gt;/g";     \
195	   echo "</programlisting>")  > $@
196
197###
198# Help targets as used by the top-level makefile
199dochelp:
200	@echo  ' Linux kernel internal documentation in different formats:'
201	@echo  '  htmldocs        - HTML'
202	@echo  '  pdfdocs         - PDF'
203	@echo  '  psdocs          - Postscript'
204	@echo  '  xmldocs         - XML DocBook'
205	@echo  '  mandocs         - man pages'
206	@echo  '  installmandocs  - install man pages generated by mandocs'
207	@echo  '  cleandocs       - clean all generated DocBook files'
208
209###
210# Temporary files left by various tools
211clean-files := $(DOCBOOKS) \
212	$(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
213	$(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
214	$(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
215	$(patsubst %.xml, %.log,  $(DOCBOOKS)) \
216	$(patsubst %.xml, %.out,  $(DOCBOOKS)) \
217	$(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
218	$(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
219	$(patsubst %.xml, %.html, $(DOCBOOKS)) \
220	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
221	$(index)
222
223clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
224
225cleandocs: cleanmediadocs
226	$(Q)rm -f $(call objectify, $(clean-files))
227	$(Q)rm -rf $(call objectify, $(clean-dirs))
228
229# Declare the contents of the .PHONY variable as phony.  We keep that
230# information in a variable se we can use it in if_changed and friends.
231
232.PHONY: $(PHONY)
233