Index: /trunk/docs/ProjectBook/ProjectBook.tex
===================================================================
--- /trunk/docs/ProjectBook/ProjectBook.tex	(revision 222)
+++ /trunk/docs/ProjectBook/ProjectBook.tex	(revision 222)
@@ -0,0 +1,122 @@
+\documentclass[10pt,a4paper]{book}
+\usepackage{natbib}
+%\usepackage{fancyheadings}
+\usepackage{fancyhdr}
+\usepackage{array}
+\usepackage{xspace}
+\usepackage{hyperref}
+\hypersetup{colorlinks=true}
+\usepackage{amsmath}
+\usepackage{amsfonts}
+
+\usepackage{setspace}
+\singlespacing
+
+%\textwidth=165 mm
+%\textheight=248 mm
+%\topmargin=-15 mm
+%\oddsidemargin=0 mm
+%\parindent=6 mm
+
+\pagestyle{fancy}
+\rhead{}
+\lhead{}
+\lfoot{\today}
+\cfoot{}
+\rfoot{\thepage}
+\renewcommand{\headrulewidth}{0cm}
+%\renewcommand{\footrulewidth}{0cm}
+
+\newcommand{\eg}{e.g.\xspace}
+\newcommand{\ie}{i.e.\xspace}
+\newcommand{\fdg}{\hbox{$.\!\!^\circ$}}
+\newcommand{\cfitsio}{\textsc{cfitsio}\xspace}
+\newcommand{\subint}{\textsc{subint}\xspace}
+\newcommand{\history}{\textsc{history}\xspace}
+\newcommand{\move}{\textsc{move}\xspace}
+\newcommand{\pvoconvert}{\textsc{pvoconvert}\xspace}
+\newcommand{\pvosummary}{\textsc{pvosummary}\xspace}
+\newcommand{\pvoconesearch}{\textsc{pvoconeseach}\xspace}
+\newcommand{\hi}{H\textsc{i}\xspace}
+\newcommand{\entrylabel}[1]{\mbox{\texttt{#1:}}\hfil}
+\newenvironment{entry}
+{\begin{list}{}%
+    {\renewcommand{\makelabel}{\entrylabel}%
+      \setlength{\leftmargin}{33mm}%
+      \setlength{\labelwidth}{33mm}%
+      \setlength{\labelsep}{0pt}%
+      \setlength{\itemsep}{3pt}%
+      \setlength{\parsep}{2pt}%
+    }%
+  }%
+  {\end{list}%
+}
+
+\newlength{\MyLen}
+\newcommand{\Lentrylabel}[1]{%
+  \settowidth{\MyLen}{\texttt{#1:}}%
+  \ifthenelse{\lengthtest{\MyLen > \labelwidth}}%
+  {\parbox[b]{\labelwidth}% term > labelwidth
+    {\makebox[0pt][l]{\texttt{#1:}}\\}}%
+  {\texttt{#1:}}% term < labelwidth
+  \hfil\relax}
+
+\newenvironment{Lentry}%
+{\renewcommand{\entrylabel}{\Lentrylabel}\begin{entry}
+    \setlength{\itemsep}{3pt}%
+    % \setlength{\leftmargin}{25mm}%
+    % \setlength{\itemindent}{0mm}%
+    % \setlength{\listparindent}{0mm}%
+    \setlength{\labelsep}{0mm}%
+  }%
+  {\end{entry}%
+}
+
+
+\title{The PulsarVO Project Book}
+\author{Matthew Whiting}
+
+\begin{document}
+
+\maketitle
+\tableofcontents
+
+\chapter{Introduction}
+\label{ch-intro}
+\input{introduction}
+
+\chapter{Conversion software}
+\label{ch-convert}
+\input{conversionSoftware}
+
+\chapter{Database}
+\label{ch-database}
+\input{database}
+
+\chapter{Web Archive}
+\label{ch-web}
+\input{web}
+
+\chapter{Virtual Observatory interface}
+\label{ch-vo}
+\input{vo}
+
+\appendix
+\chapter{Glossary}
+\input{glossary}
+
+\chapter{Formulae used}
+\input{formulae} 
+
+\chapter{Conversion Software Information}
+\label{app-convert}
+\input{conversionAppendix}
+
+\bibliographystyle{plainnat}
+\bibliography{pulsars}
+
+\end{document}
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: t
+%%% End: 
Index: /trunk/docs/ProjectBook/conversionAppendix.tex
===================================================================
--- /trunk/docs/ProjectBook/conversionAppendix.tex	(revision 222)
+++ /trunk/docs/ProjectBook/conversionAppendix.tex	(revision 222)
@@ -0,0 +1,439 @@
+\section{Conversion of header keywords}
+\label{app-headers}
+
+The following pages show how the header parameters listed in the
+existing survey data map to header keywords in the PSRFITS file. The
+parameter names are listed as they are described in the definition
+files, along with their size in bytes (and their length, if they are
+arrays -- this is done in FORTRAN format). 
+
+Alongside the parameter names are the PSRFITS keywords that each
+parameter maps to. These are labelled by the header unit that the
+keyword belongs to: \eg \verb|PHU -> STT_DATE| means the keyword
+\verb|STT_DATE| in the Primary HDU (abbreviated herein as PHU).
+
+Not all parameters have a place in the PSRFITS structure. Those
+without a clear place to go have their comments bracketed by \verb|**|
+-- many of these are simply irrelevant for the PSRFITS data structure,
+while some may need the appropriate keyword to be added to the PSRFITS
+definition. 
+
+The third sub-section of this appendix goes the other way, and
+indicates what keywords in the PSRFITS header are defined and which
+will need some input from elsewhere. This input, where necessary, will
+be of a generic nature -- such as telescope information -- that will
+most likely be able to be hard-coded into the conversion program. We
+only discuss the primary HDU and the \textsc{subint} binary table, as
+these are the two most important extensions.
+
+\newpage
+\subsection{S70 survey}
+{\footnotesize
+\begin{verbatim}
+ synch_hd*8,         :  Used to determine Survey type
+ version_hd*4,       :  
+ tapenr_hd*4,        :  
+ scan_cntr_hd*4,     :  
+ blk_cntr_hd*8,      :  Used to record the initial block of a FITS file.
+ date_hd*8,          :  PHU -> STT_DATE, plus FITS filename
+ mjd_hd*8,           :  PHU -> STT_IMJD
+ ut_strt_hd*16,      :  PHU -> STT_TIME
+ lst_strt_hd*12,     :  PHU -> STT_LST	
+ coord_type_hd*2     :  PHU -> COORD_MD
+	
+ ra_strt_hd*16,      :  PHU -> STT_CRD1
+ dec_strt_hd*16,     :  PHU -> STT_CRD2
+ gl_strt_hd*8,       :  PHU -> STT_CRD1
+ gb_strt_hd*8,       :  PHU -> STT_CRD2
+ scan_rate_hd*8,     :
+ scan_len_hd*8,      :
+ comment_hd*64,      :  PHU -> SRC_NAME (only the Field ID Gxxxxx)
+ nfilter_hd*2,       :  PHU -> NRCVR
+ chanbw_hd(2)*8,     :  SUBINT -> FREQ,     PHU->OBSFREQ
+ nchan_hd(2)*4,      :  SUBINT -> NCH_FILE, PHU->OBSFREQ
+ freq_chan1_hd(2)*12 :  SUBINT -> DAT_FREQ, PHU->OBSFREQ
+		      
+ samp_int_hd(2)*12,  :  SUBINT -> TBIN, TSAMP
+ samp_grp_hd(2)*4,   :  Used to keep track of the number of samples
+ grp_blk_hd*8,       :  Used to keep track of the number of samples
+ blk_sec_hd*8,       :  SUBINT -> TSUBINT, OFFSUB
+ data1_hd*4,         :
+ ut_hd*16,           :  PHU -> DATE_OBS, plus FITS filename
+ lst_hd*12,          :  SUBINT -> LST_SUB   
+ RA_hd*16,           :  SUBINT -> RA_SUB     
+ Dec_hd*16,          :  SUBINT -> DEC_SUB   
+ gl_hd*8,            :  SUBINT -> GLON_SUB 
+ gb_hd*8,            :  SUBINT -> GLAT_SUB 
+ tel_zen_hd*8        :  SUBINT -> TEL_AZ     
+		      						       
+ tel_az_hd*8,        :  SUBINT -> TEL_ZEN 
+ status_hd(4)*8,     :
+ tpower_hd(8)*8,     :
+ nblk_read_hd*8,     :
+ scan_ratel_hd*8,    :
+ scan_rateb_hd*8,    :
+ byte_grp_hd*4,      :
+ ibeam_hd*4,         :  Not used for S70 data -- only one beam.
+ psrname_hd*12,      :
+ data2_hd*4,         :
+ obs_filen_hd*16,    :
+ nbits_hd(2)*2,      :  SUBINT -> TFORM for DATA field
+ ddm_hd*8,           :
+ nddch_hd(2)*4,      :
+ move_hd*2,          :  Used to determine whether scan has finished.
+ pnterr_hd*6,        :
+ tree_hd*2,          :
+ nsys_hd*2,          :
+ telid_hd*10,        :  PHU -> TELESCOP
+ nbeam_hd*4,         :
+ reserve*38          :  ** blank field to fill up 640 bytes **
+\end{verbatim}
+}
+\newpage
+\subsection{Multibeam data}
+{\footnotesize
+\begin{verbatim}
+ program_hd*6        :  Used to determine Survey type
+ version_hd*4        :
+ tapenr_hd*6         :
+ file_cntr_hd*4      :
+ blk_cntr_hd*8       :  Used to record the initial block of a FITS file.
+ date_hd*8           :  PHU -> STT_DATE
+ mjd_hd*8            :  PHU -> STT_IMJD
+ ut_strt_hd*16       :  PHU -> STT_TIME
+ lst_strt_hd*12      :  PHU -> STT_LST
+ coord_type_hd*2     :  PHU -> COORD_MD
+ ra_strt_hd*16       :  PHU -> STT_CRD1  (if coord_type=J2000)
+ dec_strt_hd*16      :  PHU -> STT_CRD2
+ gl_strt_hd*8        :  PHU -> STT_CRD1  (if coord_type=Galactic)
+ gb_strt_hd*8        :  PHU -> STT_CRD2	
+ feed_angle_hd*8     :  PHU -> FA_REQ, SUBINT->FD_ANG
+ obs_time_hd*8       : 
+ comment_hd*64       : 
+ nfilter_hd*2        :  PHU -> NRCVR
+ chanbw_hd(2)*8      :  SUBINT -> FREQ,     PHU->OBSFREQ
+ nchan_hd(2)*4       :  SUBINT -> NCH_FILE, PHU->OBSFREQ
+ freq_chan1_hd(2)*12 :  SUBINT -> DAT_FREQ, PHU->OBSFREQ
+
+ samp_int_hd(2)*12   :  SUBINT -> TBIN, TSAMP			   
+ samp_grp_hd(2)*4    :	Used to keep track of the number of samples
+ grp_blk_hd*8        :	Used to keep track of the number of samples
+ blk_sec_hd*8        :  SUBINT -> TSUBINT 
+ fdcntrl_hd*2        :  PHU -> FD_MODE
+ data_hd(2)*1        :
+ ut_hd*16            :  PHU -> DATE_OBS, plus FITS filename
+ lst_hd*12           :  SUBINT -> LST_SUB  
+ RA_hd*16            :  SUBINT -> RA_SUB   
+ Dec_hd*16           :  SUBINT -> DEC_SUB  
+ gl_hd*8             :  SUBINT -> GLON_SUB 
+ gb_hd*8             :  SUBINT -> GLAT_SUB 
+ tel_zen_hd*8        :  SUBINT -> TEL_AZ   
+					   	   
+ tel_az_hd*8         :  SUBINT -> TEL_ZEN   
+ atten_hd(4)*4       :
+ tpower_hd(20)*4     :
+ nblk_read_hd*8      :
+ scan_ratel_hd*8     :
+ scan_rateb_hd*8     :
+ nbeam_hd*4          :
+ ibeam_hd*4          :  Goes in FITS filename.
+ pname_hd*16         :  PHU -> SRC_NAME  (not necessarily a pulsar name though)
+ obs_filen_hd*16     :
+ nbits_hd(2)*2       :  SUBINT -> TFORM for DATA entry
+ ddm_hd*8            :
+ nddch_hd(2)*4       :
+ move_hd*2           :  Used to determine if scan has finished
+ pnterr_hd*6         :
+ tree_hd*2           :
+ nsys_hd*2           :
+ telid_hd*10         :  PHU -> TELESCOP
+ pangle_hd*8         :  SUBINT -> PAR_ANG 
+ smp_bsw_hd*8        :
+ cal_cycle_hd*4      :  PHU -> CAL_DCYC
+\end{verbatim}
+}
+
+\newpage
+\section{Identification of fields for namespace}
+\label{app-headerFields}
+
+{\scriptsize
+\begin{tabular}{l|c|lll|lll}
+ENUM keyword &used? &S70 parameter &start &width 
+                                      &PM parameter &start &width\\
+ \hline
+
+CODE         &  &synch       &0   &8    &program     &0   &6    \\
+VERSION      &  &version     &8   &4    &version     &6   &4    \\
+TAPENR	     &  &tapenr      &12  &4    &tapenr      &10  &6    \\
+SCAN\_CNTR   &  &scan\_cntr  &16  &4    &scan\_cntr  &16  &4    \\
+BLK\_CNTR    &  &blk\_cntr   &20  &8    &blk\_cntr   &20  &8    \\
+DATE	     &* &date	     &28  &8    &date	     &28  &8     \\
+ MJD	     &* &mjd	     &36  &8    &mjd	     &36  &8     \\
+UT\_STRT     &* &ut\_strt    &44  &16   &ut\_strt    &44  &16    \\
+LST\_STRT    &  &lst\_strt   &60  &12   &lst\_strt   &60  &12    \\
+COORD\_TYPE  &* &coord\_type &72  &2    &coord\_type &72  &2     \\
+RA\_STRT     &  &ra\_strt    &74  &16   &ra\_strt    &74  &16    \\
+DEC\_STRT    &  &dec\_strt   &90  &16   &dec\_strt   &90  &16    \\
+GL\_STRT     &  &gl\_strt    &106 &8    &gl\_strt    &106 &8     \\
+GB\_STRT     &  &gb\_strt    &114 &8    &gb\_strt    &114 &8     \\
+FEED\_ANGLE  &* &[RESERVE]   &--- &---  &feed\_angle &122 &8     \\
+OBS\_TIME    &  &[RESERVE]   &--- &---  &obs\_time   &130 &8    \\
+SCAN\_RATE   &  &scan\_rate  &122 &8    &[RESERVE]   &--- &---  \\
+SCAN\_LEN    &  &scan\_len   &130 &8    &[RESERVE]   &--- &---  \\
+COMMENT      &  &comment     &138 &64   &comment     &138 &64   \\
+NFILTER	     &* &nfilter     &202 &2    &nfilter     &202 &2     \\
+CHANBW	     &* &chanbw      &204 &2x8  &chanb       &204 &2x8   \\
+NCHAN	     &* &nchan	     &220 &2x4  &nchan	     &220 &2x4   \\
+FREQ\_CHAN1  &* &freq\_chan1 &228 &2x12 &freq\_chan1 &228 &2x12  \\
+SAMP\_INT    &* &samp\_int   &252 &2x12 &samp\_int   &252 &2x12 \\
+SAMP\_GRP    &* &samp\_grp   &276 &2x4  &samp\_grp   &276 &2x4  \\
+GRP\_BLK     &* &grp\_blk    &284 &8    &grp\_blk    &284 &8    \\
+BLK\_SEC     &* &blk\_sec    &292 &8    &blk\_sec    &292 &8     \\
+FDCNTRL	     &  &[RESERVE]   &--- &---  &fdcntrl     &300 &2     \\
+DATA\_TYPE   &  &data1	     &300 &4    &data        &302 &2x1  \\
+UT	     &* &ut	     &304 &16   &ut  	     &304 &16   \\
+LST	     &* &lst	     &320 &12   &lst	     &320 &12    \\
+RA	     &* &ra	     &332 &16   &RA	     &332 &16    \\
+DEC	     &* &dec	     &348 &16   &Dec	     &348 &16    \\
+GL	     &  &gl	     &364 &8    &gl	     &364 &8     \\
+GB	     &  &gb	     &372 &8    &gb	     &372 &8     \\
+TEL\_ZEN     &* &tel\_zen    &380 &8    &tel\_zen    &380 &8     \\
+TEL\_AZ	     &* &tel\_az     &388 &8    &tel\_az     &388 &8     \\
+STATUS	     &  &status      &396 &4x8  &[RESERVE]   &--- &---  \\
+ATTEN	     &  &[RESERVE]   &--- &---  &atten       &396 &4x4   \\
+TPOWER	     &  &tpower      &428 &8x8  &tpower      &412 &20x4 \\
+NBLK\_READ   &  &nblk\_read  &492 &8    &nblk\_read  &492 &8    \\
+SCAN\_RATEL  &  &scan\_ratel &500 &8    &scan\_ratel &500 &8    \\
+SCAN\_RATEB  &  &scan\_rateb &508 &8    &scan\_rateb &508 &8    \\
+BYTE\_GRP    &  &byte\_grp   &516 &4    &[RESERVE]   &--- &---  \\
+NBEAM	     &  &nbeam	     &598 &4    &nbeam	     &516 &4    \\
+IBEAM	     &* &ibeam	     &520 &4    &ibeam	     &520 &4    \\
+PSRNAME	     &* &psrname     &524 &12   &pname	     &524 &16   \\
+DATA\_TWO    &  &data2	     &536 &4    &[RESERVE]   &--- &---  \\
+OBS\_FILEN   &  &obs\_filen  &540 &16   &obs\_filen  &540 &16   \\
+NBITS	     &* &nbits	     &556 &2x2  &nbits	     &556 &2x2  \\
+DDM	     &  &ddm	     &560 &8    &ddm	     &560 &8    \\
+NDDCH	     &  &nddch	     &568 &2x4  &nddch	     &568 &2x4  \\
+MOVE	     &* &move	     &576 &2    &move	     &576 &2    \\
+PNTERR	     &  &pnterr	     &578 &6    &pnterr      &578 &6    \\
+TREE	     &  &tree	     &584 &2    &tree	     &584 &2    \\
+NSYS	     &  &nsys	     &586 &2    &nsys	     &586 &2    \\
+TELID	     &* &telid	     &588 &10   &telid	     &588 &10   \\
+PANGLE	     &* &[RESERVE]   &--- &---  &pangle      &598 &8    \\
+SMP\_BSW     &  &[RESERVE]   &--- &---  &smp\_bsw    &606 &8    \\
+CAL\_CYCLE   &  &[RESERVE]   &--- &---  &cal\_cycle  &614 &4    \\
+RESERVE      &  &reserve     &602 &38   &reserve     &618 &22   
+\end{tabular}
+}
+
+\section{How keywords are defined.}
+
+In this section we summarise the keywords and other header parameters
+that go into the PSRFITS file, together with their comment field, and
+detail how the value is arrived at. The value will be generated by:
+\begin{itemize}
+\item Some fixed value that is a constant for the particular survey --
+  either a numeric value or a string.
+\item A direct substitution of the existing file's header values
+(written as \eg \verb|<NFILTER>|, using the enumeration setup detailed
+in the previous setction)
+\item A value calculated from one or more header values via some
+  formula. 
+\end{itemize}
+
+In the case of the first option, we sometimes separate according to
+the survey under consideration -- the options for each survey are then
+listed separately.
+
+The keywords are divided according to the extension, where we show the
+PHU and the \subint extensions. We also show new keywords that are
+added to the PHU, that involve information not in the PSRFITS
+definition that will be useful for VO purposes. These are added using
+the \texttt{PSRFits::addNewKeywords()} function.
+
+For the \subint table, we give the column values that are set for each
+block -- the ``Column Title'' is the \texttt{TTFORM\#} parameter in
+the header. Where the columns are multi-valued, we show how the $i$th
+value is calculated.
+
+\newpage
+\subsection{Existing PHU keywords}
+
+\begin{tabular}{|l|>{\setlength{\rightskip}{0pt plus 2cm}}p{7cm}|>{\setlength{\rightskip}{0pt plus 2cm}}p{5cm}|}\hline
+FITS Keyword & Comment field from FITS header & Value \\ \hline\hline
+
+DATE     & File creation date (\mbox{YYYY-MM-DDThh:mm:ss} UTC) & Date of file creation, from \texttt{fits\_get\_system\_time()}.\\\hline
+
+OBSERVER & Observer name(s)                         & \textbf{not set}\\ \hline
+
+PROJID   & Project name                             & Survey-specific project name.\\ \hline
+
+TELESCOP & Telescope name                           & \verb|<TELID>|\\\hline
+
+ANT\_X    & [m] Antenna ITRF X-coordinate (D)       & -4554231.5 \\\hline
+
+ANT\_Y    & [m] Antenna ITRF Y-coordinate (D)       & 2816759.1 \\\hline
+
+ANT\_Z    & [m] Antenna ITRF Z-coordinate (D)       & -3454036.3 \\\hline
+
+FRONTEND & Rx and feed ID                           & \emph{S70}: ``70cm\_Cavity\_Disk'', \emph{PM/PH}: ``20cm\_MB''\\\hline
+
+FD\_POLN  & LIN or CIRC                             & ``LIN'' \\\hline
+
+FD\_HAND  & +/- 1. +1 is LIN:A=X,B=Y, CIRC:A=L,B=R (I) &  \emph{S70}: 0, \emph{PM/PH}: $+1$\\\hline
+
+FD\_SANG  & [deg] FA of E vect for equal sig in A\&B (E) &  \emph{S70}: 0, \emph{PM/PH}: $-90$\\\hline
+
+FD\_XYPH  & [deg] Phase of A\^* B for injected cal (E) &  \emph{S70}: 0, \emph{PM/PH}: 0\\\hline
+
+BACKEND  & Backend ID                               & ``FB\_1BIT''\\ \hline
+
+BECONFIG & Backend configuration file name          & ``'' \\ \hline
+
+BE\_PHASE & 0/+1/-1 BE cross-phase:0 unknown,+/-1 std/rev & 0 \\\hline
+
+BE\_DCC   & 0/1 BE downconversion conjugation corrected & 0 \\\hline
+
+TCYCLE   & [s] On-line cycle time (D)               & 0 \\\hline
+
+NRCVR    & Number of receiver channels (I)          & \verb|<NFILTER>|\\\hline
+
+OBS\_MODE & (PSR, CAL, SEARCH)                      & ``SEARCH'' \\\hline
+
+SRC\_NAME & Source or scan ID                       & \verb|<PSRNAME>| (Note that this will be blank for survey data!)\\\hline
+
+COORD\_MD & Coordinate mode (J2000, Gal, Ecliptic, etc.)& \verb|<COORD_TYPE>|, translated into text.\\ \hline
+
+STT\_CRD1 & Start coord 1 (hh:mm:ss.sss or ddd.ddd) & \verb|<RA>|\\\hline
+
+STT\_CRD2 & Start coord 2 (-dd:mm:ss.sss or -dd.ddd)& \verb|<DEC>|\\\hline
+
+TRK\_MODE & Track mode (TRACK, SCANGC, SCANLAT)     & ``TRACK'' \\\hline
+
+STP\_CRD1 & Stop coord 1 (hh:mm:ss.sss or ddd.ddd)  & \verb|<RA>|\\\hline
+
+STP\_CRD2 & Stop coord 2 (-dd:mm:ss.sss or -dd.ddd) & \verb|<DEC>|\\\hline
+
+SCANLEN  & [s] Requested scan length (E)            & \emph{S70}: 152, \emph{PM}: 2100, \emph{PH}: 265 \\ \hline
+
+FD\_MODE  & Feed track mode - FA, CPA, SPA, TPA     & \emph{S70}: ``FIXED'', \emph{PM/PH}: ``CPA'' \\ \hline
+
+FA\_REQ   & [deg] Feed/Posn angle requested (E)     & \emph{S70}: 0, \emph{PM/PH}: 30 \\ \hline
+
+CAL\_MODE & Cal mode (OFF, SYNC, EXT1, EXT2)        & ``OFF'' \\ \hline
+
+CAL\_FREQ & [Hz] Cal modulation frequency (E)       &  0 \\\hline
+
+CAL\_DCYC & Cal duty cycle (E)                      & 0 \\\hline
+
+CAL\_PHS & Cal phase (wrt start time) (E)           & 0 \\\hline
+
+STT\_DATE & Start UT date (YYYY-MM-DD)              & \verb|<DATE>|, with the century added on to the start, and '/' changed to '-' \\\hline
+
+STT\_TIME & Start UT (hh:mm:ss)                     & \verb|<UT>|\\ \hline
+
+STT\_IMJD & Start MJD (UTC days) (J - long integer) & \verb|<MJD>|\\ \hline
+
+STT\_SMJD & [s] Start time (sec past UTC 00h) (J)   & \verb|<UT>| as a decimal $\times$ 3600.\\ \hline
+
+STT\_OFFS & [s] Start time offset (D)               & 0 \textbf{NEED TO CHECK THIS.}\\ \hline
+
+STT\_LST  & [s] Start LST (D)                       & \verb|<LST>| as a decimal $\times$ 3600.\\ \hline
+\end{tabular}
+
+\subsection{New PHU keywords}
+
+\begin{tabular}%
+{|l|>{\setlength{\rightskip}{0pt plus 2cm}}p{7cm}|>{\setlength{\rightskip}{0pt plus 2cm}}p{5cm}|}\hline
+FITS Keyword & Comment field from FITS header & Value \\ \hline\hline
+
+OBSFREQ  & [MHz] Observing frequency 
+& \verb|<FREQ_CHAN1>| $+$ ((\verb|<NCHAN>|$-1)/2) \times$
+\verb|<CHANBW>| \\ \hline
+
+RA       & Right Ascension & \verb|<RA>| \\ \hline
+
+DEC      & Declination     & \verb|<DEC>| \\ \hline
+
+DATE-OBS & Date of observation (\mbox{YY-MM-DDThh:mm:ss UTC})  &\verb|<DATE>|, with the century added on to the start, and '/'  changed to '-' \\\hline
+
+EQUINOX  & Equinox         & Either ``1950.0'' or ``2000.0'', if \verb|<COORD_TYPE>| is of one of
+these. \\ \hline
+
+BMAJ     &                 &\emph{S70}: 0.75, \emph{PM/PH}: 0.24 \\ \hline
+
+BMIN     &                 &\emph{S70}: 0.75, \emph{PM/PH}: 0.24 \\ \hline
+
+BPA      &                 &\emph{S70}: 0., \emph{PM/PH}: 0. \\ \hline
+\end{tabular}
+
+
+
+\subsection{SUBINT keywords}
+
+
+\begin{tabular}%
+{|l|>{\setlength{\rightskip}{0pt plus 2cm}}p{7cm}|>{\setlength{\rightskip}{0pt plus 2cm}}p{5cm}|}\hline
+FITS Keyword & Comment field from FITS header & Value \\ \hline\hline
+
+INT\_TYPE & Time axis (TIME, BINPHSPERI, BINLNGASC, etc)   & ``TIME'' \\\hline
+
+INT\_UNIT & Unit of time axis (SEC, PHS (0-1), DEG)        & ``SEC'' \\ \hline
+
+TSAMP     & [s] Sample interval for SEARCH-mode data       & \verb|<SAMP_INT>| $\times$ 1000. \\ \hline
+
+NBIN      & Nr of bins (1 for SEARCH-mode data)            & 1 \\ \hline
+
+NCH\_FILE & Number of channels/sub-bands in this file      & \verb|<NCHAN>| \\ \hline
+
+NCH\_STRT & Start channel/sub-band number (0 to NCHAN-1)   & 0 \\ \hline
+
+NPOL      & Nr of polarisations in table                   & 1 \\ \hline
+
+NSBLK     & Samples/row (each NPOL*NCH\_FILE, SEARCH mode) & \verb|<SAMP_GRP>| $\times$ \verb|<GRP_BLK>| \\ 
+\hline
+\end{tabular}
+
+\subsection{SUBINT columns}
+
+\begin{tabular}%
+{|l|>{\setlength{\rightskip}{0pt plus 2cm}}p{7cm}|>{\setlength{\rightskip}{0pt plus 2cm}}p{5cm}|}\hline
+Column title & Comment field from FITS header & Value \\ 
+\hline\hline
+
+ISUBINT  & Subint number
+& Incremental counter of the number of rows.\\ \hline
+TSUBINT  & Length of subintegration                         & \verb|<BLK_SEC>| \\ \hline
+
+OFFS\_SUB & Offset from Start of subint centre              &$\frac{1}{2}\times(2\times(\verb|<BLK_CNTR>|-(\verb|blk_initial|))+1)\times \verb|<BLK_SEC>|$ \\ \hline
+
+LST\_SUB  & LST at subint centre                            & \verb|<LST>| \\ \hline
+
+RA\_SUB   & RA (J2000) at subint centre                     & \verb|<RA>| \\ \hline
+
+DEC\_SUB  & [turns] Dec (J2000) at subint centre            & \verb|<DEC>| \\ \hline
+
+GLON\_SUB & [deg] Gal longitude at subint centre            & \verb|<GL>| \\ \hline
+
+GLAT\_SUB & [deg] Gal latitude at subint centre             & \verb|<GB>| \\ \hline
+
+FD\_ANG   & [deg] Feed angle at subint centre               & \verb|<FEED_ANGLE>| \\ \hline
+
+POS\_ANG  & [deg] Position angle of feed at subint centre   & \verb|<PANGLE>| \\ \hline
+
+PAR\_ANG  & [deg] Parallactic angle at subint centre        & $(\verb|<FEED_ANGLE>| + \verb|<PANGLE>|) \bmod 360$ \\ \hline
+
+TEL\_AZ   & [deg] Telescope azimuth at subint centre        & \verb|<TEL_AZ>| \\ \hline
+
+TEL\_ZEN  & [deg] Telescope zenith angle at subint centre   & \verb|<TEL_ZEN>| \\ \hline
+
+DAT\_FREQ & [MHz] Centre frequency for each channel         & $\verb|<FREQ_CHAN1>| + i\times\verb|<CHANBW>|$ \\ \hline
+
+DAT\_WTS  & Weights for each channel                        & 1 $\forall i \in\left[1,\verb|<NCHAN>|\right]$ \\ \hline
+
+DAT\_OFFS & Data offset for each channel                    & 0 $\forall i \in\left[1,\verb|<NCHAN>|\right]$ \\ \hline
+
+DAT\_SCL  & Data scale factor for each channel              & 1 $\forall i \in\left[1,\verb|<NCHAN>|\right]$ \\ \hline
+\end{tabular}
+
Index: /trunk/docs/ProjectBook/conversionSoftware.tex
===================================================================
--- /trunk/docs/ProjectBook/conversionSoftware.tex	(revision 222)
+++ /trunk/docs/ProjectBook/conversionSoftware.tex	(revision 222)
@@ -0,0 +1,653 @@
+\section{Introduction}
+
+This chapter provides details on \pvoconvert, the software used to
+convert the old timer format data to FITS.  The nature of the existing
+data is briefly described, primarily so that the conversion process
+can be understood. The algorithms involved are described, along with
+particular elements of the code that had to be developed. We also
+describe where the code itself resides and how it should be
+implemented.
+
+Note that an earlier version of this chapter was available via the
+subversion repository as \textbf{pvoconvertGuide.pdf}, but the content
+has been slightly updated for this document.
+
+\section{Motivation behind \pvoconvert}
+
+As part of the ATNF Pulsar Data Archive, we would like the data to be
+available in a standard format, and accessible through standard
+Virtual Observatory (VO) techniques. This has necessitated converting
+the data from the compact tape structures they are stored in currently
+to a FITS-based format that provides standard ways of accessing the
+meta-data (\ie the FITS header information), while preserving the
+binary data itself in an efficiently stored manner.
+
+There are three different surveys that we will be dealing with. The
+Parkes Southern Pulsar survey, or the 70-cm survey
+\citep[S70,][]{manchester96} is a survey of the entire southern sky
+made with a single beam at a wavelength of 70~cm. The Parkes
+Multi-beam survey \citep[PM,][]{manchester01} is a more sensitive
+survey, done at 21~cm with the 13-beam \hi multi-beam receiver. This
+survey covered only a portion of the Galactic plane. The final survey
+under consideration is the Parkes High-Latitude survey
+\citep[PH,][]{burgay06}, which used the same multi-beam receiver but
+searched out of the Galactic plane in a relatively narrow band of
+longitude (and with different integration times to the PM survey).
+
+
+\section{Pre-existing data format}
+
+The current formats of the data files for all three surveys are very
+similar. Within each file, the data are stored in blocks, where the
+first 640 bytes consist of header information, detailing positional
+and instrumental information, and the next 48kB is the 1-bit digitised
+data. For the S70 data, there is only one beam, so the data block
+consists of successive samples of the $n$ frequency channels (it is
+possible for there to be two filterbanks, in which case the second set
+of channels follows the first -- all the S70 survey data \emph{should}
+have just one filterbank). There must be a whole number of samples to
+fit in the 48kbytes.
+
+For the PM and PH data, there are 13 beams for each sample, and these
+are stored in successive blocks. This means a given file switches
+continually from beam to beam as you move from block to block (and this
+has implications for the way the FITS file will be written).
+
+A given file can have many blocks in it, and they don't all have to be
+at the same sky position. The way the surveys work is to point at a
+given location for a fixed time and then move to the next position,
+taking data as they go. The data that is taken while the telescope is
+moving is flagged as such.
+
+The header information is crucial in the conversion process. As noted,
+the format of this information is largely the same, with slight
+differences between the surveys. The S70 data\footnote{I have been
+examining the data in the directory
+\texttt{/pulsar/archive00/S70\_TAPES/}} appears to follow the format
+given by this file\footnote{\texttt{%
+/pulsar/psr/cvshome/pulsar/soft\_swin\_old/soft\_swin/search/util/sc\_head.inc}}.
+
+The PM data, however, seems to follow this file\footnote{%
+\texttt{/pulsar/psr/cvshome/pulsar/soft\_atnf/search/sc\_td/sc\_pmhead.inc}},
+which is somewhat newer and has slightly different headers in some
+cases (for instance, where there are comments in the S70 data, there
+is space for attenuator settings).
+
+
+We summarise in Table~\ref{tab-surveys} the details of each
+survey. The last two lines indicate the amount of disk space required
+for all data for one pointing, and for the whole survey. Note that the
+headers are not included here, but the size of the PSRFITS header is
+about 80~kB, so this would add about 3-6~GB to the total Survey size
+for each survey.
+
+\begin{center}
+\begin{table}[h]
+\begin{tabular}{l|lll}
+                        &S70     &PM              &PH\\ \hline
+Telescope               &Parkes  &Parkes          &Parkes\\
+Receiver                &70-cm   &21-cm multibeam &21-cm multibeam\\
+\# Beams/pointing       &1       &13              &13\\
+HPBW [arcmin]           &45      &14.2            &14.2\\
+Frequency [MHz]         &436     &1374            &1374\\
+Bandpass [MHz]          &32      &288             &288\\
+\# Channels             &256     &96              &96\\
+\# Polarisations        &1       &1               &1\\
+Sampling time [$\mu$s]  &300     &250             &125\\
+Digitisation            &1 bit   &1 bit           &1 bit\\
+Time/pointing [sec]     &152     &2100 = 35~min   &265\\
+Total Survey Pointings  &44,299  &2,670           &6,456\\
+Total Survey Beams      &44,299  &34,710          &83,928\\
+Disk Size of 1 file     &15.5~MB &96.1~MB         &24.3~MB\\
+Disk Size of Survey     &692~GB  &3.18~TB         &1.94~TB\\
+\end{tabular}
+\caption{Comparison of the three surveys under consideration.}
+\label{tab-surveys}
+\end{table} 
+\end{center}
+
+\section{Output format}
+
+We convert the data into a FITS format, using an updated version of
+the PSRFITS format \citep{hotan04}. This has a Primary Header Data
+Unit (PHU) that records a lot of the basic metadata for the FITS file:
+information such as time \& date of observation, RA, Dec, observing
+frequency, integration time, instrument setup, and so on. There are
+also a number of binary table extensions that follow the PHU. The only
+two that are used by \pvoconvert are the \history (containing a record
+of the processing of the data) and \subint (containing the actual data)
+tables. 
+
+The survey observations were performed by pointing at a fixed point on
+the sky for a given integration time, then slewing the telescope to
+the next point. The data is continually being taken in this
+process. Each of the existing tape files will have more than one sky
+position in them. To make archive searching simpler, we have stored
+the data such that each sky position is stored in its own FITS
+file. Note that this means each \emph{beam} for multibeam observations
+is given a separate file, and so the multibeam data will need to be
+broken up according to the beam number.
+
+The resultant FITS files will then be unique according to the time
+at which they were observed, and so we use the time and date to form
+the filename, together with the survey type. The format of the
+filenames are:
+\begin{itemize}
+\item S70 data: \texttt{S70\_YYMMDD\_hhmmss.fits}
+\item PM  data: \texttt{PM\_YYMMDD\_hhmmss\_BB.fits}
+\item PH  data: \texttt{PH\_YYMMDD\_hhmmss\_BB.fits}
+\end{itemize}
+where the date of observations was YY/MM/DD (the year is given in
+two-digit format), the UT time was hh:mm:ss, and, for the multibeam
+case, the beam number is BB (from 01 to 13).
+
+The actual data (that is, the 1-bit digitised measurements) will be
+written to the ``data'' field of the \subint binary
+table. Each block (of length 48kbytes) is given a separate entry
+in the table, as this is the smallest chunk of data that we have
+information about (\eg time and position information from the
+header). The dimensions of each entry will be (\# samples per
+block)$\times$(\# channels per sample). Since there is a fixed time
+per pointing for each survey, there will be a fixed number of blocks
+for each pointing position, and hence a fixed number of rows in the
+\subint table. Table~\ref{tab-datasize} summarises the size of the
+table and the dimensions of each data entry (note that there is no
+polarisation information in any of this data):
+
+\begin{table}[h]
+\begin{tabular}{lll}
+Survey  &Number of \subint rows &Dimensions of data table\\ 
+\hline
+S70          &330                            &$1536\times256$\\
+PM           &2051                           &$4096\times96$\\
+PH           &517                            &$4096\times96$\\
+\end{tabular}
+\caption{The size of the \subint data table for each survey.}
+\label{tab-datasize}
+\end{table}
+
+\section{Algorithm}
+
+Here we summarise the \pvoconvert algorithm, looking at what variables
+need to be examined and what functions will need to be called. Some
+classes and functions are referred to -- these are detailed in the
+next section.
+
+\begin{enumerate}
+
+\item Open Survey file. 
+  \begin{itemize}
+  \item Use \texttt{std::ifstream::open()} to open it. 
+  \end{itemize}
+
+\item Determine survey from first few bytes of file. Note that there
+  is no difference between the PM and PH surveys, as far as the file
+  format goes, just a difference in some parameter values.
+  \begin{itemize}
+  \item Use this information to define the Block setup (\eg
+    \texttt{DataBlock block("S70");}).
+  \end{itemize} 
+
+\item Read first block and obtain beam and moving state for that
+  block. 
+  \begin{itemize}
+  \item \texttt{block.readBlock(fin);}
+  \item \texttt{block.telescopeOK();}
+  \item This information will be used to determine future changes in
+  the beam number or the moving state of the telescope.
+  \end{itemize} 
+
+\item\label{step-init} Create a PSRFITS file and initialise based on
+the block information.
+  \begin{itemize}
+  \item Does this with \texttt{PSRFits::initialise(DataBlock \&)}.
+  \item Sets the time, date, beam, initial block and FITS filename. 
+  \item Opens the FITS file, calling the
+    \texttt{PSRFits::fixPSRFITS()} function that corrects any incorrect
+    header keywords.
+  \item Write the PHU of the fits file with
+    \texttt{PSRFits::writePHU(DataBlock \&);} 
+  \item Setup the \subint table with the necessary keywords and
+    DAT\_... arrays.
+  \end{itemize} 
+
+\item Write the current command-line command to the HISTORY table. 
+
+\item\label{step-data} If the file is open, write the block of data to
+the \subint binary table.
+  \begin{itemize}
+  \item Use the function \texttt{PSRFits::writeSubint(DataBlock \&);}
+  \item Obviously the first time round the file will be open, but it
+  may not be on subsequent occasions.
+  \end{itemize} 
+
+\item\label{step-readNew} Read next block header. If we are at the end
+  of the file, go to Step~\#\ref{step-closefile}.
+
+\item If the file is still going (so that the block is valid), check
+  beam information and moving flag.
+  \begin{itemize}
+  \item Read in the block as before.
+  \item Read the current beam and moving flags (with
+    \texttt{block.getKeyword} and \texttt{block.telescopeOK()}) and
+    compare to local versions.
+  \end{itemize} 
+
+\item If the FITS file is deemed to be full, or the beam number has
+  changed, close the file.
+  \begin{itemize}
+  \item See \S\ref{sec-moving} for details on what ``full'' means.
+  \item This is done with \texttt{PSRFits::closeFile()}.
+  \end{itemize}
+
+\item If we were moving, but are now pointing correctly, set up for a
+new file.
+  \begin{itemize}
+  \item This just means setting a flag in the PSRFits class to record
+  the fact that the file is a new one. We do not open a file on disk
+  yet.
+  \end{itemize}
+
+\item If the file is closed, and we are pointing correctly, go to
+  Step~\#\ref{step-init}.
+
+\item If the input file is still open (\ie we have read in another
+  block at Step~\#\ref{step-readNew}), go back to
+  Step~\#\ref{step-data}. If it is not, we are at the end of the
+  file. Go to next step.
+
+\item\label{step-closefile} Close PSRFITS file.
+  \begin{itemize}
+  \item \texttt{PSRFits::closeFile()}.
+  \item Need to close the existing survey file as well:
+    \texttt{fin.close()} 
+  \end{itemize} 
+  
+\end{enumerate}
+
+\section{Implementation}
+
+In this section, we discuss in more detail aspects of the \pvoconvert
+code: how it is implemented and what particular methods were required
+due to the peculiarities of the data.
+
+\subsection{Design of code}
+
+The code is written in C++: this was chosen so that several features
+in particular could be used, namely the classes and namespaces that
+C++ does better than C. The code makes use of the \cfitsio library to
+create and write to FITS files, using the psrheader.fits template
+file\footnote{\texttt{/pulsar/psr/linux/share/psrheader.fits}, pointed
+to by environment variable \texttt{\$PSRFITSDEFN}.} to define the
+structure of the PSRFITS file.
+
+There are three main classes that are used to manipulate the data and
+metadata. The primary one is the \texttt{PVO::FITS::PSRFits} class. This holds
+the information about the PSRFITS file: filenames of new and old
+files, time and date of the start of the data, beam number if needed,
+and a class containing data for the \subint table. This class,
+\texttt{PVO::FITS::Subint} holds all the information needed to populate the
+\subint binary table, both the header and the table cells themselves,
+with the exception of the actual observation data.
+
+Another class, \texttt{PVO::Block::DataBlock} keeps all information
+for a given block (640 byte header + 48kbyte data) in the old
+file. The header is stored as an STL string, while the data is stored
+as bytes in an array of chars. The class also records information
+about the type of survey and the rules for reading the header string
+(which differ for each survey). These rules are stored using the final
+class, \texttt{PVO::Header::SurveySchema}. It records the location and
+length of each header parameter in the existing header blocks, and
+provides functionality to extract a desired keyword (thereby hiding
+the location from the user). It also records certain parameters that
+are not stored in the header block, but are fixed for a given survey
+and are required by the PSRFITS PHU (such as the beam size, the
+instrumental configurations, the antenna locations).
+
+
+\subsection{Opening/reading existing data files}
+
+The different data formats for the different surveys can be
+distinguished by the first few bytes of the file. The S70 data has the
+first four bytes as \texttt{b6 6d 6d db} in hex (note that \texttt{6d}
+is \texttt{``m''} in ASCII., while the multibeam data files commence
+with \texttt{``PMD''} (in ASCII). So it is possible to
+discriminate between the different types upon reading the first few
+bytes of the file.
+
+\pvoconvert then reads the first few bytes, determines the survey
+type, and uses this to set up the \texttt{SurveySchema} class. This
+defines how the tape files' headers will be read and interpreted, to
+ensure the correct metadata is extracted and the correct FITS keywords
+are populated. Summaries of which headers go to which keywords are
+given in Appendix~\ref{app-headers}. The \texttt{SurveySchema} class
+uses \texttt{enum} labels to associate a given header parameter with a
+location in the header string. These labels are listed in
+Appendix~\ref{app-headerFields}, together with the header parameters
+they correspond to for each survey and their location in the 640-byte
+string. 
+
+\subsection{How we know when a FITS file is finished}
+\label{sec-moving}
+
+The S70 survey includes many pointings in a given (existing) data
+file. It has a \move flag in the block headers to tell you
+whether the telescope is pointing (01) or moving (02) (or is not doing
+a GRID pattern -- 00 -- which is the case for the non-survey timing
+observations that are present). 
+
+The S70 data is taken in a such a way that, after 152sec (or 330
+blocks), the move flag is set to 02, to indicate the telescope is
+about to move. However, the subsequent data is still good.
+
+The number of samples should be at least 512K ($=524288=2^{19}$),
+which requires 342 blocks. We therefore keep reading blocks and
+writing to the \subint table until the later of: \move is set
+to 02; and number of samples $>$ 521K.
+
+An important point to note is that the position, as stored in the
+\textsc{RA} and \textsc{DEC} keywords, will change a few blocks before
+the number of samples reaches 512K, so that the last few rows in the
+\subint table will have different positions to the rest.
+
+
+\section{Location of code and usage}
+
+\subsection{Location}
+
+The software is part of the pulsarVO Subversion repository described
+in \S\ref{sec-svn}. The working code, however, has been installed in
+the pulsar filesystem, in the directory \texttt{/pulsar/psr/pvo},
+where a Makefile uses the standard make system to install the
+executables in the directory \texttt{/psr/linux/bin} (in the case of
+installation on a linux machine). The Makefile used in this case is
+\texttt{Makefile.psr} in the trunk/ directory of the repository.
+
+\subsection{How to run \pvoconvert}
+
+The program is run very simply. If you have an existing tape file, \eg
+S31201, then you can convert it by typing
+\begin{quote}
+\texttt{> pvoconvert S31201}
+\end{quote}
+
+More than one file can be done at once, and wildcards can be accepted
+according to the usual shell rules \eg
+\begin{quote}
+\texttt{> pvoconvert S31201 S31204 S3131*}
+\end{quote}
+
+If an output file already exists, the default behaviour is to stop
+rather than write over the file. If you want to overwrite files in
+this situation, use the \texttt{-c} or \texttt{--clobber} option.
+
+If the datafile is from the PH Survey, you need to say so explicitly
+so that \pvoconvert knows to apply the PH settings (as the PH files
+have the same basic structure as the PM ones). This is done by using
+the \texttt{-H} flag:
+\begin{quote}
+\texttt{> pvoconvert -H <file(s)>}\hspace{1cm}\\
+\texttt{> pvoconvert --highlat <file(s)>}
+\end{quote}
+If a list of files is provided, and some are S70 files, they will be
+processed according to the S70 setup. However, you cannot provide a
+mix of PH and PM files, as all will get processed in the same way. 
+
+Other possible flags are \texttt{-h} or \texttt{--help} to provide a
+help message, and \texttt{-v} or \texttt{--verbose} to set verbose
+mode for maximum information for any error or warning messages.
+
+\section{Other PulsarVO programs}
+
+We briefly detail here two utility programs that have been developed
+for use with the newly created FITS files. They are not sufficiently
+complex to warrant their own document.
+
+\subsection{\pvosummary}
+
+This is a utility program to print out key metadata from PSRFITS
+files. The standard functionality of this program is to print out
+basic information about a FITS file: filename, RA, Dec, Beam size,
+Frequency, Date of Observation. It can also produce a csv file that
+lists many more parameters -- the full list, obtainable from
+\texttt{pvosummary -p}, is:
+{\small
+\begin{verbatim}
+Basic parameters written to screen:
+ FILENAME       The FITS file.
+ SRC_NAME       The SRC_NAME FITS keyword.
+ RAJ            Right Ascension, hh:mm:ss.ss
+ DECJ           Declination, dd:mm:ss.sss 
+ BEAM FWHM      The average full-width-half-maximum of the beam
+                 (averaged between BMAJ and BMIN)
+ OBSFREQ        The central observing frequency
+ DATE-OBS       The UT time and date of the observation, in FITS
+                 format YYYY-MM-DDThh:mm:ss.ssss
+
+Additional parameters included only in csv file:
+ File Location  The full path of the FITS file.
+ Header Version The version of the PSRFITS definition used.
+ Survey         Which survey the data comes from:
+                  left blank if not known or not a survey file (e.g. .rf files).
+ Source Name    The SRC_NAME FITS keyword (printed as SRC_NAME to screen).
+ Telescope      Where the observations were made.
+ Data_type      The type of data -- usually the backend instrument used.
+ RAJd           Right Ascension, in decimal degrees.
+ DecJd          Declination, in decimal degrees.
+ GL             Galactic Longitude, in degrees.
+ GB             Galactic Latitude, in degrees.
+ BMAJ           The FWHM of the major axis of the beam.
+ BMIN           The FWHM of the minor axis of the beam.
+ BPA            The position angle of the beam.
+ MJD            The Modified Julian Date of the start of the observation.
+ ChanBW         The channel bandwidth (from the HISTORY table).
+ Nchan          Number of channels (from the HISTORY table).
+ Scan length    The SCANLEN keyword.
+ Tsamp          Time per sample [ms] (from the SUBINT table).
+ NBits          Number of bits per datum (from the SUBINT table).
+\end{verbatim}
+
+\subsection{\pvoconesearch}
+
+
+\section{Detailed guide to algorithms}
+
+
+\subsection{Writing the FITS file}
+
+Here we summarise the main \cfitsio routines that will be used
+to open, create, write, and close the FITS file:
+
+\begin{itemize}
+\item \verb|fits_create_template| -- uses the template FITS definition
+  to create a FITS file with all the correct keywords.
+\item \verb|fits_moveabs_hdu| -- use this to move to the primary HDU.
+\item \verb|fits_movenam_hdu| -- use this to move to particular
+  (named) HDUs in the FITS file \eg SUBINT, HISTORY, ...
+\item \verb|fits_update_key| -- add the value of keywords (the
+  keywords should already be there, but if not they get appended).
+\item \verb|fits_get_num_rows| -- get the number of rows in the binary
+  table.
+\item \verb|fits_insert_rows| -- add a new row to the binary table
+  (used when adding the next block).
+\item \verb|fits_write_tdim| -- write the TDIM\# information for a
+  binary table entry that is a multidimensional array.
+\item \verb|fits_get_colnum| -- get the column number of a named
+  column in a binary table.
+\item \verb|fits_write_col| -- write data to a column of a binary
+  table. May need to do this one row at a time, so want to specify the
+  last row (\ie the highest row number present in the table) as the
+  \texttt{firstrow} argument.
+\item \verb|fits_write_col_bit| -- write 1-bit data to a column of a
+  binary table (see note in next subsection about writing 1-bit data).
+\item \verb|fits_close_file| -- obviously, closes the file once we're
+  done. 
+\end{itemize}
+
+
+\subsection{Writing the data to the FITS file's binary table}
+\label{sec-1bit1st}
+
+When the actual data (as opposed to the header information) gets
+written to the binary table, it needs to be stored as 1-bit data (else
+the storage requirements will blow out), and the datatype given by the
+TFORM keyword needs to 'X'. The writing can be accomplished in a
+couple of ways:
+
+\begin{enumerate}
+\item Use \verb|fits_write_col_bit|, giving an array of characters
+  that are either true (\ie not equal to zero) for a bit value of 1,
+  or false (\ie equal to zero) for a bit value of 0.
+\item Use \verb|fits_write_col|, writing 8 bits at a time, giving an
+  array of 8-bit integers by specifying the TBYTE datatype.
+\end{enumerate}
+
+The latter method might be the best option, as it is much less memory
+intensive. For instance, if one read a character from the existing
+data, that is 1 byte or 8 bits, and so 8 separate measurements. This
+will translate into 8 characters (and hence 8 \emph{bytes}) to be
+passed to \verb|fits_write_col_bit|. It is just a matter of making
+sure there is no loss of information.
+
+
+\section{Details of Implementation of Header analysis}
+
+We list here some important details about how the header information
+will be implemented in the code:
+
+\begin{itemize}
+\item There will be an enum structure that enumerates the keywords
+  given in the first column of the preceeding table. These will be
+  used to refer to the relevant header keyword throughout the code.
+\item There will be arrays of starting position and length of
+  field. These will need to be implemented differently for each
+  survey, due to the different starting positions for some keywords
+  (although most are the same, some that we will need are either in
+  different positions or not present in one or other of the
+  setups). The different implementations can be done through a single
+  function call within a class (with a switch to the necessary setup,
+  depending on the argument of the function).
+\item Some fields include more than one value, and so there will need
+  to be an array recording the dimension of each field (\eg NCHAN,
+  giving the number of channels, is 2$\times$4 characters in size, 
+\item There will be a standard function (templated to cope with int,
+  float and string variables) that extracts the relevant substring and
+  reads the value in that string. It will also need an argument
+  indicating the element required, if the keyword has more than one
+  dimension (this should be an optional parameter). \eg:
+  \begin{verbatim}
+    string utStartTime = readParameter(headerString, UT_STRT, 0);
+    float ra = readParameter(headerString, RA);
+    int bandwidth2 = readParameter(headerString, CHANBW, 1);
+  \end{verbatim}
+\item Enumerated keywords that are not present for a given survey
+  should point to the RESERVE location, and be given a length of
+  0. This provides a good test as to whether something is present
+  (\eg testing to see if the fdcntrl parameter is present, as it will
+  only be in the PM survey data).
+\end{itemize}
+
+The class that we have designed to implement this scheme is as follows:
+{\small
+\begin{verbatim}
+  class SurveySchema
+  {
+  public:
+    SurveySchema(){};
+    SurveySchema(std::string surveyName);
+    virtual ~SurveySchema(){};
+    int getStartPosition(int field){return startPosition[field];};
+    int getFieldLength(int field){return fieldLength[field];};
+    int getFieldDimension(int field){return fieldDimension[field];};
+    template <class T> T readParameter(std::string headerString, int field,
+				       int elementNumber = 0);
+    class xBadSurvey{
+    public:
+      xBadSurvey(std::string s){surveyName=s;};
+      virtual ~xBadSurvey(){};
+      std::string getSurvey(){return surveyName;};
+    private:
+      std::string surveyName;
+    };
+ 
+  private:
+    int startPosition[numKeywords];
+    int fieldLength[numKeywords];
+    int fieldDimension[numKeywords];
+  };
+
+\end{verbatim}
+}
+
+\section{Implementation of existing data file}
+
+The fundamental unit of data from the existing files is going to be
+the \emph{block}. This is the 640-character-long header string, plus
+the 48-kbyte data array. It will have the following elements:
+
+\begin{itemize}
+\item A string indicating which survey type it belongs to
+\item A header string -- the 640-character long string with all the
+  header information in it.
+\item A SurveyHeader object, which has the encoding of the header
+  string recorded, and provides the functionality to extract keywords
+  from the header string.
+\item A data array, stored as characters (?).
+\item A function that acts as a front-end to the readParameter
+  function in the header class above.
+\end{itemize}
+
+\section{Implementation of FITS file access}
+
+The FITS file will be accessed through a special C++ Class that has
+functions that will control the writing of data to the PHU and to the
+SUBINT binary table. These functions will be front-ends to the
+updateKeyword and writeColumnValue functions that access the
+individual keywords and table columns.
+
+\subsection{Positional information}
+
+WARNING! Contrary to first thought, the existing header parameters
+\textsc{ra\_strt} and \textsc{dec\_strt} are not the appropriate ones
+for the \textsc{stt\_crd1,2} FITS keywords. They are the starting
+positions \emph{as far as the file is concerned}, and so are the same
+even when the telescope has moved to a different position. They are
+not the position of the start of the subints for a given sky location! 
+
+\subsection{Storing 1-bit binary data}
+
+As discussed earlier (Section~\ref{sec-1bit1st}), there are a couple of
+ways to write 1-bit data to a binary table using \cfitsio. However, we
+have run up against several problems. 
+
+First, the \texttt{TFORMn} keyword that goes with the data column
+needs to be `X', but the PSRFITS definition file currently has it as
+`I'. This is not a problem -- in fact, one probably does not want the
+general definition file to be 1-bit by default. It can easily be
+changed to `X' by the \verb|fits_update_key| function. 
+
+However, a word of caution. The implicit size of the row needs to be
+preserved, and so since the `I' datatype is 2-bytes, we need to
+replace `I' by `16X' (since there are 16 bits in 2 bytes). This is
+incorporated into a \texttt{fixPSRFITS} function in the PSRFits class.
+
+Next, however, there is a bug in \cfitsio that incorrectly calculates
+the number of bytes for a given number of bits when the `X' datatype
+is being used. This bug is in \texttt{editcol.c} in the \cfitsio
+distribution and is easily fixed:
+\begin{quote}
+delbyte = ((newveclen + 1) / 8) - ((repeat + 1) / 8);
+\end{quote}
+should be replaced by
+\begin{quote}
+delbyte = ((newveclen + 7) / 8) - ((repeat + 7) / 8);
+\end{quote}
+
+Another bug/feature to be wary of: when writing the first block to a
+FITS file, it seems to want to write a second row with nothing in
+it. This doesn't happen for any subsequent rows/blocks, so I'm not
+really sure what is happening. It is easy to delete that extra row on
+the first time round (for the first block, we also need to redefine
+the data cell's dimensions and size, so this can be done in the same
+way). 
+
Index: /trunk/docs/ProjectBook/database.tex
===================================================================
--- /trunk/docs/ProjectBook/database.tex	(revision 222)
+++ /trunk/docs/ProjectBook/database.tex	(revision 222)
@@ -0,0 +1,209 @@
+
+\section{Introduction}
+
+This chapter briefly explains the nature of the database and how the
+data therein is managed. Details on querying the database via the web
+interface are in Chapter~\ref{ch-web}. This holds what is essentially
+the header information for each data file -- the metadata describing
+the observation -- as well as information on the file itself (location
+in the filesystem, and size). This database is where queries will be
+made. It will be periodically updated with information on the data
+files present by a perl script.
+
+\section{Basic Structure of the database}
+
+\subsection{Accessing the database}
+
+The database is a mySQL database called \textbf{psrchive}, residing on
+the machine \texttt{herschel}. To log in to it from \texttt{herschel},
+you can use one of two usernames: \textbf{psrdba} (the admin account,
+with full permissions to edit the psrchive database) and
+\textbf{pulsar} (which only has SELECT permissions and cannot insert
+or delete records).
+
+To access the database (from \texttt{herschel}), do the following
+(note that herein, a line starting with \texttt{>} is in the shell,
+and one starting with \texttt{mysql>} is within the \texttt{mysql}
+program):
+\begin{quote}
+\texttt{> mysql -u psrdba -p}\\
+\texttt{mysql> use psrchive;}\\
+\texttt{mysql> show tables;}
+\end{quote}
+The password for both \texttt{psrdba} and \texttt{pulsar} can be found
+in the \texttt{constants.php} file in the \texttt{htdocs}
+directory\footnote{I won't quote it here as this document may be
+  publicly visible at some point.}.The last command lists the
+available tables. The first two commands can be combined in one by:
+\begin{quote}
+\texttt{> mysql -u psrdba -p -D psrchive}
+\end{quote}
+
+
+
+\section{Table Schema}
+
+\subsection{Current tables}
+
+There are three tables that are used currently to store the
+observational data:
+\begin{entry}
+\item[observations] General pulsar observations, made with the
+  instruments CPSR2, DFB and WBC. These are all pointed observations
+  of known pulsars.
+\item[cals] Calibration observations made with the same instruments
+  during the same observing runs.
+\item[s70] 70cm search and timing data. This table includes all the
+  S70 survey data, as well as timing observations made with the same
+  setup that were converted at the same time.
+\end{entry}
+
+All three tables have been designed to have the same format 
+
+\subsection{Deprecated tables}
+
+The previous versions of ``observations'' and ``cals'', as well as a
+table called ``observations2'' have been kept, but renamed as
+``OLDobservations'', ``OLDcals'' and ``OLDobservations2''. This has
+been done simply to avoid deleting them, but to remove them from any
+query. The data therein is mostly the same as in the current tables,
+but generally incomplete and poorly formatted.
+
+The working versions of ``observations'' and ``cals'', that were
+translated into the newer format, are ``obs'' and ``calib''. These
+tables, along with ``s70'' were used in the testing phase of the web
+archive. With the newest ingest of the data into ``observations'' and
+``cals'', these tables should be deleted.
+
+The only other table present is ``users''. This is a list of users
+that was used for authentication purposes by the testing version of
+the archive. When the OPAL authentication is up and running properly,
+this list could be deleted.
+
+\section{Updating the data}
+
+The data in ``observations'' and ``cals'' are extracted from data
+files on the following disks (using the pulsar environment variables):
+\texttt{\$CP1, \$CP2, \$DFB1, \$DFB2, \$WBC} and \texttt{\$WBC2} using
+the perl script \texttt{find\_archives.pl}. This script performs two
+functions: find new files in the specified directories and save their
+metadata into the database; and delete database entries that no longer
+correspond to disk files. Some details of the script are given here.
+
+\subsection{Structure of perl script}
+
+The script uses the \texttt{Find} function to crawl through the given
+directory structure and locate suitable observation files. Each file
+is checked to see if it is already present in the database. If not, it
+is read using the \textsc{psrchive} command \texttt{vap} to extract
+the necessary metadata parameters. How these are interpreted depends
+on the nature of the data file, which we consider here.
+
+\subsubsection{Reading standard data}
+
+Data from the DFB and WBC are all in PSRFITS format, and so the output
+from \texttt{vap} can be directly used. The query made is 
+\begin{quote}
+\texttt{%
+> vap -n -c "name projid ra dec freq bw length stt\_date stt\_time mjd bmaj bmin bpa dm period nchan npol nbin nsub nbits tsamp nbeam beconfig backend rcvr hdrver telescop asite observer"
+}
+\end{quote}
+which fills many of the columns in the tables. The remaining columns
+can be calculated from the returned parameters: 
+\begin{itemize}
+\item Decimal positions for Right Ascension and Declination are
+  directly extracted from the string positions.
+\item Galactic positions are calculated from the equatorial position
+  (see \S~\ref{sec-galCoord} for details).
+\item The beam information (size and orientation), if not provided by
+  the \texttt{vap} query, are calculated from the observing frequency,
+  assuming a Parkes dish of $D=64$\,m and the classic relation
+  $\theta=1.2\lambda/D$.
+\end{itemize}
+
+The file types and their relationship to the instruments can be
+summarised by the following list:
+\begin{entry}
+\item[a*.rf, a*.cf] Observational and calibration data from DFB1.
+\item[r*.rf, r*.cf] Observational and calibration data from DFB2.
+\item[w*.rf, w*.cf] Observational and calibration data from WBC.
+\end{entry}
+
+\subsubsection{Reading CPSR2 data}
+
+Data from CPSR2 has a peculiar format. Each observation is essentially
+a directory, with a name like \texttt{2004-07-23-07:17:09}. Within
+this directory are a series of files, which are sets of coherently
+de-dispersed folded profiles. There are typically two sets of files in
+the directory, with prefixes ``m'' and ``n'' -- these correspond to
+the two different frequency bands. We want to treat each of these sets
+as a separate observation. Thus each directory will appear in the
+database twice, once for each frequency band contained in it (note
+that not all of these directories have two different frequency sets in
+them). 
+
+For each frequency band, we run \texttt{vap} on each \texttt{m*.fb} or
+\texttt{m*.cfb} file with the same parameters as above. Results from
+the first file examined are used to define most of the parameters,
+with the exception of integration time (\texttt{scan\_len}). This
+needs to be summed over all the files, and the sum used as the
+observation's integration time. Once all files have been examined, the
+additional parameters discussed above are calculated, and the full
+parameter set is then written to the database.
+
+Note that there is a third prefix -- ``o'' -- that is also
+considered. This was used in the early days of CPSR2, and will not
+constitute many files, but is included for the sake of completeness.
+
+\subsubsection{Writing to the database}
+
+Once all parameters have been determined. they are written to the
+mySQL database. To do this, we use the SQL Abstract package, which
+provides an easy method of writing an array of values to a
+database. The following code shows the syntax (not all parameters are
+shown):
+\begin{quote}
+\begin{verbatim}
+    my %data = ( filename => $filename,
+                 src_name => $results[$params_NAME],
+                 project_id => $results[$params_PROJID],
+                 raj => $results[$params_RAJ],
+                 ... );
+
+    my $sql = SQL::Abstract->new;
+    my $tableName;
+    if ($path =~ /\_R/ ) {
+        $tableName = 'cals';
+    }
+    else {
+        $tableName = 'observations';
+    }    
+    my($stmt, @bind) = $sql->insert($tableName, \%data);
+
+    my $sth = $db_handle->prepare($stmt);
+    $sth->execute(@bind);
+
+\end{verbatim}
+\end{quote}
+The \texttt{\$results} array shown above holds all the parameters
+extracted from the \texttt{vap} call. Other calculated parameters, as
+well as filename, location and file size are stored separately as
+individual parameters.
+
+\subsubsection{Deleting old data}
+
+\texttt{find\_archives.pl} also checks that all data in the archive is
+still valid. It does this by extracting all \texttt{data\_loc} \&
+\texttt{filename} combinations from the database, and performing a
+simple existence check on the full filename (using the perl
+\texttt{-e} operator). Those that do not exist are deleted from the
+database. In this way, the database matches the filesystem after each
+run of \texttt{find\_archives.pl}.
+
+When running \texttt{find\_archives.pl}, there are two command-line options
+that can be given:
+\begin{entry}
+\item[\texttt{-d}] Just delete any stale records.
+\item[\texttt{-p}] Just populate the database with any new records.
+\end{entry}
+If no options are given, both are done.
Index: /trunk/docs/ProjectBook/formulae.tex
===================================================================
--- /trunk/docs/ProjectBook/formulae.tex	(revision 222)
+++ /trunk/docs/ProjectBook/formulae.tex	(revision 222)
@@ -0,0 +1,39 @@
+
+\section{Galactic coordinates}
+\label{sec-galCoord}
+
+For the data imported into the database, we convert the equatorial
+position to Galactic position, as this is often not included in the
+pulsar data header, but would be useful to have recorded.
+
+Conversion from equatorial (we assume J2000.0 for all equatorial
+positions) is relatively straightforward. It just requires the
+position of the North Galactic Pole in J2000.0 equatorial positions --
+$\alpha_\text{NGP} = 192\fdg859508$ and $\delta_\text{NGP} =
+27\fdg128336$ -- as well as the location of the ascending node,
+$\theta=32\fdg932$. 
+
+The Galactic latitude and longitude $b,l$ are defined as follows
+(assuming the right ascension is $\alpha$ and declination is
+$\delta$): 
+\begin{eqnarray*}
+  \sin b &= &\cos(\delta) \cos(\delta_\text{NGP})
+  \cos(\alpha-\alpha_\text{NGP}) + \sin(\delta)
+  \sin(\delta_\text{NGP})\\
+  b &= &\arcsin(\sin b)\\
+  \cos b \sin l &= &\sin(\delta) \cos(\delta_\text{NGP}) -
+  \cos(\delta) \cos(\alpha-\alpha_\text{NGP})
+  \sin(\delta_\text{NGP})\\
+  \cos b \cos l &= &\cos(\delta) \sin(\alpha - \alpha_\text{NGP})\\ 
+  l &= &\arctan(\sin l / \cos l) 
+\end{eqnarray*}
+Note that, for calculating $l$, you need to make sure that you get the
+correct quadrant. This means you add, to the value of $l$ above, the
+factor from the following table, depending on the values of $\sin l$
+and $\cos l$.
+
+\begin{tabular}{l|ll}
+              & $\cos l < 0$ & $\cos l > 0$\\ \hline
+$\sin l < 0$  & $\pi$        & $2\pi$      \\
+$\sin l > 0$  & $\pi$        & 0            
+\end{tabular}
Index: /trunk/docs/ProjectBook/glossary.tex
===================================================================
--- /trunk/docs/ProjectBook/glossary.tex	(revision 222)
+++ /trunk/docs/ProjectBook/glossary.tex	(revision 222)
@@ -0,0 +1,10 @@
+
+\begin{entry}
+\item[{FITS}] The Flexible Image Transport System, a format for storing
+  astronomical data.
+\item[{PH}] The Parkes High-Latitude Survey \citep{burgay06}.
+\item[{PM}] The Parkes Multibeam Survey \citep{manchester01}.
+\item[{PSRFITS}] A type of FITS format adapted for use with pulsar
+  observational data.
+\item[{S70}] The Parkes Southern Pulsar Survey, done at 70cm \citep{manchester96}.
+\end{entry}
Index: /trunk/docs/ProjectBook/introduction.tex
===================================================================
--- /trunk/docs/ProjectBook/introduction.tex	(revision 222)
+++ /trunk/docs/ProjectBook/introduction.tex	(revision 222)
@@ -0,0 +1,53 @@
+\section{Summary of project}
+
+This Project Book provides a summary of the work undertaken for the
+Pulsar VO project\footnote{ATNF Project number 096}. The project
+encompassed the following areas of work:
+\begin{itemize}
+\item Conversion of old timing data from timer format to PSRFits. This
+  data is specifically the 70cm observations from the Parkes Southern
+  Pulsar Survey, but also data from the Parkes Multibeam and
+  High-Latitude surveys.
+\item Storage of header information from these and all other pulsar
+  data stored at ATNF in a database for ease-of-access.
+\item Development of a web-based interface to allow queries on this
+  archive, and allow downloads of the data.
+\item Development of a Virtual Observatory Simple Cone Search tool
+  that allows VO-style queries of the database.
+\end{itemize}
+
+This Project Book aims to detail the work done in all these areas, to
+allow future developer to build on this work in a consistent
+manner. It will explain the methods used in the various algorithms,
+details how the web archive works, and 
+
+
+\section{Version control and project tracking}
+\label{sec-svn}
+
+The Pulsar VO project has its own subversion repository as part of the
+ATNF subversion system. The full repository can be checked out from
+the secure url
+\texttt{https://svn.atnf.csiro.au/pulsarvo/trunk}. There are a number
+of subdirectories containing files relevant for different elements of
+the project:
+\begin{entry}
+\item[src/] C++ source code for the conversion process, as well as
+  other related functions.
+\item[htdocs/] The web-page source code (php and html), as well as the
+  perl script for ingesting data into the database.
+\item[sql/] SQL functions that create tables in the database, and that
+  were used to test the cone-searching routines.
+\item[docs/] Documentation I developed during the course of the
+  project. Most of this is essentially deprecated by this document.
+\end{entry}
+There are also a range of files in the top trunk directory that were
+kept as reference of used as scripts to make the conversion process
+easier. 
+
+In conjunction with the subversion repository, there is a Trac website
+at \href{https://svn.atnf.csiro.au/trac/pulsarvo}%
+{https://svn.atnf.csiro.au/trac/pulsarvo}. This allows tracking
+changes made to the repository, recording tickets and the work done on
+them, and access to the repository tree. It also provides a wiki for
+collaborative reporting.
Index: /trunk/docs/ProjectBook/pulsars.bib
===================================================================
--- /trunk/docs/ProjectBook/pulsars.bib	(revision 222)
+++ /trunk/docs/ProjectBook/pulsars.bib	(revision 222)
@@ -0,0 +1,66 @@
+
+%% Created for Matthew Whiting at 2008-02-18 12:03:35 +1100 
+
+
+%% Saved with string encoding Western (ASCII) 
+
+
+
+@article{manchester96,
+	Adsnote = {Provided by the Smithsonian/NASA Astrophysics Data System},
+	Author = {{Manchester}, R.N. and {Lyne}, A.G. and {D'Amico}, N. and {Bailes}, M. and {Johnston}, S. and {Lorimer}, D.R. and {Harrison}, P.A. and {Nicastro}, L. and {Bell}, J.F.},
+	Date-Modified = {2008-02-18 12:03:29 +1100},
+	Journal = {MNRAS},
+	Month = apr,
+	Pages = {1235-1250},
+	Title = {{``The Parkes southern pulsar survey - \textsc{i}. Observing and data analysis systems and initial results.''}},
+	Url = {http://adsabs.harvard.edu/abs/1996MNRAS.279.1235M},
+	Volume = 279,
+	Year = 1996,
+	Bdsk-Url-1 = {http://adsabs.harvard.edu/abs/1996MNRAS.279.1235M}}
+
+@article{manchester01,
+	Adsnote = {Provided by the Smithsonian/NASA Astrophysics Data System},
+	Author = {{Manchester}, R.N. and {Lyne}, A.G. and {Camilo}, F. and {Bell}, J.F. and {Kaspi}, V.M. and {D'Amico}, N. and {McKay}, N.P.F. and {Crawford}, F. and {Stairs}, I.H. and {Possenti}, A. and {Kramer}, M. and {Sheppard}, D.C.},
+	Date-Modified = {2008-02-18 12:03:20 +1100},
+	Doi = {10.1046/j.1365-8711.2001.04751.x},
+	Eprint = {arXiv:astro-ph/0106522},
+	Journal = {MNRAS},
+	Month = nov,
+	Pages = {17-35},
+	Title = {{``The Parkes multi-beam pulsar survey - \textsc{i}. Observing and data analysis systems, discovery and timing of 100 pulsars''}},
+	Url = {http://adsabs.harvard.edu/abs/2001MNRAS.328...17M},
+	Volume = 328,
+	Year = 2001,
+	Bdsk-Url-1 = {http://adsabs.harvard.edu/abs/2001MNRAS.328...17M},
+	Bdsk-Url-2 = {http://dx.doi.org/10.1046/j.1365-8711.2001.04751.x}}
+
+@article{burgay06,
+	Adsnote = {Provided by the Smithsonian/NASA Astrophysics Data System},
+	Author = {{Burgay}, M. and {Joshi}, B.C. and {D'Amico}, N. and {Possenti}, A. and {Lyne}, A.G. and {Manchester}, R.N. and {McLaughlin}, M.A. and {Kramer}, M. and {Camilo}, F. and {Freire}, P.C.C.},
+	Date-Modified = {2008-02-18 11:50:43 +1100},
+	Doi = {10.1111/j.1365-2966.2006.10100.x},
+	Journal = {MNRAS},
+	Month = may,
+	Pages = {283-292},
+	Title = {{``The Parkes High-Latitude pulsar survey''}},
+	Url = {http://adsabs.harvard.edu/abs/2006MNRAS.368..283B},
+	Volume = 368,
+	Year = 2006,
+	Bdsk-Url-1 = {http://adsabs.harvard.edu/abs/2006MNRAS.368..283B},
+	Bdsk-Url-2 = {http://dx.doi.org/10.1111/j.1365-2966.2006.10100.x}}
+
+@article{hotan04,
+	Adsnote = {Provided by the Smithsonian/NASA Astrophysics Data System},
+	Author = {{Hotan}, A.W. and {van Straten}, W. and {Manchester}, R.N.},
+	Date-Modified = {2008-02-18 11:50:52 +1100},
+	Doi = {10.1071/AS04022},
+	Eprint = {arXiv:astro-ph/0404549},
+	Journal = {PASA},
+	Pages = {302-309},
+	Title = {{``PSRCHIVE and PSRFITS: An Open Approach to Radio Pulsar Data Storage and Analysis''}},
+	Url = {http://adsabs.harvard.edu/abs/2004PASA...21..302H},
+	Volume = 21,
+	Year = 2004,
+	Bdsk-Url-1 = {http://adsabs.harvard.edu/abs/2004PASA...21..302H},
+	Bdsk-Url-2 = {http://dx.doi.org/10.1071/AS04022}}
Index: /trunk/docs/ProjectBook/vo.tex
===================================================================
--- /trunk/docs/ProjectBook/vo.tex	(revision 222)
+++ /trunk/docs/ProjectBook/vo.tex	(revision 222)
@@ -0,0 +1,10 @@
+
+\section{Background to the Virtual Observatory}
+
+
+\section{The Virtual Observatory Simple Cone Search}
+
+
+\section{Registering the Cone Search}
+
+
Index: /trunk/docs/ProjectBook/web.tex
===================================================================
--- /trunk/docs/ProjectBook/web.tex	(revision 222)
+++ /trunk/docs/ProjectBook/web.tex	(revision 222)
@@ -0,0 +1,70 @@
+
+\section{About the web archive}
+
+\subsection{Aims}
+
+The aim of the ATNF Pulsar Data Archive is to provide public access to
+all pulsar observations made with the Parkes telescope. Users are able
+to query the database to see what observations have been made
+satisfying some criteria (position, time, observing mode, ...), and
+can download data from the results of their query.
+
+There is also a Virtual Observatory ConeSearch tool -- a PHP page that
+returns a VOTable XML file of query results. This is discussed in
+Chapter~\ref{ch-vo}. 
+
+\subsection{Data restrictions}
+
+ATNF pulsar data has a 2 year proprietary period, meaning that for 2
+years after the data is taken, it can only be accessed by those
+involved in the project. After 2 years have passed, the data becomes
+publicly available and anyone can access it. The archive addresses
+this issue by having two alternatives on the login page: an anonymous
+access (where the user enters their email only -- similar to anonymous
+FTP), where only publicly available data is accessible; and
+authenticated access, using the OPAL\footnote{The ATNF Online Proposal
+  Applications \& Links system, \href{http://opal.atnf.csiro.au/}%
+{http://opal.atnf.csiro.au/}} system, where the user can access
+publicly available data plus any proprietary data from projects the
+user has been involved in. 
+
+\subsection{Structure of the archive}
+
+This section summarises the main files that are present in the
+archive, and what their purpose is:
+
+\begin{entry}
+\item[index.php] The main page of the archive, that provides the login
+  page and the page where queries are entered.
+\item[query.php] The page that displays the query results. This does
+  the work of sending the SQL queries and displaying the table of
+  results.
+\item[constants.php] A list of constants defined once, so that they
+  can be easily and uniformly changed.
+\item[logger.php] Functions governing the logging of user interactions
+  with the archive.
+\item[utils.php] Assorted utility PHP functions used by other files.
+\item[printTables.php] Controls printing of the tables of results.
+\item[view\_profiles.php] Presents plotted profiles of selected
+  observations. 
+\item[conesearch.php] The VO Conesearch web service. See
+  Chapter~\ref{ch-vo}. 
+\item[xmlFunctions.php] Functions for use in constructing a
+  VOTable. See Chapter~\ref{ch-vo}.
+\item[pulsar\_archive\_guide.html] A Users' Guide on how the archive works.
+\item[header.html] The top-of-page matter for the web pages.
+\item[footer.html] The bottom-of-page matter for the web pages.
+
+\end{entry}
+
+
+\section{Possible queries}
+
+
+\section{How the queries are done}
+
+
+\section{Presenting the results}
+
+
+\section{Obtaining data}
Index: /trunk/docs/conversionCodeDetails.tex
===================================================================
--- /trunk/docs/conversionCodeDetails.tex	(revision 221)
+++ /trunk/docs/conversionCodeDetails.tex	(revision 222)
@@ -1,5 +1,6 @@
 \documentclass{article}
 \usepackage{natbib}
-\usepackage{fancyheadings}
+%\usepackage{fancyheadings}
+\usepackage{fancyhdr}
 \usepackage{array}
 \usepackage{xspace}
@@ -17,5 +18,6 @@
 \cfoot{}
 \rfoot{\thepage}
-\setlength{\headrulewidth}{0in}
+\renewcommand{\headrulewidth}{0cm}
+%\setlength{\headrulewidth}{0in}
 
 \newcommand{\eg}{e.g.\xspace}
Index: /trunk/docs/pvoconvertGuide.tex
===================================================================
--- /trunk/docs/pvoconvertGuide.tex	(revision 221)
+++ /trunk/docs/pvoconvertGuide.tex	(revision 222)
@@ -1,5 +1,6 @@
 \documentclass[10pt,a4paper]{article}
 \usepackage{natbib}
-\usepackage{fancyheadings}
+%\usepackage{fancyheadings}
+\usepackage{fancyhdr}
 \usepackage{array}
 \usepackage{xspace}
@@ -17,5 +18,6 @@
 \cfoot{}
 \rfoot{\thepage}
-\setlength{\headrulewidth}{0in}
+\renewcommand{\headrulewidth}{0cm}
+%\setlength{\headrulewidth}{0in}
 
 %Define a test for doing PDF format -- use different code below
