Changeset 408


Ignore:
Timestamp:
11/04/09 16:31:28 (14 years ago)
Author:
pinsard
Message:

small things for documentations

Location:
trunk/SRC/Documentation/xmldoc
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/SRC/Documentation/xmldoc/doidldoc.sh

    r377 r408  
    66# ==== 
    77# 
    8 # idldoc.sh -  build idldoc documentations 
    9 # 
     8# idldoc.sh - build idldoc documentations 
    109# 
    1110# SYNOPSYS 
    1211# ======== 
    1312# 
    14 # ``doidldoc.sh -i indir -t title -o outdir`` 
     13# ``doidldoc.sh -i indir -t title -o outdir -idldoc_version idldoc_version -idldoc_dir idldoc_dir`` 
    1514# 
    1615# DESCRIPTION 
    … …  
    1918# Produce HTML files from IDL sources using idldoc. 
    2019# 
    21 # -i  directory input 
    22 # -t  title 
    23 # -o  directory output 
     20# -i directory input 
     21# -t title 
     22# -o directory output 
     23# -idldoc_version idldoc_version 
     24# -idldoc_dir idldoc_dir 
    2425# 
    2526# Two pass : first *classic* idldoc then some home made transformation to avoid 
    … …  
    2829# The first pass produce files in /tmp/idldoc_output_${$}/ directory. 
    2930# 
    30 # At the end the result is in ``outdir`` 
     31# At the end the result is in ``outdir``. 
     32# 
     33# 
     34# By default, embedded ``idldoc`` 2.0 in SAXO is used. 
     35# 
     36# You can specified an other ``idldoc`` implentation by specify directory and 
     37# version using *idldoc_dir* and *idldoc_version*. 
     38# 
     39# Be warned that assitant help is only available with ``idldoc 2.0``. 
    3140# 
    3241# EXAMPLES 
    … …  
    3544# Results can be seen be opening a browser on /tmp/idldoc_html_output/index.html 
    3645# 
    37 # To produce SAXO HTML outputs 
     46# To produce SAXO HTML outputs : 
    3847# :: 
    3948# 
    40 #  $ cd SAXO_ws/SRC/Documentations/xmldoc/ 
    41 #  $ doidldoc.sh -i ../.. -t "SAXO Documentation" -o ./idldoc_html_output/ 
    42 # 
    43 # To produce AMSU HTML outputs 
     49# $ cd SAXO_ws/SRC/Documentations/xmldoc/ 
     50# $ doidldoc.sh -i ../.. -t "SAXO Documentation" -o ./idldoc_html_output/ 
     51# 
     52# To produce AMSU HTML outputs : 
    4453# :: 
    4554# 
    46 #  $ cd /usr/home/fplod/incas/amsu/amsu_ws/ 
    47 #  $ doidldoc.sh -i . -t "AMSU Documentation" -o /tmp/idldoc_html_output/ 
     55# $ cd /usr/home/fplod/incas/amsu/amsu_ws/ 
     56# $ doidldoc.sh -i . -t "AMSU Documentation" -o /tmp/idldoc_html_output/ 
    4857# 
    4958# TODO 
    … …  
    5463# :: 
    5564# 
    56 #  $ export PATH=${HOME}/SAXO_DIR/SRC/Documentation/xmldoc/:${PATH} 
     65# $ export PATH=${HOME}/SAXO_DIR/SRC/Documentation/xmldoc/:${PATH} 
    5766# 
    5867# ++ pb avec IDL_DIR pas tjs positionné 
    … …  
    6069# :: 
    6170# 
    62 #  $ export IDL_DIR=/usr/local_linux/idl/ 
     71# $ export IDL_DIR=/usr/local_linux/idl/ 
    6372# 
    6473# or for MacOSX with 
    6574# :: 
    6675# 
    67 #  $ export IDL_DIR=/usr/local_macosx/idl//idl_6.2/idl_6.2/ 
     76# $ export IDL_DIR=/usr/local_macosx/idl//idl_6.2/idl_6.2/ 
    6877# 
    6978# 
    7079# ++ choix de la version de idldoc et consequences sur assistant 
    7180# 
    72 # ++ choix de la version de idl et consequences sur assistant et lien sur 
     81# ++ choix de la version de IDL et consequences sur assistant et lien sur 
    7382# doc idl 
    7483# 
    … …  
    8392# $Id$ 
    8493# 
     94# - ++ 
     95# 
     96# * add idldoc_version and idldoc_dir parameters 
     97# idldoc version is usefull because parameters of ``idldoc`` 
     98# have been modified (see ``CHARSET`` in 3.1.1.). 
     99# 
     100# ``idldoc`` release can not be guessed 
     101# 
    85102# - fplod 2008-08-11T12:57:48Z aedon.locean-ipsl.upmc.fr (Darwin) 
    86103# 
    87 #   * comments in this file in ReST format 
    88 #   * add ``-i``, ``-t`` and ``-o`` parameters 
     104# * comments in this file in ReST format 
     105# * add ``-i``, ``-t`` and ``-o`` parameters 
    89106# 
    90107# - fplod 2008-06-20T13:07:59Z aedon.locean-ipsl.upmc.fr (Darwin) 
    91108# 
    92 #   * evaluation version 3.1.1 
    93 # 
    94 #     we are not yet still ready to migrate to rst format because of lack of 
    95 #     assistant transformation independant of IDLdoc release (at least 
    96 #     between 2. and 3.) 
     109# * evaluation version 3.1.1 
     110# 
     111# we are not yet still ready to migrate to rst format because of lack of 
     112# assistant transformation independant of IDLdoc release (at least 
     113# between 2. and 3.) 
    97114# 
    98115# - fplod 2008-01-10T08:13:41Z aedon.locean-ipsl.upmc.fr (Darwin) 
    99116# 
    100 #   * version http://cookbook.idldev.com/idldoc-3.0rc2.zip 
     117# * version http://cookbook.idldev.com/idldoc-3.0rc2.zip 
    101118# 
    102119# - fplod 2008-01-03T09:59:18Z aedon.locean-ipsl.upmc.fr (Darwin) 
    103120# 
    104 #   * version http://cookbook.idldev.com/idldoc-3.0rc1.zip 
     121# * version http://cookbook.idldev.com/idldoc-3.0rc1.zip 
    105122# 
    106123# - fplod 2007-12-12T09:47:04Z aedon.locean-ipsl.upmc.fr (Darwin) 
    107124# 
    108 #   * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4.zip 
     125# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4.zip 
    109126# 
    110127# - fplod 2007-12-11T09:14:04Z aedon.locean-ipsl.upmc.fr (Darwin) 
    111128# 
    112 #   * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4-src.zip 
    113 #   * ++ pb path 
    114 #   * beginning of docbook templates writing (from html 3.0b3 tt files) 
     129# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b4-src.zip 
     130# * ++ pb path 
     131# * beginning of docbook templates writing (from html 3.0b3 tt files) 
    115132# 
    116133# - fplod 2007-12-10T09:28:11Z aedon.locean-ipsl.upmc.fr (Darwin) 
    117134# 
    118 #   * test with gdl : pas possible car compatibility < 6.1 
     135# * test with gdl : pas possible car compatibility < 6.1 
    119136# 
    120137# - fplod 2007-12-04T09:21:18Z aedon.locean-ipsl.upmc.fr (Darwin) 
    121138# 
    122 #   * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b3.zip 
    123 #   * pb parser if ; after ;- 
    124 #   * ++ plus de param et keyword dans l'index 
    125 #   * ++ pas w3c tilte au lieu de title, pas de charset, pas de alt, pas de summary 
    126 #   * ++ css pas ok 
    127 #   * ++ plus de @restrictions 
     139# * version http://michaelgalloy.com/wp-content/uploads/2007/12/idldoc-3.0b3.zip 
     140# * pb parser if ; after ;- 
     141# * ++ plus de param et keyword dans l'index 
     142# * ++ pas w3c tilte au lieu de title, pas de charset, pas de alt, pas de summary 
     143# * ++ css pas ok 
     144# * ++ plus de @restrictions 
    128145# 
    129146# - fplod 2007-12-04T09:10:55Z aedon.locean-ipsl.upmc.fr (Darwin) 
    130147# 
    131 #   * externalisation of idldoc issues from savesaxo.sh 
    132 #   * previous release of idldoc was 2.0 
    133 #   * this tool can be checked by creating doc from Michael Galloy librayry 
    134 #     available on http://www.michaelgalloy.com/lib-docs/ 
    135 #   * version http://michaelgalloy.com/wp-content/uploads/2007/11/idldoc-3.0b1.zip 
    136 #   * pas ok ne reconnait pas les @param, @keyword 
     148# * externalisation of idldoc issues from savesaxo.sh 
     149# * previous release of idldoc was 2.0 
     150# * this tool can be checked by creating doc from Michael Galloy librayry 
     151# available on http://www.michaelgalloy.com/lib-docs/ 
     152# * version http://michaelgalloy.com/wp-content/uploads/2007/11/idldoc-3.0b1.zip 
     153# * pas ok ne reconnait pas les @param, @keyword 
    137154#- 
    138155# 
    … …  
    148165# 
    149166command=$(basename ${0}) 
    150 log_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") 
    151 # 
    152 usage=" Usage : ${command} -i indir -t title -o outdir" 
     167log_date=$(date -u +"%Y%m%dT%H%M%SZ") 
     168# 
     169usage=" Usage : ${command} -i indir -t title -o outdir [-idldoc_dir idldoc_dir -idldoc_version idldoc_version]" 
    153170# 
    154171# default ++ pas encore en parametre 
    155172assistant=0 
     173#assistant=1 
    156174transform=1 
    157 idldoc_dir="../idldoc/" # 
    158 idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for test ++ 
     175command_dir=$(dirname ${0}) 
     176idldoc_dir="${command_dir}/../idldoc/" 
     177idldoc_version="2.0" 
     178unset command_dir 
     179 
     180#idldoc_dir="/usr/home/fplod/src/idldoc-3.1.1/" # overriding idldoc_dir for test ++ 
    159181# 
    160182minargcount=4 
    … …  
    170192 case ${1} in 
    171193 -i) 
    172   indir=${2} 
    173   shift 
     194 indir=${2} 
     195 shift 
    174196 ;; 
    175197 -t) 
    176   title=${2} 
    177   shift 
     198 title=${2} 
     199 shift 
    178200 ;; 
    179201 -o) 
    180   outdir=${2} 
    181   shift 
     202 outdir=${2} 
     203 shift 
     204 ;; 
     205 -idldoc_dir) 
     206 idldoc_dir=${2} 
     207 shift 
     208 ;; 
     209 -idldoc_version) 
     210 idldoc_version=${2} 
     211 shift 
    182212 ;; 
    183213 -h) 
    184   echo "${usage}" 
    185   exit 0 
     214 echo "${usage}" 
     215 exit 0 
    186216 ;; 
    187217 *) # other choice 
    188   echo "${usage}" 
    189   exit 1 
     218 echo "${usage}" 
     219 exit 1 
    190220 ;; 
    191221 esac 
    … …  
    195225set -u 
    196226# 
    197 # ++ test si idl (car gdl inutilisable) 
     227# ++ test si IDL (car GDL inutilisable) 
    198228application=idl 
    199229# 
    … …  
    201231memopwd=$(pwd) # should be <working space>/SRC/Documentation/xmldoc 
    202232# 
    203 # build a idl file to launch idldoc 
     233# build a IDL file to launch idldoc 
    204234outputtmp=/tmp/idldoc_output${$}/ 
    205235idldoc_log="/tmp/idldochtml_${$}.log" 
    … …  
    207237# 
    208238cd ${idldoc_dir} 
    209 cat << EOF > ${pro} 
     239case ${idldoc_version} in 
     240 3.1.1) 
     241 cat << EOF > ${pro} 
    210242!path = expand_path('+' + '${idldoc_dir}') 
    211243idldoc,root="${indir}",title="${title}", $ 
    … …  
    216248exit 
    217249EOF 
    218 # launch idl with the file built above 
     250 ;; 
     251 2.0) 
     252 cat << EOF > ${pro} 
     253!path = expand_path('+' + '${idldoc_dir}') 
     254idldoc,root="${indir}",title="${title}", $ 
     255LOG_FILE="${idldoc_log}", $ 
     256output="${outputtmp}", $ 
     257overview="../../overview", /statistics, /preformat 
     258exit 
     259EOF 
     260 ;; 
     261 *) 
     262  echo "eee : idldoc version not implemented ${idldoc_version}" 
     263  exit 1 
     264 ;; 
     265esac 
     266# launch IDL with the file built above 
    219267export IDL_STARTUP=${pro} 
    220268${application} 
    … …  
    245293 # retrieve the path of html file relative to memopwd (so relative to 
    246294 # output). This path will be used in "Source" link. 
    247  nblev2=$(dirname ${file_html} |  sed -e "s@/\$@@" | awk -F "/" '{print NF}') 
     295 nblev2=$(dirname ${file_html} | sed -e "s@/\$@@" | awk -F "/" '{print NF}') 
    248296 difflev=$((${nblev2} - ${nblev1})) 
    249297 if [ ${difflev} -ge 2 ] 
    250298 then 
    251   ilev=1 
    252   reloutput_html=".." 
    253   while [ ${ilev} -le ${difflev} ] 
    254   do 
    255    reloutput_html="${reloutput_html}/.." 
    256    ilev=$(( ${ilev} + 1 )) 
    257   done 
    258   relpath_html=$(dirname ${file_html} | \ 
    259   sed \ 
    260   -e "s@${outputtmp}@${reloutput_html}@" \ 
    261   -e "s@\$@/@") 
    262   # echo "relpath ${relpath_html})" 
     299 ilev=1 
     300 reloutput_html=".." 
     301 while [ ${ilev} -le ${difflev} ] 
     302 do 
     303 reloutput_html="${reloutput_html}/.." 
     304 ilev=$(( ${ilev} + 1 )) 
     305 done 
     306 relpath_html=$(dirname ${file_html} | \ 
     307 sed \ 
     308 -e "s@${outputtmp}@${reloutput_html}@" \ 
     309 -e "s@\$@/@") 
     310 # echo "relpath ${relpath_html})" 
    263311 else 
    264   relpath_html="./" 
     312 relpath_html="./" 
    265313 fi 
    266314 # echo "relpath ${relpath_html}/${bfile}" 
    … …  
    303351if [ ${status} -ne 0 ] 
    304352then 
    305    echo "eee : pb during pro2href.sh for <pro>...</pro>" 
    306    exit 1 
     353 echo "eee : pb during pro2href.sh for <pro>...</pro>" 
     354 exit 1 
    307355fi 
    308356# replace <proidl>ginette</proidl> by a sequence like 
    … …  
    312360if [ ${status} -ne 0 ] 
    313361then 
    314    echo "eee : pb during pro2href.sh for <proidl>...</proidl>" 
    315    exit 1 
     362 echo "eee : pb during pro2href.sh for <proidl>...</proidl>" 
     363 exit 1 
    316364fi 
    317365fi # end of transform = 1 
    … …  
    320368if [ ${assistant} -eq 1 ] 
    321369then 
    322 # build a idl file to launch idldoc 
    323 idldoc_log="/tmp/idldocassistant_${$}.log" 
    324 pro="/tmp/idldocassistant_${$}.pro" 
    325 cat <<EOF > ${pro} 
     370 # build a IDL file to launch idldoc 
     371 idldoc_log="/tmp/idldocassistant_${$}.log" 
     372 pro="/tmp/idldocassistant_${$}.pro" 
     373 case ${idldoc_version} in 
     374 3.1.1) 
     375  echo "iii : assistant is not feasable with idldoc > 2.0" 
     376 ;; 
     377 2.0) 
     378  cat << EOF > ${pro} 
    326379!path = expand_path('+' + '${idldoc_dir}') 
    327380idldoc,root="${indir}",title="${title}", $ 
    … …  
    330383exit 
    331384EOF 
    332 # launch idl with the file built above 
     385 ;; 
     386 *) 
     387  echo "eee : idldoc version not implemented ${idldoc_version}" 
     388  exit 1 
     389 ;; 
     390esac 
     391more ${pro} 
     392read a 
     393# launch IDL with the file built above 
    333394IDL_STARTUP=${pro};${IDL_DIR}/bin/idl 
    334395/bin/rm ${pro} 
    … …  
    336397# lines produced by idldoc : 
    337398# examples : 
    338 # <!-- Generated by IDLdoc 2.0 on Wed Jun  7 10:25:28 2006 --> 
     399# <!-- Generated by IDLdoc 2.0 on Wed Jun 7 10:25:28 2006 --> 
    339400# will be replaced by 
    340401# <!-- Generated by IDLdoc 2.0 --> 
    … …  
    342403# will be replaced by 
    343404# <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0</font></p> 
    344 # <h2>Produced on Wed Jun  7 10:23:13 2006</h2> 
     405# <h2>Produced on Wed Jun 7 10:23:13 2006</h2> 
    345406# will be delete 
    346407# other lines will be deleted because the time is the time of checkout not 
    … …  
    348409# the sequence of lines 
    349410#<dl> 
    350 #      <dt>Last modification:</dt> 
    351 #       <dd>Fri Jun 2 11:46:24 2006</dd> 
    352 #    </dl> 
     411# <dt>Last modification:</dt> 
     412# <dd>Fri Jun 2 11:46:24 2006</dd> 
     413# </dl> 
    353414# should also be removed ++ je ne sais pas dire en sed la ligne 
    354415# suivant l'occurence de Last modification 
    … …  
    356417# with _keyword_ 
    357418#++ -e 's@\(href="#_.*\)\(_param_\)\(.*"\)@\1_keyword_\3@g' \ # ++ pb global 
    358 #  ONLINE_HELP, book="../idldoc_assistant_output/idldoc-lib.adp", /full_path    # won't work 
     419# ONLINE_HELP, book="../idldoc_assistant_output/idldoc-lib.adp", /full_path # won't work 
    359420# encaspulate example content in <pre> </pre> in idldoc assistant outputs 
    360421# Examples section is supposed to start with <h3>Examples</h3> 
    … …  
    385446if [ ${status} -ne 0 ] 
    386447then 
    387    echo "eee : pb during pro2href.sh for <pro>...</pro>" 
    388    exit 1 
     448 echo "eee : pb during pro2href.sh for <pro>...</pro>" 
     449 exit 1 
    389450fi 
    390451# replace <proidl>ginette</proidl> by a sequence like 
    391452# <a href="./ginette.html">ginette</a> 
    392 pro2href.sh  -i ${outputtmp} -r ${IDL_DIR}/help/online_help -e proidl 
     453pro2href.sh -i ${outputtmp} -r ${IDL_DIR}/help/online_help -e proidl 
    393454status=${?} 
    394455if [ ${status} -ne 0 ] 
    395456then 
    396    echo "eee : pb during pro2href.sh for <proidl>...</proidl>" 
    397    exit 1 
     457 echo "eee : pb during pro2href.sh for <proidl>...</proidl>" 
     458 exit 1 
    398459fi 
    399460# add the directory-overview.html from dir-files.html in idldoc_html_output 
    … …  
    401462for file_html in ${list_html} 
    402463do 
    403   fout=../idldoc_assistant_output/${file_html#../idldoc_html_output/*} 
    404   fout=${fout%/*}/directory-overview.html 
    405   cp ${file_html} ${fout} 
     464 fout=../idldoc_assistant_output/${file_html#../idldoc_html_output/*} 
     465 fout=${fout%/*}/directory-overview.html 
     466 cp ${file_html} ${fout} 
    406467done 
    407468# copy listings.css (needed by directory-overview.html files) 
    … …  
    420481for i in $( find ../.. -name "*.pro" ) 
    421482do 
    422   nhtml=$( find ../.. -name $( basename ${i} .pro ).html | wc -l ) 
    423   if [ ${nhtml} -ne 2 ] 
    424           then 
    425           echo "ERROR there is not 2 $( basename ${i} .pro ).html files" 
    426           find ../.. -name $( basename ${i} .pro ).html 
    427           echo 
    428   fi 
     483 nhtml=$( find ../.. -name $( basename ${i} .pro ).html | wc -l ) 
     484 if [ ${nhtml} -ne 2 ] 
     485         then 
     486         echo "ERROR there is not 2 $( basename ${i} .pro ).html files" 
     487         find ../.. -name $( basename ${i} .pro ).html 
     488         echo 
     489 fi 
    429490done 
    430491# 

  • trunk/SRC/Documentation/xmldoc/faqsaxo.xml

    r376 r408  
    2424exemple de l'entité incluse) 
    2525--> 
    26 <title>Frequently Asked questions about SAXO</title> 
     26<title>Frequently Asked Questions about SAXO</title> 
    2727  <info> 
    2828    <authorgroup> 

  • trunk/SRC/Documentation/xmldoc/svnbasiccommands.xml

    r387 r408  
    3333      <author><personname><firstname>Sébastien</firstname> <surname>Masson</surname></personname> <email>Sebastien.Masson_at_locean-ipsl.upmc.fr</email></author> 
    3434    </authorgroup> 
    35  <pubdate>$Id</pubdate> 
     35 <pubdate>$Id$</pubdate> 
    3636</info> 
    3737 
    … …  
    6060 
    6161<screen> 
    62  <prompt>$</prompt> <userinput>svn co svn+ssh://<replaceable>YOUR_LOGIN</replaceable>@forge.ipsl.jussieu.fr/ipsl/forge/projets/&project;/svn/trunk ~/&project;</userinput> 
     62 <prompt>$</prompt> <userinput>svn checkout svn+ssh://<replaceable>YOUR_LOGIN</replaceable>@forge.ipsl.jussieu.fr/ipsl/forge/projets/&project;/svn/trunk ~/&project;</userinput> 
    6363</screen> 
    6464</para> 
    … …  
    116116 
    117117<para> 
    118 Add a new file to &project; 
     118Add a new file to &project; : 
    119119 
    120120<screen> 
    121121 <prompt>$</prompt> <userinput>svn add <replaceable>file_name</replaceable></userinput> 
     122</screen> 
     123</para> 
     124<para> 
     125If <replaceable>file_name</replaceable> is not in the working space (here ~/&project;), you must copy it.  
     126For example : 
     127<screen> 
     128 <prompt>$</prompt> <userinput>cp -p <replaceable>another_directory</replaceable> ~/&project;/</userinput> 
    122129</screen> 
    123130</para> 
    … …  
    203210 
    204211<programlisting> 
    205 $Id$ 
     212&dollar;Id&dollar; 
    206213</programlisting> 
    207214</para> 
    … …  
    216223 
    217224<para> 
    218 Next time you download/update you file, <literal>$Id$</literal> will be automatically replaced by the version tag. 
     225Next time you download/update you file, <literal>&dollar;Id&dollar;</literal> will be automatically replaced by the version tag. 
    219226</para> 
    220227</sect1> 
Note: See TracChangeset for help on using the changeset viewer.