I'm writing a major report, and have two PDF files I'd like to include as appendices. The report is written using ReStructuredText, and rst2pdf will be used to convert it.
Does docutils or rst2pdf have any functionality for external files as appendices?
Docutils has the raw directive for passing data through to the final output untouched. In the documentation they demonstrate this for the LaTeX and HTML outputs. rst2pdf seems to support this directive: in the manual they use the raw directive to include some text/commands in the final PDF (see the section headed Raw Directive) but they do not demonstrate using this directive for including external PDF files.
If rst2pdf does support this feature, you should just be able to use:
.. raw:: pdf
:file: your_pdf_file.pdf
:encoding: the encoding of the PDF file, if different from the
reStructuredText document's encoding.
I have just had a go at doing this (if in doubt, give it a go) and I get a number of UnicodeDecodeErrors, so the feature seems to be supported but I can't get it to work.
You could embed PDFs as images, but that makes no sense for appendixes.
If you only have those files as PDF, you can add them using a PDF manipulation tool, but those usually break page numbering or links or some other piece of the PDFs.
In the end, I couldn't fix this problem directly. I converted the ReStructuredText file to Latex, and included the appendices there.
Related
rmarkdown, following {xe|lua}latex, allows to specify fonts for main text, sans-serif text, monspaced text (most notably code chunks !) and math fonts in the YAML header. At least for PDF rendering via xetex, this works.
However, I found no (documented) way to pass options to the underlying setxxxfont \LaTeX command. For example, the YAML fragment :
```
monofont: Inconsolata
```
generates the following \LaTeX fragment :
\setmonofont[Mapping=tex-ansi]{Inconsolata}
I have two questions with this:
why is the Mapping=tex-ansi added ? And how to control it ? (I'm working in UTF8...).
How could I set additional arguments for the font options i.e. \setmonofont[Scale=0.91]{TeX Gyre Cursor}?
The R Markdown book and the Pandoc's User's Guide did not reveal anything pertinent.
Background:
When R Markdown converts the knitted code to the output format (PDF), a pandoc template is used. The template is stored within the package, and any variables which get replaced by the YAML variables are contained in the $$ Notation
1. Encoding
The Mapping=tex-ansi is added to the code as a workaround an issue as reported on GitHub. Therefore I would be cautious of deleting this for potential side effects.
If you do indeed wish to change this code, you will have to make a copy of the LaTeX template file used to convert the document. You can find the default template here. See here for some more information on providing custom templates.
2. Additional Font Options
You can use the monofontoptions YAML argument to add additional arguments to the font options.
Documentation of the variables which can be parsed by the LaTeX output are available in the pandoc documentation
Why is it important? My collaborators would like to be able to modify my .pdf reports and they are not able to modify the actual .tex code. They are sooo used to word !
How I write my reports? I use knitr. What a great and useful tool; thanks Yihui :)
What I'm looking for? convert the generated pdf report into .doc (my collaborators favorite !)
a solution might help: Pandoc (http://johnmacfarlane.net/pandoc/). As it's explained in the introduction of page of Pandoc, it can be used to convert LaTex to .docx and to markup. I then thought converting the .tex file of each of my reports (a .tex file is generated when I run my knitr .Rnw file) and convert it to .docx using pandoc:
pandoc -s myTexRepot.tex -o aDocReport.docx
issue: 1) Figures are missing in my .docx file. 2) I generate all my tables in my reports using xtable(), none of them can be converted! 3) Also, I lose all table of contents, section numbering.
Markup to Word: Issue (1) above is still an issue in converting Markup code to .doc
Is there any better idea to approach the issue of converting latex to doc. If Pandoc is the best, would you know how I can solve the issues above?
I really appreciate your help.
since you are already using knitr, you can call the rmarkdown:render() function to knit the document.
there is a parameter in render() called output_format[1]. the parameter along with the YAML header in your knitr document will allow you do generate the pdf and word document simultaneously
[1] output_format
R Markdown output format to convert to. Pass "all" to render all formats defined within the file. Pass the name of a format (e.g. "html_document") to render a single format or pass a vector of format names to render multiple formats. Alternatively you can pass an output format object; e.g. html_document(). If NULL is passed then the output format is the first one defined in the YAML metadata of the input file (defaulting to HTML if none is specified).
When converting markdown to html the default is (I think) to convert an image file into a string and embed it into the html file. When running knit on an rhtml file this is not the case though. Here a separate figure folder is generated, which is of course a sensible default setting.
But if I want my images to be embedded, is there a way to achieve this using rthml and knitr as well? I can't find any options where to declare this.
Thanks, Mark
Alright, I figured out myself. Seems to work just the same as with .Rmd files, by simply passing the string "base64_images"to the options argument in knit2html.
knit2html("foo.Rhtml", options=c("base64_images"))
Is it possible to include an image in documentation generated by roxygen? I have a number of functions that are essentially wrappers for ggplot() that I'd like to document by showing an example of the output.
As per the change list from the announcement of R 2.14:
Rd markup has a new \figure tag so that figures can be included in
help pages when converted to HTML or LaTeX. There are examples on
the help pages for par() and points().
From: http://cran.r-project.org/doc/manuals/R-exts.html#Figures
To include figures in help pages, use the \figure markup. There are three forms.
The two commonly used simple forms are \figure{filename} and \figure{filename}{alternate text}. This will include a copy of the figure in either HTML or LaTeX output. In text output, the alternate text will be displayed instead. (When the second argument is omitted, the filename will be used.) Both the filename and the alternate text will be parsed verbatim, and should not include special characters that are significant in HTML or LaTeX.
The expert form is \figure{filename}{options: string}. (The word ‘options:’ must be typed exactly as shown and followed by at least one space.) In this form, the string is copied into the HTML img tag as attributes following the src attribute, or into the second argument of the \Figure macro in LaTeX, which by default is used as options to an \includegraphics call. As it is unlikely that any single string would suffice for both display modes, the expert form would normally be wrapped in conditionals. It is up to the author to make sure that legal HTML/LaTeX is used. For example, to include a logo in both HTML (using the simple form) and LaTeX (using the expert form), the following could be used:
\if{html}{\figure{logo.jpg}{Our logo}}
\if{latex}{\figure{logo.jpg}{options: width=0.5in}}
The files containing the figures should be stored in the directory man/figures. Files with extensions .jpg, .pdf, .png and .svg from that directory will be copied to the help/figures directory at install time. (Figures in PDF format will not display in most HTML browsers, but might be the best choice in reference manuals.) Specify the filename relative to man/figures in the \figure directive.
I plan to use reStructuredText to write documentation with the main purpose of generating some nice HTML pages. For this I use the docutils rst2html.py tool.
However, I may also need to present the documentation in nice plain text format, that is without the reStructuredText markup, and where paragraph wrapping and similar nice formatting is still performed on the text output. But, there is no rst2txt.py tool in the docutils.
Is there a way to convert reStructuredText to nice plain text format, maybe with use of special options to docutils ?
I have also seen this done by rendering to html using rst2html, then converting the html to plain text by using a command-line html browser, such as:
lynx http://lynx.browser.org
links http://links.sourceforge.net
w3m http://w3m.sourceforge.net
elinks http://elinks.or.cz
Each of these browsers has a command-line switch or similar to render its output to a .txt file, so you could create a two line script called 'rst2txt', something like:
rst2html docs.rst docs.html
lynx -dump docs.html > docs.txt
Sphinx has a TextBuilder for txt output format. Just tried it and it seems to do what you are looking for.
However, it might be a little outdated because it is not in the default Makefile. But it worked well on my fairly complex documentation (150 pdf pages). To use it, just add the following target to it:
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
#echo
#echo "Build finished."
Also, keep in mind that Sphinx implements only a subset of the rst specs.