Blame CONTRIBUTING.md

Packit dda32d
Contributing to pandoc
Packit dda32d
======================
Packit dda32d
Packit dda32d
Have a question?
Packit dda32d
----------------
Packit dda32d
Packit dda32d
Ask on [pandoc-discuss].
Packit dda32d
Packit dda32d
Packit dda32d
Found a bug?
Packit dda32d
------------
Packit dda32d
Packit dda32d
Bug reports are welcome!  Please report all bugs on pandoc's github
Packit dda32d
[issue tracker].
Packit dda32d
Packit dda32d
Before you submit a bug report, search the [open issues] *and* [closed issues]
Packit dda32d
to make sure the issue hasn't come up before. Also, check the [User's Guide] and
Packit dda32d
[FAQs] for anything relevant.
Packit dda32d
Packit dda32d
Make sure you can reproduce the bug with the [latest released version] of pandoc
Packit dda32d
(or, even better, the [development version]).
Packit dda32d
Packit dda32d
Your report should give detailed, *reproducible* instructions, including
Packit dda32d
Packit dda32d
  * the pandoc version (check using `pandoc -v`)
Packit dda32d
  * the exact command line used
Packit dda32d
  * the exact input used
Packit dda32d
  * the output received
Packit dda32d
  * the output you expected instead
Packit dda32d
Packit dda32d
A small test case (just a few lines) is ideal.  If your input is large,
Packit dda32d
try to whittle it down to a *minimum working example*.
Packit dda32d
Packit dda32d
Out of scope?
Packit dda32d
-------------
Packit dda32d
Packit dda32d
A less than perfect conversion does not necessarily mean there's
Packit dda32d
a bug in pandoc.  Quoting from the MANUAL:
Packit dda32d
Packit dda32d
> Because pandoc's intermediate representation of a document is less
Packit dda32d
> expressive than many of the formats it converts between, one should
Packit dda32d
> not expect perfect conversions between every format and every other.
Packit dda32d
> Pandoc attempts to preserve the structural elements of a document, but
Packit dda32d
> not formatting details such as margin size.  And some document elements,
Packit dda32d
> such as complex tables, may not fit into pandoc's simple document
Packit dda32d
> model.  While conversions from pandoc's Markdown to all formats aspire
Packit dda32d
> to be perfect, conversions from formats more expressive than pandoc's
Packit dda32d
> Markdown can be expected to be lossy.
Packit dda32d
Packit dda32d
For example, both `docx` and `odt` formats can represent margin size, but
Packit dda32d
because pandoc's internal document model does not contain a representation of
Packit dda32d
margin size, this information will be lost on converting from docx
Packit dda32d
to `odt`.  (You can, however, customize margin size using `--reference-doc`.)
Packit dda32d
Packit dda32d
So before submitting a bug report, consider whether it might be
Packit dda32d
"out of scope." If it concerns a feature of documents that isn't
Packit dda32d
representable in pandoc's Markdown, then it very likely is.
Packit dda32d
(If in doubt, you can always ask on [pandoc-discuss].)
Packit dda32d
Packit dda32d
Fixing bugs from the issue tracker
Packit dda32d
----------------------------------
Packit dda32d
Packit dda32d
Almost all the bugs on the issue tracker have one or more associated
Packit dda32d
tags. These are used to indicate the *complexity* and *nature* of a
Packit dda32d
bug. There is not yet a way to indicate priority. An up to date
Packit dda32d
summary of issues can be found on [GitHub labels].
Packit dda32d
Packit dda32d
* [beginner-friendly] — The perfect starting point for new contributors. The
Packit dda32d
  issue is generic and can be resolved without deep knowledge of the code
Packit dda32d
  base.
Packit dda32d
* [enhancement] — A feature which would be desirable. We recommend
Packit dda32d
  you discuss any proposed enhancement on pandoc-discuss before
Packit dda32d
  writing code.
Packit dda32d
* [bug] — A problem which needs to be fixed.
Packit dda32d
* [complexity:low] — The fix should only be a couple of lines.
Packit dda32d
* [complexity:high] — The fix might require structural changes or in depth
Packit dda32d
  knowledge of the code base.
Packit dda32d
* [new:reader] — A request to add a new input format.
Packit dda32d
* [new:writer] — A request to add a new output format.
Packit dda32d
* [docs] — A discrepancy,  or ambiguity in the documentation.
Packit dda32d
* [status:in-progress] — Someone is actively working on or planning to work on the
Packit dda32d
  ticket.
Packit dda32d
* [status:more-discussion-needed] — It is unclear what the correct approach
Packit dda32d
  to solving the ticket is. Before starting on tickets such as this it
Packit dda32d
  would be advisable to post on the ticket.
Packit dda32d
* [status:more-info-needed] — We require more information from a user before
Packit dda32d
  we can classify a report properly.
Packit dda32d
Packit dda32d
Issues related to a specific format are tagged accordingly, e.g. feature request
Packit dda32d
or bug reports related to Markdown are labelled with [format:markdown].
Packit dda32d
Packit dda32d
Have an idea for a new feature?
Packit dda32d
-------------------------------
Packit dda32d
Packit dda32d
First, search [pandoc-discuss] and the issue tracker (both [open issues] *and*
Packit dda32d
[closed issues]) to make sure that the idea has not been discussed before.
Packit dda32d
Packit dda32d
Explain the rationale for the feature you're requesting.  Why would this
Packit dda32d
feature be useful?  Consider also any possible drawbacks, including backwards
Packit dda32d
compatibility, new library dependencies, and performance issues.
Packit dda32d
Packit dda32d
It is best to discuss a potential new feature on [pandoc-discuss]
Packit dda32d
before opening an issue.
Packit dda32d
Packit dda32d
Patches and pull requests
Packit dda32d
-------------------------
Packit dda32d
Packit dda32d
Patches and pull requests are welcome.  Before you put time into a nontrivial
Packit dda32d
patch, it is a good idea to discuss it on [pandoc-discuss], especially if it is
Packit dda32d
for a new feature (rather than fixing a bug).
Packit dda32d
Packit dda32d
Please follow these guidelines:
Packit dda32d
Packit dda32d
1.  Each patch (commit) should make a single logical change (fix a bug, add
Packit dda32d
    a feature, clean up some code, add documentation).  Everything
Packit dda32d
    related to that change should be included (including tests and
Packit dda32d
    documentation), and nothing unrelated should be included.
Packit dda32d
Packit dda32d
2.  The first line of the commit message should be a short description
Packit dda32d
    of the whole commit (ideally <= 50 characters).  Then there should
Packit dda32d
    be a blank line, followed by a more detailed description of the
Packit dda32d
    change.
Packit dda32d
Packit dda32d
3.  Follow the stylistic conventions you find in the existing
Packit dda32d
    pandoc code.  Use spaces, not tabs, and wrap code to 80 columns.
Packit dda32d
    Always include type signatures for top-level functions.
Packit dda32d
    Consider installing [EditorConfig], this will help you to follow the
Packit dda32d
    coding style prevalent in pandoc.
Packit dda32d
Packit dda32d
4.  Your code should compile without warnings (`-Wall` clean).
Packit dda32d
Packit dda32d
5.  Run the tests to make sure your code does not introduce new bugs.
Packit dda32d
    (See below under [Tests](#tests).)  All tests should pass.
Packit dda32d
Packit dda32d
6.  It is a good idea to add test cases for the bug you are fixing.  (See
Packit dda32d
    below under [Tests](#tests).)  If you are adding a new writer or reader,
Packit dda32d
    you must include tests.
Packit dda32d
Packit dda32d
7.  If you are adding a new feature, include updates to `MANUAL.txt`.
Packit dda32d
Packit dda32d
8.  All code must be released under the general license governing pandoc
Packit dda32d
    (GPL v2).
Packit dda32d
Packit dda32d
9.  It is better not to introduce new dependencies.  Dependencies on
Packit dda32d
    external C libraries should especially be avoided.
Packit dda32d
Packit dda32d
10. We aim for compatibility with ghc versions from 7.8.3 to the
Packit dda32d
    latest release.  All pull requests and commits are tested
Packit dda32d
    automatically on <travis-ci.org>, using GHC versions in the
Packit dda32d
    `Tested-With` stanza of `pandoc.cabal`.  We currently relax
Packit dda32d
    the "`-Wall` clean" requirement for GHC 7.10.x, because
Packit dda32d
    there are so many warnings relating to the addition of type
Packit dda32d
    classes to the Prelude.
Packit dda32d
Packit dda32d
Tests
Packit dda32d
-----
Packit dda32d
Packit dda32d
Tests can be run as follows:
Packit dda32d
Packit dda32d
    cabal install --only-dependencies --enable-tests
Packit dda32d
    cabal configure --enable-tests
Packit dda32d
    cabal build
Packit dda32d
    cabal test
Packit dda32d
Packit dda32d
or, if you're using [stack],
Packit dda32d
Packit dda32d
    stack setup
Packit dda32d
    stack test
Packit dda32d
Packit dda32d
The test program is `test/test-pandoc.hs`.
Packit dda32d
Packit dda32d
Benchmarks
Packit dda32d
----------
Packit dda32d
Packit dda32d
To run benchmarks with cabal:
Packit dda32d
Packit dda32d
    cabal configure --enable-benchmarks
Packit dda32d
    cabal build
Packit dda32d
    cabal bench
Packit dda32d
Packit dda32d
With stack:
Packit dda32d
Packit dda32d
    stack bench
Packit dda32d
Packit dda32d
You can also build pandoc with the `weigh-pandoc` flag and
Packit dda32d
run `weigh-pandoc` to get some statistics on memory usage.
Packit dda32d
(Eventually this should be incorporated into the benchmark
Packit dda32d
suite.)
Packit dda32d
Packit dda32d
Using the REPL
Packit dda32d
--------------
Packit dda32d
Packit dda32d
With a recent version of cabal, you can do `cabal repl` and get
Packit dda32d
a ghci REPL for working with pandoc.  With [stack], use
Packit dda32d
`cabal ghci`.
Packit dda32d
Packit dda32d
We recommend using the following `.ghci` file (which can be
Packit dda32d
placed in the source directory):
Packit dda32d
Packit dda32d
	:set -fobject-code
Packit dda32d
	:set -XTypeSynonymInstances
Packit dda32d
	:set -XScopedTypeVariables
Packit dda32d
	:set -XOverloadedStrings
Packit dda32d
Packit dda32d
Profiling
Packit dda32d
---------
Packit dda32d
Packit dda32d
To use the GHC profiler with cabal:
Packit dda32d
Packit dda32d
    cabal clean
Packit dda32d
    cabal install --enable-library-profiling --enable-executable-profiling
Packit dda32d
    pandoc +RTS -p -RTS [file]...
Packit dda32d
    less pandoc.prof
Packit dda32d
Packit dda32d
With stack:
Packit dda32d
Packit dda32d
    stack clean
Packit dda32d
    stack install --profile
Packit dda32d
    pandoc +RTS -p -RTS [file]...
Packit dda32d
    less pandoc.prof
Packit dda32d
Packit dda32d
Templates
Packit dda32d
---------
Packit dda32d
Packit dda32d
The default templates live in `data/templates`, which is a git
Packit dda32d
subtree linked to <https://github.com/jgm/pandoc-templates.git>.
Packit dda32d
The purpose of maintaining a separate repository is to allow
Packit dda32d
people to maintain variant templates as a fork.
Packit dda32d
Packit dda32d
You can modify the templates and submit patches without worrying
Packit dda32d
much about this: when these patches are merged, we will
Packit dda32d
push them to the main templates repository by doing
Packit dda32d
Packit dda32d
    git subtree push --prefix=data/templates templates master
Packit dda32d
Packit dda32d
where `templates` is a remote pointing to the templates
Packit dda32d
repository.
Packit dda32d
Packit dda32d
The code
Packit dda32d
--------
Packit dda32d
Packit dda32d
Pandoc has a publicly accessible git repository on
Packit dda32d
github: <http://github.com/jgm/pandoc>.  To get a local copy of the source:
Packit dda32d
Packit dda32d
    git clone https://github.com/jgm/pandoc.git
Packit dda32d
Packit dda32d
The source for the main pandoc program is `pandoc.hs`.  The source for
Packit dda32d
the pandoc library is in `src/`, the source for the tests is in
Packit dda32d
`test/`, and the source for the benchmarks is in `benchmark/`.
Packit dda32d
Packit dda32d
The modules `Text.Pandoc.Definition`, `Text.Pandoc.Builder`, and
Packit dda32d
`Text.Pandoc.Generic` are in a separate library `pandoc-types`.  The code can
Packit dda32d
be found in <http://github.com/jgm/pandoc-types>.
Packit dda32d
Packit dda32d
To build pandoc, you will need a working installation of the
Packit dda32d
[Haskell platform].
Packit dda32d
Packit dda32d
The library is structured as follows:
Packit dda32d
Packit dda32d
  - `Text.Pandoc` is a top-level module that exports what is needed
Packit dda32d
    by most users of the library.  Any patches that add new readers
Packit dda32d
    or writers will need to make changes here, too.
Packit dda32d
  - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
Packit dda32d
    used for representing a pandoc document.
Packit dda32d
  - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
Packit dda32d
    building pandoc documents programatically.
Packit dda32d
  - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
Packit dda32d
    you to promote functions that operate on parts of pandoc documents
Packit dda32d
    to functions that operate on whole pandoc documents, walking the
Packit dda32d
    tree automatically.
Packit dda32d
  - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
Packit dda32d
    are the writers.
Packit dda32d
  - `Text.Pandoc.Biblio` is a utility module for formatting citations
Packit dda32d
    using citeproc-hs.
Packit dda32d
  - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
Packit dda32d
    cabal flag is used.  It is generated from `src/Text/Pandoc/Data.hsb` using
Packit dda32d
    the preprocessor [hsb2hs].
Packit dda32d
  - `Text.Pandoc.Highlighting` contains the interface to the
Packit dda32d
    skylighting library, which is used for code syntax highlighting.
Packit dda32d
  - `Text.Pandoc.ImageSize` is a utility module containing functions for
Packit dda32d
    calculating image sizes from the contents of image files.
Packit dda32d
  - `Text.Pandoc.MIME` contains functions for associating MIME types
Packit dda32d
    with extensions.
Packit dda32d
  - `Text.Pandoc.Options` defines reader and writer options.
Packit dda32d
  - `Text.Pandoc.PDF` contains functions for producing a PDF from a
Packit dda32d
    LaTeX source.
Packit dda32d
  - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
Packit dda32d
  - `Text.Pandoc.Pretty` is a pretty-printing library specialized to
Packit dda32d
    the needs of pandoc.
Packit dda32d
  - `Text.Pandoc.SelfContained` contains functions for making an HTML
Packit dda32d
    file "self-contained," by importing remotely linked images, CSS,
Packit dda32d
    and JavaScript and turning them into `data:` URLs.
Packit dda32d
  - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
Packit dda32d
  - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
Packit dda32d
  - `Text.Pandoc.Slides` contains functions for splitting a markdown document
Packit dda32d
    into slides, using the conventions described in the MANUAL.
Packit dda32d
  - `Text.Pandoc.Templates` defines pandoc's templating system.
Packit dda32d
  - `Text.Pandoc.UTF8` contains functions for converting text to and from
Packit dda32d
    UTF8 bytestrings (strict and lazy).
Packit dda32d
  - `Text.Pandoc.Asciify` contains functions to derive ascii versions of
Packit dda32d
    identifiers that use accented characters.
Packit dda32d
  - `Text.Pandoc.UUID` contains functions for generating UUIDs.
Packit dda32d
  - `Text.Pandoc.XML` contains functions for formatting XML.
Packit dda32d
Packit dda32d
[open issues]: https://github.com/jgm/pandoc/issues
Packit dda32d
[closed issues]: https://github.com/jgm/pandoc/issues?q=is%3Aissue+is%3Aclosed
Packit dda32d
[latest released version]: https://github.com/jgm/pandoc/releases/latest
Packit dda32d
[development version]: https://github.com/pandoc-extras/pandoc-nightly/releases/latest
Packit dda32d
[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
Packit dda32d
[issue tracker]: https://github.com/jgm/pandoc/issues
Packit dda32d
[User's Guide]: http://pandoc.org/MANUAL.html
Packit dda32d
[FAQs]:  http://pandoc.org/faqs.html
Packit dda32d
[EditorConfig]: http://editorconfig.org/
Packit dda32d
[Haskell platform]: http://www.haskell.org/platform/
Packit dda32d
[hsb2hs]: http://hackage.haskell.org/package/hsb2hs
Packit dda32d
[GitHub labels]: https://github.com/jgm/pandoc/labels
Packit dda32d
[beginner-friendly]: https://github.com/jgm/pandoc/labels/beginner-friendly
Packit dda32d
[enhancement]: https://github.com/jgm/pandoc/labels/enhancement
Packit dda32d
[bug]: https://github.com/jgm/pandoc/labels/bug
Packit dda32d
[complexity:low]: https://github.com/jgm/pandoc/labels/complexity:low
Packit dda32d
[complexity:high]: https://github.com/jgm/pandoc/labels/complexity:high
Packit dda32d
[docs]: https://github.com/jgm/pandoc/labels/docs
Packit dda32d
[format:markdown]: https://github.com/jgm/pandoc/labels/format:markdown
Packit dda32d
[new:reader]: https://github.com/jgm/pandoc/labels/new:reader
Packit dda32d
[new:writer]: https://github.com/jgm/pandoc/labels/new:writer
Packit dda32d
[status:in-progress]: https://github.com/jgm/pandoc/labels/status:in-progress
Packit dda32d
[status:more-discussion-needed]: https://github.com/jgm/pandoc/labels/status:more-discussion-needed
Packit dda32d
[status:more-info-needed]: https://github.com/jgm/pandoc/labels/status:more-info-needed
Packit dda32d
[stack]: https://github.com/commercialhaskell/stack
Packit dda32d