You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
251 lines
7.1 KiB
251 lines
7.1 KiB
#! /usr/bin/env perl
|
|
|
|
# kdemangen.pl
|
|
# Copyright (C) 2003 Dominique Devriese <devriese@kde.org>
|
|
|
|
# This program is free software; you can redistribute it and/or
|
|
# modify it under the terms of the GNU General Public License
|
|
# as published by the Free Software Foundation; either version 2
|
|
# of the License, or (at your option) any later version.
|
|
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program; if not, write to the Free Software Foundation, Inc.,
|
|
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
|
|
|
|
|
|
# Here's a little explanation about this script:
|
|
# In order to fix long-standing Debian bug #116485, I've written a
|
|
# script that takes a KDE app, and generates a nice man page.. It uses
|
|
# the app's "--author" and "--help-all" output, along with a description
|
|
# from Debian's control file to get the data. I think the script works
|
|
# great, the man pages look almost hand-written ;) I encourage you all
|
|
# to try this out, and very much welcome any feedback, especially as to
|
|
# how to integrate this into either the Debian KDE packaging system or
|
|
# the KDE build system..
|
|
|
|
# The idea to do this with a script allows us to easily keep the man
|
|
# pages up to date, and is generally very low-trouble for the
|
|
# developer...
|
|
|
|
# The script is attached at the bottom..
|
|
|
|
# USAGE:
|
|
# Suppose you wanted to generate a man page for the KDE-Edu program
|
|
# kalzium.. Then you would
|
|
# 1 cd to /path/to/kde/srcs/tdeedu/debian ( necessary so the script
|
|
# finds the Debian control file.. )
|
|
# 2 run "/path/to/kdemangen.pl $(which kstars) > kstars.1"
|
|
# 3 run "man ./kstars.1" to check out the generated page..
|
|
|
|
# PROBLEMS:
|
|
# Only works for full KDE applications that use KCmdLineArgs (
|
|
# inherent to my approach, but most KDE apps fulfill this requirement
|
|
# )
|
|
|
|
use warnings;
|
|
use strict;
|
|
|
|
sub optionstonroff
|
|
{
|
|
my $options = shift;
|
|
my $ret = "";
|
|
foreach( split /\n/, $options )
|
|
{
|
|
if( /^ (--?[[:alpha:]]+, )?(--[[:alpha:]-]*|-[[:alpha:]])( <[[:alpha:] ]*>| [[:alpha:]]*)? *(.*)$/ )
|
|
{
|
|
my $short;
|
|
my $long;
|
|
my $arg;
|
|
my $desc;
|
|
if( $1 ) { $short = $1; } else { $short = ""; };
|
|
if( $2 ) { $long = $2; } else { $long = ""; };
|
|
if( $3 ) { $arg = $3; } else { $arg = ""; };
|
|
if( $4 ) { $desc = $4; } else { $desc = ""; };
|
|
$short =~ s/-/\\-/g;
|
|
$long =~ s/-/\\-/g;
|
|
$arg =~ s/-/\\-/g;
|
|
$ret .= ".TP\n";
|
|
$ret .= ".B $short $long $arg\n";
|
|
$ret .= "$desc\n";
|
|
}
|
|
elsif( /^ ([[:alpha:]]+) +(.*)$/ )
|
|
{
|
|
$ret .= ".TP\n";
|
|
$ret .= ".B $1\n";
|
|
$ret .= "$2\n";
|
|
}
|
|
elsif( /^ +(.*)$/ )
|
|
{
|
|
$ret .= "$1\n";
|
|
}
|
|
elsif( /^(.*)$/ )
|
|
{
|
|
$ret .= ".SS $1\n";
|
|
# this means a header like "Qt Options:" I'm wondering
|
|
# what to do with this, I don't know enough nroff to
|
|
# format it nicely, I'm affraid..
|
|
}
|
|
}
|
|
return $ret;
|
|
};
|
|
|
|
sub sortoptionsfromnroff {
|
|
# Zack Cerza
|
|
|
|
# Rather than redo Dominique's optionstonroff(), I decided
|
|
# to make this function to sort the options sections created
|
|
# by his function.
|
|
|
|
# What it does is read line-by-line and first determine which
|
|
# section it's looking at via the ".SS <SECTION>" lines. Once
|
|
# it knows, it sets a "$in_<SECTION>" variable to "1" and
|
|
# begins to write the section data into $<SECTION>. When it
|
|
# gets to a line that contains only ".SS ", it sets
|
|
# $in_<SECTION> to "0" and continues.
|
|
|
|
# It's a little messy, but it's the only way I could
|
|
# get it to work with what little knowledge I had.
|
|
|
|
# This is the first time I've used Perl. Be kind.
|
|
|
|
my $options = shift;
|
|
my $ret="";
|
|
|
|
my $in_gen_opts = "0";
|
|
my $gen_opts = "";
|
|
my $in_qt_opts = "0";
|
|
my $qt_opts = "";
|
|
my $in_kde_opts = "0";
|
|
my $kde_opts = "";
|
|
my $in_opts = "0";
|
|
my $opts = "";
|
|
my $in_args = "0";
|
|
my $args = "";
|
|
|
|
foreach ( split /\n/, $options ) {
|
|
if( $in_gen_opts == "1" ) {
|
|
if( /^(\.SS )$/ ) { $in_gen_opts = "0"; }
|
|
$gen_opts .= $_;
|
|
$gen_opts .= "\n";
|
|
}
|
|
if( /^(\.SS.+Generic options:)$/ )
|
|
{ $in_gen_opts = "1"; $gen_opts .= $1; $gen_opts .= "\n"; }
|
|
|
|
if( $in_qt_opts == "1" ) {
|
|
if( /^(\.SS )$/ ) { $in_qt_opts = "0"; }
|
|
$qt_opts .= $_;
|
|
$qt_opts .= "\n";
|
|
}
|
|
if( /^(\.SS.+Qt options:)$/ )
|
|
{ $in_qt_opts = "1"; $qt_opts .= $1; $qt_opts .= "\n"; }
|
|
|
|
if( $in_kde_opts == "1" ) {
|
|
if( /^(\.SS )$/ ) { $in_kde_opts = "0"; }
|
|
$kde_opts .= $_;
|
|
$kde_opts .= "\n";
|
|
}
|
|
if( /^(\.SS.+KDE options:)$/ )
|
|
{ $in_kde_opts = "1"; $kde_opts .= $1; $kde_opts .= "\n"; }
|
|
|
|
if( $in_opts == "1" ) {
|
|
if( /^(\.SS )$/ ) { $in_opts = "0"; }
|
|
$opts .= $_;
|
|
$opts .= "\n";
|
|
}
|
|
if( /^(\.SS.+Options:)$/ )
|
|
{ $in_opts = "1"; $opts .= $1; $opts .= "\n"; }
|
|
|
|
if( $in_args == "1" ) {
|
|
if( /^(\.SS )$/ ) { $in_args = "0"; }
|
|
$args .= $_;
|
|
$args .= "\n";
|
|
}
|
|
if( /^(\.SS.+Arguments:)$/ )
|
|
{ $in_args = "1"; $args .= ".SS\n"; $args .= $1; $args .= "\n"; }
|
|
}
|
|
$ret .= $args;
|
|
$ret .= $opts;
|
|
$ret .= $gen_opts;
|
|
$ret .= $kde_opts;
|
|
$ret .= $qt_opts;
|
|
return $ret;
|
|
};
|
|
|
|
sub usage
|
|
{
|
|
print "This script generates a nice manual page for a KDE app which uses KCmdLineArgs..\n";
|
|
print "USAGE: $0 app\n";
|
|
print "There's more information about how to use this script in the comments at the front of the source..\n"
|
|
};
|
|
|
|
if( $#ARGV < 0 ){
|
|
usage();
|
|
exit 1;
|
|
}
|
|
|
|
my $runapp = "$ARGV[0]";
|
|
if ( ! -x $runapp )
|
|
{
|
|
print "Error: $runapp is not executable.\n";
|
|
exit 1;
|
|
}
|
|
else { $runapp = "KDE_LANG=en_US $runapp"; };
|
|
|
|
my $shortdescription = `$runapp --help | sed -ne '3p'`;
|
|
chomp $shortdescription;
|
|
|
|
my $synopsis = `$runapp --help | sed -n '1p' | sed -e 's/[^:]*: //'`;
|
|
chomp $synopsis;
|
|
$synopsis =~ s/-/\\-/g;
|
|
my $appname = $synopsis;
|
|
$appname =~ s/ .*$//;
|
|
my $ucappname = uc $appname;
|
|
|
|
my $options = `$runapp --help-all | sed -e '1,4d'`;
|
|
$options = optionstonroff( $options );
|
|
$options = sortoptionsfromnroff( $options );
|
|
|
|
my $timespec = ucfirst `date '+%b %G'`;
|
|
chomp $timespec;
|
|
|
|
my $description = $shortdescription;
|
|
if( -r "control" )
|
|
{
|
|
$description = `cat control | sed -ne '/^Description:/,/^\$/p' | egrep -v '^\\w*:.*\$' | sed -e 's/^ //' | sed -e 's/^\\.//'`;
|
|
# leads to problems in some cases :(
|
|
# $description =~ s/KDE ?/\n.SM KDE\n/g;
|
|
}
|
|
|
|
my $authors = `$runapp --author | sed -ne '2,\$p' | sed -e '\$d' | sed -e 's/^ *//'`;
|
|
$authors =~ s/\n/\n.br\n/g;
|
|
|
|
print <<EOF;
|
|
.\\\" This file was generated by kdemangen.pl
|
|
.TH $ucappname 1 \"$timespec\" \"K Desktop Environment\" \"$shortdescription\"
|
|
.SH NAME
|
|
$appname
|
|
\\- $shortdescription
|
|
.SH SYNOPSIS
|
|
$synopsis
|
|
.SH DESCRIPTION
|
|
$description
|
|
.SH OPTIONS
|
|
$options
|
|
.SH SEE ALSO
|
|
Full user documentation is available through the KDE Help Center. You can also enter the URL
|
|
.BR help:/$appname/
|
|
directly into konqueror or you can run
|
|
.BR "`khelpcenter help:/$appname/'"
|
|
from the command-line.
|
|
.br
|
|
.SH AUTHORS
|
|
.nf
|
|
$authors
|
|
EOF
|