Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/kernel-doc-nano-HOWTO.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 4435 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 4435 byte(s)
Tag kernel26-2.6.12-alx-r9
1 | kernel-doc nano-HOWTO |
2 | ===================== |
3 | |
4 | Many places in the source tree have extractable documentation in the |
5 | form of block comments above functions. The components of this system |
6 | are: |
7 | |
8 | - scripts/kernel-doc |
9 | |
10 | This is a perl script that hunts for the block comments and can mark |
11 | them up directly into DocBook, man, text, and HTML. (No, not |
12 | texinfo.) |
13 | |
14 | - Documentation/DocBook/*.tmpl |
15 | |
16 | These are SGML template files, which are normal SGML files with |
17 | special place-holders for where the extracted documentation should |
18 | go. |
19 | |
20 | - scripts/docproc.c |
21 | |
22 | This is a program for converting SGML template files into SGML |
23 | files. When a file is referenced it is searched for symbols |
24 | exported (EXPORT_SYMBOL), to be able to distinguish between internal |
25 | and external functions. |
26 | It invokes kernel-doc, giving it the list of functions that |
27 | are to be documented. |
28 | Additionally it is used to scan the SGML template files to locate |
29 | all the files referenced herein. This is used to generate dependency |
30 | information as used by make. |
31 | |
32 | - Makefile |
33 | |
34 | The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used |
35 | to build DocBook files, PostScript files, PDF files, and html files |
36 | in Documentation/DocBook. |
37 | |
38 | - Documentation/DocBook/Makefile |
39 | |
40 | This is where C files are associated with SGML templates. |
41 | |
42 | |
43 | How to extract the documentation |
44 | -------------------------------- |
45 | |
46 | If you just want to read the ready-made books on the various |
47 | subsystems (see Documentation/DocBook/*.tmpl), just type 'make |
48 | psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your |
49 | preference. If you would rather read a different format, you can type |
50 | 'make sgmldocs' and then use DocBook tools to convert |
51 | Documentation/DocBook/*.sgml to a format of your choice (for example, |
52 | 'db2html ...' if 'make htmldocs' was not defined). |
53 | |
54 | If you want to see man pages instead, you can do this: |
55 | |
56 | $ cd linux |
57 | $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man |
58 | $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man |
59 | |
60 | Here is split-man.pl: |
61 | |
62 | --> |
63 | #!/usr/bin/perl |
64 | |
65 | if ($#ARGV < 0) { |
66 | die "where do I put the results?\n"; |
67 | } |
68 | |
69 | mkdir $ARGV[0],0777; |
70 | $state = 0; |
71 | while (<STDIN>) { |
72 | if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) { |
73 | if ($state == 1) { close OUT } |
74 | $state = 1; |
75 | $fn = "$ARGV[0]/$1.4"; |
76 | print STDERR "Creating $fn\n"; |
77 | open OUT, ">$fn" or die "can't open $fn: $!\n"; |
78 | print OUT $_; |
79 | } elsif ($state != 0) { |
80 | print OUT $_; |
81 | } |
82 | } |
83 | |
84 | close OUT; |
85 | <-- |
86 | |
87 | If you just want to view the documentation for one function in one |
88 | file, you can do this: |
89 | |
90 | $ scripts/kernel-doc -man -function fn file | nroff -man | less |
91 | |
92 | or this: |
93 | |
94 | $ scripts/kernel-doc -text -function fn file |
95 | |
96 | |
97 | How to add extractable documentation to your source files |
98 | --------------------------------------------------------- |
99 | |
100 | The format of the block comment is like this: |
101 | |
102 | /** |
103 | * function_name(:)? (- short description)? |
104 | (* @parameterx: (description of parameter x)?)* |
105 | (* a blank line)? |
106 | * (Description:)? (Description of function)? |
107 | * (section header: (section description)? )* |
108 | (*)?*/ |
109 | |
110 | The short function description cannot be multiline, but the other |
111 | descriptions can be (and they can contain blank lines). Avoid putting a |
112 | spurious blank line after the function name, or else the description will |
113 | be repeated! |
114 | |
115 | All descriptive text is further processed, scanning for the following special |
116 | patterns, which are highlighted appropriately. |
117 | |
118 | 'funcname()' - function |
119 | '$ENVVAR' - environment variable |
120 | '&struct_name' - name of a structure (up to two words including 'struct') |
121 | '@parameter' - name of a parameter |
122 | '%CONST' - name of a constant. |
123 | |
124 | Take a look around the source tree for examples. |
125 | |
126 | |
127 | How to make new SGML template files |
128 | ----------------------------------- |
129 | |
130 | SGML template files (*.tmpl) are like normal SGML files, except that |
131 | they can contain escape sequences where extracted documentation should |
132 | be inserted. |
133 | |
134 | !E<filename> is replaced by the documentation, in <filename>, for |
135 | functions that are exported using EXPORT_SYMBOL: the function list is |
136 | collected from files listed in Documentation/DocBook/Makefile. |
137 | |
138 | !I<filename> is replaced by the documentation for functions that are |
139 | _not_ exported using EXPORT_SYMBOL. |
140 | |
141 | !D<filename> is used to name additional files to search for functions |
142 | exported using EXPORT_SYMBOL. |
143 | |
144 | !F<filename> <function [functions...]> is replaced by the |
145 | documentation, in <filename>, for the functions listed. |
146 | |
147 | |
148 | Tim. |
149 | */ <twaugh@redhat.com> |
150 |