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 instructions for how to reproduce the problem,
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 the minimum necessary to illustrate the problem.
28Fixing bugs from the issue tracker
29----------------------------------
31Almost all the bugs on the issue tracker have one or more associated
32tags. These are used to indicate the *difficulty* and *nature* of a
33bug. There is not yet a way to indicate priority. An up to date
34summary of issues can be found [here](https://github.com/jgm/pandoc/labels).
36* [enhancement] -- A feature which would be desirable. We recommend
37 you discuss any proposed enhancement on pandoc-discuss before
39* [bug] -- A problem which needs to be fixed.
40* [minor] -- The fix should only be a couple of lines.
41* [major] -- The fix might require structural changes or in depth knowledge of
43* [reader] -- A request to add a new input format.
44* [writer] -- A request to add a new output format.
45* [docs] -- A discrepency or ambiguity in the documentation.
46* [inprogress] -- Someone is actively working on or planning to work on the
48* [more discussion needed] -- It is unclear what the correct approach
49 to solving the ticket is. Before starting on tickets such as this it
50 would be advisable to post on the ticket.
51* [more info needed] -- We require more information from a user before
52 we can classify a report properly.
54Have an idea for a new feature?
55-------------------------------
57First, search [pandoc-discuss] and the issue tracker (both open and closed
58issues) to make sure that the idea has not been discussed before.
60Explain the rationale for the feature you're requesting. Why would this
61feature be useful? Consider also any possible drawbacks, including backwards
62compatibility, new library dependencies, and performance issues.
64It is best to discuss a potential new feature on [pandoc-discuss]
65before opening an issue.
67Patches and pull requests
68-------------------------
70Patches and pull requests are welcome. Before you put time into a nontrivial
71patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
72for a new feature (rather than fixing a bug).
74Please follow these guidelines:
761. Each patch (commit) should make a single logical change (fix a bug, add
77 a feature, clean up some code, add documentation). Everything
78 related to that change should be included (including tests and
79 documentation), and nothing unrelated should be included.
812. The first line of the commit message should be a short description
82 of the whole commit (ideally <= 50 characters). Then there should
83 be a blank line, followed by a more detailed description of the
863. Follow the stylistic conventions you find in the existing
87 pandoc code. Use spaces, not tabs, and wrap code to 80 columns.
88 Always include type signatures for top-level functions.
89 Consider installing [EditorConfig], this will help you to follow the
90 coding style prevalent in pandoc.
924. Your code should compile without warnings (`-Wall` clean).
945. Run the tests to make sure your code does not introduce new bugs.
95 (See below under [Tests](#tests).) All tests should pass.
976. It is a good idea to add test cases for the bug you are fixing. (See
98 below under [Tests](#tests).) If you are adding a new writer or reader,
99 you must include tests.
1017. If you are adding a new feature, include updates to the README.
1038. All code must be released under the general license governing pandoc
1069. It is better not to introduce new dependencies. Dependencies on
107 external C libraries should especially be avoided.
112Tests can be run as follows:
114 cabal configure --enable-tests
118The test program is `tests/test-pandoc.hs`.
120Benchmarks can be enabled by passing the `--enable-benchmarks` flag
121to `cabal configure`, and run using `cabal bench`.
126Pandoc has a publicly accessible git repository on
127github: <http://github.com/jgm/pandoc>. To get a local copy of the source:
129 git clone git://github.com/jgm/pandoc.git
131Note: after cloning the repository (and in the future after pulling from it),
134 git submodule update --init
136to pull in changes to the templates (`data/templates/`). You can automate this
137by creating a file `.git/hooks/post-merge` with the contents:
140 git submodule update --init
142and making it executable:
144 chmod +x .git/hooks/post-merge
146The source for the main pandoc program is `pandoc.hs`. The source for
147the pandoc library is in `src/`, the source for the tests is in
148`tests/`, and the source for the benchmarks is in `benchmark/`.
150The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
151`Text.Pandoc.Generic` are in a separate library `pandoc-types`. The code can
152be found in a <http://github.com/jgm/pandoc-types>.
154To build pandoc, you will need a working installation of the
157The library is structured as follows:
159 - `Text.Pandoc` is a top-level module that exports what is needed
160 by most users of the library. Any patches that add new readers
161 or writers will need to make changes here, too.
162 - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
163 used for representing a pandoc document.
164 - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
165 building pandoc documents programatically.
166 - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
167 you to promote functions that operate on parts of pandoc documents
168 to functions that operate on whole pandoc documents, walking the
170 - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
172 - `Text.Pandoc.Biblio` is a utility module for formatting citations
174 - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
175 cabal flag is used. It is generated from `src/Text/Pandoc/Data.hsb` using
176 the preprocessor [hsb2hs].
177 - `Text.Pandoc.Highlighting` contains the interface to the
178 highlighting-kate library, which is used for code syntax highlighting.
179 - `Text.Pandoc.ImageSize` is a utility module containing functions for
180 calculating image sizes from the contents of image files.
181 - `Text.Pandoc.MIME` contains functions for associating MIME types
183 - `Text.Pandoc.Options` defines reader and writer options.
184 - `Text.Pandoc.PDF` contains functions for producing a PDF from a
186 - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
187 - `Text.Pandoc.Pretty` is a pretty-printing library specialized to
189 - `Text.Pandoc.SelfContained` contains functions for making an HTML
190 file "self-contained," by importing remotely linked images, CSS,
191 and javascript and turning them into `data:` URLs.
192 - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
193 - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
194 - `Text.Pandoc.Slides` contains functions for splitting a markdown document
195 into slides, using the conventions described in the README.
196 - `Text.Pandoc.Templates` defines pandoc's templating system.
197 - `Text.Pandoc.UTF8` contains functions for converting text to and from
198 UTF8 bytestrings (strict and lazy).
199 - `Text.Pandoc.Asciify` contains functions to derive ascii versions of
200 identifiers that use accented characters.
201 - `Text.Pandoc.UUID` contains functions for generating UUIDs.
202 - `Text.Pandoc.XML` contains functions for formatting XML.
204[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
205[issue tracker]: https://github.com/jgm/pandoc/issues
206[User's Guide]: http://pandoc.org/README.html
207[FAQs]: http://pandoc.org/faqs.html
208[EditorConfig]: http://editorconfig.org/
209[Haskell platform]: http://www.haskell.org/platform/
210[hsb2hs]: http://hackage.haskell.org/package/hsb2hs
211[enhancement]: https://github.com/jgm/pandoc/labels/enhancement
212[bug]: https://github.com/jgm/pandoc/labels/bug
213[minor]: https://github.com/jgm/pandoc/labels/Minor
214[major]: https://github.com/jgm/pandoc/labels/Major
215[reader]: https://github.com/jgm/pandoc/labels/Reader
216[writer]: https://github.com/jgm/pandoc/labels/Writer
217[docs]: https://github.com/jgm/pandoc/labels/docs
218[inprogress]: https://github.com/jgm/pandoc/labels/inprogress
219[more discussion needed]: https://github.com/jgm/pandoc/labels/More%20discussion%20needed
220[more info needed]: https://github.com/jgm/pandoc/labels/More%20info%20needed
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