oli-obk / rust-pandoc Goto Github PK

License: Apache License 2.0

Rust 100.00%

rust-pandoc's Introduction

Instructions

Install pandoc
add the pandoc crate to your Cargo.toml
```
[dependencies]
pandoc = "0.8"
```

create a pandoc builder and execute it

let mut pandoc = pandoc::new();
pandoc.add_input("hello_world.md");
pandoc.set_output(OutputKind::File("hello_world.pdf".to_string()));
pandoc.execute().unwrap();

PDF-output

Windows specific

install miktex or texlive, if your installation paths differ from the default use the add_latex_path_hint function to add them to the pandoc builder.

Common Issues

file not found errors

use add_pandoc_path_hint to add the actual path to pandoc search path. Under windows it can often be found in %LOCALAPPDATA%\Pandoc\, but that path is searched automatically by this crate.

rust-pandoc's People

Stargazers

Watchers

rust-pandoc's Issues

How to set MarkdownExtension?

I want to add the argument -f markdown-implicit_figures and I found it but I don't know how to apply this 🤔

Last month I submitted a number of PRs around updates myself and a friend were making for our use of this crate. We've settled and don't think we need more changes for now, so I'd like to formally request a new release of the pandoc crate. I'm happy to prepare a PR for updating the version numbers etc, though I don't believe it's necessarily sensible to grant me the right to upload to crates.io for it.

If you want me to co-maintain the crate then I'm prepared to, though I'd expect to be pretty hands-off unless I need further changes to support my use-cases.

Just tell me how you'd like me to help, if you don't want to do the release entirely yourself, and I'll do my best.

Thanks,

Publish latest commits to crates.io

I am really grateful for the PR which added the citeproc option.
I'm currently using it via the git= option in my Cargo file, but I'm not able to publish my crate if the dependency isn't published.

Please can you bump the number and republish to crates.io?

Piped PDF output?

Currently there's no OutputFormat for PDF. I realize that this is probably designed this way due to the way pandoc itself handles PDF output. However, because of this, I don't currently see a way of getting PDF output to a pipe.

Is it possible? In Pandoc it is, because you can force output to stdout by passing -o -, but then I have no way of telling rust-pandoc that I want PDF output because there is no extension.

Add functions to allow input and output via stdin/stdout

The builder currently lacks functions to supply a string (via stdin) to Pandoc and read the result into a string (via stdout). It would be great, if this functionality could be added, since the Pandoc executable supports this and it would enable conversions on-the-fly.

Thanks

update to pandoc 1.19

https://github.com/jgm/pandoc/releases/tag/1.19

make LatexEngine's value an enum with the commonly know latex types

currently to enable e.g. xetex one needs to call

pandoc.add_option(pandoc::PandocOption::LatexEngine("xelatex".into()));

adding strings is not pretty. To still allow arbitrary engines the enum can have a Custom variant.

Pandoc's docs have pdflatex|lualatex|xelatex as the choices. so:

enum LatexEngine {
    PdfLatex,
    LuaLatex,
    XeLatex,
    Custom(PathBuf),
}

or maybe leave off the Latex postfix

How to set --pdf-engine argument?

I found the enum PandocOption::PdfEngine(PathBuf), and the apply function.

But I still don't know how to set --pdf-engine argument.

Pandoc error output is redirected to stderr and not captured in error object

Consider the following code:

extern crate pandoc;

fn main() {
    let mut p = pandoc::Pandoc::new();
    p.add_input("test.mediawiki");
    p.set_output_format(pandoc::OutputFormat::Json);
    p.set_input_format(pandoc::InputFormat::MediaWiki);
    p.set_output(pandoc::OutputKind::File("output.txt".into()));
    match p.execute() {
        Ok(_) => println!("It worked."),
        Err(e) => println!("Error: {:?}", e),
    }
}

When the specified input file is missing, the output looks like this:

pandoc: test.mediawiki: openFile: does not exist (No such file or directory)
Error: exit_code: Some(1)stdout: stderr:

As shown, Pandoc prints its stderr itself and the members of the error object do
not contain the desired output. For a broken document with a syntax error, this
would look like this:

pandoc:
Error at "source" (line 75, column 1):
unexpected end of input
expecting "|", "!", "||", "!!", "|-", lf new-line or "|}"

^
CallStack (from HasCallStack):
  error, called at src/Text/Pandoc/Error.hs:66:13 in pandoc-1.17.2-Cq2iGUE9cDsAnk3CjbY7fx:Text.Pandoc.Error
Error: exit_code: Some(1)stdout: stderr:

It would be great if stderr could be properly captured, so that Pandoc can be
used as a silent back-end. It would also allow for post-processing of the error
message.

Thanks

Add `add_options`

Rather than requiring the user to call add_option over and over again, it would be extremely helpful to simply allow them to call add_options(), probably with the following signature:

pub fn add_options(options &[PandocOption])

Change function signatures to accommodate chaining builder calls

The corresponding feature request #8 has been closed as resolved, but the following does not work with rust-pandoc version 0.8.10:

Steps to reproduce

Invoke pandoc in a builder approach:

// Cargo.toml dependencies: pandoc = "0.8.10"

use pandoc::{InputFormat, InputKind, OutputFormat, OutputKind, PandocOutput};

// [...]

let pandoc_output = pandoc::Pandoc::new()
    .set_input(InputKind::Pipe(markdown.to_string()))
    .set_output(OutputKind::Pipe)
    .set_input_format(InputFormat::Markdown, Vec::new())
    .set_output_format(OutputFormat::Json, Vec::new())
    .execute()
    .expect("pandoc");

Expected outcome

Code compiles, pandoc does its thing

Actual outcome

The set_xyz() functions take and return &mut self, but execute() takes self. Therefore, chaining execute() behind a set_xyz() call leads to the following error:

error[E0507]: cannot move out of a mutable reference
    --> src/lib.rs:16:29
     |
16   |           let pandoc_output = pandoc::Pandoc::new()
     |  _____________________________^
17   | |             .set_input(InputKind::Pipe(markdown.to_string()))
18   | |             .set_output(OutputKind::Pipe)
19   | |             .set_input_format(InputFormat::Markdown, Vec::new())
20   | |             .set_output_format(OutputFormat::Json, Vec::new())
21   | |             .execute()
     | |              --------^
     | |______________|_______|
     |                |       move occurs because value has type `pandoc::Pandoc`, which does not implement the `Copy` trait
     |                value moved due to this method call
     |
note: this function takes ownership of the receiver `self`, which moves value
    --> /home/elaforma/.cargo/registry/src/github.com-1ecc6299db9ec823/pandoc-0.8.10/src/lib.rs:1212:24
     |
1212 |     pub fn execute(mut self) -> Result<PandocOutput, PandocError> {
     |                        ^^^^

There are two possible ways to solve this:

Other Rust builders often have their setter functions consume and return self as well (e.g., fn set_xyz(self, xyz: XyzOptionType) -> Self)
Another possibility would be to have execute() take &mut self instead

Both of these would naturally be breaking changes.

Support a builder approach

Currently, configuring the pandoc item is something like this:

let pandoc = Pandoc::new();
pandoc.set_input(...);
pandoc.add_option(...);
pandoc.add_option(...);
pandoc.add_option(...);
pandoc.add_option(...);
pandoc.set_output(...)
let result = pandoc.execute();

It would be nice to use the builder pattern instead:

let result = Pandoc::new()
    .set_input(...)
    .add_option(...)
    .add_option(...)
    .add_option(...)
    .add_option(...)
    .set_output(...)
    .execute(...);

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: exit_code: Some(6)stdout: stderr: --reference-docx has been removed. Use --reference-doc instead.