Main Question:
Is there a way to flag Pandoc to turn off appending the bibliography but still have it insert the correct inline citations?
I am writing a Markdown / Knitr document that has a main file (article.Rmd) and several "child" files that are included in the main file using Knitr's "child=" chunk option.
The child files are basically sections of the main article file, just separated for easier editing and management. Throughout these child section files, I use the citations in the Markdown text (e.g. "#author_title_1999") to cite various papers. The main file and each child file has a YAML header that provides the BibTex file location, e.g.:
---
bibliography: mybibfile.bib
...
(Including this YAML entry more than once is not a problem; see the readme on metadata-blocks.)
When I compile the entire document using Knitr, a big Markdown document is created. I then use Pandoc with the --filter pandoc-citeproc option to manage the citations. Pandoc inserts nice citations and appends a list of the cited papers as references/bibliography. Cool.
As I write and edit the individual child sections, I use the same citation compiling which produces the correct inline citations, but unfortunately also appends the references at the end, even though it's just a section of the larger document. I would like to compile these small child sections with inline citations, but without the bibliography at the end.
I think this is possible with the suppress-bibliography metadata field first introduced in pandoc-citeproc 0.7 (released in May 2015). From the current pandoc-citeproc man page:
pandoc-citeproc will look for the following metadata fields in the input:
...
suppress-bibliography : If this has a true value, the bibliography will be left off. Otherwise a bibliography will be inserted into each Div element with id refs. If there is no such Div, one will be created at the end of the document.
(as a workaround, you can also quite easily create a custom CSL style that doesn't produce a bibliography, by deleting the cs:bibliography child element of the style. See http://docs.citationstyles.org/en/stable/specification.html#child-elements-of-cs-style.)
Related
How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:
Sphinx
Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:
Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.
RST, in General
The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)
A complete example is available here.
New, better answer for 2016!
The autosection extension lets you do this easily.
=============
Some Document
=============
Internal Headline
=================
then, later...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
This extension is built-in, so all you need is to edit conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)
Example:
Hey, read the :ref:`Installation:Homebrew` section.
where Homebrew is a section inside a different document named Installation.rst.
This uses the autosection feature, so will need to edit config.py with the following:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
In Sphinx 3.0.3 the only solution that worked for me is :any: (see https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything).
Suppose, one document has such a section:
.. _my-section:
My Section
----------
Lorem ipsum blablabla
Then another document can have the following fragment to create a link:
See :any:`my-section` for the details
I was struggling to make this work and i found out that the actual notation is :ref:'{dir-path}/Installation:Homebrew' where {dir-path} is the relative path to Installation.rst from where config.py exists
Adding description of behavior that was confusing to me.
Section titles must be referenced with the file name (overview here) in front of it:
overview.rst:
************
API Overview
************
index.rst:
:ref:`overview:API Overview`
However, when referencing links, the file name (constants here) must not be there:
constants.rst:
.. _section-constants:
*******************
Enums and Constants
*******************
api.rst:
:ref:`section-constants`
Also, for this to work, one must enable extension 'autosectionlabel':
conf.py:
extensions = [
...
"sphinx.ext.autosectionlabel"
]
I try to upgrade a program converting blog entries using pandoc from using pandoc-citeproc to the new citeproc. I have not found a simple example for usage of citeproc and have difficulties to use it.
Specifically, I do not see how to construct the list of references and list of citations.
For the list of references, I assume I should process the bib file as it was done with, e.g.
parseBibTex :: String -> IO [Entry.T]
what is the corresponding function?
I cannot see how to extract the list of citations and how to produce the formatted file.
Perhaps I misunderstood that citeproc was a replacement for pandoc-citeproc. I think it would be extremely useful to see a simple complete example how a text converted to pandoc format and a reference bib file would be processed to obtain a formated text file. I think I could work from such an example...
Thank you!
The functions you want for processing a Pandoc document with citeproc are not in citeproc itself but in Pandoc's Citeproc module:
https://hackage.haskell.org/package/pandoc-2.16.2/docs/Text-Pandoc-Citeproc.html
These functions handle all of the details for you.
I have done some experiments with writing programs that are also at the same time valid documentation that can be rendered as README's by e.g. Github - this ensures that code snippets are up to date and valid - and had some very interesting findings with Markdown. Unfortunately that format does not support having an automatically generated table of contents, so we looked into AsciiDoc which does.
I managed to copy an example using :toc: macro (to be able to place it after the opening summary), and then went on to make it valid Java, which essentially mean that you have to start the file with the /* characters but then I cannot make the table of contents appear any more.
The snippet starts with:
= Asciidoctor PDF Theming Guide
Dan Allen <https://github.com/mojavelinux[#mojavelinux]>
// Settings:
:idprefix:
:idseparator: -
:toc: macro
:experimental:
ifndef::env-github[:icons: font]
ifdef::env-github[]
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
:window: _blank
// Aliases:
:conum-guard-yaml: #
ifndef::icons[:conum-guard-yaml: # #]
ifdef::backend-pdf[:conum-guard-yaml: # #]
:url-fontforge: https://fontforge.github.io/en-US/
:url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
:url-prawn: http://prawnpdf.org
////
Topics remaining to document:
* line height and line height length (and what that all means)
* title page layout / title page images (logo & background)
////
[.lead]
The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file
... blurb removed ...
/* (Experiment with asciidoc)
= Dagger 2 Hello World
// (Important: As an experiment Main.java is also a valid markdown file copied unmodified to README.md, so only edit Main.java)
This project is a single file Hello World Dagger-2 Maven project for
Java 8 and later, while also being its own documentation written in AsciiDoc.
toc::[]
My gut feeling is that the TOC does only work as expected if the file starts with lines parsed by AsciiDoc where this is set up and configured. If any output is generated before the configuration bits (like the Java comment) then the TOC is silently empty.
Hence I would like to know how I should do this correctly. All I want is a functional toc::[] macro in a file starting with /*
Asciidoc markup files are not Java source files. While I understand that this would be a compelling combination of the formats, that capability does not exist.
To keep source files up-to-date, your Asciidoc source files can use the include directive to include a source file. See: https://asciidoctor.org/docs/user-manual/#include-directive
To include, say, a single method, you can use tags to mark the start and end of the method's implementation, and then you can include that tag-delimited code section like this:
[source,java]
----
include::path/to/source.java[tag="method-x"]
----
Note that if the path to the Java source that you want to include is outside of the current directory, you may have to change the safe mode accordingly: https://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely
I have an article document in LaTeX in which I cite sources from a bibtex file. I want to be able to still cite these sources, but I also want to be able to compile the bibliography into a separate pdf document. This document is a grant proposal for NSF, and they want the bibliography to be in a separate document.
I have searched the web for solutions to this problem. Each solution is slightly different than what I need for my particular problem.
\usepackage{cite}
\usepackage{bibentry}
...
\nocite{*}
\bibliographystyle{plain}
\bibliography{MyBibliography}
The sources are included at the end of the document, and they are labeled "References". I need them in a separate document, labeled "Bibliography".
Assuming your main file is called test, you can simply import its bibliography in a new file with \input{test.bbl} and change the \renewcommand{\refname}{Bibliography} or \renewcommand{\bibname}{Bibliography}, depending on the documentclass. This way the references will have the same numbering as in the original document.
\documentclass{article}
\usepackage{cite}
\usepackage{bibentry}
\renewcommand{\refname}{Bibliography}
\begin{document}
\input{test.bbl}
\end{document}
Wenn converting markdown files with cross document links to html, docs or pdf the links get broken in the process.
I use pandoc 1.19.1 and MikTex.
This is my testcase:
File1: doc1.md
[link1](/doc2.md)
File2: doc2.md
[link2](/doc1.md)
The result in html with this call to pandoc:
pandoc doc1.md doc2.md -o test.html
looks like this:
<p>link1 link2</p>
As pdf a link is created but it does not work. Exported as docx it looks the same.
I would have asumed that when multiple files are processed and concatenated into the same output file, then the result should contain page internal links like anchor links for html-output. But instead the link it created in the output file like it was in the input files. Even the original file extension .md is preserved in the created links.
What am I doing wrong ?
My problem looks a bit like this:
pandoc command line parameters for resolving internal links
In the comments of this question the bug is said to be fixed by a pull request in May. But the bug still seems to exist.
Greetings
Georg
I had a similar problem when trying to export a Gitlab wiki to PDF. There links between pages look like filename-of-page#anchor-name and links within a page look like #anchor-name. I wrote a (finicky and fragile) pandoc filter that solved that problem for me, who knows it's useful to others.
Example files
To explain my solution I'll have two test files, 101-first-page.md:
# First page // Gitlab automatically creates an anchor here named #first-page
Some text.
## Another section // Gitlab automatically creates an anchor here named #another-section
A link to the [first section](#first-page)
and 102-second-page.md:
# Second page // Gitlab automatically creates an anchor here named #second-page
Some text and [a link to the first page](101-first-page#first-page).
When concatenating them to render as one document in pandoc, links between pages break as anchors change. Below the concatenated file with the anchors in comments.
# First page // anchor=#first-page
Some text.
## Another section anchor=#another-section
A link to the [first section](#first-page)
# Second page // anchor=#second-page
Some text and [a link to the first page](101-first-page#first-page). // <-- this anchor no longer exists.
The link from the second to the first page breaks as the link target is incorrect.
Solution
By pre-processing all markdown files first individually via a pandoc filter, and then concatenating the resulting json files I was able to get all links working.
Requirements
pandoc
latex
python
pandocfilters
Every file should start with a level 1 header that matches the filename (except for the number at the beginning). E.g. the file 101-A file on the wiki.md should have a first level one header named A file on the wiki.
Filter
The filter itself (together with the pandoc script) is available in this gist.
What it does is:
It gets the label of the first level 1 header, e.g. first-page
It prepends that label to all other labels in the same file, e.g. first-page-another-section.
It renames all links to the same file such that the prefix is taken into account, e.g. #first-page-first-page
It renames all links to other files such that the (assumed) prefix of the other files is taken into account, e.g. 101-first-page#first-page becomes #first-page-first-page.
After it has run every markdown file through this filter individually and converted them to json files, it concatenates the json's and converts that to a PDF.
As the pandoc README states:
If multiple input files are given, pandoc will concatenate them all (with blank lines between them) before parsing.
So for the parsing done by pandoc, it sees it as one document... so you'll have to construct your links in multiple files as if it they were all in one file, see also this answer for details.