Initial commit

1 files changed, 94 insertions, 0 deletions

diff --git a/vo/votools/doc/colbyname.hlp b/vo/votools/doc/colbyname.hlp
new file mode 100644
index 00000000..880d1b8f
--- /dev/null
+++ b/vo/votools/doc/colbyname.hlp
@@ -0,0 +1,94 @@
+.help colbyname Mar12 votools
+.ih
+NAME
+colbyname -- Identify VOTable column by NAMED attribute
+.ih
+USAGE
+colbyname input name
+.ih
+PARAMETERS
+.ls input
+The input VOTable.
+.le
+.ls name
+The NAMED 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 \fICOLBYNAMED\fR task is used to find the column in a VOTable with the
+named \fINAMED\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 NAMEs),
+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 'name' attribute is 'RA' in a
+VOTable document:
+
+.nf
+  votools> colbyname vodata$usno-b.xml RA print+
+  2
+  votools> colbyname http://iraf.noao.edu/votest/usno-b.xml RA print+
+  2
+  votools> colbyname file:///<path>/usno-b.xml RA print+
+  2
+  votools> colbyname file:///localhost/<path>/usno-b.xml RA print+
+  2
+.fi
+
+Or when a parameter is not found:
+
+.nf
+  votools> colbyname 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> =colbyname.column
+  2
+  votools> =colbyname.found
+  yes
+  votools> =colbyname.ucd
+  POS_EQ_RA_MAIN
+  votools> =colbyname.name
+  RA
+.fi
+
+.ih
+REVISIONS
+.le
+.ih
+SEE ALSO
+colbyucd, colbyid
+.endhelp