Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

ROBODoc to Pod translator

by wazoox (Prior)
on Mar 13, 2006 at 16:35 UTC ( #536298=sourcecode: print w/ replies, xml ) Need Help??

Category: Utility
Author/Contact Info Emmanuel Florac ( wazoox @ free . fr )
Description: Do you know ROBODoc ? It's quite similar to Pod but has several advantages :
  • It allows to write inline documentation with most languages, including HTML;
  • You can create single or multiple documents from the same source;
  • It's more compact than Pod, ans it's a nice advantage when working with ctags.

However it missed something : the ability to generate Pod (for people used to it) from your ROBODoc. So here it is at last !

update : corrected a regexp

#!/usr/bin/perl
###################################################
# robodoc 2 pod converter
###################################################
#****h* robodoc2pod
# NAME
# Robodoc 2 Pod
#
# FUNCTION
# Generate POD documentation from ROBODoc to allow
# use of perldoc with your Robodoc'ed code.
#
# HISTORY
# * V 0.2.1 of 06/03/14        corrected the regexps
# * V 0.2.0 of 06/03/13        rewritten with intermediate representat
+ion
# * V 0.1.0 of 06/03/10        first version
#
# BUGS
# nothing known right now.
#
# TODO
# * refactor cleanly
# * manage locales
# * manage nested lists
# * indent EXAMPLE with 
# 
# LICENSE
# This program is free software; you can redistribute it and/or modify
+ it under the same terms as Perl itself. 
# AUTHOR
# Emmanuel Florac ( wazoox @ free . fr )
# COPYRIGHT
# (c) 2006 Intellique (www.intellique.com)
#***
# always use strict et warnings.
use strict;
use warnings;

use Data::Dumper;

#########################
# functions
#########################

sub usage {
    return "usage  : $0 <source file> [ >> <pod file> ]";
}

#########################
# main
#########################

# must provide a file name to work with
my $file = shift or die usage();
open my $fh, $file or die "can't open file : $file";

# robodoc start and end tags (marks robodoc blocks)
my $rbd_starttag = qr(^\*\*\*\*[\w\*]\*);
my $rbdheadtype  = qr(^\*\*\*\*([\w\*])\*);
my $rbd_endtag   = qr(^\*\*\*);

# robodoc general tags
my @rbdtags = (
    'NAME',          'COPYRIGHT',      'SYNOPSIS',    'USAGE',
    'FUNCTION',      'DESCRIPTION',    'PURPOSE',     'AUTHOR',
    'CREATION DATE', 'MODIFICATION',   'HISTORY',     'INPUTS',
    'ARGUMENTS',     'OPTIONS',        'PARAMETERS',  'SWITCHES',
    'OUTPUT',        'SIDE EFFECTS',   'RESULT',      'RETURN VALUE',
    'EXAMPLE',       'NOTES',          'DIAGNOSTICS', 'WARNINGS',
    'ERRORS',        'BUGS',           'TODO',        'IDEAS',
    'PORTABILITY',   'SEE ALSO',       'METHODS',     'NEW METHODS',
    'ATTRIBUTES',    'NEW ATTRIBUTES', 'TAGS',        'COMMANDS',
    'DERIVED FROM',  'DERIVED BY',     'USES',        'CHILDREN',
    'USED BY',       'PARENTS',        'SOURCE',       'LICENSE',
);

my %rbdheaders = (
    c   => 'Class',
    d   => 'Constant',
    f   => 'Fonction',
    h   => 'Module',
    m   => 'Méthod',
    s   => 'Structure',
    t   => 'Type',
    u   => 'Unit Test',
    v   => 'Variable',
    '*' => '',
);

# to check for headers tags
my $tagmatch = join '|', @rbdtags;
$tagmatch = qr(^($tagmatch));

# to store the robodoc
my @robodoc;

# flag and titles
my $inrobodoc  = 0;
my $rbdtagname = '';

# read the file
while (<$fh>) {

    # remove leading # if any
    s/^\s*# *//;
    chomp;

    $inrobodoc = 0 if m/$rbd_endtag/;

    if ($inrobodoc) {
        push @{ $robodoc[$#robodoc]{$rbdtagname} }, $_;
    }

    if (m/$rbd_starttag/) {
        $inrobodoc = 1;
        my ($headertype) = (m/$rbdheadtype/);
        ($rbdtagname) = (m/$rbd_starttag(.*)/);
        chomp $rbdtagname;
        if ($rbdtagname) {
            $rbdtagname = $rbdheaders{$headertype} . $rbdtagname;
            push @robodoc, { $rbdtagname => [] };
        }
    }
}

close $fh;

# now convert robodoc to pod
my @pod;
my $items   = 0;
my $podhead = 1;

foreach (@robodoc) {
    my ( $k, $v ) = each %$_;
    my $currhead = $podhead;
    push @pod, '', "=head$currhead $k", '';
    $currhead++;

    foreach my $line (@$v) {
        # insert head if this is a managed tag
        if ( $line =~ m/$tagmatch/ ) {
            push @pod, ( '', "=head$currhead $line", '' );
        # insert bulleted lists
        } elsif ( my ($elem) = ( $line =~ m/^\*\s+(.*)/ ) ) {
            if ( $items == 0 ) {
                $items++;
                push @pod, "=over";
            }
            push @pod, ( '', '=item *', '', $elem );
        # end bulleted list
        } elsif ( $items > 0 ) {
            $items = 0;
            push @pod, ('', '=back', '');
            push @pod, $line;
        # raw insert
        } else {
            push @pod, $line;
        }
    }
}

print join( "\n", @pod ) . "\n";

Comment on ROBODoc to Pod translator
Download Code
Re: ROBODoc to Pod translator
by slower (Novice) on Feb 11, 2010 at 00:35 UTC

    I took your post here as inspiration to turn this into a module and published it on CPAN. It's called Pod::ROBODoc and also sports a command-line program called robodoc2pod that can read from STDIN or a file and write to STDOUT or another file.

      Robodoc2pod has also been included in the standard robodoc distribution. I should check if the one that's published here is the latest, though.

Back to Code Catacombs

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: sourcecode [id://536298]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (3)
As of 2014-07-31 05:27 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (245 votes), past polls