From 78a88f7930becb78afef09c1237a8e4edc1b01e1 Mon Sep 17 00:00:00 2001 From: Mario Six Date: Tue, 10 Jul 2018 08:40:17 +0200 Subject: doc: Replace DocBook with sphinx-based docs The Linux kernel moved to sphinx-based documentation and got rid of the DocBook based documentation quite a while ago. Hence, the DocBook documentation for U-Boot should be converted as well. To achieve this, import the necessary files from Linux v4.17, and convert the current DocBook documentation (three files altogether) to sphinx/reStructuredText. For now, all old DocBook documentation was merged into a single handbook, tentatively named "U-Boot Hacker Manual". For some source files, the documentation style was changed to comply with kernel-doc; no functional changes were applied. Signed-off-by: Mario Six --- doc/DocBook/.gitignore | 15 --- doc/DocBook/Makefile | 222 ------------------------------------------ doc/DocBook/docbook.css | 16 --- doc/DocBook/efi.tmpl | 17 ---- doc/DocBook/linker_lists.tmpl | 46 --------- doc/DocBook/stdio.tmpl | 46 --------- doc/DocBook/stylesheet.xsl | 10 -- 7 files changed, 372 deletions(-) delete mode 100644 doc/DocBook/.gitignore delete mode 100644 doc/DocBook/Makefile delete mode 100644 doc/DocBook/docbook.css delete mode 100644 doc/DocBook/efi.tmpl delete mode 100644 doc/DocBook/linker_lists.tmpl delete mode 100644 doc/DocBook/stdio.tmpl delete mode 100644 doc/DocBook/stylesheet.xsl (limited to 'doc') diff --git a/doc/DocBook/.gitignore b/doc/DocBook/.gitignore deleted file mode 100644 index 7ebd5465d92..00000000000 --- a/doc/DocBook/.gitignore +++ /dev/null @@ -1,15 +0,0 @@ -*.xml -*.ps -*.pdf -*.html -*.9.gz -*.9 -*.aux -*.dvi -*.log -*.out -*.png -*.gif -*.svg -media-indices.tmpl -media-entities.tmpl diff --git a/doc/DocBook/Makefile b/doc/DocBook/Makefile deleted file mode 100644 index 52576135138..00000000000 --- a/doc/DocBook/Makefile +++ /dev/null @@ -1,222 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 -### -# 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 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. - -DOCBOOKS := efi.xml linker_lists.xml stdio.xml - -### -# 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 += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs - -targets += $(DOCBOOKS) -BOOKS := $(addprefix $(obj)/,$(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) - $(if $(wildcard $(obj)/man/*.9),gzip -f $(obj)/man/*.9) - -installmandocs: mandocs - mkdir -p /usr/local/man/man9/ - install $(obj)/man/*.9.gz /usr/local/man/man9/ - -### -#External programs used -KERNELDOC = $(srctree)/scripts/kernel-doc -DOCPROC = $(objtree)/scripts/docproc - -XMLTOFLAGS = -m $(srctree)/$(src)/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). -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 $(KERNELDOC) $(DOCPROC) FORCE - $(call if_changed_rule,docproc) - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -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 = $(obj)/$(index) -build_main_index = rm -rf $(main_idx); \ - echo '

U-Boot Bootloader HTML Documentation

' >> $(main_idx) && \ - echo '

U-Boot Version: $(UBOOTVERSION)

' >> $(main_idx) && \ - cat $(HTML) >> $(main_idx) - -quiet_cmd_db2html = HTML $@ - cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ - echo ' \ - $(patsubst %.html,%,$(notdir $@))

' > $@ - -%.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 $< ; 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 ""; \ - expand --tabs=8 < $< | \ - sed -e "s/&/\\&/g" \ - -e "s//\\>/g"; \ - echo "") > $@ - -### -# 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: - $(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/docbook.css b/doc/DocBook/docbook.css deleted file mode 100644 index 7a79ec54bd2..00000000000 --- a/doc/DocBook/docbook.css +++ /dev/null @@ -1,16 +0,0 @@ -body { - font-family: sans-serif; -} - -.programlisting { - font-family: monospace; - font-size: 1em; - display: block; - padding: 10px; - border: 1px solid #aaa; - color: #000; - background-color: #eee; - overflow: auto; - margin: 1em 0em; - border-radius: 6px; -} diff --git a/doc/DocBook/efi.tmpl b/doc/DocBook/efi.tmpl deleted file mode 100644 index 5daaae382b5..00000000000 --- a/doc/DocBook/efi.tmpl +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - The U-Boot EFI subsystem - - - - - - Boot services -!Ilib/efi_loader/efi_boottime.c - - - diff --git a/doc/DocBook/linker_lists.tmpl b/doc/DocBook/linker_lists.tmpl deleted file mode 100644 index f1975165d62..00000000000 --- a/doc/DocBook/linker_lists.tmpl +++ /dev/null @@ -1,46 +0,0 @@ - - - - - - The U-Boot Linker-Generated Arrays - - - - This documentation 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 - - - - For more details see the file COPYING in the source - distribution of U-Boot Bootloader. - - - - - - - - Linker-Generated Arrays -!Iinclude/linker_lists.h - - - diff --git a/doc/DocBook/stdio.tmpl b/doc/DocBook/stdio.tmpl deleted file mode 100644 index 4783abb0a07..00000000000 --- a/doc/DocBook/stdio.tmpl +++ /dev/null @@ -1,46 +0,0 @@ - - - - - - The U-Boot STDIO subsystem - - - - This documentation 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 - - - - For more details see the file COPYING in the source - distribution of U-Boot Bootloader. - - - - - - - - U-Boot Serial subsystem -!Idrivers/serial/serial.c - - - diff --git a/doc/DocBook/stylesheet.xsl b/doc/DocBook/stylesheet.xsl deleted file mode 100644 index 85b25275196..00000000000 --- a/doc/DocBook/stylesheet.xsl +++ /dev/null @@ -1,10 +0,0 @@ - - -1 -ansi -80 -0 - -2 -1 - -- cgit v1.2.3