Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Clarified what is "out of scope" in README and CONTRIBUTING.md.

Browse source
This commit is contained in:
John MacFarlane 2015-08-08 15:18:31 -07:00
parent 2eec8cf61b
commit f78b5a4a5a
2 changed files with 36 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
CONTRIBUTING.md
View file

@ -25,6 +25,32 @@ including
A small test case (just a few lines) is ideal. If your input is large,
try to whittle it down to the minimum necessary to illustrate the problem.
Out of scope?
-------------
A less than perfect conversion does not necessarily mean there's
a bug in pandoc. Quoting from the README:
> 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
> 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
margin size, this information will be lost on converting from docx
to odt. (You can, however, customize margin size using `--reference-odt`.)
So before submitting a bug report, consider whether it might be
"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.)
Fixing bugs from the issue tracker
----------------------------------

10
README
View file

@ -40,6 +40,16 @@ representation of the document, and a set of writers, which convert
this native representation into a target format. Thus, adding an input
or output format requires only adding a reader or writer.
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
Markdown can be expected to be lossy.
Using `pandoc`
--------------