1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
|
This is a guide for commenting c-code so that it can be
used by docgen.tcl to generate html documentation.
Note that the style sheet entity.css is kept simple:
The html files should be viewable with *any* browser.
(I checked with netscape, mozilla, lynx).
- docgen.tcl parses all *.[ch] files of the source tree:
comments should look like this (see tcl-embed/tcl-embed.c):
/*: target-file.html
* <a name=this_entry class=entry>this_entry more arguments</a>
* more html markup goes here.
*/
where `target-file.html' is the file, where this entry will be added.
The class attribute is used for the style. The name attribute is used
for making a reference list at top of `target-file.html'. Just have a
look at tcl-api-reference.html which is also generated by docgen.tcl
A documentation for a gtk tag could look like this:
/*: gtk-tag-reference.html
* <a name=onbuttonpress class=entry>onbuttonpress</a>
* more html markup goes here.
*/
- gtk tags should go into the file gtk-tag-reference.html!
(other html files will refer to this, see the tag references
in tcl-api.html).
- code examples are included like this (note that it's really html,
so the '<,>'s must be escaped by the proper html entities.):
/*: gtk-tag-reference.html
* <a name=onenter class=entry>onenter</a>
* <pre class=code>
* <app default-lang="tcl">
* <window title="entry">
* <entry name = "fred" onenter = "dump"/>
* <tcl>
* namespace import ::Entity::*
* proc dump args {
* puts [get_attr entry.fred text]
* }
* </tcl>
* </window>
* </app>
* </pre>
*/
- if you write docs `by hand' and use vim, the .vimrc is set
up to convert words to references:
-- place the cursor on the word to convert (e.g. `convert')
-- hit <F6>
-- you'll get <a href=gtk-tag-reference.html#convert>convert</a>
<F6> --> reference to gtk-tag-reference
<F7> --> reference to perl-api-reference
<F8> --> reference to tcl-api-reference
|
