Initial commit

1 files changed, 92 insertions, 0 deletions

diff --git a/vo/votools/doc/colbyucd.hlp b/vo/votools/doc/colbyucd.hlp
new file mode 100644
index 00000000..abe52cbc
--- /dev/null
+++ b/vo/votools/doc/colbyucd.hlp
@@ -0,0 +1,92 @@
+.help colbyucd Mar12 votools
+.ih
+NAME
+colbyucd -- Identify VOTable column by UCD attribute
+.ih
+USAGE
+colbyucd input ucd
+.ih
+PARAMETERS
+.ls input
+The input VOTable.
+.le
+.ls ucd
+The UCD attribute name
+.le
+.ls column = 0
+Found column number (1-indexed, or -1 if not found)
+.le
+.ls id = ""
+Value of the ID 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 \fICOLBYUCD\fR task is used to find the column in a VOTable with the
+named \fIUCD\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.  
+
+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 \fIid\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 'ucd' attribute is 'RA' in a
+VOTable document:
+
+.nf
+  votools> colbyucd vodata$usno-b.xml POS_EQ_RA_MAIN print+
+  2
+  votools> colbyucd http://iraf.noao.edu/votest/usno-b.xml POS_EQ_RA_MAIN print+
+  2
+  votools> colbyucd file:///<path>/usno-b.xml POS_EQ_RA_MAIN print+
+  2
+  votools> colbyucd file:///localhost/<path>/usno-b.xml POS_EQ_RA_MAIN print+
+  2
+.fi
+
+Or when a parameter is not found:
+
+.nf
+  votools> colbyucd 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> =colbyucd.column
+  2
+  votools> =colbyucd.found
+  yes
+  votools> =colbyid.ucd
+  POS_EQ_RA_MAIN
+  votools> =colbyucd.name
+  RA
+.fi
+
+.ih
+REVISIONS
+.le
+.ih
+SEE ALSO
+colbyid, colbyname
+.endhelp