Warning, file /sdk/kde-dev-scripts/kdemangen.pl was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 #! /usr/bin/env perl
0002 
0003 # kdemangen.pl
0004 # Copyright (C)  2003  Dominique Devriese <devriese@kde.org>
0005 
0006 # This program is free software; you can redistribute it and/or
0007 # modify it under the terms of the GNU General Public License
0008 # as published by the Free Software Foundation; either version 2
0009 # of the License, or (at your option) any later version.
0010 
0011 # This program is distributed in the hope that it will be useful,
0012 # but WITHOUT ANY WARRANTY; without even the implied warranty of
0013 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0014 # GNU General Public License for more details.
0015 
0016 # You should have received a copy of the GNU General Public License
0017 # along with this program; if not, write to the Free Software Foundation, Inc.,
0018 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
0019 
0020 
0021 
0022 # Here's a little explanation about this script:
0023 # In order to fix long-standing Debian bug #116485, I've written a
0024 # script that takes a KDE app, and generates a nice man page..  It uses
0025 # the app's "--author" and "--help-all" output, along with a description
0026 # from Debian's control file to get the data.  I think the script works
0027 # great, the man pages look almost hand-written ;) I encourage you all
0028 # to try this out, and very much welcome any feedback, especially as to
0029 # how to integrate this into either the Debian KDE packaging system or
0030 # the KDE build system..
0031 
0032 # The idea to do this with a script allows us to easily keep the man
0033 # pages up to date, and is generally very low-trouble for the
0034 # developer...
0035 
0036 # The script is attached at the bottom..
0037 
0038 # USAGE:
0039 # Suppose you wanted to generate a man page for the KDE-Edu program
0040 # kalzium..  Then you would
0041 # 1 cd to /path/to/kde/srcs/kdeedu/debian  ( necessary so the script
0042 #   finds the Debian control file.. )
0043 # 2 run "/path/to/kdemangen.pl $(which kstars) > kstars.1"
0044 # 3 run "man ./kstars.1" to check out the generated page..
0045 
0046 # PROBLEMS:
0047 # Only works for full KDE applications that use KCmdLineArgs (
0048 # inherent to my approach, but most KDE apps fulfill this requirement
0049 # )
0050 
0051 use warnings;
0052 use strict;
0053 
0054 sub optionstonroff
0055   {
0056     my $options = shift;
0057     my $ret = "";
0058     foreach( split /\n/, $options )
0059       {
0060     if( /^  (--?[[:alpha:]]+, )?(--[[:alpha:]-]*|-[[:alpha:]])( <[[:alpha:] ]*>| [[:alpha:]]*)? *(.*)$/ )
0061       {
0062         my $short;
0063         my $long;
0064         my $arg;
0065         my $desc;
0066         if( $1 ) { $short = $1; } else { $short = ""; };
0067         if( $2 ) { $long = $2; } else { $long = ""; };
0068         if( $3 ) { $arg = $3; } else { $arg = ""; };
0069         if( $4 ) { $desc = $4; } else { $desc = ""; };
0070         $short =~ s/-/\\-/g;
0071         $long =~ s/-/\\-/g;
0072         $arg =~ s/-/\\-/g;
0073         $ret .= ".TP\n";
0074         $ret .= ".B $short $long $arg\n";
0075         $ret .= "$desc\n";
0076       }
0077     elsif( /^  ([[:alpha:]]+) +(.*)$/ )
0078       {
0079         $ret .= ".TP\n";
0080         $ret .= ".B $1\n";
0081         $ret .= "$2\n";
0082       }
0083     elsif( /^ +(.*)$/ )
0084       {
0085         $ret .= "$1\n";
0086       }
0087     elsif( /^(.*)$/ )
0088       {
0089         $ret .= ".SS $1\n";
0090         # this means a header like "Qt Options:" I'm wondering
0091         # what to do with this, I don't know enough nroff to
0092         # format it nicely, I'm affraid..
0093       }
0094       }
0095     return $ret;
0096   };
0097 
0098 sub sortoptionsfromnroff {
0099     # Zack Cerza
0100 
0101     # Rather than redo Dominique's optionstonroff(), I decided
0102     # to make this function to sort the options sections created
0103     # by his function.
0104 
0105     # What it does is read line-by-line and first determine which
0106     # section it's looking at via the ".SS <SECTION>" lines. Once
0107     # it knows, it sets a "$in_<SECTION>" variable to "1" and
0108     # begins to write the section data into $<SECTION>. When it
0109     # gets to a line that contains only ".SS ", it sets
0110     # $in_<SECTION> to "0" and continues.
0111 
0112     # It's a little messy, but it's the only way I could 
0113     # get it to work with what little knowledge I had.
0114 
0115     # This is the first time I've used Perl. Be kind.
0116 
0117     my $options = shift;
0118     my $ret="";
0119 
0120     my $in_gen_opts = "0";
0121     my $gen_opts = "";
0122     my $in_qt_opts = "0";
0123     my $qt_opts = "";
0124     my $in_kde_opts = "0";
0125     my $kde_opts = "";
0126     my $in_opts = "0";
0127     my $opts = "";
0128     my $in_args = "0";
0129     my $args = "";
0130 
0131     foreach ( split /\n/, $options ) {
0132         if( $in_gen_opts == "1" ) {
0133         if( /^(\.SS )$/ ) { $in_gen_opts = "0"; }
0134         $gen_opts .= $_;
0135         $gen_opts .= "\n";
0136     }
0137     if( /^(\.SS.+Generic options:)$/ ) 
0138       { $in_gen_opts = "1"; $gen_opts .= $1; $gen_opts .= "\n"; }
0139       
0140         if( $in_qt_opts == "1" ) {
0141         if( /^(\.SS )$/ ) { $in_qt_opts = "0"; }
0142         $qt_opts .= $_;
0143         $qt_opts .= "\n";
0144     }
0145         if( /^(\.SS.+Qt options:)$/ ) 
0146       { $in_qt_opts = "1"; $qt_opts .= $1; $qt_opts .= "\n"; }
0147 
0148         if( $in_kde_opts == "1" ) {
0149         if( /^(\.SS )$/ ) { $in_kde_opts = "0"; }
0150         $kde_opts .= $_;
0151         $kde_opts .= "\n";
0152     }
0153         if( /^(\.SS.+KDE options:)$/ ) 
0154       { $in_kde_opts = "1"; $kde_opts .= $1; $kde_opts .= "\n"; }
0155         
0156     if( $in_opts == "1" ) {
0157         if( /^(\.SS )$/ ) { $in_opts = "0"; }
0158         $opts .= $_;
0159         $opts .= "\n";
0160     }
0161         if( /^(\.SS.+Options:)$/ ) 
0162       { $in_opts = "1"; $opts .= $1; $opts .= "\n"; }
0163 
0164         if( $in_args == "1" ) {
0165         if( /^(\.SS )$/ ) { $in_args = "0"; }
0166         $args .= $_;
0167         $args .= "\n";
0168     }
0169         if( /^(\.SS.+Arguments:)$/ ) 
0170       { $in_args = "1"; $args .= ".SS\n"; $args .= $1; $args .= "\n"; }
0171       }
0172     $ret .= $args;
0173     $ret .= $opts;
0174     $ret .= $gen_opts;
0175     $ret .= $kde_opts;
0176     $ret .= $qt_opts;
0177     return $ret;
0178   };
0179 
0180 sub usage
0181   {
0182     print "This script generates a nice manual page for a KDE app which uses KCmdLineArgs..\n";
0183     print "USAGE: $0 app\n";
0184     print "There's more information about how to use this script in the comments at the front of the source..\n"
0185   };
0186 
0187 if( $#ARGV < 0 ){
0188   usage();
0189   exit 1;
0190 }
0191 
0192 my $runapp = "$ARGV[0]";
0193 if ( ! -x $runapp )
0194   {
0195     print "Error: $runapp is not executable.\n";
0196     exit 1;
0197   }
0198 else { $runapp = "KDE_LANG=en_US $runapp"; };
0199 
0200 my $shortdescription = `$runapp --help | sed -ne '3p'`;
0201 chomp $shortdescription;
0202 
0203 my $synopsis = `$runapp --help | sed -n '1p' | sed -e 's/[^:]*: //'`;
0204 chomp $synopsis;
0205 $synopsis =~ s/-/\\-/g;
0206 my $appname = $synopsis;
0207 $appname =~ s/ .*$//;
0208 my $ucappname = uc $appname;
0209 
0210 my $options = `$runapp --help-all | sed -e '1,4d'`;
0211 $options = optionstonroff( $options );
0212 $options = sortoptionsfromnroff( $options );
0213 
0214 my $timespec = ucfirst `date '+%b %G'`;
0215 chomp $timespec;
0216 
0217 my $description = $shortdescription;
0218 if( -r "control" )
0219   {
0220     $description = `cat control | sed -ne '/^Description:/,/^\$/p' | egrep -v '^\\w*:.*\$' | sed -e 's/^ //' | sed -e 's/^\\.//'`;
0221 # leads to problems in some cases :(
0222 #    $description =~ s/KDE ?/\n.SM KDE\n/g;
0223   }
0224 
0225 my $authors = `$runapp --author | sed -ne '2,\$p' | sed -e '\$d' | sed -e 's/^ *//'`;
0226 $authors =~ s/\n/\n.br\n/g;
0227 
0228 print <<EOF;
0229 .\\\" This file was generated by kdemangen.pl
0230 .TH $ucappname 1 \"$timespec\" \"KDE\" \"$shortdescription\"
0231 .SH NAME
0232 $appname
0233 \\- $shortdescription
0234 .SH SYNOPSIS
0235 $synopsis
0236 .SH DESCRIPTION
0237 $description
0238 .SH OPTIONS
0239 $options
0240 .SH SEE ALSO
0241 Full user documentation is available through the KDE Help Center.  You can also enter the URL
0242 .BR help:/$appname/
0243 directly into konqueror or you can run 
0244 .BR "`khelpcenter help:/$appname/'"
0245 from the command-line.
0246 .br
0247 .SH AUTHORS
0248 .nf
0249 $authors
0250 EOF