git.iko.soy/typeable/pandoc
on issue1234 help sign in
typeable/pandoc/CONTRIBUTING.md
184 lines 7.4 kB history raw
1Contributing to pandoc
2======================
4Found a bug?
5------------
7Bug reports are welcome! Please report all bugs on pandoc's github
8[issue tracker].
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]
12for anything relevant.
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,
18including
20 * the exact command line used
21 * the exact input used
22 * the output received
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.
28Have an idea for a new feature?
29-------------------------------
31First, search [pandoc-discuss] and the issue tracker (both open and closed
32issues) to make sure that the idea has not been discussed before.
34Explain the rationale for the feature you're requesting. Why would this
35feature be useful? Consider also any possible drawbacks, including backwards
36compatibility, new library dependencies, and performance issues.
38It is best to discuss a potential new feature on [pandoc-discuss]
39before opening an issue.
41Patches and pull requests
42-------------------------
44Patches and pull requests are welcome. Before you put time into a nontrivial
45patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
46for a new feature (rather than fixing a bug).
48Please follow these guidelines:
501. Each patch (commit) should make a single logical change (fix a bug, add
51 a feature, clean up some code, add documentation). Everything
52 related to that change should be included (including tests and
53 documentation), and nothing unrelated should be included.
552. The first line of the commit message should be a short description
56 of the whole commit (ideally <= 50 characters). Then there should
57 be a blank line, followed by a more detailed description of the
58 change.
603. Follow the stylistic conventions you find in the existing
61 pandoc code. Use spaces, not tabs, and wrap code to 80 columns.
62 Always include type signatures for top-level functions.
63 Consider installing [EditorConfig], this will help you to follow the
64 coding style prevalent in pandoc.
664. Your code should compile without warnings (`-Wall` clean).
685. Run the tests to make sure your code does not introduce new bugs.
69 (See below under [Tests](#tests).) All tests should pass.
716. It is a good idea to add test cases for the bug you are fixing. (See
72 below under [Tests](#tests).) If you are adding a new writer or reader,
73 you must include tests.
757. If you are adding a new feature, include updates to the README.
778. All code must be released under the general license governing pandoc
78 (GPL v2).
809. It is better not to introduce new dependencies. Dependencies on
81 external C libraries should especially be avoided.
83Tests
84-----
86Tests can be run as follows:
88 cabal configure --enable-tests
89 cabal build
90 cabal test
92The test program is `tests/test-pandoc.hs`.
94Benchmarks can be enabled by passing the `--enable-benchmarks` flag
95to `cabal configure`, and run using `cabal bench`.
97The code
98--------
100Pandoc has a publicly accessible git repository on
101github: <http://github.com/jgm/pandoc>. To get a local copy of the source:
103 git clone git://github.com/jgm/pandoc.git
105Note: after cloning the repository (and in the future after pulling from it),
106you should do
108 git submodule update --init
110to pull in changes to the templates (`data/templates/`). You can automate this
111by creating a file `.git/hooks/post-merge` with the contents:
113 #!/bin/sh
114 git submodule update --init
116and making it executable:
118 chmod +x .git/hooks/post-merge
120The source for the main pandoc program is `pandoc.hs`. The source for
121the pandoc library is in `src/`, the source for the tests is in
122`tests/`, and the source for the benchmarks is in `benchmark/`.
124The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
125`Text.Pandoc.Generics` are in a separate library `pandoc-types`. The code can
126be found in a <http://github.com/jgm/pandoc-types>.
128To build pandoc, you will need a working installation of the
129[Haskell platform].
131The library is structured as follows:
133 - `Text.Pandoc` is a top-level module that exports what is needed
134 by most users of the library. Any patches that add new readers
135 or writers will need to make changes here, too.
136 - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
137 used for representing a pandoc document.
138 - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
139 building pandoc documents programatically.
140 - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
141 you to promote functions that operate on parts of pandoc documents
142 to functions that operate on whole pandoc documents, walking the
143 tree automatically.
144 - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
145 are the writers.
146 - `Text.Pandoc.Biblio` is a utility module for formatting citations
147 using citeproc-hs.
148 - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
149 cabal flag is used. It is generated from `src/Text/Pandoc/Data.hsb` using
150 the preprocessor [hsb2hs].
151 - `Text.Pandoc.Highlighting` contains the interface to the
152 highlighting-kate library, which is used for code syntax highlighting.
153 - `Text.Pandoc.ImageSize` is a utility module containing functions for
154 calculating image sizes from the contents of image files.
155 - `Text.Pandoc.MIME` contains functions for associating MIME types
156 with extensions.
157 - `Text.Pandoc.Options` defines reader and writer options.
158 - `Text.Pandoc.PDF` contains functions for producing a PDF from a
159 LaTeX source.
160 - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
161 - `Text.Pandoc.Pretty` is a pretty-printing library specialized to
162 the needs of pandoc.
163 - `Text.Pandoc.SelfContained` contains functions for making an HTML
164 file "self-contained," by importing remotely linked images, CSS,
165 and javascript and turning them into `data:` URLs.
166 - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
167 - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
168 - `Text.Pandoc.Slides` contains functions for splitting a markdown document
169 into slides, using the conventions described in the README.
170 - `Text.Pandoc.Templates` defines pandoc's templating system.
171 - `Text.Pandoc.UTF8` contains functions for converting text to and from
172 UTF8 bytestrings (strict and lazy).
173 - `Text.Pandoc.Asciify` contains functions to derive ascii versions of
174 identifiers that use accented characters.
175 - `Text.Pandoc.UUID` contains functions for generating UUIDs.
176 - `Text.Pandoc.XML` contains functions for formatting XML.
178[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
179[issue tracker]: https://github.com/jgm/pandoc/issues
180[User's Guide]: http://johnmacfarlane.net/pandoc/README.html
181[FAQs]: http://johnmacfarlane.net/pandoc/faqs.html
182[EditorConfig]: http://editorconfig.org/
183[Haskell platform]: http://www.haskell.org/platform/
184[hsb2hs]: http://hackage.haskell.org/package/hsb2hs