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 = 1;
  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 manual index
  38 $index_node = 'Index.html';
  39
  40 # Several special plugin names necessary to rewrite
  41 %rewrite = (
  42   # Rendered effects and transitions are not segmented in the Contents
  43   "CD Ripper"           => "Rendered Audio Effects",
  44   "Normalize"           => "Rendered Audio Effects",
  45   "Resample"            => "Rendered Audio Effects",
  46   "Time stretch"        => "Rendered Audio Effects",
  47
  48   "720 to 480"          => "Rendered Video Effects",
  49   "Reframe"             => "Rendered Video Effects",
  50
  51   # Audio transitions are segmented in the Index
  52 #  "Crossfade"           => "Audio Transitions",
  53
  54   # Video transitions are segmented in the Index
  55 #  "BandSlide"           => "Video Transitions",
  56 #  "BandWipe"            => "Video Transitions",
  57 #  "Dissolve"            => "Video Transitions",
  58 #  "Flash"               => "Video Transitions",
  59 #  "IrisSquare"          => "Video Transitions",
  60 #  "Shape Wipe"          => "Video Transitions",
  61 #  "Slide"               => "Video Transitions",
  62 #  "Wipe"                => "Video Transitions",
  63 #  "Zoom"                => "Video Transitions",
  64
  65   # Several not properly matched names
  66   "AgingTV"             => "Aging TV",
  67   "Brightness/Contrast" => "Brightness\\/Contrast",
  68   "Chroma key (HSV)"    => "Chroma Key \\(HSV\\)",
  69   "Crop & Position"     => "Crop &amp; Position",
  70   "FindObj"             => "Find Object",
  71   "RGB - 601"           => "RGB-601",
  72   "ShiftInterlace"      => "Shift Interlace",
  73   "Cinelerra: Scopes"   => "Videoscope"
  74   );
  75
  76 # Cinelerra installation path
  77 $cin_dat = $ENV{'CIN_DAT'};
  78 $cin_dat = '.' if $cin_dat eq '';
  79
  80 # Cinelerra HTML manual must reside here
  81 $cin_man = "$cin_dat/doc/CinelerraGG_Manual";
  82 $contents = $cin_man.'/'.$contents_node;
  83 $index = $cin_man.'/'.$index_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   system "$cin_browser \"file://$index\" &";
 138   exit 0;
 139 }
 140 # Show the named file on this special request
 141 if ($help_key =~ /^FILE:/)
 142 {
 143   $help_key =~ s/^FILE://;
 144   $help_key = $cin_man.'/'.$help_key;
 145   system "$cin_browser \"file://$help_key\" &";
 146   exit 0;
 147 }
 148
 149 $help_key = $rewrite{$help_key} if exists $rewrite{$help_key};
 150 # Do nothing if no key requested
 151 exit 0 if $help_key eq '';
 152 # Show contents on this special request
 153 if ($help_key eq 'TOC')
 154 {
 155   system "$cin_browser \"file://$contents\" &";
 156   exit 0;
 157 }
 158 # Show index on this special request
 159 if ($help_key eq 'IDX')
 160 {
 161   system "$cin_browser \"file://$index\" &";
 162   exit 0;
 163 }
 164 # Show the named file on this special request
 165 if ($help_key =~ /^FILE:/)
 166 {
 167   $help_key =~ s/^FILE://;
 168   $help_key = $cin_man.'/'.$help_key;
 169   system "$cin_browser \"file://$help_key\" &";
 170   exit 0;
 171 }
 172
 173 # Now try searching...
 174 open CONTENTS, $contents or die "Cannot open $contents: $!";
 175 $node = '';
 176 # First search contents for the exact key
 177 while (<CONTENTS>)
 178 {
 179   chomp;
 180   last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 181 }
 182 # If not found, search contents for an approximate key
 183 if ($node eq '')
 184 {
 185   seek CONTENTS, 0, 0;
 186   while (<CONTENTS>)
 187   {
 188     chomp;
 189     last if ($node) = /^\s*HREF=\"(.+?\.html)\">.*?$help_key.*?<\/A>$/i;
 190   }
 191 }
 192
 193 # If not found, search index for the exact key
 194 if ($node eq '')
 195 {
 196   open INDEX, $index or die "Cannot open $index: $!";
 197   while (<INDEX>)
 198   {
 199     chomp;
 200     # Cut off anchor: xdg-open does not like it
 201     last if ($node) = /<A\s+HREF=\"(.+?\.html)(?:#\d+)?\">\s*$help_key\s*<\/A>$/;
 202     # Retain anchor
 203 #    last if ($node) = /<A\s+HREF=\"(.+?\.html(?:#\d+)?)\">\s*$help_key\s*<\/A>$/;
 204   }
 205   close INDEX;
 206 }
 207 # If not found, search index for an approximate key
 208 if ($node eq '')
 209 {
 210   open INDEX, $index or die "Cannot open $index: $!";
 211   while (<INDEX>)
 212   {
 213     chomp;
 214     # Cut off anchor: xdg-open does not like it
 215     last if ($node) = /<A\s+HREF=\"(.+?\.html)(?:#\d+)?\">.*?$help_key.*?<\/A>$/i;
 216     # Retain anchor
 217 #    last if ($node) = /<A\s+HREF=\"(.+?\.html(?:#\d+)?)\">.*?$help_key.*?<\/A>$/i;
 218   }
 219   close INDEX;
 220 }
 221
 222 # If not found, grep manual for exact key instance
 223 if ($node eq '')
 224 {
 225   $_ = `grep -l \"$help_key\" \"$cin_dat\"/doc/CinelerraGG_Manual/*.html`;
 226   ($node) = split;
 227 }
 228 # If not found, grep manual for case insensitive key instance
 229 if ($node eq '')
 230 {
 231   $_ = `grep -il \"$help_key\" \"$cin_dat\"/doc/CinelerraGG_Manual/*.html`;
 232   ($node) = split;
 233 }
 234
 235 if ($node eq '')
 236 {
 237   if ($help_key =~ /^F_/)
 238   { # If not found, search contents for FFmpeg plugins
 239     $help_key = 'FFmpeg Audio and Video Plugins';
 240     seek CONTENTS, 0, 0;
 241     while (<CONTENTS>)
 242     {
 243       chomp;
 244       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 245     }
 246   }
 247   elsif ($help_key =~ /^L_/)
 248   { # If not found, search contents for LADSPA plugins
 249     $help_key = 'Audio Ladspa Effects';
 250     seek CONTENTS, 0, 0;
 251     while (<CONTENTS>)
 252     {
 253       chomp;
 254       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 255     }
 256   }
 257 }
 258
 259 close CONTENTS;
 260
 261 # If still nothing found, show contents
 262 $node = $contents_node if $node eq '';
 263 $node = $cin_man.'/'.$node unless $node =~ /\//;
 264 #print "ContextManual: found $node\n";
 265
 266 # Call browser to show the proposed HTML file
 267 system "$cin_browser \"file://$node\" &";
 268
 269 # And immediately return to the caller
 270 exit 0;