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 ducument the SRC - and how to read it.
6 # To add a new book the only step required is to add the book to the
9 DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11 procfs-guide.xml writing_usb_driver.xml scsidrivers.xml \
12 sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \
13 gadget.xml libata.xml mtdnand.xml librs.xml
16 # The build process is as follows (targets):
18 # file.tmpl --> file.xml +--> file.ps (psdocs)
19 # +--> file.pdf (pdfdocs)
20 # +--> DIR=file (htmldocs)
24 # The targets that may be used.
25 .PHONY: xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs
27 BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
31 PS := $(patsubst %.xml, %.ps, $(BOOKS))
34 PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
37 HTML := $(patsubst %.xml, %.html, $(BOOKS))
40 MAN := $(patsubst %.xml, %.9, $(BOOKS))
43 installmandocs: mandocs
44 mkdir -p /usr/local/man/man9/
45 install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
48 #External programs used
49 KERNELDOC = scripts/kernel-doc
50 DOCPROC = scripts/basic/docproc
52 #XMLTOFLAGS = --skip-validation
55 # DOCPROC is used for two purposes:
56 # 1) To generate a dependency list for a .tmpl file
57 # 2) To preprocess a .tmpl file and call kernel-doc with
58 # appropriate parameters.
59 # The following rules are used to generate the .xml documentation
60 # required to generate the final targets. (ps, pdf, html).
61 quiet_cmd_docproc = DOCPROC $@
62 cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
65 $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
68 echo 'cmd_$@ := $(cmd_$(1))'; \
69 echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
70 ) > $(dir $@).$(notdir $@).cmd
74 $(call if_changed_rule,docproc)
77 #Read in all saved dependency files
78 cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
85 # Changes in kernel-doc force a rebuild of all documentation
86 $(BOOKS): $(KERNELDOC)
89 # procfs guide uses a .c file as example code.
90 # This requires an explicit dependency
91 C-procfs-example = procfs_example.xml
92 C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
93 $(obj)/procfs-guide.xml: $(C-procfs-example2)
96 # Rules to generate postscript, PDF and HTML
97 # db2html creates a directory. Generate a html file used for timestamp
99 quiet_cmd_db2ps = XMLTO $@
100 cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $<
102 @(which xmlto > /dev/null 2>&1) || \
103 (echo "*** You need to install DocBook stylesheets ***"; \
107 quiet_cmd_db2pdf = XMLTO $@
108 cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $<
110 @(which xmlto > /dev/null 2>&1) || \
111 (echo "*** You need to install DocBook stylesheets ***"; \
115 quiet_cmd_db2html = XMLTO $@
116 cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
117 echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \
118 Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
121 @(which xmlto > /dev/null 2>&1) || \
122 (echo "*** You need to install DocBook stylesheets ***"; \
124 @rm -rf $@ $(patsubst %.html,%,$@)
126 @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
127 cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
129 quiet_cmd_db2man = XMLTO $@
130 cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
132 @(which xmlto > /dev/null 2>&1) || \
133 (echo "*** You need to install DocBook stylesheets ***"; \
139 # Rules to generate postscripts and PNG imgages from .fig format files
140 quiet_cmd_fig2eps = FIG2EPS $@
141 cmd_fig2eps = fig2dev -Leps $< $@
144 @(which fig2dev > /dev/null 2>&1) || \
145 (echo "*** You need to install transfig ***"; \
149 quiet_cmd_fig2png = FIG2PNG $@
150 cmd_fig2png = fig2dev -Lpng $< $@
153 @(which fig2dev > /dev/null 2>&1) || \
154 (echo "*** You need to install transfig ***"; \
159 # Rule to convert a .c file to inline XML documentation
163 echo "<programlisting>"; \
164 expand --tabs=8 < $< | \
165 sed -e "s/&/\\&/g" \
168 echo "</programlisting>") > $@
171 # Help targets as used by the top-level makefile
173 @echo ' Linux kernel internal documentation in different formats:'
174 @echo ' xmldocs (XML DocBook), psdocs (Postscript), pdfdocs (PDF)'
175 @echo ' htmldocs (HTML), mandocs (man pages, use installmandocs to install)'
178 # Temporary files left by various tools
179 clean-files := $(DOCBOOKS) \
180 $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
181 $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
182 $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
183 $(patsubst %.xml, %.log, $(DOCBOOKS)) \
184 $(patsubst %.xml, %.out, $(DOCBOOKS)) \
185 $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
186 $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
187 $(patsubst %.xml, %.html, $(DOCBOOKS)) \
188 $(patsubst %.xml, %.9, $(DOCBOOKS)) \
191 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS))
193 #man put files in man subdir - traverse down