source: trunk/SRC/Documentation/xmldoc/doidldoc.sh @ 430

Last change on this file since 430 was 430, checked in by pinsard, 14 years ago

indent shell scripts
  • Property svn:executable set to *
  • Property svn:keyword set to Id
  • Property svn:keywords set to Id
File size: 17.5 KB
Line 
1#! /bin/sh
2#+
3#
4# NAME
5# ====
6#
7# idldoc.sh - build idldoc documentations
8#
9# SYNOPSYS
10# ========
11#
12# ``doidldoc.sh -i indir -t title -o outdir -idl_dir idl_dir -idldoc_version idldoc_version -idldoc_dir idldoc_dir -e element -r refhtlm``
13#
14# DESCRIPTION
15# ===========
16#
17# Produce HTML files from IDL sources using idldoc.
18#
19# -i directory input
20# -t title
21# -o directory output
22# -idl_dir idl_dir
23# -idldoc_version idldoc_version
24# -idldoc_dir idldoc_dir
25# -e element
26# -r refhtml
27#
28# Two passes : first *classic* idldoc then some home made transformation
29# to avoid for example version of idldoc on each HTML files.
30#
31# The first pass produce files in /tmp/idldoc_output_${$}/ directory.
32#
33# At the end the result is in ``outdir``.
34#
35# By default, embedded ``idldoc`` 2.0 in SAXO is used.
36#
37# You can specified an other ``idldoc`` implentation by specify directory and
38# version using *idldoc_dir* and *idldoc_version*.
39#
40# Be warned that assitant help is only available with ``idldoc 2.0``.
41#
42# Must be run two times to resolve internal links.
43#
44# CAUTIONS
45# ========
46#
47# SAXO_DIR must be set. The value should be the directory where
48# SAXO is available.
49#
50# for example, if you work at LOCEAN and work with default SAXO,
51# SAXO_DIR=/usr/home/smasson/SAXO_DIR/.
52#
53# For working in progress, you should checkout SAXO on a personnal
54# directory and set SAXO_DIR to the working space.
55#
56# example for me : SAXO_DIR=/usr/lodyc/incas/fplod/SAXO_DIR_ws/
57#
58# EXAMPLES
59# ========
60#
61# Results can be seen be opening a browser on /tmp/idldoc_html_output/index.html
62#
63# To produce SAXO HTML outputs :
64# ::
65#
66# $ cd ${SAXO_DIR}/SRC/Documentation/xmldoc/
67# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i ../.. -t "SAXO Documentation" -o ../idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help
68#
69#
70# To produce GEOMAG HTML outputs :
71# ::
72#
73# $ cd /usr/home/fplod/incas/geomag/geomag_ws/
74# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i . -t "GEOMAG Documentation" -o /usr/work/incas/${LOGNAME}/geomag/idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help -e progeomag -r /usr/work/incas/${LOGNAME}/idldoc_html_output/
75
76#
77# To produce VARAMMA HTML outputs :
78# ::
79#
80# $ cd /usr/home/fplod/incas/varamma/varamma_ws/
81# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i . -t "VARAMMA Documentation" -o /tmp/idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help
82#
83# To produce POST_IT HTML outputs :
84# ::
85#
86# $ cd /usr/lodyc/incas/fplod/post_it_ws/
87# $ ${SAXO_DIR}/SRC/Documentation/xmldoc/doidldoc.sh -i . -t "POST_IT/Documentation" -o /usr/work/incas/${LOGNAME}/idldoc_html_output/ -idl_dir /usr/local_linux/idl/idl_6.4/idl/ -e pro -r ${SAXO_DIR}/SRC/Documentation/idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help -e propost_it -r /usr/work/incas/${LOGNAME}/idldoc_html_output/
88#
89# TODO
90# ====
91#
92# ++ choix de la version de idldoc et consequences sur assistant
93#
94# ++ choix de la version de IDL et consequences sur assistant et lien sur
95# doc idl
96#
97# add checking of consistency between numbers of -e and -r parameters
98#
99# SEE ALSO
100# ========
101#
102# idldoc++ lien
103#
104# pro2href.sh
105#
106# EVOLUTIONS
107# ==========
108#
109# $Id$
110#
111# - fplod 20100125T105849Z aedon.locean-ipsl.upmc.fr (Darwin)
112#
113#   * add -e and -r parameters to replace hardcoded element and reference
114#     of links
115#
116# - fplod 20091112T101526Z zeus.locean-ipsl.upmc.fr (Linux)
117#
118#   * replace mv by cp -r because mv may no works accross filesystems
119#   * add chek on outdir
120#
121# - fplod 20091112T084225Z aedon.locean-ipsl.upmc.fr (Darwin)
122#
123#   * bug fix if indir is set to '.'
124#   * idl_dir in parameter
125#   * path of local commands
126#
127# - fplod 20091110T151839Z aedon.locean-ipsl.upmc.fr (Darwin)
128#   
129#   * add CAUTIONS about SAXO_DIR environment variable
130#     and usage in EXAMPLES
131#
132# - ++
133#
134# * add idldoc_version and idldoc_dir parameters
135# idldoc version is usefull because parameters of ``idldoc``
136# have been modified (see ``CHARSET`` in 3.1.1.).
137#
138# ``idldoc`` release can not be guessed
139#
140# - fplod 2008-08-11T12:57:48Z aedon.locean-ipsl.upmc.fr (Darwin)
141#
142# * comments in this file in ReST format
143# * add ``-i``, ``-t`` and ``-o`` parameters
144#
145# - fplod 2008-06-20T13:07:59Z aedon.locean-ipsl.upmc.fr (Darwin)
146#
147# * evaluation version 3.1.1
148#
149# we are not yet still ready to migrate to rst format because of lack of
150# assistant transformation independant of IDLdoc release (at least
151# between 2. and 3.)
152#
153# - fplod 2008-01-10T08:13:41Z aedon.locean-ipsl.upmc.fr (Darwin)
154#
155# * version http://cookbook.idldev.com/idldoc-3.0rc2.zip
156#
157# - fplod 2008-01-03T09:59:18Z aedon.locean-ipsl.upmc.fr (Darwin)
158#
159# * version http://cookbook.idldev.com/idldoc-3.0rc1.zip
160#
161# - fplod 2007-12-12T09:47:04Z aedon.locean-ipsl.upmc.fr (Darwin)
162#
163# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4.zip
164#
165# - fplod 2007-12-11T09:14:04Z aedon.locean-ipsl.upmc.fr (Darwin)
166#
167# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4-src.zip
168# * ++ pb path
169# * beginning of docbook templates writing (from html 3.0b3 tt files)
170#
171# - fplod 2007-12-10T09:28:11Z aedon.locean-ipsl.upmc.fr (Darwin)
172#
173# * test with gdl : pas possible car compatibility < 6.1
174#
175# - fplod 2007-12-04T09:21:18Z aedon.locean-ipsl.upmc.fr (Darwin)
176#
177# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b3.zip
178# * pb parser if ; after ;-
179# * ++ plus de param et keyword dans l'index
180# * ++ pas w3c tilte au lieu de title, pas de charset, pas de alt, pas de summary
181# * ++ css pas ok
182# * ++ plus de @restrictions
183#
184# - fplod 2007-12-04T09:10:55Z aedon.locean-ipsl.upmc.fr (Darwin)
185#
186# * externalisation of idldoc issues from savesaxo.sh
187# * previous release of idldoc was 2.0
188# * this tool can be checked by creating doc from Michael Galloy librayry
189# available on http://www.michaelgalloy.com/lib-docs/
190# * version http://michaelgalloy.com/wp-content/uploads/2007/11/idldoc-3.0b1.zip
191# * pas ok ne reconnait pas les @param, @keyword
192#-
193#
194system=$(uname)
195case "${system}" in
196   AIX|IRIX64)
197      echo " www : no specific posix checking"
198   ;;
199   *)
200      set -o posix
201   ;;
202esac
203#
204command=$(basename ${0})
205log_date=$(date -u +"%Y%m%dT%H%M%SZ")
206#
207usage=" Usage : ${command} -i indir -t title -o outdir [-idldoc_dir idldoc_dir -idldoc_version idldoc_version]"
208#
209# default ++ pas encore en parametre
210assistant=0
211#assistant=1
212transform=1
213command_dir=$(dirname ${0})
214idldoc_dir="${command_dir}/../idldoc/"
215idldoc_version="2.0"
216unset command_dir
217# default IDL command and directory
218#idl_dir=/usr/local_linux/idl/idl64/  # overriding idl_dir for test ++
219#idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for test ++
220#
221ielement=1
222#
223minargcount=6
224if [ ${#} -lt ${minargcount} ]
225then
226   echo "eee : not enought arguments"
227   echo "${usage}"
228   exit 1
229fi
230#
231while [ ! -z "${1}" ] # ++ pb bash
232do
233   case ${1} in
234      -i)
235         indir=${2}
236         shift
237         case ${indir} in
238            .)
239               indir=$(pwd)
240            ;;
241         esac
242      ;;
243      -t)
244         title=${2}
245         shift
246      ;;
247      -o)
248         outdir=${2}
249         shift
250      ;;
251      -idldoc_dir)
252         idldoc_dir=${2}
253         shift
254      ;;
255      -idldoc_version)
256         idldoc_version=${2}
257         shift
258      ;;
259      -idl_dir)
260         idl_dir=${2}
261         shift
262      ;;
263      -e)
264         element[${ielement}]=${2}
265         shift
266      ;;
267      -r)
268         refhtml[${ielement}]=${2}
269         shift
270         ielement=$(( ${ielement} + 1))
271      ;;
272      -h)
273         echo "${usage}"
274         exit 0
275      ;;
276      *) # other choice
277         echo "${usage}"
278         exit 1
279      ;;
280   esac
281   shift # next flag
282done
283#
284set -u
285#
286# check for outir
287if [ ! -d ${outdir} ]
288then
289   echo "eee : outdir (${outdir}) not found"
290   exit 1
291fi
292# check for permission access on outdir
293if [ ! -x ${outdir} ]
294then
295   echo " eee : ${outdir} not reachable"
296   exit 1
297fi
298#
299# check for write permission on outdir
300if [ ! -w ${outdir} ]
301then
302   echo " eee : ${outdir} not writable"
303   exit 1
304fi
305#
306# ++ test si IDL (car GDL inutilisable)
307application=${idl_dir}/bin/idl
308#
309# build a IDL file to launch idldoc
310outputtmp=/tmp/idldoc_output${$}/
311idldoc_log="/tmp/idldochtml_${$}.log"
312pro="/tmp/idldochtml_${$}.pro"
313#
314cd ${idldoc_dir}
315case ${idldoc_version} in
316   3.1.1)
317      cat << EOF > ${pro}
318!path = expand_path('+' + '${idldoc_dir}')
319idldoc,root="${indir}",title="${title}", $
320CHARSET="ISO-8859-15", $
321LOG_FILE="${idldoc_log}", $
322output="${outputtmp}", $
323overview="../../overview", /statistics
324exit
325EOF
326   ;;
327   2.0)
328      cat << EOF > ${pro}
329!path = expand_path('+' + '${idldoc_dir}')
330idldoc,root="${indir}",title="${title}", $
331LOG_FILE="${idldoc_log}", $
332output="${outputtmp}", $
333overview="../../overview", /statistics, /preformat
334exit
335EOF
336   ;;
337   *)
338      echo "eee : idldoc version not implemented ${idldoc_version}"
339      exit 1
340   ;;
341esac
342#
343# launch IDL with the file built above
344export IDL_STARTUP=${pro}
345${application}
346rm ${pro}
347#
348if [ ${transform} -eq 1 ]
349then
350   # In order to do not have to many revision in svn, we modify some
351   # lines produced by idldoc :
352   # - add Source link in each html file corresponding to a .pro file
353   # example :
354   # <td>Source</td>
355   # will be replaced by
356   # <td><a href="../../Calendar/caldat.pro" title="Source code of a file">Source</a></td>
357   #
358   # - remove version, date and time of idldoc production
359   # ++ je ne sais pas dire en sed la ligne suivant l'occurence de Modification date
360   #
361   # count of directory levels in output
362   # this count will be use to format relative path later
363   nblev1=$(echo ${outputtmp} | sed -e "s@/\$@@" |awk -F "/" '{print NF}')
364   #
365   list_html_pro=$(find ${outputtmp} -name "*.html" -exec grep -l "<title>.*\.pro" {} \;)
366   for file_html in ${list_html_pro}
367   do
368      # build the .pro file name
369      bfile=$(basename ${file_html} .html)
370      # retrieve the path of html file relative to output.
371      # This path will be used in "Source" link.
372      nblev2=$(dirname ${file_html} | sed -e "s@/\$@@" | awk -F "/" '{print NF}')
373      difflev=$((${nblev2} - ${nblev1}))
374      if [ ${difflev} -ge 2 ]
375      then
376         ilev=1
377         reloutput_html=".."
378         while [ ${ilev} -le ${difflev} ]
379         do
380            reloutput_html="${reloutput_html}/.."
381            ilev=$(( ${ilev} + 1 ))
382         done
383         relpath_html=$(dirname ${file_html} | \
384            sed \
385               -e "s@${outputtmp}@${reloutput_html}@" \
386               -e "s@\$@/@")
387         # echo "relpath ${relpath_html})"
388      else
389         relpath_html="./"
390      fi
391      # echo "relpath ${relpath_html}/${bfile}"
392      sed \
393         -e "s@<td >Source<\/td>@<td><a href=\"${relpath_html}/${bfile}.pro\" title=\"Source code of a file\">Source<\/a><\/td>@" \
394         ${file_html} > ${file_html}_modify
395      mv ${file_html}_modify ${file_html}
396   done
397   list_html=$(find ${outputtmp} -name "*.html")
398   for file_html in ${list_html}
399   do
400      sed \
401         -e "s/\(Generated by IDLdoc\)\( .* on .*\)\( -->\)/\1\3/" \
402         -e "s/\(Produced by IDLdoc\)\( .* on .*\)\(<\/div>\)/\1\3/" \
403         -e "/<h2>Produced on/d" \
404         -e "/Modifcation:/d" \
405         -e "/<td>... ... .* ..:..:.. ....<\/td>/d" \
406         -e 's@<div class="value">@<div class="preformat">@' \
407         -e 's/div\#file_comments {/div\#file_comments { white-space: pre;/' \
408         -e 's@^ <fixe>@<pre>@' \
409         -e 's@^ </fixe>@</pre>@' \
410         -e 's@xhtml-transitional@xhtml1-transitional@' \
411         ${file_html} > ${file_html}_modify
412      mv ${file_html}_modify ${file_html}
413   done
414   # suppress ".html" in idldoc-index*.html in lines like
415   # a parameter from the routine ./ReadWrite/idl-NetCDF/ncdf_read.html
416   list_html=$(find ${outputtmp} -name "idldoc-index*.html")
417   for file_html in ${list_html}
418   do
419      sed \
420         -e "s/\(a parameter from the routine \)\(.*\)\(.html\)/\1\2/" \
421         ${file_html} > ${file_html}_modify
422      mv ${file_html}_modify ${file_html}
423   done
424   nelement=${#element[@]}
425   ielement=1
426   while [ ${ielement} -le ${nelement} ]
427   do
428      # replace <element>ginette</element> by a sequence like
429      # <a href="./ginette.html">ginette</a>
430      ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} \
431         -r ${refhtml[${ielement}]} \
432         -e ${element[${ielement}]}
433      status=${?}
434      if [ ${status} -ne 0 ]
435      then
436         echo "eee : pb during pro2href.sh for ${element}...</${element}>"
437         exit 1
438      fi
439      ielement=$(( ${ielement} + 1))
440   done
441fi # end of transform = 1
442#
443#
444if [ ${assistant} -eq 1 ]
445then
446   # build a IDL file to launch idldoc
447   idldoc_log="/tmp/idldocassistant_${$}.log"
448   pro="/tmp/idldocassistant_${$}.pro"
449   case ${idldoc_version} in
450      3.1.1)
451         echo "iii : assistant is not feasable with idldoc > 2.0"
452      ;;
453      2.0)
454         cat << EOF > ${pro}
455!path = expand_path('+' + '${idldoc_dir}')
456idldoc,root="${indir}",title="${title}", $
457LOG_FILE="${idldoc_log}", $
458output="${outputtmp}", overview='../../overview', /statistics, /embed, /assistant
459exit
460EOF
461      ;;
462      *)
463         echo "eee : idldoc version not implemented ${idldoc_version}"
464         exit 1
465      ;;
466   esac
467   # launch IDL with the file built above
468   IDL_STARTUP=${pro};${idl_dir}/bin/idl
469   /bin/rm ${pro}
470   # In order to do not have to many revision in svn, we modify some
471   # lines produced by idldoc :
472   # examples :
473   # <!-- Generated by IDLdoc 2.0 on Wed Jun 7 10:25:28 2006 -->
474   # will be replaced by
475   # <!-- Generated by IDLdoc 2.0 -->
476   # <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0 on Wed Sep 13 16:32:10 2006.</font></p>
477   # will be replaced by
478   # <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0</font></p>
479   # <h2>Produced on Wed Jun 7 10:23:13 2006</h2>
480   # will be delete
481   # other lines will be deleted because the time is the time of checkout not
482   # the time of revision.
483   # the sequence of lines
484   #<dl>
485   # <dt>Last modification:</dt>
486   # <dd>Fri Jun 2 11:46:24 2006</dd>
487   # </dl>
488   # should also be removed ++ je ne sais pas dire en sed la ligne
489   # suivant l'occurence de Last modification
490   # replace *_param_* in href attributes because anchors are badly written
491   # with _keyword_
492   #++ -e 's@\(href="#_.*\)\(_param_\)\(.*"\)@\1_keyword_\3@g' \ # ++ pb global
493   # ONLINE_HELP, book="../idldoc_assistant_output/idldoc-lib.adp", /full_path # won't work
494   # encaspulate example content in <pre> </pre> in idldoc assistant outputs
495   # Examples section is supposed to start with <h3>Examples</h3>
496   # and end is before <h3>Version history</h3>
497   list_html=$(find ${outputtmp} -name "*.html")
498   for file_html in ${list_html}
499   do
500      sed \
501         -e "s/\(Generated by IDLdoc 2.0\)\( on .*\)\( -->\)/\1\3/" \
502         -e "s/\(Produced by IDLdoc 2.0\)\( on .*\)\(\.<\/font>\)/\1\3/" \
503         -e "/<h2>Produced on/d" \
504         -e "/Last modification:/d" \
505         -e "/<dd>... ... .* ..:..:.. ....<\/dd>/d" \
506         -e '/href/s@_param_@_keyword_@g' \
507         -e 's@<div class="value">@<div class="preformat">@' \
508         -e 's/div\#file_comments {/div\#file_comments { white-space: pre;/' \
509         -e 's@^ <fixe>@<pre>@' \
510         -e 's@^ </fixe>@</pre>@' \
511         -e "s@<h3>Examples</h3>@<h3>Examples</h3><pre>@" \
512         -e "s@<h3>Version history</h3>@</pre><h3>Version history</h3>@" \
513         ${file_html} > ${file_html}_modify
514      mv ${file_html}_modify ${file_html}
515   done
516   #
517   # replace <pro>ginette</pro> by a sequence like
518   # <a href="./ginette.html">ginette</a>
519   ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} -r ${outputtmp} -e pro
520   status=${?}
521   if [ ${status} -ne 0 ]
522   then
523      echo "eee : pb during pro2href.sh for <pro>...</pro>"
524      exit 1
525   fi
526   # replace <proidl>ginette</proidl> by a sequence like
527   # <a href="./ginette.html">ginette</a>
528   ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} -r ${idl_dir}/help/online_help -e proidl
529   status=${?}
530   if [ ${status} -ne 0 ]
531   then
532      echo "eee : pb during pro2href.sh for <proidl>...</proidl>"
533      exit 1
534   fi
535   # add the directory-overview.html from dir-files.html in idldoc_html_output
536   list_html=$(find ../idldoc_html_output -name dir-files.html)
537   for file_html in ${list_html}
538   do
539      fout=../idldoc_assistant_output/${file_html#../idldoc_html_output/*}
540      fout=${fout%/*}/directory-overview.html
541      cp ${file_html} ${fout}
542   done
543   # copy listings.css (needed by directory-overview.html files)
544   cp ../idldoc/resource/listings.css ${outputtmp}
545   # add an id in idldoc-lib.adp
546   cat << EOF > /tmp/adp_modification
547<!-- \$Id\$ -->
548EOF
549   sed -e "/<\/profile>/r /tmp/adp_modification" \
550      ../idldoc_assistant_output/idldoc-lib.adp > \
551      ../idldoc_assistant_output/idldoc-lib.adp_${$}
552   mv ../idldoc_assistant_output/idldoc-lib.adp_${$} \
553   ../idldoc_assistant_output/idldoc-lib.adp
554   rm /tmp/adp_modification
555   # check that the number of existing html files for each .pro file is 2!
556   for i in $( find ../.. -name "*.pro" )
557   do
558      nhtml=$( find ../.. -name $( basename ${i} .pro ).html | wc -l )
559      if [ ${nhtml} -ne 2 ]
560      then
561         echo "ERROR there is no 2 $( basename ${i} .pro ).html files"
562         find ../.. -name $( basename ${i} .pro ).html
563         echo
564      fi
565   done
566   #
567fi
568# copy of temporary outputs on final directory
569cp -r ${outputtmp}/* ${outdir}
570echo "iii : look at ${outdir}/index.html"
571echo "iii : you can see idldoc log file in ${idldoc_log}"
572echo "iii : and look ${outdir}/idldoc-warnings.html#undoc"
573#
574# end
575exit 0
Note: See TracBrowser for help on using the repository browser.