4 # mp_doccer - Documentation generator
6 # Copyright (C) 2001/2008 Angel Ortega <angel@triptico.com>
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 # http://www.triptico.com/software/mp_doccer.html
28 $main::VERSION
= '1.2.1';
35 # output file or directory
42 my $man_section = '3';
44 # function (and variable) documentation database
53 # prefix for generated files
56 # author's name and email
69 if (!GetOptions
('f|format=s' => \
$format,
70 'o|output=s' => \
$output,
72 't|title=s' => \
$title,
73 'v|version' => \
$version,
74 'p|prefix=s' => \
$file_prefix,
75 'm|man-section=s' => \
$man_section,
76 'a|author=s' => \
$author,
84 print "$main::VERSION\n";
88 # list of source code files
89 my @sources = sort(@ARGV) or usage
();
91 extract_doc
(@sources);
94 if ($format eq 'html') {
97 elsif ($format eq 'man') {
100 elsif ($format eq 'localhelp') {
103 elsif ($format eq 'html1') {
107 print "Invalid output format '$format'\n";
108 print "Valid ones are: html man localhelp html1\n";
112 # ###################################################################
116 # extract the documentation from the source code files
121 foreach my $f (@sources) {
122 unless (open F
, $f) {
123 warn "Can't open $_";
127 # $f=$1 if $f =~ /\/([^\/]*)$/;
129 print("Processing $f...\n");
132 my ($fname, $bdesc, @arg, @argdesc, $desc,
133 $syn, $altsyn, $uniq, @category);
137 unless (/^\s*\/\
*\
*$/) {
141 chop($_ = <F
>) or last;
143 # extract function name and brief description
144 ($fname, $bdesc) = /([\w_\.]*) - (.*)/;
148 chop($_ = <F
>) or goto eof;
150 unless (/^\s+\*\s+\@([^:]*):\s+(.*)/) {
162 # rest of lines until */ are the description
164 chop($_ = <F
>) or goto eof;
167 # a line with only [text] is a category
168 if (/^\s+\*\s+\[(.*)\]$/) {
171 my $s = $categories{$sec};
173 unless (grep /^$fname$/, @
$s) {
175 $categories{$sec} = $s;
178 push(@category, $sec);
189 # rest of info until a { or ; is the synopsis
191 chop($_ = <F
>) or goto eof;
193 if (/^\s*\/\
*\
*(.*)\
*\
//) {
194 $altsyn .= $1 . "\n";
196 elsif (/^([^{;]*)[{;]/) {
200 elsif (/^\s\/\
*\
*$/) {
208 # fix synopsis to have a trailing ;
213 # delete (posible) leading 'sub'
214 $syn =~ s/^\s*sub\s+//;
216 # calculate a unique name
217 # (to avoid collisions in file names)
218 if ($func_idx{$fname}) {
219 $uniq = $fname . $func_idx{$fname}++;
223 $func_idx{$fname} = 1;
229 $func->{'file'} = $f;
230 $func->{'func'} = $fname;
231 $func->{'bdesc'} = $bdesc;
232 $func->{'desc'} = $desc;
233 $func->{'syn'} = $syn;
234 $func->{'uniq'} = $uniq;
237 $func->{'arg'} = \
@arg;
241 $func->{'argdesc'} = \
@argdesc;
245 $func->{'altsyn'} = $altsyn;
249 $func->{'category'} = \
@category;
252 push(@functions, $func);
260 # iterate now the functions, creating the 'prev' and 'next' fields
262 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
264 $prev->{'next'} = $f->{'func'};
265 $f->{'prev'} = $prev->{'func'};
276 mp_doccer
$main::VERSION
- C Source Code Documentation Generator
277 Copyright
(C
) 2001/2008 Angel Ortega
<angel\
@triptico.com
>
278 This software is covered by the GPL license
. NO WARRANTY
.
280 Usage
: mp_doccer
[options
] c_code_files
...
284 -o
|--output
=dest Directory
or file where the
285 documentation is generated
.
286 -t
|--title
="title" Title
for the documentation
.
287 -c
|--css
="css URL" URL to a Cascade Style Sheet
288 to include
in all HTML files
.
289 -f
|--format
="format" Format
for the generated
292 html man localhelp html1
293 -p
|--prefix
="prefix" Prefix
for the name of the
294 generated files
. Main
index
295 file will also have this name
.
296 -a
|--author
="author" Sets author info
(as name
and email
)
297 to be included
in the documentation
.
298 -m
|--man
-section
="sect" Section number
for the generated
300 -v
|--version Shows version
.
301 -q
|--quiet Suppress
'built with...' info
.
304 The mp_doccer Home Page
:
305 http
://www
.triptico
.com
/software
/mp_doccer
.html
312 #######################################################
315 # create a help shell script
320 $output = 'localhelp.sh';
323 open F
, ">$output" or die "Error: $!";
327 print F
"#!/bin/sh\n\n";
328 printf F
"# Help program generated by mp_doccer $main::VERSION on %s\n",scalar(localtime());
329 print F
"# mp_doccer is part of the Minimum Profit Text Editor\n";
330 print F
"# http://www.triptico.com/software/mp.html\n\n";
332 print F
"case \"\$1\" in\n";
334 for (my $n = 0; $n < scalar(@functions); $n++) {
339 print F
"$f->{'func'})\n";
341 print F
"cat << EOF\n";
343 print F
"$title\n\n";
346 print F
"$f->{'func'} - $f->{'bdesc'}\n\n";
348 print F
"SYNOPSIS\n\n";
350 $syn = defined($f->{'altsyn'}) ?
$f->{'altsyn'} : $f->{'syn'};
351 $syn =~ s/\@([\w]+)/$1/g;
352 $syn =~ s/\%([\w]+)/$1/g;
361 $d = $f->{'argdesc'};
363 print F
"ARGUMENTS\n\n";
365 for (my $n = 0; $n < scalar(@
$a); $n++) {
366 print F
"$$a[$n] - $$d[$n]\n";
373 print F
"DESCRIPTION\n\n";
375 my ($desc) = $f->{'desc'};
376 $desc =~ s/\@([\w]+)/$1/g;
377 $desc =~ s/\%([\w]+)/$1/g;
381 if ($f->{'category'}) {
382 my $s = $f->{'category'};
384 print F
"CATEGORIES\n\n";
386 for (my $n = 0; $n < scalar(@
$s); $n++) {
396 print F
"AUTHOR\n\n";
405 print F
"\techo \"Usage: \$0 {keyword}\"\n";
409 print F
"\techo \"No help for \$1\"\n";
434 unless (-d
$output) {
435 print "$output must be a directory; aborting\n";
440 $pf = $file_prefix . '_';
443 for(my $n = 0; $n < scalar(@functions); $n++) {
449 open F
, ">$output/${pf}$f->{'func'}.$man_section" or die "Error: $!";
451 print F
".TH $f->{'func'} $man_section \"\" \"$title\"\n";
452 print F
".SH NAME\n";
453 print F
"$f->{'func'} \\- $f->{'bdesc'}\n";
454 print F
".SH SYNOPSIS\n";
457 $syn = defined($f->{'altsyn'}) ?
$f->{'altsyn'} : $f->{'syn'};
465 $d = $f->{'argdesc'};
467 print F
".SH ARGUMENTS\n";
469 for (my $n = 0; $n < scalar(@
$a); $n++) {
470 print F
".B $$a[$n] \\-\n";
477 print F
".SH DESCRIPTION\n";
479 # take the description
480 my ($desc) = $f->{'desc'};
487 if ($f->{'category'}) {
488 my ($s) = $f->{'category'};
490 print F
".SH CATEGORIES\n";
492 for (my $n = 0; $n < scalar(@
$s); $n++) {
502 print F
".SH AUTHOR\n";
518 $ret .= "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\"\n";
519 $ret .= "\"http://www.w3.org/TR/REC-html40/loose.dtd\">\n";
520 $ret .= "<head><title>$title</title>\n";
521 $ret .= "<link rel = 'StyleSheet' href = '$css' type = 'text/css'>\n" if $css;
522 $ret .= "<meta name = 'generator' content = 'mp_doccer $main::VERSION'>\n";
523 $ret .= "<meta name = 'date' content = '" . scalar(localtime()) . "'>\n";
524 $ret .= "<meta name = 'author' content = '$author'>\n" if $author;
525 $ret .= "</head>\n<body>\n";
533 my $ret = "<div class = 'footer'>\n";
536 $ret .= "<span class = 'author'>$author</span>";
540 $ret .= " - <em class = 'built_with'>Built with <a href = 'http://www.triptico.com/software/mp_doccer.html'>mp_doccer $main::VERSION</a></em>";
543 $ret .= "\n</div>\n</body>\n</html>\n";
551 my $func_link = shift;
554 $ret .= "<a name = '_TOP_'></a><h1>$title</h1>\n<div class = 'toc'>\n";
556 if (scalar(keys(%categories))) {
557 $ret .= "<h2>By Category</h2>\n";
559 foreach my $sn (sort keys %categories) {
560 $ret .= "<a name = '$sn'></a>\n";
561 $ret .= "<h3 class = 'category'>$sn</h3>\n";
563 $ret .= "<ul class = 'by_category'>\n";
566 map { " <li><a href = '" . $func_link->($_) . "'>$_</a></li>\n" }
567 sort(@
{$categories{$sn}})
574 $ret .= "<h2>By Source</h2>\n";
576 foreach my $s (@sources) {
577 my @f = grep { $_->{'file'} eq $s } @functions;
583 $ret .= "<h3 class = 'source_file'>$s</h3>\n";
585 $ret .= "<ul class = 'by_source'>\n";
588 map { " <li><a href = '" . $func_link->($_) . "'>$_</a></li>\n" }
589 sort(map { $_->{'func'} } @f)
595 $ret .= "<h2>Alphabetical</h2>\n";
596 $ret .= "<ul class = 'alphabetical'>\n";
598 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
599 $ret .= " <li><a href = '" . $func_link->($f->{'func'}) .
600 "'>$f->{'func'}</a> - $f->{'bdesc'}</li>\n";
603 $ret .= "</ul></div>\n";
615 $ret .= "\n<div class = 'func' style = 'margin-left: 1em;'>\n";
617 $ret .= "<h3>Name</h3>\n";
618 $ret .= "<strong class = 'funcname'>$f->{'func'}</strong> - $f->{'bdesc'}\n";
620 $ret .= "<h3>Synopsis</h3>\n";
622 $syn = defined($f->{'altsyn'}) ?
$f->{'altsyn'} : $f->{'syn'};
624 # synopsis decoration
625 $syn =~ s/\b$f->{'func'}\b/\<strong class = 'funcname'>$f->{'func'}\<\/strong
>/g
;
627 $syn =~ s/@([\w]+)/<em class = 'funcarg'>$1<\/em>/g
;
628 $syn =~ s/\%([\w]+)/<em class = 'funcret'>$1<\/em>/g
;
631 foreach my $a (@
{$f->{'arg'}}) {
632 $syn =~ s/\b$a\b/\<em class = 'funcarg'>$a\<\/em>/g
;
636 $ret .= "<pre class = 'funcsyn'>\n$syn</pre>\n";
639 my @a = @
{$f->{'arg'}};
640 my @d = @
{$f->{'argdesc'}};
642 $ret .= "<h3>Arguments</h3>\n";
643 $ret .= "<dl class = 'arguments'>\n";
646 $ret .= " <dt><em class = 'funcarg'>" . shift(@a) . "</em></dt>";
647 $ret .= "<dd>" . shift(@d) . "</dd>\n";
654 $ret .= "<h3>Description</h3>\n";
656 # take the description
657 my ($desc) = $f->{'desc'};
659 # decorate function names
660 $desc =~ s/([\w_]+\(\))/<code class = 'funcname'>$1<\/code>/g
;
662 # decorate function arguments
663 $desc =~ s/@([\w_]+)/<em class = 'funcarg'>$1<\/em>/g
;
665 # decorate return values
666 $desc =~ s/\%([\w_]+)/<em class = 'funcret'>$1<\/em>/g
;
668 # replace blank lines
669 $desc =~ s/\n\n/\n<p>\n/gs;
671 $ret .= "<p class = 'description'>$desc</p>\n";
673 if ($f->{category
}) {
674 $ret .= "<h3>Categories</h3>\n";
676 $ret .= "<ul class = 'categories'>\n" .
677 join('', map { " <li><a href = '#$_'>$_</a></li>\n" } @
{$f->{'category'}}) .
692 $file_prefix = '_' . $file_prefix;
696 my $fn = $output . $file_prefix . '.html';
698 open F
, ">$fn" or die "Error create $fn: $!";
700 print F html_header
($title);
702 print F html_toc
( sub { "#" . shift } );
704 # the functions themselves
705 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
706 # avoid duplicate function names
707 if ($f{$f->{'func'}}) {
713 print F
"\n<div class = 'func_container'>\n";
714 print F
"<a name = '$f->{'func'}'></a>\n";
715 print F
"<h2 style = 'border-bottom: solid 2px;'>$f->{'func'}</h2>\n";
717 print F html_func
($f);
722 print F html_footer
();
729 # create multipage html documents
731 $output = "." unless $output;
734 unless (-d
$output) {
735 print "$output must be a directory; aborting\n";
739 my $pf = $file_prefix ?
$file_prefix . '_' : '';
741 # create the table of contents
742 my $top = $file_prefix || 'index';
744 open TOC
, ">$output/${top}.html"
747 print TOC html_header
($title);
749 print TOC html_toc
( sub { $pf . shift() . ".html" } );
751 print TOC html_footer
();
755 # the functions themselves
756 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
758 open F
, ">$output/" . $pf . "$f->{'func'}.html"
761 print F html_header
($f->{'func'});
763 print F
"<div class = 'topnav'>\n";
765 print F
' ', $f->{'prev'} ?
"<a href = '${pf}$f->{'prev'}.html'>Prev</a>" : "Prev",
767 " <a href = '${top}.html'><b>$title</b></a>",
769 ' ', $f->{'next'} ?
"<a href = '${pf}$f->{'next'}.html'>Next</a>" : "Next",
774 print F
"<h2 style = 'border-bottom: solid 2px;'>$f->{'func'}</h2>\n";
776 print F html_func
($f);
778 print F html_footer
();