2 ###################################################
3 # robodoc 2 pod converter
4 ###################################################
10 # Generate POD documentation from ROBODoc to allow
11 # use of perldoc with your Robodoc'ed code.
14 # * V 0.2.1 of 06/03/14 corrected the regexps
15 # * V 0.2.0 of 06/03/13 rewritten with intermediate representation
16 # * V 0.1.0 of 06/03/10 first version
19 # nothing known right now.
24 # * manage nested lists
25 # * indent EXAMPLE with
28 # This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
30 # Emmanuel Florac ( wazoox @ free . fr )
32 # (c) 2006 Intellique (www.intellique.com)
34 # always use strict et warnings.
40 #########################
42 #########################
45 return "usage : $0 <source file> [ >> <pod file> ]";
48 #########################
50 #########################
52 # must provide a file name to work with
53 my $file = shift or die usage();
54 open my $fh, $file or die "can't open file : $file";
56 # robodoc start and end tags (marks robodoc blocks)
57 my $rbd_starttag = qr(^\*\*\*\*[\w\*]\*);
58 my $rbdheadtype = qr(^\*\*\*\*([\w\*])\*);
59 my $rbd_endtag = qr(^\*\*\*);
61 # robodoc general tags
63 'NAME', 'COPYRIGHT', 'SYNOPSIS', 'USAGE',
64 'FUNCTION', 'DESCRIPTION', 'PURPOSE', 'AUTHOR',
65 'CREATION DATE', 'MODIFICATION', 'HISTORY', 'INPUTS',
66 'ARGUMENTS', 'OPTIONS', 'PARAMETERS', 'SWITCHES',
67 'OUTPUT', 'SIDE EFFECTS', 'RESULT', 'RETURN VALUE',
68 'EXAMPLE', 'NOTES', 'DIAGNOSTICS', 'WARNINGS',
69 'ERRORS', 'BUGS', 'TODO', 'IDEAS',
70 'PORTABILITY', 'SEE ALSO', 'METHODS', 'NEW METHODS',
71 'ATTRIBUTES', 'NEW ATTRIBUTES', 'TAGS', 'COMMANDS',
72 'DERIVED FROM', 'DERIVED BY', 'USES', 'CHILDREN',
73 'USED BY', 'PARENTS', 'SOURCE', 'LICENSE',
89 # to check for headers tags
90 my $tagmatch = join '|', @rbdtags;
91 $tagmatch = qr(^($tagmatch));
93 # to store the robodoc
103 # remove leading # if any
107 $inrobodoc = 0 if m/$rbd_endtag/;
110 push @{ $robodoc[$#robodoc]{$rbdtagname} }, $_;
113 if (m/$rbd_starttag/) {
115 my ($headertype) = (m/$rbdheadtype/);
116 ($rbdtagname) = (m/$rbd_starttag(.*)/);
119 $rbdtagname = $rbdheaders{$headertype} . $rbdtagname;
120 push @robodoc, { $rbdtagname => [] };
127 # now convert robodoc to pod
133 my ( $k, $v ) = each %$_;
134 my $currhead = $podhead;
135 push @pod, '', "=head$currhead $k", '';
138 foreach my $line (@$v) {
139 # insert head if this is a managed tag
140 if ( $line =~ m/$tagmatch/ ) {
141 push @pod, ( '', "=head$currhead $line", '' );
142 # insert bulleted lists
143 } elsif ( my ($elem) = ( $line =~ m/^\*\s+(.*)/ ) ) {
148 push @pod, ( '', '=item *', '', $elem );
150 } elsif ( $items > 0 ) {
152 push @pod, ('', '=back', '');
161 print join( "\n", @pod ) . "\n";