The examples folder demonstrates what you can produce with mediabuilder. For each example there is a basic Makefile, which provides examples of recipes for building different media types. For example, this will render the example manuscript:
cd examples/manuscript
make manuscript
- Manuscript: Render the .md manuscript source into a generic manuscript PDF, or use the Oxford University Press Bioinformatics Template; or use the Databio lab template.
- NIH biosketch: Render the .md biosketch source into a PDF
- Grant (NIH-formatted): Render the .md grant source into a PDF
- CV (pending).
- Install software prerequisites:
Really, just use Bulker (requires docker):
pip install bulker
bulker load databio/mediabuilder
bulker activate databio/mediabuilder
Or you can do it the hard way:
- Install pandoc to convert markdown to PDF.
- Install inkscape to convert SVG to PDF.
- Install libreoffice (optional) for some recipes that read
xlsordocxfiles. - Install ghostscript (optional) if you need to merge PDFs (should be standard on linux).
-
Clone and configure
mediabuilder:- Clone databio/sciquill
- Configure
mediabuilder. The examples use an environment variable$CODE, in which you will store this repo:
export CODE=`pwd` git clone git@github.com:databio/sciquill.gitThe latex templates in
tex_templatesrely on some relative includes. To use these you'll need to add the path to that folder to yourTEXINPUTSenvironment variable. Adding something like this in your.bashrcwill accomplish this permanently:export TEXINPUTS="${TEXINPUTS}${CODE}/sciquill/tex_templates/:"If using bulker, you will also need to make sure this variable is passed on to your bulker tools. So, add it to the list of
envvarsin your bulker config file. -
Assemble your BibTeX database (optional).
If you want to produce a media type that includes citations, you will also need a
bibtexfile with your references. My favorite BibTeX management software is JabRef, because it is free, actively developed, and uses BibTeX as its native file format. The default makefile (mediabuilder.make) will use an${BIBTEXDB}environment variable to look for yourbibtexdatabase. You can set it like this:export BIBTEXDB=path/to/db.bib -
Produce your content in markdown format.
You may choose to start with an example from the examples folder.
This repository contains:
- tex_templates - a collection of tex templates for, e.g. NIH grants.
- tex_utilities - some bonus tex software to do things like add page numbers to an existing PDF
- bin - Small scripted utilities to build figures, extract bibliographies, suppress page numbers, merge PDFs, select versions of grant source files, etc. Documented in /bin/README.md.
- csl - Contains some citation styles, which are derived from the citationstyles project repository, or from Zotero collection (https://github.com/citation-style-language/styles); it's the set of styles I use frequently, with some possible additions or adjustments for particular things I need. You can use any style from that repository or define your own
- docx_templates - Word document templates for different grant agencies. To be used in YAML RMarkdown header as
output:
word_document:
reference_docx: styles.doc/NSF_grant_style.docx
I've also produced docker containers for pandoc, inkscape, libreoffice that make this easier if you use docker:
docker pull nsheff/pandocker
docker pull nsheff/inkscape-docker
docker pull nsheff/libre
There's a bulker manifest that makes it much simpler:
pip install bulker
bulker load databio/mediabuilder
bulker activate databio/mediabuilder
Running libreoffice on the command-line like this will silently fail if you
already have libreoffice running. If you use a containerized version, you can
get around that issue. Use my libre docker container so you can run it while the real one is open.
budget:
echo "Make sure libreoffice isn't already open"
libreoffice --headless --invisible --convert-to pdf \
--outdir output \
src/budget_worksheet.xlsx
To set page printing limits in libreoffice calc:
- go to View > Page Break
- now select the area to print
- choose: Format > Print Ranges > Define
pdf:
soffice --convert-to pdf output/toc.docx \
--outdir output
merge:
$(mbin)/mergepdf output/merged.pdf \
output/title_page.pdf \
output/research_proposal.pdf \
output/assembly_plan.pdf
To add page numbers:
- put the PDF document into the
tex_utilities/addpages.texfile. - Run:
pdflatex addpages.tex - Page numbers are added at addpages.pdf!
You can refer to figures by label instead of by number, which makes reordering figures within documents easy. It also makes it possible to move figures from one document to another without renumbering.
Refer to figures with \ref{label}.
By default, pandoc will include your references cited just right at the end of the document. That works for some grants, but others want a separate reference document. To accomodate this, we need to do 2 things: 1) make a bibliography-only file; 2) suppress the bibliography in the main file.
- make a bibliography-only file
I wrote a script that does this: bin/getrefs
You can run getrefs on your markdown files, and pipe the results pandoc:
getrefs document.md | pandoc ...
However, this will also include any commented references, which is probably
not what you want. So, there's a more complicated recipe in the
mediabuilder.make Makefile called refs that will do this for you. It looks like this:
# Requires pandoc 2 with --strip-comments implemented
refs_nocomment:
pandoc --strip-comments -t markdown `$(mbin)/ver src/specific_aims` \
`$(mbin)/ver src/significance_innovation` \
`$(mbin)/ver src/aim1` `$(mbin)/ver src/aim2` `$(mbin)/ver src/aim3` | \
$(mbin)/getrefs | \
pandoc -o output/references.pdf $(PANDOC_FLAGS)
- Suppress the bibliography in the main
.mdfiles.
One way to do this is to use a csl file that doesn't have a style for a
bibliography. I don't like that, though, because it requires mucking around with
style files, and you may want to produce a document with the bibliography some
time. The better alternative is this: In the file itself, put in a yaml header:
---
suppress-bibliography: True
---
Or, I also wrote a little helper script that will do this for you on-the-fly: bin/nobib. Use it like getrefs:
$(mbin)/nobib file.md | \
pandoc \
-o output/approach.pdf \
That will suppress the bibliography in the output. Done!
docker run --rm -it --volume=pwd:/repo --volume=$HOME/code/mediabuilder:/mbdir --env TEXINPUTS=/mbdir/tex_templates: --workdir="/repo" --network="host" --entrypoint sh pandoc/latex
pandoc content.md -o content.pdf --template /mbdir/tex_templates/twocol.tex
This line will test the entire process
docker run --rm -it --volume=pwd:/repo --volume=$HOME/code/mediabuilder:/mbdir --env TEXINPUTS=/mbdir/tex_templates: --workdir="/repo" --network="host" --entrypoint pandoc databio/sciquill src/content.md -o output/content.pdf --template /mbdir/tex_templates/twocol.tex
docker run --rm -it --volume=pwd:/repo --volume=$HOME/code/mediabuilder:/mbdir --env TEXINPUTS=/mbdir/tex_templates: --workdir="/repo" --network="host" --entrypoint pandoc databio/sciquill src/*.md -o output/content.pdf --template /mbdir/tex_templates/twocol.tex
docker run --rm -it --volume=pwd:/repo --volume=$HOME/code/mediabuilder:/mbdir --env TEXINPUTS=/mbdir/tex_templates: --workdir="/repo" --network="host" --entrypoint make databio/sciquill manu
bulker load -c bulker/bulker_config.yaml databio/sciquill -f sciquill_bulker_manifest.yaml -r
in the past I just used pandoc --filter wrapfig, but this way, the pandoc image has to have python available. It works better to use a pipe so that each program can run in its own container; so now: pandoc -t json | $(wrapfig) | pandoc -f json \ This works.