pandoc-mode expects that the pandoc binary can be found in your system's $PATH and that the contents of $PATH is available to Emacs. Especially on OS X, this may not always be the case. To remedy this, you can set the user option pandoc-binary to the full path of pandoc on your system. A more elegant solution is to install the exec-path-from-shell package. This package makes sure that the contents of your system's $PATH variable is visible to Emacs, allowing Emacs to find pandoc. =pandoc-mode=期望可以在系统的=$PATH=中找到=pandoc=二进制文件，并且=$PATH=的内容对Emacs是可用的。特别是在OS X上，情况可能不总是这样。要解决这个问题，可以在系统上将user选项=pandoc-binary=设置为=pandoc=的完整路径。一个更好的解决方案是安装exec-path-from-shell包。这个包确保系统的=$PATH=变量的内容对Emacs是可见的，允许Emacs查找=pandoc=。

The most important settings are the input and output formats. The input format is set automatically by Emacs on the basis of the major mode of the input file, but you can change it if you need to. The output format defaults to “Native Haskell”, so most likely you will want to set it to something else before you run Pandoc. The input and output format menus also provide access to a submenu with the Markdown extensions that Pandoc supports. 最重要的设置是输入和输出格式。输入格式由Emacs根据输入文件的主要模式自动设置，但是如果需要，您可以更改它。输出格式默认为“本机Haskell”，因此您很可能希望在运行Pandoc之前将其设置为其他格式。输入和输出格式菜单还提供了对带有Pandoc支持的Markdown扩展的子菜单的访问。

As already stated, you may wish to use different output formats for a single input file. Most likely, the options that you want to pass to Pandoc will be different for each output format. To make this easier, pandoc-mode has the ability to save the settings for a specific output format. The main menu has an option “Settings files” (C-c / s), which takes you to a submenu where you can save the current settings. Emacs saves these settings to a hidden file in the same directory as the file you're editing, under a name composed of the input file, appended with the name of the output format and the string .pandoc. So if your input file is called mytext.md, the html settings file will be called .mytext.md.html.pandoc. (See the section ‘Settings Files' for details.) 如前所述，您可能希望对单个输入文件使用不同的输出格式。对于每种输出格式，您希望传递给Pandoc的选项很可能是不同的。为了简化这一点，=pandoc-mode=能够保存特定输出格式的设置。主菜单有一个选项“设置文件”(C-c / s)，它会带你到一个可以保存当前设置的子菜单。Emacs将这些设置保存到与正在编辑的文件相同目录中的一个隐藏文件中，该文件的名称由输入文件组成，并附加输出格式的名称和字符串=.pandoc=。如果你的输入文件被称为=mytext。md=， html=设置文件将被调用.mytext.md.html.pandoc=。(详见' Settings Files'小节)

A single document can have a separate settings file for each output format that Pandoc supports. These can simply be created by setting all options the way you want them for the first output format, save them, then choose another output format, set the required options, save again, etc. Because the name of a settings file contains the output format for which it was created, the different settings files won't interfere with each other. When you switch the output format (with C-c / O), Emacs checks if a corresponding settings file exists and loads it if one is found. 对于Pandoc支持的每种输出格式，单个文档可以有单独的设置文件。这些可以简单地创建通过设置所有选项的方式，你想要的第一个输出格式，保存它们，然后选择另一个输出格式，设置所需的选项，再次保存，等等。因为设置文件的名称包含它创建时的输出格式，所以不同的设置文件不会相互干扰。当您切换输出格式(with C-c / O)时，Emacs检查是否存在相应的设置文件，如果找到，则加载它。

On systems that have symbolic links, it is also possible to specify a default output format (C-c / s d). This is done by creating a symbolic link to the settings file of the current output format (a settings file is created if one doesn't exist yet) with the output format replaced by the string "default". The file it points to is read by the function pandoc-load-default-settings, making it possible to automatically load a specific settings file when pandoc-mode is invoked, as described above. 在具有符号链接的系统上，也可以指定默认的输出格式(C-c / s d)。这是通过创建到当前输出格式的设置文件的符号链接来实现的(如果设置文件还不存在，则创建一个设置文件)，输出格式将被string ="default"=替换。它所指向的文件由函数=pandoc-load-default-settings=读取，这样就可以在调用=pandoc-mode=时自动加载特定的设置文件，如上所述。

Note that the current output format is always visible in the mode line: the “lighter” for pandoc-mode in the mode line has the form Pandoc/<format>, where <format> is the current output format. 注意，当前的输出格式在模式行中总是可见的:模式行中的“lighter”for =Pandoc -mode=有form =Pandoc/<format>=，其中=<format>=是当前的输出格式。

The major modes for which pandoc-mode selects an input format automatically can be customised (user option pandoc-major-modes). You can add major modes or remove those that you don't use. Similarly, you can customise the file extensions for each output format (pandoc-output-format-extensions). 可以自定义=pandoc-mode=选择输入格式的主要模式(user option pandoc-major-modes)。您可以添加主要模式或删除那些您不使用。类似地，您可以为每种输出格式定制文件扩展名(pandoc-output-format-extensions)。

The options menu has a number of submenus, each related to a specific type of options: file options, reader options, writer options (general and specific), citations and math rendering. The file options menu contains options for the output file, output directory, data directory, the directory to extract media files to, and the master file. Only two of these (the data directory and the extract media directory) correspond directly to a Pandoc option. The output file and output directory options are combined to form Pandoc's --output option, while the master file option is only used by pandoc-mode. These options are discussed in the sections ‘Setting an output file' and 'Master file', respectively. 选项菜单有许多子菜单，每个子菜单都与特定类型的选项相关:文件选项、阅读器选项、作者选项(通用和特定)、引用和数学呈现。文件选项菜单包含输出文件、输出目录、数据目录、要提取媒体文件的目录和主文件的选项。其中只有两个(data目录和extract media目录)直接对应于Pandoc选项。输出文件和输出目录选项组合在一起形成了Pandoc的=——output=选项，而主文件选项仅由= Pandoc -mode=使用。这些选项分别在' Setting an output file'和'Master file'小节中讨论。

Note that the subdivision in the options menu is based on the subdivision in the Pandoc README and the user guide on Pandoc.org, which should make it easier to find the relevant options in the menus. pandoc-mode supports Pandoc version 1.x and version 2.x: options that are only valid in Pandoc 1.x are marked with an asterisk. (Options that only exist in Pandoc 2.x aren't marked.) 请注意，选项菜单中的细分是基于Pandoc README中的细分和Pandoc.org上的用户指南，这将使在菜单中查找相关选项变得更加容易。= Pandoc -mode=支持Pandoc版本1。x和版本2。x:仅在Pandoc 1中有效的选项。x用星号标出。(选项只存在于Pandoc 2中。x不明显。)

One nice thing about the hydra menus is that the value of an option is displayed beside it. Pandoc's options come in several different kinds. Switches, (boolean options that do not take a value), are toggled when you select them, and their value is displayed as either “yes” or “no”. If you select another kind of option, you are asked to provide a value in the minibuffer. For template variables and metadata items, you are asked both a variable / metadata name and a value. hydra菜单的一个优点是，选项的值显示在它旁边。Pandoc有几种不同的选择。开关(不接受值的布尔选项)在您选择它们时被切换，它们的值显示为“yes”或“no”。如果您选择另一种类型的选项，系统会要求您在minibuffer中提供一个值。对于模板变量和元数据项，将同时询问变量/元数据名称和值。

Unsetting an option can usually be done by prefixing the relevant key with a dash -. This is actually the negative prefix argument, which can be typed without the meta (alt) key when inside a hydra menu. So for example, if you're in the files menu (C-c / o f), you can set an output file with o, and to unset the output file, you can type - o. 取消设置选项通常可以通过在相关键前面加上破折号=-来实现。这实际上是否定前缀参数，在hydra菜单中输入时不需要使用meta (alt)键。例如，如果在files菜单中(=C-c / o f)，可以使用=o=设置输出文件，要取消设置输出文件，可以输入=- o=。

Many Pandoc options have file names as values. These are normally prompted for and stored as relative paths. File name completion is available, starting from the current directory. For some options, such as --css, relative paths make more sense because an absolute file would almost certainly be incorrect once the output html file is moved to the web server. Other options, such as --template, look in Pandoc's data directory and therefore also do not require an absolute path. Lastly, auxiliary files, such as --include-in-header, will usually be stored in the same directory as the source file or in a subdirectory, in which case a relative path is unproblematic. 许多Pandoc选项都有文件名作为值。它们通常被提示并存储为相对路径。从当前目录开始，文件名完成是可用的。对于某些选项，例如=——css=，相对路径更有意义，因为一旦输出html文件被移动到web服务器，绝对文件几乎肯定是不正确的。其他选项，如=——template=，查找Pandoc的数据目录，因此也不需要绝对路径。最后，辅助文件，如=——include-in-header=，通常存储在与源文件相同的目录或子目录中，在这种情况下，相对路径是没有问题的。

However, if for some reason you need to store an absolute path for an option, you can do so by using the prefix argument C-u. So for example in the general writer options menu, accessible through C-/ o w, pressing C-u H asks for a file to include in the header and stores it as an absolute path. Note that absolute paths are not expanded, i.e., they may contain abbreviations such as ~ for one's home directory. This makes it easier to share settings files between computers with different OSes (for example, Linux expands ~ to /home/<user>, while on OS X it becomes /Users/<user>). 但是，如果出于某种原因需要存储某个选项的绝对路径，可以使用前缀参数=C-u=来实现。例如，在通用写入器选项菜单中，可以通过=C-/ o w=访问，按=C-u H=要求将文件包含在头文件中，并将其存储为绝对路径。注意，绝对路径没有展开。，它们可能包含主目录的缩写，如=~=。这使得在具有不同操作系统的计算机之间共享设置文件变得更加容易(例如，Linux将=~= to /home/<user>=，而在OS X上则变为=/Users/<user>)。

Note that if you use a minibuffer completion framework (such as Ivy or Helm), file name completion may work differently. Ivy, for example, always expands file names. 注意，如果您使用的是minibuffer补全框架(比如Ivy或Helm)，那么文件名补全的工作方式可能不同。例如，Ivy总是展开文件名。

Some file options (such as --epub-stylesheet) may have a default value. Such options can be specified on the pandoc command line without naming a file. To select such a default value for a file option, use a numeric prefix argument, which in the hydra menu is obtained by pressing a number without the meta key. That is, to select the default EPUB style sheet, go to the EPUB options menu (C-/ o s E) and press 1 s. 一些文件选项(比如=——epub-stylesheet=)可能有一个默认值。可以在=pandoc=命令行中指定这些选项，而不需要命名文件。要为文件选项选择这样的默认值，请使用一个数字前缀参数，在hydra菜单中，该参数是通过按一个没有元键的数字获得的。也就是说，要选择默认的EPUB样式表，转到EPUB选项菜单(C-/ o s E)，然后按=1 s=。

Options that are not files or numbers are “string options”, which include options that specify a URL. These may also have a default value, which can be set in the same way as with file options. Note, though, that this does not apply to options that only have a limited set of possible values (e.g., --email-obfuscation, --pdf-engine). These can be set or unset, you cannot explicitly request their default value. (`pandoc' uses their default values even if they are not specified on the command line, unlike string options.) 不是文件或数字的选项是“字符串选项”，其中包括指定URL的选项。这些选项也可能有一个默认值，可以用与文件选项相同的方式设置。但是请注意，这并不适用于只有有限可能值集的选项(例如，=——email-obfuscation=， ——pdf-engine)。这些值可以设置或取消设置，您不能显式地请求它们的默认值。(与字符串选项不同，即使没有在命令行中指定，“pandoc”也会使用它们的默认值。)

To get an overview of all the settings for the current file and output format, you can use the option “View current settings” in the main menu (C-c / S). This displays all settings in a *Help* buffer in a Lisp-like format. For example, the settings for TeXinfo output of this manual look like this: 要查看当前文件和输出格式的所有设置，可以使用主菜单中的“查看当前设置”选项(C-c / S)。这将以类似于lisp的格式显示=\*Help\*= buffer中的所有设置。例如，本手册的TeXinfo输出设置如下:

((standalone . t)
(read . "markdown")
(write . "texinfo")
(output . t)
(include-before-body . "~/src/pandoc-mode/manual/texi-before-body"))

pandoc-mode allows you to set or change template variables through the menu. The variables are in the general writer options menu, the metadata in the reader options menu. Emacs will ask you for the name of a variable or metadata item and for a value for it. If you provide a name that already exists (TAB completion works), the new value replaces the old one. =pandoc-mode=允许您通过菜单设置或更改模板变量。这些变量位于“常规写入器选项”菜单中，“读取器选项”菜单中的“元数据”菜单中。Emacs将询问变量或元数据项的名称及其值。如果您提供的名称已经存在(制表符完成工作)，则新值将替换旧值。

Deleting a template variable or metadata item can be done by prefixing the menu key with -. Emacs will ask you for the variable name (TAB completion works here, too) and removes it from the list. 删除模板变量或元数据项可以通过在菜单键前面加上=-=来完成。Emacs将询问您的变量名(TAB补全也适用于此)并将其从列表中删除。

The first item in the menu is “Run Pandoc” (accessible with C-c / r), which, as the name suggests, runs Pandoc on the document, passing all options you have set. By default, Pandoc sends the output to stdout (except when the output format is “odt”, “epub” or “docx”, in which case output is always sent to a file). Emacs captures this output and redirects it to the buffer *Pandoc output*. The output buffer is not normally shown, but you can make it visible through the menu or by typing C-c / V. Error messages from Pandoc are also displayed in this buffer. 第一项菜单中“Pandoc运行”(访问=碳碳/ r ),,顾名思义,运行Pandoc文档,通过所有选项设置。默认情况下,Pandoc将输出发送到stdout(除非输出格式是“odt”,“epub”或“多克斯”,在这种情况下,总是发送到输出文件)。Emacs捕获此输出并将其重定向到缓冲区\*Pandoc输出\*=。输出缓冲区通常不显示，但您可以通过菜单或键入=C-c / V=使其可见。来自Pandoc的错误消息也显示在这个缓冲区中。

When you run Pandoc, pandoc-mode also generates a few messages, which are logged in a buffer called *Pandoc log*. You will rarely need to see this, since pandoc-mode displays a message telling you whether Pandoc finished successfully or not. In the latter case, the output buffer is displayed, so you can see the error that Pandoc reported. 运行Pandoc时，= Pandoc -mode=也会生成一些消息，这些消息被记录在一个名为=\*Pandoc log\*=的缓冲区中。您很少需要看到这个，因为= Pandoc -mode=显示一条消息，告诉您Pandoc是否成功完成。在后一种情况下，将显示输出缓冲区，因此可以看到Pandoc报告的错误。

Note that when you run Pandoc, Pandoc doesn't read the file on disk. Rather, Emacs feeds it the contents of the buffer through stdin. This means that you don't actually have to save your file before running Pandoc. Whatever is in your buffer, saved or not, is passed to Pandoc. Alternatively, if the region is active, only the region is sent to Pandoc. 注意，运行Pandoc时，Pandoc不会读取磁盘上的文件。相反，Emacs通过=stdin=将缓冲区的内容提供给它。这意味着您实际上不必在运行Pandoc之前保存文件。无论缓冲区中有什么，是否保存，都会传递给Pandoc。或者，如果该区域处于活动状态，则只将该区域发送到Pandoc。

If you call this command with a prefix argument C-u (so the key sequence becomes C-/ C-u r: C-/ to open the menu and C-u r to run Pandoc), Emacs asks you for an output format to use. If there is a settings file for the format you specify, the settings in it will be passed to Pandoc instead of the settings in the current buffer. If there is no settings file, Pandoc will be called with just the output format and no other options. 如果您使用前缀参数=C-u=调用此命令(因此键序列变为=C-/ C-u r=: =C-/=打开菜单并=C-u r=运行Pandoc)， Emacs将要求您使用输出格式。如果您指定的格式有设置文件，那么其中的设置将被传递给Pandoc，而不是当前缓冲区中的设置。如果没有设置文件，则只调用输出格式的Pandoc，没有其他选项。

Note that specifying an output format this way does not change the output format or any of the settings in the buffer, it just changes the output profile used for calling Pandoc. This can be useful if you use different output formats but don't want to keep switching between profiles when creating the different output files. 注意，以这种方式指定输出格式并不会更改输出格式或缓冲区中的任何设置，它只会更改用于调用Pandoc的输出配置文件。如果您使用不同的输出格式，但在创建不同的输出文件时不希望在配置文件之间不断切换，那么这将非常有用。

If you want to save the output to a file rather than have it appear in the output buffer, you can set an explicit output file. Note that setting an output file is not the same thing as setting an output format (though normally the output file has a suffix that indicates the format of the file). 如果希望将输出保存到文件中，而不是显示在输出缓冲区中，可以设置显式输出文件。注意，设置输出文件与设置输出格式是不同的(尽管通常输出文件有一个表示文件格式的后缀)。

In pandoc-mode, the output file setting has three options: the default is to send output to stdout, in which case it is redirected to the buffer *Pandoc output*. This option can be selected by typing - o in the file options menu. Alternatively, you can let Emacs create an output filename for you. In this case the output file will have the same base name as the input file but with the proper suffix for the output format. To select this option, prefix the output file key o with C-u in the file options menu. The third option is to specify an explicit output file. This can (obviously) be done by hitting just o. 在= Pandoc -mode=中，输出文件设置有三个选项:默认是将输出发送到stdout，在这种情况下，输出被重定向到缓冲区=\*Pandoc output\*=。可以在“文件选项”菜单中键入=- o=来选择此选项。或者，您可以让Emacs为您创建一个输出文件名。在这种情况下，输出文件将具有与输入文件相同的基本名称，但是输出格式有适当的后缀。要选择此选项，请在“文件选项”菜单中的“输出文件”键=o=前面加上=C-u=。第三个选项是指定一个显式输出文件。这显然可以通过点击=o=来实现。

Note that Pandoc does not allow output to be sent to stdout if the output format is an OpenOffice.org Document (ODT), EPUB or MS Word (docx) file. Therefore, Emacs will always create an output filename in those cases, unless of course you've explicitly set an output file yourself. 注意，如果输出格式是OpenOffice.org文档(ODT)、EPUB或MS Word (docx)文件，Pandoc不允许将输出发送到stdout。因此，在这些情况下，Emacs将始终创建输出文件名，当然，除非您自己显式地设置了输出文件。

The output file you set is always just the base filename, it does not specify a directory. Which directory the output file is written to depends on the setting “Output Directory” (which is not actually a Pandoc option). Emacs creates an output destination out of the settings for the output directory and output file. If you don't specify any output directory, the output file will be written to the same directory that the input file is in. 您设置的输出文件总是基本文件名，它不指定目录。输出文件写入到哪个目录取决于设置“output directory”(实际上不是Pandoc选项)。Emacs从输出目录和输出文件的设置中创建输出目的地。如果不指定任何输出目录，则输出文件将被写入与输入文件所在的相同目录。

The second item in the main menu is “Create PDF” (invoked with C-c / p). This option calls Pandoc with a PDF file as output file. Pandoc offers different ways of creating a PDF file: you can use LaTeX, an HTML-to-PDF converter, or groff. Which method is used depends on the output format you specify, because Pandoc creates a PDF file by first converting your input file to the specified output format and then calling the pdf converter on the output file. 主菜单中的第二项是“创建PDF”(用=C-c / p=调用)。此选项使用PDF文件作为输出文件调用Pandoc。Pandoc提供了创建PDF文件的不同方法:您可以使用LaTeX、HTML-to-PDF转换器或groff。使用哪种方法取决于指定的输出格式，因为Pandoc首先将输入文件转换为指定的输出格式，然后在输出文件上调用PDF转换器，从而创建PDF文件。

When creating a PDF using pandoc-mode, Emacs first checks if the output format of the current buffer is set to latex, context, beamer, html, or ms. If it is, C-c / p creates the PDF using that format. If you want to bypass this automatic detection, use a prefix argument C-u (i.e., type C-c / C-u p). Emacs will then ask you for the output format to use. 在使用=pandoc-mode=创建PDF时，Emacs首先检查当前缓冲区的输出格式是否设置为=latex=， context=， =beamer=， =html=，或=ms=。如果是，则=C-c / p=使用该格式创建PDF。如果您想绕过这个自动检测，请使用前缀参数=C-u=(即， type =C-c / C-u p)。然后Emacs将询问您要使用的输出格式。

If the buffer's current output format does not allow for PDF creation, Emacs will ask you which output format to use. If there is a settings file for the output format you specify, it is used to create the PDF. (The current buffer's settings aren't changed, however.) If there is no settings file, Pandoc is called with only the input and output formats and the output file. 如果缓冲区的当前输出格式不允许创建PDF，那么Emacs将询问您使用哪种输出格式。如果您指定的输出格式有一个设置文件，那么它将用于创建PDF。(不过，当前缓冲区的设置没有改变。)如果没有设置文件，则使用输入和输出格式以及输出文件调用Pandoc。

The format you choose is remembered (at least until you close the buffer or change the output format), so that the next time you convert the buffer to PDF, you are not asked for the format again. If you want to use a different format, use the prefix argument C-u. 您选择的格式将被记住(至少在关闭缓冲区或更改输出格式之前)，以便下次将缓冲区转换为PDF时，不会再次询问该格式。如果您想使用不同的格式，请使用前缀参数=C-u=。

This setup means that you do not need to switch the output format to latex, context or html5 every time you wish to create a PDF, which can be practical if you're also converting to another format. However, if you wish to change settings for PDF output, you do need to switch to the relevant output format. 这种设置意味着您不需要在每次希望创建PDF时都将输出格式切换为=latex=、=context=或=html5=，如果您也要转换为另一种格式，这是很实用的。但是，如果您希望更改PDF输出的设置，您\*确实\*需要切换到相关的输出格式。

Note that for latex, beamer and html, you can use different PDF engines. For latex and beamer, these are pdflatex (the default), xelatex and lualatex, for html there are wkhtmltopdf (the default), weasyprint and prince. If you wish to use a PDF engine other than the default, you need to set the option pdf-engine. 注意，对于=latex=、=beamer=和=html=，可以使用不同的PDF引擎。For latex and beamer=，其中=pdflatex=(默认值)，=xelatex and lualatex=， For =html there wkhtmltopdf=(默认值)，=weasyprint and =prince=。如果希望使用默认之外的PDF引擎，则需要设置option = PDF -engine=。

After running Pandoc, you can view the output file with the option View output file in the menu (or C-c / v). Emacs will try to display the file created during the most recent Pandoc run. Which viewer is used to display the output file depends on the output format (not on the output file's extension, so that you can use different viewers for different output formats, even if their file extensions are identical. For example, docbook, jats=and =tei all use xml as the file extension, but you may not want to use the same viewer for all of them). 运行Pandoc后，可以使用菜单中的option = view output file=查看输出文件(或=C-c / v=)。Emacs将尝试显示在最近一次运行Pandoc期间创建的文件。使用哪个查看器来显示输出文件取决于输出格式(而不是输出文件的扩展名，因此您可以对不同的输出格式使用不同的查看器，即使它们的文件扩展名是相同的。例如，=docbook=、=jats=和=tei=都使用=xml=作为文件扩展名，但您可能不希望对所有扩展名使用相同的查看器)。

Viewers are defined in the customisation option pandoc-viewers. There are three types of viewers: you can choose to use Emacs itself as the file viewer, in which case the output file is opened in Emacs and displayed using display-buffer. It is also possible to define an external viewer, which should then be a program that takes a file argument on the command line. For example, word processor formats (odt, docx) and Powerpoint presentations (pptx) are by default opened in LibreOffice, which can be called with the shell command libreoffice <filename>. 查看器在自定义选项=pandoc-viewer 中定义。有三种类型的查看器:您可以选择使用Emacs本身作为文件查看器，在这种情况下，在Emacs中打开输出文件并使用=display-buffer=显示。还可以定义一个外部查看器，它应该是一个在命令行上接受文件参数的程序。例如，word处理器格式(=odt=， =docx)和Powerpoint演示文稿(pptx)在LibreOffice中默认打开，可以使用shell命令= LibreOffice <filename>=调用。

Lastly, it is also possible to specify a specific Emacs function to handle the file. This should be a function that takes a file name as argument. The function can pass on the file to an external program (HTML-based formats, for example, are by default handled by the function browse-url, which sends the file to a suitable browser), or it can arrange to open the file in Emacs, if the standard find-file-noselect is not suitable. Note, though, that if you choose this method, you should also make sure that your function not only opens the file but also displays its buffer (e.g., using display-buffer). 最后，还可以指定一个特定的Emacs函数来处理该文件。这应该是一个以文件名作为参数的函数。该函数可以将文件传递给外部程序(例如，基于html的格式在默认情况下由函数=browse-url=处理，该函数将文件发送到合适的浏览器)，或者如果标准的=find-file-noselect=不合适，它可以安排在Emacs中打开文件。但是请注意，如果选择此方法，还应该确保函数不仅打开文件，而且还显示其缓冲区(例如，使用=display-buffer=)。

If the most recent call to Pandoc created a pdf file (i.e, the option “Convert to pdf” was called), Emacs will display the pdf file instead of the output file defined by the output file/directory options. The viewer to use in this case is defined by the option pandoc-pdf-viewer, which can be Emacs (which will then use =doc-view-mode, or=pdf-tools` if installed) or an external program. 如果最近调用Pandoc创建了一个pdf文件(i。，选项“转换为pdf”被调用)，Emacs将显示pdf文件，而不是由输出文件/目录选项定义的输出文件。在本例中使用的查看器由option =pandoc-pdf-viewer=定义，它可以是Emacs(然后使用=doc-view-mode，如果安装了=pdf-tools ')或外部程序。

Note that this functionality is not as full-featured as with e.g., AUCTeX and SyncTeX. There is no forward or backward search and what happens when you view a file when an earlier version of that file is already open in some application is up to that application. Emacs will usually notice that the file has changed on disk and will ask you if you want to reload it. Pdf viewers will generally behave correctly (that includes pdf-tools in Emacs) and simply reload the file without asking. 请注意，此功能不像AUCTeX和SyncTeX那样功能全面。不存在前向或后向搜索，当您查看一个文件时，当该文件的早期版本已经在某个应用程序中打开时，所发生的事情取决于该应用程序。Emacs通常会注意到磁盘上的文件已经更改，并询问是否要重新加载它。Pdf查看器的行为通常是正确的(包括= Pdf -tools= in Emacs)，并且不需要询问就可以简单地重新加载文件。

If you want to open the output file automatically after conversion, you can add the function pandoc-view-output to pandoc-async-success-hook. As the name of the hook implies, this only works if you call Pandoc asynchronously ---cf. the option pandoc-use-async--- but this is the default and there is usually little reason to change it. 如果希望在转换后自动打开输出文件，可以添加函数=pandoc-view-output= to =pandoc-async-success-hook=。正如钩子的名字所暗示的那样，这只有在异步调用Pandoc时才有效——cf。选项=pandoc-use-async=——但这是默认的，通常没有什么理由去改变它。

If you try to view an output file before calling Pandoc (e.g., after reopening the input file), Emacs will try to display the output file defined by the output directory and output file settings. If no output file is defined at all (which means that Pandoc does not create an output file but instead sends its output to standard out), Emacs will show the *Pandoc output* buffer, which is where the output of the call to Pandoc is captured. 如果您尝试在调用Pandoc之前查看输出文件(例如，在重新打开输入文件之后)，Emacs将尝试显示由=output目录=和=output file= settings定义的输出文件。如果根本没有定义输出文件(这意味着Pandoc不创建输出文件，而是将其输出发送到标准输出)，则Emacs将显示=\*Pandoc输出\*= buffer，在这里捕获对Pandoc调用的输出。

If the most recent Pandoc run returned an error, trying to view the output file will result in an error as well, unless you provide a prefix argument (C-c / C-u v), in which case Emacs will try to display the output file defined by the output directory and output file settings. 如果最近Pandoc运行返回一个错误,试图查看输出文件将导致一个错误,除非你提供一个前缀的论点(碳碳/ c u v =),在这种情况下,Emacs会显示定义的输出文件=输出文件输出目录=和 =设置。

By default, Emacs starts pandoc as an asynchronous process using a tty. If this causes problems for some reason, you can try using a pipe instead by customising pandoc-process-connection-type. Alternatively, you can use a synchronous process by unsetting the user option pandoc-use-async. 默认情况下，Emacs使用tty启动=pandoc=作为异步进程。如果由于某种原因导致问题，您可以通过自定义=pandoc-process-connection-type=来尝试使用管道。或者，您可以通过取消user选项=pandoc-use-async=的设置来使用同步进程。

pandoc-mode provides the function pandoc-jump-to-reference that locates a reference within external bibliography files indicated by the bibliography user option. Note that entries to the bibliography user option list must have an absolute path for this option to work properly (i.e. ="./Bibliography.bib"= rather than "Bibliography.bib"). This feature is not bound to any key by default, but may of course be bound to a key combination as follows: pandoc-mode=提供函数=pandoc-jump-to-reference=，该函数在由=bibliography user选项指定的外部书目文件中定位一个引用。注意，=bibliography= user选项列表中的条目必须有一个绝对路径，以便该选项正常工作(例如="./ bibliography。而不是“bibliographi .bib”=)。这个特性默认情况下不绑定到任何键，但是当然可以绑定到一个键组合，如下所示:

(define-key markdown-mode-map (kbd "C-c j") 'pandoc-jump-to-reference)

The jump behaviour can be customised by changing the option pandoc-citation-jump-function. Its default value is pandoc-goto-citation-reference, which opens the relevant BibTeX file in a new window and moves point to the entry. Two alternative functions have been defined: pandoc-open-in-ebib, which opens the relevant entry in Ebib, and pandoc-show-citation-as-help, which shows the entry in a *Help* buffer, but does not open the corresponding BibTeX file. 可以通过更改选项=pandoc-引用-跳转-函数=来定制跳转行为。它的默认值是=pandoc-goto- reference=，它将在一个新窗口中打开相关的BibTeX文件，并将指向该条目。已经定义了两个替代函数:=pandoc-open-in-ebib=，它打开Ebib中的相关条目;=pandoc-show-引用-as- Help ，它显示了\*Help\*=缓冲区中的条目，但是没有打开相应的BibTeX文件。

Alternatively, you may also define your own function, which should take two arguments: the key of the entry to be displayed and a list of BibTeX files. 或者，您也可以定义自己的函数，该函数应该有两个参数:要显示的条目的键和BibTeX文件的列表。

If you have a master file with one or more @@include directives and you're editing one of the included files, running Pandoc from that buffer will not produce the desired result, because it runs Pandoc on the included file. To make working with included files easier, you can specify a master file for them, with the command pandoc-set-master-file (through the menu with C-c / o f m). When this option is set, Pandoc is run on the master file rather than on the file in the current buffer. 如果您有一个带有一个或多个=@@include=指令的主文件，并且您正在编辑其中一个包含的文件，那么从该缓冲区运行Pandoc将不会产生所需的结果，因为它在包含的文件上运行Pandoc。为了使处理包含的文件更容易，可以使用命令=pandoc-set-master-file=(通过菜单=C-c / o f m=)为它们指定一个主文件。设置此选项后，Pandoc将在主文件上运行，而不是在当前缓冲区中的文件上运行。

The settings used in this case are always the settings for the master file, not the settings for the included file. The only exception is the output format, which is taken from the buffer from which you run Pandoc. This makes it possible to change the output format while in a buffer visiting an included file and have pandoc-mode do the right thing. 本例中使用的设置始终是主文件的设置，而不是包含的文件的设置。唯一的例外是输出格式，它取自运行Pandoc的缓冲区。这使得在缓冲区中访问包含的文件时更改输出格式成为可能，并且have =pandoc-mode=做正确的事情。

One thing to keep in mind is that the master file setting is dependent on the output format. When you set a master file, it is only set for the output format that is active. This means that you need to set the output format before you set the master file. 需要记住的一点是，主文件设置依赖于输出格式。当您设置主文件时，它只设置为活动的输出格式。这意味着您需要在设置主文件之前设置输出格式。

Note that the master file menu also has an option “Use this file as master file” (C-c / o f M). When you select this option, the current file is set as master file and a project settings file is created for the current output format. This is a quick way to set the master file for all files in a directory, since the project settings will apply to all files in the directory. 注意，主文件菜单也有一个选项“使用这个文件作为主文件”(C-c / o f M)。选择此选项时，将当前文件设置为主文件，并为当前输出格式创建项目设置文件。这是为目录中的所有文件设置主文件的快速方法，因为项目设置将应用于目录中的所有文件。

Defining @@-directives yourself is done in two steps. First, you need to define the function that the directive will call. This function must take at least one argument to pass the output format and may take at most one additional argument. It should return a string, which is inserted into the buffer. The second step is to go to the customisation buffer with M-x customize-group RET pandoc RET. One of the options there is pandoc-directives. This variable contains a list of directives and the functions that they are linked with. You can add a directive by providing a name (without @@) and the function to call. Note that directive names may only consists of letters (a-z, A-Z) or numbers (0-9). Other characters are not allowed. Directive names are case sensitive, so @@Date is not the same as @@date. 您自己定义=@@=-directive有两个步骤。首先，您需要定义指令将调用的函数。此函数必须使用至少一个参数来传递输出格式，并且最多可以使用一个附加参数。它应该返回一个字符串，该字符串被插入到缓冲区中。第二步是使用=M-x customize-group= RET pandoc RET=进入定制缓冲区。其中一个选项是=pandoc-directive =。这个变量包含一列指令和它们所链接的函数。您可以通过提供一个名称(没有=@@)和要调用的函数来添加一个指令。注意，指令名只能由字母(a-z=， =a-z)或数字(0-9)组成。其他字符是不允许的。指令名是大小写敏感的，所以=@@Date=和=@@Date=不一样。

Passing more than one argument to an @@-directive is not supported. However, if you really want to, you could use split-string to split the argument of the @@-directive and “fake” multiple arguments that way. 不支持向=@@=-指令传递多个参数。但是，如果您真的想这样做，您可以使用=split-string=来分割=@@=-指令的参数，并以这种方式“伪造”多个参数。

A final note: the function that processes the @@-directives is called pandoc-process-directives and can be called interactively. This may be useful if a directive is not producing the output that you expect. By running pandoc-process-directives interactively, you can see what exactly your directives produce before the resulting text is sent to pandoc. The changes can of course be undone with M-x undo (usually bound to C-/). 最后注意:处理=@@=-伪指令的函数被称为=pandoc-process-directive ，可以交互调用。如果一个指令没有产生您期望的输出，这可能会有用。通过交互式地运行=pandoc-process-directive =，您可以看到在生成的文本被发送到pandoc之前，指令究竟生成了什么。当然，可以使用=M-x undo=(通常绑定到=C-/)来撤消更改。

There is another customisable variable related to @@-directives: pandoc-directives-hook. This is a list of functions that are executed before the directives are processed. These functions are not supposed to change anything in the buffer, they are intended for setting up things that the directive functions might need. 还有一个与=@@=-相关的可定制变量:=pandoc-directives-hook=。这是在处理指令之前执行的函数列表。这些函数不应该改变缓冲区中的任何东西，它们是用来设置指令函数可能需要的东西的。