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

#! /bin/sh
#
#+
#
# NAME
# ====
#
# idldoc.sh -  build idldoc documentations
#
#
# SYNOPSYS
# ========
#
# ``doidldoc.sh -i indir -t title -o outdir``
#
# DESCRIPTION
# ===========
#
# Produce HTML files from IDL sources using idldoc.
#
# -i  directory input
# -t  title
# -o  directory output
#
# Two pass : 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``
#
# EXAMPLES
# ========
#
# Results can be seen be opening a browser on /tmp/idldoc_html_output/index.html
#
# To produce SAXO HTML outputs
# ::
#
#  $ cd SAXO_ws/SRC/Documentations/xmldoc/
#  $ doidldoc.sh -i ../.. -t "SAXO Documentation" -o ./idldoc_html_output/
#
# To produce AMSU HTML outputs
# ::
#
#  $ cd /usr/home/fplod/incas/amsu/amsu_ws/
#  $ doidldoc.sh -i . -t "AMSU Documentation" -o /tmp/idldoc_html_output/
#
# TODO
# ====
#
# ++ pb PATH introduire SAXO_PATH
# can be solved with:
# ::
#
#  $ export PATH=${HOME}/SAXO_DIR/SRC/Documentation/xmldoc/:${PATH}
#
# ++ pb avec IDL_DIR pas tjs positionné
# can be solved for linux with
# ::
#
#  $ export IDL_DIR=/usr/local_linux/idl/
#
# or for MacOSX with
# ::
#
#  $ export IDL_DIR=/usr/local_macosx/idl//idl_6.2/idl_6.2/
#
#
# ++ 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
#
# SEE ALSO
# ========
#
# idldoc++ lien
#
# EVOLUTIONS
# ==========
#
# $Id$
#
# - fplod 2008-08-11T12:57:48Z aedon.locean-ipsl.upmc.fr (Darwin)
#
#   * comments in this file in ReST 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 rst format because of lack of
#     assistant transformation independant 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 librayry
#     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
#
command=$(basename ${0})
log_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
#
usage=" Usage : ${command} -i indir -t title -o outdir"
#
# default ++ pas encore en parametre
assistant=0
transform=1
idldoc_dir="../idldoc/" #
idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for test ++
#
minargcount=4
if [ ${#} -lt ${minargcount} ]
then
 echo "eee : not enought arguments"
 echo "${usage}"
 exit 1
fi
#
while [ ! -z "${1}" ] # ++ pb bash
do
 case ${1} in
 -i)
  indir=${2}
  shift
 ;;
 -t)
  title=${2}
  shift
 ;;
 -o)
  outdir=${2}
  shift
 ;;
 -h)
  echo "${usage}"
  exit 0
 ;;
 *) # other choice
  echo "${usage}"
  exit 1
 ;;
 esac
 shift # next flag
done
#
set -u
#
# ++ test si idl (car gdl inutilisable)
application=idl
#
# memorize current directory
memopwd=$(pwd) # should be <working space>/SRC/Documentation/xmldoc
#
# build a idl file to launch idldoc
outputtmp=/tmp/idldoc_output${$}/
idldoc_log="/tmp/idldochtml_${$}.log"
pro="/tmp/idldochtml_${$}.pro"
#
cd ${idldoc_dir}
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
# 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 to 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'occurence 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 memopwd (so 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 .*\)\(<\/td>\)/\1\3/" \
 -e "/<h2>Produced on/d" \
 -e "/Modifcation:/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
# replace <pro>ginette</pro> by a sequence like
# <a href="./ginette.html">ginette</a>
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>
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
fi # end of transform = 1
#
#
if [ ${assistant} -eq 1 ]
then
# build a idl file to launch idldoc
idldoc_log="/tmp/idldocassistant_${$}.log"
pro="/tmp/idldocassistant_${$}.pro"
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
# launch idl with the file built above
IDL_STARTUP=${pro};${IDL_DIR}/bin/idl
/bin/rm ${pro}
# In order to do not have to 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'occurence 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
# encaspulate 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>
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>
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 not 2 $( basename ${i} .pro ).html files"
          find ../.. -name $( basename ${i} .pro ).html
          echo
  fi
done
#
fi
# copy of temporary outputs on final directory
# ++ if transform
mv ${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