7Bug reports are welcome! Please report all bugs on pandoc's github
10Before you submit a bug report, search the (open *and* closed) issues to make
11sure the issue hasn't come up before. Also, check the [User's Guide] and [FAQs]
14Make sure you can reproduce the bug with the latest released version of pandoc
15(or, even better, the development version).
17Your report should give detailed, *reproducible* instructions, including
19 * the pandoc version (check using `pandoc -v`)
20 * the exact command line used
21 * the exact input used
23 * the output you expected instead
25A small test case (just a few lines) is ideal. If your input is large,
26try to whittle it down to a *minimum working example*.
31A less than perfect conversion does not necessarily mean there's
32a bug in pandoc. Quoting from the MANUAL:
34> Because Pandoc's intermediate representation of a document is less
35> expressive than many of the formats it converts between, one should
36> not expect perfect conversions between every format and every other.
37> Pandoc attempts to preserve the structural elements of a document, but
38> not formatting details such as margin size. And some document elements,
39> such as complex tables, may not fit into Pandoc's simple document
40> model. While conversions from Pandoc's Markdown to all formats aspire
41> to be perfect, conversions from formats more expressive than Pandoc's
42> Markdown can be expected to be lossy.
44For example, both docx and odt can represent margin size, but because
45pandoc's internal document model does not contain a representation of
46margin size, this information will be lost on converting from docx
47to odt. (You can, however, customize margin size using `--reference-odt`.)
49So before submitting a bug report, consider whether it might be
50"out of scope." If it concerns a feature of documents that isn't
51representable in pandoc's Markdown, then it very likely is.
52(If in doubt, you can always ask on pandoc-discuss.)
54Fixing bugs from the issue tracker
55----------------------------------
57Almost all the bugs on the issue tracker have one or more associated
58tags. These are used to indicate the *complexity* and *nature* of a
59bug. There is not yet a way to indicate priority. An up to date
60summary of issues can be found [here](https://github.com/jgm/pandoc/labels).
62* [beginner-friendly] — The perfect starting point for new contributors. The
63 issue is generic and can be resolved without deep knowledge of the code
65* [enhancement] — A feature which would be desirable. We recommend
66 you discuss any proposed enhancement on pandoc-discuss before
68* [bug] — A problem which needs to be fixed.
69* [complexity:low] — The fix should only be a couple of lines.
70* [complexity:high] — The fix might require structural changes or in depth
71 knowledge of the code base.
72* [new:reader] — A request to add a new input format.
73* [new:writer] — A request to add a new output format.
74* [docs] — A discrepency, or ambiguity in the documentation.
75* [status:in-progress] — Someone is actively working on or planning to work on the
77* [status:more-discussion-needed] — It is unclear what the correct approach
78 to solving the ticket is. Before starting on tickets such as this it
79 would be advisable to post on the ticket.
80* [status:more-info-needed] — We require more information from a user before
81 we can classify a report properly.
83Issues related to a specific format are tagged accordingly, e.g. feature request
84or bug reports related to Markdown are labelled with [format:markdown].
86Have an idea for a new feature?
87-------------------------------
89First, search [pandoc-discuss] and the issue tracker (both open and closed
90issues) to make sure that the idea has not been discussed before.
92Explain the rationale for the feature you're requesting. Why would this
93feature be useful? Consider also any possible drawbacks, including backwards
94compatibility, new library dependencies, and performance issues.
96It is best to discuss a potential new feature on [pandoc-discuss]
97before opening an issue.
99Patches and pull requests
100-------------------------
102Patches and pull requests are welcome. Before you put time into a nontrivial
103patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
104for a new feature (rather than fixing a bug).
106Please follow these guidelines:
1081. Each patch (commit) should make a single logical change (fix a bug, add
109 a feature, clean up some code, add documentation). Everything
110 related to that change should be included (including tests and
111 documentation), and nothing unrelated should be included.
1132. The first line of the commit message should be a short description
114 of the whole commit (ideally <= 50 characters). Then there should
115 be a blank line, followed by a more detailed description of the
1183. Follow the stylistic conventions you find in the existing
119 pandoc code. Use spaces, not tabs, and wrap code to 80 columns.
120 Always include type signatures for top-level functions.
121 Consider installing [EditorConfig], this will help you to follow the
122 coding style prevalent in pandoc.
1244. Your code should compile without warnings (`-Wall` clean).
1265. Run the tests to make sure your code does not introduce new bugs.
127 (See below under [Tests](#tests).) All tests should pass.
1296. It is a good idea to add test cases for the bug you are fixing. (See
130 below under [Tests](#tests).) If you are adding a new writer or reader,
131 you must include tests.
1337. If you are adding a new feature, include updates to MANUAL.txt.
1358. All code must be released under the general license governing pandoc
1389. It is better not to introduce new dependencies. Dependencies on
139 external C libraries should especially be avoided.
14110. We aim for compatibility with ghc versions from 7.8.3 to the
142 latest release. All pull requests and commits are tested
143 automatically on travis-ci.org, using GHC versions in the
144 `Tested-With` stanza of `pandoc.cabal`. We currently relax
145 the "`-Wall` clean" requirement for GHC 7.10.x, because
146 there are so many warnings relating to the addition of type
147 classes to the Prelude.
152Tests can be run as follows:
154 cabal install --only-dependencies --enable-tests
155 cabal configure --enable-tests
159or, if you're using [stack],
164The test program is `tests/test-pandoc.hs`.
169To run benchmarks with cabal:
171 cabal configure --enable-benchmarks
182With a recent version of cabal, you can do `cabal repl` and get
183a ghci REPL for working with pandoc. With [stack], use
186We recommend using the following `.ghci` file (which can be
187placed in the source directory):
191:set -XTypeSynonymInstances
192:set -XScopedTypeVariables
193:set -XOverloadedStrings
199Pandoc has a publicly accessible git repository on
200github: <http://github.com/jgm/pandoc>. To get a local copy of the source:
202 git clone git://github.com/jgm/pandoc.git
204Note: after cloning the repository (and in the future after pulling from it),
207 git submodule update --init
209to pull in changes to the templates (`data/templates/`). You can automate this
210by creating a file `.git/hooks/post-merge` with the contents:
213 git submodule update --init
215and making it executable:
217 chmod +x .git/hooks/post-merge
219The source for the main pandoc program is `pandoc.hs`. The source for
220the pandoc library is in `src/`, the source for the tests is in
221`tests/`, and the source for the benchmarks is in `benchmark/`.
223The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
224`Text.Pandoc.Generic` are in a separate library `pandoc-types`. The code can
225be found in a <http://github.com/jgm/pandoc-types>.
227To build pandoc, you will need a working installation of the
230The library is structured as follows:
232 - `Text.Pandoc` is a top-level module that exports what is needed
233 by most users of the library. Any patches that add new readers
234 or writers will need to make changes here, too.
235 - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
236 used for representing a pandoc document.
237 - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
238 building pandoc documents programatically.
239 - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
240 you to promote functions that operate on parts of pandoc documents
241 to functions that operate on whole pandoc documents, walking the
243 - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
245 - `Text.Pandoc.Biblio` is a utility module for formatting citations
247 - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
248 cabal flag is used. It is generated from `src/Text/Pandoc/Data.hsb` using
249 the preprocessor [hsb2hs].
250 - `Text.Pandoc.Highlighting` contains the interface to the
251 skylighting library, which is used for code syntax highlighting.
252 - `Text.Pandoc.ImageSize` is a utility module containing functions for
253 calculating image sizes from the contents of image files.
254 - `Text.Pandoc.MIME` contains functions for associating MIME types
256 - `Text.Pandoc.Options` defines reader and writer options.
257 - `Text.Pandoc.PDF` contains functions for producing a PDF from a
259 - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
260 - `Text.Pandoc.Pretty` is a pretty-printing library specialized to
262 - `Text.Pandoc.SelfContained` contains functions for making an HTML
263 file "self-contained," by importing remotely linked images, CSS,
264 and javascript and turning them into `data:` URLs.
265 - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
266 - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
267 - `Text.Pandoc.Slides` contains functions for splitting a markdown document
268 into slides, using the conventions described in the MANUAL.
269 - `Text.Pandoc.Templates` defines pandoc's templating system.
270 - `Text.Pandoc.UTF8` contains functions for converting text to and from
271 UTF8 bytestrings (strict and lazy).
272 - `Text.Pandoc.Asciify` contains functions to derive ascii versions of
273 identifiers that use accented characters.
274 - `Text.Pandoc.UUID` contains functions for generating UUIDs.
275 - `Text.Pandoc.XML` contains functions for formatting XML.
277[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
278[issue tracker]: https://github.com/jgm/pandoc/issues
279[User's Guide]: http://pandoc.org/MANUAL.html
280[FAQs]: http://pandoc.org/faqs.html
281[EditorConfig]: http://editorconfig.org/
282[Haskell platform]: http://www.haskell.org/platform/
283[hsb2hs]: http://hackage.haskell.org/package/hsb2hs
284[beginner-friendly]: https://github.com/jgm/pandoc/labels/beginner-friendly
285[enhancement]: https://github.com/jgm/pandoc/labels/enhancement
286[bug]: https://github.com/jgm/pandoc/labels/bug
287[complexity:low]: https://github.com/jgm/pandoc/labels/complexity:low
288[complexity:high]: https://github.com/jgm/pandoc/labels/complexity:high
289[docs]: https://github.com/jgm/pandoc/labels/docs
290[format:markdown]: https://github.com/jgm/pandoc/labels/format:markdown
291[new:reader]: https://github.com/jgm/pandoc/labels/new:reader
292[new:writer]: https://github.com/jgm/pandoc/labels/new:writer
293[status:in-progress]: https://github.com/jgm/pandoc/labels/status:in-progress
294[status:more-discussion-needed]: https://github.com/jgm/pandoc/labels/status:more-discussion-needed
295[status:more-info-needed]: https://github.com/jgm/pandoc/labels/status:more-info-needed
296[stack]: https://github.com/commercialhaskell/stack
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list