1;+
2;
3; NAME:   ONLINE_HELP
4;
5; PURPOSE: accessing the documentation, the general one or for a given
6;          procedure of function (intrinsic or not)
7;
8; CATEGORY: documentation
9;
10; CALLING SEQUENCE:  ( ? or ONLINE_HELP ) or ( ?fft or ONLINE_HELP, 'fft')
11;
12; INPUTS: no mandatory ones
13;
14; OPTIONAL INPUTS: name of a procedure, function or code
15;
16; KEYWORD PARAMETERS:
17;   original ones: book=, context=, full_path=, title=
18;   extensions : ourPdf=ourPdf, nohtml=nohtml, ourTable=ourTable, browser=browser, $
19;                 test=test, debug=debug, help=help, verbose=verbose
20;
21; OUTPUTS: none
22;
23; OPTIONAL OUTPUTS: none
24;
25; COMMON BLOCKS: none
26;
27; SIDE EFFECTS: may or not succeed to start a WEB browser.
28;
29; RESTRICTIONS:
30;
31; 1/ except if a copy of the "GDL.pdf" is locally available
32; and in the !path, an internet connection is mandatory ...
33;
34; 2/ the result is very sensitive to the version of the WEB browser
35; and which plugings (and pluging versions) are available.
36;
37; PROCEDURE: straitforward
38;
39; EXAMPLE:  ONLINE_HELP, 'fft', browser='midori'
40;
41; MODIFICATION HISTORY:
42; -- 01-March-2013: creation by Alain Coulais,
43; -- 18-April-2013: managing the book= keyword, with/out /full_path
44; -- 17-June-2020: AC : better management of "xdg-open"; success to
45; overpass Firefox unsetting MOZ_NO_REMOTE
46;
47; LICENCE: This code is under GNU GPL v2 or later.
48;
49;
50; Very preliminary concept. the goal is to link to internal pages of
51; the PDF file "gdl.pdf" (eventually downloaded if not found)
52; (currently at: http://gnudatalanguage.sourceforge.net/gdl.pdf)
53; and also starting online HTML doc.
54;
55; The PDF file is currently at: http://gnudatalanguage.sourceforge.net/gdl.pdf
56; Following Adobe Documention, direct links to page, chapter shall be possible
57; http://partners.adobe.com/public/developer/en/acrobat/PDFOpenParameters.pdf
58; We use now only the search option ralated to Acroread viewer.
59; Up to now, no equivalent functions inside alternative PDF
60; readers (evince, xpdf) but is is supposed to be OK with "pdf.js"
61; pluging in Firefox https://github.com/mozilla/pdf.js/issues/1875
62;
63; We have to consider to have local HTML version of the documentation.
64;
65; It seems that recent Firefox browsers can be call passing --new-tab
66; / --new-win
67;
68;-
69pro ONLINE_HELP, name, book=book, context=context, full_path=full_path, title=title, $
70                 ourPdf=ourPdf, nohtml=nohtml, ourTable=ourTable, browser=browser, $
71                 path2pdf=path2pdf, path2ourTable=path2ourTable, link2html=link2htlm, $
72                 test=test, debug=debug, help=help, verbose=verbose
73;
74ON_ERROR, 2
75;
76path2pdf='http://aramis.obspm.fr/~coulais/GDL/' ;gdl.pdfhttp://gnudatalanguage.sourceforge.net/'
77path2ourTable='http://aramis.obspm.fr/~coulais/IDL_et_GDL/'
78link2html='http://www.exelisvis.com/docs/'
79
80if ~KEYWORD_SET(test) then ON_ERROR, 2
81;
82if KEYWORD_SET(help) then begin
83   print, 'pro ONLINE_HELP, name, book=book, context=context, full_path=full_path, title=title, $'
84   print, '                 ourPdf=ourPdf, nohtml=nohtml, ourTable=ourTable, browser=browser, $'
85   print, '                 test=test, debug=debug, help=help, verbose=verbose'
86   print, ''
87   return
88endif
89;
90if N_PARAMS() EQ 0 then name=''
91;
92if N_PARAMS() EQ 1 then name=STRCOMPRESS(name,/remove_all)
93;
94; do we have access to X11 ??
95; (we may consider using Lynx (tested succesfully) but is it really
96; useful ?)
97;
98status=EXECUTE('xy=GET_SCREEN_SIZE()')
99if (status EQ 0) then begin
100   MESSAGE, 'Since we are unable to connect to X Windows display, no ONLINE HELP'
101endif
102;
103if KEYWORD_SET(context) then begin
104   MESSAGE, /continue, 'This option (only MSwin) is not available'
105endif
106;
107; setting a default browser if not provided
108; this code was tested with konqueror, midori and firefox
109;
110if ~KEYWORD_SET(browser) then begin
111   ;; classical default !
112   browser='firefox'
113   ;;
114   ;; on some GNU/Linux systems, a BROWSER is defined ...
115   default_browser=GETENV('BROWSER')
116   if (STRLEN(default_browser) GT 0) then browser=default_browser
117   ;;
118   ;; on OSX, it seems to be better to use "open" but this is not
119   ;; working over ssh -X connection ... (suggestion welcome !)
120   ;;
121   if (!version.os EQ 'darwin') then browser='open'
122endif
123;
124; we check if the default or selected brower is in the path
125;
126SPAWN, 'which '+browser, ok, error
127;
128if (STRLEN(ok) EQ 0) then begin
129   MESSAGE, /continue, 'WEB Browser not found : '+browser
130   MESSAGE, 'Please provide the name (+path) to the browser you want to use'
131endif
132;
133space=' '
134quote="'"                       ;'
135qsq=quote+space+quote
136background=' &'
137;
138if KEYWORD_SET(book) then begin
139   ;;
140   ;; when the document is a PDF file, we try to use a PDF viewer
141   ;;
142   idx_suffixe=STRPOS(book, '.', /reverse_search)
143   ;; when the suffixe is not found we need "browser"
144   if (idx_suffixe GE 0) then begin
145      suffixe=STRMID(book, idx_suffixe+1)
146      if STRLOWCASE(suffixe) EQ 'pdf' then begin
147         ;; don't hesitate to complete this list
148         list_of_pdf_viewers=['xpdf','evince','atril','acroread']
149         ;; if we don't locate a PDF viewer, we will use the default (web) Brower
150         for ii=0, N_ELEMENTS(list_of_pdf_viewers)-1 do begin
151            SPAWN, 'which '+list_of_pdf_viewers[ii], ok, error
152            if (STRLEN(ok) NE 0) then begin
153               browser=list_of_pdf_viewers[ii]
154               break
155            endif
156         endfor
157      endif
158   endif
159   if ~KEYWORD_SET(full_path) then begin
160      ;;message, /continue, 'ToDo : managing !HELP_PATH'
161      DEFSYSV, '!HELP_PATH', exist=exist
162      if exist then begin
163         book=FILE_WHICH(!HELP_PATH,book)
164         if (STRLEN(book) EQ 0) then MESSAGE, 'no file found, please check !HELP_PATH and book name'
165      endif else begin
166         ;; falling back to standard multi-tab help
167         MESSAGE, /continue, '!HELP_PATH not set !'
168      endelse
169   endif
170   ;; we have to check whether the file exist or not !!
171   if FILE_TEST(book) then begin
172      command=browser+space+book+background
173      goto, execute_command
174   endif
175endif
176;
177; link to IDL exelis in-line documentation
178;
179link=''
180if ~KEYWORD_SET(nohtml) then begin
181   suffixe='.html'
182   ;;
183   if STRLEN(name) GT 0 then begin
184      link=link2html+STRUPCASE(name)+suffixe
185   endif else begin
186      link=link2html
187   endelse
188endif
189;
190; link to PDF
191; if not found in the !PATH, this file is downloaded the first time
192;
193if KEYWORD_SET(ourPdf) then begin
194   local_pdf=FILE_WHICH(!path, 'gdl.pdf',/include_current_dir)
195   ;;
196   ;; if no "gdl.pdf" in the !Path, trying to download it
197   if STRLEN(local_pdf) EQ 0 then begin
198      script=''
199      SPAWN, 'which wget', res
200      if STRLEN(res) GT 0 then begin
201         script='wget '
202      endif else begin
203         SPAWN, 'which curl', res
204         if STRLEN(res) GT 0 then script='curl -O '
205      endelse
206      if (STRLEN(script) GT 0) then begin
207         SPAWN, script+path2pdf+'gdl.pdf', ok, pb
208      endif
209      local_pdf=FILE_WHICH(!path, 'gdl.pdf',/include_current_dir)
210   endif
211   ;;
212   if (STRLEN(local_pdf) GT 0) then begin
213      if STRLEN(name) GT 0 then begin
214         ;; activating the search capability inside PDF,
215         ;; worked on Acroread pluging
216         ;; should worked withing
217         link='file://'+FILE_EXPAND_PATH(local_pdf)+'#search="'+name+'"'
218      endif else begin
219         link='file://'+FILE_EXPAND_PATH(local_pdf)
220      endelse
221   endif else begin
222      MESSAGE, /continue, 'GDL pdf documentaion not found :('
223   endelse
224endif
225;
226if KEYWORD_SET(ourTable) then begin
227   ;;
228   if (STRLEN(name) GT 0) then begin
229      ;; is it a .PRO file ??
230      pro_file=FILE_WHICH(name+'.pro')
231      if STRLEN(pro_file) GT 0 then begin
232         link='file://'+pro_file
233         link=path2ourTable+'Matrice_IDLvsGDL.html#'+STRUPCASE(STRMID(name,0,1))
234      endif else begin
235         link=path2ourTable+'known_keywords.html#GDL_'+STRUPCASE(name)
236      endelse
237   endif else begin
238      link=path2ourTable+'Matrice_IDLvsGDL.html'
239   endelse
240endif
241;
242if (browser EQ 'firefox') then begin
243
244   command=browser+space+quote+link+quote+background
245endif else begin
246   bsq=browser+space+quote
247   qcs="'; "
248   command=bsq+link+qcs
249endelse
250;
251; line by line the command used by browser
252;
253if keyword_set(verbose) then begin
254   MESSAGE, /continue, 'link2html= : '+link2html
255   MESSAGE, /continue, 'path2pdf = : '+path2pdf
256   MESSAGE, /continue, 'path2ourTable = : '+path2ourTable
257   MESSAGE, /continue, ''
258   MESSAGE, /continue, 'link = : '+link
259   MESSAGE, /continue, ''
260   MESSAGE, /continue, 'the whole command : '+command
261endif
262;
263execute_command:
264;
265if KEYWORD_SET(debug) then begin
266   print, command
267   STOP
268endif
269
270SPAWN, 'unset MOZ_NO_REMOTE; '+command
271;
272if KEYWORD_SET(test) then stop
273;
274end
275