version update
[goodguy/cinelerra.git] / 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;