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.2-dev';
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') {
106 elsif ($format eq 'grutatxt') {
110 print "Invalid output format '$format'\n";
111 print "Valid ones are: html man localhelp html1 grutatxt\n";
115 # ###################################################################
119 # extract the documentation from the source code files
124 foreach my $f (@sources) {
125 unless (open F
, $f) {
126 warn "Can't open $_";
130 # $f=$1 if $f =~ /\/([^\/]*)$/;
132 print("Processing $f...\n");
135 my ($fname, $bdesc, @arg, @argdesc, $desc,
136 $syn, $altsyn, $uniq, @category);
140 unless (/^\s*\/\
*\
*$/) {
144 chop($_ = <F
>) or last;
146 # extract function name and brief description
147 ($fname, $bdesc) = /([\w_\.]*) - (.*)/;
151 chop($_ = <F
>) or goto eof;
153 unless (/^\s+\*\s+\@([^:]*):\s+(.*)/) {
165 # rest of lines until */ are the description
167 chop($_ = <F
>) or goto eof;
170 # a line with only [text] is a category
171 if (/^\s+\*\s+\[(.*)\]$/) {
174 my $s = $categories{$sec};
176 unless (grep /^$fname$/, @
$s) {
178 $categories{$sec} = $s;
181 push(@category, $sec);
192 # rest of info until a { or ; is the synopsis
194 chop($_ = <F
>) or goto eof;
196 if (/^\s*\/\
*\
*(.*)\
*\
//) {
197 $altsyn .= $1 . "\n";
199 elsif (/^([^{;]*)[{;]/) {
203 elsif (/^\s\/\
*\
*$/) {
211 # fix synopsis to have a trailing ;
216 # delete (posible) leading 'sub'
217 $syn =~ s/^\s*sub\s+//;
219 # calculate a unique name
220 # (to avoid collisions in file names)
221 if ($func_idx{$fname}) {
222 $uniq = $fname . $func_idx{$fname}++;
226 $func_idx{$fname} = 1;
232 $func->{'file'} = $f;
233 $func->{'func'} = $fname;
234 $func->{'bdesc'} = $bdesc;
235 $func->{'desc'} = $desc;
236 $func->{'syn'} = $syn;
237 $func->{'uniq'} = $uniq;
240 $func->{'arg'} = \
@arg;
244 $func->{'argdesc'} = \
@argdesc;
248 $func->{'altsyn'} = $altsyn;
252 $func->{'category'} = \
@category;
255 push(@functions, $func);
263 # iterate now the functions, creating the 'prev' and 'next' fields
265 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
267 $prev->{'next'} = $f->{'func'};
268 $f->{'prev'} = $prev->{'func'};
279 mp_doccer
$main::VERSION
- C Source Code Documentation Generator
280 Copyright
(C
) 2001/2008 Angel Ortega
<angel\
@triptico.com
>
281 This software is covered by the GPL license
. NO WARRANTY
.
283 Usage
: mp_doccer
[options
] c_code_files
...
287 -o
|--output
=dest Directory
or file where the
288 documentation is generated
.
289 -t
|--title
="title" Title
for the documentation
.
290 -c
|--css
="css URL" URL to a Cascade Style Sheet
291 to include
in all HTML files
.
292 -f
|--format
="format" Format
for the generated
295 html man localhelp html1
296 -p
|--prefix
="prefix" Prefix
for the name of the
297 generated files
. Main
index
298 file will also have this name
.
299 -a
|--author
="author" Sets author info
(as name
and email
)
300 to be included
in the documentation
.
301 -m
|--man
-section
="sect" Section number
for the generated
303 -v
|--version Shows version
.
304 -q
|--quiet Suppress
'built with...' info
.
307 The mp_doccer Home Page
:
308 http
://www
.triptico
.com
/software
/mp_doccer
.html
315 #######################################################
318 # create a help shell script
323 $output = 'localhelp.sh';
326 open F
, ">$output" or die "Error: $!";
330 print F
"#!/bin/sh\n\n";
331 printf F
"# Help program generated by mp_doccer $main::VERSION on %s\n",scalar(localtime());
332 print F
"# mp_doccer is part of the Minimum Profit Text Editor\n";
333 print F
"# http://www.triptico.com/software/mp.html\n\n";
335 print F
"case \"\$1\" in\n";
337 for (my $n = 0; $n < scalar(@functions); $n++) {
342 print F
"$f->{'func'})\n";
344 print F
"cat << EOF\n";
346 print F
"$title\n\n";
349 print F
"$f->{'func'} - $f->{'bdesc'}\n\n";
351 print F
"SYNOPSIS\n\n";
353 $syn = defined($f->{'altsyn'}) ?
$f->{'altsyn'} : $f->{'syn'};
354 $syn =~ s/\@([\w]+)/$1/g;
355 $syn =~ s/\%([\w]+)/$1/g;
364 $d = $f->{'argdesc'};
366 print F
"ARGUMENTS\n\n";
368 for (my $n = 0; $n < scalar(@
$a); $n++) {
369 print F
"$$a[$n] - $$d[$n]\n";
376 print F
"DESCRIPTION\n\n";
378 my ($desc) = $f->{'desc'};
379 $desc =~ s/\@([\w]+)/$1/g;
380 $desc =~ s/\%([\w]+)/$1/g;
384 if ($f->{'category'}) {
385 my $s = $f->{'category'};
387 print F
"CATEGORIES\n\n";
389 for (my $n = 0; $n < scalar(@
$s); $n++) {
399 print F
"AUTHOR\n\n";
408 print F
"\techo \"Usage: \$0 {keyword}\"\n";
412 print F
"\techo \"No help for \$1\"\n";
437 unless (-d
$output) {
438 print "$output must be a directory; aborting\n";
443 $pf = $file_prefix . '_';
446 for(my $n = 0; $n < scalar(@functions); $n++) {
452 open F
, ">$output/${pf}$f->{'func'}.$man_section" or die "Error: $!";
454 print F
".TH $f->{'func'} $man_section \"\" \"$title\"\n";
455 print F
".SH NAME\n";
456 print F
"$f->{'func'} \\- $f->{'bdesc'}\n";
457 print F
".SH SYNOPSIS\n";
460 $syn = defined($f->{'altsyn'}) ?
$f->{'altsyn'} : $f->{'syn'};
468 $d = $f->{'argdesc'};
470 print F
".SH ARGUMENTS\n";
472 for (my $n = 0; $n < scalar(@
$a); $n++) {
473 print F
".B $$a[$n] \\-\n";
480 print F
".SH DESCRIPTION\n";
482 # take the description
483 my ($desc) = $f->{'desc'};
490 if ($f->{'category'}) {
491 my ($s) = $f->{'category'};
493 print F
".SH CATEGORIES\n";
495 for (my $n = 0; $n < scalar(@
$s); $n++) {
505 print F
".SH AUTHOR\n";
521 $ret .= "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\"\n";
522 $ret .= "\"http://www.w3.org/TR/REC-html40/loose.dtd\">\n";
523 $ret .= "<head><title>$title</title>\n";
524 $ret .= "<link rel = 'StyleSheet' href = '$css' type = 'text/css'>\n" if $css;
525 $ret .= "<meta name = 'generator' content = 'mp_doccer $main::VERSION'>\n";
526 $ret .= "<meta name = 'date' content = '" . scalar(localtime()) . "'>\n";
527 $ret .= "<meta name = 'author' content = '$author'>\n" if $author;
528 $ret .= "</head>\n<body>\n";
536 my $ret = "<div class = 'footer'>\n";
539 $ret .= "<span class = 'author'>$author</span>";
543 $ret .= " - <em class = 'built_with'>Built with <a href = 'http://www.triptico.com/software/mp_doccer.html'>mp_doccer $main::VERSION</a></em>";
546 $ret .= "\n</div>\n</body>\n</html>\n";
554 my $func_link = shift;
557 $ret .= "<a name = '_TOP_'></a><h1>$title</h1>\n<div class = 'toc'>\n";
559 if (scalar(keys(%categories))) {
560 $ret .= "<h2>By Category</h2>\n";
562 foreach my $sn (sort keys %categories) {
563 $ret .= "<a name = '$sn'></a>\n";
564 $ret .= "<h3 class = 'category'>$sn</h3>\n";
566 $ret .= "<ul class = 'by_category'>\n";
569 map { " <li><a href = '" . $func_link->($_) . "'>$_</a></li>\n" }
570 sort(@
{$categories{$sn}})
577 $ret .= "<h2>By Source</h2>\n";
579 foreach my $s (@sources) {
580 my @f = grep { $_->{'file'} eq $s } @functions;
586 $ret .= "<h3 class = 'source_file'>$s</h3>\n";
588 $ret .= "<ul class = 'by_source'>\n";
591 map { " <li><a href = '" . $func_link->($_) . "'>$_</a></li>\n" }
592 sort(map { $_->{'func'} } @f)
598 $ret .= "<h2>Alphabetical</h2>\n";
599 $ret .= "<ul class = 'alphabetical'>\n";
601 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
602 $ret .= " <li><a href = '" . $func_link->($f->{'func'}) .
603 "'>$f->{'func'}</a> - $f->{'bdesc'}</li>\n";
606 $ret .= "</ul></div>\n";
618 $ret .= "\n<div class = 'func' style = 'margin-left: 1em;'>\n";
620 $ret .= "<h3>Name</h3>\n";
621 $ret .= "<strong class = 'funcname'>$f->{'func'}</strong> - $f->{'bdesc'}\n";
623 $ret .= "<h3>Synopsis</h3>\n";
625 $syn = defined($f->{'altsyn'}) ?
$f->{'altsyn'} : $f->{'syn'};
627 # synopsis decoration
628 $syn =~ s/\b$f->{'func'}\b/\<strong class = 'funcname'>$f->{'func'}\<\/strong
>/g
;
630 $syn =~ s/@([\w]+)/<em class = 'funcarg'>$1<\/em>/g
;
631 $syn =~ s/\%([\w]+)/<em class = 'funcret'>$1<\/em>/g
;
634 foreach my $a (@
{$f->{'arg'}}) {
635 $syn =~ s/\b$a\b/\<em class = 'funcarg'>$a\<\/em>/g
;
639 $ret .= "<pre class = 'funcsyn'>\n$syn</pre>\n";
642 my @a = @
{$f->{'arg'}};
643 my @d = @
{$f->{'argdesc'}};
645 $ret .= "<h3>Arguments</h3>\n";
646 $ret .= "<dl class = 'arguments'>\n";
649 $ret .= " <dt><em class = 'funcarg'>" . shift(@a) . "</em></dt>";
650 $ret .= "<dd>" . shift(@d) . "</dd>\n";
657 $ret .= "<h3>Description</h3>\n";
659 # take the description
660 my ($desc) = $f->{'desc'};
662 # decorate function names
663 $desc =~ s/([\w_]+\(\))/<code class = 'funcname'>$1<\/code>/g
;
665 # decorate function arguments
666 $desc =~ s/@([\w_]+)/<em class = 'funcarg'>$1<\/em>/g
;
668 # decorate return values
669 $desc =~ s/\%([\w_]+)/<em class = 'funcret'>$1<\/em>/g
;
671 # replace blank lines
672 $desc =~ s/\n\n/\n<p>\n/gs;
674 $ret .= "<p class = 'description'>$desc</p>\n";
676 if ($f->{category
}) {
677 $ret .= "<h3>Categories</h3>\n";
679 $ret .= "<ul class = 'categories'>\n" .
680 join('', map { " <li><a href = '#$_'>$_</a></li>\n" } @
{$f->{'category'}}) .
695 $file_prefix = '_' . $file_prefix;
699 my $fn = $output . $file_prefix . '.html';
701 open F
, ">$fn" or die "Error create $fn: $!";
703 print F html_header
($title);
705 print F html_toc
( sub { "#" . shift } );
707 # the functions themselves
708 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
709 # avoid duplicate function names
710 if ($f{$f->{'func'}}) {
716 print F
"\n<div class = 'func_container'>\n";
717 print F
"<a name = '$f->{'func'}'></a>\n";
718 print F
"<h2 style = 'border-bottom: solid 2px;'>$f->{'func'}</h2>\n";
720 print F html_func
($f);
725 print F html_footer
();
732 # create multipage html documents
734 $output = "." unless $output;
737 unless (-d
$output) {
738 print "$output must be a directory; aborting\n";
742 my $pf = $file_prefix ?
$file_prefix . '_' : '';
744 # create the table of contents
745 my $top = $file_prefix || 'index';
747 open TOC
, ">$output/${top}.html"
750 print TOC html_header
($title);
752 print TOC html_toc
( sub { $pf . shift() . ".html" } );
754 print TOC html_footer
();
758 # the functions themselves
759 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
761 open F
, ">$output/" . $pf . "$f->{'func'}.html"
764 print F html_header
($f->{'func'});
766 print F
"<div class = 'topnav'>\n";
768 print F
' ', $f->{'prev'} ?
"<a href = '${pf}$f->{'prev'}.html'>Prev</a>" : "Prev",
770 " <a href = '${top}.html'><b>$title</b></a>",
772 ' ', $f->{'next'} ?
"<a href = '${pf}$f->{'next'}.html'>Next</a>" : "Next",
777 print F
"<h2 style = 'border-bottom: solid 2px;'>$f->{'func'}</h2>\n";
779 print F html_func
($f);
781 print F html_footer
();
796 return $t . "\n" . $s . "\n\n";
812 # create a grutatxt document
817 $file_prefix = '_' . $file_prefix;
821 my $fn = $output . $file_prefix . '.txt';
823 open F
, ">$fn" or die "Error create $fn: $!";
825 print F _grutatxt_header
($title, "=");
827 if (scalar(keys(%categories))) {
829 print F _grutatxt_header
('By Category', '-');
831 foreach my $sn (sort keys %categories) {
833 print F _grutatxt_header
($sn, '~');
836 map { ' * ./#' . _gl
($_) . ' (' . $_ . ')' }
837 sort(@
{$categories{$sn}})
844 print F _grutatxt_header
('By Source', '-');
846 foreach my $s (@sources) {
847 my @f = grep { $_->{'file'} eq $s } @functions;
853 print F _grutatxt_header
($s, '~');
856 map { ' * ./#' . _gl
($_) . ' (' . $_ . ')' }
857 sort(map { $_->{'func'} } @f)
863 print F _grutatxt_header
('Alphabetical', '-');
865 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
877 # the functions themselves
878 foreach my $f (sort { $a->{'func'} cmp $b->{'func'} } @functions) {
879 # avoid duplicate function names
880 if ($f{$f->{'func'}}) {
886 print F _grutatxt_header
($f->{func
}, '-');
888 print F _grutatxt_header
('Name', '~');
890 print F
'*' . $f->{func
} . '* - ' . $f->{bdesc
} . "\n";
894 print F _grutatxt_header
('Synopsis', '~');
896 my $syn = $f->{'altsyn'} || (' ' . $f->{'syn'});
898 # strip arg and return value marks
899 $syn =~ s/[@%]([\w]+)/$1/g;
901 print F
$syn . "\n\n";
904 my @a = @
{$f->{'arg'}};
905 my @d = @
{$f->{'argdesc'}};
907 print F _grutatxt_header
('Arguments', '~');
910 print F
' * ' . shift(@a) . ': ' . shift(@d) . "\n";
917 print F _grutatxt_header
('Description', '~');
919 # take the description
920 my $desc = $f->{'desc'};
922 # decorate function arguments
923 $desc =~ s/@([\w_]+)/_$1_/g;
925 # decorate return values
926 $desc =~ s/\%([\w_]+)/_$1_/g;
930 if ($f->{category
}) {
931 print F _grutatxt_header
('Categories', '~');
934 map { ' * ./#' . _gl
($_) . ' (' . $_ . ')' }
935 @
{$f->{'category'}});
945 print F
"----\n$author ";
949 print F
"- Built with http://triptico.com/software/mp_doccer.html (mp_doccer $main::VERSION)";