#! /bin/sh -x
#+
#
# NAME
# ====
#
# idldoc.sh - build idldoc documentations
#
# SYNOPSIS
# ========
#
# .. code-block:: bash
#
#    doidldoc.sh -i indir -t title -o outdir -idl_dir idl_dir -idldoc_version idldoc_version -idldoc_dir idldoc_dir -e element -r refhtml``
#
# DESCRIPTION
# ===========
#
# Produce HTML files from IDL sources using idldoc.
#
# .. option:: -i <directory input>
# .. option:: -t <title>
# .. option:: -o <directory output>
# .. option:: -idl_dir <idl_dir>
# .. option:: -idldoc_version <idldoc_version>
# .. option:: -idldoc_dir <idldoc_dir>
# .. option:: -e <element>
# .. option:: -r <refhtml>
#
# Two passes : first *classic* idldoc then some home made transformation
# to avoid for example version of idldoc on each HTML files.
#
# The first pass produce files in /tmp/idldoc_output_${$}/ directory.
#
# At the end the result is in ``outdir``.
#
# By default, embedded ``idldoc`` 2.0 in SAXO is used.
#
# You can specified an other ``idldoc`` implementation by specify directory
# and version using *idldoc_dir* and *idldoc_version*.
#
# Be warned that assistant help is only available with ``idldoc 2.0``.
#
# Must be run two times to resolve internal links.
#
# CAUTIONS
# ========
#
# SAXO_DIR must be set. The value should be the directory where
# SAXO is available.
#
# for example, if you work at LOCEAN and work with default SAXO,
# SAXO_DIR=/usr/home/smasson/SAXO_DIR/.
#
# For working in progress, you should checkout SAXO on a personal
# directory and set SAXO_DIR to the working space.
#
# example for me : SAXO_DIR=/usr/lodyc/incas/fplod/SAXO_DIR_ws/
#
# EXAMPLES
# ========
#
# Results can be seen be opening a browser on /tmp/idldoc_html_output/index.html
#
# To produce SAXO HTML outputs :
#
# .. code-block:: bash
#
#    cd ${SAXO_DIR}/SRC/Documentation/xmldoc/
#    ${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
#
# To produce GEOMAG HTML outputs :
#
# .. code-block:: bash
#
#    cd /usr/home/fplod/incas/geomag/geomag_ws/
#    ${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/
#
# To produce VARAMMA HTML outputs :
#
# .. code-block:: bash
#
#    cd /usr/home/fplod/incas/varamma/varamma_ws/
#    ${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/ \
#    -idldoc_version 3.2 -idldoc_dir /usr/home/incas/francoise/idldoc-3.2_aedon.locean-ipsl.upmc.fr///idldoc-3.2/ \
#    -e pro -r ../idldoc_html_output/ -e proidl -r /usr/local_linux/idl/idl_6.4/idl/help/online_help
#
# To produce POST_IT HTML outputs :
#
# .. code-block:: bash
#
#    cd /usr/lodyc/incas/fplod/post_it_ws/
#    ${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/
#
# TODO
# ====
#
# ++ choix de la version de idldoc et consequences sur assistant
#
# ++ choix de la version de IDL et consequences sur assistant et lien sur
# doc idl
#
# idldoc 3.2 (beware of sphinx compatibility)
#
# add checking of consistency between numbers of -e and -r parameters
#
# SEE ALSO
# ========
#
# idldoc++ lien
#
# pro2href.sh
#
# EVOLUTIONS
# ==========
#
# $Id$
#
# - fplod 20100701T144720Z aedon.locean-ipsl.upmc.fr (Darwin)
#
#   * test with idldoc 3.2 (no more 3.1.1) on VARAMMA project. not yet ok
#
# - fplod 20100125T105849Z aedon.locean-ipsl.upmc.fr (Darwin)
#
#   * add -e and -r parameters to replace hardcoded element and reference
#     of links
#
# - fplod 20091112T101526Z zeus.locean-ipsl.upmc.fr (Linux)
#
#   * replace mv by cp -r because mv may no works across filesystems
#   * add check on outdir
#
# - fplod 20091112T084225Z aedon.locean-ipsl.upmc.fr (Darwin)
#
#   * bug fix if indir is set to '.'
#   * idl_dir in parameter
#   * path of local commands
#
# - fplod 20091110T151839Z aedon.locean-ipsl.upmc.fr (Darwin)
#
#   * add CAUTIONS about SAXO_DIR environment variable
#     and usage in EXAMPLES
#
# - ++
#
# * add idldoc_version and idldoc_dir parameters
# idldoc version is useful because parameters of ``idldoc``
# have been modified (see ``CHARSET`` in 3.1.1.).
#
# ``idldoc`` release can not be guessed
#
# - fplod 2008-08-11T12:57:48Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * comments in this file in reStructuredText format
# * add ``-i``, ``-t`` and ``-o`` parameters
#
# - fplod 2008-06-20T13:07:59Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * evaluation version 3.1.1
#
#   we are not yet still ready to migrate to reStructuredText format
#   because of lack of assistant transformation independent of IDLdoc release
#   (at least between 2. and 3.)
#
# - fplod 2008-01-10T08:13:41Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * version http://cookbook.idldev.com/idldoc-3.0rc2.zip
#
# - fplod 2008-01-03T09:59:18Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * version http://cookbook.idldev.com/idldoc-3.0rc1.zip
#
# - fplod 2007-12-12T09:47:04Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4.zip
#
# - fplod 2007-12-11T09:14:04Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4-src.zip
# * ++ pb path
# * beginning of docbook templates writing (from html 3.0b3 tt files)
#
# - fplod 2007-12-10T09:28:11Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * test with gdl : pas possible car compatibility < 6.1
#
# - fplod 2007-12-04T09:21:18Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b3.zip
# * pb parser if ; after ;-
# * ++ plus de param et keyword dans l'index
# * ++ pas w3c tilte au lieu de title, pas de charset, pas de alt, pas de summary
# * ++ css pas ok
# * ++ plus de @restrictions
#
# - fplod 2007-12-04T09:10:55Z aedon.locean-ipsl.upmc.fr (Darwin)
#
# * externalisation of idldoc issues from savesaxo.sh
# * previous release of idldoc was 2.0
# * this tool can be checked by creating doc from Michael Galloy library
# available on http://www.michaelgalloy.com/lib-docs/
# * version http://michaelgalloy.com/wp-content/uploads/2007/11/idldoc-3.0b1.zip
# * pas ok ne reconnait pas les @param, @keyword
#-
#
system=$(uname)
case "${system}" in
    AIX|IRIX64)
        echo " www : no specific posix checking"
    ;;
    *)
        set -o posix
    ;;
esac
#
set -u
#
command=$(basename ${0})
log_date=$(date -u +"%Y%m%dT%H%M%SZ")
#
usage=" Usage : ${command} -i indir -t title -o outdir [-idldoc_dir idldoc_dir -idldoc_version idldoc_version]"
#
# default ++ pas encore en paramètre
assistant=0
#assistant=1
transform=1
command_dir=$(dirname ${0})
idldoc_dir="${command_dir}/../idldoc/"
idldoc_version="2.0"
unset command_dir
# default IDL command and directory
#idl_dir=/usr/local_linux/idl/idl64/  # overriding idl_dir for test ++
#idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for test ++
#
ielement=1
#
minargcount=6
if [ ${#} -lt ${minargcount} ]
then
    echo "eee : not enough arguments"
    echo "${usage}"
    exit 1
fi
#
while [ ${#} -gt 0 ]
do
    case ${1} in
        -i)
            indir=${2}
            shift
            case ${indir} in
                .)
                    indir=$(pwd)/
                ;;
            esac
        ;;
        -t)
            title=${2}
            shift
        ;;
        -o)
            outdir=${2}
            shift
        ;;
        -idldoc_dir)
            idldoc_dir=${2}
            shift
        ;;
        -idldoc_version)
            idldoc_version=${2}
            shift
        ;;
        -idl_dir)
            idl_dir=${2}
            shift
        ;;
        -e)
            element[${ielement}]=${2}
            shift
        ;;
        -r)
            refhtml[${ielement}]=${2}
            shift
            ielement=$(( ${ielement} + 1))
        ;;
        -h)
            echo "${usage}"
            exit 0
        ;;
        *)
            # other choice
            echo "${usage}"
            exit 1
        ;;
    esac
    # next flag
    shift
done
#
# check for outir
if [ ! -d ${outdir} ]
then
    echo "eee : outdir (${outdir}) not found"
    exit 1
fi
# check for permission access on outdir
if [ ! -x ${outdir} ]
then
    echo " eee : ${outdir} not reachable"
    exit 1
fi
#
# check for write permission on outdir
if [ ! -w ${outdir} ]
then
    echo " eee : ${outdir} not writable"
    exit 1
fi
#
# ++ test si IDL (car GDL inutilisable)
application=${idl_dir}/bin/idl
#
# build a IDL file to launch idldoc
outputtmp=/tmp/idldoc_output${$}/
idldoc_log="/tmp/idldochtml_${$}.log"
pro="/tmp/idldochtml_${$}.pro"
#
cd ${idldoc_dir}
case ${idldoc_version} in
    3.2)
        cat << EOF > ${pro}
!path = expand_path('+' + '${idldoc_dir}')
idldoc,root="${indir}",title="${title}", $
CHARSET="ISO-8859-15", $
LOG_FILE="${idldoc_log}", $
output="${outputtmp}", $
overview="../../overview", /statistics
exit
EOF
    ;;
    2.0)
      cat << EOF > ${pro}
!path = expand_path('+' + '${idldoc_dir}')
idldoc,root="${indir}",title="${title}", $
LOG_FILE="${idldoc_log}", $
output="${outputtmp}", $
overview="../../overview", /statistics, /preformat
exit
EOF
   ;;
   *)
      echo "eee : idldoc version not implemented ${idldoc_version}"
      exit 1
   ;;
esac
more ${pro}
#
# launch IDL with the file built above
export IDL_STARTUP=${pro}
${application}
rm ${pro}
#
if [ ${transform} -eq 1 ]
then
    # In order to do not have too many revision in svn, we modify some
    # lines produced by idldoc :
    # - add Source link in each html file corresponding to a .pro file
    # example :
    # <td>Source</td>
    # will be replaced by
    # <td><a href="../../Calendar/caldat.pro" title="Source code of a file">Source</a></td>
    #
    # - remove version, date and time of idldoc production
    #   ++ je ne sais pas dire en sed la ligne suivant l'occurrence de
    #   Modification date
    #
    # count of directory levels in output
    # this count will be use to format relative path later
    nblev1=$(echo ${outputtmp} | sed -e "s@/\$@@" |awk -F "/" '{print NF}')
    #
    list_html_pro=$(find ${outputtmp} -name "*.html" -exec grep -l "<title>.*\.pro" {} \;)
    for file_html in ${list_html_pro}
    do
        # build the .pro file name
        bfile=$(basename ${file_html} .html)
        # retrieve the path of html file relative to output.
        # This path will be used in "Source" link.
        nblev2=$(dirname ${file_html} | sed -e "s@/\$@@" | awk -F "/" '{print NF}')
        difflev=$((${nblev2} - ${nblev1}))
        if [ ${difflev} -ge 2 ]
        then
            ilev=1
            reloutput_html=".."
            while [ ${ilev} -le ${difflev} ]
            do
                reloutput_html="${reloutput_html}/.."
                ilev=$(( ${ilev} + 1 ))
            done
            relpath_html=$(dirname ${file_html} | \
            sed \
            -e "s@${outputtmp}@${reloutput_html}@" \
            -e "s@\$@/@")
            # echo "relpath ${relpath_html})"
        else
            relpath_html="./"
        fi
        # echo "relpath ${relpath_html}/${bfile}"
        sed \
        -e "s@<td >Source<\/td>@<td><a href=\"${relpath_html}/${bfile}.pro\" title=\"Source code of a file\">Source<\/a><\/td>@" \
        ${file_html} > ${file_html}_modify
        mv ${file_html}_modify ${file_html}
    done
    list_html=$(find ${outputtmp} -name "*.html")
    for file_html in ${list_html}
    do
        sed \
        -e "s/\(Generated by IDLdoc\)\( .* on .*\)\( -->\)/\1\3/" \
        -e "s/\(Produced by IDLdoc\)\( .* on .*\)\(<\/div>\)/\1\3/" \
        -e "/<h2>Produced on/d" \
        -e "/Modification:/d" \
        -e "/<td>... ... .* ..:..:.. ....<\/td>/d" \
        -e 's@<div class="value">@<div class="preformat">@' \
        -e 's/div\#file_comments {/div\#file_comments { white-space: pre;/' \
        -e 's@^ <fixe>@<pre>@' \
        -e 's@^ </fixe>@</pre>@' \
        -e 's@xhtml-transitional@xhtml1-transitional@' \
        ${file_html} > ${file_html}_modify
        mv ${file_html}_modify ${file_html}
    done
    # suppress ".html" in idldoc-index*.html in lines like
    # a parameter from the routine ./ReadWrite/idl-NetCDF/ncdf_read.html
    list_html=$(find ${outputtmp} -name "idldoc-index*.html")
    for file_html in ${list_html}
    do
        sed \
        -e "s/\(a parameter from the routine \)\(.*\)\(.html\)/\1\2/" \
        ${file_html} > ${file_html}_modify
        mv ${file_html}_modify ${file_html}
    done
    nelement=${#element[@]}
    ielement=1
    while [ ${ielement} -le ${nelement} ]
    do
        # replace <element>ginette</element> by a sequence like
        # <a href="./ginette.html">ginette</a>
        ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} \
        -r ${refhtml[${ielement}]} \
        -e ${element[${ielement}]}
        status=${?}
        if [ ${status} -ne 0 ]
        then
            echo "eee : pb during pro2href.sh for ${element}...</${element}>"
            exit 1
        fi
        ielement=$(( ${ielement} + 1))
    done
    # end of transform = 1
fi
#
if [ ${assistant} -eq 1 ]
then
    # build a IDL file to launch idldoc
    idldoc_log="/tmp/idldocassistant_${$}.log"
    pro="/tmp/idldocassistant_${$}.pro"
    case ${idldoc_version} in
        3.2)
            echo "iii : assistant is not feasible with idldoc > 2.0"
        ;;
        2.0)
            cat << EOF > ${pro}
!path = expand_path('+' + '${idldoc_dir}')
idldoc,root="${indir}",title="${title}", $
LOG_FILE="${idldoc_log}", $
output="${outputtmp}", overview='../../overview', /statistics, /embed, /assistant
exit
EOF
        ;;
        *)
            echo "eee : idldoc version not implemented ${idldoc_version}"
            exit 1
        ;;
    esac
    # launch IDL with the file built above
    IDL_STARTUP=${pro};${idl_dir}/bin/idl
    /bin/rm ${pro}
    # In order to do not have too many revision in svn, we modify some
    # lines produced by idldoc :
    # examples :
    # <!-- Generated by IDLdoc 2.0 on Wed Jun 7 10:25:28 2006 -->
    # will be replaced by
    # <!-- Generated by IDLdoc 2.0 -->
    # <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0 on Wed Sep 13 16:32:10 2006.</font></p>
    # will be replaced by
    # <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0</font></p>
    # <h2>Produced on Wed Jun 7 10:23:13 2006</h2>
    # will be delete
    # other lines will be deleted because the time is the time of checkout not
    # the time of revision.
    # the sequence of lines
    #<dl>
    # <dt>Last modification:</dt>
    # <dd>Fri Jun 2 11:46:24 2006</dd>
    # </dl>
    # should also be removed ++ je ne sais pas dire en sed la ligne
    # suivant l'occurrence de Last modification
    # replace *_param_* in href attributes because anchors are badly written
    # with _keyword_
    #++ -e 's@\(href="#_.*\)\(_param_\)\(.*"\)@\1_keyword_\3@g' \ # ++ pb global
    # ONLINE_HELP, book="../idldoc_assistant_output/idldoc-lib.adp", /full_path # won't work
    # encapsulate example content in <pre> </pre> in idldoc assistant outputs
    # Examples section is supposed to start with <h3>Examples</h3>
    # and end is before <h3>Version history</h3>
    list_html=$(find ${outputtmp} -name "*.html")
    for file_html in ${list_html}
    do
        sed \
        -e "s/\(Generated by IDLdoc 2.0\)\( on .*\)\( -->\)/\1\3/" \
        -e "s/\(Produced by IDLdoc 2.0\)\( on .*\)\(\.<\/font>\)/\1\3/" \
        -e "/<h2>Produced on/d" \
        -e "/Last modification:/d" \
        -e "/<dd>... ... .* ..:..:.. ....<\/dd>/d" \
        -e '/href/s@_param_@_keyword_@g' \
        -e 's@<div class="value">@<div class="preformat">@' \
        -e 's/div\#file_comments {/div\#file_comments { white-space: pre;/' \
        -e 's@^ <fixe>@<pre>@' \
        -e 's@^ </fixe>@</pre>@' \
        -e "s@<h3>Examples</h3>@<h3>Examples</h3><pre>@" \
        -e "s@<h3>Version history</h3>@</pre><h3>Version history</h3>@" \
        ${file_html} > ${file_html}_modify
        mv ${file_html}_modify ${file_html}
    done
    #
    # replace <pro>ginette</pro> by a sequence like
    # <a href="./ginette.html">ginette</a>
    ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} -r ${outputtmp} -e pro
    status=${?}
    if [ ${status} -ne 0 ]
    then
        echo "eee : pb during pro2href.sh for <pro>...</pro>"
        exit 1
    fi
    # replace <proidl>ginette</proidl> by a sequence like
    # <a href="./ginette.html">ginette</a>
    ${SAXO_DIR}/SRC/Documentation/xmldoc/pro2href.sh -i ${outputtmp} -r ${idl_dir}/help/online_help -e proidl
    status=${?}
    if [ ${status} -ne 0 ]
    then
        echo "eee : pb during pro2href.sh for <proidl>...</proidl>"
        exit 1
    fi
    # add the directory-overview.html from dir-files.html in idldoc_html_output
    list_html=$(find ../idldoc_html_output -name dir-files.html)
    for file_html in ${list_html}
    do
        fout=../idldoc_assistant_output/${file_html#../idldoc_html_output/*}
        fout=${fout%/*}/directory-overview.html
        cp ${file_html} ${fout}
    done
    # copy listings.css (needed by directory-overview.html files)
    cp ../idldoc/resource/listings.css ${outputtmp}
    # add an id in idldoc-lib.adp
    cat << EOF > /tmp/adp_modification
<!-- \$Id\$ -->
EOF
    sed -e "/<\/profile>/r /tmp/adp_modification" \
    ../idldoc_assistant_output/idldoc-lib.adp > \
    ../idldoc_assistant_output/idldoc-lib.adp_${$}
    mv ../idldoc_assistant_output/idldoc-lib.adp_${$} \
    ../idldoc_assistant_output/idldoc-lib.adp
    rm /tmp/adp_modification
    # check that the number of existing html files for each .pro file is 2!
    for i in $( find ../.. -name "*.pro" )
    do
        nhtml=$( find ../.. -name $( basename ${i} .pro ).html | wc -l )
        if [ ${nhtml} -ne 2 ]
        then
            echo "ERROR there is no 2 $( basename ${i} .pro ).html files"
            find ../.. -name $( basename ${i} .pro ).html
            echo
        fi
    done
    #
fi
# copy of temporary outputs on final directory
cp -r ${outputtmp}/* ${outdir}
echo "iii : look at ${outdir}/index.html"
echo "iii : you can see idldoc log file in ${idldoc_log}"
echo "iii : and look ${outdir}/idldoc-warnings.html#undoc"
#
# end
exit 0