Commit ff41c419 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

docs: update old references for DocBook from the documentation

DocBook is mentioned several times at the documentation. Update
the obsolete references from it at the DocBook.
Acked-by: default avatarSeongJae Park <sj38.park@gmail.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent cb43fb57
...@@ -186,7 +186,7 @@ must disable interrupts while the lock is held. If the device sends ...@@ -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 a different interrupt, the driver will deadlock trying to recursively
acquire the spinlock. Such deadlocks can be avoided by using acquire the spinlock. Such deadlocks can be avoided by using
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts 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 4.5 How to tell whether MSI/MSI-X is enabled on a device
......
...@@ -55,12 +55,6 @@ Documentation ...@@ -55,12 +55,6 @@ Documentation
contains information about the problems, which may result by upgrading contains information about the problems, which may result by upgrading
your kernel. 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 Installing the kernel source
---------------------------- ----------------------------
......
...@@ -10,7 +10,6 @@ How to write kernel documentation ...@@ -10,7 +10,6 @@ How to write kernel documentation
sphinx.rst sphinx.rst
kernel-doc.rst kernel-doc.rst
parse-headers.rst parse-headers.rst
docbook.rst
.. only:: subproject and html .. only:: subproject and html
......
...@@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The ...@@ -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 kernel-doc comments have some special structure and formatting, but beyond that
they are also treated as reStructuredText. 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 Finally, there are thousands of plain text documentation files scattered around
``Documentation``. Some of these will likely be converted to reStructuredText ``Documentation``. Some of these will likely be converted to reStructuredText
over time, but the bulk of them will remain in plain text. over time, but the bulk of them will remain in plain text.
......
...@@ -289,12 +289,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field. ...@@ -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 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 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 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. 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 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 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. 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 For forward compatibility reasons applications must zero those fields, and
......
...@@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The ...@@ -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 task would be to clean up interfaces like moving functions around between
files to better group them and improving the interfaces like dropping return files to better group them and improving the interfaces like dropping return
values for functions that never fail. Then write kerneldoc for all exported 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. See https://dri.freedesktop.org/docs/drm/ for what's there already.
......
...@@ -17,8 +17,8 @@ The format for this documentation is called the kernel-doc format. ...@@ -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. It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
This style embeds the documentation within the source files, using This style embeds the documentation within the source files, using
a few simple conventions. The scripts/kernel-doc perl script, some a few simple conventions. The scripts/kernel-doc perl script, the
SGML templates in Documentation/DocBook, and other tools understand Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
these conventions, and are used to extract this embedded documentation these conventions, and are used to extract this embedded documentation
into various documents. into various documents.
...@@ -122,15 +122,9 @@ are: ...@@ -122,15 +122,9 @@ are:
- scripts/kernel-doc - scripts/kernel-doc
This is a perl script that hunts for the block comments and can mark 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.) 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 - scripts/docproc.c
This is a program for converting SGML template files into SGML This is a program for converting SGML template files into SGML
...@@ -145,25 +139,18 @@ are: ...@@ -145,25 +139,18 @@ are:
- Makefile - Makefile
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
to build XML DocBook files, PostScript files, PDF files, and html files are used to build XML DocBook files, LaTeX files, PDF files,
in Documentation/DocBook. The older target 'sgmldocs' is equivalent ePub files and html files in Documentation/.
to 'xmldocs'.
- Documentation/DocBook/Makefile
This is where C files are associated with SGML templates.
How to extract the documentation How to extract the documentation
-------------------------------- --------------------------------
If you just want to read the ready-made books on the various If you just want to read the ready-made books on the various
subsystems (see Documentation/DocBook/*.tmpl), just type 'make subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your depending on your preference. If you would rather read a different format,
preference. If you would rather read a different format, you can type you can type 'make xmldocs' and then use DocBook tools to convert
'make xmldocs' and then use DocBook tools to convert Documentation/output/*.xml to a format of your choice (for example,
Documentation/DocBook/*.xml to a format of your choice (for example,
'db2html ...' if 'make htmldocs' was not defined). 'db2html ...' if 'make htmldocs' was not defined).
If you want to see man pages instead, you can do this: 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.: ...@@ -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). * hardware, software, or its subject(s).
*/ */
DOC: sections are used in SGML templates files as indicated below. DOC: sections are used in ReST files.
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.
Tim. Tim.
*/ <twaugh@redhat.com> */ <twaugh@redhat.com>
...@@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev ...@@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
Linux documentation for functions is transitioning to inline Linux documentation for functions is transitioning to inline
documentation via specially-formatted comments near their documentation via specially-formatted comments near their
definitions in the source. These comments can be combined with the definitions in the source. These comments can be combined with ReST
SGML templates in the Documentation/DocBook directory to make DocBook files the Documentation/ directory to make enriched documentation, which can
files, which can then be converted by DocBook stylesheets to PostScript, then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
HTML, PDF files, and several other formats. In order to convert from In order to convert from ReST format to a format of your choice, you'll need
DocBook format to a format of your choice, you'll need to install Jade as Sphinx.
well as the desired DocBook stylesheets.
Util-linux Util-linux
---------- ----------
...@@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.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 functionalities required for ``XeLaTex`` to work. For PDF output you'll also
need ``convert(1)`` from ImageMagick (https://www.imagemagick.org). 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 Getting updated software
======================== ========================
...@@ -409,15 +402,6 @@ Quota-tools ...@@ -409,15 +402,6 @@ Quota-tools
- <http://sourceforge.net/projects/linuxquota/> - <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 Intel P6 microcode
------------------ ------------------
......
...@@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with:: ...@@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
make latexdocs make latexdocs
make epubdocs 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 Becoming A Kernel Developer
--------------------------- ---------------------------
......
...@@ -40,50 +40,18 @@ Enjoy! ...@@ -40,50 +40,18 @@ Enjoy!
Docs at the Linux Kernel tree 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}``. The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
* Name: **linux/Documentation** * Name: **linux/Documentation**
:Author: Many. :Author: Many.
:Location: Documentation/ :Location: Documentation/
:Keywords: text files, Sphinx, DocBook. :Keywords: text files, Sphinx.
:Description: Documentation that comes with the kernel sources, :Description: Documentation that comes with the kernel sources,
inside the Documentation directory. Some pages from this document inside the Documentation directory. Some pages from this document
(including this document itself) have been moved there, and might (including this document itself) have been moved there, and might
be more up to date than the web version. 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 On-line docs
------------ ------------
......
...@@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに ...@@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
make latexdocs make latexdocs
make epubdocs make epubdocs
現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
Postscript または man ページの形式を生成するには以下のようにします - ::
make psdocs
make mandocs
カーネル開発者になるには カーネル開発者になるには
------------------------ ------------------------
......
...@@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된 ...@@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
make latexdocs make latexdocs
make epubdocs make epubdocs
현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
Postscript 나 man page 로도 만들어질 수 있다::
make psdocs
make mandocs
커널 개발자가 되는 것 커널 개발자가 되는 것
--------------------- ---------------------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment