Skip to contentSkip to conversation

Get rid of DocBook

PATCH Superseded Mauro Carvalho Chehab 4 participants 22 messages May 14, 2017 – May 16, 2017

Subsystems (19)
DRM drivers Documentation SCSI USB +15 more subsystems

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover Get rid of DocBook

As just one book (lsm) was missing conversion, let's convert it and store as if it were a plain text file under Documentation/lsm.txt, adding a notice that it requires update.

This way, as everything is now converted, we can get rid of the DocBook building system and update places that were mentioning it.

PS.: We could also remove the parts of the kernel-doc script that produce DocBook outputs, but, as this might still be useful for someone, for now let's just keep the functionality there.

-

This patch series is based on my past 00/05 and 00/36 patch series that convert the other DocBooks to ReST, applied on the top of docs tree (next branch).

The full patch series is on this tree is at:

https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook2

And the HTML output at:

http://www.infradead.org/~mchehab/kernel_docs/
https://mchehab.fedorapeople.org/kernel_docs/

Mauro Carvalho Chehab (13):
docs-rst: convert lsm from DocBook to ReST
docs: remove DocBook from the building system
docs: update old references for DocBook from the documentation
MAINTAINERS: update old references for DocBook directory
ata: update references for libata documentation ia64, scsi: update references for the device-io book
irq: update genericirq book location
fs: update location of filesystems documentation
lib: update location of kgdb documentation
sound: fix the comments that refers to kernel-doc
fs: fix the location of the kernel-api book
usb: fix the comment with regards to DocBook
docs-rst: get rid of Documentation/sphinx/tmplcvt script

 Documentation/00-INDEX                     |   6 +-
 Documentation/DocBook/.gitignore           |  17 --
 Documentation/DocBook/Makefile             | 276 -----------------------------
 Documentation/DocBook/lsm.tmpl             | 265 ---------------------------
 Documentation/DocBook/stylesheet.xsl       |  11 --
 Documentation/Makefile                     | 125 +++++++++++++
 Documentation/Makefile.sphinx              | 130 --------------
 Documentation/PCI/MSI-HOWTO.txt            |   2 +-
 Documentation/admin-guide/README.rst       |   6 -
 Documentation/doc-guide/docbook.rst        |  90 ----------
 Documentation/doc-guide/index.rst          |   1 -
 Documentation/doc-guide/sphinx.rst         |   5 -
 Documentation/fb/api.txt                   |   4 +-
 Documentation/gpu/todo.rst                 |   2 +-
 Documentation/kernel-doc-nano-HOWTO.txt    |  65 ++-----
 Documentation/lsm.txt                      | 201 +++++++++++++++++++++
 Documentation/process/changes.rst          |  26 +--
 Documentation/process/howto.rst            |   8 -
 Documentation/process/kernel-docs.rst      |  34 +---
 Documentation/sphinx/tmplcvt               |  28 ---
 Documentation/translations/ja_JP/howto.rst |   7 -
 Documentation/translations/ko_KR/howto.rst |   7 -
 MAINTAINERS                                |   5 +-
 Makefile                                   |  11 +-
 arch/ia64/include/asm/io.h                 |   2 +-
 arch/ia64/sn/kernel/iomv.c                 |   2 +-
 drivers/ata/acard-ahci.c                   |   2 +-
 drivers/ata/ahci.c                         |   2 +-
 drivers/ata/ahci.h                         |   2 +-
 drivers/ata/ata_piix.c                     |   2 +-
 drivers/ata/libahci.c                      |   2 +-
 drivers/ata/libata-core.c                  |   2 +-
 drivers/ata/libata-eh.c                    |   2 +-
 drivers/ata/libata-scsi.c                  |   2 +-
 drivers/ata/libata-sff.c                   |   2 +-
 drivers/ata/libata.h                       |   2 +-
 drivers/ata/pata_pdc2027x.c                |   2 +-
 drivers/ata/pdc_adma.c                     |   2 +-
 drivers/ata/sata_nv.c                      |   2 +-
 drivers/ata/sata_promise.c                 |   2 +-
 drivers/ata/sata_promise.h                 |   2 +-
 drivers/ata/sata_qstor.c                   |   2 +-
 drivers/ata/sata_sil.c                     |   2 +-
 drivers/ata/sata_sis.c                     |   2 +-
 drivers/ata/sata_svw.c                     |   2 +-
 drivers/ata/sata_sx4.c                     |   2 +-
 drivers/ata/sata_uli.c                     |   2 +-
 drivers/ata/sata_via.c                     |   2 +-
 drivers/ata/sata_vsc.c                     |   2 +-
 drivers/scsi/qla1280.c                     |   2 +-
 drivers/usb/gadget/Kconfig                 |   2 +-
 fs/debugfs/file.c                          |   2 +-
 fs/debugfs/inode.c                         |   2 +-
 include/linux/ata.h                        |   2 +-
 include/linux/debugfs.h                    |   2 +-
 include/linux/libata.h                     |   2 +-
 include/sound/pcm.h                        |   2 +-
 kernel/irq/chip.c                          |   2 +-
 kernel/irq/handle.c                        |   2 +-
 kernel/irq/irqdesc.c                       |   2 +-
 lib/Kconfig.debug                          |   2 +-
 lib/Kconfig.kgdb                           |   2 +-
 scripts/Makefile                           |   9 +-
 scripts/check-lc_ctype.c                   |  11 --
 64 files changed, 396 insertions(+), 1032 deletions(-)
 delete mode 100644 Documentation/DocBook/.gitignore
 delete mode 100644 Documentation/DocBook/Makefile
 delete mode 100644 Documentation/DocBook/lsm.tmpl
 delete mode 100644 Documentation/DocBook/stylesheet.xsl
 delete mode 100644 Documentation/Makefile.sphinx
 delete mode 100644 Documentation/doc-guide/docbook.rst
 create mode 100644 Documentation/lsm.txt
 delete mode 100755 Documentation/sphinx/tmplcvt
 delete mode 100644 scripts/check-lc_ctype.c
Signature · 7 lines
2.9.3


_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#1 lore raw

PATCH 1/13 docs-rst: convert lsm from DocBook to ReST

This file is outdated. Still, as it is the only one left at DocBook dir, convert it, and store it, with a .txt extension, under Documentation/lsm.txt.

This way, we can get rid of DocBook from the building system, without needing to wait for someone to take care of it.

---
 Documentation/00-INDEX         |   2 +
 Documentation/DocBook/Makefile | 275 -----------------------------------------
 Documentation/DocBook/lsm.tmpl | 265 ---------------------------------------
 Documentation/lsm.txt          | 201 ++++++++++++++++++++++++++++++
 4 files changed, 203 insertions(+), 540 deletions(-)
 delete mode 100644 Documentation/DocBook/lsm.tmpl
 create mode 100644 Documentation/lsm.txt
Documentation/00-INDEX +2 -0
index 793acf999e9e..8c2a66e176b9 100644
@@ -264,6 +264,8 @@ logo.gif
 	- full colour GIF image of Linux logo (penguin - Tux).
 logo.txt
 	- info on creator of above logo & site to get additional images from.
+lsm.txt
+	- Linux Security Modules: General Security Hooks for Linux
 lzo.txt
 	- kernel LZO decompressor input formats
 m68k/
Documentation/DocBook/Makefile +0 -275

276 lines not on this page · raw message

Documentation/DocBook/lsm.tmpl deleted +0 -265

265 lines not on this page · raw message

Documentation/lsm.txt new file +201 -0

201 lines not on this page · raw message

Signature · 1 line
2.9.3
#2 lore raw

PATCH 2/13 docs: remove DocBook from the building system

In reply to Mauro Carvalho Chehab

Now that we don't have any DocBook anymore, remove it from the building system.

---
 Documentation/00-INDEX               |   4 --
 Documentation/DocBook/.gitignore     |  17 -----
 Documentation/DocBook/Makefile       |   1 -
 Documentation/DocBook/stylesheet.xsl |  11 ---
 Documentation/Makefile               | 125 +++++++++++++++++++++++++++++++++
 Documentation/Makefile.sphinx        | 130 -----------------------------------
 Documentation/doc-guide/docbook.rst  |  90 ------------------------
 Makefile                             |  11 ++-
 scripts/Makefile                     |   9 +--
 scripts/check-lc_ctype.c             |  11 ---
 10 files changed, 132 insertions(+), 277 deletions(-)
 delete mode 100644 Documentation/DocBook/.gitignore
 delete mode 100644 Documentation/DocBook/Makefile
 delete mode 100644 Documentation/DocBook/stylesheet.xsl
 delete mode 100644 Documentation/Makefile.sphinx
 delete mode 100644 Documentation/doc-guide/docbook.rst
 delete mode 100644 scripts/check-lc_ctype.c
Documentation/00-INDEX +0 -4
index 8c2a66e176b9..d0165461b024 100644
@@ -24,8 +24,6 @@ DMA-ISA-LPC.txt
 	- How to do DMA with ISA (and LPC) devices.
 DMA-attributes.txt
 	- listing of the various possible attributes a DMA region can have
-DocBook/
-	- directory with DocBook templates etc. for kernel documentation.
 EDID/
 	- directory with info on customizing EDID for broken gfx/displays.
 IPMI.txt
@@ -40,8 +38,6 @@ Intel-IOMMU.txt
 	- basic info on the Intel IOMMU virtualization support.
 Makefile
 	- It's not of interest for those who aren't touching the build system.
-Makefile.sphinx
-	- It's not of interest for those who aren't touching the build system.
 PCI/
 	- info related to PCI drivers.
 RCU/
Documentation/DocBook/.gitignore deleted +0 -17
deleted file mode 100644
index e05da3f7aa21..000000000000
@@ -1,17 +0,0 @@
-*.xml
-*.ps
-*.pdf
-*.html
-*.9.gz
-*.9
-*.aux
-*.dvi
-*.log
-*.out
-*.png
-*.gif
-*.svg
-*.proc
-*.db
-media-indices.tmpl
-media-entities.tmpl
Documentation/DocBook/Makefile deleted +0 -1
deleted file mode 100644
index 8b137891791f..000000000000
@@ -1 +0,0 @@
-
Documentation/DocBook/stylesheet.xsl deleted +0 -11
deleted file mode 100644
index 3bf4ecf3d760..000000000000
@@ -1,11 +0,0 @@
-<?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.consistent.ids">1</param>
-<param name="generate.section.toc.level">2</param>
-<param name="use.id.as.filename">1</param>
-</stylesheet>
Documentation/Makefile +125 -0

126 lines not on this page · raw message

Documentation/Makefile.sphinx deleted +0 -130

130 lines not on this page · raw message

Documentation/doc-guide/docbook.rst deleted +0 -90

90 lines not on this page · raw message

Makefile +4 -7
index 220121fdca4d..80be98ccca60 100644
@@ -1298,7 +1298,7 @@ clean: archclean vmlinuxclean
 #
 mrproper: rm-dirs  := $(wildcard $(MRPROPER_DIRS))
 mrproper: rm-files := $(wildcard $(MRPROPER_FILES))
-mrproper-dirs      := $(addprefix _mrproper_,Documentation/DocBook scripts)
+mrproper-dirs      := $(addprefix _mrproper_,scripts)
 
 PHONY += $(mrproper-dirs) mrproper archmrproper
 $(mrproper-dirs):
@@ -1400,9 +1400,7 @@ help:
 	@$(MAKE) $(build)=$(package-dir) help
 	@echo  ''
 	@echo  'Documentation targets:'
-	@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
-	@echo  ''
-	@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
+	@$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
 	@echo  ''
 	@echo  'Architecture specific targets ($(SRCARCH)):'
 	@$(if $(archhelp),$(archhelp),\
@@ -1453,9 +1451,8 @@ $(help-board-dirs): help-%:
 DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
-	$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
-	$(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
-	$(Q)$(MAKE) $(build)=Documentation/DocBook $@
+	$(Q)$(MAKE) $(build)=scripts build_docproc
+	$(Q)$(MAKE) $(build)=Documentation $@
 
 else # KBUILD_EXTMOD
 
scripts/Makefile +3 -6
index 1d80897a9644..55550e4141c4 100644
@@ -6,8 +6,7 @@
 # pnmttologo:    Convert pnm files to logo files
 # conmakehash:   Create chartable
 # conmakehash:	 Create arrays for initializing the kernel console tables
-# docproc:       Used in Documentation/DocBook
-# check-lc_ctype: Used in Documentation/DocBook
+# docproc:       Used in Documentation/
 
 HOST_EXTRACFLAGS += -I$(srctree)/tools/include
 
@@ -29,16 +28,14 @@ HOSTLOADLIBES_extract-cert = -lcrypto
 always		:= $(hostprogs-y) $(hostprogs-m)
 
 # The following hostprogs-y programs are only build on demand
-hostprogs-y += unifdef docproc check-lc_ctype
+hostprogs-y += unifdef docproc
 
 # These targets are used internally to avoid "is up to date" messages
-PHONY += build_unifdef build_docproc build_check-lc_ctype
+PHONY += build_unifdef build_docproc
 build_unifdef: $(obj)/unifdef
 	@:
 build_docproc: $(obj)/docproc
 	@:
-build_check-lc_ctype: $(obj)/check-lc_ctype
-	@:
 
 subdir-$(CONFIG_MODVERSIONS) += genksyms
 subdir-y                     += mod
scripts/check-lc_ctype.c deleted +0 -11
deleted file mode 100644
index 9097ff5449fb..000000000000
@@ -1,11 +0,0 @@
-/*
- * Check that a specified locale works as LC_CTYPE.  Used by the
- * DocBook build system to probe for C.UTF-8 support.
- */
-
-#include <locale.h>
-
-int main(void)
-{
-	return !setlocale(LC_CTYPE, "");
-}
Signature · 1 line
2.9.3
#3 lore raw

PATCH 3/13 docs: update old references for DocBook from the documentation

In reply to Mauro Carvalho Chehab

DocBook is mentioned several times at the documentation. Update the obsolete references from it at the DocBook.

---
 Documentation/PCI/MSI-HOWTO.txt            |  2 +-
 Documentation/admin-guide/README.rst       |  6 ---
 Documentation/doc-guide/index.rst          |  1 -
 Documentation/doc-guide/sphinx.rst         |  5 ---
 Documentation/fb/api.txt                   |  4 +-
 Documentation/gpu/todo.rst                 |  2 +-
 Documentation/kernel-doc-nano-HOWTO.txt    | 65 +++++-------------------------
 Documentation/process/changes.rst          | 26 +++---------
 Documentation/process/howto.rst            |  8 ----
 Documentation/process/kernel-docs.rst      | 34 +---------------
 Documentation/translations/ja_JP/howto.rst |  7 ----
 Documentation/translations/ko_KR/howto.rst |  7 ----
 12 files changed, 21 insertions(+), 146 deletions(-)
Documentation/PCI/MSI-HOWTO.txt +1 -1
index 1e37138027a3..618e13d5e276 100644
@@ -186,7 +186,7 @@ must disable interrupts while the lock is held.  If the device sends
 a different interrupt, the driver will deadlock trying to recursively
 acquire the spinlock.  Such deadlocks can be avoided by using
 spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
-and acquire the lock (see Documentation/DocBook/kernel-locking).
+and acquire the lock (see Documentation/kernel-hacking/locking.rst).
 
 4.5 How to tell whether MSI/MSI-X is enabled on a device
 
Documentation/admin-guide/README.rst +0 -6
index b96e80f79e85..b5343c5aa224 100644
@@ -55,12 +55,6 @@ Documentation
    contains information about the problems, which may result by upgrading
    your kernel.
 
- - The Documentation/DocBook/ subdirectory contains several guides for
-   kernel developers and users.  These guides can be rendered in a
-   number of formats:  PostScript (.ps), PDF, HTML, & man-pages, among others.
-   After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
-   or ``make mandocs`` will render the documentation in the requested format.
-
 Installing the kernel source
 ----------------------------
 
Documentation/doc-guide/index.rst +0 -1
index 6fff4024606e..a7f95d7d3a63 100644
@@ -10,7 +10,6 @@ How to write kernel documentation
    sphinx.rst
    kernel-doc.rst
    parse-headers.rst
-   docbook.rst
 
 .. only::  subproject and html
 
Documentation/doc-guide/sphinx.rst +0 -5
index 731334de3efd..84e8e8a9cbdb 100644
@@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The
 kernel-doc comments have some special structure and formatting, but beyond that
 they are also treated as reStructuredText.
 
-There is also the deprecated DocBook toolchain to generate documentation from
-DocBook XML template files under ``Documentation/DocBook``. The DocBook files
-are to be converted to reStructuredText, and the toolchain is slated to be
-removed.
-
 Finally, there are thousands of plain text documentation files scattered around
 ``Documentation``. Some of these will likely be converted to reStructuredText
 over time, but the bulk of them will remain in plain text.
Documentation/fb/api.txt +2 -2
index d4ff7de85700..d52cf1e3b975 100644
@@ -289,12 +289,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field.
 FOURCC definitions are located in the linux/videodev2.h header. However, and
 despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
 and don't require usage of the V4L2 subsystem. FOURCC documentation is
-available in Documentation/DocBook/v4l/pixfmt.xml.
+available in Documentation/media/uapi/v4l/pixfmt.rst.
 
 To select a format, applications set the grayscale field to the desired FOURCC.
 For YUV formats, they should also select the appropriate colorspace by setting
 the colorspace field to one of the colorspaces listed in linux/videodev2.h and
-documented in Documentation/DocBook/v4l/colorspaces.xml.
+documented in Documentation/media/uapi/v4l/colorspaces.rst.
 
 The red, green, blue and transp fields are not used with the FOURCC-based API.
 For forward compatibility reasons applications must zero those fields, and
Documentation/gpu/todo.rst +1 -1
index 1bdb7356a310..6162d0e9dc28 100644
@@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The
 task would be to clean up interfaces like moving functions around between
 files to better group them and improving the interfaces like dropping return
 values for functions that never fail. Then write kerneldoc for all exported
-functions and an overview section and integrate it all into the drm DocBook.
+functions and an overview section and integrate it all into the drm book.
 
 See https://dri.freedesktop.org/docs/drm/ for what's there already.
 
Documentation/kernel-doc-nano-HOWTO.txt +11 -54

96 lines not on this page · raw message

Documentation/process/changes.rst +5 -21
index e25d63f8c0da..3aed751e0cb5 100644
@@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
 
 Linux documentation for functions is transitioning to inline
 documentation via specially-formatted comments near their
-definitions in the source.  These comments can be combined with the
-SGML templates in the Documentation/DocBook directory to make DocBook
-files, which can then be converted by DocBook stylesheets to PostScript,
-HTML, PDF files, and several other formats.  In order to convert from
-DocBook format to a format of your choice, you'll need to install Jade as
-well as the desired DocBook stylesheets.
+definitions in the source.  These comments can be combined with ReST
+files the Documentation/ directory to make enriched documentation, which can
+then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
+In order to convert from ReST format to a format of your choice, you'll need
+Sphinx.
 
 Util-linux
 ----------
@@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.6.
   functionalities required for ``XeLaTex`` to work. For PDF output you'll also
   need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
 
-Other tools
------------
-
-In order to produce documentation from DocBook, you'll also need ``xmlto``.
-Please notice, however, that we're currently migrating all documents to use
-``Sphinx``.
 
 Getting updated software
 ========================
@@ -409,15 +402,6 @@ Quota-tools
 
 - <http://sourceforge.net/projects/linuxquota/>
 
-DocBook Stylesheets
--------------------
-
-- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
-
-XMLTO XSLT Frontend
--------------------
-
-- <http://cyberelk.net/tim/xmlto/>
 
 Intel P6 microcode
 ------------------
Documentation/process/howto.rst +0 -8
index 1260f60d4cb9..c6875b1db56f 100644
@@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
 	make latexdocs
 	make epubdocs
 
-Currently, there are some documents written on DocBook that are in
-the process of conversion to ReST. Such documents will be created in the
-Documentation/DocBook/ directory and can be generated also as
-Postscript or man pages by running::
-
-	make psdocs
-	make mandocs
-
 Becoming A Kernel Developer
 ---------------------------
 
Documentation/process/kernel-docs.rst +1 -33
index 05a7857a4a83..b8cac85a4001 100644
@@ -40,50 +40,18 @@ Enjoy!
 Docs at the Linux Kernel tree
 -----------------------------
 
-The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
 The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
 
     * Name: **linux/Documentation**
 
       :Author: Many.
       :Location: Documentation/
-      :Keywords: text files, Sphinx, DocBook.
+      :Keywords: text files, Sphinx.
       :Description: Documentation that comes with the kernel sources,
         inside the Documentation directory. Some pages from this document
         (including this document itself) have been moved there, and might
         be more up to date than the web version.
 
-    * Title: **The Kernel Hacking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-hacking.tmpl
-      :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
-        symbols, return conventions.
-      :Description: From the Introduction: "Please understand that I
-        never wanted to write this document, being grossly underqualified,
-        but I always wanted to read it, and this was the only way. I
-        simply explain some best practices, and give reading entry-points
-        into the kernel sources. I avoid implementation details: that's
-        what the code is for, and I ignore whole tracts of useful
-        routines. This document assumes familiarity with C, and an
-        understanding of what the kernel is, and how it is used. It was
-        originally written for the 2.3 kernels, but nearly all of it
-        applies to 2.2 too; 2.0 is slightly different".
-
-    * Title: **Linux Kernel Locking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-locking.tmpl
-      :Keywords: locks, locking, spinlock, semaphore, atomic, race
-        condition, bottom halves, tasklets, softirqs.
-      :Description: The title says it all: document describing the
-        locking system in the Linux Kernel either in uniprocessor or SMP
-        systems.
-      :Notes: "It was originally written for the later (>2.3.47) 2.3
-        kernels, but most of it applies to 2.2 too; 2.0 is slightly
-        different". Freely redistributable under the conditions of the GNU
-        General Public License.
-
 On-line docs
 ------------
 
Documentation/translations/ja_JP/howto.rst +0 -7
index 4511eed0fabb..8d7ed0cbbf5f 100644
@@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
         make latexdocs
         make epubdocs
 
-現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
-す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
-Postscript または man ページの形式を生成するには以下のようにします - ::
-
-        make psdocs
-        make mandocs
-
 カーネル開発者になるには
 ------------------------
 
Documentation/translations/ko_KR/howto.rst +0 -7
index 2333697251dd..f06de9ca41a4 100644
@@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
          make latexdocs
          make epubdocs
 
-현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
-문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다::
-
-         make psdocs
-         make mandocs
-
 커널 개발자가 되는 것
 ---------------------
 
Signature · 1 line
2.9.3
Acked-by on v1 3/13
#4 lore raw

Re: [PATCH 03/13] docs: update old references for DocBook from the documentation

Quoted 362 lines · Mauro Carvalho Chehab

DocBook is mentioned several times at the documentation. Update the obsolete references from it at the DocBook.

---

Documentation/PCI/MSI-HOWTO.txt            |  2 +-
Documentation/admin-guide/README.rst       |  6 ---
Documentation/doc-guide/index.rst          |  1 -
Documentation/doc-guide/sphinx.rst         |  5 ---
Documentation/fb/api.txt                   |  4 +-
Documentation/gpu/todo.rst                 |  2 +-
Documentation/kernel-doc-nano-HOWTO.txt    | 65 +++++-------------------------
Documentation/process/changes.rst          | 26 +++---------
Documentation/process/howto.rst            |  8 ----
Documentation/process/kernel-docs.rst      | 34 +---------------
Documentation/translations/ja_JP/howto.rst |  7 ----
Documentation/translations/ko_KR/howto.rst |  7 ----
12 files changed, 21 insertions(+), 146 deletions(-)
Documentation/PCI/MSI-HOWTO.txt +0 -0
index 1e37138027a3..618e13d5e276 100644
@@ -186,7 +186,7 @@ must disable interrupts while the lock is held.  If the device sends

a different interrupt, the driver will deadlock trying to recursively acquire the spinlock. Such deadlocks can be avoided by using spin_lock_irqsave() or spin_lock_irq() which disable local interrupts

Documentation/PCI/MSI-HOWTO.txt +1 -1
-and acquire the lock (see Documentation/DocBook/kernel-locking).
+and acquire the lock (see Documentation/kernel-hacking/locking.rst).

4.5 How to tell whether MSI/MSI-X is enabled on a device

Documentation/admin-guide/README.rst +0 -6
index b96e80f79e85..b5343c5aa224 100644
@@ -55,12 +55,6 @@ Documentation
   contains information about the problems, which may result by upgrading
   your kernel.
 
- - The Documentation/DocBook/ subdirectory contains several guides for
-   kernel developers and users.  These guides can be rendered in a
-   number of formats:  PostScript (.ps), PDF, HTML, & man-pages, among others.
-   After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
-   or ``make mandocs`` will render the documentation in the requested format.
-

Installing the kernel source
----------------------------

Documentation/doc-guide/index.rst +0 -1
index 6fff4024606e..a7f95d7d3a63 100644
@@ -10,7 +10,6 @@ How to write kernel documentation
   sphinx.rst
   kernel-doc.rst
   parse-headers.rst
-   docbook.rst
 

.. only:: subproject and html

Documentation/doc-guide/sphinx.rst +0 -0
index 731334de3efd..84e8e8a9cbdb 100644
@@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The

kernel-doc comments have some special structure and formatting, but beyond that they are also treated as reStructuredText.

Documentation/doc-guide/sphinx.rst +0 -5
-There is also the deprecated DocBook toolchain to generate documentation from
-DocBook XML template files under ``Documentation/DocBook``. The DocBook files
-are to be converted to reStructuredText, and the toolchain is slated to be
-removed.
-

Finally, there are thousands of plain text documentation files scattered around ``Documentation``. Some of these will likely be converted to reStructuredText over time, but the bulk of them will remain in plain text.

Documentation/fb/api.txt +0 -0
index d4ff7de85700..d52cf1e3b975 100644
@@ -289,12 +289,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field.

FOURCC definitions are located in the linux/videodev2.h header. However, and despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2 and don't require usage of the V4L2 subsystem. FOURCC documentation is

Documentation/fb/api.txt +1 -1
-available in Documentation/DocBook/v4l/pixfmt.xml.
+available in Documentation/media/uapi/v4l/pixfmt.rst.

To select a format, applications set the grayscale field to the desired FOURCC. For YUV formats, they should also select the appropriate colorspace by setting the colorspace field to one of the colorspaces listed in linux/videodev2.h and

Documentation/fb/api.txt +1 -1
-documented in Documentation/DocBook/v4l/colorspaces.xml.
+documented in Documentation/media/uapi/v4l/colorspaces.rst.

The red, green, blue and transp fields are not used with the FOURCC-based API. For forward compatibility reasons applications must zero those fields, and

Documentation/gpu/todo.rst +0 -0
index 1bdb7356a310..6162d0e9dc28 100644
@@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The

task would be to clean up interfaces like moving functions around between files to better group them and improving the interfaces like dropping return values for functions that never fail. Then write kerneldoc for all exported

Documentation/gpu/todo.rst +1 -1
-functions and an overview section and integrate it all into the drm DocBook.
+functions and an overview section and integrate it all into the drm book.

See https://dri.freedesktop.org/docs/drm/ for what's there already.

Documentation/kernel-doc-nano-HOWTO.txt +0 -0
index 104740ea0041..c23e2c5ab80d 100644
@@ -17,8 +17,8 @@ The format for this documentation is called the kernel-doc format.

It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.

This style embeds the documentation within the source files, using

Documentation/kernel-doc-nano-HOWTO.txt +2 -2
-a few simple conventions.  The scripts/kernel-doc perl script, some
-SGML templates in Documentation/DocBook, and other tools understand
+a few simple conventions.  The scripts/kernel-doc perl script, the
+Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand

these conventions, and are used to extract this embedded documentation into various documents.

Documentation/kernel-doc-nano-HOWTO.txt +4 -19
@@ -122,15 +122,9 @@ are:
- scripts/kernel-doc
 
  This is a perl script that hunts for the block comments and can mark
-  them up directly into DocBook, man, text, and HTML. (No, not
+  them up directly into DocBook, ReST, man, text, and HTML. (No, not
  texinfo.)
 
-- Documentation/DocBook/*.tmpl
-
-  These are SGML template files, which are normal SGML files with
-  special place-holders for where the extracted documentation should
-  go.
-
- scripts/docproc.c
 
  This is a program for converting SGML template files into SGML
@@ -145,25 +139,18 @@ are:
 
- Makefile
 
-  The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
-  to build XML DocBook files, PostScript files, PDF files, and html files
-  in Documentation/DocBook. The older target 'sgmldocs' is equivalent
-  to 'xmldocs'.
-
-- Documentation/DocBook/Makefile
-
-  This is where C files are associated with SGML templates.
-
+  The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
+  are used to build XML DocBook files, LaTeX files, PDF files,
+  ePub files and html files in Documentation/.
 

How to extract the documentation
--------------------------------

If you just want to read the ready-made books on the various

Documentation/kernel-doc-nano-HOWTO.txt +4 -5
-subsystems (see Documentation/DocBook/*.tmpl), just type 'make
-psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
-preference.  If you would rather read a different format, you can type
-'make xmldocs' and then use DocBook tools to convert
-Documentation/DocBook/*.xml to a format of your choice (for example,
+subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
+depending on your preference.  If you would rather read a different format,
+you can type 'make xmldocs' and then use DocBook tools to convert
+Documentation/output/*.xml to a format of your choice (for example,

'db2html ...' if 'make htmldocs' was not defined).

If you want to see man pages instead, you can do this:

Documentation/kernel-doc-nano-HOWTO.txt +1 -31
@@ -329,37 +316,7 @@ This is done by using a DOC: section keyword with a section title.  E.g.:
 * hardware, software, or its subject(s).
 */
 
-DOC: sections are used in SGML templates files as indicated below.
-
-
-How to make new SGML template files
------------------------------------
-
-SGML template files (*.tmpl) are like normal SGML files, except that
-they can contain escape sequences where extracted documentation should
-be inserted.
-
-!E<filename> is replaced by the documentation, in <filename>, for
-functions that are exported using EXPORT_SYMBOL: the function list is
-collected from files listed in Documentation/DocBook/Makefile.
-
-!I<filename> is replaced by the documentation for functions that are
-_not_ exported using EXPORT_SYMBOL.
-
-!D<filename> is used to name additional files to search for functions
-exported using EXPORT_SYMBOL.
-
-!F<filename> <function [functions...]> is replaced by the
-documentation, in <filename>, for the functions listed.
-
-!P<filename> <section title> is replaced by the contents of the DOC:
-section titled <section title> from <filename>.
-Spaces are allowed in <section title>; do not quote the <section title>.
-
-!C<filename> is replaced by nothing, but makes the tools check that
-all DOC: sections and documented functions, symbols, etc. are used.
-This makes sense to use when you use !F/!P only and want to verify
-that all documentation is included.
+DOC: sections are used in ReST files.
 

Tim.
*/ <[email protected]>

Documentation/process/changes.rst +0 -0
index e25d63f8c0da..3aed751e0cb5 100644
@@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
 

Linux documentation for functions is transitioning to inline documentation via specially-formatted comments near their

Documentation/process/changes.rst +5 -6
-definitions in the source.  These comments can be combined with the
-SGML templates in the Documentation/DocBook directory to make DocBook
-files, which can then be converted by DocBook stylesheets to PostScript,
-HTML, PDF files, and several other formats.  In order to convert from
-DocBook format to a format of your choice, you'll need to install Jade as
-well as the desired DocBook stylesheets.
+definitions in the source.  These comments can be combined with ReST
+files the Documentation/ directory to make enriched documentation, which can
+then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
+In order to convert from ReST format to a format of your choice, you'll need
+Sphinx.

Util-linux
----------

Documentation/process/changes.rst +0 -6
@@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.6.
  functionalities required for ``XeLaTex`` to work. For PDF output you'll also
  need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
 
-Other tools
------------
-
-In order to produce documentation from DocBook, you'll also need ``xmlto``.
-Please notice, however, that we're currently migrating all documents to use
-``Sphinx``.
 

Getting updated software
========================

Documentation/process/changes.rst +0 -10
@@ -409,15 +402,6 @@ Quota-tools
 
- <http://sourceforge.net/projects/linuxquota/>
 
-DocBook Stylesheets
--------------------
-
-- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
-
-XMLTO XSLT Frontend
--------------------
-
-- <http://cyberelk.net/tim/xmlto/>
 

Intel P6 microcode
------------------

Documentation/process/howto.rst +0 -8
index 1260f60d4cb9..c6875b1db56f 100644
@@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
 	make latexdocs
 	make epubdocs
 
-Currently, there are some documents written on DocBook that are in
-the process of conversion to ReST. Such documents will be created in the
-Documentation/DocBook/ directory and can be generated also as
-Postscript or man pages by running::
-
-	make psdocs
-	make mandocs
-

Becoming A Kernel Developer
---------------------------

Documentation/process/kernel-docs.rst +0 -0
index 05a7857a4a83..b8cac85a4001 100644
@@ -40,50 +40,18 @@ Enjoy!

Docs at the Linux Kernel tree
-----------------------------

-The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.

* Name: **linux/Documentation**

:Author: Many.
:Location: Documentation/

Documentation/process/kernel-docs.rst +1 -32
-      :Keywords: text files, Sphinx, DocBook.
+      :Keywords: text files, Sphinx.
      :Description: Documentation that comes with the kernel sources,
        inside the Documentation directory. Some pages from this document
        (including this document itself) have been moved there, and might
        be more up to date than the web version.
 
-    * Title: **The Kernel Hacking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-hacking.tmpl
-      :Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
-        symbols, return conventions.
-      :Description: From the Introduction: "Please understand that I
-        never wanted to write this document, being grossly underqualified,
-        but I always wanted to read it, and this was the only way. I
-        simply explain some best practices, and give reading entry-points
-        into the kernel sources. I avoid implementation details: that's
-        what the code is for, and I ignore whole tracts of useful
-        routines. This document assumes familiarity with C, and an
-        understanding of what the kernel is, and how it is used. It was
-        originally written for the 2.3 kernels, but nearly all of it
-        applies to 2.2 too; 2.0 is slightly different".
-
-    * Title: **Linux Kernel Locking HOWTO**
-
-      :Author: Various Talented People, and Rusty.
-      :Location: Documentation/DocBook/kernel-locking.tmpl
-      :Keywords: locks, locking, spinlock, semaphore, atomic, race
-        condition, bottom halves, tasklets, softirqs.
-      :Description: The title says it all: document describing the
-        locking system in the Linux Kernel either in uniprocessor or SMP
-        systems.
-      :Notes: "It was originally written for the later (>2.3.47) 2.3
-        kernels, but most of it applies to 2.2 too; 2.0 is slightly
-        different". Freely redistributable under the conditions of the GNU
-        General Public License.
-

On-line docs
------------

Documentation/translations/ja_JP/howto.rst +0 -7
index 4511eed0fabb..8d7ed0cbbf5f 100644
@@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
        make latexdocs
        make epubdocs
 
-現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
-す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
-Postscript または man ページの形式を生成するには以下のようにします - ::
-
-        make psdocs
-        make mandocs
-

カーネル開発者になるには
------------------------

Documentation/translations/ko_KR/howto.rst +0 -0
index 2333697251dd..f06de9ca41a4 100644

Documentation/translations/ko_KR/howto.rst ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된 · line 200

Quoted 10 lines
Documentation/translations/ko_KR/howto.rst +0 -7
@@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
         make latexdocs
         make epubdocs
 
-현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
-문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다::
-
-         make psdocs
-         make mandocs
-

for translations/ko_KR/ part change. Looks good to me!

Thanks,
SeongJae Park

Quoted 7 lines

커널 개발자가 되는 것
---------------------

Signature · 1 line
2.9.3
#5 lore raw

PATCH 4/13 MAINTAINERS: update old references for DocBook directory

In reply to Mauro Carvalho Chehab

As everything was converted, update the references to point to the new places.

---
 MAINTAINERS | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
MAINTAINERS +2 -3
index f42daf74f541..8609dba03cbc 100644
@@ -3567,7 +3567,6 @@ T:	git git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6.git
 S:	Maintained
 F:	Documentation/crypto/
 F:	Documentation/devicetree/bindings/crypto/
-F:	Documentation/DocBook/crypto-API.tmpl
 F:	arch/*/crypto/
 F:	crypto/
 F:	drivers/crypto/
@@ -7364,7 +7363,7 @@ W:	http://kgdb.wiki.kernel.org/
 L:	[email protected]
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git
 S:	Maintained
-F:	Documentation/DocBook/kgdb.tmpl
+F:	Documentation/dev-tools/kgdb.rst
 F:	drivers/misc/kgdbts.c
 F:	drivers/tty/serial/kgdboc.c
 F:	include/linux/kdb.h
@@ -10971,7 +10970,7 @@ S:	Supported
 F:	arch/s390/
 F:	drivers/s390/
 F:	Documentation/s390/
-F:	Documentation/DocBook/s390*
+F:	Documentation/driver-api/s390-drivers.rst
 
 S390 COMMON I/O LAYER
 M:	Sebastian Ott <[email protected]>
Signature · 1 line
2.9.3
#6 lore raw

PATCH 5/13 ata: update references for libata documentation

In reply to Mauro Carvalho Chehab

The libata documentation is now using ReST. Update references to it to point to the new place.

---
 drivers/ata/acard-ahci.c    | 2 +-
 drivers/ata/ahci.c          | 2 +-
 drivers/ata/ahci.h          | 2 +-
 drivers/ata/ata_piix.c      | 2 +-
 drivers/ata/libahci.c       | 2 +-
 drivers/ata/libata-core.c   | 2 +-
 drivers/ata/libata-eh.c     | 2 +-
 drivers/ata/libata-scsi.c   | 2 +-
 drivers/ata/libata-sff.c    | 2 +-
 drivers/ata/libata.h        | 2 +-
 drivers/ata/pata_pdc2027x.c | 2 +-
 drivers/ata/pdc_adma.c      | 2 +-
 drivers/ata/sata_nv.c       | 2 +-
 drivers/ata/sata_promise.c  | 2 +-
 drivers/ata/sata_promise.h  | 2 +-
 drivers/ata/sata_qstor.c    | 2 +-
 drivers/ata/sata_sil.c      | 2 +-
 drivers/ata/sata_sis.c      | 2 +-
 drivers/ata/sata_svw.c      | 2 +-
 drivers/ata/sata_sx4.c      | 2 +-
 drivers/ata/sata_uli.c      | 2 +-
 drivers/ata/sata_via.c      | 2 +-
 drivers/ata/sata_vsc.c      | 2 +-
 include/linux/ata.h         | 2 +-
 include/linux/libata.h      | 2 +-
 25 files changed, 25 insertions(+), 25 deletions(-)
drivers/ata/acard-ahci.c +1 -1
index ed6a30cd681a..940ddbc59aa7 100644
@@ -25,7 +25,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
drivers/ata/ahci.c +1 -1
index 2fc52407306c..fd712e0e9d87 100644
@@ -24,7 +24,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
drivers/ata/ahci.h +1 -1
index 5db6ab261643..30f67a1a4f54 100644
@@ -24,7 +24,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
drivers/ata/ata_piix.c +1 -1
index ffbe625e6fd2..8401c3b5be92 100644
@@ -33,7 +33,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available at http://developer.intel.com/
  *
drivers/ata/libahci.c +1 -1
index 3159f9e66d8f..6154f0e2b81a 100644
@@ -24,7 +24,7 @@
  *
  *
  * libata documentation is available via 'make {ps|pdf}docs',
- * as Documentation/DocBook/libata.*
+ * as Documentation/driver-api/libata.rst
  *
  * AHCI hardware documentation:
  * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
drivers/ata/libata-core.c +1 -1
index 2d83b8c75965..55aaa2e4c683 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/ and
  *  http://www.sata-io.org/
drivers/ata/libata-eh.c +1 -1
index ef68232b5222..7e33e200aae5 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/ and
  *  http://www.sata-io.org/
drivers/ata/libata-scsi.c +1 -1
index dcd38d9e9804..b0866f040d1f 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from
  *  - http://www.t10.org/
drivers/ata/libata-sff.c +1 -1
index 274d6d7193d7..052921352f31 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/ and
  *  http://www.sata-io.org/
drivers/ata/libata.h +1 -1
index 120fce0befd3..5afe35baf61b 100644
@@ -21,7 +21,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 
drivers/ata/pata_pdc2027x.c +1 -1
index d9ef9e276225..82bfd51692f3 100644
@@ -17,7 +17,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware information only available under NDA.
  *
drivers/ata/pdc_adma.c +1 -1
index 64d682c6ee57..f1e873a37465 100644
@@ -21,7 +21,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *
  *  Supports ATA disks in single-packet ADMA mode.
drivers/ata/sata_nv.c +1 -1
index 734f563b8d37..8c683ddd0f58 100644
@@ -21,7 +21,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  No hardware documentation available outside of NVIDIA.
  *  This driver programs the NVIDIA SATA controller in a similar
drivers/ata/sata_promise.c +1 -1
index 0fa211e2831c..d032bf657f70 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware information only available under NDA.
  *
drivers/ata/sata_promise.h +1 -1
index 00d6000e546f..61633ef5ed72 100644
@@ -20,7 +20,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 
drivers/ata/sata_qstor.c +1 -1
index af987a4f33d1..1fe941688e95 100644
@@ -23,7 +23,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 
drivers/ata/sata_sil.c +1 -1
index 29bcff086bce..ed76f070d21e 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Documentation for SiI 3112:
  *  http://gkernel.sourceforge.net/specs/sii/3112A_SiI-DS-0095-B2.pdf.bz2
drivers/ata/sata_sis.c +1 -1
index d1637ac40a73..30f4f35f36d4 100644
@@ -24,7 +24,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *
drivers/ata/sata_svw.c +1 -1
index ff614be55d0f..0fd6ac7e57ba 100644
@@ -30,7 +30,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *
drivers/ata/sata_sx4.c +1 -1
index 48301cb3a316..405e606a234d 100644
@@ -24,7 +24,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *
drivers/ata/sata_uli.c +1 -1
index 08f98c3ed5c8..4f6e8d8156de 100644
@@ -18,7 +18,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *
drivers/ata/sata_via.c +1 -1
index f3f538eec7b3..22e96fc77d09 100644
@@ -25,7 +25,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available under NDA.
  *
drivers/ata/sata_vsc.c +1 -1
index 183eb52085df..9648127cca70 100644
@@ -26,7 +26,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Vitesse hardware documentation presumably available under NDA.
  *  Intel 31244 (same hardware interface) documentation presumably
include/linux/ata.h +1 -1
index ad7d9ee89ff0..73fe18edfdaf 100644
@@ -20,7 +20,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  *  Hardware documentation available from http://www.t13.org/
  *
include/linux/libata.h +1 -1
index c9a69fc8821e..9e6633235ad7 100644
@@ -19,7 +19,7 @@
  *
  *
  *  libata documentation is available via 'make {ps|pdf}docs',
- *  as Documentation/DocBook/libata.*
+ *  as Documentation/driver-api/libata.rst
  *
  */
 
Signature · 1 line
2.9.3
#7 lore raw

PATCH 6/13 ia64, scsi: update references for the device-io book

In reply to Mauro Carvalho Chehab

The book is now at Documentation/driver-api/device-io.rst. Update such references.

---
 arch/ia64/include/asm/io.h | 2 +-
 arch/ia64/sn/kernel/iomv.c | 2 +-
 drivers/scsi/qla1280.c     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
arch/ia64/include/asm/io.h +1 -1
index 5de673ac9cb1..a2540e21f919 100644
@@ -117,7 +117,7 @@ extern int valid_mmap_phys_addr_range (unsigned long pfn, size_t count);
  * following the barrier will arrive after all previous writes.  For most
  * ia64 platforms, this is a simple 'mf.a' instruction.
  *
- * See Documentation/DocBook/deviceiobook.tmpl for more information.
+ * See Documentation/driver-api/device-io.rst for more information.
  */
 static inline void ___ia64_mmiowb(void)
 {
arch/ia64/sn/kernel/iomv.c +1 -1
index c77ebdf98119..2b22a71663c1 100644
@@ -63,7 +63,7 @@ EXPORT_SYMBOL(sn_io_addr);
 /**
  * __sn_mmiowb - I/O space memory barrier
  *
- * See arch/ia64/include/asm/io.h and Documentation/DocBook/deviceiobook.tmpl
+ * See arch/ia64/include/asm/io.h and Documentation/driver-api/device-io.rst
  * for details.
  *
  * On SN2, we wait for the PIO_WRITE_STATUS SHub register to clear.
drivers/scsi/qla1280.c +1 -1
index 634254a52301..8a29fb09db14 100644
@@ -3390,7 +3390,7 @@ qla1280_isp_cmd(struct scsi_qla_host *ha)
 	 *    On PCI bus, order reverses and write of 6 posts, then index 5,
 	 *       causing chip to issue full queue of stale commands
 	 * The mmiowb() prevents future writes from crossing the barrier.
-	 * See Documentation/DocBook/deviceiobook.tmpl for more information.
+	 * See Documentation/driver-api/device-io.rst for more information.
 	 */
 	WRT_REG_WORD(&reg->mailbox4, ha->req_ring_index);
 	mmiowb();
Signature · 1 line
2.9.3
#8 lore raw

PATCH 7/13 irq: update genericirq book location

In reply to Mauro Carvalho Chehab

This book got converted from DocBook. Update its references to point to the current location.

---
 kernel/irq/chip.c    | 2 +-
 kernel/irq/handle.c  | 2 +-
 kernel/irq/irqdesc.c | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
kernel/irq/chip.c +1 -1
index 686be4b73018..4188a0a7691f 100644
@@ -7,7 +7,7 @@
  * This file contains the core interrupt handling code, for irq-chip
  * based architectures.
  *
- * Detailed information is available in Documentation/DocBook/genericirq
+ * Detailed information is available in Documentation/core-api/genericirq.rst
  */
 
 #include <linux/irq.h>
kernel/irq/handle.c +1 -1
index d3f24905852c..bbf9a7174283 100644
@@ -6,7 +6,7 @@
  *
  * This file contains the core interrupt handling code.
  *
- * Detailed information is available in Documentation/DocBook/genericirq
+ * Detailed information is available in Documentation/core-api/genericirq.rst
  *
  */
 
kernel/irq/irqdesc.c +1 -1
index 00bb0aeea1d0..22e443133987 100644
@@ -4,7 +4,7 @@
  *
  * This file contains the interrupt descriptor management code
  *
- * Detailed information is available in Documentation/DocBook/genericirq
+ * Detailed information is available in Documentation/core-api/genericirq.rst
  *
  */
 #include <linux/irq.h>
Signature · 1 line
2.9.3
#9 lore raw

PATCH 8/13 fs: update location of filesystems documentation

In reply to Mauro Carvalho Chehab

The filesystem documentation was moved from DocBook to Documentation/filesystems/. Update it at the sources.

---
 fs/debugfs/file.c       | 2 +-
 include/linux/debugfs.h | 2 +-
 lib/Kconfig.debug       | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
fs/debugfs/file.c +1 -1
index 354e2ab62031..6dabc4a10396 100644
@@ -9,7 +9,7 @@
  *	2 as published by the Free Software Foundation.
  *
  *  debugfs is for people to use instead of /proc or /sys.
- *  See Documentation/DocBook/filesystems for more details.
+ *  See Documentation/filesystems/ for more details.
  *
  */
 
include/linux/debugfs.h +1 -1
index 9174b0d28582..aa86e6d8c1aa 100644
@@ -9,7 +9,7 @@
  *	2 as published by the Free Software Foundation.
  *
  *  debugfs is for people to use instead of /proc or /sys.
- *  See Documentation/DocBook/filesystems for more details.
+ *  See Documentation/filesystems/ for more details.
  */
 
 #ifndef _DEBUGFS_H_
lib/Kconfig.debug +1 -1
index e4587ebe52c7..b7882d45f48e 100644
@@ -286,7 +286,7 @@ config DEBUG_FS
 	  write to these files.
 
 	  For detailed documentation on the debugfs API, see
-	  Documentation/DocBook/filesystems.
+	  Documentation/filesystems/.
 
 	  If unsure, say N.
 
Signature · 1 line
2.9.3
#10 lore raw

PATCH 9/13 lib: update location of kgdb documentation

In reply to Mauro Carvalho Chehab

The documentation was moved from DocBook directory. Update its location.

---
 lib/Kconfig.kgdb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
lib/Kconfig.kgdb +1 -1
index 533f912638ed..ab4ff0eea776 100644
@@ -13,7 +13,7 @@ menuconfig KGDB
 	  CONFIG_FRAME_POINTER to aid in producing more reliable stack
 	  backtraces in the external debugger.  Documentation of
 	  kernel debugger is available at http://kgdb.sourceforge.net
-	  as well as in DocBook form in Documentation/DocBook/.  If
+	  as well as in Documentation/dev-tools/kgdb.rst.  If
 	  unsure, say N.
 
 if KGDB
Signature · 1 line
2.9.3
#11 lore raw

PATCH 10/13 sound: fix the comments that refers to kernel-doc

In reply to Mauro Carvalho Chehab

The markup inside the #if 0 comment actually refers to a kernel-doc markup. As we're getting rid of DocBook update it.

---
 include/sound/pcm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/sound/pcm.h +1 -1
index 361749e60799..bbf97d4c4c17 100644
@@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
 int snd_pcm_format_linear(snd_pcm_format_t format);
 int snd_pcm_format_little_endian(snd_pcm_format_t format);
 int snd_pcm_format_big_endian(snd_pcm_format_t format);
-#if 0 /* just for DocBook */
+#if 0 /* just for kernel-doc */
 /**
  * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
  * @format: the format to check
Signature · 1 line
2.9.3
Reviewed-by on v1 10/13
#12 lore raw

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

Quoted 5 lines · Mauro Carvalho Chehab

The markup inside the #if 0 comment actually refers to a kernel-doc markup. As we're getting rid of DocBook update it.

I guess you prefer taking it from your tree? Feel free to take my ack:

thanks,

Takashi

Quoted 21 lines
---
 include/sound/pcm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/sound/pcm.h +1 -1
index 361749e60799..bbf97d4c4c17 100644
@@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
 int snd_pcm_format_linear(snd_pcm_format_t format);
 int snd_pcm_format_little_endian(snd_pcm_format_t format);
 int snd_pcm_format_big_endian(snd_pcm_format_t format);
-#if 0 /* just for DocBook */
+#if 0 /* just for kernel-doc */
 /**
  * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
  * @format: the format to check
Signature · 1 line
2.9.3
#13 lore raw

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

Em Mon, 15 May 2017 11:04:26 +0200
Takashi Iwai <[email protected]> escreveu:

Quoted 11 lines
Quoted 5 lines · Mauro Carvalho Chehab

The markup inside the #if 0 comment actually refers to a kernel-doc markup. As we're getting rid of DocBook update it.

I guess you prefer taking it from your tree? Feel free to take my ack:

In the specific case of this patch, it doesn't matter much from what tree it would be merged, as no other patch depends on it ;)

So, if you prefer, you can merge it directly on your tree. Otherwise, I'll keep it on my pile of patches to be send to docs -next.

Quoted 19 lines

thanks,

Takashi

Quoted 13 lines
---
 include/sound/pcm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/sound/pcm.h +0 -1
index 361749e60799..bbf97d4c4c17 100644
@@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
 int snd_pcm_format_linear(snd_pcm_format_t format);
 int snd_pcm_format_little_endian(snd_pcm_format_t format);
 int snd_pcm_format_big_endian(snd_pcm_format_t format);
-#if 0 /* just for DocBook */
Quoted 8 lines
Quoted 8 lines
include/sound/pcm.h +1 -0
+#if 0 /* just for kernel-doc */
 /**
  * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
  * @format: the format to check
Signature · 1 line
2.9.3

Thanks,
Mauro

#14 lore raw

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

Quoted 16 lines · Mauro Carvalho Chehab

Em Mon, 15 May 2017 11:04:26 +0200
Takashi Iwai <[email protected]> escreveu:

Quoted 11 lines
Quoted 5 lines · Mauro Carvalho Chehab

The markup inside the #if 0 comment actually refers to a kernel-doc markup. As we're getting rid of DocBook update it.

I guess you prefer taking it from your tree? Feel free to take my ack:

Quoted 5 lines

In the specific case of this patch, it doesn't matter much from what tree it would be merged, as no other patch depends on it ;)

So, if you prefer, you can merge it directly on your tree. Otherwise, I'll keep it on my pile of patches to be send to docs -next.

OK, since the PCM stuff is being changed for 4.13, may be it's safer that I take this patch in sound git tree.

thanks,

Takashi

Quoted 35 lines
Quoted 21 lines

thanks,

Takashi

Quoted 13 lines
---
 include/sound/pcm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/sound/pcm.h +0 -1
index 361749e60799..bbf97d4c4c17 100644
@@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
 int snd_pcm_format_linear(snd_pcm_format_t format);
 int snd_pcm_format_little_endian(snd_pcm_format_t format);
 int snd_pcm_format_big_endian(snd_pcm_format_t format);
-#if 0 /* just for DocBook */
Quoted 8 lines
Quoted 8 lines
include/sound/pcm.h +1 -0
+#if 0 /* just for kernel-doc */
 /**
  * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
  * @format: the format to check
Signature · 1 line
2.9.3

Thanks,
Mauro

#15 lore raw

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

Em Tue, 16 May 2017 12:50:55 +0200
Takashi Iwai <[email protected]> escreveu:

Quoted 18 lines
Quoted 16 lines · Mauro Carvalho Chehab

Em Mon, 15 May 2017 11:04:26 +0200
Takashi Iwai <[email protected]> escreveu:

Quoted 11 lines
Quoted 5 lines · Mauro Carvalho Chehab

The markup inside the #if 0 comment actually refers to a kernel-doc markup. As we're getting rid of DocBook update it.

I guess you prefer taking it from your tree? Feel free to take my ack:

Quoted 8 lines
Quoted 5 lines

In the specific case of this patch, it doesn't matter much from what tree it would be merged, as no other patch depends on it ;)

So, if you prefer, you can merge it directly on your tree. Otherwise, I'll keep it on my pile of patches to be send to docs -next.

OK, since the PCM stuff is being changed for 4.13, may be it's safer that I take this patch in sound git tree.

OK! I'll remove from my patch pile :-)

Thanks,
Mauro

#16 lore raw

PATCH 11/13 fs: fix the location of the kernel-api book

In reply to Mauro Carvalho Chehab

The kernel-api book is now part of the core-api. Update its location.

---
 fs/debugfs/inode.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
fs/debugfs/inode.c +1 -1
index e892ae7d89f8..77440e4aa9d4 100644
@@ -9,7 +9,7 @@
  *	2 as published by the Free Software Foundation.
  *
  *  debugfs is for people to use instead of /proc or /sys.
- *  See Documentation/DocBook/kernel-api for more details.
+ *  See ./Documentation/core-api/kernel-api.rst for more details.
  *
  */
 
Signature · 1 line
2.9.3
#17 lore raw

PATCH 12/13 usb: fix the comment with regards to DocBook

In reply to Mauro Carvalho Chehab

The USB gadget documentation is not at DocBook anymore. The main file was converted to ReST, and stored at Documentation/driver-api/usb/gadget.rst, but there are still several plain text files related to gadget under Documentation/usb.

So, be generic and just mention documentation without specifying where it is.

---
 drivers/usb/gadget/Kconfig | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/usb/gadget/Kconfig +1 -1
index c164d6b788c3..b3c879b75a39 100644
@@ -41,7 +41,7 @@ menuconfig USB_GADGET
 	   don't have this kind of hardware (except maybe inside Linux PDAs).
 
 	   For more information, see <http://www.linux-usb.org/gadget> and
-	   the kernel DocBook documentation for this API.
+	   the kernel documentation for this API.
 
 if USB_GADGET
 
Signature · 1 line
2.9.3
#18 lore raw

PATCH 13/13 docs-rst: get rid of Documentation/sphinx/tmplcvt script

In reply to Mauro Carvalho Chehab

As everything was converted to ReST, we don't need this script anymore.

---
 Documentation/sphinx/tmplcvt | 28 ----------------------------
 1 file changed, 28 deletions(-)
 delete mode 100755 Documentation/sphinx/tmplcvt
Documentation/sphinx/tmplcvt deleted +0 -28
deleted file mode 100755
index 6848f0a26fa5..000000000000
@@ -1,28 +0,0 @@
-#!/bin/bash
-#
-# Convert a template file into something like RST
-#
-# fix <function>
-# feed to pandoc
-# fix \_
-# title line?
-#
-set -eu
-
-if [ "$#" != "2" ]; then
-	echo "$0 <docbook file> <rst file>"
-	exit
-fi
-
-DIR=$(dirname $0)
-
-in=$1
-rst=$2
-tmp=$rst.tmp
-
-cp $in $tmp
-sed --in-place -f $DIR/convert_template.sed $tmp
-pandoc -s -S -f docbook -t rst -o $rst $tmp
-sed --in-place -f $DIR/post_convert.sed $rst
-rm $tmp
-echo "book writen to $rst"
Signature · 1 line
2.9.3
#19 lore raw
In reply to Mauro Carvalho Chehab
Quoted 3 lines · Mauro Carvalho Chehab

As just one book (lsm) was missing conversion, let's convert it and store as if it were a plain text file under Documentation/lsm.txt, adding a notice that it requires update.

I could probably fold this change into my rst-ification of Documentation/security/

https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=kspp/rst

Specifically, the new Documentation/security/LSM.rst was rather short. I think your lsm.txt and this one could be likely merged.

-Kees

Signature · 6 lines
Kees Cook
Pixel Security
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#20 lore raw

Em Sun, 14 May 2017 14:05:09 -0700
Kees Cook <[email protected]> escreveu:

Quoted 6 lines
Quoted 3 lines · Mauro Carvalho Chehab

As just one book (lsm) was missing conversion, let's convert it and store as if it were a plain text file under Documentation/lsm.txt, adding a notice that it requires update.

Quoted 7 lines

I could probably fold this change into my rst-ification of Documentation/security/

https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=kspp/rst

Specifically, the new Documentation/security/LSM.rst was rather short. I think your lsm.txt and this one could be likely merged.

Yeah, makes sense. I'm not sure what would be the best way to proceed, as, currently, after removing lsm.tmpl, my patch series remove DocBook, as everything else was already removed.

I see a few ways for us to proceed:

1) You could submit the patches you have so far to docs -next, to be merged before my patch series;

2) I could send you a patch based on your tree. I'll need to rebase this series to be applied on the top of your tree + docs-next, with would require that your patch series would be merged before, at docs -next;

3) we can handle both series independently. When both gets merged at docs -next, a simple patch, either written by you or me, could merge both files.

IMO, (3) is simpler, but if you prefer, we can do on some other way.

Thanks,
Mauro
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#21 lore raw
Quoted 17 lines · Mauro Carvalho Chehab

Em Sun, 14 May 2017 14:05:09 -0700
Kees Cook <[email protected]> escreveu:

Quoted 6 lines
Quoted 3 lines · Mauro Carvalho Chehab

As just one book (lsm) was missing conversion, let's convert it and store as if it were a plain text file under Documentation/lsm.txt, adding a notice that it requires update.

Quoted 7 lines

I could probably fold this change into my rst-ification of Documentation/security/

https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=kspp/rst

Specifically, the new Documentation/security/LSM.rst was rather short. I think your lsm.txt and this one could be likely merged.

Quoted 8 lines

Yeah, makes sense. I'm not sure what would be the best way to proceed, as, currently, after removing lsm.tmpl, my patch series remove DocBook, as everything else was already removed.

I see a few ways for us to proceed:

1) You could submit the patches you have so far to docs -next, to be merged before my patch series;

I sent my series already (it got CCed to linux-doc); it's collected a few Acks already. I'm not sure what the timing for that means, though.

Quoted 8 lines

2) I could send you a patch based on your tree. I'll need to rebase this series to be applied on the top of your tree + docs-next, with would require that your patch series would be merged before, at docs -next;

3) we can handle both series independently. When both gets merged at docs -next, a simple patch, either written by you or me, could merge both files.

I don't see a reason for us to make the trees depend on each other. Let's just proceed as-is and whenever we're in a position to merge the LSM docs, we can do that.

Quoted 2 lines

IMO, (3) is simpler, but if you prefer, we can do on some other way.

Agreed.

-Kees

Signature · 6 lines
Kees Cook
Pixel Security
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel