4 # cdoc - generate man pages for C code
5 # Copyright (C) 2000 Bibliotech Ltd., Unit 2-3, 50 Carnwath Road,
6 # London, SW6 3EG, United Kingdom.
8 # This program is free software; you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation; either version 2 of the License, or
11 # (at your option) any later version.
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
18 # You should have received a copy of the GNU General Public License
19 # along with this program; if not, write to the Free Software
20 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 # $Id: cdoc,v 1.4 2001/02/16 17:02:15 rich Exp $
28 my $date = `date +'%B %d, %Y'`;
29 $date =~ s/[\r\n]+$//;
35 while ($arg = shift @ARGV)
37 my ($type, $header_file);
39 if ($arg eq "--help" || $arg eq "-?" || $arg eq "-h")
42 "cdoc [--options ...] files ...\n",
44 " --author \"Author name\" Details for the AUTHOR section\n",
45 " --version package-version Details for the VERSION section\n",
46 " --license \"License data\" Details for the LICENSE section\n";
49 elsif ($arg eq "--author")
51 $author = shift @ARGV;
54 elsif ($arg eq "--version")
56 $version = shift @ARGV;
59 elsif ($arg eq "--license")
61 $license = shift @ARGV;
64 elsif ($arg =~ /(.*)\.h$/)
67 $type = "header file";
70 or die "$arg: cannot open file: $!";
74 print STDERR "$arg: unknown file type: assuming it's a header file";
82 # Look for intro line.
83 if (m(^\s*/\*\s*(Function|Variable):\s*(.*?)\s+-\s+(.*))o)
89 push @functions, { name => $manpage };
96 my $section = \$description;
98 # Read the rest of the comment block.
102 s/^\s*\*\s*//; # Remove leading " * ".
104 last if m(^/)o; # End of comment block?
106 if (m(^(Function|Variable):\s*(.*))o)
108 push @functions, { name => $2 };
110 elsif (m(^Bugs:\s*(.*))o)
113 $$section .= $1 . " ";
115 elsif (m(^History:\s*(.*))o)
117 $section = \$history;
118 $$section .= $1 . " ";
120 elsif (m(^See also:\s*(.*))o)
122 $section = \$see_also;
123 $$section .= $1 . " ";
125 elsif (m(^Returns:\s*(.*))o)
127 $section = \$returns;
128 $$section .= $1 . " ";
141 # Mark up the sections.
142 $description = mark_up ($description);
143 $bugs = mark_up ($bugs);
144 $history = mark_up ($history);
145 $see_also = mark_up ($see_also);
146 $returns = mark_up ($returns);
148 # Read the functions which should follow, one per line, in order.
150 foreach $fn (@functions)
154 if (!$_ || !m($fn->{name}))
156 print STDERR "$arg: could not find prototype of variable/function: $fn->{name}\n";
162 $fn->{prototype} = $_;
165 # Now we're in a situation to produce the manual page.
166 print "cdoc: creating $manpage.3\n";
168 open MANPAGE, ">$manpage.3"
169 or die "$manpage.3: cannot open file: $!";
171 my $names = join ", ", map { $_->{name} } @functions;
174 ".TH $manpage 3 \"$date\" \"GNU\" \"Programmer's Manual\"\n",
176 "$names \\- $name_text\n",
179 ".B #include <$header_file.h>\n",
184 print MANPAGE ".BI \"$_->{prototype}\"\n";
192 print MANPAGE ".SH RETURNS\n$returns\n" if $returns;
193 print MANPAGE ".SH BUGS\n$bugs\n" if $bugs;
194 print MANPAGE ".SH AUTHOR\n$author\n" if $author;
195 print MANPAGE ".SH LICENSE\n$license\n" if $license;
196 print MANPAGE ".SH VERSION\n$version\n" if $version;
197 print MANPAGE ".SH HISTORY\n$history\n" if $history;
198 print MANPAGE ".SH SEE ALSO\n$see_also\n" if $see_also;
202 # Links for other pages.
203 my @other_pages = @functions;
206 foreach $fn (@other_pages)
208 print "cdoc: creating $fn->{name}.3\n";
210 open MANPAGE, ">$fn->{name}.3"
211 or die "$fn->{name}.3: cannot open file: $!";
214 ".so man3/$manpage.3\n";
231 s/\@code{(.*?)}/\\fB$1\\fP/ogs;
232 s/\@ref{(.*?)}/\\fB$1\\fP/ogs; # Should be able to handle this better. XXX