Initial commit

1 files changed, 94 insertions, 0 deletions

diff --git a/vo/votools/doc/colbyid.hlp b/vo/votools/doc/colbyid.hlp
new file mode 100644
index 00000000..34510f57
--- /dev/null
+++ b/vo/votools/doc/colbyid.hlp
@@ -0,0 +1,94 @@
+.help colbyid Mar12 votools
+.ih
+NAME
+colbyid -- Identify VOTable column by ID attribute
+.ih
+USAGE
+colbyid input id
+.ih
+PARAMETERS
+.ls input
+The input VOTable.
+.le
+.ls id
+The ID attribute name
+.le
+.ls column = 0
+Found column number (1-indexed, or -1 if not found)
+.le
+.ls ucd = ""
+Value of the UCD attribute for the found column.
+.le
+.ls name = ""
+Value of the NAME attribute for the found column.
+.le
+.ls print = no
+Print column field number?
+.le
+.ls found = no
+Was column found in table?
+.le
+
+.ih
+DESCRIPTION
+The \fICOLBYID\fR task is used to find the column in a VOTable with the
+named \fIID\fR attribute value of a table column.  This attribute is not
+generally guaranteed to be unique within a table and so the task will print
+a warning if multiple values are found, but only the first value found will
+be saved.  This attribute value is not generally guaranteed to be the same
+across VO services (e.g. an 'RA' and 'Dec' column may have alternate IDs),
+and so some knowledge of the table contents is assumed.
+
+If a column with the specified attribute is found, the \fIcolumn\fR parameter
+will be the one-indexed column number and the \fIfound\fR parameter will 
+be set, otherwise the \fIcolumn\fR value will be '-1'.  If the column is
+found, the \fIucd\fR and \fIname\fR values will be filled in with the
+corresponding attributes for that column or the null string.
+
+If the \fIprint\fR parameter is set, the column number will be printed to the
+standard output.
+
+.ih
+EXAMPLES
+1. Find the column in the table where the 'id' attribute is 'RA' in a
+VOTable document:
+
+.nf
+  votools> colbyid vodata$usno-b.xml RA print+
+  2
+  votools> colbyid http://iraf.noao.edu/votest/usno-b.xml RA print+
+  2
+  votools> colbyid file:///<path>/data/usno-b.xml RA print+
+  2
+  votools> colbyid file:///localhost/<path>/data/usno-b.xml RA print+
+  2
+.fi
+
+Or when a parameter is not found:
+
+.nf
+  votools> colbyid vodata$usno-b.xml FOO print+
+  -1
+.fi
+
+If a matching column is found in the table, the task parameters may be 
+queried for additional information:
+
+.nf
+  votools> =colbyid.column
+  2
+  votools> =colbyid.found
+  yes
+  votools> =colbyid.ucd
+  POS_EQ_RA_MAIN
+  votools> =colbyid.name
+  RA
+.fi
+
+.ih
+REVISIONS
+.le
+.ih
+SEE ALSO
+colbyucd, colbyname
+.endhelp