[DOC-SIG] Re: [PYTHON DOC-SIG] contributing documentation
Case Roole
cjr@bound.xs4all.nl
Thu, 12 Jun 1997 00:37:28 +0100 (WET DST)
Sue Williams wrote:
> OK, I documented commands.py. (Thanks for the pointer to Doc/libtemplate.tex.
> It was very helpful.)
(snip)
> I do not have access to laTex here (at least I don't think I do).
> Hopefully this parses. There is only one thing I did (intentionally)
> that may be suspicious--can you put macros inside quoted strings?
No problem: LaTeX doesn't know "strings", only quotes. Well, it parsed but
for one phrase: '2>$1'.
First, $ delimits the "math environment" in LaTeX. You can show a $ by
backslashing it. Second, > is turned into an inverted exclamation mark
*outside* the math environement, but you can show it by $>$. Thus the wanted
phrase is produced by: 2$>$\$1.
> So: I've got a libcommands.tex file here, as well as some diffs of
> commands.py to add doc strings (one for the module, a one-liner for
> each of three functions).
I read the document and, loo, I'll stop struggling with os.popen from now
on.
Below I have attached the original file with the above change.
Note that I placed this file my in python ./Doc directory and used a reduced
version of lib.tex to compile it.
To get the LaTeX code actually to compile you must use a documentclass
wrapper that includes the macros. I used:
\documentstyle[twoside,11pt,myformat]{report}
\begin{document}
\pagenumbering{roman}
\input{libcommand}
\end{document}
cjr
--
Case Roole <croole@wins.uva.nl>
------ libcommand.tex -- cut here --------------------------------------
\section{Standard module \sectcode{commands}} % If implemented in Python
\stmodindex{commands}
The \code{commands} module contains wrapper functions for \code{os.popen()}
which take a system command as a string and return any output generated by
the command, and optionally, the exit status.
The \code{commands} module is only usable on systems which support
\code{popen()} (currently \UNIX{}).
The \code{commands} module defines the following functions:
\renewcommand{\indexsubitem}{(in module commands)}
\begin{funcdesc}{getstatusoutput}{cmd}
Execute the string \var{cmd} in a shell with \code{os.popen()} and return
a 2-tuple (status, output). \var{cmd} is actually run as "{ cmd ; } 2$>$\$1",
so that the returned output will contain output or error messages.
A trailing newline is stripped from the output. The exit status for the
command can be interpreted according to the rules for the \C{} function
\code{wait()}.
\end{funcdesc}
\begin{funcdesc}{getoutput}{cmd}
Like \code{getstatusoutput()}, except the exit status is ignored and
the return value is a string containing the command's output.
\end{funcdesc}
\begin{funcdesc}{getstatus}{file}
Return the output of "ls -ld \var{file}" as a string. This function uses
the \code{getoutput()} function, and properly escapes backslashes and
dollar signs in the argument.
\end{funcdesc}
Example:
\begin{verbatim}
>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls'
\end{verbatim}
_______________
DOC-SIG - SIG for the Python Documentation Project
send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________