From aa5c95912010f76445e547938059624eddb339d1 Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Wed, 26 Apr 2017 12:34:29 +0100 Subject: [PATCH 1/9] Add installation instructions --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index bf87661..d13f7a6 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,18 @@ Convert markdown files into PDF Documents. __Note__: All features are completely optional +### Installation +This library isn't on Pypi, but can still be installed using pip: + + pip install https://github.com/RealOrangeOne/md-pdf + +Additionally, you will need the following programs: +- `wkhtmltopdf` (With QT - [See Here](https://pypi.python.org/pypi/pdfkit)) +- `pandoc` +- `pandoc-siteproc` + +These packages should be available on most linux distributions, OSX and Windows support is untested! + ### Usage $ mdp --help usage: mdp [-h] [-v] [--update-csl] From c15e24a4e744ba43208b9f4f4f4af1f4774ad989 Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Wed, 26 Apr 2017 13:24:08 +0100 Subject: [PATCH 2/9] Move documentation into directory --- README.md | 13 ++----------- docs/installation.md | 0 docs/referencing.md | 1 + 3 files changed, 3 insertions(+), 11 deletions(-) create mode 100644 docs/installation.md create mode 100644 docs/referencing.md diff --git a/README.md b/README.md index d13f7a6..eb95f74 100644 --- a/README.md +++ b/README.md @@ -16,17 +16,8 @@ Convert markdown files into PDF Documents. __Note__: All features are completely optional -### Installation -This library isn't on Pypi, but can still be installed using pip: - - pip install https://github.com/RealOrangeOne/md-pdf - -Additionally, you will need the following programs: -- `wkhtmltopdf` (With QT - [See Here](https://pypi.python.org/pypi/pdfkit)) -- `pandoc` -- `pandoc-siteproc` - -These packages should be available on most linux distributions, OSX and Windows support is untested! +### Documentation +Documentation can be found in the `docs/` directory. ### Usage $ mdp --help diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/referencing.md b/docs/referencing.md new file mode 100644 index 0000000..81b6887 --- /dev/null +++ b/docs/referencing.md @@ -0,0 +1 @@ +# Referencing From c6fd6e2854e9dc388e2305d3bf3066649644494c Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Wed, 26 Apr 2017 14:21:46 +0100 Subject: [PATCH 3/9] Add installation documentation --- docs/installation.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index e69de29..3effefd 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -0,0 +1,34 @@ +# Installation + +### Installing dependencies +These applications will not be installed with `md-pdf`, so need to be installed through your OS's package manager. +- `pandoc` +- `pandoc-citeproc` +- `wkhtmltopdf` (With QT - [See Here](https://pypi.python.org/pypi/pdfkit)) + + +#### Arch Linux + yaourt -S pandoc pandoc-citeproc wkhtmltopdf-static + +#### Ubuntu + sudo apt install pandoc pandoc-citeproc + +To install the correct version of `wkhtmltopdf`, you will need to build it yourself using [this script](https://github.com/JazzCore/python-pdfkit/blob/master/travis/before-script.sh). + +#### Windows +__Note__: Windows is an untested platform, these installation instructions are only theoretical! + +Pandoc (and `pandoc-citeproc`) can be installed using the installer found [here](https://github.com/jgm/pandoc/releases/). + +`wkhtmltopdf` can be installed from the [official website](https://wkhtmltopdf.org/downloads.html). + + +### Installing `md-pdf`. +This application isn't available through Pypi directly, but can still be installed using pip. + + pip install https://github.com/RealOrangeOne/md-pdf + +This should install the rest of the dependencies. To check it installed correctly, you can run this: + + mdp --help +If you see the help information, it's installed correctly. If not, please submit an [issue](https://github.com/RealOrangeOne/md-pdf). From b32a39904a9c4b20f7f37c4e36297852dcd6ad2c Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Wed, 26 Apr 2017 22:09:27 +0100 Subject: [PATCH 4/9] Add usage documentation --- docs/usage.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/usage.md diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..2702acb --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,25 @@ +# Usage + $ mdp --help + usage: mdp [-h] [-v] [--update-csl] + + optional arguments: + -h, --help show this help message and exit + -v, --verbose Set verbosity level (repeat argument) + --update-csl Update CSL files + +## Running the application +Assuming you're in a directory with a valid `mdp.yml` file, simply run `mdp` to build your files to the output directory! + +## Downloading CSL Files +In order to use referencing properly, `csl` files need to be downloaded. These tell `md-pdf` what style of referencing you're using, and how to output the bibliography. + +To download these, simply run: + + mdp --update-csl + +This will download the `csl` files into the install directory of the application. It only needs to be run once, however can be run whenever to update the definitions from [here](https://github.com/citation-style-language/styles/). + +## Verbosity +By default, when building, the application doesn't output anything to the console. It simply runs, and terminates when it's finished. Obviously errors are still reported. + +To increase the verbosity level, simply add the `-v` argument when running the application. This can be chained a maximum of 3 times (`-vvv`), subsequent repetition will be ignored. From 886877880753ae8781e7740fff7ed142e978a353 Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Thu, 27 Apr 2017 19:53:30 +0100 Subject: [PATCH 5/9] Add more advanced example files --- test-files/1intro.md | 5 +++++ test-files/2-pandoc.md | 23 +++++++++++++++++++++++ test-files/bib.yaml | 40 ++++++++++++++++++++++++++++++++++++++++ test-files/end.md | 3 +++ test-files/test.md | 1 - 5 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 test-files/1intro.md create mode 100644 test-files/2-pandoc.md create mode 100644 test-files/end.md delete mode 100644 test-files/test.md diff --git a/test-files/1intro.md b/test-files/1intro.md new file mode 100644 index 0000000..d26cb43 --- /dev/null +++ b/test-files/1intro.md @@ -0,0 +1,5 @@ +# Test content + +_Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ante purus, scelerisque sed pulvinar eget, suscipit feugiat augue. Cras quis quam ac dui aliquam rhoncus eu id diam. Cras dapibus vel nunc in finibus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Nulla a lacinia nibh. Aenean finibus mauris et est euismod aliquam. Curabitur dictum nulla quis turpis fringilla vestibulum at eget ligula. Donec et ultricies massa, ut volutpat neque. Praesent elementum ultrices urna at finibus. Nunc risus mi, porta sed eros sit amet, sagittis sollicitudin velit. Nulla a felis in tellus gravida pretium sit amet eget libero. Donec aliquet ac est semper molestie._ + +__Curabitur arcu velit, faucibus sed condimentum vitae, consectetur a lectus. Fusce a cursus magna. Nam vel posuere erat, in congue purus. Aliquam aliquet eu leo vel cursus. Vestibulum mattis est ac diam finibus, in aliquet erat iaculis. Phasellus est quam, rutrum a tempus non, vehicula vitae tellus. Nam nec leo consectetur, aliquam lorem eget, dignissim arcu. Phasellus vitae convallis urna, ac aliquet purus. Vivamus nisl mauris, volutpat quis pretium non, fringilla non dui. Pellentesque velit justo, pretium a porta nec, varius ac lacus.__ diff --git a/test-files/2-pandoc.md b/test-files/2-pandoc.md new file mode 100644 index 0000000..08d5e36 --- /dev/null +++ b/test-files/2-pandoc.md @@ -0,0 +1,23 @@ + + +- [@nonexistent] + +- @nonexistent + +- @item1 says blah. + +- @item1 [p. 30] says blah. + +- @item1 [p. 30, with suffix] says blah. + +- @item1 [-@item2 p. 30; see also @item3] says blah. + +- A citation group [see @item1 p. 34-35; also @item3 chap. 3]. + +- Another one [see @item1 p. 34-35]. + +- Citation with a suffix and locator [@item1 pp. 33, 35-37, and nowhere else]. + +- Citation with suffix only [@item1 and nowhere else]. + +- With some markup [*see* @item1 p. **32**]. diff --git a/test-files/bib.yaml b/test-files/bib.yaml index e69de29..99eac3c 100644 --- a/test-files/bib.yaml +++ b/test-files/bib.yaml @@ -0,0 +1,40 @@ +references: +- id: item1 + type: book + author: + - family: Doe + given: John + issued: + - year: '2005' + title: First book + publisher: Cambridge University Press + publisher-place: Cambridge + +- id: item2 + type: article-journal + author: + - family: Doe + given: John + issued: + - year: '2006' + title: Article + container-title: Journal of Generic Studies + page: '33-34' + volume: '6' + +- id: item3 + type: chapter + author: + - family: Doe + given: John + - family: Roe + given: Jenny + editor: + - family: Smith + given: Sam + issued: + - year: '2007' + title: Why water is wet + container-title: Third book + publisher: Oxford University Press + publisher-place: Oxford diff --git a/test-files/end.md b/test-files/end.md new file mode 100644 index 0000000..fcb505f --- /dev/null +++ b/test-files/end.md @@ -0,0 +1,3 @@ +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus accumsan justo nisi, eget eleifend eros blandit sit amet. Mauris ligula neque, posuere a fringilla quis, pharetra ac nisi. Duis lacus dui, sodales sit amet semper sit amet, euismod ut erat. Donec faucibus, nisi eget condimentum rutrum, tellus orci rhoncus ante, sed laoreet odio ex eu mi. In sem neque, ultrices et laoreet at, vestibulum non justo. Vestibulum tempus pulvinar vulputate. Vestibulum tellus nunc, pellentesque eget dolor eu, porta molestie nunc. Pellentesque at feugiat nisl. Aenean bibendum, lorem ut vehicula laoreet, ante eros sollicitudin augue, vitae volutpat diam augue a purus. Sed fermentum et enim quis elementum. Proin commodo, erat a egestas ultrices, ipsum tellus finibus neque, non aliquam nulla urna non magna. Nulla facilisi. Vivamus in lacinia neque. Aenean gravida elit ipsum, ac rutrum ligula vehicula a. + +Ut imperdiet sit amet sem egestas iaculis. Aliquam sit amet posuere ante, eget iaculis turpis. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Phasellus maximus lacinia malesuada. Nullam ullamcorper rhoncus massa, a eleifend enim malesuada ullamcorper. Sed sed consequat nibh. Vestibulum fringilla dignissim nulla, nec viverra felis elementum et. Cras tristique posuere luctus. Mauris dapibus pellentesque volutpat. In porttitor placerat felis, non ultrices mi elementum eget. Aenean id lectus egestas, imperdiet dolor ut, varius ante. Mauris vulputate congue lectus, vel tempus nisl volutpat et. Duis dapibus mauris vel aliquet porttitor. Mauris nec risus tempus, pharetra lectus sit amet, molestie ex. Vivamus dapibus mi quis porttitor fermentum. Maecenas imperdiet metus at mi varius pretium. diff --git a/test-files/test.md b/test-files/test.md deleted file mode 100644 index 043968d..0000000 --- a/test-files/test.md +++ /dev/null @@ -1 +0,0 @@ -# Test content From 86fc080dba286f7823d717f4529c631e6fefe4a0 Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Thu, 27 Apr 2017 20:25:09 +0100 Subject: [PATCH 6/9] Add referencing instructions --- docs/referencing.md | 32 ++++++++++++++++++++++++++++++++ test-files/mdp.yml | 2 +- 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/referencing.md b/docs/referencing.md index 81b6887..a085f56 100644 --- a/docs/referencing.md +++ b/docs/referencing.md @@ -1 +1,33 @@ # Referencing + +Referencing is powered by `pandoc-citeproc`, so any format supported by it is supported. A list of supported formats can be found [here](https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md). + +__Remember__: To use YAML, your file must end `.yaml` rather than `.yml`! + +## CSL Files +There are many different ways of referencing, both inline, and in a bibliography. `md-pdf` supports _all_ of them. + +The configuration used for this is stored in `csl` files, which can be downloaded through `md-pdf`. See the usage instructions on how to download these. + +There's a full list of available `csl` files [here](https://github.com/citation-style-language/styles/). + +## Example +Assuming youre using the same bibliography as the example, an input of: + +```markdown +@item1 says blah. +``` +Will render as: +``` +Doe (2005) says blah. +``` + +### Advanced Citation +You can also use more advanced referencing to be more specific: +```markdown +A citation group [see @item1 p. 34-35; also @item3 chap. 3]. +``` +will result in: +``` +A citation group (see Doe 2005, 34–35; also Doe and Roe 2007, chap. 3) +``` diff --git a/test-files/mdp.yml b/test-files/mdp.yml index 9f1ad47..411e971 100644 --- a/test-files/mdp.yml +++ b/test-files/mdp.yml @@ -5,7 +5,7 @@ output_formats: output_dir: out/ bibliography: references: bib.yaml - csl: apa + csl: chicago-author-date context: foo: bar bar: foo From 1ba275cee1299d81230ff5afbc24587fff8bb00b Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Thu, 27 Apr 2017 20:31:01 +0100 Subject: [PATCH 7/9] Write documentation about output directory --- docs/output.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/output.md diff --git a/docs/output.md b/docs/output.md new file mode 100644 index 0000000..be85430 --- /dev/null +++ b/docs/output.md @@ -0,0 +1,9 @@ +# Output + +Rather than outputting a single file, `md-pdf` outputs to a directory, allowing multiple different output formats. + +### Supported formats +- HTML +- PDF + +The output files will be named `output` with their formats default extension (eg `output.html`) From 7d76b413ead8cf811013a17bb8899aa89a635612 Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Wed, 3 May 2017 15:19:43 +0100 Subject: [PATCH 8/9] Fix example bibliography format --- test-files/bib.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/test-files/bib.yaml b/test-files/bib.yaml index 99eac3c..5ca622d 100644 --- a/test-files/bib.yaml +++ b/test-files/bib.yaml @@ -1,3 +1,4 @@ +--- references: - id: item1 type: book @@ -38,3 +39,4 @@ references: container-title: Third book publisher: Oxford University Press publisher-place: Oxford +... From a6931517ac4d446e262204c58b28c7ecb62ea9ec Mon Sep 17 00:00:00 2001 From: Jake Howard Date: Wed, 10 May 2017 20:09:10 +0100 Subject: [PATCH 9/9] Added markdown documentation --- docs/markdown.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 docs/markdown.md diff --git a/docs/markdown.md b/docs/markdown.md new file mode 100644 index 0000000..46d456d --- /dev/null +++ b/docs/markdown.md @@ -0,0 +1,14 @@ +# Markdown + +Whilst `md-pdf` theoretically supports all formats pandoc does, it's only been tested and and validated to support markdown. + +Information about markdown as a format can be found [here](http://daringfireball.net/projects/markdown/). The standard format and syntax is used, however there are some additional features to improve the output format. + +### Images +Images take the same syntax as with standard markdown: + + ![title](url) + +Referencing files inside your project directory can be done with a path relative to the project directory. You can use images direct from online, however you'll need to be connected to the internet when generating. + +The title for the image is also used as the caption, and is displayed directly under the images.