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

Last change on this file was 495, checked in by pinsard, 10 years ago

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