kerneldoc: Implant DocBook from Linux kernel
Pull slightly modified version of Documentation/DocBook, the related perl
script scripts/kernel-doc and the scripts/docproc.c from Linux kernel and
implant it into U-Boot. This will allow smooth generation of kerneldoc
style documentation.
It was necessary to modify the DocBook/Makefile to work with U-Boot build
system. The changes were only minor though and involved replacing the kbuild
specific parts.
It was also necessary to replace use of variables like KERNEL_VERSION with
U_BOOT_VERSION, strings like Linux kernel with U-Boot Bootloader etc. so
the generated result actually matches.
Finally, it was necessary to adjust docproc.c, since the documentation in
U-Boot is located in doc/DocBook instead of Documentation/DocBook as is in
case of the Linux kernel.
Some parts of the DocBook Makefile are unused, but to allow easier sync with
Linux kernel, these parts are still left in. The targets enabled now are
"htmldocs" "pdfdocs" "psdocs" "xmldocs" and "cleandocs" to remove the results
of documentation build.
Linux scripts/docproc.c:
commit f0f3ca8d967462dafb815412b14ca3339b9817a6
Date: Wed Jun 15 11:53:13 2011 +0200
Linux scripts/kernel-doc:
commit 1b40c1944db445c1de1c47ffd8cd426167f488e8
Date: Sun Aug 12 10:46:15 2012 +0200
Linux Documentation/DocBook:
commit bb8187d35f820671d6dd76700d77a6b55f95e2c5
Date: Thu May 17 19:06:13 2012 -0400
Signed-off-by: Marek Vasut <marex@denx.de>
diff --git a/doc/DocBook/.gitignore b/doc/DocBook/.gitignore
new file mode 100644
index 0000000..90c1b11
--- /dev/null
+++ b/doc/DocBook/.gitignore
@@ -0,0 +1,15 @@
+*/
+*.xml
+*.ps
+*.pdf
+*.html
+*.9.gz
+*.9
+*.aux
+*.dvi
+*.log
+*.out
+*.png
+*.gif
+media-indices.tmpl
+media-entities.tmpl
diff --git a/doc/DocBook/Makefile b/doc/DocBook/Makefile
new file mode 100644
index 0000000..2f2ddfc
--- /dev/null
+++ b/doc/DocBook/Makefile
@@ -0,0 +1,229 @@
+###
+# This makefile is used to generate the kernel documentation,
+# primarily based on in-line comments in various source files.
+# See doc/kernel-doc-nano-HOWTO.txt for instruction in how
+# to document 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.
+
+include $(TOPDIR)/config.mk
+
+DOCBOOKS :=
+
+###
+# The build process is as follows (targets):
+# (xmldocs) [by docproc]
+# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
+# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
+# +--> DIR=file (htmldocs) [by xmlto]
+# +--> man/ (mandocs) [by xmlto]
+
+
+# for PDF and PS output you can choose between xmlto and docbook-utils tools
+PDF_METHOD = $(prefer-db2x)
+PS_METHOD = $(prefer-db2x)
+
+
+###
+# The targets that may be used.
+PHONY += $(obj).depend xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
+
+BOOKS := $(addprefix $(OBJTREE)/doc/DocBook/,$(DOCBOOKS))
+xmldocs: $(BOOKS)
+sgmldocs: xmldocs
+
+PS := $(patsubst %.xml, %.ps, $(BOOKS))
+psdocs: $(PS)
+
+PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
+pdfdocs: $(PDF)
+
+HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
+htmldocs: $(HTML)
+ $(call build_main_index)
+ $(call build_images)
+ $(call install_media_images)
+
+MAN := $(patsubst %.xml, %.9, $(BOOKS))
+mandocs: $(MAN)
+
+installmandocs: mandocs
+ mkdir -p /usr/local/man/man9/
+ install doc/DocBook/man/*.9.gz /usr/local/man/man9/
+
+###
+#External programs used
+KERNELDOC = $(SRCTREE)/tools/kernel-doc/kernel-doc
+DOCPROC = $(OBJTREE)/tools/kernel-doc/docproc
+
+XMLTOFLAGS = -m $(SRCTREE)/doc/DocBook/stylesheet.xsl
+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).
+%.xml: %.tmpl
+ $(DOCPROC) doc $< >$@
+
+ifeq ($@, "cleandocs")
+sinclude $(obj).depend
+$(obj).depend: $(patsubst %.xml, %.tmpl, $(DOCBOOKS))
+ rm -f $(obj).depend ; \
+ touch $(obj).depend ; \
+ for file in $^ ; do \
+ xmlfile=`echo "$${file}" | \
+ sed "s/tmpl$$/xml/"` ; \
+ echo -n "$${xmlfile}: ">> $(obj).depend ; \
+ $(DOCPROC) depend $$file >> $(obj).depend ; \
+ echo -e "\n\t$(DOCPROC) doc $< >$${xmlfile} " >> \
+ $(obj).depend ; \
+ done
+endif
+
+###
+# Changes in kernel-doc force a rebuild of all documentation
+$(BOOKS): $(KERNELDOC)
+
+notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
+ exit 1
+db2xtemplate = db2TYPE -o $(dir $@) $<
+xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
+
+# determine which methods are available
+ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
+ use-db2x = db2x
+ prefer-db2x = db2x
+else
+ use-db2x = notfound
+ prefer-db2x = $(use-xmlto)
+endif
+ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
+ use-xmlto = xmlto
+ prefer-xmlto = xmlto
+else
+ use-xmlto = notfound
+ prefer-xmlto = $(use-db2x)
+endif
+
+# the commands, generated from the chosen template
+quiet_cmd_db2ps = PS $@
+ cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
+%.ps : %.xml
+ $(call cmd_db2ps)
+
+quiet_cmd_db2pdf = PDF $@
+ cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
+%.pdf : %.xml
+ $(call cmd_db2pdf)
+
+
+index = index.html
+main_idx = $(index)
+build_main_index = rm -rf $(main_idx); \
+ echo '<h1>U-Boot Bootloader HTML Documentation</h1>' >> $(main_idx) && \
+ echo '<h2>U-Boot Version: $(U_BOOT_VERSION)</h2>' >> $(main_idx) && \
+ cat $(HTML) >> $(main_idx)
+
+# To work around bug [1] in docbook-xsl-stylesheets 1.76.1 , generate only html
+# docs instead of xhtml with xmlto.
+# [1] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=654338
+quiet_cmd_db2html = HTML $@
+ cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
+ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
+ $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
+
+%.html: %.xml
+ @(which xmlto > /dev/null 2>&1) || \
+ (echo "*** You need to install xmlto ***"; \
+ 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 = MAN $@
+ 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 xmlto ***"; \
+ exit 1)
+ $(Q)mkdir -p $(obj)man
+ $(call cmd_db2man)
+ @touch $@
+
+###
+# Rules to generate postscripts and PNG images 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
+ gen_xml = :
+ quiet_gen_xml = echo ' GEN $@'
+silent_gen_xml = :
+%.xml: %.c
+ @$($(quiet)gen_xml)
+ @( \
+ 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 ' U-Boot bootloader internal documentation in different formats:'
+ @echo ' htmldocs - HTML'
+ @echo ' pdfdocs - PDF'
+ @echo ' psdocs - Postscript'
+ @echo ' xmldocs - XML DocBook'
+ @echo ' mandocs - man pages'
+ @echo ' installmandocs - install man pages generated by mandocs'
+ @echo ' cleandocs - clean all generated DocBook files'
+
+###
+# 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)) \
+ $(index)
+
+clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
+
+cleandocs:
+ @rm -f $(obj).depend
+ @$(Q)rm -f $(call objectify, $(clean-files))
+ @$(Q)rm -rf $(call objectify, $(clean-dirs))
+
+# Declare the contents of the .PHONY variable as phony. We keep that
+# information in a variable se we can use it in if_changed and friends.
+
+.PHONY: $(PHONY)
diff --git a/doc/DocBook/stylesheet.xsl b/doc/DocBook/stylesheet.xsl
new file mode 100644
index 0000000..85b2527
--- /dev/null
+++ b/doc/DocBook/stylesheet.xsl
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<param name="chunk.quietly">1</param>
+<param name="funcsynopsis.style">ansi</param>
+<param name="funcsynopsis.tabular.threshold">80</param>
+<param name="callout.graphics">0</param>
+<!-- <param name="paper.type">A4</param> -->
+<param name="generate.section.toc.level">2</param>
+<param name="use.id.as.filename">1</param>
+</stylesheet>