[PATCH 03/13] docs: update old references for DocBook from the documentation
SeongJae Park
sj38.park at gmail.com
Mon May 15 02:07:11 UTC 2017
On Sun, 14 May 2017, Mauro Carvalho Chehab wrote:
> DocBook is mentioned several times at the documentation. Update
> the obsolete references from it at the DocBook.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab at s-opensource.com>
> ---
> 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(-)
>
> diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.txt
> index 1e37138027a3..618e13d5e276 100644
> --- a/Documentation/PCI/MSI-HOWTO.txt
> +++ b/Documentation/PCI/MSI-HOWTO.txt
> @@ -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
>
> diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst
> index b96e80f79e85..b5343c5aa224 100644
> --- a/Documentation/admin-guide/README.rst
> +++ b/Documentation/admin-guide/README.rst
> @@ -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
> ----------------------------
>
> diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
> index 6fff4024606e..a7f95d7d3a63 100644
> --- a/Documentation/doc-guide/index.rst
> +++ b/Documentation/doc-guide/index.rst
> @@ -10,7 +10,6 @@ How to write kernel documentation
> sphinx.rst
> kernel-doc.rst
> parse-headers.rst
> - docbook.rst
>
> .. only:: subproject and html
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index 731334de3efd..84e8e8a9cbdb 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -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.
> diff --git a/Documentation/fb/api.txt b/Documentation/fb/api.txt
> index d4ff7de85700..d52cf1e3b975 100644
> --- a/Documentation/fb/api.txt
> +++ b/Documentation/fb/api.txt
> @@ -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
> diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
> index 1bdb7356a310..6162d0e9dc28 100644
> --- a/Documentation/gpu/todo.rst
> +++ b/Documentation/gpu/todo.rst
> @@ -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.
>
> diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
> index 104740ea0041..c23e2c5ab80d 100644
> --- a/Documentation/kernel-doc-nano-HOWTO.txt
> +++ b/Documentation/kernel-doc-nano-HOWTO.txt
> @@ -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
> -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.
>
> @@ -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
> -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:
> @@ -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.
> */ <twaugh at redhat.com>
> diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
> index e25d63f8c0da..3aed751e0cb5 100644
> --- a/Documentation/process/changes.rst
> +++ b/Documentation/process/changes.rst
> @@ -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
> ------------------
> diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
> index 1260f60d4cb9..c6875b1db56f 100644
> --- a/Documentation/process/howto.rst
> +++ b/Documentation/process/howto.rst
> @@ -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
> ---------------------------
>
> diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
> index 05a7857a4a83..b8cac85a4001 100644
> --- a/Documentation/process/kernel-docs.rst
> +++ b/Documentation/process/kernel-docs.rst
> @@ -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
> ------------
>
> diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
> index 4511eed0fabb..8d7ed0cbbf5f 100644
> --- a/Documentation/translations/ja_JP/howto.rst
> +++ b/Documentation/translations/ja_JP/howto.rst
> @@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
> make latexdocs
> make epubdocs
>
> -現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
> -す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
> -Postscript または man ページの形式を生成するには以下のようにします - ::
> -
> - make psdocs
> - make mandocs
> -
> カーネル開発者になるには
> ------------------------
>
> diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
> index 2333697251dd..f06de9ca41a4 100644
> --- a/Documentation/translations/ko_KR/howto.rst
> +++ b/Documentation/translations/ko_KR/howto.rst
> @@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
> make latexdocs
> make epubdocs
>
> -현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
> -문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
> -Postscript 나 man page 로도 만들어질 수 있다::
> -
> - make psdocs
> - make mandocs
> -
Acked-by: SeongJae Park <sj38.park at gmail.com>
for translations/ko_KR/ part change. Looks good to me!
Thanks,
SeongJae Park
> 커널 개발자가 되는 것
> ---------------------
>
> --
> 2.9.3
>
>
More information about the dri-devel
mailing list