Re: Gtk2-Perl API documentation project

[Mauricio Silveira <msilveira linuxbr com>]

muppet wrote:

> ...
> but i think we can do this, and do it well enough that we could use it 
> on any of the add-on projects, too (Gnome2, Gnome2::Canvas, 
> Gnome2::Print, etc, etc).
>
>
> an mockup manpage containing the information we could extract via code 
> parsing and introspection:
>
> NAME
> Gtk2::Button -
>
> SYNOPSIS
> Gtk2::Button->new (mnemonic=undef)
> Gtk2::Button->new_from_stock (stock_id)
> $button->pressed
> $button->released
> $button->clicked
> ...
>
> DESCRIPTION
> any text that may be available. if there's no text, this section 
> doesn't appear.
>
> METHODS
> $widget = Gtk2::Button->new (mnemonic=undef)
> - mnemonic: string
>
> $button->clicked
> here is some descriptive text from a =for apidoc pod.
>
> $button->set_use_underline (use_underline)
> - use_underline: boolean
>
> ...
>
> PROPERTIES
> use-underline - boolean - read/write
> blurb text
> ...
>
> SIGNALS
> clicked
>
> ...


I think yes, there SHOULD be a documentation project for GTK2-perl.
Muppet's mocked man-page example is great, let me write down my thoughts:

1.) Since every .xs file will have a pod for its own, there must be a 
central pod file such as "Gtk2-reference".
2.) There must be a separate pod file for Objects, Flags, enums such as 
Gtk1-perl had!
3.) There should probably be a "complete reference guide" pod file with 
only the "SYNOPSIS" from all the .xs files and the whole Gtk2-objects.
4.) Making it short: there must be a rule of "how GTK2-perl 
documentation works", so that people who wish to contribute with the 
documentation project may help with it.

I'd be glad to spare some time getting the reference for Gtk2-perl ready!
You know, I'm not a very experienced programmer, to be honest, I've just 
barely learnt perl(!), but I'd love to help with this project; I believe 
that many people around are whispering for a good documentation set for 
the project, many like me might not be an experienced programmer, so 
searching the C sources/headers/api documentation from GTK2+ for 
function calls, enums etc is not as fun as programming GTK2-perl with a 
good API reference.

I propose a debate about how should the GTK2-perl documentation project 
be guided. And you bet I'd love to help(as playing around with structs, 
typedefs, mallocs and pointers in C is not my taste for the time beeing 
;) the project.

I could write the text into the xs files as far as someone wrote a 
new(make some cahnges) to your parseem.pl and printem.pl so that there 
could be the NAME, SYNOPSIS, DESCRIPTION, METHODS, EXAMPLES etc sections 
for the output pod as well as those Objects, the "Gtk2-reference" and 
the "complete reference guide".

Muppet, if you help me where to start, I can help the project with this 
task... (I will surely learn a lot with this task too ;).

Just turn the task a bit easier and I'll handle with this.

BTW, isn't the "maps" file still missing the line "GTK_STOCK GtkStock 
Gobject Gtk2::Stock"? and GtkButton.xs missing "GtkStock stock_id" at 
the gtk_button_new_from_stock Widget definition?

What else should be updated to get Gtk2::Stock "translation" working for 
the code and reference? (Relax, just curious ;)

I wrote two new scripts for anyone use:
viewpodout.pl -> will generate and show the pod2text output from a 
specified .xs file (just change the $toolspath to the dir where 
parseem.pl an printem.pl are located) in a loop, just press q to exit 
from less and enter after you changed the .xs file to see the results
gendocs.pl -> command line arguments -s /path/to/dir/with/xs -d 
/tmp/allgtk2perldocs -f txt,man,html will write all the .xs pods into 
each format subfolder.

These might come handy for those wishing to help writing the 
documentation... or useless...

Sorry if I was inconvenient anyway, or for any mistakes, or for my bad 
english or for ... whatever :P


Mauricio Silveira <msilveira at linuxbr dot com>



#!/usr/bin/perl -w

use strict;
use Getopt::Long;
use constant TRUE => 1;
use constant FALSE => 0;
use File::Basename;
use File::Spec;
use Cwd;

#
my $progname = basename($0);
#Handle command line options
Getopt::Long::Configure("bundling", "noignore_case_always", "no_auto_abbrev");

my $sourcedir;
my $destdir;
die("Try '$0 --help' for more options.\n") unless
        GetOptions('sourcedir|s=s' => \$sourcedir,'destdir|d=s' => \$destdir, 'formats|f=s', "help|h");

my @formats = split(/,/, our $opt_formats);

if (our $opt_help) {
        print "Usage: $0 [options...]\n" .
              "Source path is the working directory.\n" .
              "options:\n\n" .
              "-s, --sourcedir=/path/to/dir\n" .
              "\tSource *.xs dir from Gtk2-perl source.\n\n" .
              "-d, --destdir=/path/to/dir\n".
              "\tDestination folder for the output docs.\n" .
              "\tOutputs will be [destdir]/format:\n" .
              "\t*Destination folder will be auto-created if doesn't exist.\n\n"
              . "-f, --formats=[txt,html,man]\n" .
              "\tComma ',' separated list of output formats.\n" .
              "\tValid formats are:\n" .
              "\tman -> ManPage format\n" .
              "\ttxt -> Pure text format\n" .
              "\thtml -> HyperText format\n" .
              "\tpod -> Plain Old Documentation format\n\n" .
              "2004 - Mauricio Silveira <msilveira\ linuxbr com>"
              . "\n\n";
              exit(0);
}

##################
##Sourcedir checks
##################
if ( ! $sourcedir) {
$sourcedir = cwd();
die "You must be into Gtk2-perl's xs dir or enter a sourcedir.\nTry '$progname --help' for options.\n" unless 
(((-e "maps" and -f _) or (-e "../maps" and -f _)) and (index(cwd(), "xs", -2)) > 0);
}
opendir SOURCEDIR, "$sourcedir" or die "Can't open xs dir $sourcedir: $!\n";
my @xs_files = grep(/\w+\.xs$/, readdir SOURCEDIR) or die "That doesn't seem to be the xs dir....\n";
closedir SOURCEDIR;

###############
#Destdir checks
###############
die "Your must enter a destdir for doc output!\n" unless ($destdir);
if (-d $destdir) {
        unless (-r _ and -w _) {
                die "You don't have permission to write on $destdir.\n";
        } else {
                #Die as unexpected error!
                opendir DESTDIR, "$destdir" or die "Can't open destdir: $!\n";
                if ((my @destlist = readdir DESTDIR) > 2) {
                        warn "WARNING: The directory exists and is not empty!\n" .
                        "\tThe program may OVERWRITE any previous output!\n" .
                        "\tIT MAY EVEN OVERWRITE IMPORTANT FILES!\n" .
                        "\tYou've been warned!\n" .
                        "\tPress enter to proceed or press Ctrl-C NOW to abort!\n\n";
                } else {
                        print "Storing documents into existing folder $destdir.\n";
                }
        }
} elsif (-e $destdir) {
                die "$destdir exists and is not a directory!\n";
} else {
        warn "Destination dir $destdir doesn't exist!\n";
        my $dest_parent = dirname($destdir);
        (-r $dest_parent and -w _) or die "You don't have permission to create a dir into $dest_parent: $!\n";
        print "Creating destdir: $destdir... ";
        while (1) {
                if (mkdir($destdir)) {
                        print "OK!\n";
                        print "Storing documents into folder $destdir.\n";
                        last;
                } else {
                        print "#FAILED: $!\n";
                        print "Impossible to create $destdir.\n";
                        print "Enter a new destdir(or press enter to cancel): ";
                        chomp($destdir = <STDIN>);
                        die "Quitting..." if $destdir =~ /^\s*$/i;
                        next;
                }
        }
}

################
##Formats ckeck
################
#This %fmt_ext is redundant, I know but... if i ever wish to change the
#command line input format names? ;) (No likely, really but...)
my %fmt_ext = (
        "pod" => "pod",
        "txt" => "txt",
        "man" => "man",
        "html" => "html",
);
if (@formats) {
        print "Output will be stored as txt format.\n" if grep(/^\btxt\b$/i, @formats);
        print "Output will be stored as html format.\n" if grep( /^\bhtml\b$/i, @formats);
        print "Output will be stored as manpage format.\n" if grep( /^\bman\b$/i, @formats);
        print "Output will be stored as pod format.\n" if grep( /^\bpod\b$/i, @formats);
        my @invalid_out = grep(!/^\b(man|txt|html|pod)\b$/, @formats);
        die "Unknown format output(s): @invalid_out.\n" if @invalid_out;
} else {
        my $default_output = "pod";
        print "Warning: Using default format output: $default_output.\n";
        unshift(@formats, "pod");
}
foreach(@formats) {
        my $formatdir = File::Spec->catfile("$destdir", "$_");
        #unlikely to need die here...
        mkdir($formatdir);# or die "Cannot create dir $formatdir: $!\n";
        print "Created $_ format output dir.\n";
}


#OK, let's write out the documents!

#chdir into xs dir, because printeem.pl needs the maps or ../maps file
chdir "$sourcedir";

my $toolspath = "/opt/gtk2-perldoc";
my $xs_parser = "$toolspath/parseem.pl";
my $xs_print = "$toolspath/printem.pl";
my $errorlog = "$destdir/errorlog";

foreach (@xs_files) {
        my $shortname = basename($_, ".xs");
        my $fullpath_filename = File::Spec->catfile($sourcedir, $_);
        open XSFILE, "$fullpath_filename" or die "$fullpath_filename: $!\n";
        close XSFILE;
        open STDERR, ">>$errorlog" or die "Can't open errorlog: $!\n";
        printf("Writing output files with formats [%s]:\n", join(',', @formats));
        foreach (@formats) {
                my $destfile = File::Spec->catfile("$destdir", "$_", "$shortname.$fmt_ext{$_}");
                system("$xs_parser $fullpath_filename | $xs_print > $destfile") if grep( /^\bpod\b$/i, $_);
                system("$xs_parser $fullpath_filename | $xs_print | pod2text > $destfile") if grep( 
/^\btxt\b$/i, $_);
                system("$xs_parser $fullpath_filename | $xs_print | pod2man > $destfile") if grep( 
/^\bman\b$/i, $_);
                system("$xs_parser $fullpath_filename | $xs_print | pod2html --cachedir=/tmp > $destfile") if 
grep( /^\bhtml\b$/i, $_);
                my $sep_multiplier = 80-length($destfile)-length("*Wrote: ->");
                printf "*Wrote: %s> %s\n", ("-" x $sep_multiplier), $destfile;
        }
}

#OK :)
#"First" useful perl program :P

#!/usr/bin/perl -w


use strict;
use Cwd;

use constant TRUE => 1;
use constant FALSE => 0;

$ENV{'PATH'} = "/opt/gtk2-perldoc:$ENV{'PATH'}";

die "You must enter a filename, a .xs filename.\n" unless @ARGV;

my $podfile = shift @ARGV;
my $errorlog = cwd() . "/$podfile.podlog";
my $toolspath = "/opt/gtk2-perldoc";
my $podparser = "$toolspath/parseem.pl";
my $podprint = "$toolspath/printem.pl";

open STDERR, ">$errorlog" or die "Can't write log file.\n";

print "Press enter to view the file or type 'quit' to exit: ";
while (<STDIN>) {
        if ($_ =~ /^\bquit\b$/i) { #Terminate
                print "Terminated!\n";
                die "$0: Terminated.\n";
        } elsif ($_ =~ /^\blog\b$/i) { #View error logs
                system("cat $errorlog");
                print "\n";
        } else { #actually view the file
                system("$podparser $podfile | $podprint | pod2text | less");
        }
        print "Press enter to view the file or type 'quit' to exit: ";
}