Skip to contentSkip to conversation

Adjust and fix kernel-doc

PATCH New Masahiro Yamada 2 participants 7 messages Feb 5, 2014 – Feb 19, 2014 Kbuild

lore
Share & tools
lore
#0 lore raw

v2 cover Adjust and fix kernel-doc

"make %docs" have not worked for a while.

This problem was reported by Abraham Varricatt.
"make htmldocs" gives error:
http://u-boot.10912.n7.nabble.com/quot-make-htmldocs-quot-gives-error-td168840.html

This series adjusts kernel doc stuff to the current build system and fixes errors.

By applying this series, "make pdfdocs", "make htmldocs", etc. will work.

This series uses my Kbuild series as a prerequisite. "Switch over to real Kbuild" series must be applied beforehand.

Changes in v2:
- fix typos in commit log
- update also .gitignore

Masahiro Yamada (3):
kernel-doc: move kernel-doc tools to scripts/
kernel-doc: update kernel-doc related files to Linux v3.13
kernel-doc: fix some errors

 Makefile                                 | 10 +++--
 doc/DocBook/.gitignore                   |  1 -
 doc/DocBook/Makefile                     | 17 +++-----
 doc/DocBook/stylesheet.xsl               |  1 -
 include/linker_lists.h                   |  6 +--
 scripts/.gitignore                       |  4 ++
 scripts/Makefile                         | 14 ++++++
 {tools/kernel-doc => scripts}/docproc.c  | 74 +++++++++++++++++---------------
 {tools/kernel-doc => scripts}/kernel-doc | 74 +++++++++++++++++++++++++++-----
 tools/.gitignore                         |  1 -
 tools/Makefile                           |  2 -
 tools/kernel-doc/Makefile                | 10 -----
 12 files changed, 137 insertions(+), 77 deletions(-)
 create mode 100644 scripts/.gitignore
 rename {tools/kernel-doc => scripts}/docproc.c (90%)
 rename {tools/kernel-doc => scripts}/kernel-doc (97%)
 delete mode 100644 tools/kernel-doc/Makefile
Signature · 1 line
1.8.3.2
#1 lore raw

PATCH v2 1/3 kernel-doc: move kernel-doc tools to scripts/

tools/kernel-doc/docproc.c and tools/kernel-doc/kernel-doc are files imported from Linux Kernel.

They originally resided under scripts/ directory in Linux Kernel.

This commit moves them to the original location.

---

Changes in v2:
- fix typos in commit log

 Makefile                                 | 10 +++++++---
 doc/DocBook/Makefile                     | 15 ++++++---------
 scripts/.gitignore                       |  4 ++++
 scripts/Makefile                         | 14 ++++++++++++++
 {tools/kernel-doc => scripts}/docproc.c  |  2 +-
 {tools/kernel-doc => scripts}/kernel-doc |  0
 tools/.gitignore                         |  1 -
 tools/Makefile                           |  2 --
 tools/kernel-doc/Makefile                | 10 ----------
 9 files changed, 32 insertions(+), 26 deletions(-)
 create mode 100644 scripts/.gitignore
 rename {tools/kernel-doc => scripts}/docproc.c (99%)
 rename {tools/kernel-doc => scripts}/kernel-doc (100%)
 delete mode 100644 tools/kernel-doc/Makefile
Makefile +7 -3
index 817f2a9..cb9c243 100644
@@ -1151,9 +1151,6 @@ $(TIMESTAMP_FILE):
 env: depend scripts_basic
 	$(Q)$(MAKE) $(build)=tools/$@
 
-xmldocs pdfdocs psdocs htmldocs mandocs: tools/kernel-doc/docproc
-	$(Q)$(MAKE) U_BOOT_VERSION=$(U_BOOT_VERSION) $(build)=doc/DocBook $@
-
 tools-all: HOST_TOOLS_ALL=y
 tools-all: env tools ;
 
@@ -1261,6 +1258,13 @@ backup:
 	F=`basename $(TOPDIR)` ; cd .. ; \
 	gtar --force-local -zcvf `LC_ALL=C date "+$$F-%Y-%m-%d-%T.tar.gz"` $$F
 
+
+# Documentation targets
+# ---------------------------------------------------------------------------
+%docs: scripts_basic FORCE
+	$(Q)$(MAKE) $(build)=scripts build_docproc
+	$(Q)$(MAKE) $(build)=doc/DocBook $@
+
 # Dummies...
 PHONY += prepare scripts
 prepare: ;
doc/DocBook/Makefile +6 -9
index 75e59c2..3077134 100644
@@ -1,7 +1,7 @@
 ###
 # 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
+# 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.
@@ -51,8 +51,8 @@ installmandocs: mandocs
 
 ###
 #External programs used
-KERNELDOC = $(srctree)/tools/kernel-doc/kernel-doc
-DOCPROC   = $(objtree)/tools/kernel-doc/docproc
+KERNELDOC = $(srctree)/scripts/kernel-doc
+DOCPROC   = $(objtree)/scripts/docproc
 
 XMLTOFLAGS = -m $(srctree)/doc/DocBook/stylesheet.xsl
 XMLTOFLAGS += --skip-validation
@@ -134,11 +134,8 @@ build_main_index = rm -rf $(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,%,$@) $< && \
+      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
 		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
         $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
 
@@ -225,8 +222,8 @@ clean-files := $(DOCBOOKS) \
 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
 
 cleandocs:
-	@$(Q)rm -f $(call objectify, $(clean-files))
-	@$(Q)rm -rf $(call objectify, $(clean-dirs))
+	$(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.
scripts/.gitignore new file +4 -0
new file mode 100644
index 0000000..82bc06e
@@ -0,0 +1,4 @@
+#
+# Generated files
+#
+docproc
scripts/Makefile +14 -0
index ebbadc9..242e3a0 100644
@@ -1,2 +1,16 @@
+###
+# scripts contains sources for various helper programs used throughout
+# the kernel for the build process.
+# ---------------------------------------------------------------------------
+# docproc:       Used in Documentation/DocBook
+
+# The following hostprogs-y programs are only build on demand
+hostprogs-y += docproc
+
+# These targets are used internally to avoid "is up to date" messages
+PHONY += build_docproc
+build_docproc: scripts/docproc
+	@:
+
 # Let clean descend into subdirs
 subdir-	+= basic
scripts/docproc.c renamed from tools/kernel-doc/docproc.c +1 -1
similarity index 99%
rename from tools/kernel-doc/docproc.c
rename to scripts/docproc.c
index a9b49c5..23c3a43 100644
@@ -65,7 +65,7 @@ FILELINE * docsection;
 
 #define MAXLINESZ     2048
 #define MAXFILES      250
-#define KERNELDOCPATH "tools/kernel-doc/"
+#define KERNELDOCPATH "scripts/"
 #define KERNELDOC     "kernel-doc"
 #define DOCBOOK       "-docbook"
 #define LIST          "-list"
scripts/kernel-doc renamed from tools/kernel-doc/kernel-doc +0 -0
similarity index 100%
rename from tools/kernel-doc/kernel-doc
rename to scripts/kernel-doc
tools/.gitignore +0 -1
index 6e4a287..2a90dfe 100644
@@ -18,4 +18,3 @@
 /easylogo/easylogo
 /gdb/gdbcont
 /gdb/gdbsend
-/kernel-doc/docproc
tools/Makefile +0 -2
index 783e643..dcd49f8 100644
@@ -183,8 +183,6 @@ HOST_EXTRACFLAGS += -include $(SRCTREE)/include/libfdt_env.h \
 
 __build:	$(LOGO-y)
 
-subdir-y += kernel-doc
-
 $(LOGO_H):	$(obj)/bmp_logo $(LOGO_BMP)
 	$(obj)/bmp_logo --gen-info $(LOGO_BMP) > $@
 
tools/kernel-doc/Makefile deleted +0 -10
deleted file mode 100644
index f15a4b7..0000000
@@ -1,10 +0,0 @@
-#
-# Copyright (C) 2012 Marek Vasut <[email protected]>
-#
-# SPDX-License-Identifier:	GPL-2.0+
-#
-
-hostprogs-y := docproc
-always := $(hostprogs-y)
-
-HOST_EXTRACFLAGS := -pedantic
Signature · 1 line
1.8.3.2
#2 lore raw

PATCH v2 1/3 kernel-doc: move kernel-doc tools to scripts/

Quoted 9 lines · Masahiro Yamada

tools/kernel-doc/docproc.c and tools/kernel-doc/kernel-doc are files imported from Linux Kernel.

They originally resided under scripts/ directory in Linux Kernel.

This commit moves them to the original location.

Applied to u-boot/master, thanks!

Signature · 8 lines
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20140219/b06459c9/attachment.pgp>
#3 lore raw

PATCH v2 2/3 kernel-doc: update kernel-doc related files to Linux v3.13

In reply to Masahiro Yamada

---

Changes in v2:
- update also .gitignore

 doc/DocBook/.gitignore     |  1 -
 doc/DocBook/stylesheet.xsl |  1 -
 scripts/docproc.c          | 72 +++++++++++++++++++++++---------------------
 scripts/kernel-doc         | 74 +++++++++++++++++++++++++++++++++++++++-------
 4 files changed, 101 insertions(+), 47 deletions(-)
doc/DocBook/.gitignore +0 -1
index 90c1b11..720f245 100644
@@ -1,4 +1,3 @@
-*/
 *.xml
 *.ps
 *.pdf
doc/DocBook/stylesheet.xsl +0 -1
index 8adce56..85b2527 100644
@@ -7,5 +7,4 @@
 <!-- <param name="paper.type">A4</param> -->
 <param name="generate.section.toc.level">2</param>
 <param name="use.id.as.filename">1</param>
-<param name="html.stylesheet">../docbook.css</param>
 </stylesheet>
scripts/docproc.c +38 -34

127 lines not on this page · raw message

scripts/kernel-doc +63 -11

209 lines not on this page · raw message

Signature · 1 line
1.8.3.2
#4 lore raw

PATCH v2 2/3 kernel-doc: update kernel-doc related files to Linux v3.13

Quoted 2 lines · Masahiro Yamada

Applied to u-boot/master, thanks!

Signature · 8 lines
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20140219/63d0c0e6/attachment.pgp>
#5 lore raw

PATCH v2 3/3 kernel-doc: fix some errors

In reply to Masahiro Yamada

- Delete fs.xml from DOCBOOKS to fix an error. Commit e3ff797c added fs.xml to DOCBOOKS
but missed to add doc/DocBook/fs.tmpl.
- Fix the location of include guard in include/linker_lists.h.

---

This problem was reported by Abraham Varricatt:
http://u-boot.10912.n7.nabble.com/quot-make-htmldocs-quot-gives-error-td168840.html

Changes in v2: None

 doc/DocBook/Makefile   | 2 +-
 include/linker_lists.h | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)
doc/DocBook/Makefile +1 -1
index 3077134..44afc47 100644
@@ -6,7 +6,7 @@
 # To add a new book the only step required is to add the book to the
 # list of DOCBOOKS.
 
-DOCBOOKS := fs.xml linker_lists.xml stdio.xml
+DOCBOOKS := linker_lists.xml stdio.xml
 
 ###
 # The build process is as follows (targets):
include/linker_lists.h +3 -3
index 1eebb95..997d149 100644
@@ -8,6 +8,9 @@
  * SPDX-License-Identifier:	GPL-2.0+
  */
 
+#ifndef __LINKER_LISTS_H__
+#define __LINKER_LISTS_H__
+
 /*
  * There is no use in including this from ASM files, but that happens
  * anyway, e.g. PPC kgdb.S includes command.h which incluse us.
@@ -97,9 +100,6 @@
  *   %u_boot_list_2_drivers_3
  */
 
-#ifndef __LINKER_LISTS_H__
-#define __LINKER_LISTS_H__
-
 /**
  * ll_entry_declare() - Declare linker-generated array entry
  * @_type:	Data type of the entry
Signature · 1 line
1.8.3.2
#6 lore raw

PATCH v2 3/3 kernel-doc: fix some errors

Quoted 8 lines · Masahiro Yamada

- Delete fs.xml from DOCBOOKS to fix an error.
Commit e3ff797c added fs.xml to DOCBOOKS
but missed to add doc/DocBook/fs.tmpl.
- Fix the location of include guard in include/linker_lists.h.

Applied to u-boot/master, thanks!

Signature · 8 lines
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20140219/9eb8f9cc/attachment.pgp>