Command-line help in the docs.
--- a/documentation/Makefile Thu Jul 24 07:40:45 2008 +0000
+++ b/documentation/Makefile Thu Jul 24 08:11:07 2008 +0000
@@ -10,16 +10,38 @@
LATEX_OPTIONS := -file-line-error-style
+COMMANDS := \
+ alias \
+ config \
+ data \
+ debug \
+ domains \
+ master \
+ pdos \
+ sdos \
+ download \
+ upload \
+ slaves \
+ sii_read \
+ sii_write \
+ states \
+ xml
+
+EXT_PREFIX := external/ethercat_
+EXT_FILES := $(addprefix $(EXT_PREFIX),$(COMMANDS))
+ETHERCAT_CMD := ../tool/ethercat
+ETHERCAT_HELP := $(ETHERCAT_CMD) -h
+
#------------------------------------------------------------------------------
-first: pdf
+all: pdf
-all: dvi pdf
+$(EXT_FILES): $(ETHERCAT_CMD)
+ @mkdir -pv external
+ @echo Creating $@...
+ $(shell $(subst $(EXT_PREFIX),$(ETHERCAT_HELP) ,$@) > $@)
-dvi:
- latex $(LATEX_OPTIONS) \\nonstopmode\\input{$(FILE).tex}
-
-pdf:
+pdf: $(EXT_FILES)
pdflatex $(LATEX_OPTIONS) $(FILE)
index:
--- a/documentation/ethercat_doc.tex Thu Jul 24 07:40:45 2008 +0000
+++ b/documentation/ethercat_doc.tex Thu Jul 24 08:11:07 2008 +0000
@@ -301,7 +301,8 @@
\end{itemize}
-\item User space command-line-tool ``ethercat``.
+\item User space command-line-tool ``ethercat`` (see
+section~\ref{sec:ethercat})
\begin{itemize}
@@ -2692,10 +2693,70 @@
%------------------------------------------------------------------------------
-\subsection{Listing the bus}
+\subsection{Setting alias addresses}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
+
+%------------------------------------------------------------------------------
+
+\subsection{Displaying the bus configuration}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
+
+%------------------------------------------------------------------------------
+
+\subsection{Displaying process data}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
+
+%------------------------------------------------------------------------------
+
+\subsection{Setting a master's debug level}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
+
+%------------------------------------------------------------------------------
+
+\subsection{Configured domains}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
+
+%------------------------------------------------------------------------------
+
+\subsection{Master and Ethernet device information}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
+
+%------------------------------------------------------------------------------
+
+\subsection{Showing slaves' sync managers, Pdos and Pdo entries}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
+
+%------------------------------------------------------------------------------
+
+\subsection{Displaying the Sdo dictionary}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos}
+
+%------------------------------------------------------------------------------
+
+\subsection{Sdo access}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
+
+%------------------------------------------------------------------------------
+
+\subsection{Displaying slaves on the bus}
Slave information can be gathered with the subcommand \lstinline+slaves+:
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
+
+Below is a typical output:
+
\begin{lstlisting}
$ `\textbf{ethercat slaves}`
0 0:0 PREOP + EK1100 Ethernet Kopplerklemme (2A E-Bus)
@@ -2704,25 +2765,6 @@
3 5555:2 PREOP + EL2004 4K. Dig. Ausgang 24V, 0,5A
\end{lstlisting}
-Every slave found is displayed as one text row. The columns have the following
-meanings:
-
-\begin{enumerate}
-
-\item Ring position in the bus.
-
-\item Alias and position (see section~\ref{sec:addr}).
-
-\item Application-layer state.
-
-\item Error flag: \lstinline!+! means that the slave is ok, \lstinline+E+
-means that an error has occurred during scanning or configuration.
-
-\item The slave's name, as it appears in the ``general'' SII category. If no
-name is found, the slave's vendor ID and product code are listed.
-
-\end{enumerate}
-
%------------------------------------------------------------------------------
\subsection{SII Access}
@@ -2746,6 +2788,8 @@
\end{itemize}
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
+
Reading out SII data is as easy as other commands. Though the data are in
binary format, analysis is easier with a tool like \textit{hexdump}:
@@ -2766,6 +2810,8 @@
To download SII contents to a slave, writing access to the master's character
device is necessary (see section~\ref{sec:cdev}).
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
+
\begin{lstlisting}
# `\textbf{ethercat sii\_write --slave 3 sii-of-slave3.bin}`
\end{lstlisting}
@@ -2775,6 +2821,18 @@
%------------------------------------------------------------------------------
+\subsection{Requesting application-layer states}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
+
+%------------------------------------------------------------------------------
+
+\subsection{Generating slave description XML}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
+
+%------------------------------------------------------------------------------
+
\section{System Integration}
\label{sec:system}