diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-07-17 11:17:36 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-07-17 11:17:36 -0300 |
commit | a3db9d60a118571e696b684a6e8c692a2b064941 (patch) | |
tree | ff7bae0f79b7a2ee0bce03de4f883550200c52a9 /Documentation/kernel-doc-nano-HOWTO.txt | |
parent | media: staging: cxd2099: Activate cxd2099 buffer mode (diff) | |
parent | Linux v4.13-rc1 (diff) | |
download | linux-dev-a3db9d60a118571e696b684a6e8c692a2b064941.tar.xz linux-dev-a3db9d60a118571e696b684a6e8c692a2b064941.zip |
Merge tag 'v4.13-rc1' into patchwork
Linux v4.13-rc1
* tag 'v4.13-rc1': (11136 commits)
Linux v4.13-rc1
random: reorder READ_ONCE() in get_random_uXX
random: suppress spammy warnings about unseeded randomness
replace incorrect strscpy use in FORTIFY_SOURCE
kmod: throttle kmod thread limit
kmod: add test driver to stress test the module loader
MAINTAINERS: give kmod some maintainer love
xtensa: use generic fb.h
fault-inject: add /proc/<pid>/fail-nth
fault-inject: simplify access check for fail-nth
fault-inject: make fail-nth read/write interface symmetric
fault-inject: parse as natural 1-based value for fail-nth write interface
fault-inject: automatically detect the number base for fail-nth write interface
kernel/watchdog.c: use better pr_fmt prefix
MAINTAINERS: move the befs tree to kernel.org
lib/atomic64_test.c: add a test that atomic64_inc_not_zero() returns an int
mm: fix overflow check in expand_upwards()
ubifs: Set double hash cookie also for RENAME_EXCHANGE
ubifs: Massage assert in ubifs_xattr_set() wrt. init_xattrs
ubifs: Don't leak kernel memory to the MTD
...
Diffstat (limited to 'Documentation/kernel-doc-nano-HOWTO.txt')
-rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 65 |
1 files changed, 11 insertions, 54 deletions
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@redhat.com> |