cinelerra-5.1/doc/ContextManual.pl

 1 #!/usr/bin/perl
 2
 3 # Helper script for context help in Cinelerra
 4 # Calling: ContextManual.pl "<help keyphrase>"
 5 # Searches the requested key in the following order:
 6 # 1) manual Contents
 7 # 2) manual Index
 8 # 3) all manual pages via grep
 9 # 4) FFmpeg or Ladspa plugins
 10 # The first item found is shown via the default web browser
 11 # If nothing found, the Contents itself is shown
 12 # On empty keyphrase do nothing
 13 # The special keyphrase "TOC" shows Contents, "IDX" shows Index
 14 # The keyphrase starting with "FILE:" shows the file named after colon
 15 # The special keyphrase "API" shows the numeric version of the script itself
 16
 17 # Several important definitions
 18
 19 # ContextManual.pl script API version. Must not be changed !
 20 $cin_cm_api = 2;
 21
 22 # Web browser executable, can be redefined on user's demand
 23 $cin_browser = $ENV{'CIN_BROWSER'};
 24 # a likely default browser
 25 $cin_browser = 'firefox' if $cin_browser eq '';
 26 # another possible browser
 27 #$cin_browser = 'xdg-open' if $cin_browser eq '';
 28 # a fake browser for debugging
 29 #$cin_browser = 'echo';
 30
 31 # The following definitions depend on the HTML manual structure
 32 # There is nothing to change below this line
 33
 34 # The node with the manual contents
 35 $contents_node = 'Contents.html';
 36
 37 # The node with the actual index if needed will be found after parsing contents
 38 $index_node = '';
 39 $index = '';
 40
 41 # Several special plugin names necessary to rewrite
 42 %rewrite = (
 43   # Rendered effects and transitions are not segmented in the Contents
 44   "CD Ripper"           => "Rendered Audio Effects",
 45   "Normalize"           => "Rendered Audio Effects",
 46   "Resample"            => "Rendered Audio Effects",
 47   "Time stretch"        => "Rendered Audio Effects",
 48
 49   "720 to 480"          => "Rendered Video Effects",
 50   "Reframe"             => "Rendered Video Effects",
 51
 52   # Audio transitions are segmented in the Index
 53 #  "Crossfade"           => "Audio Transitions",
 54
 55   # Video transitions are segmented in the Index
 56 #  "BandSlide"           => "Video Transitions",
 57 #  "BandWipe"            => "Video Transitions",
 58 #  "Dissolve"            => "Video Transitions",
 59 #  "Flash"               => "Video Transitions",
 60 #  "IrisSquare"          => "Video Transitions",
 61 #  "Shape Wipe"          => "Video Transitions",
 62 #  "Slide"               => "Video Transitions",
 63 #  "Wipe"                => "Video Transitions",
 64 #  "Zoom"                => "Video Transitions",
 65
 66   # Several not properly matched names
 67   "AgingTV"             => "Aging TV",
 68   "Brightness/Contrast" => "Brightness\\/Contrast",
 69   "Chroma key (HSV)"    => "Chroma Key \\(HSV\\)",
 70   "Crop & Position"     => "Crop &amp; Position",
 71   "FindObj"             => "Find Object",
 72   "RGB - 601"           => "RGB-601",
 73   "ShiftInterlace"      => "Shift Interlace",
 74   "Cinelerra: Scopes"   => "Videoscope"
 75   );
 76
 77 # Cinelerra installation path
 78 $cin_dat = $ENV{'CIN_DAT'};
 79 $cin_dat = '.' if $cin_dat eq '';
 80
 81 # Cinelerra HTML manual must reside here
 82 $cin_man = "$cin_dat/doc/CinelerraGG_Manual";
 83 $contents = $cin_man.'/'.$contents_node;
 84 #print "ContextManual: using contents $contents\n";
 85
 86 # Cinelerra user's config directory
 87 $cin_config = $ENV{'CIN_CONFIG'};
 88 $cin_config = $ENV{'HOME'}.'/.bcast5'
 89   if $cin_config eq '' && $ENV{'HOME'} ne '';
 90 $cin_config = '.' if $cin_config eq '';
 91 $me_config = "$cin_config/ContextManual.pl";
 92 #print "ContextManual: user script=$me_config\n";
 93
 94 # 1st argument is the requested key
 95 $help_key = $ARGV[0];
 96 #print "ContextManual: request=$help_key\n";
 97 # Do nothing if no key requested
 98 exit 0 if $help_key eq '';
 99
 100 # A special internal request: output own API version
 101 if ($help_key eq 'API')
 102 {
 103   print "$cin_cm_api\n";
 104   exit 0;
 105 }
 106
 107 # If a system (not user's) script instance is executed, and the API versions
 108 # of both scripts do not match, then copy the system script to the user's one
 109 # (making a backup copy of the latter). Then execute it with the same key.
 110 if ($0 ne $me_config)
 111 {
 112   $me_api = 0;
 113   $me_api = `\"$me_config\" API` if -x $me_config;
 114   if ($me_api != $cin_cm_api)
 115   {
 116     print "ContextManual: copying \"$0\" to \"$me_config\"\n";
 117     unlink "$me_config.bak" if -f "$me_config.bak";
 118     rename "$me_config", "$me_config.bak" if -f $me_config;
 119     system "cp \"$0\" \"$me_config\"";
 120     system "chmod +x \"$me_config\"";
 121   }
 122   exec "\"$me_config\" \"$help_key\"" if -x $me_config;
 123 }
 124
 125 # If a user's script instance is executed, do everything by myself
 126 #print "ContextManual: executing \"$0\" \"$help_key\"\n";
 127
 128 # Show contents on this special request
 129 if ($help_key eq 'TOC')
 130 {
 131   system "$cin_browser \"file://$contents\" &";
 132   exit 0;
 133 }
 134 # Show index on this special request
 135 if ($help_key eq 'IDX')
 136 {
 137   # Index node will be needed now, find it
 138   if ($index_node eq '')
 139   {
 140     $node = '';
 141     open CONTENTS, $contents or die "Cannot open $contents: $!";
 142     while (<CONTENTS>)
 143     {
 144       chomp;
 145       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*Index\s*<\/A>(?:<\/B>)?$/;
 146     }
 147     close CONTENTS;
 148     $index_node = $node if $node ne '';
 149     $index_node = 'Index.html' if $index_node eq '';
 150     $index = $cin_man.'/'.$index_node;
 151   }
 152   system "$cin_browser \"file://$index\" &";
 153   exit 0;
 154 }
 155 # Show the named file on this special request
 156 if ($help_key =~ /^FILE:/)
 157 {
 158   $help_key =~ s/^FILE://;
 159   $help_key = $cin_man.'/'.$help_key;
 160   system "$cin_browser \"file://$help_key\" &";
 161   exit 0;
 162 }
 163
 164 $help_key = $rewrite{$help_key} if exists $rewrite{$help_key};
 165 # Do nothing if no key requested
 166 exit 0 if $help_key eq '';
 167 # Show contents on this special request
 168 if ($help_key eq 'TOC')
 169 {
 170   system "$cin_browser \"file://$contents\" &";
 171   exit 0;
 172 }
 173 # Show index on this special request
 174 if ($help_key eq 'IDX')
 175 {
 176   # Index node will be needed now, find it
 177   if ($index_node eq '')
 178   {
 179     $node = '';
 180     open CONTENTS, $contents or die "Cannot open $contents: $!";
 181     while (<CONTENTS>)
 182     {
 183       chomp;
 184       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*Index\s*<\/A>(?:<\/B>)?$/;
 185     }
 186     close CONTENTS;
 187     $index_node = $node if $node ne '';
 188     $index_node = 'Index.html' if $index_node eq '';
 189     $index = $cin_man.'/'.$index_node;
 190   }
 191   system "$cin_browser \"file://$index\" &";
 192   exit 0;
 193 }
 194 # Show the named file on this special request
 195 if ($help_key =~ /^FILE:/)
 196 {
 197   $help_key =~ s/^FILE://;
 198   $help_key = $cin_man.'/'.$help_key;
 199   system "$cin_browser \"file://$help_key\" &";
 200   exit 0;
 201 }
 202
 203 # Now try searching...
 204 open CONTENTS, $contents or die "Cannot open $contents: $!";
 205 $node = '';
 206 # First search contents for the exact key
 207 while (<CONTENTS>)
 208 {
 209   chomp;
 210   last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 211 }
 212 # If not found, search contents for an approximate key
 213 if ($node eq '')
 214 {
 215   seek CONTENTS, 0, 0;
 216   while (<CONTENTS>)
 217   {
 218     chomp;
 219     last if ($node) = /^\s*HREF=\"(.+?\.html)\">.*?$help_key.*?<\/A>$/i;
 220   }
 221 }
 222
 223 # Index node will be needed now, find it
 224 if ($node eq '' && $index_node eq '')
 225 {
 226   seek CONTENTS, 0, 0;
 227   while (<CONTENTS>)
 228   {
 229     chomp;
 230     last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*Index\s*<\/A>(?:<\/B>)?$/;
 231   }
 232   $index_node = $node if $node ne '';
 233   $index_node = 'Index.html' if $index_node eq '';
 234   $index = $cin_man.'/'.$index_node;
 235   $node = '';
 236 }
 237
 238 # If not found, search index for the exact key
 239 if ($node eq '')
 240 {
 241   open INDEX, $index or die "Cannot open $index: $!";
 242   while (<INDEX>)
 243   {
 244     chomp;
 245     # Cut off anchor: xdg-open does not like it
 246     last if ($node) = /<A\s+HREF=\"(.+?\.html)(?:#\d+)?\">\s*$help_key\s*<\/A>$/;
 247     # Retain anchor
 248 #    last if ($node) = /<A\s+HREF=\"(.+?\.html(?:#\d+)?)\">\s*$help_key\s*<\/A>$/;
 249   }
 250   close INDEX;
 251 }
 252 # If not found, search index for an approximate key
 253 if ($node eq '')
 254 {
 255   open INDEX, $index or die "Cannot open $index: $!";
 256   while (<INDEX>)
 257   {
 258     chomp;
 259     # Cut off anchor: xdg-open does not like it
 260     last if ($node) = /<A\s+HREF=\"(.+?\.html)(?:#\d+)?\">.*?$help_key.*?<\/A>$/i;
 261     # Retain anchor
 262 #    last if ($node) = /<A\s+HREF=\"(.+?\.html(?:#\d+)?)\">.*?$help_key.*?<\/A>$/i;
 263   }
 264   close INDEX;
 265 }
 266
 267 # If not found, grep manual for exact key instance
 268 if ($node eq '')
 269 {
 270   $_ = `grep -l \"$help_key\" \"$cin_dat\"/doc/CinelerraGG_Manual/*.html`;
 271   ($node) = split;
 272 }
 273 # If not found, grep manual for case insensitive key instance
 274 if ($node eq '')
 275 {
 276   $_ = `grep -il \"$help_key\" \"$cin_dat\"/doc/CinelerraGG_Manual/*.html`;
 277   ($node) = split;
 278 }
 279
 280 if ($node eq '')
 281 {
 282   if ($help_key =~ /^F_/)
 283   { # If not found, search contents for FFmpeg plugins
 284     $help_key = 'FFmpeg Audio and Video Plugins';
 285     seek CONTENTS, 0, 0;
 286     while (<CONTENTS>)
 287     {
 288       chomp;
 289       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 290     }
 291   }
 292   elsif ($help_key =~ /^L_/)
 293   { # If not found, search contents for LADSPA plugins
 294     $help_key = 'Audio Ladspa Effects';
 295     seek CONTENTS, 0, 0;
 296     while (<CONTENTS>)
 297     {
 298       chomp;
 299       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 300     }
 301   }
 302 }
 303
 304 close CONTENTS;
 305
 306 # If still nothing found, show contents
 307 $node = $contents_node if $node eq '';
 308 $node = $cin_man.'/'.$node unless $node =~ /\//;
 309 #print "ContextManual: found $node\n";
 310
 311 # Call browser to show the proposed HTML file
 312 system "$cin_browser \"file://$node\" &";
 313
 314 # And immediately return to the caller
 315 exit 0;