[certi-cvs] applications/PyHLA/doc .cvsignore CMakeLists.tx...

[certi-cvs]

CVSROOT:        /sources/certi
Module name:    applications
Changes by:     Petr Gotthard <gotthardp>       09/07/12 19:30:07

Modified files:
        PyHLA/doc      : .cvsignore CMakeLists.txt PyHLA.tex 
        PyHLA/doc/rti  : services.tex 
Added files:
        PyHLA/doc      : GetMscStyle.cmake 

Log message:
        Patch #6862: Automatic download of msc.sty, documentation update.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/applications/PyHLA/doc/.cvsignore?cvsroot=certi&r1=1.2&r2=1.3
http://cvs.savannah.gnu.org/viewcvs/applications/PyHLA/doc/CMakeLists.txt?cvsroot=certi&r1=1.4&r2=1.5
http://cvs.savannah.gnu.org/viewcvs/applications/PyHLA/doc/PyHLA.tex?cvsroot=certi&r1=1.8&r2=1.9
http://cvs.savannah.gnu.org/viewcvs/applications/PyHLA/doc/GetMscStyle.cmake?cvsroot=certi&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/applications/PyHLA/doc/rti/services.tex?cvsroot=certi&r1=1.2&r2=1.3

Patches:
Index: .cvsignore
===================================================================
RCS file: /sources/certi/applications/PyHLA/doc/.cvsignore,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- .cvsignore  9 Oct 2008 16:50:58 -0000       1.2
+++ .cvsignore  12 Jul 2009 19:30:05 -0000      1.3
@@ -1,5 +1,6 @@
 Makefile
 CMakeFiles
 cmake_install.cmake
+msc.sty
 PyHLA.dvi
 PyHLA.pdf

Index: CMakeLists.txt
===================================================================
RCS file: /sources/certi/applications/PyHLA/doc/CMakeLists.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- CMakeLists.txt      10 Jul 2009 20:35:23 -0000      1.4
+++ CMakeLists.txt      12 Jul 2009 19:30:05 -0000      1.5
@@ -21,7 +21,12 @@
         DEPENDS ${HOWTO_HTML_DIR}/PyHLA.html PyHLA.dvi PyHLA.pdf
     )
 
-    # PyHLA.tex requires msc.sty from http://satoss.uni.lu/mscpackage
+    # download msc.sty from http://satoss.uni.lu/mscpackage
+    ADD_CUSTOM_COMMAND(
+        OUTPUT msc.sty
+        COMMAND ${CMAKE_COMMAND} -P 
${CMAKE_CURRENT_SOURCE_DIR}/GetMscStyle.cmake
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+
     SET(HOWTO_SOURCES
         PyHLA.tex
         omt/module.tex
@@ -64,4 +69,4 @@
     MESSAGE("Cannot find Python mkhowto rules for generating doc not added.")
 ENDIF(PYTHON_MKHOWTO)
 
-# $Id: CMakeLists.txt,v 1.4 2009/07/10 20:35:23 gotthardp Exp $
+# $Id: CMakeLists.txt,v 1.5 2009/07/12 19:30:05 gotthardp Exp $

Index: PyHLA.tex
===================================================================
RCS file: /sources/certi/applications/PyHLA/doc/PyHLA.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- PyHLA.tex   24 Apr 2009 09:36:38 -0000      1.8
+++ PyHLA.tex   12 Jul 2009 19:30:06 -0000      1.9
@@ -143,6 +143,35 @@
 make install
 \end{verbatim}
 
+\subsection{Building the PyHLA documentation}
+The \module{PyHLA} documentation may be find online at
+\ulink{http://www.nongnu.org/certi/PyHLA/manual}{http://www.nongnu.org/certi/PyHLA/manual}
+however you may rebuild the documentation from the PyHLA source itself, in 
order
+to generate either PDF, HTML or DVI format.
+
+The documentation of \module{PyHLA} uses standard Python documentation
+system, in particular the python mkhowto script.
+For generating the documentation from source you need:
+\begin{itemize}
+  \item a working python installation with mkhowto script
+  \item a working latex compiler
+  \item a specific latex style called \texttt{msc.sty} which is used
+        to draw Message Sequence Chart in the documentation.
+        If you do not have the \texttt{msc.sty} installed you may
+        let CMake retrieve the file for you from:        
+        
\ulink{http://satoss.uni.lu/mscpackage}{http://satoss.uni.lu/mscpackage}.
+\end{itemize}
+
+The procedure for generating the documentation is simple,
+go the \module{PyHLA} source directory and then:
+\begin{verbatim}
+make msc.sty
+make howto
+\end{verbatim}
+
+The \texttt{msc.sty} step is optional and necessary only if you don't have
+\texttt{msc.sty} installed.
+
 \subsection{Performance}
 
 Discuss the performance penalty. Use the DFSS/DMAIC methodology.
@@ -159,4 +188,4 @@
 \input{PyHLA.ind}
 \end{document}
 
-% $Id: PyHLA.tex,v 1.8 2009/04/24 09:36:38 gotthardp Exp $
+% $Id: PyHLA.tex,v 1.9 2009/07/12 19:30:06 gotthardp Exp $

Index: rti/services.tex
===================================================================
RCS file: /sources/certi/applications/PyHLA/doc/rti/services.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- rti/services.tex    7 Jun 2009 15:12:48 -0000       1.2
+++ rti/services.tex    12 Jul 2009 19:30:07 -0000      1.3
@@ -753,15 +753,64 @@
 \exception{AttributeNotOwned}.
 \end{methoddesc}
 
-\begin{methoddesc}{updateAttributeValues}{object, \{attribute:value\}, 
tag\optional{, time}}
-
+\begin{methoddesc}[rtia]{updateAttributeValues}{object, \{attribute:value\},
+tag\optional{, time}}
+\begin{description}
+\item \var{object} is the object instance handle obtained from
+\method{rtia.registerObjectInstance}
+\item \var{\{attribute:value\}} is a python dictionary whose key are attribute
+handles with associated values.
+\item \var{tag} is a string
+\item \var{time} may be a timestamp
+\end{description}
 Returns eventRetraction handle.
 
 For example
 \begin{verbatim}
 rtia.updateAttributeValues(thisObject,
+            {textAttributeHandle:"text"},
+            "update")
+    
+rtia.updateAttributeValues(thisObject,
+            {structAttributeHandle:struct.pack('hhl', 1, 2, 3)}
+            "update")
+            
+rtia.updateAttributeValues(thisObject,
     {wordLocationHandle:fom.WorldLocationStruct.pack({"X":1,"Y":2,"Z":3})},
     "update")
+            
+rtia.updateAttributeValues(thisObject,
+            {textAttributeHandle:"text",
+            structAttributeHandle:struct.pack('hhl', 1, 2, 3),           
+            
wordLocationHandle:fom.WorldLocationStruct.pack({"X":1,"Y":2,"Z":3})},
+            "update")            
+\end{verbatim}
+
+Several methods may be used to encode the data before sending the update.
+The first one use text encoding, the second uses the python builtin
+struct encoding  
+\ulink{http://docs.python.org/library/struct.html}{http://docs.python.org/library/struct.html}
+and the last one uses the builtin \module{PyHLA} FOM encoding using
+IEEE-1516 standard encoding. The \texttt{fom} object used in this
+example is the result of something like:
+\begin{verbatim}
+import hla.omt as fom
+
+#Include RPR-FOM data types
+fom.HLAuse('rpr2-d18.xml')
+\end{verbatim}
+The previous code should have defined the RPR-FOM datatype
+\texttt{WorldLocationStruct} used in the previous example.
+Note however that you may use the predefined builtin IEEE-1516
+types without loading any FOM data type file.
+This is shown in the following example:
+\begin{verbatim}
+import hla.omt as fom
+
+...
+rtia.updateAttributeValues(thisObject,
+            {attributeHandle:fom.HLAfloat32BE.pack(3.14)},
+            "update")
 \end{verbatim}
 
 May raise
@@ -778,6 +827,16 @@
 \begin{methoddesc}{reflectAttributeValues}{object, \{attribute:value\}, tag, 
orderType, transportType\optional{, time, eventRetraction}}
 Received attribute values are received in a dictionary. Attribute handle is 
used as key.
 The value can be unpacked using the \module{hla.omt} functions.
+\begin{description}
+\item \var{object} is an object instance handle 
+\item \item \var{\{attribute:value\}} is a python dictionary whose key are 
attribute
+handles with associated values.
+\item \var{tag} is a string
+\item \var{orderType}
+\item \var{transportType}
+\item \var{time} may be a timestamp
+\item \var{eventRetraction}
+\end{description}
 
 For example
 \begin{verbatim}
@@ -1908,4 +1967,4 @@
 \begin{methoddesc}{federationSynchronized}{label}
 \end{methoddesc}
 
-% $Id: services.tex,v 1.2 2009/06/07 15:12:48 gotthardp Exp $
+% $Id: services.tex,v 1.3 2009/07/12 19:30:07 gotthardp Exp $

Index: GetMscStyle.cmake
===================================================================
RCS file: GetMscStyle.cmake
diff -N GetMscStyle.cmake
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ GetMscStyle.cmake   12 Jul 2009 19:30:06 -0000      1.1
@@ -0,0 +1,29 @@
+# Simple cmake script which may be used
+# to get the msc.sty file from http://satoss.uni.lu/mscpackage
+# which is needed to build the PyHLA documentation
+cmake_minimum_required(VERSION 2.6)
+SET(LOCAL_FILE "./msc.sty")
+SET(REMOTE_FILE "http://satoss.uni.lu/mscpackage/msc.sty";)
+
+message(STATUS "Checking for ${LOCAL_FILE} file...")
+if (EXISTS ${LOCAL_FILE})
+   message(STATUS "Already there: nothing to do")
+else (EXISTS ${LOCAL_FILE})
+   message(STATUS "Not there, trying to download...")
+   file(DOWNLOAD ${REMOTE_FILE} ${LOCAL_FILE}
+        TIMEOUT 10
+        STATUS DL_STATUS
+        LOG DL_LOG)  
+   list(GET DL_STATUS 0 DL_NOK)
+   if ("${DL_LOG}" MATCHES "404 Not Found")
+      set(DL_NOK 1)
+   endif ("${DL_LOG}" MATCHES "404 Not Found")
+   if (DL_NOK)
+      # we shall remove the file because it is created
+      # with an inappropriate content
+      file(REMOVE ${LOCAL_FILE})
+      message(SEND_ERROR "Download failed: ${DL_LOG}")           
+   else (DL_NOK)
+      message(STATUS "Download successful.")
+   endif (DL_NOK)      
+endif (EXISTS ${LOCAL_FILE})