Revision: 75958
http://sourceforge.net/p/brlcad/code/75958
Author: starseeker
Date: 2020-05-28 15:17:48 +0000 (Thu, 28 May 2020)
Log Message:
-----------
update whichid man page
Modified Paths:
--------------
brlcad/trunk/doc/docbook/system/mann/whichid.xml
Modified: brlcad/trunk/doc/docbook/system/mann/whichid.xml
===================================================================
--- brlcad/trunk/doc/docbook/system/mann/whichid.xml 2020-05-28 13:54:49 UTC
(rev 75957)
+++ brlcad/trunk/doc/docbook/system/mann/whichid.xml 2020-05-28 15:17:48 UTC
(rev 75958)
@@ -9,7 +9,7 @@
<refnamediv xml:id="name">
<refname>whichid</refname>
- <refpurpose>Lists all the regions that use one of the idents specified.
+ <refpurpose>Reports information relating to usage of the region_id property
on regions.
</refpurpose>
</refnamediv>
@@ -17,33 +17,136 @@
<refsynopsisdiv xml:id="synopsis">
<cmdsynopsis sepchar=" ">
<command>whichid</command>
-
- <arg choice="req" rep="norepeat"><replaceable>idents</replaceable></arg>
-
+ <arg choice="opt" rep="norepeat"><replaceable>options
...</replaceable></arg>
+ <arg choice="req"
rep="repeat"><replaceable>ident[-ident]</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsection xml:id="description"><title>DESCRIPTION</title>
- <para>Lists all the regions that use one of the idents specified.
+<para>
+ Reports information about the usage of the <emphasis>region_id</emphasis>
property
+ by regions in a .g file. Its default mode is to report which regions in a
.g file
+ are using one or a range of region_id values. If a root object is
specified, it
+ will report that result only for the regions in the tree of the root object.
- </para>
+ If the <option>U</option> is specified, the reporting is inverted and the
command
+ will report the ranges of <emphasis>unused</emphasis> ids rather than the
regions
+ using various ids.
+</para>
</refsection>
+<refsection xml:id="search_options"><title>OPTIONS</title>
+
+<variablelist remap="TP">
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">-U</emphasis></term>
+ <listitem>
+ <para>
+ Report unused id ranges.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis remap="B" role="bold">--root objname</emphasis></term>
+ <listitem>
+ <para>
+ Limit reporting to regions in the CSG tree below
<emphasis>objname</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</refsection>
+
+
<refsection xml:id="examples"><title>EXAMPLES</title>
- <para>The example shows the use of the <command>whichid</command> command to
list all the regions that use one of the specified idents.
- </para>
+<para>
+ For these examples the geometry file used is the standard
<emphasis>ktank.g</emphasis>
+ included with BRL-CAD.
+</para>
- <example><title>List all regions having the specified idents.</title>
+<example>
+ <title>Report all regions using region ids between 4000 and 7000.</title>
+ <para>
+ <prompt>mged></prompt><userinput>whichid 4000-7000</userinput>
+ <literallayout class="normal">
+Region[s] with ident 4001:
+ r23
+ r25
+Region[s] with ident 4050:
+ r24
+ r26
+Region[s] with ident 6001:
+ r210
+Region[s] with ident 6002:
+ r212
+ </literallayout>
+ </para>
+</example>
- <para>
- <prompt>mged></prompt><userinput>whichid 1002 1003</userinput>
- </para>
- <para>Lists all regions having idents of 1002 or 1003.
- </para>
- </example>
+<example>
+ <title>Report all regions using region ids between 1000-2000 and
4000-5000.</title>
+ <para>
+ <prompt>mged></prompt><userinput>whichid 1000-2000 4000-5000</userinput>
+ <literallayout class="normal">
+Region[s] with ident 1010:
+ r213
+Region[s] with ident 1011:
+ r214
+Region[s] with ident 4001:
+ r23
+ r25
+Region[s] with ident 4050:
+ r24
+ r26
+ </literallayout>
+ </para>
+</example>
+<example>
+ <title>Report all regions using region ids between 1000-2000 and 4000-5000,
limiting
+ results to regions in the <emphasis>tank</emphasis> geomtry tree.</title>
+ <para>
+ <prompt>mged></prompt><userinput>whichid --root tank 1000-2000
4000-5000</userinput>
+ <literallayout class="normal">
+Region[s] with ident 4001:
+ r23
+ r25
+Region[s] with ident 4050:
+ r24
+ r26
+ </literallayout>
+ </para>
+</example>
+
+<example>
+ <title>Report all unused region_id ranges in the database between 1 and
1000.</title>
+ <para>
+ <prompt>mged></prompt><userinput>whichid -U 1-1000</userinput>
+ <literallayout class="normal">
+Unused idents:
+ 1
+ 4
+ 6-99
+ 105-109
+ 112-114
+ 116-119
+ 122-159
+ 161-164
+ 166-204
+ 210-224
+ 226-504
+ 519-609
+ 620-719
+ 730-829
+ 840-939
+ 950-1000
+ </literallayout>
+ </para>
+</example>
+
</refsection>
<refsection xml:id="author"><title>AUTHOR</title><para>BRL-CAD
Team</para></refsection>
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
_______________________________________________
BRL-CAD Source Commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
