diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 125 |
1 files changed, 79 insertions, 46 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9c95702e..1145dd835 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,24 @@ Contributing to pandoc ====================== +Have a question? +---------------- + +Ask on [pandoc-discuss]. + + 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. +Before you submit a bug report, search the [open issues] *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). +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, *reproducible* instructions, including @@ -31,25 +37,25 @@ Out of scope? A less than perfect conversion does not necessarily mean there's a bug in pandoc. Quoting from the MANUAL: -> Because Pandoc's intermediate representation of a document is less +> 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 +> 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 +For example, both `docx` and `odt` formats 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`.) +to `odt`. (You can, however, customize margin size using `--reference-doc`.) So before submitting a bug report, consider whether it might be -"out of scope." If it concerns a feature of documents that isn't +"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.) +(If in doubt, you can always ask on [pandoc-discuss].) Fixing bugs from the issue tracker ---------------------------------- @@ -57,9 +63,9 @@ 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 *complexity* 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). +summary of issues can be found on [GitHub labels]. -* [beginner-friendly] — The perfect starting point for new contributors. The +* [good first issue] — The perfect starting point for new contributors. The issue is generic and can be resolved without deep knowledge of the code base. * [enhancement] — A feature which would be desirable. We recommend @@ -71,7 +77,7 @@ summary of issues can be found [here](https://github.com/jgm/pandoc/labels). knowledge of the code base. * [new:reader] — A request to add a new input format. * [new:writer] — A request to add a new output format. -* [docs] — A discrepency, or ambiguity in the documentation. +* [docs] — A discrepancy, or ambiguity in the documentation. * [status:in-progress] — Someone is actively working on or planning to work on the ticket. * [status:more-discussion-needed] — It is unclear what the correct approach @@ -86,8 +92,8 @@ or bug reports related to Markdown are labelled with [format:markdown]. 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. +First, search [pandoc-discuss] and the issue tracker (both [open issues] *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 @@ -130,7 +136,7 @@ Please follow these guidelines: 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 MANUAL.txt. +7. If you are adding a new feature, include updates to `MANUAL.txt`. 8. All code must be released under the general license governing pandoc (GPL v2). @@ -140,7 +146,7 @@ Please follow these guidelines: 10. We aim for compatibility with ghc versions from 7.8.3 to the latest release. All pull requests and commits are tested - automatically on travis-ci.org, using GHC versions in the + 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 @@ -161,7 +167,7 @@ or, if you're using [stack], stack setup stack test -The test program is `tests/test-pandoc.hs`. +The test program is `test/test-pandoc.hs`. Benchmarks ---------- @@ -176,6 +182,11 @@ With stack: stack bench +You can also build pandoc with the `weigh-pandoc` flag and +run `weigh-pandoc` to get some statistics on memory usage. +(Eventually this should be incorporated into the benchmark +suite.) + Using the REPL -------------- @@ -186,43 +197,60 @@ a ghci REPL for working with pandoc. With [stack], use We recommend using the following `.ghci` file (which can be placed in the source directory): -``` -:set -fobject-code -:set -XTypeSynonymInstances -:set -XScopedTypeVariables -:set -XOverloadedStrings -``` + :set -fobject-code + :set -XTypeSynonymInstances + :set -XScopedTypeVariables + :set -XOverloadedStrings -The code --------- +Profiling +--------- -Pandoc has a publicly accessible git repository on -github: <http://github.com/jgm/pandoc>. To get a local copy of the source: +To use the GHC profiler with cabal: - git clone git://github.com/jgm/pandoc.git + cabal clean + cabal install --enable-library-profiling --enable-executable-profiling + pandoc +RTS -p -RTS [file]... + less pandoc.prof -Note: after cloning the repository (and in the future after pulling from it), -you should do +With stack: - git submodule update --init + stack clean + stack install --profile + pandoc +RTS -p -RTS [file]... + less pandoc.prof -to pull in changes to the templates (`data/templates/`). You can automate this -by creating a file `.git/hooks/post-merge` with the contents: +Templates +--------- - #!/bin/sh - git submodule update --init +The default templates live in `data/templates`, which is a git +subtree linked to <https://github.com/jgm/pandoc-templates.git>. +The purpose of maintaining a separate repository is to allow +people to maintain variant templates as a fork. -and making it executable: +You can modify the templates and submit patches without worrying +much about this: when these patches are merged, we will +push them to the main templates repository by doing + + git subtree push --prefix=data/templates templates master + +where `templates` is a remote pointing to the templates +repository. + +The code +-------- + +Pandoc has a publicly accessible git repository on +github: <http://github.com/jgm/pandoc>. To get a local copy of the source: - chmod +x .git/hooks/post-merge + git clone https://github.com/jgm/pandoc.git 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/`. +`test/`, 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>. +be found in <http://github.com/jgm/pandoc-types>. To build pandoc, you will need a working installation of the [Haskell platform]. @@ -261,7 +289,7 @@ The library is structured as follows: 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. + 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 @@ -274,6 +302,10 @@ The library is structured as follows: - `Text.Pandoc.UUID` contains functions for generating UUIDs. - `Text.Pandoc.XML` contains functions for formatting XML. +[open issues]: https://github.com/jgm/pandoc/issues +[closed issues]: https://github.com/jgm/pandoc/issues?q=is%3Aissue+is%3Aclosed +[latest released version]: https://github.com/jgm/pandoc/releases/latest +[development version]: https://github.com/pandoc-extras/pandoc-nightly/releases/latest [pandoc-discuss]: http://groups.google.com/group/pandoc-discuss [issue tracker]: https://github.com/jgm/pandoc/issues [User's Guide]: http://pandoc.org/MANUAL.html @@ -281,7 +313,8 @@ The library is structured as follows: [EditorConfig]: http://editorconfig.org/ [Haskell platform]: http://www.haskell.org/platform/ [hsb2hs]: http://hackage.haskell.org/package/hsb2hs -[beginner-friendly]: https://github.com/jgm/pandoc/labels/beginner-friendly +[GitHub labels]: https://github.com/jgm/pandoc/labels +[good first issue]:https://github.com/jgm/pandoc/labels/good%20first%20issue [enhancement]: https://github.com/jgm/pandoc/labels/enhancement [bug]: https://github.com/jgm/pandoc/labels/bug [complexity:low]: https://github.com/jgm/pandoc/labels/complexity:low |