8b0c2d989c
xmlto uses standared XSLT templates to generate manpages, (x)html pages, and XML FO files which can be processed with passivetex. This is much faster than using jadetex for everything. This patch also reduces the number of kernel-specific scripts that are needed to generate documentation. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
195 lines
5.8 KiB
Makefile
195 lines
5.8 KiB
Makefile
###
|
|
# This makefile is used to generate the kernel documentation,
|
|
# primarily based on in-line comments in various source files.
|
|
# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
|
|
# to ducument the SRC - and how to read it.
|
|
# To add a new book the only step required is to add the book to the
|
|
# list of DOCBOOKS.
|
|
|
|
DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
|
|
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
|
|
procfs-guide.xml writing_usb_driver.xml scsidrivers.xml \
|
|
sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \
|
|
gadget.xml libata.xml mtdnand.xml librs.xml
|
|
|
|
###
|
|
# The build process is as follows (targets):
|
|
# (xmldocs)
|
|
# file.tmpl --> file.xml +--> file.ps (psdocs)
|
|
# +--> file.pdf (pdfdocs)
|
|
# +--> DIR=file (htmldocs)
|
|
# +--> man/ (mandocs)
|
|
|
|
###
|
|
# The targets that may be used.
|
|
.PHONY: xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs
|
|
|
|
BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
|
|
xmldocs: $(BOOKS)
|
|
sgmldocs: xmldocs
|
|
|
|
PS := $(patsubst %.xml, %.ps, $(BOOKS))
|
|
psdocs: $(PS)
|
|
|
|
PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
|
|
pdfdocs: $(PDF)
|
|
|
|
HTML := $(patsubst %.xml, %.html, $(BOOKS))
|
|
htmldocs: $(HTML)
|
|
|
|
MAN := $(patsubst %.xml, %.9, $(BOOKS))
|
|
mandocs: $(MAN)
|
|
|
|
installmandocs: mandocs
|
|
mkdir -p /usr/local/man/man9/
|
|
install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
|
|
|
|
###
|
|
#External programs used
|
|
KERNELDOC = scripts/kernel-doc
|
|
DOCPROC = scripts/basic/docproc
|
|
|
|
#XMLTOFLAGS = --skip-validation
|
|
|
|
###
|
|
# DOCPROC is used for two purposes:
|
|
# 1) To generate a dependency list for a .tmpl file
|
|
# 2) To preprocess a .tmpl file and call kernel-doc with
|
|
# appropriate parameters.
|
|
# The following rules are used to generate the .xml documentation
|
|
# required to generate the final targets. (ps, pdf, html).
|
|
quiet_cmd_docproc = DOCPROC $@
|
|
cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
|
|
define rule_docproc
|
|
set -e; \
|
|
$(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
|
|
$(cmd_$(1)); \
|
|
( \
|
|
echo 'cmd_$@ := $(cmd_$(1))'; \
|
|
echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
|
|
) > $(dir $@).$(notdir $@).cmd
|
|
endef
|
|
|
|
%.xml: %.tmpl FORCE
|
|
$(call if_changed_rule,docproc)
|
|
|
|
###
|
|
#Read in all saved dependency files
|
|
cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
|
|
|
|
ifneq ($(cmd_files),)
|
|
include $(cmd_files)
|
|
endif
|
|
|
|
###
|
|
# Changes in kernel-doc force a rebuild of all documentation
|
|
$(BOOKS): $(KERNELDOC)
|
|
|
|
###
|
|
# procfs guide uses a .c file as example code.
|
|
# This requires an explicit dependency
|
|
C-procfs-example = procfs_example.xml
|
|
C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
|
|
$(obj)/procfs-guide.xml: $(C-procfs-example2)
|
|
|
|
###
|
|
# Rules to generate postscript, PDF and HTML
|
|
# db2html creates a directory. Generate a html file used for timestamp
|
|
|
|
quiet_cmd_db2ps = XMLTO $@
|
|
cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $<
|
|
%.ps : %.xml
|
|
@(which xmlto > /dev/null 2>&1) || \
|
|
(echo "*** You need to install DocBook stylesheets ***"; \
|
|
exit 1)
|
|
$(call cmd,db2ps)
|
|
|
|
quiet_cmd_db2pdf = XMLTO $@
|
|
cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $<
|
|
%.pdf : %.xml
|
|
@(which xmlto > /dev/null 2>&1) || \
|
|
(echo "*** You need to install DocBook stylesheets ***"; \
|
|
exit 1)
|
|
$(call cmd,db2pdf)
|
|
|
|
quiet_cmd_db2html = XMLTO $@
|
|
cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
|
|
echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \
|
|
Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
|
|
|
|
%.html: %.xml
|
|
@(which xmlto > /dev/null 2>&1) || \
|
|
(echo "*** You need to install DocBook stylesheets ***"; \
|
|
exit 1)
|
|
@rm -rf $@ $(patsubst %.html,%,$@)
|
|
$(call cmd,db2html)
|
|
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
|
|
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
|
|
|
|
quiet_cmd_db2man = XMLTO $@
|
|
cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
|
|
%.9 : %.xml
|
|
@(which xmlto > /dev/null 2>&1) || \
|
|
(echo "*** You need to install DocBook stylesheets ***"; \
|
|
exit 1)
|
|
$(call cmd,db2man)
|
|
@touch $@
|
|
|
|
###
|
|
# Rules to generate postscripts and PNG imgages from .fig format files
|
|
quiet_cmd_fig2eps = FIG2EPS $@
|
|
cmd_fig2eps = fig2dev -Leps $< $@
|
|
|
|
%.eps: %.fig
|
|
@(which fig2dev > /dev/null 2>&1) || \
|
|
(echo "*** You need to install transfig ***"; \
|
|
exit 1)
|
|
$(call cmd,fig2eps)
|
|
|
|
quiet_cmd_fig2png = FIG2PNG $@
|
|
cmd_fig2png = fig2dev -Lpng $< $@
|
|
|
|
%.png: %.fig
|
|
@(which fig2dev > /dev/null 2>&1) || \
|
|
(echo "*** You need to install transfig ***"; \
|
|
exit 1)
|
|
$(call cmd,fig2png)
|
|
|
|
###
|
|
# Rule to convert a .c file to inline XML documentation
|
|
%.xml: %.c
|
|
@echo ' GEN $@'
|
|
@( \
|
|
echo "<programlisting>"; \
|
|
expand --tabs=8 < $< | \
|
|
sed -e "s/&/\\&/g" \
|
|
-e "s/</\\</g" \
|
|
-e "s/>/\\>/g"; \
|
|
echo "</programlisting>") > $@
|
|
|
|
###
|
|
# Help targets as used by the top-level makefile
|
|
dochelp:
|
|
@echo ' Linux kernel internal documentation in different formats:'
|
|
@echo ' xmldocs (XML DocBook), psdocs (Postscript), pdfdocs (PDF)'
|
|
@echo ' htmldocs (HTML), mandocs (man pages, use installmandocs to install)'
|
|
|
|
###
|
|
# Temporary files left by various tools
|
|
clean-files := $(DOCBOOKS) \
|
|
$(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.aux, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.tex, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.log, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.out, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.ps, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.html, $(DOCBOOKS)) \
|
|
$(patsubst %.xml, %.9, $(DOCBOOKS)) \
|
|
$(C-procfs-example)
|
|
|
|
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS))
|
|
|
|
#man put files in man subdir - traverse down
|
|
subdir- := man/
|