aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohn MacFarlane <jgm@berkeley.edu>2015-08-08 15:18:31 -0700
committerJohn MacFarlane <jgm@berkeley.edu>2015-08-08 15:18:31 -0700
commitf78b5a4a5a885f45a0934e436647af5d8a52c1fc (patch)
treef1c39dc6eb44347bf1744423c95be696eabcb8cb
parent2eec8cf61bc317b77669d9f8256f707ba0e5d69f (diff)
downloadpandoc-f78b5a4a5a885f45a0934e436647af5d8a52c1fc.tar.gz
Clarified what is "out of scope" in README and CONTRIBUTING.md.
-rw-r--r--CONTRIBUTING.md26
-rw-r--r--README10
2 files changed, 36 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7b321f868..75f412df0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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
----------------------------------
diff --git a/README b/README
index 6164693b9..cf662ffd0 100644
--- a/README
+++ b/README
@@ -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`
--------------