Clean up MarkDown

[silverhook]

• initial change from (thanks to @dmgerman)
• include @kappapiana’s patches
• clean up MarkDown syntax
• recreate metadata
• fix footnotes
• fix links to authors
• fix internal references (although I suspect those could be scripted or salvaged through Pandoc)
• clean up the repo of old files (rm *.txt *.xml)
• generate PDF and ePub
• figure out which character is missing from the standard font and either replace the font or the character – I suspect it is one of the quotation marks or apostrophes
• check if all looks well (including ToC)

[silverhook]

At LLW I spoke with @martinsramek and he was enthusiastic to help out here as well. I’m optimistic that together we can actually push this forward in a reasonable time.

[silverhook]

Currently I am working on the pandoc-clean-up branch. I suggest we use that as the fix branch for the basic clean-up and push from there to dev (see #3)

[silverhook]

I managed to fix the footnotes, but how to fix the links to authors needs some more thoughts.

The ePubs also seem to be functional now, but need some more work to be prettier.

[silverhook]

Authors subtask could be fixable with using https://github.com/alpianon/include-pandoc

It might make sense to split up the Authors into separate per-author files, in order to have an author included also when generating per-chapter files:

• split authors into per-author markdown files
• change the authors chapter to !include all per-author markdown files
• for per-chapter files, we could simply manually include the per-author markdown files at build time in Makefile – e.g. pandoc -o Italy.pdf Italy.markdown Carlo_Piana.markdown

[silverhook]

Links to authors and Internal (cross-file) references could be done with https://lierdakil.github.io/pandoc-crossref/

[martinsramek]

include-pandoc is a good choice for including the authors biographies from separate files.

However, include-pandoc does not seem to recognise the alternative heading syntax:
============== for Heading 1 and ------------------ for Heading 2

@alpianon, is this true or should I have done something differently? Do I need to simply rewrite the heading syntax in the individual files to # Heading 1 and ## Heading 2 or is there a "smarter" solution?

[silverhook]

I think changing the headings to # instead would make sense regardless, as they are much easier to manipulate and tell which level they are.

[kappapiana]

I agree. The # notation has the clear advantage of having a one-liner for containing the heading.

But no, my version would recognize it. Can you share an example?

[martinsramek]

@kappapiana Yes. include-pandoc --number-sections --latex-engine=xelatex src/*markdown -o TEST1.pdf gives the attached output.
TEST1.pdf

EDIT: Actually, I just realized the issue might be a bit more complicated (and also that giving you the output file without the input is not at all helpful). It might not be (just) the heading syntax. include-pandoc seems to concatenate the markdown files differently than pandoc. It seems the first few lines of the files are not included. I'll have to test it out a bit more.

[kappapiana]

Hi, didn't mention that Alberto has ported all filters to Lua and they are now blazingly fast. https://github.com/alpianon in branch dev-legal
I have a script that works for Debian in https://github.com/kappapiana/script/blob/master/create_toolchain.sh (so you have all dependencies laid down in one place anyway)

[silverhook]

• fix internal references (although I suspect those could be scripted or salvaged through Pandoc)
• figure out which character is missing from the standard font and either replace the font or the character – I suspect it is one of the quotation marks or apostrophes

On call with @martinsramek we think this is done now, but if anyone finds anything not working, please open a new issue.

[martinsramek]

The PDF version is almost ready. Just need to resolve following issues:

• Make odd and even pages look the same
• Remove the chapter reference from the bios
• Add ToC
• Add cover

[silverhook]

Re ToC and metadata, there is a way to add it in YAML format at the top of a file Pandoc is parsing.

Perhaps we could use this in e.g. 00-metadata.markdown and add all the metadata and LaTeX options there.

This is e.g. a YAML (template) I use in my own documents:

---
title: 
author: Matija Šuklje
date: 
geometry: "left=3cm,right=3cm,top=2cm,bottom=2cm"
toc: true
toc-depth: 3
colorlinks: true
output: pdf_document
---

Relevant parts of Pandoc manual:
https://pandoc.org/MANUAL.html#variables-for-latex
https://pandoc.org/MANUAL.html#metadata-variables
https://pandoc.org/MANUAL.html#extension-yaml_metadata_block

[silverhook]

I could play a bit with those, but I assume this should be a good start:

---
title: International Free & Open Source Law Book
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
description: |
    As legal systems differ throughout the world there are significant differences in how Free and Open Source Software licenses are treated in different countries, and it can be difficult to obtain reliable information on national interpretations. The International Free and Open Source Software Law Book engages with this by providing a clear yet thorough analysis of Free and Open Source legal matters written and maintained by local experts.
    
    The publication is targeted towards lawyers, jurists and academics, and positioned as an international bench mark reference work. It provides an introduction to software protection, a general analysis of FOSS under local legislation and an overview of local FOSS cases (if any) for each country covered.
    
    The 2nd Edition of the book features both new and updated chapters to ensure professionals remain abreast of the latest developments and market growth of Open Source.
keywords: [nothing, nothingness]
toc: true
colorlinks: true
documentclass: book
classoption: oneside
output: pdf_document
---

[martinsramek]

Adding a cover with latex seems a bit tricky. I have not been yet able to find a working solution. There is always the brute force method of merging two PDFs (one with the cover image and one with the document) but then the numbering doesn't match.

But apart from the missing cover the PDF should be in its final form.

[silverhook]

Just found this. Might be of help: https://pandoc.org/epub.html

[silverhook]

Fixed in #10 🎉 🍾