31 Jul 2009

31.07.2009

:*

30 Jul 2009

How to generate user documentation from Perl script?

If you want to generate user documentation from POD in Perl should add at the bottom of script this section - after keyword __END__(this is only example - I use this schema for my documentation): i
#!/usr/bin/perl

print "hello world!\n";

# end of script

# TAGS IN PERLDOC:
# *PROGNAME* - replace with program name
# *SHORT_DESCRIPTION* - one sentence description

__END__

=head1 NAME

*PROGNAME* - *SHORT_DESRIPTION*.



=head1 SYNOPSIS

*PROGNAME* 



=head1 EXAMPLES

*PROGNAME*

=head1 REQUIRED ARGUMENTS



=head1 OPTIONS

=over 4

=item B<-v, --verbose>

Be verbose

=item B<-d, --debug>

Be even more verbose - information specifig for debugging

=item B<-h, --help>

Display short usage help and exit

=back




=head1 DESCRIPTION

*PROGNAME* was designed for *PURPOSE*



=head1 DEPENDENCIES

=over 4

=item B<perl 5.6> or newer with standard modules

=back



=head1 BUGS AND LIMITATIONS

You are welcome to send bug reports about *PROGNAME* to my email.

Please attach in a bug report, informations like:

=over 4

=item * Perl version (perl --version)

=item * information what you've expected as a output

=back



=head1 VERSION

This documentation refers to *PROGNAME* version *VERSION*.



=head1 SEE ALSO

B<__>



=head1 AUTHOR

*AUTHOR*



=head1 LICENSE AND COPYRIGHT

*LICENSE*

About licenses

Generating docs

First of all you need to have perldoc.
apt-get install perl-doc

Wiki (syntax) documentation from Perl scripts - pod2wiki

There is an extension for POD which helps creating Wiki like syntax documentation from POD files. On Debian systems it can be installed using:
apt-get install libpod-simple-wiki-perl
Generating documentation is really easy
pod2wiki --style mediawiki file.pl > file.wiki
Possible styles of output are: I've made my own DokuWiki plugin to libpod-simple-wiki installation is easy, copy the contents to file named 'Dokuwiki.pm' and run cp Dokuwiki.pm /usr/share/perl5/Pod/Simple/Wiki/Dokuwiki.pm of course as a root. Porting was only done to step number 3 - for my test file it worked like a charm, but for yours it may not - just test it.
package Pod::Simple::Wiki::Dokuwiki;



# Portme: This module is used as a boiler plate or example of how to create a
# new C<Pod::Simple::Wiki::> module.
#
# Read the Portme section of the documentation below for more information.
#
# Portme. Try to maintain the same code style as this module:
#     4 space indents.
#     No tabs.
#     No trailing whitespace.
#     79 column wrap.
#     Consistency.
#

###############################################################################

#
# Pod::Simple::Wiki::Dokuwiki - A class for creating Pod to Dokuwiki filters.
#
#
# Copyright 2003-2007, John McNamara, jmcnamara@cpan.org
# Copyright 2009 - DokuWiki module, Tomasz Gaweda - http://blog.0x1fff.com/
#
# Documentation after __END__
#

use Pod::Simple::Wiki;
use strict;
use vars qw(@ISA $VERSION);


@ISA     = qw(Pod::Simple::Wiki);
$VERSION = '0.08';

# Portme. Start with these tags.


###############################################################################
#
# The tag to wiki mappings.
#
my $tags = {
            '<b>'    => '** ',
            '</b>'   => ' **',
            '<i>'    => '// ',
            '</i>'   => ' //',
            '<tt>'   => "''",
            '</tt>'  => "''",
            '<pre>'  => '   ',
            '</pre>' => "   \n\n",
            '<h1>'   => "\n===== ",
            '</h1>'  => " =====\n\n",
            '<h2>'   => "\n==== ",
            '</h2>'  => " ====\n\n",
            '<h3>'   => "\n=== ",
            '</h3>'  => " ===\n\n",
            '<h4>'   => "\n== ",
            '</h4>'  => " ==\n\n",
           };

# Portme. You can leave new() as it is.

###############################################################################
#
# new()
#
# Simple constructor inheriting from Pod::Simple::Wiki.
#
sub new {
    my $class                   = shift;
    my $self                    = Pod::Simple::Wiki->new('wiki', @_);
       $self->{_tags}           = $tags;
#      $self->{_debug}         = 1;
    bless  $self, $class;
    return $self;
}

# Portme. How Pod "=over" blocks are converted to Dokuwiki wiki lists.
###############################################################################
#
# _indent_item()
#
# Indents an "over-item" to the correct level.
#
sub _indent_item {
    my $self         = shift;
    my $item_type    = $_[0];
    my $item_param   = $_[1];
    my $indent_level = $self->{_item_indent};

    if ($item_type eq 'bullet') {
         $self->_append('  *' x $indent_level . ' ');
    }
    elsif ($item_type eq 'number') {
         $self->_append('  - ' x $indent_level . ' ');
    }
    elsif ($item_type eq 'text') {
         $self->_append('  * ' x $indent_level . ' ');
    }
}

# Portme: Use this is text tokens need to be escaped, such as CamelCase words.
###############################################################################
#
# _handle_text()
#
# Perform any necessary transforms on the text. This is mainly used to escape
# inadvertent CamelCase words.
#
sub _handle_text {
    my $self = shift;
    my $text = $_[0];

    # Only escape words in paragraphs
    if (not $self->{_in_Para}) {
        $self->{_wiki_text} .= $text;
        return;
    }

    # Split the text into tokens but maintain the whitespace
    my @tokens = split /(\s+)/, $text;

    # Portme:
    # Escape any tokens here, if necessary.

    # Rejoin the tokens and whitespace.
    $self->{_wiki_text} .= join '', @tokens;
}

# Portme. How Pod "=over" blocks are converted to Dokuwiki wiki lists.
###############################################################################
#
# Functions to deal with =over ... =back regions for
#
# Bulleted lists
# Numbered lists
# Text     lists
# Block    lists
#

sub _end_item_text     {$_[0]->_output("\n\n")}

# Portme: Probably won't have to change this.
###############################################################################
#
# _start_Para()
#
# Special handling for paragraphs that are part of an "over" block.
#
sub _start_Para {
    my $self         = shift;
    my $indent_level = $self->{_item_indent};

    if ($self->{_in_over_block}) {
        # Do something here is necessary
    }
}

1;

__END__

=head1 NAME

Pod::Simple::Wiki::Dokuwiki - A class for creating Pod to Dokuwiki wiki filters.

=head1 SYNOPSIS

This module isn't used directly. Instead it is called via C<Pod::Simple::Wiki>:

    #!/usr/bin/perl -w
    use strict;
    use Pod::Simple::Wiki;
    my $parser = Pod::Simple::Wiki->new('template');
    ...

Convert Pod to a Dokuwiki wiki format using the installed C<pod2wiki> utility:

    pod2wiki --style template file.pod > file.wiki

=head1 DESCRIPTION

This module is used as a boiler plate or example of how to create a new C<Pod::Simple::Wiki::> module. See the Portme section below.
The C<Pod::Simple::Wiki::Dokuwiki> module is used for converting Pod text to Wiki text.
Pod (Plain Old Documentation) is a simple markup language used for writing Perl documentation.
For an introduction to Dokuwiki see: http://www.portme.org
This module isn't generally invoked directly. Instead it is called via C<Pod::Simple::Wiki>. See the L<Pod::Simple::Wiki> and L<pod2wiki> documentation for more information.

=head1 PORTME

This module is used as a boiler plate or example of how to create a new C<Pod::Simple::Wiki::> module.
If you are thinking of creating a new C<Pod::Simple::Wiki::> you should use this module as a basis.
B<Portme>. Any comments in the code or documentation that begin with or contain the word C<portme> are intended for the C<porter>, the person who is creating the new module. You should read all of the C<portme> comments and eventully delete them when the module is finished.

The following are some suggested steps in porting the module. For the sake of example say we wish to convert Pod to a format called C<portmewiki>. Also for the sake of this example we will assume that you know how to install and work on a module or work on it in a local source tree using C<-I./lib> or C<-Mblib>.


=head2 Portme Step 1

Copy the C</lib/Pod/Simple/Wiki/Dokuwiki.pm> to a new module C</lib/Pod/Simple/Wiki/Portmewiki.pm>.

The module name should have the first letter capitalised and all others lowercase, i.e, the same as returned by C<ucfirst()>.

=head2 Portme Step 2

Edit the module and replace all instances of C<Dokuwiki> with C<Portmewiki> (case sensitive).

Then replace all instances of C<template> with C<portmewiki> (case sensitive).


=head2 Portme Step 3

The module should now work and can now be called as follows:

    use Pod::Simple::Wiki;
    my $parser = Pod::Simple::Wiki->new('portmewiki');

The default output format, in this configuration is Kwiki.


=head2 Portme Step 4

Write some tests.

Copy the tests in the C</t> directory for one of formats that is similar to the format that you are porting.


=head2 Portme Step 5

Modify the source of C<Portmewiki.pm> until all the tests pass and you are happy with the output format.
Start by modifying the C<tags> and then move on to the other methods.

If you encounter problems then you can turn on internal debugging:

    my $parser = Pod::Simple::Wiki->new('portmewiki');
    $parser->_debug(1);

    Or for more debug information that you can deal with:

    # At the start of your program and before anything else:
    use Pod::Simple::Debug (5);
    ...
    $parser->_debug(0);


If you find yourself with a difficult porting issue then you may also wish to read L<Pod::Simple::Methody> and L<Pod::Simple::Subclassing>.
Try to maintain the code style of this module. See the source for more information.


=head2 Portme Step 6


Remove or replace all C<portme> comments.


=head2 Portme Step 7

Send it to me the tarred directory with libs and tests and I'll release it to CPAN.


=head1 METHODS

Pod::Simple::Wiki::Dokuwiki inherits all of the methods of C<Pod::Simple> and C<Pod::Simple::Wiki>. See L<Pod::Simple> and L<Pod::Simple::Wiki> for more details.


=head1 Dokuwiki Specific information

Portme: Add some information specific to the Dokuwiki format or this module here. If required.


=head1 SEE ALSO

This module also installs a C<pod2wiki> command line utility. See C<pod2wiki --help> for details.


=head1 ACKNOWLEDGEMENTS

Thanks to Portme McPortme and Portme O'Portme for patches, documentation or bugfixes.

=head1 DISCLAIMER OF WARRANTY

Please refer to the DISCLAIMER OF WARRANTY in L<Pod::Simple::Wiki>.


=head1 AUTHORS

John McNamara jmcnamara@cpan.org

Portme McPortme portme@portme.org


=head1 COPYRIGHT

(C) MMIII-MMVII, John McNamara.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.
Source of this module is also available on Google code. After instalation there is a simple way to invoke this:
pod2wiki --style dokuwiki file.pl > file.dokuwiki.txt
By the way, this helps publishing Perl code at Blogger - it changes some characters to proper HTML entities.

RTF documentation from Perl scripts - pod2rtf

First of all if you need to use Polish characters in your manual, you should convert source from UTF-8 to ISO-8859-2 and later run command:
perldoc -ortf file.pl > file_pod.rtf

LaTeX documentation from Perl scripts - pod2latex

perldoc -oLaTeX file.pl > file_pod.tex
or
pod2latex file.pl -out file_pod.tex
Both commands do the same.

PDF documentation from Perl scripts - pod2pdf

There is a module which provides pdf pod writer and whole project pod2pdf. This projects require libpdf-api2-perl and lib argvfile.
apt-get install libpdf-api2-perl libgetopt-argvfile-perl
General usage od pod2pdf is:
pod2pdf file.pl > file_pod.pdf
For more specific istructions reffer to author site or to polish "man page"

HTML documentation from Perl scripts - pod2html

First of all we need libpod-xhtml-perl - translate POD to Xhtml.
apt-get install libpod-xhtml-perl
General usage of pod2html package:
pod2html file.pl > file_pod.html

Manpage documentation from Perl scripts - pod2man

pod2man file.pl > file_pod.man

Summary of generating user documentation in Perl

#!/bin/bash

if [ $# -lt 1 ] ; then
 echo "usage: "$0" file1.pl file2.pl ... fileN.pl"
 exit;
fi

for file in $@ ; do
 out=`basename $file .pl`
 if [ ! -d $out ] ; then 
  mkdir $out
 fi
 echo "Generating perldoc for file $file in $out"
 outName="${out}/${out}_man_"`date -I`
 
 # here do character conversion
 tmpName=`mktemp /tmp/perlDocAll.XXXXXXX`
 tmpNamePl=$tmpName".pl"
 #iconv -f UTF-8 -t ISO-8859-2 $file > $tmpNamePl
 cat $file > $tmpNamePl

 perldoc -ortf $tmpNamePl > $outName.rtf
 pod2latex $tmpNamePl -out $outName.tex
 pod2pdf $tmpNamePl > $outName.pdf
 pod2html $tmpNamePl > $outName.html
 pod2man $tmpNamePl > $outName.man
 pod2wiki --style dokuwiki $tmpName > $outName.dokuwiki.txt

 rm $tmpName $tmpNamePl
done
This simple scripts converts documentation from .pl files into all formats described in this article :) have fun.

Documentation generators in other languages

26 Jul 2009

Alternatives to Nautilus

Today Nautilus was so sluggish that I couldn't stand that any more. I really don't know why this is happening - I've tried searching on Google but no results:(. My CPU usage and disk are getting crazy, when opening directory where is many sub and sub-sub directories especially on USB hard drive. Something is wrong - probably sluggish Nautilus is not due to thumbnails :(.

Alternatives to Nautilus

Xfe
X File Explorer (Xfe) is an MS-Explorer or Commander like file manager for X. It is based on the popular, but discontinued X Win Commander. In my opinion it's not so nice to use it - looks like software written in mid 90 :(
Thunar
This file manager is a component of the XFCE desktop, which is not on the same level as GNOME and KDE but file manager is quite nice.

Pros are: small size, responsiveness, lots of plugins and familiarity for new users.

Cons are: no desktop icons support, bugs in resizing of icons (especially navigation bar), icons are too close to each other (no way to change it).
PCManfm
It's really similar to Thunar, but it's better. PCManfm is probably one of the most useful competitors to Nautilus - (pros) it has tabbed interface, it can load large directories quickly, it has bookmarks and several great views it is also stable.
Cons are: there is no way to change thumbnails size (photos), no recycle bin support - deleting is done right now, default file drag-and-drop on the same disk is copy not move. I think PCManfm is the best alternative but not every feature from Nautilus is implemented ... but I will probably use it soon.
Other software tested
  • rox-filer - GUI from early 90 - ugly :(

File managers

Sometimes I would like to easily move some files easily and quickly. File managers described below can be an "alternative" to Total Commander on Windows.
Emelfm2
A file manager that implements the popular two-pane design based on Gtk2. Some people like it, but I don't - GUI is not very functional other wrong thing is missing progress bar when moving large files and function keys doesn't work :(!.
TuxCMD
And we have winner - checkout it - see screenshots. I will use it.
Other software checked

Summary

apt-get install pcmanfm tuxcmd

Simple Config reader in Perl

Recently I had to develop some config file reading utillity, and here are efects.

Config file definition

# this is comment
! this also is comment
; and this

param : argh
param2=argh2
param3     := arghs

    ; ! # erm?
# erm
param4 = "test in quotes"

# this is invalid
param invalid = invalid
invalid-2=in-valid

param_ok : ok
param_test = #this is not comment

Perl code (one liner) formating this config file

perl -ne 'm/^([^\$\!;#][A-Z0-9_]+)\s*[=:]+\s*(.*|)/i && printf("%-35s%s\n", $1, $2)'

Perl code for reading this file

#!/usr/bin/perl

# Author:  Tomasz Gawęda - blog.0x1fff.com
# Date:   2009.07.26
# License:  BSD
# Description: Simple Perl script for parsing config files
#
# Dependicies: Perl
# Tested on: Perl v5.10.0

use strict;
use warnings;

# Return value of key in hash if it exists and
# it is defined else returns user default (if not set 0)
sub getExistsDefine {
 my ( $hash, $key, $default ) = @_;

 $default |= 0;

 return $default if not exists $hash->{$key};
 return $default if not defined $hash->{$key};

 return $hash->{$key};
}

# procedure for reading config file
sub readConfig {
 my ( $cnfLoc, $h_config, $options ) = @_;

 # cnfLoc - location of config file
 # h_config - reference to hash (here keys will be stored)
 # options - list of options - reference to hash - possible vals:
 #   ':replace' => {0,1},
 #   ':verbose' => {0,1},
 #   ':debug' => {0,1},
 #   ':checkParams' => {0,1},
 #   ':acceptedParams' => \%acceptedParams, # ref to hash
 #

 my $replace     = getExistsDefine( $options, ':replace',     0 );
 my $checkParams = getExistsDefine( $options, ':checkParams', 0 );
 my $h_expected = getExistsDefine( $options, ':acceptedParams', {} );
 my $verbose = getExistsDefine( $options, ':verbose', 1 );
 my $debug   = getExistsDefine( $options, ':debug',   1 );

 if ($debug) {
  print "readConfig: Passed options are:\n";
  for my $prop ( keys %{$options} ) {
   print $prop. " => " . $options->{$prop} . "\n";
  }
  print "\n";
 }

 die "Config $cnfLoc is not readable\n" if not -r $cnfLoc;
 open( CONF, '<', $cnfLoc ) or die "Unable to open file $cnfLoc\n";
 print <CONF> if 0;    # this is only to get rid of warning

 while ( my $line = <CONF> ) {

  print "Reading line: " . $line if $debug;

  # do read
  if ( $line =~ m/^\s*([^#\$\!;]\s*[a-z_0-9]*)\s*[=:]+\s*(.*?)\s*$/i ) {
   my $prop = $1;
   my $val  = ( defined $2 ) ? $2 : "";

   print "Found param: " . $prop . " => " . $val if $verbose or $debug;

   # check is param is valid
   if ( $checkParams and not exists $h_expected->{$prop} ) {
    print "\tIgnoring\n" if $verbose or $debug;
    next;
   }

   # if parameter is on list - replace it or not?
   if ( exists( $h_config->{$prop} ) and not $replace ) {
    print "\tReplacing\n" if $verbose or $debug;
    next;
   }

   # save it
   print "\tAccepting (" . $prop . " => " . $val . ")\n"
     if $verbose or $debug;

   $h_config->{$prop} = $val;
  }
 }
 close(CONF) or die "Unable to close file $cnfLoc\n";
}

##
##
## MAIN:
##
##

die "\nusage:\t" . $0 . " config_file_location\n\n" if scalar @ARGV %lt; 1;

print "Reading config file " . $ARGV[0] . "\n";

my %cnf;    # here will read be data stored

# this is list of accepted parameters in config file
my %acceptedParams = ( 'this_params_is_ok', 'this_also_is_ok', 'nunfil', );

# internal options for procedure
my %opts = (
 ':replace'        => 0,
 ':verbose'        => 1,
 ':debug'          => 0,
 ':checkParams'    => 1,
 ':acceptedParams' => \%acceptedParams,
);
readConfig( $ARGV[0], \%cnf, \%opts );

# and inline way to run it
#readConfig($ARGV[0], \%cnf, {":me"=>"a"});

# print values
for my $prop ( keys %cnf ) {
 print $prop. " => " . $cnf{$prop} . "\n";
}

# end

Summary

I hope that code is readable for everybody and will help to deal with some simple config files.

20 Jul 2009

Darmowe środowisko testowe dla Perla od Microsoftu

Najpierw była zapowiedź, a teraz projekt Microsoftu oferujący darmowe środowisko testowania skryptów Perla dla Windowsa stało się faktem - całość to parę maszyn wirtualnych z głównymi wersjami Windows jak donosi Heise OpenSource. Na maszynach też jest dostępne środowisko Strawberry Perl, tak więc jeśli jesteś deweloperem CPAN - możesz całkowicie za darmo przetestować swoje skrypty pod Windowsem. Jako, że pod Windowsem najczęściej korzystam z dystrybucji Active State ActivePerl to i tak sporo mi to daje - zapewne przesiadka na Strawberry Perl nie będzie żadnym kłopotem (tym bardziej, że jest on dostępny na pendrive).

Co to może oznaczać?

Hmm, czyżby Microsoft chciał zamienić swój język skryptowy używany w powłoce systemu na Perla? Nie było by to złe rozwiązanie, bo skądinąd wiem że niektóre firmy świadczące usługi serwisowe dla sieci korporacyjnych już obecnie korzystają ze skryptów Perla, które wykonują jakieś tam (*niestety nie wiem jakie*) zadania pod systemami Microsoftu. Czyżby Perl przeżywał swój renesans w dobie Ruby on Rails, Python, Groovy, Scala i innych języków? A może Microsoft ma dalekosiężne plany by wykorzystać nową maszynę wirtualną Perla - Parrot (o której to chyba już krążą legendy niczym o Yeti) jako silnik do tworzenia swoich nowych języków?

Jeżeli Microsoft stworzyłby jeszcze pluginy do VisualStudio obsługujące język Perl - to pewnie by to przyczyniło się do odrodzenia całej społeczności CPAN, a także napływu nowych programistów do społeczności.

19 Jul 2009

Generating ready to print PDF Javadoc file

Some time ago, when writing project from Computer Networks in Java me and my friend want to generate Javadoc in PDF. On Sun tech support is information how to generate Javadoc PDF but it was not really usefull. Reading this article you have to pass few steps and install additional software which is not nice.

After some time I have decided to search other way to do it. I found two applications doclets worth using.
What is doclet?
Doclet is programs (it's some kind of plugin to Javadoc tool) written in the Java programming language that use the doclet API to specify the content and format of the output of the Javadoc tool. By default, the Javadoc tool uses the "standard" doclet provided by Sun Microsystems to generate API documentation in HTML format. However, user can write own doclets and start generating documentation in custom format for example PDF, PS, TXT.

PDFDoclet

PDFDoclet is doclet build using iText library (for generating PDF). For proper working it requires only PDFDoclet jar file. On Source Forge site author of PDFDoclet says: PDFDoclet is a straightforward, simple-to-use 100% pure Java solution. It creates a PDF file as similar as possible to a typical HTML javadoc. As far I remember the generated javadoc can be customized by specifying a header/footer text and a cover page in XHTML. Running PDFDoclet for first time is not as straightforward as it should be, but in the download bundle some example scripts can be found.

PDFDoclet - how to generate PDF javadoc?

It's not so straight forward that it could be ;) mostly because user is obliged to specify list of packages which has to be in PDF file. I really don't like this part and I wrote bash script which simplifies this.

Script gen-pdf-javadoc-pdfdoclet.sh

Here is source code (it can also be downloaded from Google Code gen-pdf-javadoc-pdfdoclet.sh):
#!/bin/bash

# Author: Tomasz Gawęda - blog.0x1fff.com
# Date:  2009.07.13
# License: BSD
# Description: Simple shell script to generate pdf 
#  javadoc (without ANT) from small
#  Java projects - use under Linux.
#
# Dependicies: Bash
#  Java JDK - 1.6
#  PDFDoclet
#  


# Set the JAVA_HOME variable correctly!!!
JAVA_HOME="/usr/lib/jvm/java-6-sun-1.6.0.13"
PATH="$PATH:$JAVA_HOME/bin"
PATH_DOCLET_JAR=pdfdoclet-1.0.2-all.jar
CUSTOM_CONF='conf.properties'

DEFAULT_CONFIG=<<END_DEFAULT_CONFIG
#
# Default config to pdf doclet
#

# Prints @author tags if set to "yes".
tag.author=yes

# Prints @version tags if set to "yes".
tag.version=yes

# Prints @since tags if set to "yes".
tag.since=no

# Show the Summary Tables if set to "yes".
summary.table=yes

# Encrypts the document if set to "yes".
encrypted=yes

# The following property is ignored
# if "encrypted" is not set to yes.
allow.printing=yes

# Creates hyperlinks if set to "yes".
# For print documents, use "no", so
# there will be no underscores.
create.links=yes

# Creates an alphabetical index of all
# classes and members at the end of the
# document if set to "yes".
create.index=yes

# Creates a navigation frame (or PDF
# outline tree) if set to "yes".
create.frame=yes

# Creates a title page at the beginning
# of the document if set to "yes".
api.title.page=yes

# Defines the path of the HTML file that
# should be used as the title page.
#api.title.file=example/laby/laby_title.html

# Defines the title on the title page if
# no external HTML page is used.
api.title=Hello Doclet!

# Defines the copyright text on the
# title page.
api.copyright=Tom

# Defines the author text on the
# title page.
api.author=Tomasz Gawęda

# Defines packages whose classes should not
# be printed fully qualified. For example, every
# Java developer probably knows that "String" is in
# the "java.lang" package, so instead of wasting 
# page spage, just get rid of that package qualifier:
# dontspec=java.lang
dontspec=java.lang,java.io,java.util

#font.text.name=example/fonts/Windows/Vera.ttf
#font.text.name=example/fonts/Windows/Arial.TTF
#font.text.name=example/fonts/garait.ttf
#font.code.name=example/fonts/SF Arch Rival v1.0/SF Arch Rival.ttf
#font.text.enc=Cp1252
#font.text.enc=ISO-8859-9
#font.code.enc=UTF-8

END_DEFAULT_CONFIG

## DO NOT EDIT BELOW THIS LINE ##

########################################################
########################################################
########################################################
########################################################
########################################################
########################################################

# check command line params
if [ $# -lt 2 ] ; then 
 echo usage: $0 src-dir new-pdf-file
 exit 1
fi

if [ ! -r $PATH_DOCLET_JAR ] ; then
 echo "FATAL: Unable to find doclet in $PATH_DOCLET_JAR"
 exit 1
fi

DOCLET_MAIN=com.tarsec.javadoc.pdfdoclet.PDFDoclet
JAVADOC=`which javadoc`
if [ $? -ne 0 ] ; then
 echo "FATAL: Unable to find javadoc in $PATH"
 exit 1
fi
echo "JavaDoc found in $JAVADOC"

SRCDIR=$1
if [ ! -d $SRCDIR ] ; then
 echo "FATAL: Directory $SRCDIR does not exists"
 exit 1
fi
echo "Src directory of program exists ($SRCDIR)"

OUTPUT=$2
if [ -e $OUTPUT ] ; then
 echo "WARNING: Out document exists - will be overwritten ($OUTPUT)"
 echo "WARNING: Got five seconds to break"
 sleep 3
 echo "WARNING: Got two seconds to break"
 sleep 2
 echo "WARNING: Too late ..."
fi

DEL_CONF=0
echo "Checking if exists custom configuration ($CUSTOM_CONF)"
if [ ! -r $CUSTOM_CONF ] ; then
 echo "Custom configuration doesn't exists using default"
 echo $DEFAULT_CONFIG > $CUSTOM_CONF
 DEL_CONF=1
fi

echo "Starting analyzing sources - finding packages"
# find all packages
PACKAGES=`find $SRCDIR -type d -and -not -empty|sed s#$SRCDIR##g | sed s#/#.#g`
echo "Found "`echo $PACKAGES | wc -l `" packages"

export JAVA_HOME PATH DOCLET_MAIN PATH_DOCLET_JAR JAVADOC

echo "Running JavaDoc"
# Run
$JAVADOC -doclet $DOCLET_MAIN -docletpath $PATH_DOCLET_JAR -pdf $OUTPUT -config $CUSTOM_CONF -sourcepath $SRCDIR $PACKAGES

echo "JavaDoc finished with exit status "$?

if [ $DEL_CONF ] ; then
 echo "Cleanning up"
 rm $CUSTOM_CONF
fi

Usage of gen-pdf-javadoc-pdfdoclet.sh

bash gen-pdf-javadoc-pdfdoclet.sh /home/johny/NetBeansProjects/HelloWorldApp/src/ HelloWorld_pdfdoclet.pdf

Auriga Doclet

Auriga Doclet is a Doclet which can generate Java API Documentation in many formats:
  • Formatting Object(FO)
  • PDF
  • Postscript
  • PCL
  • SVG
The generated javadoc can be customized by specifying a header/footer text and a cover page in XHTML.

Auriga Doclet - how to generate PDF javadoc?

Again it could be much easier, but it can be done - I've also wrote simple bash script to make it easier.

Script gen-pdf-javadoc-auriga.sh

Here is source code (it can also be downloaded from Google Code gen-pdf-javadoc-auriga.sh):
#!/bin/bash


# Author: Tomasz Gawęda - blog.0x1fff.com
# Date:  2009.07.13
# License: BSD
# Description: Simple shell script to generate pdf 
#  javadoc (without ANT) from small
#  Java projects - use under Linux.
#
# Dependicies: Bash
#  Java JDK - 1.6
#  AurigaDoclet jar file (http://sourceforge.net/projects/aurigadoclet/)
#
# Notes: Has to be run from directory where was extracted 
#  (additional libs are needed) catalog - lib/

# Set the JAVA_HOME variable correctly!!!
JAVA_HOME="/usr/lib/jvm/java-6-sun-1.6.0.13"
PATH="$PATH:$JAVA_HOME/bin"
PATH_DOCLET_JAR=bin/AurigaDoclet.jar

## DO NOT EDIT BELOW THIS LINE ##

########################################################
########################################################
########################################################
########################################################
########################################################
########################################################

# check command line args
if [ $# -lt 2 ] ; then 
 echo usage: $0 src-dir new-pdf-file
 exit 1
fi

if [ ! -r $PATH_DOCLET_JAR ] ; then
 echo "FATAL: Unable to find doclet in $PATH_DOCLET_JAR"
 exit 1
fi

DOCLET_MAIN=com.aurigalogic.doclet.core.Doclet
JAVADOC=`which javadoc`
if [ $? -ne 0 ] ; then
 echo "FATAL: Unable to find javadoc in $PATH"
 exit 1
fi
echo "JavaDoc found in $JAVADOC"

SRCDIR=$1
if [ ! -d $SRCDIR ] ; then
 echo "FATAL: Directory $SRCDIR does not exists"
 exit 1
fi
echo "Src directory of program exists ($SRCDIR)"

OUTPUT=$2
if [ -e $OUTPUT ] ; then
 echo "WARNING: Out document exists - will be overwritten ($OUTPUT)"
 echo "WARNING: Got five seconds to break"
 sleep 3
 echo "WARNING: Got two seconds to break"
 sleep 2
 echo "WARNING: Too late ..."
fi


echo "Starting analyzing sources - finding packages"
# find all packages
PACKAGES=`find $SRCDIR -type d -and -not -empty|sed s#$SRCDIR##g | sed s#/#.#g`
echo "Found "`echo $PACKAGES | wc -l `" packages"

export JAVA_HOME PATH DOCLET_MAIN PATH_DOCLET_JAR JAVADOC

echo "Running JavaDoc"

$JAVADOC -doclet $DOCLET_MAIN -docletpath $PATH_DOCLET_JAR -format pdf -out $OUTPUT -sourcepath $SRCDIR $PACKAGES

echo "JavaDoc finished with exit status "$?

Usage of gen-pdf-javadoc-auriga.sh

bash gen-pdf-javadoc-auriga.sh /home/johny/NetBeansProjects/HelloWorldApp/src/ HelloWorld_auriga.pdf

Warning about using Auriga Doclet - pdf generator script

This script have to be run from Auriga Doclet directory!!! (it requires additional third party libs which are not included in jar but are present in lib folder).

Summary

Both projects (PDFDoclet and Auriga Doclet) are doing thweir job with Java 1.6 on Linux. I think more straight forward and with more possibilities to expand is PDF Doclet, but Auriga is also very customizable - both are worth using, but i prefer PDFDoclet :) - mostly because I have only one additional Jar file.

I hope that this article was easy to understand - comments welcome.

18 Jul 2009

Making Ubuntu - Jaunty Gnome Environment a little more friendly for those who remember "old Gnome"

Gnome: Ubuntu Home Folder on desktop - where is it?

It's not in Gnome Desktop distributed with Ubuntu. I really liked home icon on my desktop but in new version (9.04) of Ubuntu I can't find it. The easiest way to enable it back is, running these commands (gconftool-2):
gconftool-2 --type boolean --set /apps/nautilus/desktop/home_icon_visible true
gconftool-2 --type string --set /apps/nautilus/desktop/home_icon_name "Home folder"

... and where is the trash icon?

It has been also disabled by Ubuntu developers :( - if you want it back just run:
gconftool-2 --type boolean --set /apps/nautilus/desktop/trash_icon_visible true
For more possible tweaks of Gnome Desktop you can checkout gconf-editor software, or try to navigate of settings tree from command line (gconftool-2 -R /).

More interesting tweaks

If you're searching for interesting tweaks to your Gnome Desktop you should checkout this entry Gconf - gnome desktop on steroids [EN] or the same in Polish Gconf - a czy ty wiesz jak podrasowac swoj pulpit

Gnome: system wide changing "default action" application

Exact procedure is described in post Changing default applications, but it's done for all users of computer. This is done by few easy steps:
  • edit /usr/share/applications/defaults.list
  • find your entry for example application/pdf=kpdf.desktop and change kpdf.desktop to "something else"
  • remember that "something else" must be in /usr/share/applications

Gnome: Changing "default application" per user

For making user specific change You have to edit file: $HOME/.local/share/applications (syntax is the same as in system wide config). If your application doesn't have an .desktop entry you can easily create it.

Adding custom application support to Gnome (integrating new software)

Creating .desktop file

At the begining you have to create *.desktop file which describes application lunch procedure.

Register new file type in Gnome

Specific informations can be found at system admin guide for version 2.26.

Creating new mime type support in Gnome

Specific informations can be found at system admin guide for version 2.26.

I hope this article is easy to understand - because it is my first public article in English.

13 Jul 2009

Aplikacja do pisania bloga

Dla kogo Windows Live Writer

Jeżeli jesteś autorem blogai tworzysz swoje notki pod systemem Windows - możesz być zainteresowany projektem Windows Live Writer.
Pełna recenzja tego oprogramowania znajduje się tutaj.

Moim zdaniem

Oprogramowanie jest użyteczne - jeżeli bym publikował treści na tym blogu spod systemu Microsoft Windows zapewne bym go używał - bo z tego co się przyjrzałem generuje całkiem przyjemny kod XHTML i pozwala na zapisywanie "Wersji roboczych" artykułów lokalnie jeżeli nie jest dostępne połączenie z internetem.
Bardzo podoba mi się fakt, że piszemy "od razu w swoim blogu" - w żywym podglądzie naszego notatnika. Czyżby darmowy produkt Microsoftu który może być użyteczny dla Bloggerów?
Produkt wart zainteresowania w szczególności dla osób rozpoczynających przygodę z tworzeniem materiału do sieci internet - pozwala na szybkie tworzenie i publikowanie treści w internecie metodą WYSWIG. Otwarto źródłowe aplikacje moim zdaniem nie są tak przyjazne jak Windows Live Writer (ale może nie sprawdziłem wszystkich)?

9 Jul 2009

TP-LINK TD-W8910G - czyli niedrogi sposób na WiFi z ADSL

TP-LINK TD-W8910G

Urządzenie mam już ponad rok (a może dwa?) i jestem zadowolony, skonfigurowałem i leży (czasami trzeba zrobić restart, ale to zdarza się rzadko). Router pracuje pod kontrolą Linuxa wg. nmapa (kernel serii 2.6.x) - co jest już samo w sobie ciekawe - i powoduje, że przy odpowiednim kombinowaniu może by się dało tam zainstalować custom firmware - tak jak jest to w niektórych DLinkach.

Dane techniczne

Dostępne porty1x WAN (RJ-11) - neostrada ; 4x LAN (RJ-45) - switch
Obsługiwane standardyADSL 2+; IEEE 802.11 b/g (WiFi)
Szyfrowanie transmisji bezprzewodowejWEP 64/128/152-bit, WPA/WPA-PSK, WPA2/WPA2-PSK
ZarządzanieWWW, Telnet
DodatkowoNAT, Firewall, Filtrowanie IP/MAC, serwer DNS, możliwość skorzystania z freedns, wykręcana antena, QoS (ale nie korzystałem), Chpset: Atheros
Opis ten nie jest pełny, ale ukazuje cechy na które ja zwracałem uwagę w momencie kupowania sprzętu. W tym sklepie można poczytać o samym modemie więcej.

Co należy zrobić po kupnie?

Ustawić parametry linii dla TP: VPI=0, VCI=35, enkapsulacja=PPPoA VcMUX Polecam zaktualizować firmware, jest on do pobrania z tej strony. Sam upgrade należy wykonywać przez połączenie kablowe! Na stronie są dwie wersje oprogramowania i rodzi się pytanie:

Jaki typ modemu posiadam?

Najprawdopodobniej wersję Annex A.

Czym to się różni Annex A od Annex B?

Sam annex opisuje zakres częstotliwości sygnału w jakim realizowane jest połączenie
Annex A - ITU-T G.992.1 Annex A ADSL over POTS
Wersja standardu ADSL która jest przeznaczona dla zwykłych łączy telefonicznych (POTS). Czyli usługi Neostrada, Netia Net24 - modem działa w paśmie powyżej 25 kHz - by nie nachodzić na sygnał telefoniczny
Annex B - ITU-T G.992.1 Annex B ADSL over ISDN
Wersja standardu ADSL przeznaczona dla sieci cyfrowej z integracją usług (ISDN). Czyli usługi Netia i Dialog. Do ISDN trzeba po prostu modem działający na paśmie wyższym niż 138 kHz żeby nie nachodził na sygnał telefoniczny.

Podsumowanie

Warto zainwestować w router bezprzewodowy TP-LINK TD-W8910G - okazjonalne zwisy nie są raczej przeszkodą (starczy wyciągnąć wtyczkę z prądu i wsadzić ją z powrotem i już jest ok). Router ten raczej nie jest przeznaczony dla klientów instytucjonalnych, ale do domu doskonale się nadaje. Z tego co testowałem pomiędzy piętrami też rozsyła sygnał, a ściany w mieszkaniu (w "wielkiej płycie" nie testowałem) nie są dla niego problemem (zasięg jak dla mnie jest wystarczający, stabilność również). Producent co jakiś czas wypuszcza nowe wersje oprogramowania dla tego urządzenia często zwiększając tym samym jego możliwości.