git.hungrycats.org Git - xscreensaver/blob - hacks/xml2man.pl

   1 #!/usr/bin/perl -w
   2 # Copyright © 2002-2013 Jamie Zawinski <jwz@jwz.org>
   3 #
   4 # Permission to use, copy, modify, distribute, and sell this software and its
   5 # documentation for any purpose is hereby granted without fee, provided that
   6 # the above copyright notice appear in all copies and that both that
   7 # copyright notice and this permission notice appear in supporting
   8 # documentation.  No representations are made about the suitability of this
   9 # software for any purpose.  It is provided "as is" without express or
  10 # implied warranty.
  11 #
  12 # Created: 30-May-2002.
  13 #
  14 # This creates man pages from the XML program descriptions in
  15 # xscreensaver/hacks/config/.
  16 #
  17 # They aren't necessarily the most accurate or well-written man pages,
  18 # but at least they exist.
  19
  20 require 5;
  21 use diagnostics;
  22 use strict;
  23
  24 use Text::Wrap;
  25
  26 my $progname = $0; $progname =~ s@.*/@@g;
  27 my $version = q{ $Revision: 1.4 $ }; $version =~ s/^[^0-9]+([0-9.]+).*$/$1/;
  28
  29 my $verbose = 0;
  30
  31 my $default_args = ("[\\-display \\fIhost:display.screen\\fP]\n" .
  32                     "[\\-visual \\fIvisual\\fP]\n" .
  33                     "[\\-window]\n" .
  34                     "[\\-root]\n");
  35 my $default_options = (".TP 8\n" .
  36                        ".B \\-visual \\fIvisual\\fP\n" .
  37                        "Specify which visual to use.  Legal values " .
  38                        "are the name of a visual class,\n" .
  39                        "or the id number (decimal or hex) of a " .
  40                        "specific visual.\n" .
  41                        ".TP 8\n" .
  42                        ".B \\-window\n" .
  43                        "Draw on a newly-created window.  " .
  44                        "This is the default.\n" .
  45                        ".TP 8\n" .
  46                        ".B \\-root\n" .
  47                        "Draw on the root window.\n");
  48
  49 my $man_suffix = (".SH ENVIRONMENT\n" .
  50                   ".PP\n" .
  51                   ".TP 8\n" .
  52                   ".B DISPLAY\n" .
  53                   "to get the default host and display number.\n" .
  54                   ".TP 8\n" .
  55                   ".B XENVIRONMENT\n" .
  56                   "to get the name of a resource file that overrides " .
  57                   "the global resources\n" .
  58                   "stored in the RESOURCE_MANAGER property.\n" .
  59                   ".SH SEE ALSO\n" .
  60                   ".BR X (1),\n" .
  61                   ".BR xscreensaver (1)\n" .
  62                   ".SH COPYRIGHT\n" .
  63                   "Copyright \\(co %YEAR% by %AUTHOR%.  " .
  64                   "Permission to use, copy, modify, \n" .
  65                   "distribute, and sell this software and its " .
  66                   "documentation for any purpose is \n" .
  67                   "hereby granted without fee, provided that " .
  68                   "the above copyright notice appear \n" .
  69                   "in all copies and that both that copyright " .
  70                   "notice and this permission notice\n" .
  71                   "appear in supporting documentation.  No " .
  72                   "representations are made about the \n" .
  73                   "suitability of this software for any purpose.  " .
  74                   "It is provided \"as is\" without\n" .
  75                   "express or implied warranty.\n" .
  76                   ".SH AUTHOR\n" .
  77                   "%AUTHOR%.\n");
  78
  79 sub xml2man($) {
  80   my ($exe) = @_;
  81   my $cfgdir = (-d "config" ? "config" : "../config");
  82   my $xml = "$cfgdir/$exe.xml";
  83   my $man = "$exe.man";
  84
  85   error ("$exe does not exist") if (! -f $exe);
  86   error ("$xml does not exist") if (! -f $xml);
  87   error ("$man already exists") if (-f $man);
  88
  89   local *IN;
  90   open (IN, "<$xml") || error ("$xml: $!");
  91   my $xmltxt = "";
  92   while (<IN>) { $xmltxt .= $_; }
  93   close IN;
  94
  95   my $args = "";
  96   my $body = "";
  97   my $desc;
  98
  99   $xmltxt =~ s/\s+/ /gs;
 100   $xmltxt =~ s/<!--.*?-->//g;
 101   $xmltxt =~ s@(<[^/])@\n$1@gs;
 102
 103   foreach (split ('\n', $xmltxt)) {
 104     next if m/^$/;
 105     next if m/^<\?xml\b/;
 106     next if m/^<screensaver\b/;
 107     next if m/^<command\b/;
 108     next if m/^<[hv]group\b/;
 109     next if m/^<select\b/;
 110
 111     my ($x,$arg) = m@\barg(|-unset|-set)=\"([^\"]+)\"@;
 112     my ($label)  = m@\b_?label=\"([^\"]+)\"@;
 113     my ($low)    = m@\blow=\"([^\"]+)\"@;
 114     my ($hi)     = m@\bhigh=\"([^\"]+)\"@;
 115     my ($def)    = m@\bdefault=\"([^\"]+)\"@;
 116
 117     $arg =~ s@\s*\%\s*@ \\fInumber\\fP@g if ($arg);
 118
 119     my $carg = $arg;
 120     my $boolp = m/^<boolean/;
 121     my $novalsp = 0;
 122
 123     if ($arg && $arg =~ m/^-no(-.*)/) {
 124       $arg = "$1 | \\$arg";
 125     } elsif ($boolp && $arg) {
 126       $arg = "$arg | \\-no$arg";
 127     }
 128
 129     if ($carg && $carg =~ m/colors/) {
 130       $hi = $low = undef;
 131     }
 132
 133     if (!$carg) {
 134     } elsif ($carg eq '-move' || $carg eq '-no-move' ||
 135              $carg eq '-wander' || $carg eq '-no-wander') {
 136       $label = "Whether the object should wander around the screen.";
 137     } elsif ($boolp && ($carg eq '-spin' || $carg eq '-no-spin')) {
 138       $label = "Whether the object should spin.";
 139     } elsif ($carg eq '-spin X') {
 140       $carg = '-spin \fI[XYZ]\fP';
 141       $arg = $carg;
 142       $label = "Around which axes should the object spin?";
 143     } elsif ($carg eq '-fps' || $carg eq '-no-fps') {
 144       $label = "Whether to show a frames-per-second display " .
 145                "at the bottom of the screen.";
 146     } elsif ($carg eq '-wireframe' || $carg eq '-wire') {
 147       $label = "Render in wireframe instead of solid.";
 148     } elsif ($carg =~ m/^-delay/ && $hi && $hi >= 10000) {
 149       $label = "Per-frame delay, in microseconds.";
 150       $def = sprintf ("%d (%0.2f seconds)", $def, ($def/1000000.0));
 151       $low = $hi = undef;
 152     } elsif ($carg eq '-speed \fInumber\fP') {
 153       $label = "Animation speed.  2.0 means twice as fast, " .
 154                "0.5 means half as fast.";
 155       $novalsp = 1;
 156     } elsif ($boolp) {
 157       $label .= ".  Boolean.";
 158     } elsif ($label) {
 159       $label .= ".";
 160     }
 161
 162     if (m/^<(number|boolean|option)/) {
 163
 164       next if (!$arg && m/<option/);
 165       if (!$label) {
 166         print STDERR "$progname: ERROR: no label: $_\n";
 167         $label = "???";
 168       }
 169
 170       $args .= "[\\$carg]\n";
 171
 172       if (! $novalsp) {
 173         $label .= "  $low - $hi." if (defined($low) && defined($hi));
 174         $label .= "  Default: $def." if (defined ($def));
 175       }
 176       $label = wrap ("", "", $label);
 177
 178       $body .= ".TP 8\n.B \\$arg\n$label";
 179       $body .= "\n";
 180
 181     } elsif (m@^<_description>\s*(.*)\s*</_description>@) {
 182       $desc = $1;
 183     } else {
 184       print STDERR "$progname: ERROR: UNKNOWN: $_\n";
 185     }
 186   }
 187
 188   $desc = "Something pretty." unless $desc;
 189
 190   my $author = undef;
 191   if ($desc =~ m@^(.*?)\s*(Written by|By) ([^.]+\.?\s*)$@s) {
 192     $desc = $1;
 193     $author = $3;
 194     $author =~ s/\s*[.]\s*$//;
 195   }
 196
 197   if (!$author) {
 198     print STDERR "$progname: $exe: WARNING: unknown author\n";
 199     $author = "UNKNOWN";
 200   }
 201
 202   $desc =~ s@http://en\.wikipedia\.org/[^\s]+@@gs;
 203
 204   $desc = wrap ("", "", $desc);
 205
 206   $body = (".TH XScreenSaver 1 \"\" \"X Version 11\"\n" .
 207            ".SH NAME\n" .
 208            "$exe - screen saver.\n" .
 209            ".SH SYNOPSIS\n" .
 210            ".B $exe\n" .
 211            $default_args .
 212            $args .
 213            ".SH DESCRIPTION\n" .
 214            $desc . "\n" .
 215            ".SH OPTIONS\n" .
 216            $default_options .
 217            $body .
 218            $man_suffix);
 219
 220   my $year = $1 if ($author =~ s/; (\d{4})$//s);
 221   $year = (localtime)[5] + 1900 unless $year;
 222
 223   $body =~ s/%AUTHOR%/$author/g;
 224   $body =~ s/%YEAR%/$year/g;
 225
 226 #print $body; exit 0;
 227
 228   local *OUT;
 229   open (OUT, ">$man") || error ("$man: $!");
 230   print OUT $body || error ("$man: $!");
 231   close OUT || error ("$man: $!");
 232   print STDERR "$progname: wrote $man\n";
 233 }
 234
 235
 236 sub error($) {
 237   my ($err) = @_;
 238   print STDERR "$progname: $err\n";
 239   exit 1;
 240 }
 241
 242 sub usage() {
 243   print STDERR "usage: $progname [--verbose] programs...\n";
 244   exit 1;
 245 }
 246
 247 sub main() {
 248   my @progs = ();
 249   while ($_ = $ARGV[0]) {
 250     shift @ARGV;
 251     if ($_ eq "--verbose") { $verbose++; }
 252     elsif (m/^-v+$/) { $verbose += length($_)-1; }
 253     elsif (m/^-./) { usage; }
 254     else { push @progs, $_; }
 255   }
 256
 257   usage() if ($#progs < 0);
 258
 259   foreach (@progs) { xml2man($_); }
 260 }
 261
 262 main();
 263 exit 0;