From e00e5a4cc27dd5b995887f8152bb71da4f2792c9 Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sat, 3 Jul 2021 15:19:39 -0700 Subject: Add doc/faqs.md. This is imported from the website; in the future the website version will be drawn from here. Added a FAQ on the use of `\AtEndPreamble` for cases when the contents of `header-includes` need to refer to definitions that come later in the preamble. See #7422. --- doc/faqs.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 doc/faqs.md (limited to 'doc/faqs.md') diff --git a/doc/faqs.md b/doc/faqs.md new file mode 100644 index 000000000..0b53730f3 --- /dev/null +++ b/doc/faqs.md @@ -0,0 +1,110 @@ +% FAQs + +::: faqs + +## How can I convert a whole directory of files from Markdown to RTF? + +On linux or OSX: + + for f in *.txt; do pandoc "$f" -s -o "${f%.txt}.rtf"; done + + +In Windows Powershell: + + gci -r -i *.txt |foreach{$rtf=$_.directoryname+"\"+$_.basename+".rtf";pandoc -f markdown -s $_.name -o $rtf} + +## I used pandoc to convert a document to ICML (or OPML or RTF), and when I try to open it I'm told it's invalid. What have I done wrong? + +Be sure to use the `-s` or `--standalone` flag, or you just get a +fragment, not a full document with the required header: + + pandoc -s -f markdown -t icml -o my.icml my.md + +## I get a blank document when I try to convert a markdown document in Chinese to PDF. + +By default, pandoc uses pdflatex to generate the PDF, and pdflatex +doesn't handle Chinese characters. But you can change the default to +use xelatex instead. You should also make sure you're using a font +with Chinese glyphs. For example: + + pandoc -o c.pdf --pdf-engine=xelatex -V mainfont='Adobe Ming Std' + +## The Windows installer does a single user install, rather than installing pandoc for all users. How can I install pandoc for all users? + +Run the following command as admin: + + msiexec /i pandoc-VERSION.msi ALLUSERS=1 + +This will put pandoc in `C:\Program Files\Pandoc`. +You can install Pandoc to a different directory by setting APPLICATIONFOLDER parameter, +for example: + + msiexec /i pandoc-1.11.1.msi ALLUSERS=1 APPLICATIONFOLDER="C:\Pandoc" + +## How do I change the margins in PDF output? + +The option + + -V geometry:margin=1in + +will set the margins to one inch on each side. If you don't want uniform +margins, you can do something like + + -V geometry:"top=2cm, bottom=1.5cm, left=1cm, right=1cm" + +Or + + -V geometry:"left=3cm, width=10cm" + +For more options, see the documentation for the LaTeX [geometry +package](https://www.ctan.org/pkg/geometry). + +## How does pandoc compare to multimarkdown? + +Here is a [wiki +page](https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown) +comparing the two. + +## When I specify an image width of 50% and convert to LaTeX, pandoc sets the height to textheight and the aspect ratio isn't preserved. How can I prevent this? + +For example, if you convert an image with `{width="50%"}`, the LaTeX produced +will be `\includegraphics[width=0.5\textwidth,height=\textheight]`. + +This output presupposes the following code in pandoc's default latex +template: + +``` +% Scale images if necessary, so that they will not overflow the page +% margins by default, and it is still possible to overwrite the defaults +% using explicit options in \includegraphics[width, height, ...]{} +\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio} +``` + +If you don't have this in your custom template, you should +add it. If we didn't set the `height` explicitly in this way, +the image would not be resized correctly unless it was +being resized to smaller than its original size. + +## Pandoc sometimes uses too much memory. How can I limit the memory used by pandoc? + +`pandoc +RTS -M30m -RTS` will limit heap memory to 30MB. +When converting a document requires more than this, an out of +memory error will be issued. + +## When using `--include-in-header` with PDF or LaTeX output, how do I reference tex declarations coming after `$header-includes$` in the default template? + +For various reasons, the `$header-includes$` are not at the very +end of the LaTeX preamble. This poses a problem when the code +you are inserting depends on declarations in the preamble coming +after the `$header-includes$` location. For example, you might +want to reference the `\author` and `\title` metadata values +(set at the very bottom of the preamble) and present them in +margins. In that case you can wrap your code in `etoolbox`'s +`\AtEndPreamble`. The technique is demonstrated in [this +gist](https://gist.github.com/JohnLukeBentley/9dda6166b9ee5c4127afd2b8cd16b70a). +When using `\AtEndPreamble`, keep any `makeatletter` or +`makeatother` outside of the `\AtEndPreamble`, as shown in the +example. + +::: + -- cgit v1.2.3 From 95541294d384d5bf6514b0b676bf93b44ba4d26d Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sat, 3 Jul 2021 15:51:07 -0700 Subject: Add FAQ on converting from/to PDF --- doc/faqs.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'doc/faqs.md') diff --git a/doc/faqs.md b/doc/faqs.md index 0b53730f3..2f3368837 100644 --- a/doc/faqs.md +++ b/doc/faqs.md @@ -106,5 +106,23 @@ When using `\AtEndPreamble`, keep any `makeatletter` or `makeatother` outside of the `\AtEndPreamble`, as shown in the example. +## How can I convert PDFs to other formats using pandoc? + +You can't. You can try opening the PDF in Word or Google Docs +and saving in a format from which pandoc can convert directly. + +## Do I really need to install a 1 GB TeX installation to produce a PDF using pandoc? + +No. You can get by with a relatively small TeX installation, +for example, by starting with MacTeX's Basic TeX distribution +and using the `tlmgr` tool to install a few packages required by pandoc +(see https://pandoc.org/MANUAL.html#creating-a-pdf). + +Or, you can produce PDFs via HTML and `wkhtmltopdf`, +or via groff ms and `pdfroff`. (These don't produce as nice +topography as TeX, particularly when it comes to math, but they +may be fine for many purposes.) + + ::: -- cgit v1.2.3