]>
Commit | Line | Data |
---|---|---|
1dc4bbf0 MCC |
1 | DocBook XML [DEPRECATED] |
2 | ======================== | |
3 | ||
4 | .. attention:: | |
5 | ||
6 | This section describes the deprecated DocBook XML toolchain. Please do not | |
7 | create new DocBook XML template files. Please consider converting existing | |
8 | DocBook XML templates files to Sphinx/reStructuredText. | |
9 | ||
10 | Converting DocBook to Sphinx | |
11 | ---------------------------- | |
12 | ||
13 | Over time, we expect all of the documents under ``Documentation/DocBook`` to be | |
14 | converted to Sphinx and reStructuredText. For most DocBook XML documents, a good | |
15 | enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script, | |
16 | which uses ``pandoc`` under the hood. For example:: | |
17 | ||
18 | $ cd Documentation/sphinx | |
19 | $ ./tmplcvt ../DocBook/in.tmpl ../out.rst | |
20 | ||
21 | Then edit the resulting rst files to fix any remaining issues, and add the | |
22 | document in the ``toctree`` in ``Documentation/index.rst``. | |
23 | ||
24 | Components of the kernel-doc system | |
25 | ----------------------------------- | |
26 | ||
27 | Many places in the source tree have extractable documentation in the form of | |
28 | block comments above functions. The components of this system are: | |
29 | ||
30 | - ``scripts/kernel-doc`` | |
31 | ||
32 | This is a perl script that hunts for the block comments and can mark them up | |
33 | directly into reStructuredText, DocBook, man, text, and HTML. (No, not | |
34 | texinfo.) | |
35 | ||
36 | - ``Documentation/DocBook/*.tmpl`` | |
37 | ||
38 | These are XML template files, which are normal XML files with special | |
39 | place-holders for where the extracted documentation should go. | |
40 | ||
41 | - ``scripts/docproc.c`` | |
42 | ||
43 | This is a program for converting XML template files into XML files. When a | |
44 | file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be | |
45 | able to distinguish between internal and external functions. | |
46 | ||
47 | It invokes kernel-doc, giving it the list of functions that are to be | |
48 | documented. | |
49 | ||
50 | Additionally it is used to scan the XML template files to locate all the files | |
51 | referenced herein. This is used to generate dependency information as used by | |
52 | make. | |
53 | ||
54 | - ``Makefile`` | |
55 | ||
56 | The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build | |
57 | DocBook XML files, PostScript files, PDF files, and html files in | |
58 | Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'. | |
59 | ||
60 | - ``Documentation/DocBook/Makefile`` | |
61 | ||
62 | This is where C files are associated with SGML templates. | |
63 | ||
64 | How to use kernel-doc comments in DocBook XML template files | |
65 | ------------------------------------------------------------ | |
66 | ||
67 | DocBook XML template files (\*.tmpl) are like normal XML files, except that they | |
68 | can contain escape sequences where extracted documentation should be inserted. | |
69 | ||
70 | ``!E<filename>`` is replaced by the documentation, in ``<filename>``, for | |
71 | functions that are exported using ``EXPORT_SYMBOL``: the function list is | |
72 | collected from files listed in ``Documentation/DocBook/Makefile``. | |
73 | ||
74 | ``!I<filename>`` is replaced by the documentation for functions that are **not** | |
75 | exported using ``EXPORT_SYMBOL``. | |
76 | ||
77 | ``!D<filename>`` is used to name additional files to search for functions | |
78 | exported using ``EXPORT_SYMBOL``. | |
79 | ||
80 | ``!F<filename> <function [functions...]>`` is replaced by the documentation, in | |
81 | ``<filename>``, for the functions listed. | |
82 | ||
83 | ``!P<filename> <section title>`` is replaced by the contents of the ``DOC:`` | |
84 | section titled ``<section title>`` from ``<filename>``. Spaces are allowed in | |
85 | ``<section title>``; do not quote the ``<section title>``. | |
86 | ||
87 | ``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC: | |
88 | sections and documented functions, symbols, etc. are used. This makes sense to | |
89 | use when you use ``!F`` or ``!P`` only and want to verify that all documentation | |
90 | is included. |