Index: /trunk/SRC/Documentation/xmldoc/doidldoc.sh
===================================================================
--- /trunk/SRC/Documentation/xmldoc/doidldoc.sh	(revision 376)
+++ /trunk/SRC/Documentation/xmldoc/doidldoc.sh	(revision 377)
@@ -1,76 +1,207 @@
 #! /bin/sh
 #
-# module :
-# build idldoc documentations 
-#
-# update :
+#+
+#
+# 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$
-# ++ pb PATH introduire SAXO_PATH
-# 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
+#
+# - 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
-assistant=0
-transform=1
-title="SAXO Documentation" # ++ parametre
-root="../../"
-root="/Users/fplod/SAXO_DIR_ws/SRC/" #++ à cause du cd pour éviter expand_path
-# ++ pb avec /Users/fplod/SAXO_DIR_ws/SRC/ToBeReviewed/UTILITAIRE/oups.pro ELEMENTS ... à cause de todo
-#root="/usr/home/fplod/src/mglib/" # overriding root for test ++
-#
-#
-idldoc_dir="../idldoc/" # 
-idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for ctest ++
-template_location=${idldoc_dir}/templates/
-#++ pas fini 
-#template_location=${idldoc_dir}/templates_dbk/ # overriding TEMPLATE_LOCATION++
-#template_location=/usr/home/fplod/src/idldoc-3.0b3/templates_dbk/ # overriding TEMPLATE_LOCATION++
 #
 # memorize current directory
 memopwd=$(pwd) # should be <working space>/SRC/Documentation/xmldoc
-#------------------------------------------------------------------
 #
 # build a idl file to launch idldoc
-output=../idldoc_html_output/
-#++outputtmp=/tmp/idldoc_html_output${$}/
-outputtmp=/tmp/idldoc_html_output/
-log="/tmp/idldochtml_${$}.log"
+outputtmp=/tmp/idldoc_output${$}/
+idldoc_log="/tmp/idldochtml_${$}.log"
 pro="/tmp/idldochtml_${$}.pro"
 #
@@ -78,7 +209,7 @@
 cat << EOF > ${pro}
 !path = expand_path('+' + '${idldoc_dir}')
-idldoc,root="${root}",title="${title}", $
+idldoc,root="${indir}",title="${title}", $
 CHARSET="ISO-8859-15", $
-LOG_FILE="${log}", $
+LOG_FILE="${idldoc_log}", $
 output="${outputtmp}", $
 overview="../../overview", /statistics
@@ -186,17 +317,14 @@
 fi # end of transform = 1
 #
-echo "iii : you can see log file in ${log}"
-echo "iii : and look ${outputtmp}/idldoc-warnings.html#undoc"
-#
-if [ ${assistant} -eq 1 ] 
+#
+if [ ${assistant} -eq 1 ]
 then
 # build a idl file to launch idldoc
-output=../idldoc_assistant_output/
-log="/tmp/idldocassistant_${$}.log"
+idldoc_log="/tmp/idldocassistant_${$}.log"
 pro="/tmp/idldocassistant_${$}.pro"
 cat <<EOF > ${pro}
 !path = expand_path('+' + '${idldoc_dir}')
-idldoc,root="${root}",title="${title}", $
-LOG_FILE="${log}", $
+idldoc,root="${indir}",title="${title}", $
+LOG_FILE="${idldoc_log}", $
 output="${outputtmp}", overview='../../overview', /statistics, /embed, /assistant
 exit
@@ -289,6 +417,4 @@
 ../idldoc_assistant_output/idldoc-lib.adp
 rm /tmp/adp_modification
-echo "iii : you can see log file in ${log}"
-echo "iii : and look ${outputtmp}/idldoc-warnings.html#undoc"
 # check that the number of existing html files for each .pro file is 2!
 for i in $( find ../.. -name "*.pro" )
@@ -306,6 +432,9 @@
 # copy of temporary outputs on final directory
 # ++ if transform
-#++mv ${outputtmp} ${output} # ++ rsync
-echo "look at ${outputtmp}/index.html" #++
+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
