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 = 3;
  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   "Chroma key (Avid)"   => "Chroma Key \\(Avid\\)",
  71   "Crop & Position"     => "Crop &amp; Position",
  72   "FindObj"             => "Find Object",
  73   "RGB - 601"           => "RGB-601",
  74   "ShiftInterlace"      => "Shift Interlace",
  75   "Cinelerra: Scopes"   => "Videoscope"
  76   );
  77
  78 # Cinelerra installation path
  79 $cin_dat = $ENV{'CIN_DAT'};
  80 $cin_dat = '.' if $cin_dat eq '';
  81
  82 # Cinelerra HTML manual must reside here
  83 $cin_man = "$cin_dat/doc/CinelerraGG_Manual";
  84 $contents = $cin_man.'/'.$contents_node;
  85 #print "ContextManual: using contents $contents\n";
  86
  87 # Cinelerra user's config directory
  88 $cin_config = $ENV{'CIN_CONFIG'};
  89 $cin_config = $ENV{'HOME'}.'/.bcast5'
  90   if $cin_config eq '' && $ENV{'HOME'} ne '';
  91 $cin_config = '.' if $cin_config eq '';
  92 $me_config = "$cin_config/ContextManual.pl";
  93 #print "ContextManual: user script=$me_config\n";
  94
  95 # 1st argument is the requested key
  96 $help_key = $ARGV[0];
  97 #print "ContextManual: request=$help_key\n";
  98 # Do nothing if no key requested
  99 exit 0 if $help_key eq '';
 100
 101 # A special internal request: output own API version
 102 if ($help_key eq 'API')
 103 {
 104   print "$cin_cm_api\n";
 105   exit 0;
 106 }
 107
 108 # If a system (not user's) script instance is executed, and the API versions
 109 # of both scripts do not match, then copy the system script to the user's one
 110 # (making a backup copy of the latter). Then execute it with the same key.
 111 if ($0 ne $me_config)
 112 {
 113   $me_api = 0;
 114   $me_api = `\"$me_config\" API` if -x $me_config;
 115   if ($me_api != $cin_cm_api)
 116   {
 117     print "ContextManual: copying \"$0\" to \"$me_config\"\n";
 118     unlink "$me_config.bak" if -f "$me_config.bak";
 119     rename "$me_config", "$me_config.bak" if -f $me_config;
 120     system "cp \"$0\" \"$me_config\"";
 121     system "chmod +x \"$me_config\"";
 122   }
 123   exec "\"$me_config\" \"$help_key\"" if -x $me_config;
 124 }
 125
 126 # If a user's script instance is executed, do everything by myself
 127 #print "ContextManual: executing \"$0\" \"$help_key\"\n";
 128
 129 # Show contents on this special request
 130 if ($help_key eq 'TOC')
 131 {
 132   system "$cin_browser \"file://$contents\" &";
 133   exit 0;
 134 }
 135 # Show index on this special request
 136 if ($help_key eq 'IDX')
 137 {
 138   # Index node will be needed now, find it
 139   if ($index_node eq '')
 140   {
 141     $node = '';
 142     open CONTENTS, $contents or die "Cannot open $contents: $!";
 143     while (<CONTENTS>)
 144     {
 145       chomp;
 146       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*Index\s*<\/A>(?:<\/B>)?$/;
 147     }
 148     close CONTENTS;
 149     $index_node = $node if $node ne '';
 150     $index_node = 'Index.html' if $index_node eq '';
 151     $index = $cin_man.'/'.$index_node;
 152   }
 153   system "$cin_browser \"file://$index\" &";
 154   exit 0;
 155 }
 156 # Show the named file on this special request
 157 if ($help_key =~ /^FILE:/)
 158 {
 159   $help_key =~ s/^FILE://;
 160   $help_key = $cin_man.'/'.$help_key;
 161   system "$cin_browser \"file://$help_key\" &";
 162   exit 0;
 163 }
 164
 165 $help_key = $rewrite{$help_key} if exists $rewrite{$help_key};
 166 # Do nothing if no key requested
 167 exit 0 if $help_key eq '';
 168 # Show contents on this special request
 169 if ($help_key eq 'TOC')
 170 {
 171   system "$cin_browser \"file://$contents\" &";
 172   exit 0;
 173 }
 174 # Show index on this special request
 175 if ($help_key eq 'IDX')
 176 {
 177   # Index node will be needed now, find it
 178   if ($index_node eq '')
 179   {
 180     $node = '';
 181     open CONTENTS, $contents or die "Cannot open $contents: $!";
 182     while (<CONTENTS>)
 183     {
 184       chomp;
 185       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*Index\s*<\/A>(?:<\/B>)?$/;
 186     }
 187     close CONTENTS;
 188     $index_node = $node if $node ne '';
 189     $index_node = 'Index.html' if $index_node eq '';
 190     $index = $cin_man.'/'.$index_node;
 191   }
 192   system "$cin_browser \"file://$index\" &";
 193   exit 0;
 194 }
 195 # Show the named file on this special request
 196 if ($help_key =~ /^FILE:/)
 197 {
 198   $help_key =~ s/^FILE://;
 199   $help_key = $cin_man.'/'.$help_key;
 200   system "$cin_browser \"file://$help_key\" &";
 201   exit 0;
 202 }
 203
 204 # Now try searching...
 205 open CONTENTS, $contents or die "Cannot open $contents: $!";
 206 $node = '';
 207 # First search contents for the exact key
 208 while (<CONTENTS>)
 209 {
 210   chomp;
 211   last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 212 }
 213 # If not found, search contents for an approximate key
 214 if ($node eq '')
 215 {
 216   seek CONTENTS, 0, 0;
 217   while (<CONTENTS>)
 218   {
 219     chomp;
 220     last if ($node) = /^\s*HREF=\"(.+?\.html)\">.*?$help_key.*?<\/A>$/i;
 221   }
 222 }
 223
 224 # Index node will be needed now, find it
 225 if ($node eq '' && $index_node eq '')
 226 {
 227   seek CONTENTS, 0, 0;
 228   while (<CONTENTS>)
 229   {
 230     chomp;
 231     last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*Index\s*<\/A>(?:<\/B>)?$/;
 232   }
 233   $index_node = $node if $node ne '';
 234   $index_node = 'Index.html' if $index_node eq '';
 235   $index = $cin_man.'/'.$index_node;
 236   $node = '';
 237 }
 238
 239 # If not found, search index for the exact key
 240 if ($node eq '')
 241 {
 242   open INDEX, $index or die "Cannot open $index: $!";
 243   while (<INDEX>)
 244   {
 245     chomp;
 246     # Cut off anchor: xdg-open does not like it
 247     last if ($node) = /<A\s+HREF=\"(.+?\.html)(?:#\d+)?\">\s*$help_key\s*<\/A>$/;
 248     # Retain anchor
 249 #    last if ($node) = /<A\s+HREF=\"(.+?\.html(?:#\d+)?)\">\s*$help_key\s*<\/A>$/;
 250   }
 251   close INDEX;
 252 }
 253 # If not found, search index for an approximate key
 254 if ($node eq '')
 255 {
 256   open INDEX, $index or die "Cannot open $index: $!";
 257   while (<INDEX>)
 258   {
 259     chomp;
 260     # Cut off anchor: xdg-open does not like it
 261     last if ($node) = /<A\s+HREF=\"(.+?\.html)(?:#\d+)?\">.*?$help_key.*?<\/A>$/i;
 262     # Retain anchor
 263 #    last if ($node) = /<A\s+HREF=\"(.+?\.html(?:#\d+)?)\">.*?$help_key.*?<\/A>$/i;
 264   }
 265   close INDEX;
 266 }
 267
 268 # If not found, grep manual for exact key instance
 269 if ($node eq '')
 270 {
 271   $_ = `grep -l \"$help_key\" \"$cin_dat\"/doc/CinelerraGG_Manual/*.html`;
 272   ($node) = split;
 273 }
 274 # If not found, grep manual for case insensitive key instance
 275 if ($node eq '')
 276 {
 277   $_ = `grep -il \"$help_key\" \"$cin_dat\"/doc/CinelerraGG_Manual/*.html`;
 278   ($node) = split;
 279 }
 280
 281 if ($node eq '')
 282 {
 283   if ($help_key =~ /^F_/)
 284   { # If not found, search contents for FFmpeg plugins
 285     $help_key = 'FFmpeg Audio and Video Plugins';
 286     seek CONTENTS, 0, 0;
 287     while (<CONTENTS>)
 288     {
 289       chomp;
 290       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 291     }
 292   }
 293   elsif ($help_key =~ /^L_/)
 294   { # If not found, search contents for LADSPA plugins
 295     $help_key = 'Audio Ladspa Effects';
 296     seek CONTENTS, 0, 0;
 297     while (<CONTENTS>)
 298     {
 299       chomp;
 300       last if ($node) = /^\s*HREF=\"(.+?\.html)\">\s*$help_key\s*<\/A>$/;
 301     }
 302   }
 303 }
 304
 305 close CONTENTS;
 306
 307 # If still nothing found, show contents
 308 $node = $contents_node if $node eq '';
 309 $node = $cin_man.'/'.$node unless $node =~ /\//;
 310 #print "ContextManual: found $node\n";
 311
 312 # Call browser to show the proposed HTML file
 313 system "$cin_browser \"file://$node\" &";
 314
 315 # And immediately return to the caller
 316 exit 0;