Commit 30ff8918 authored by Marek Vasut's avatar Marek Vasut Committed by Tom Rini

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's avatarMarek Vasut <marex@denx.de>
parent c50204a5
......@@ -715,6 +715,9 @@ easylogo env gdb:
$(MAKE) -C tools/$@ all MTD_VERSION=${MTD_VERSION}
gdbtools: gdb
xmldocs pdfdocs psdocs htmldocs mandocs: tools/kernel-doc/docproc
$(MAKE) U_BOOT_VERSION=$(U_BOOT_VERSION) -C doc/DocBook/ $@
tools-all: easylogo env gdb $(VERSION_FILE) $(TIMESTAMP_FILE)
$(MAKE) -C tools HOST_TOOLS_ALL=y
......@@ -799,7 +802,8 @@ clean:
$(obj)tools/mk{env,}image $(obj)tools/mpc86x_clk \
$(obj)tools/mk{smdk5250,}spl \
$(obj)tools/mxsboot \
$(obj)tools/ncb $(obj)tools/ubsha1
$(obj)tools/ncb $(obj)tools/ubsha1 \
$(obj)tools/kernel-doc/docproc
@rm -f $(obj)board/cray/L1/{bootscript.c,bootscript.image} \
$(obj)board/matrix_vision/*/bootscript.img \
$(obj)board/voiceblue/eeprom \
......@@ -812,6 +816,7 @@ clean:
@rm -f $(obj)include/generated/asm-offsets.h
@rm -f $(obj)$(CPUDIR)/$(SOC)/asm-offsets.s
@rm -f $(TIMESTAMP_FILE) $(VERSION_FILE)
@$(MAKE) -C doc/DocBook/ cleandocs
@find $(OBJTREE) -type f \
\( -name 'core' -o -name '*.bak' -o -name '*~' -o -name '*.su' \
-o -name '*.o' -o -name '*.a' -o -name '*.exe' \) -print \
......
*/
*.xml
*.ps
*.pdf
*.html
*.9.gz
*.9
*.aux
*.dvi
*.log
*.out
*.png
*.gif
media-indices.tmpl
media-entities.tmpl
###
# 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/&/\\&amp;/g" \
-e "s/</\\&lt;/g" \
-e "s/>/\\&gt;/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)
<?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>
......@@ -17,3 +17,4 @@
/env/fw_printenv
/gdb/gdbcont
/gdb/gdbsend
/kernel-doc/docproc
......@@ -21,7 +21,7 @@
# MA 02111-1307 USA
#
TOOLSUBDIRS =
TOOLSUBDIRS = kernel-doc
#
# Include this after HOSTOS HOSTARCH check
......
#
# Copyright (C) 2012 Marek Vasut <marex@denx.de>
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; either version 2 of
# the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston,
# MA 02111-1307 USA
#
include $(TOPDIR)/config.mk
all: $(obj)docproc
$(obj)docproc: docproc.c
$(HOSTCC) $(HOSTCFLAGS) $(HOSTLDFLAGS) -o $@ $^
$(HOSTSTRIP) $@
clean:
rm -rf docproc
#########################################################################
# defines $(obj).depend target
include $(SRCTREE)/rules.mk
sinclude $(obj).depend
#########################################################################
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment