source: trunk/SRC/Documentation/xmldoc/faqsaxo.xml @ 408

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article [
<!ENTITY promptidl "idl&gt;">
]>

<article version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xml:lang="en"
xml:id="faqsaxo">

<!--
en s'inspirant de
http://www.csc.fi/math_topics/Mail/FAQ/msg00069.html
pour les questions
on pourra aussi s'inspirer de http://idlastro.gsfc.nasa.gov/idlfaq.html

!! on notera l'utilisation hypersioux de xinclude xpointer pour ne pas répéter
(avec des erreurs, forcément) ce qui est déjà écrit dans un autre document
!!
cf http://www.zvon.org/xxl/XIncludeTutorial/Output/example9.html
cf http://www.zvon.org/xxl/XIncludeTutorial/Output/example12.html
bon finalement c'est pas si hyper rusé parce qu'on hérite du plan (sect1 par
exemple de l'entité incluse)
-->
<title>Frequently Asked Questions about SAXO</title>
  <info>
    <authorgroup>
      <author><personname><firstname>Sébastien</firstname> <surname>Masson</surname></personname> <email>Sebastien.Masson_at_locean-ipsl.upmc.fr</email></author>
      <author><personname><firstname>Françoise</firstname> <surname>Pinsard</surname></personname> <email>Francoise.Pinsard_at_locean-ipsl.upmc.fr</email></author>
    </authorgroup>
    <keywordset>
      <keyword>IDL</keyword>
      <keyword>SAXO</keyword>
      <keyword>FAQ</keyword>
    </keywordset>
    <revhistory>
      <revision>
        <revnumber>0.0</revnumber>
        <date>August 2006</date>
        <revremark>First draft</revremark>
      </revision>
      <revision>
        <revnumber>0.1</revnumber>
        <date>September 2006</date>
        <revremark>+ onlinehelp</revremark>
      </revision>
      <revision>
        <revnumber>0.2</revnumber>
        <date>April 2008</date>
        <revremark>migration from DocBook 4.2 to Docbook 5.0</revremark>
      </revision>
    </revhistory>
    <pubdate>$Id$</pubdate>
  </info>

<qandaset>
<para>
This is a list of Frequently Asked Questions about SAXO.
</para>
<para>
This list is roughly divided into categories: general questions,
technical questions, contributors questions.
</para>
<para>
Suggestions for corrections or additional sections are welcome -- please email them to <email>saxo-dev@forge.ipsl.jussieu.fr</email>.
</para>
<qandadiv xml:id="general">
<title>General</title>
<qandaentry>
<question>
<para>
What is SAXO ?
</para>
</question>
<answer>
<para>
see document <link xl:href="./whatissaxo.html">What is SAXO</link>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How can I get help ?
</para>
</question>
<answer>
<para>
see Support in document <link xl:href="./websaxo.html">Main page of SAXO</link>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I get SAXO ?
</para>
</question>
<answer>
<para>
see document <link xl:href="./getsaxo.html">Get SAXO</link>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
What is the current version of SAXO ?
</para>
</question>
<answer>
<para>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
On what systems does SAXO run ?
</para>
</question>
<answer>
<para>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Does SAXO works with GDL instead of IDL ?
</para>
</question>
<answer>
<para>
Not yet. <!-- et de toute façon GDL est pour l'instant équivalent à la version
6.0 de IDL donc peut-etre que tout SAXO ne fonctionnerait pas -->
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
When is the next version of SAXO due out ?
</para>
</question>
<answer>
<para>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How can I find if a routine to do what I want already exists ?
</para>
</question>
<answer>
<para>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How should SAXO be cited or acknowledged in publication ?
</para>
</question>
<answer>
<para>
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv xml:id="technical">
<title>Technical questions</title>
<qandaentry>
<question>
<para>
Is there on-line help for SAXO ?
</para>
</question>
<answer>
<para>
Yes, if you use at least IDL 6.2. It is produced by <application><link xl:href="http://www.ittvis.com/codebank/search.asp?FID=100">IDLdoc</link></application>. SAXO and IDL online_help have been merged, you can simply get the help by typing:
     <screen>
       <prompt>&promptidl;</prompt> <userinput><command>?</command></userinput>
     </screen>
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv xml:id="Contributors">
<title>Contributors</title>
<qandaentry>
<question>
<para>
Is there an SAXO Style Guide available ?
</para>
</question>
<answer>
<para>
There is a template for header <link xl:href="../new_header.txt">new_header.txt</link>
which can be parsed by <application>IDLdoc</application>.
</para>
<para>
This file can be added in <application>Emacs</application> configuration
<menuchoice>
  <shortcut>
    <keycombo><keysym>C-c</keysym><keysym>C-h</keysym></keycombo>
  </shortcut>
  <guimenu>IDLWAVE</guimenu>
  <guimenuitem>Templates</guimenuitem>
  <guimenuitem>Doc Header</guimenuitem>
</menuchoice>.
in your <filename>${HOME}/.emacs</filename> like this :
<programlisting>
(add-hook 'idlwave-mode-hook
  (function
    (lambda ()
     (setq idlwave-file-header '("<replaceable>SAXO_basedirectory</replaceable>/SAXO_DIR/SRC/Documentation/new_header.txt")
    ))))
</programlisting>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Is there any trouble with <application>IDLdoc</application> ?
</para>
</question>
<answer>
<para>
Yes, there are some :
<itemizedlist>
<listitem>
<para>
<literal>\</literal> in <filename>*.pro</filename> are not written
in <filename>*.html</filename>.
They must be escaped by an other <literal>\</literal> or you can choose an other character.
</para>
</listitem>
<listitem>
<para>
The search facility (<guimenu>Search</guimenu>) doesn't handle characters 
like <literal>-</literal> and <literal>|</literal>.
</para>
</listitem>
<listitem>
<para>
Paragraphs of <filename>*.pro</filename> headers are shown with a proportional
font in the <literal>HTML</literal> release.
</para>
<para>
If you need to draw some small figure like grid cell, you can encapsulate
the block to be shown in constant font <!-- see savesaxo.sh -->
between
<literal>; &lt;fixe&gt;</literal> and
<literal>; &lt;/fixe&gt;</literal>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Unfortunately, these troubles may not be fixed because the author does not
have anymore the opportunity to work on his own work.
</para>
<para>
Bugs can be submitted to IDL but we do not expect answers !
<!-- ++ rappel du bug soumis -->
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How can I check spelling of XML files ?
</para>
</question>
<answer>
<para>
There is one way with command line :
     <screen>
       <prompt>$</prompt> <userinput><command>aspell</command> <option>--mode=sgml</option> <option>-c</option> <filename><replaceable>xmlfile</replaceable></filename></userinput>
     </screen>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How can I check spelling of IDL files ?
</para>
</question>
<answer>
<para>
Not so easy but you can start with something like this :
     <screen>
       <prompt>$</prompt> <userinput><command>cd</command> <filename class="directory">${HOME}/SAXO_DIR/SRC/</filename></userinput>
       <prompt>$</prompt> <userinput>list=$(find . -name "*.pro")</userinput>
       <prompt>$</prompt> <userinput>for file in ${list}; do aspell list &lt; ${file}; done > /tmp/list_word </userinput>
       <prompt>$</prompt> <userinput>sort -u /tmp/list_word > /tmp/list_sort</userinput>
     </screen>
</para>
<para>
This will give <filename>/tmp/list_sort</filename> a list of sorted word
used in IDL files that are not in the default dictionnary.
Some of these words are correct in IDL and SAXO vocabulary, so they do not have to be replaced but some typo can be found.
</para>
<para>
To find occurences of one of these misspelled words, you have to do this :
     <screen>
       <prompt>$</prompt> <userinput>find . -name "*.pro" -exec grep -h "<replaceable>misspelled_word</replaceable>" {} \;</userinput>
     </screen>
</para>
<para>
We should improve this by providing some IDL and SAXO dictionnary. <!-- ++ -->
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How can I see online help update ?
</para>
</question>
<answer>
<para>
You won't see  online help update if you are working with the official distribution because of <varname>!HELP_PATH</varname>. To override this problem, when you are in <filename class="directory"><replaceable>SAXO_basedirectory</replaceable>/SAXO_DIR/SRC/Documentation/xmldoc/</filename>,  you can call online help like this :
     <screen>
       <prompt>&promptidl;</prompt> <userinput><command>ONLINE_HELP</command>,<option>book="../idldoc_assistant_output/idldoc-lib.adp"</option></userinput>
     </screen>
</para>
</answer>
</qandaentry>
</qandadiv>
</qandaset>
</article>