main.tex

\documentclass[fontset=fandol]{ctexrep}
\usepackage{accsupp}
\usepackage{geometry}
\usepackage{listings}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage[os=win,hyperrefcolorlinks]{menukeys}

\geometry{a4paper,hmargin=1.25in,vmargin=1in}

\ctexset{
  chapter ={
    format = \huge\bfseries\raggedright,
    number = \arabic{chapter},
    name   = {},
  },
  section/format = \Large\bfseries\raggedright
}

\lstset{
  backgroundcolor = \color{lightgray!30},
  keywordstyle    = \color{blue},
  stringstyle     = \color{brown},
  basicstyle      = {\small\ttfamily},
  breaklines      = true,
  tabsize         = 4,
  gobble          = 2,
  numbers         = left,
  numberstyle     = \tiny\emptyaccsupp,
  frame           = single,
  xleftmargin     = \ccwd,
  numbersep       = \ccwd,
  columns         = fullflexible,
}

\newcommand\emptyaccsupp[1]{%
  \BeginAccSupp{ActualText={}}#1\EndAccSupp{}%
}

\hypersetup{pdfpagelayout=SinglePage}

\renewmenumacro{\menu}[>]{angularmenus}
\renewmenumacro{\keys}[+]{shadowedroundedkeys}

\title{\bfseries SumatraPDF 阅读器的配置方法\thanks{\url{https://github.com/OsbertWang/latex-editor-sumatrapdf}}}
\author{啸行\thanks{\url{ranwang.osbert@outlook.com}}}
\date{\today}

\begin{document}
\maketitle

\begin{abstract}
  SumatraPDF 是一款常见的、功能比较丰富的、适合浏览 \LaTeX{} 编译结果的轻量级 PDF 阅读器.
  以前 C\TeX{} 套装将它集成以配合 WinEdt 使用,
  现如今依然有很多 WinEdt 用户青睐于这样的搭配,
  \href{https://www.sumatrapdfreader.org/free-pdf-reader.html}{SumatraPDF 官网}%
  也给出了 \href{https://www.sumatrapdfreader.org/docs/Use-Sumatra-as-a-pre-viewer-for-LaTeX-editors.html}{Use Sumatra as a pre-viewer for LaTeX editors}
  的手册,
  其中就包含了
  \href{https://notepad-plus-plus.org/}{Notepad++}、
  \href{https://www.texstudio.org/}{\TeX Studio}、
  \href{http://www.texniccenter.org/}{TeXnicCenter}、
  \href{http://www.winedt.com/}{WinEdt}、
  \href{https://www.gnu.org/software/emacs/}{Emacs}
  和
  \href{https://www.vim.org/}{Vim}.
  本文将整合
  \href{http://ask.latexstudio.net/ask/article/81.html}{SumatraPDF 阅读器该怎么设置——以 TeXStudio 和 VS Code 为例}%
  和%
  \href{http://ask.latexstudio.net/ask/article/83.html}{以 Notepad++ 为 LaTeX 编辑器及以 SumatraPDF 进行正反向搜索的配置方法}%
  两篇文章.

  全文假设 \texttt{main.tex} 已经被编译为 \texttt{main.pdf},
  其中 \texttt{main.tex} 内容如下:
  \begin{lstlisting}[gobble=4,language={[LaTeX]TeX}]
    \documentclass{article}
    \usepackage{lipsum}
    \begin{document}
    \section{main file}
    \lipsum[1]
    \input{subfile.tex}
    \end{document}
  \end{lstlisting}
  而 \texttt{subfile.tex} 内容如下:
  \begin{lstlisting}[gobble=4,language={[LaTeX]TeX}]
    \section{subfile}
    \lipsum[2]
    \[ a = b \]
  \end{lstlisting}
\end{abstract}

\chapter{\TeX Studio}
假设 \texttt{<SumatraPDFROOT>} 是 SumatraPDF 的安装路径.
在配置之前,
我首先简要介绍下使用命令行的方法.

事实上,
SumatraPDF 允许通过添加命令行参数来形成不同的阅读效果.
对 \LaTeX{} 用户而言,
最重要的效果就是正反向搜索.
在这里给出我所使用的命令行代码.
\begin{lstlisting}
  <SumatraPDFROOT>\SumatraPDF.exe -reuse-instance -forward-search subfile.tex 2 -inverse-search "\"<TeXStudioROOT>\texstudio.exe\" \"%f\" -line %l" main.pdf
\end{lstlisting}
其中,
\begin{lstlisting}
  -reuse-instance
\end{lstlisting}
表示只打开一个 SumatraPDF 窗口;
\begin{lstlisting}
  -forward-search subfile.tex 2
\end{lstlisting}
表示对 \texttt{subfile.tex} 的第 2 行进行正向搜索
(在 SumatraPDF 中表现为 \texttt{main.pdf} 对应位置变蓝);
\begin{lstlisting}
  -inverse-search "\"<TeXStudioROOT>\texstudio.exe\" \"%f\" -line %l" main.pdf
\end{lstlisting}
表示使用 \TeX Studio 对 \texttt{main.pdf} 进行反向搜索
(表现为双击 \texttt{main.pdf} 的某部分会在 \TeX Studio 中返回对应的 \texttt{tex} 文件的某行).

明白了命令行的原理就很容易在软件中进行设置了.
首先在 \menu{Options > Configure TeXstudio} 中选择 \menu{Show Advanced Options},
而后在 \menu{Build > User commands} 中添加
\begin{lstlisting}
  "<SumatraPDFDIR>\SumatraPDF.exe" -reuse-instance -forward-search ?c:rme" @ -inverse-search "<TeXstudioDIR>\texstudio.exe %%f -line %%l" ?p{pdf}:ame"
\end{lstlisting}
将其命名为 \texttt{user0:sumatrapdf}.
这里的 \texttt{?c:rme}、\texttt{@}、\texttt{\%\%}、\texttt{?p\{pdf\}:ame} 均是 \TeX Studio 自己定义的有特殊含义的字符.
接下来,
在 \menu{Build > Build \& View} 中将
\texttt{txs:///compile | txs:///view}
改为
\texttt{txs:///compile | txs:///user0}.
最后在 \menu{Menus} 中将 \menu{View} 的命令由 \texttt{txs:///view}
改为 \texttt{txs:///user0}.
完成以上设置后,
关闭窗口.
这时,
用户使用快捷键 \keys{F5} 和 \keys{F7}
均可打开 SumatraPDF 并且实现了正反向搜索.

如果以上设置没能正确实现正反向搜索,
那么可以将 \texttt{user0:sumatrapdf} 改为
\begin{lstlisting}
  dde:///"<SumatraPDFDIR>\SumatraPDF.exe":SUMATRA/control/[ForwardSearch(?p{pdf}:ame",?c:rme",@,0,0,1)]
\end{lstlisting}
其他不变.
而后用 SumatraPDF 打开编译完的 pdf 文件,
将
\begin{lstlisting}
  "<TeXstudioROOT>\texstudio.exe" "%f" -line %l
\end{lstlisting}
写入 \menu{Settings > Options > Set inverse search command line}.
至此完成了逆向搜索,
双击 pdf 文件便可回到 \TeX Studio 中对应代码的行首.

\chapter{VS Code}
同样先介绍命令行
\begin{lstlisting}
  <SumatraPDFROOT>\SumatraPDF.exe -reuse-instance -forward-search main.tex 4 -inverse-search "\"<VSCodeROOT>\bin\code.cmd\" -r -g \"%f:%l\"" main.pdf
\end{lstlisting}
其中 \texttt{<VSCodeROOT>} 是 VS Code 的安装路径,
\texttt{code.cmd} 是软件已经写好的打开 VS Code 的批处理文件.
与前面不同的是 \texttt{-inverse-search} 参数对应了不同的编辑器.

接下来,
用户安装 \textsf{LaTeX-Workshop} 插件.
然后打开设置的 \texttt{json} 文件,
在其中添加以下代码:
\begin{lstlisting}
  "latex-workshop.view.pdf.viewer": "external",
  "latex-workshop.view.pdf.ref.viewer":"external",
  "latex-workshop.view.pdf.external.viewer.command": "<SumatraPDFROOT>/SumatraPDF.exe",
  "latex-workshop.view.pdf.external.viewer.args": [
	  "-inverse-search",
	  "\"<VSCodeROOT>/bin/code.cmd\" -r -g \"%f:%l\"",
    "%PDF%"
  ],
  "latex-workshop.view.pdf.external.synctex.command": "<SumatraPDFROOT>/SumatraPDF.exe",
  "latex-workshop.view.pdf.external.synctex.args":[
    "-forward-search",
    "%TEX%",
    "%LINE%",
    "%PDF%",
  ],
\end{lstlisting}
注意在 \texttt{json} 文件中要将路径中的 \verb+\+ 写作 \verb+/+.
下面略加解释以上设置的用意.

为了能够使用 SumatraPDF 进行正反向搜索,
首先需要将
\begin{lstlisting}
  "latex-workshop.view.pdf.viewer"
\end{lstlisting}
和
\begin{lstlisting}
  "latex-workshop.view.pdf.ref.viewer"
\end{lstlisting}
都设置为外部 (external).
然后在
\begin{lstlisting}
  "latex-workshop.view.pdf.external.viewer.command"
\end{lstlisting}
和
\begin{lstlisting}
  "latex-workshop.view.pdf.external.viewer.args"
\end{lstlisting}
中分别设置打开 pdf 阅读器的命令和所需参数,
这些参数用于进行反向搜索.
类似地,
正面搜索的命令和参数分别定义在
\begin{lstlisting}
  "latex-workshop.view.pdf.external.synctex.command"
\end{lstlisting}
和
\begin{lstlisting}
  "latex-workshop.view.pdf.external.synctex.args"
\end{lstlisting}

完成以上设置,
用户使用时在左侧点击 \menu{View LaTeX PDF} 便可打开 SumatraPDF,
之后点击 \menu{navigate, select and edit > SyncTeX from cursor} 便可进行正向搜索.
当然,
VS Code 还提供了快捷键供用户使用,
用户可以自行查询或更改为自己喜欢的按键组合.

\chapter{Notepad++}
Notepad++ 配合 SumatraPDF 阅读器需要一些插件,
例如 \texttt{NppExec} 和 \texttt{Customize Toolbar},
它们的安装方式很简单,
在 \menu{插件 > 插件管理} 中即可找到.

首先用 Notepad++ 打开一个 \texttt{tex} 文件.
通过快捷键 \keys{F6} 调出 \texttt{Execute} 对话框.
在窗口内输入如下代码:
\begin{lstlisting}
  cd $(CURRENT_DIRECTORY)
  xelatex -synctex=1 -interaction=nonstopmode $(NAME_PART)
\end{lstlisting}
简要介绍一下代码含义.
\verb+$(CURRENT_DIRECTORY)+ 是 \texttt{NppExec} 插件的设置的变量,
表示当前文件所在的目录;
\verb+$(NAME_PART)+ 表示当前文件文件名 (不含扩展名).
这两句代码的含义就很好理解了,
进入当前目录,
对当前文件用 \texttt{xelatex} 以指定参数进行编译.
将这段临时脚本起名保存为 \texttt{XeLaTeX},
点击 \keys{OK} 按钮即开始这段脚本.
类似地,
我们可以创建其他编译命令的执行脚本,
不一一赘述.

为了实现 SumatraPDF 的正反向搜索,
预览 pdf 文件的脚本应输入如下代码:
\begin{lstlisting}
  cd $(CURRENT_DIRECTORY)
  NPP_run "<SumatraPDFROOT>\SumatraPDF.exe" -reuse-instance -forward-search $(NAME_PART).tex $(CURRENT_LINE) -inverse-search "\"<Notepad++ROOT>\Notepad++.exe\" -n%l %f" $(NAME_PART).pdf
\end{lstlisting}
其中,
\verb+Npp_run+ 是 \texttt{NppExec} 附带的命令,
表示执行外部程序和命令;
\verb+$(CURRENT_LINE)+ 表示文件的当前行.
若要形成编译链,
连续使用几个既已保存的脚本,
可以不用将脚本命令重复复制,
可以使用 \texttt{NppExec} 附带命令 \verb+Npp_exec+ 执行相应脚本即可.
例如,
已经设置保存了 \texttt{XeLaTeX}、\texttt{bibtex} 和 \texttt{View PDF} 三个脚本,
若需创建一个标准的完整编译过程的脚本,
可以在 \texttt{Execute} 窗口输入如下代码并保存即可
\begin{lstlisting}
  Npp_exec "XeLaTeX"
  Npp_exec "bibtex"
  Npp_exec "XeLaTeX"
  Npp_exec "XeLaTeX"
  Npp_exec "View PDF"
\end{lstlisting}

利用 \menu{插件 > NppExec > Advanced Options} 可以进行一些高级设置,
将已经保存的脚本加入到菜单项中.
\menu{Menu item} 可以选择需要添加到菜单的脚本,
并为菜单项设置名称;
\menu{Menu item*} 中勾选 \menu{Place to the Macros submenu} 后,
菜单项将添加在\menu{宏 (M)} 菜单项之下.

在\menu{宏 (M) > 管理快捷键}可以设置快捷键.
在\menu{插件命令}选项卡可以找到添加到菜单项的命令,
利用对话框设置快捷键即可.

快捷键 \keys{Shift + F6} 可以调出 NppExec 控制台输出过滤.
在 \menu{HighLight} 选项卡中,
我们可以设置控制台信息过滤条件 \texttt{l.\%LINE\%},
并设置高亮颜色和粗体下划线样式.
在勾选最前面的 \menu{checkbox},
启用这个条件后,
我们可以编辑一个简单的 tex 文件:
\begin{lstlisting}[language={[LaTeX]TeX}]
  \documentclass{article}
\begin{document}
  Hello! \latex
\end{document}
\end{lstlisting}
我们故意写错 \verb+\LaTeX+ 为 \verb+\latex+,
进行编译后,
系统将给出报错信息,
控制台回显的报错信息中:
\begin{lstlisting}
  l.4  Hello! \latex
\end{lstlisting}
双击这条报错信息,
在文本编辑器内,
光标将定位到出错这一行的行首.
这个设置实现了错误快速定位.

\texttt{Cstomize Toolbar} 安装完成后,
\menu{插件 > Customize Toolbar > Custom Buttons} 可以启动用户自定义工具条按钮.
按钮的配置是通过文件
\begin{lstlisting}
  %APPDATA%\Notepad++\plugins\config\CustomizeToolbar.btn
\end{lstlisting}
实现的.
文件示例如下:
\begin{lstlisting}
  宏(M),pdfLaTeX,,,pdflatex.bmp
  宏(M),XeLaTeX,,,xelatex.bmp
  宏(M),bibtex,,,bibtex.bmp
  宏(M),biber,,,biber.bmp
  宏(M),makeindex,,,makeindex.bmp
  宏(M),View PDF,,,adobe.bmp
  宏(M),Clear,,,trash.bmp
  宏(M),Latexmk,,,latexmk.bmp
\end{lstlisting}
其中,
每一行均为4个逗号,
分隔成的5部分,
前4部分为各级菜单项名称,
必须与当前菜单选用的界面语言一致,
最后一项为按钮显示图标文件名,
图标文件必须为 $16 \times 16$ 的 bmp 格式图像.
特别需要注意的是:
\texttt{CustomizeToolbar.btn} 的文件编码格式必须保存为 \textbf{UCS-2 Little Endian 含 BOM},
文件行尾格式必须为 \textbf{Windows (CR LF)}.
\end{document}