# source specials

dviout interprets source specials supported by MikTeX and yap or pTeX (recent version). Using the specials, dviout calls an editor to edit the part pointed by the mouse coursor and conversely dviout can display the part whose source file and the line number are indicated.
source special is embedded in a DVI file as follows:
\special{src:line_number source_file_name}
1. dviout calls an editor to edit the source file
The way to call an editor is given by -src: which is indicated in Setup Parameters->[Common]. For example
c:\usr\local\bin\mule.exe^s+%d %s
is the content of -src:. Here %s represents the file name of the TeX file (full path) and %d represents the line number. %s may be replaced by %n which represents the path name without its extension.
^s is the separator between the program to be executed and its parameters.
If the chracter < is put at the top, then dviout is minimized after calling an editor:
<c:\usr\local\bin\mule.exe^s+%d %s
If emacs/mule/meadow is used under gnuserv package, one can indicate as
gnuclientw^s +%d %s
To use the package put the contained executable files in a directory in PATH and gnuserv.el in a lisp directory, byte-compile it by the command M-x byte-compile-file and add the two lines
(require 'gnuserv)
(gnuserv-start)
in $HOME/.emacs.
To execute DDE command, the string combined with the service name, the topic name and the string to export by XTYP_EXECUTE transaction separated by a space in this order shoud be indicated by following the top character `.
It is terminated by another ` and the command to be executed when the DDE server is not registered in DDEML is given after that. For example,
`myedit myedit [dviout(+%d %s)]`c:\Program Files\myedit.exe^s+%d %s
If the second ` is replaced by ``, the first DDE command is executed after the execution of the second command if the DDE server is not registered in DDEML. In this case, the second command registers the DDE server in DDEML.
More than one XTYP_EXECUTE transactions may be indicated with the separator | as follows
`myedit myedit Open(%s)|Line(%d)``myedit
If no DDE command is indicated, dviout inserts
`srctex srctex %s: %d
at the top of -src: when dviout interprets -src:
If -src: is void and the environment variable TEXEDIT is set, the environment variable is used for -src:
1.1. The double click of the left button on the mouse results the jump to the source file according to -src: (it may fail if the shape of the mouse corsor is not an arrow).
Moreover String Copy is done by clicking the left button of the mouse under pressing SHIFT key.
In this case, if source specials are set, [Execute] button is changed into [->Src] button and pressing the button results the jump to the source file according to -src:. This step is omitted if Jump->DireCt Jump to Editor is checked.
If -src: is not void and %d or %s do not exist in -src:, a text in a tag jump format is displayed.
This function is killed by Option->source specials
1.2. Clicking the right button of the mouse under pressing both the CTRL key and the left button of the mouse results the similar jump to the source file as above.
In this case, only the vertical position (or horizontal position in vertical mode) is considered, jumped position may not be accurate in case of a multi-column page etc.
2. Jump in dviout using source specials
As the jump by HyperTeX, dviout can display a page by indicating #line_number tex_file_name or #line_number/string tex_file_name. In the command line, one can input, for example,
dviout -1 foo.dvi "# 235 foo.tex"
Here -1 means the first dviout (cf. Start and Exit and no more dviout). Here the extension .dvi cannot be omitted. Moreover
dviout -1 foo.dvi "# 235/This foo.tex"
says that dviout should indicate the word "This" in 235-th line in foo.tex (The last search of dviout determine that this search of
"This" is done as a word or not). If one wants to search the block "This book", then one inputs
dviout -1 foo.dvi "# 235/This book foo.tex"
(The last part in "# ... " is the filename of the source text).
In case of DDE(Link to Other Program), one can set
[PageOpen(# 235 foo.tex)]
If the file name is *, the check of the file name is skipped. If the file name contains a space then it should be braced by ' such as 'My Docments\foo.tex'
One can jump from an editor editing the source file to the preview window of dviout to show the corresponding lines indicated in the source text. For example, the macro to do this jump from Hidemaru to dviout is as follows:
ddeinitiate "dviout", "dviout";
ddeexecute "[PageOpen(# "+str(lineno)+" *)]";
ddeexecute "[FileOpen("+leftstr(filename,strlen(filename)-3)+"dvi)]";
Here we suppose the full path name of the corresponding DVI file is only different in the extension from that of the TeX source file. Note that the spaces in the above strings "[PageOpen(# " and " *)]" (cf. Example Using DDE).
It is also possible to indicate it directly by String Search such as _235_foo.tex or _235_*. Here _ represents a space.
3. Make a DVI file with source specials
If the TeX compiler support source specials, a DVI file with source specials is made by the -src option:
latex --src foo
By the attached srctex one can make a DVI file with source specials by a TeX compiler which doesn't support them. It can be done, for example, by
srctex latex foo
or
srctex -a latex foo
in place of
latex foo
In this case, srctex transforms foo.tex into foo.tmp and calls latex to make foo.dvi. The -a option generates more precise information but there increses the possibility to fail in generating a DVI file and the size of the DVI file becomes bigger.
To edit foo.tex in case of the error in making foo.dvi, an attached utility convedit can be used. If
TEXEDIT=convedit emacs +%d "%s"
is set in the TeX environment, the command
convedit emacs +123 foo.tmp
is interpreted as
emacs +123 foo.tex.
To transform foo.tex into a TeX file fo1.tex containing source specials, execute
srctex -ofo1.tex foo
The following is a command to make a DVI file by latex fo2 after this transformation
srctex -ifoo.tex -ofo1.tex latex fo2
For more information on srctex, please refere to the message displayed by executing srctex and the attached configulation file srctex.cfg.