Document Generator

Overview

This document is a summary of my document making process in markdown > latex > document. Designed with pop~os Linux.

This setup has been abandoned, because I don’t care enough about a perfect system. As of late, I simply use any system capable of handling my immediate challenge. It’s easier than fine-tuning these things.

Requires:

  • latex
  • pandoc

Great pandoc guide Pandoc manual

Setup/Install

Texlive or Latex

To install, run `sudo apt install -y texlive texlive-full`

NOTE: texlive-full gets stuck at 'Pregenerating ConTeXt MarkIV format'. Solved by letting it run for a while, and then pressing "Enter" a whole lot, as mentioned by one user online.

Pandoc

Make sure to install at the same version as pandoc-crossref. See here for installation (run dpkg -i on downloads page dpkg release).

Extra note: handy to remove tags in url to find packages by version.

  1. pandoc-crossref

    Make sure to install at the same version as pandoc-crossref.

    Place pandoc-crossref in `~/.local/bin/` & then restart. In `echo $PATH`, pandoc-crossref placed in ~/.local/bin will not show until restart.

Sites to go through for details:

https://alvinalexander.com/blog/post/latex/reference-figure-or-table-within-latex-document/ Nicely comprehensive: https://opensource.com/article/18/9/pandoc-research-paper https://boisgera.github.io/pandoc/markdown/ https://blog.cubieserver.de/2021/document-writing-with-markdown-and-latex/ https://allefeld.github.io/nerd-notes/Markdown/A%20writer's%20guide%20to%20Pandoc's%20Markdown.html Nice list of features: https://deatrich.github.io/doc-with-pandoc-markdown/current/doc-with-pandoc-markdown.html#fenced-code-blocks

TO SOLVE FOR EASIER DOCUMENT MAKING

[#B] alt txt font size

I suspect best option is not to use markdown approach but latex or html

[#B] MAKEFILE: Edits for handouts & regular slides?

https://gist.github.com/lmullen/c3d4c7883f081ed8692a#file-makefile

My Makefile General Guide

Start

Location for texlive documents is /usr/share/texlive when `sudo apt install texlive-full`

Declaring Documents to Use

File Types to Generate

Guide: -r input format. -s Produce output with an appropriate header and footer. -V specifics a theme already in the system. Needs –template for personal theme. -t output format. $(FILTERS) after –pdf-engine. –csl=$(CSL).csl –bibliography=$(BIB) -N –reference-doc Use with pptx templates [[[https://pandoc.org/MANUAL#option--toc\](https://pandoc.org/MANUAL#option--toc)[][–toc]] Table of Contents. Useless without the -s option

To Put Together The Finale Document

To develop

To put columns?

pandoc manual

[#C] spelling

yaml header: "spellchecker: hunspell" lua-filter=spellcheck

[#C] Figure out bib (NEEDS PANDOC-CROSSREF?)

[#A] PANDOC: crossref

[#A] PDF: Figures prefix/reference using markdown syntax (NEEDS PANDOC-CROSSREF?)

Following seems specific to document making with markdown syntax. Needs pandoc-crossref? see stackoverflow response blog post focusing on markdown syntax in a paper

1figPrefix:
2 - "Figure"
3 - "Figures"
4
5tblPrefix:
6 - "Table"
7 - "Tables"

using md syntax, add `{#fig:scatter-matrix}` to end of figure. Ref using

[#C] PDF: Controlling image location

Autostart sh

This script is run on a terminal from the directory with the files. auto runs 'make' based on changes to the directory.

 1#!/bin/bash
 2
 3# Automatically set WATCH_DIR to the directory where this script is located
 4SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
 5WATCH_DIR="${SCRIPT_DIR}" # Directory to watch for changes
 6MEXT="(md|yaml)" # Markdown file extension
 7SLEEPTIME=1 # Sleep time between checks in seconds
 8
 9# Function to compile documents
10compile_docs() {
11    echo "Detected changes. Compiling documents..."
12    make all
13    echo "Compilation finished."
14}
15
16# Function to clean generated documents
17clean_docs() {
18    echo "Cleaning up generated documents..."
19    make clean
20    echo "Cleanup finished."
21}
22
23# Initial clean and compile
24clean_docs
25compile_docs
26
27# Get the initial state of the directory
28initial_state=$(ls -lR --time-style=full-iso $WATCH_DIR | grep -E "\.$MEXT")
29
30echo "Watching for changes in $WATCH_DIR. Press [CTRL+C] to stop."
31
32# Continuous loop to check for changes
33while true; do
34    sleep $SLEEPTIME
35    current_state=$(ls -lR --time-style=full-iso $WATCH_DIR | grep -E "\.$MEXT")
36
37    # Check if anything changed
38    if [ "$initial_state" != "$current_state" ]; then
39        compile_docs
40        initial_state=$current_state
41    fi
42done

PDF

Future developments

Tuft handouts

Presentations

Makefile (Mar 26th, 2024)

This is the makefile used to generate the document.

  1## Put this Makefile in your project directory---i.e., the directory
  2## containing the paper you are writing. Assuming you are using the
  3## rest of the toolchain here, you can use it to create .html, .tex,
  4## and .pdf output files (complete with bibliography, if present) from
  5## your markdown file.
  6## -    Change the paths at the top of the file as needed.
  7## -    Using `make` without arguments will generate html, tex, and pdf
  8##  output files from all of the files with the designated markdown
  9##  extension. The default is `.md` but you can change this.
 10## -    You can specify an output format with `make tex`, `make pdf`,
 11## -    `make html`, or `make docx`.
 12## -    Doing `make clean` will remove all the .tex, .html, .pdf, and .docx files
 13##  in your working directory. Make sure you do not have files in these
 14##  formats that you want to keep!
 15
 16## IMPORTANT TODO
 17# [B] Two column slides, one with image? Adjusting width of columns
 18# [C] Figure out bib
 19# [D] What is 'submission'?
 20
 21## Later things to learn
 22# What are slide levels, ex pandoc --slide-level 2
 23# Confirm what pandoc --toc does
 24# Possible to tell markdown to exclude titles?
 25
 26OS := $(shell uname)
 27
 28## Markdown extension (e.g. md, markdown, mdown).
 29MEXT = md
 30
 31## All markdown files in the working directory
 32SRC = $(wildcard *.$(MEXT))
 33
 34## Final doc
 35# This is a document that will be generated containing the sum.
 36FINAL_DOC := final_doc.md
 37
 38## Location of Pandoc support files.
 39PREFIX = ${HOME}/.config/pandoc/
 40
 41## Location of parent bibliography
 42#LIBRARY=library.bib # TODO Will this function with this line included, as well as the below bib mentions?
 43
 44## Location of your working bibliography file
 45# Contains the citations
 46#BIB = bibexport.bib
 47
 48## CSL stylesheet (located in the csl folder of the PREFIX directory).
 49#CSL = acrf  # For styling of Bibliography # TODO are there CSL stylesheets in texlive/pandoc?
 50
 51## TEMPLATE
 52# Location for texlive documents is /usr/share/texlive when `sudo apt install texlive-full`
 53TEMPLATE    =   metropolis  # TODO where does it search for template? # NOTE Template document.
 54
 55PDFS=$(SRC:.md=.pdf)
 56TEX=$(SRC:.md=.tex)
 57PPTX=$(SRC:.md=.pptx)
 58
 59FILTERS = --filter pandoc-crossref # --filter pandoc-citeproc #--lua-filter=draftnotes # TODO any useful lua filters for presentations?
 60
 61EXTENSIONS := simple_tables+table_captions+yaml_metadata_block+smart # TODO How are these extensions installed/added?
 62
 63##############################
 64# DECLARING DOCUMENTS TO USE #
 65##############################
 66
 67SUBMISSION  =   submit/GTK-AcRF-T1-2018.pdf  # TODO Where to save the file?
 68
 69PDFENGINE=pdflatex
 70
 71# NOTE When Available, add to line below:
 72# bibexport.bib $(TEMPLATE).latex $(CSL).csl
 73#final_presentation.pdf:    final_presentation.md presentation.md Makefile  # NOTE Files to generate .pdf # TODO Why is Makefile listed here?
 74
 75all:    $(PDFS) $(TEX) $(PPTX)
 76
 77pdf:    clean $(PDFS)
 78tex:    clean $(TEX)
 79pptx:   clean $(PPTX)
 80
 81# GUIDE:
 82# See FINAL_DOC variable above
 83# NOTE Change this to arrange order of documents.
 84# Used to be grant.md.
 85$(FINAL_DOC):   00-metadata.yaml \
 86	01-presentation.md
 87	cat $^ >| $@
 88
 89##########################
 90# FILE TYPES TO GENERATE #
 91##########################
 92# Guide:
 93# -r input format.
 94# -s enables titles?
 95# -V specifics a theme already in the system. Needs --template for personal theme.
 96# -t output format.
 97# $(FILTERS) after --pdf-engine.
 98# --csl=$(CSL).csl
 99# --bibliography=$(BIB)
100# -N
101# --reference-doc Use with pptx templates
102
103%.pdf:  $(FINAL_DOC)
104    pandoc -r markdown+$(EXTENSIONS) -t beamer \
105    -s --pdf-engine=$(PDFENGINE) \
106    $(FILTERS)  \
107    -V theme:$(TEMPLATE) \
108    -o $@ $
109
110%.tex:  $(FINAL_DOC)
111    pandoc -r markdown+$(EXTENSIONS) \
112    -s --pdf-engine=$(PDFENGINE) \
113    $(FILTERS)  \
114    -V theme:$(TEMPLATE) \
115    -o $@ $
116
117# TODO Add  $(FILTERS)  \ to pptx?
118%.pptx: $(FINAL_DOC)
119    pandoc -r markdown+$(EXTENSIONS) -s -t pptx \
120    -o $@ $
121    
122clean:
123    rm -f *.pdf *.tex *.pptx\
124
125
126#########################################
127# # TO PUT TOGETHER THE FINALE DOCUMENT #
128#########################################
129# Guide:
130# This segment will combine parts from multiple documents
131# In this setup, it takes the $(GRANT_SHELL) page 1-8, places grant.pdf first 11 pages for 9-19, and back to $(GRANT_SHELL) for 20 onwards.
132# TODO figure out this section
133# $(SUBMISSION): final_presentation.pdf
134#   pdfjam --a4paper $< \
135#        --outfile $@

How To

Notes

stack overflow

Use either \note{}{=latex} or ::: note :::

Figures (LATEX)

Font size follows that in here

1header-includes:
2    - \usepackage[font={footnotesize},labelfont=bf]{caption}
1\begin{figure}
2    \includegraphics[width=0.5\textwidth,height=\textheight]{./images/EnvelopedmRNA.png}
3    \caption{something here}
4\end{figure}

Figures (MARKDOWN)

Haven't confirmed whether `#fig` works in this context

1![alt_text](./image.pnd){ width=50% style="center" #fig:figurelabel }