Another version of introduction and common

diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex
index 749bfe0..785bd9c 100644 (file)
--- a/org.glite.lb.doc/src/LBDG-Introduction.tex
+++ b/org.glite.lb.doc/src/LBDG-Introduction.tex
@@ -86,9 +86,9 @@ The context also stores details on errors of the recent API call.
 
 For use with the \emph{producer} calls (see Sect.~\ref{s:producer})
 the context has to be assigned a~single \jobid
-(with the \verb'edg_wll_SetLoggingJob' call, see Sect.~\ref{s:sequence}),
+(with the \verb'edg_wll_SetLoggingJob' call),
 and keeps track of an event \emph{sequence code} for the job 
-(detailed description in~\cite{lbarch}).
+(see~\cite{LBUG}, detailed description in~\cite{lbarch}).
 
 \subsubsection{Asynchronnous calls}
 \LB library calls are typically asynchronnous. The typical call --
@@ -113,82 +113,80 @@ channel establishment.
 \subsection{\LB common overview}
 
 \subsubsection{edg\_wll\_Event}
-\begin{description}
- \item[Description:] Data structure representing a \LB event
-   (set of key--value pairs with predefined structure -- allowed event
-   types and names of attributes).
- \item[Components:]  The data structure have a common part and a event
-   type specific part. Most important common event attributes:
-   \begin{itemize}
-    \item \texttt{jobId} Grid job id of the job the event belongs to.
-    \item \texttt{user} Identity (certificate subject) of the event sender.
-    \item \texttt{timestamp} Time when the event was generated.
-    \item \texttt{seqcode} Sequence code assigned to the event.
-    \item \texttt{type} Event type.
-   \end{itemize}
- \item[Header file:] \texttt{glite/lb/events.h}
- \item[Operations:] The event type is transparent. The only important
-   operation defined is \texttt{edg\_wll\_FreeEvent(edg\_wll\_Event
-     *event)} to free event structure.
- \item[More information:] see file \texttt{org.glite.lb.types/types.T} 
-\end{description}
+Data structure \texttt{edg\_wll\_Event} represents a \LB event (set of
+key--value pairs with predefined structure -- allowed event types and
+names of attributes). It is returned by customer LB API job event
+related calls. The data structure have a common part and a event
+type specific part. Most important common event attributes:
+\begin{itemize}
+  \item \texttt{jobId} Grid job id of the job the event belongs to.
+  \item \texttt{user} Identity (certificate subject) of the event sender.
+  \item \texttt{timestamp} Time when the event was generated.
+  \item \texttt{seqcode} Sequence code assigned to the event.
+  \item \texttt{type} Event type.
+\end{itemize}
+
+The event type is transparent. The only important operation defined is
+\texttt{edg\_wll\_FreeEvent(edg\_wll\_Event *event)} to free event
+structure. For more information see file \texttt{org.glite.lb.types/types.T} 
+
+\TODO{examples}
 
 \subsubsection{edg\_wll\_Context} 
-vytváøení, ru¹ení, nastavování paramentrù
-\begin{description}
- \item[Description:] Data structure representing \LB API context (see
-   section~\ref{s:context}).
- \item[Components:] There are parameters described in consumer
-   and producer API chapters which are stored in context and
-   accessed by funcions described below (\texttt{edg\_wll\_SetParam})
-   using appropriate constants. Examples of common context parameters:
-   \begin{itemize}
-    \item \texttt{EDG\_WLL\_PARAM\_X509\_KEY} key file to use for authentication.
-    \item \texttt{EDG\_WLL\_PARAM\_X509\_CERT} certificate file to use for
+Data structure representing \LB API context (see
+section~\ref{s:context}).  There are parameters described in consumer
+and producer API chapters which are stored in context and accessed by
+funcions described below (\texttt{edg\_wll\_SetParam}) using
+appropriate constants. Examples of common context parameters:
+\begin{itemize}
+  \item \texttt{EDG\_WLL\_PARAM\_X509\_KEY} key file to use for authentication.
+  \item \texttt{EDG\_WLL\_PARAM\_X509\_CERT} certificate file to use for
       authentication
-   \end{itemize}
- \item[Header file:] \texttt{glite/lb/context.h}
- \item[Operations:] The context type is opaque. Operations with the
-   instance:
-   \begin{itemize}
-    \item \texttt{edg\_wll\_InitContext(edg\_wll\_Context *context)}
-      Allocate and initialize a new context object.
-    \item \texttt{edg\_wll\_FreeContext(edg\_wll\_Context context)}
-      Destroy and free context object.
-    \item \texttt{edg\_wll\_SetParam(edg\_wll\_Context context, 
-      edg\_wll\_ContextParam param, val)} Set a context parameter.
-    \item \texttt{edg\_wll\_GetParam(edg\_wll\_Context context, 
-      edg\_wll\_ContextParam param, val)} Get current parameter value.
-   \end{itemize}
- \item[More information:] see file \texttt{context.h} 
-\end{description}
+\end{itemize}
+
+The context type is opaque. Operations with the type instance:
+\begin{itemize}
+  \item \texttt{edg\_wll\_InitContext(edg\_wll\_Context *context)}
+    Allocate and initialize a new context object.
+  \item \texttt{edg\_wll\_FreeContext(edg\_wll\_Context context)}
+    Destroy and free context object.
+  \item \texttt{edg\_wll\_SetParam(edg\_wll\_Context context, 
+    edg\_wll\_ContextParam param, val)} Set a context parameter.
+  \item \texttt{edg\_wll\_GetParam(edg\_wll\_Context context, 
+    edg\_wll\_ContextParam param, val)} Get current parameter value.
+\end{itemize}
+For more information see file \texttt{context.h} 
+
+\TODO{examples}
+
+\subsubsection{edg\_wll\_JobStat}
+Data type \texttt{edg\_wll\_JobStat} represents status of a job as
+computed by \LB from received events. The data structure have a common
+part and a job state specific part. Most important common
+attributes:
+\begin{itemize}
+  \item \texttt{state} numeric code of the status
+    (EDG\_WLL\_JOB\_SUBMITTED, EDG\_WLL\_JOB\_WAITING, \dots)
+  \item \texttt{type} type of the job (EDG\_WLL\_JOB\_SIMPLE or
+    EDG\_WLL\_JOB\_DAG) 
+  \item \texttt{children} list of subjob \jobid's
+\end{itemize}
+
+
+\TODO{JobId? Odkazy na zacatek user's guide pro vysvetleni architektury.}
 
-\subsubsection{JobStat}
+\subsubsection{\LB common header files overview}
+
+Header files for mentioned common structures are summarized in the
+following table, other important header files are described in the
+next chapters (producer and consumer API).
+
+\begin{table}[h]
+\begin{tabularx}{\textwidth}{>{\tt}lX}
+glite/lb/context.h & Definition of context structure and parameters. \\
+glite/lb/events.h & \LB event data structure.\\
+glite/lb.jobstat.h & Job status structure returned by consumer API.\\
+\end{tabularx}
+\end{table}
 
 
-\subsubsection{\LB common header files overview}
-CountRef.h
-Event.h.T
-LoggingExceptions.h
-authz.h
-connpool.h
-context-int.h
-context.h
-events.h.T
-events\_parse.h
-il\_msg.h
-il\_string.h
-jobstat.h.T
-lb\_maildir.h
-lb\_perftest.h
-lb\_plain\_io.h
-log\_proto.h
-mini\_http.h
-notif\_rec.h
-notifid.h
-padstruct.h
-query\_rec.h
-timeouts.h
-ulm\_parse.h
-xml\_conversions.h
-xml\_parse.h