1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
Contributing to pandoc
======================
Found a bug?
------------
Bug reports are welcome! Please report all bugs on pandoc's github
[issue tracker].
Before you submit a bug report, search the (open *and* closed) issues to make
sure the issue hasn't come up before. Also, check the [User's Guide] and [FAQs]
for anything relevant.
Make sure you can reproduce the bug with the latest released version of pandoc
(or, even better, the development version).
Your report should give detailed instructions for how to reproduce the problem,
including
* the exact command line used
* the exact input used
* the output received
* the output you expected instead
A small test case (just a few lines) is ideal. If your input is large,
try to whittle it down to the minimum necessary to illustrate the problem.
Out of scope?
-------------
A less than perfect conversion does not necessarily mean there's
a bug in pandoc. Quoting from the README:
> Because Pandoc's intermediate representation of a document is less
> expressive than many of the formats it converts between, one should
> not expect perfect conversions between every format and every other.
> Pandoc attempts to preserve the structural elements of a document, but
> not formatting details such as margin size. And some document elements,
> such as complex tables, may not fit into Pandoc's simple document
> model. While conversions from Pandoc's Markdown to all formats aspire
> to be perfect, conversions from formats more expressive than Pandoc's
> Markdown can be expected to be lossy.
For example, both docx and odt can represent margin size, but because
pandoc's internal document model does not contain a representation of
margin size, this information will be lost on converting from docx
to odt. (You can, however, customize margin size using `--reference-odt`.)
So before submitting a bug report, consider whether it might be
"out of scope." If it concerns a feature of documents that isn't
representable in pandoc's Markdown, then it very likely is.
(If in doubt, you can always ask on pandoc-discuss.)
Fixing bugs from the issue tracker
----------------------------------
Almost all the bugs on the issue tracker have one or more associated
tags. These are used to indicate the *difficulty* and *nature* of a
bug. There is not yet a way to indicate priority. An up to date
summary of issues can be found [here](https://github.com/jgm/pandoc/labels).
* [enhancement] -- A feature which would be desirable. We recommend
you discuss any proposed enhancement on pandoc-discuss before
writing code.
* [bug] -- A problem which needs to be fixed.
* [minor] -- The fix should only be a couple of lines.
* [major] -- The fix might require structural changes or in depth knowledge of
the code base.
* [reader] -- A request to add a new input format.
* [writer] -- A request to add a new output format.
* [docs] -- A discrepency or ambiguity in the documentation.
* [inprogress] -- Someone is actively working on or planning to work on the
ticket.
* [more discussion needed] -- It is unclear what the correct approach
to solving the ticket is. Before starting on tickets such as this it
would be advisable to post on the ticket.
* [more info needed] -- We require more information from a user before
we can classify a report properly.
Have an idea for a new feature?
-------------------------------
First, search [pandoc-discuss] and the issue tracker (both open and closed
issues) to make sure that the idea has not been discussed before.
Explain the rationale for the feature you're requesting. Why would this
feature be useful? Consider also any possible drawbacks, including backwards
compatibility, new library dependencies, and performance issues.
It is best to discuss a potential new feature on [pandoc-discuss]
before opening an issue.
Patches and pull requests
-------------------------
Patches and pull requests are welcome. Before you put time into a nontrivial
patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
for a new feature (rather than fixing a bug).
Please follow these guidelines:
1. Each patch (commit) should make a single logical change (fix a bug, add
a feature, clean up some code, add documentation). Everything
related to that change should be included (including tests and
documentation), and nothing unrelated should be included.
2. The first line of the commit message should be a short description
of the whole commit (ideally <= 50 characters). Then there should
be a blank line, followed by a more detailed description of the
change.
3. Follow the stylistic conventions you find in the existing
pandoc code. Use spaces, not tabs, and wrap code to 80 columns.
Always include type signatures for top-level functions.
Consider installing [EditorConfig], this will help you to follow the
coding style prevalent in pandoc.
4. Your code should compile without warnings (`-Wall` clean).
5. Run the tests to make sure your code does not introduce new bugs.
(See below under [Tests](#tests).) All tests should pass.
6. It is a good idea to add test cases for the bug you are fixing. (See
below under [Tests](#tests).) If you are adding a new writer or reader,
you must include tests.
7. If you are adding a new feature, include updates to the README.
8. All code must be released under the general license governing pandoc
(GPL v2).
9. It is better not to introduce new dependencies. Dependencies on
external C libraries should especially be avoided.
10. We aim for compatibility with ghc versions from 7.4.2 to the
latest release. All pull requests and commits are tested
automatically on travis-ci.org, using GHC versions in the
`Tested-With` stanza of `pandoc.cabal`. We currently relax
the "`-Wall` clean" requirement for GHC 7.10.x, because
there are so many warnings relating to the addition of type
classes to the Prelude.
Tests
-----
Tests can be run as follows:
cabal configure --enable-tests
cabal build
cabal test
The test program is `tests/test-pandoc.hs`.
Benchmarks can be enabled by passing the `--enable-benchmarks` flag
to `cabal configure`, and run using `cabal bench`.
Using the REPL
--------------
With a recent version of cabal, you can do `cabal repl` and get
a ghci REPL for working with pandoc. We recommend using the following
`.ghci` file (which can be placed in the source directory):
```
:set -fobject-code
:set -XTypeSynonymInstances
:set -XScopedTypeVariables
:set -XOverloadedStrings
```
The code
--------
Pandoc has a publicly accessible git repository on
github: <http://github.com/jgm/pandoc>. To get a local copy of the source:
git clone git://github.com/jgm/pandoc.git
Note: after cloning the repository (and in the future after pulling from it),
you should do
git submodule update --init
to pull in changes to the templates (`data/templates/`). You can automate this
by creating a file `.git/hooks/post-merge` with the contents:
#!/bin/sh
git submodule update --init
and making it executable:
chmod +x .git/hooks/post-merge
The source for the main pandoc program is `pandoc.hs`. The source for
the pandoc library is in `src/`, the source for the tests is in
`tests/`, and the source for the benchmarks is in `benchmark/`.
The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
`Text.Pandoc.Generic` are in a separate library `pandoc-types`. The code can
be found in a <http://github.com/jgm/pandoc-types>.
To build pandoc, you will need a working installation of the
[Haskell platform].
The library is structured as follows:
- `Text.Pandoc` is a top-level module that exports what is needed
by most users of the library. Any patches that add new readers
or writers will need to make changes here, too.
- `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
used for representing a pandoc document.
- `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
building pandoc documents programatically.
- `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
you to promote functions that operate on parts of pandoc documents
to functions that operate on whole pandoc documents, walking the
tree automatically.
- `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
are the writers.
- `Text.Pandoc.Biblio` is a utility module for formatting citations
using citeproc-hs.
- `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
cabal flag is used. It is generated from `src/Text/Pandoc/Data.hsb` using
the preprocessor [hsb2hs].
- `Text.Pandoc.Highlighting` contains the interface to the
highlighting-kate library, which is used for code syntax highlighting.
- `Text.Pandoc.ImageSize` is a utility module containing functions for
calculating image sizes from the contents of image files.
- `Text.Pandoc.MIME` contains functions for associating MIME types
with extensions.
- `Text.Pandoc.Options` defines reader and writer options.
- `Text.Pandoc.PDF` contains functions for producing a PDF from a
LaTeX source.
- `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
- `Text.Pandoc.Pretty` is a pretty-printing library specialized to
the needs of pandoc.
- `Text.Pandoc.SelfContained` contains functions for making an HTML
file "self-contained," by importing remotely linked images, CSS,
and javascript and turning them into `data:` URLs.
- `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
- `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
- `Text.Pandoc.Slides` contains functions for splitting a markdown document
into slides, using the conventions described in the README.
- `Text.Pandoc.Templates` defines pandoc's templating system.
- `Text.Pandoc.UTF8` contains functions for converting text to and from
UTF8 bytestrings (strict and lazy).
- `Text.Pandoc.Asciify` contains functions to derive ascii versions of
identifiers that use accented characters.
- `Text.Pandoc.UUID` contains functions for generating UUIDs.
- `Text.Pandoc.XML` contains functions for formatting XML.
[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
[issue tracker]: https://github.com/jgm/pandoc/issues
[User's Guide]: http://pandoc.org/README.html
[FAQs]: http://pandoc.org/faqs.html
[EditorConfig]: http://editorconfig.org/
[Haskell platform]: http://www.haskell.org/platform/
[hsb2hs]: http://hackage.haskell.org/package/hsb2hs
[enhancement]: https://github.com/jgm/pandoc/labels/enhancement
[bug]: https://github.com/jgm/pandoc/labels/bug
[minor]: https://github.com/jgm/pandoc/labels/Minor
[major]: https://github.com/jgm/pandoc/labels/Major
[reader]: https://github.com/jgm/pandoc/labels/Reader
[writer]: https://github.com/jgm/pandoc/labels/Writer
[docs]: https://github.com/jgm/pandoc/labels/docs
[inprogress]: https://github.com/jgm/pandoc/labels/inprogress
[more discussion needed]: https://github.com/jgm/pandoc/labels/More%20discussion%20needed
[more info needed]: https://github.com/jgm/pandoc/labels/More%20info%20needed
|
