#! /bin/sh #+ # # NAME # ==== # # idldoc.sh - build idldoc documentations # # SYNOPSYS # ======== # # ``doidldoc.sh -i indir -t title -o outdir -idl_dir idl_dir -idldoc_version idldoc_version -idldoc_dir idldoc_dir -e element -r refhtlm`` # # DESCRIPTION # =========== # # Produce HTML files from IDL sources using idldoc. # # -i directory input # -t title # -o directory output # -idl_dir idl_dir # -idldoc_version idldoc_version # -idldoc_dir idldoc_dir # -e element # -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`` implentation by specify directory and # version using *idldoc_dir* and *idldoc_version*. # # Be warned that assitant 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 personnal # 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 : # :: # # $ 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 : # :: # # $ 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 : # :: # # $ 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/ -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 : # :: # # $ 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 # # add checking of consistency between numbers of -e and -r parameters # # SEE ALSO # ======== # # idldoc++ lien # # pro2href.sh # # EVOLUTIONS # ========== # # $Id$ # # - 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 accross filesystems # * add chek 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 usefull 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 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 [-idldoc_dir idldoc_dir -idldoc_version idldoc_version]" # # default ++ pas encore en parametre 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 enought arguments" echo "${usage}" exit 1 fi # while [ ! -z "${1}" ] # ++ pb bash 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 shift # next flag done # set -u # # 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.1.1) 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 # # 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 : #
@' \ -e 's@^
Produced by IDLdoc 2.0 on Wed Sep 13 16:32:10 2006.
# will be replaced by #Produced by IDLdoc 2.0
#in idldoc assistant outputs # Examples section is supposed to start with
@' \ -e 's@^
@" \ -e "s@Version history
@