<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="edit">

<refmeta>
  <refentrytitle>EDIT</refentrytitle>
  <manvolnum>nged</manvolnum>
  <refmiscinfo class="source">BRL-CAD</refmiscinfo>
  <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
</refmeta>

<refnamediv xml:id="name">
  <refname>edit</refname>
  <refpurpose>
    Edits objects, using <emphasis>subcommand</emphasis>s.
  </refpurpose>
</refnamediv>

<!-- body begins here -->
<refsynopsisdiv xml:id="synopsis">
  <cmdsynopsis sepchar=" ">
    <!-- hv3 hack to prevent line insertion -->
    <link linkend="dummy_id">&#09;</link>
    <command xml:id="dummy_id">edit</command>
    <arg>
      <synopfragmentref linkend="subcommands">subcommand</synopfragmentref>
      <arg><synopfragmentref linkend="args">args</synopfragmentref></arg>
      <arg choice="plain" rep="repeat"><replaceable>object</replaceable></arg>
    </arg>
    <sbr/>

    <sbr/>
    <synopfragment xml:id="subcommands">
      <group choice="plain" rep="repeat">
	<arg choice="plain">help</arg>
	<arg choice="plain">translate</arg>
	<arg choice="plain">rotate</arg>
	<arg choice="plain">scale</arg>
	<arg choice="plain"> </arg>
      </group>
    </synopfragment>

    <sbr/>
    <synopfragment xml:id="args">
      <group><synopfragmentref linkend="from">from</synopfragmentref></group>
      <arg choice="plain">
	<synopfragmentref linkend="to">to</synopfragmentref>
      </arg>
      <arg rep="repeat">
	<synopfragmentref linkend="args">more_args</synopfragmentref>
      </arg>
    </synopfragment>

    <sbr/>
    <synopfragment xml:id="from">
      <arg><option>-n</option></arg>
      <arg choice="plain"><option>-k</option></arg>
      <group choice="req">
	<arg choice="plain">
	  <synopfragmentref linkend="obj">from_object</synopfragmentref>
	</arg>
	<arg choice="plain">
	  <synopfragmentref linkend="pos">from_position</synopfragmentref>
	</arg>
      </group>
    </synopfragment>

    <sbr/>
    <synopfragment xml:id="to">
      <arg><option>-n</option></arg>
      <group>
	<arg choice="plain"><option choice="plain">-a</option></arg>
	<arg choice="plain"><option choice="plain">-r</option></arg>
      </group>
      <group choice="req">
	<arg choice="plain">
	  <synopfragmentref linkend="obj">to_object</synopfragmentref>
	</arg>
	<arg choice="plain">
	  <synopfragmentref linkend="pos">to_position</synopfragmentref>
	</arg>
      </group>
    </synopfragment>

    <sbr/>
    <synopfragment xml:id="pos">
      <group choice="plain">
	<arg choice="req">
	  <synopfragmentref linkend="coord">coords</synopfragmentref>
	</arg>
	<arg choice="req">
	  <arg>
	    <arg choice="plain"><option>-x</option></arg>
	    <group choice="req">
	      <arg choice="plain"><replaceable>x</replaceable></arg>
	      <arg choice="plain">
		<synopfragmentref linkend="obj">x-obj</synopfragmentref>
	      </arg>
	    </group>
	  </arg>
	  <arg>
	    <arg choice="plain"><option>-y</option></arg>
	    <group choice="req">
	      <arg choice="plain"><replaceable>y</replaceable></arg>
	      <arg choice="plain">
		<synopfragmentref linkend="obj">y-obj</synopfragmentref>
	      </arg>
	    </group>
	  </arg>
	  <arg>
	    <arg choice="plain"><option>-z</option></arg>
	    <group choice="req">
	      <arg choice="plain"><replaceable>z</replaceable></arg>
	      <arg choice="plain">
		<synopfragmentref linkend="obj">z-obj</synopfragmentref>
	      </arg>
	    </group>
	  </arg>
	</arg>
      </group>
    </synopfragment>

    <sbr/>
    <synopfragment xml:id="obj">
      <arg choice="plain">
	<arg><replaceable>path/</replaceable></arg>
	<arg choice="plain"><replaceable>object</replaceable></arg>
      </arg>
      <arg>
	<synopfragmentref linkend="coord">offset_distance</synopfragmentref>
      </arg>
    </synopfragment>

    <sbr/>
    <synopfragment xml:id="coord">
      <arg choice="plain"><replaceable>x</replaceable></arg>
      <arg>
	<arg choice="plain"><replaceable>y</replaceable></arg>
	<arg><replaceable>z</replaceable></arg>
      </arg>
    </synopfragment>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection xml:id="description">
  <info><title>DESCRIPTION</title></info>
  <para>
    Operates on objects in the database, solely through the use
    of <emphasis>subcommand</emphasis>s. The flexibility of the
    <command>edit</command> <emphasis>subcommand</emphasis>s lies
    in their utilization of a common style of syntax.
    Coordinates in model space, offsets, and objects are all
    accepted interchangeably as reference points. A single
    reference point is equivalent to an absolute point in model
    space. A pair of refence points specifies a distance or an
    angle, and is supplied as a set of
    <emphasis>from</emphasis> - <emphasis>to</emphasis> arguments (a
    <emphasis>from</emphasis> argument is similar to the concept
    of a keypoint). Reference points may be incomplete, and
    specify only one or two coordinates.
  </para> 
  <para>
    The format of the standard options accepted by subcommands, 
    <option>-n</option>,
    <option>-k</option>,
    <option>-a</option>/<option>-r</option>, and
    <option>-x</option>/
    <option>-y</option>/<option>-z</option>, is defined
    here. The interpretation of these options, however, is left up
    to the implementation of a given subcommand.
  </para>
  <para>
    All edit commands interpret a lone point
    (<arg choice="plain"> . </arg>) as a special
    operator, called the batch operator. The batch operator is
    accepted as an argument to the options 
    <option>-k</option>, <option>-a</option>, and <option>-r</option>.
    In a batch operation, each individual
    <emphasis>object</emphasis> is operated on using the bounding
    box center of itself in place of the batch
    operator. While all <emphasis>object</emphasis>'s move
    together in a non-batch operation, in batch operations, each
    <emphasis>object</emphasis> may move independently of all
    other <emphasis>object</emphasis>'s.
  </para>
  <para>
    If any <emphasis>from</emphasis> coordinates are omitted, they
    default to the bounding box center of the first
    <emphasis>object</emphasis> is used as <emphasis>from</emphasis>.
    To use the natural origin of the first
    <emphasis>object</emphasis> as <emphasis>from</emphasis>,
    <emphasis>from_object</emphasis> must be manually set to whatever
    <emphasis>object</emphasis> is set to. If any
    <emphasis>to</emphasis> coordinates are omitted, they default to
    the values set in <emphasis>from</emphasis>.
  </para>

  <para>
    The quantity and arrangement of standard <command>edit</command>
    arguments as well as their intepretation depends upon the
    subcommand. See the manual page for a given subcommand for more
    information on its usage:<sbr/>
    <prompt>&gt; </prompt>
    <userinput>man edit_<replaceable>subcommandName</replaceable></userinput>
  </para>
</refsection>

<refsection xml:id="options"><info><title>OPTIONS</title></info>
  <variablelist remap="TP">
    <varlistentry>
      <term><option>-n</option></term>
      <listitem>
	<para>
	  Use the natural origin of the object specified as an
	  argument to <option>-k</option>, <option>-a</option>, or
	  <option>-r</option> rather than its bounding box center.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-k</option></term>
      <listitem>
	<para>
	  Sets the keypoint <emphasis>from</emphasis> to either
	  <emphasis>from_object</emphasis>'s bounding box center or
	  <emphasis>from_position</emphasis>. 
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-a</option></term>
      <listitem>
	<para>
	  Sets the destination point <emphasis>to</emphasis> to
	  either <emphasis>to_object</emphasis>'s bounding box center
	  or <emphasis>to_position</emphasis>. 
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><option>-r</option></term>
      <listitem>
	<para>
	  Sets the destination point <emphasis>to</emphasis> to 
	  a point offset by <emphasis>to_position</emphasis> from
	  the <emphasis>from</emphasis> point.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
	<group choice="plain">
	  <arg choice="plain"><option>-x</option></arg>
	  <arg choice="plain"><option>-y</option></arg>
	  <arg choice="plain"><option>-z</option></arg>
	  </group>
      </term>
      <listitem>
	<para>
	  Sets the coordinate of a particular axis.
	</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsection>

<refsection xml:id="examples"><info><title>EXAMPLES</title></info>
  <example>
    <info><title>
      Get the authoritative list of available subcommands.
    </title></info>
    <variablelist>
      <varlistentry>
	<term>
	  <prompt>&gt; </prompt>
	  <userinput>edit</userinput>
	</term>
      </varlistentry>
      <varlistentry>
	<term>
	  <prompt>&gt; </prompt>
	  <userinput>edit help</userinput>
	</term>
	<listitem>
	  <para>
	    Prints usage and a list of available subcommands.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </example>

  <example><info><title>Get the usage of a subcommand.</title></info>
    <variablelist>
      <varlistentry>
        <term>
          <prompt>&gt; </prompt>
          <userinput>edit translate</userinput>
        </term>
        <listitem>
          <para>
	    Print usage of the translate subcommand
          </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </example>

  <example>
    <info><title>
      Use the help subcommand to print extended usage of subcommands.
    </title></info>
    <variablelist>
      <varlistentry>
	<term>
	  <prompt>&gt; </prompt>
	  <userinput>edit translate help</userinput>
	</term>
      </varlistentry>

      <varlistentry>
	<term>
	  <prompt>&gt; </prompt>
	  <userinput>edit help translate</userinput>
	</term>
	<listitem>
	  <para>
	    Print extended usage of the translate subcommand. Each
	    subcommand also accepts <emphasis>help</emphasis> as an
	    argument, so that the extended usage is still available if
	    <command>edit translate</command> is aliased to something
	    else.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </example>

  <example>
    <info><title>
	A fake subcommand is used to show how standard
	<command>edit</command> arguments and nonstandard
	<command>edit</command> arguments are used.
    </title></info>
    <variablelist>
      <varlistentry>
        <term>
          <prompt>&gt; </prompt>
          <userinput>edit fake_subcmd -B 12 -k sph.s 1.5 7 -a 0 0 0 cube.s</userinput>
        </term>
        <listitem>
          <para>
	    The nonstandard <option>-B</option> option is unique to
	    <command>fake_subcmd</command>. An explanation of how it
	    is used would be found in the manual for fake_subcmd, if
	    there were one. The remaining options and arguments are
	    standardized. The <option>-k</option> and
	    <option>-a</option> options are used to specify a
	    <emphasis>from</emphasis> - <emphasis>to</emphasis> pair,
	    as defined in this manual for <command>edit</command>.
	    The interpretation of the vector created by these points
	    would be defined in the <command>fake_subcmd</command>
	    manual.
          </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </example>
       
</refsection>

<info><corpauthor>BRL-CAD Team</corpauthor></info>

<refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
  
  <para>
    Reports of bugs or problems should be submitted via electronic
    mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.
  </para>
</refsection>
</refentry>
