#!/bin/tcsh -f
#(ie run the tshell on this but don't read the .cshrc or .tcshrc)

echo version = 1.02 of setxdvi 2006 Dec 11
# 2006 Dec 11, 1.02: rename kickxdvi to setxdvi
# 2006 Nov 23, 1.01: allow 0 for line number 
# 2006 Nov 23, 1.00: origin (functional)

if ($#argv == 0) then
   echo 'usage: setxdvi [paper.dvi] [line number]'
   echo 'Set the dvi file to the line given.'

   echo
   echo 'Documentation'
   echo 'The information about how to control xdvi is given in the'
   echo 'manual page for xdvi under the flag -sourceposition.'
   echo 'One needs to set up the LaTeX file using:'
   echo '  % provide hooks for controlling xdvi's reading the dvi
   echo '  \usepackage{srcltx}'
   echo 'srcltx.sty can be found at ctan:'
   echo 'http://www.ctan.org/tex-archive/help/Catalogue/entries/srcltx.html'

   echo
   if (-f paper.dvi) then
      echo 'Since there is a paper.dvi file in this directory'
      echo 'it will be brought to a line determined by'
      echo 'ten times the number of seconds on the clock\!'
   else
      echo 'If there were a paper.dvi file in this directory'
      echo 'setxdvi would demonstrate how it works by'
      echo 'bringing the display to a line determined by'
      echo 'ten times the number of seconds on the clock\!'
      exit
   endif
   echo
   set target = paper
   set seconds = `date '+%S'`
   @ location = 10 * $seconds
else
   set target   = `echo $1 | sed "s/\.dvi//" `
   if ($#argv == 1) then
      set location = 1
   else
      set location = $2
   endif
endif

if ($location == '0') then
  # Can't just set it to 0
  set location = '1'
endif

if !(-f $target.dvi) then
   echo "$target.dvi is not found.  It is needed."
endif

# if !(-f $target.tex) then
#   echo "$target.tex is not found.  It is needed."
# apparently not!!!!
# endif

echo Kicking the dvi file $target.dvi to line $location

xdvi -hl red -sourceposition "$location $target.tex" $target.dvi

exit
*****************************************************************

# THIS WORKS:
# xdvi -sourceposition 2:paper.tex paper.dvi

# THIS WORKED: #####################################
# xdvi -sourceposition "200 paper.tex" paper.dvi
# The quote marks are important!
# ##################################################

SOURCE SPECIALS
       Some  TeX implementations or macro packages provide the facility to au-
       tomatically include so-called  `source  specials'  into  a  .dvi  file.
       These  contain  the  line  number,  eventually a column number, and the
       filename of the .tex source. This makes it possible to jump from a .dvi
       file  to  the  corresponding  place  in  the .tex source and back (also
       called `reverse search' and `forward search').

       To be usable with xdvi, source specials in the dvi file must  have  one
       of the following formats:

                src:line[ ]filename
                src:line:col[ ]filename
                src:line
                src:line:col
                src::col

       If  filename or line are omitted, the most recent values are used.  The
       first source special on each page must be  in  one  of  the  first  two
       forms, since defaults are not inherited across pages.

       You  will  need  a  TeX  implementation or a macro package (such as sr-
       cltx.sty or srctex.sty , available from CTAN)  to  insert  such  source
       specials into the dvi file.

       For  reverse  search,  you can use the combination CTRL-Mouse 1 to make
       xdvi open an editor (the value of the -editor command line option) with
       the  file  and the line number of the .tex source. (See the description
       of the -editor option for more information and examples.)


       -sourceposition line[:col][ ]filename
              This option makes xdvi start in `client mode' to perform a `for-
              ward search'. The main dvi file dvi_file  is  specified  on  the
              command line as usual. `Forward search' means that xdvi will try
              to open the page in dvi_file corresponding to the line  (option-
              ally also the column) and filename of the .tex source, and high-
              light the place found by drawing a rectangle in highlight colour
              (see  the -hl option) around the corresponding text.  (This only
              works when the dvi_file has been prepared  with  source  special
              information;  see  the section SOURCE SPECIALS for more informa-
              tion on this.)

              `Client mode' means that if there is already another instance of
              xdvi running on this X display and displaying the same dvi_file,
              a new instance started with the -sourceposition option will only
              notify  that running instance to perform the forward search, and
              exit after that. This way, other programs such such as text edi-
              tors  may  invoke  xdvi  in  `client mode' to jump to a specific
              place in the .dvi file corresponding to the current mouse cursor
              position in the .tex file.

              The  argument  for filename should be a string with the same ex-
              tension as the file name used for the source specials in the dvi
              file.  The  space before filename is only needed if the filename
              starts with a digit.  When the space is used, the argument needs
              to  be encosed in quotes to prevent the shell from misinterpret-
              ing the space as argument separator.

From srcltx.pdf

2 Usage
To use the package with LATEX, put the line
\usepackage{srcltx}
into the preamble of your document.

This will insert source specials at every start of a paragraph of your
document and at every math environment
...
The specials inserted by this package have the following format, which
should be compatible with all DVI viewers:
\special{src:line-number filename}



*****************************************************************

historic junk:

# xdvi -sourceposition 2::paper.tex paper.dvi

# this made a new one but failed ?? to kick old one:
# xdvi -sourceposition 2:paper.tex paper.dvi