doc/commands/PipeRead.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   6 %myents;
   7 ]>
   8
   9 <!-- $Id: PipeRead.xml,v 1.3 2007/06/16 12:38:46 griph Exp $ -->
  10
  11 <section id='PipeRead'>
  12 <title>PipeRead</title>
  13
  14 <cmdsynopsis>
  15         <command>PipeRead</command
  16         ><arg choice='plain'
  17                 ><replaceable>command</replaceable
  18         ></arg
  19         ><arg choice='opt'>quiet</arg>
  20 </cmdsynopsis>
  21
  22 <para>Causes fvwm to read commands from the output of the
  23 <replaceable>command</replaceable>.
  24 This
  25 <replaceable>command</replaceable>
  26 is executed by
  27 <filename>/bin/sh</filename>
  28 as if you typed it on the command line.  If the command consists
  29 of more than one word it must be quoted.  Useful for building up
  30 dynamic menu entries based on a directories contents, for
  31 example. If the keyword
  32 <fvwmopt cmd="PipeRead" opt="Quiet"/>
  33 follows the command no message is produced if the
  34 <replaceable>command</replaceable>
  35 is not found.</para>
  36
  37 <para>Example:</para>
  38
  39 <programlisting>
  40 <fvwmref cmd="AddToMenu"/> HomeDirMenu
  41 PipeRead 'for i in $HOME/*; \
  42   do echo "+ $i <fvwmref cmd="Exec"/> xterm -e vi $i"; done'
  43 </programlisting>
  44
  45
  46 <para>Note: The
  47 <emphasis remap='B'>PipeRead</emphasis>
  48 changes the pointer to a watch cursor by default during
  49 execution.  However, some commands, for example xwd, need to take
  50 control of the pointer themselves and do not work.  To disable the
  51 watch cursor, use the command prior to
  52 <emphasis remap='B'>PipeRead</emphasis></para>
  53
  54 <programlisting>
  55 <fvwmref cmd="BusyCursor"/> <fvwmref cmd="BusyCursor" opt="Read"/> off
  56 </programlisting>
  57
  58
  59 <para>The
  60 <emphasis remap='B'>PipeRead</emphasis>
  61 command executes synchronously.  If you want to
  62 <fvwmref cmd="Exec"/>
  63 something, but need the command to run synchronously,
  64 you might do something like:</para>
  65
  66 <programlisting>
  67 PipeRead 'command 1&gt;&amp;2'
  68 </programlisting>
  69
  70 <para>The redirection causes any output from the program to go to stderr
  71 instead of being read as a sequence of commands by fvwm.
  72 <emphasis remap='B'>PipeRead</emphasis>
  73 returns 1 if the given command could be executed or -1 if not
  74 (see the section
  75 <fvwmref sect="conditionals" opt="conditional_commands" name="Conditional Commands"/>
  76 for the meaning of return codes).</para>
  77
  78 </section>