# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1481704988 -3600
# Node ID c742c8f9ffa34fcd8d916fc55fafa065ea8389cb
# Parent  83c0a6556e6c35eddad3f7ab9a8dabf9330fdf48
encodings

diff -r 83c0a6556e6c -r c742c8f9ffa3 Sphinx/source/developers.rst
--- a/Sphinx/source/developers.rst	Tue Dec 13 18:00:15 2016 +0100
+++ b/Sphinx/source/developers.rst	Wed Dec 14 09:43:08 2016 +0100
@@ -6,5 +6,6 @@
 
    developers/creating-plugins.rst
    developers/stone.rst
+   developers/db-versioning.rst
+   developers/implementation-notes.rst
    developers/coding-style.rst
-   developers/db-versioning.rst
diff -r 83c0a6556e6c -r c742c8f9ffa3 Sphinx/source/developers/implementation-notes.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/developers/implementation-notes.rst	Wed Dec 14 09:43:08 2016 +0100
@@ -0,0 +1,43 @@
+.. _implementation-notes:
+
+Implementation notes
+====================
+
+Encodings
+---------
+
+DICOM supports many codepages to encode strings. DICOM instances using
+special characters should contain the ``SpecificCharacterSet
+(0008,0005)`` tag. The latter tag `specifies which codepage
+<http://dicom.nema.org/dicom/2013/output/chtml/part03/sect_C.12.html#sect_C.12.1.1.2>`__
+is used by the DICOM instance. Internally, Orthanc converts all these
+codepages to the `UTF-8 encoding
+<https://en.wikipedia.org/wiki/UTF-8>`__.
+
+In particular, :ref:`plugins <creating-plugins>` must assume that any
+string or JSON file coming from the Orthanc core is encoded using
+UTF-8. Similarly, plugins must use UTF-8 when calling services
+provided by the Orthanc core. The conversion to/from UTF-8 is done
+transparently by the plugin engine.
+
+The :ref:`configuration option <configuration>` ``DefaultEncoding``
+plays an important role. It is used in three cases:
+
+1. If receiving a DICOM instance without the ``SpecificCharacterSet
+   (0008,0005)`` tag, Orthanc will interpret strings within this
+   instance using this default encoding. This is important in
+   practice, as many DICOM modalities are not properly configured with
+   respect to encodings.
+
+2. When answering a :ref:`C-Find query <dicom-find>` (including for
+   worklists), Orthanc will use its default encoding. If one single
+   answer uses a different encoding, it will be transcoded.
+
+3. If creating a new instance (e.g. through the
+   ``/tools/create-dicom`` URI of the :ref:`REST API <rest>`, or
+   through the ``OrthancPluginCreateDicom()`` primitive of the plugin
+   SDK) and if ``SpecificCharacterSet (0008,0005)`` is not provided
+   for this instance, Orthanc will use its default encoding. Note
+   however that if ``SpecificCharacterSet`` is set, Orthanc will
+   transcode the incoming UTF-8 strings to the codepage specified in
+   this tag, and not to the default encoding.
diff -r 83c0a6556e6c -r c742c8f9ffa3 Sphinx/source/users/configuration.rst
--- a/Sphinx/source/users/configuration.rst	Tue Dec 13 18:00:15 2016 +0100
+++ b/Sphinx/source/users/configuration.rst	Wed Dec 14 09:43:08 2016 +0100
@@ -25,6 +25,10 @@
 * Create a HTTP server for the REST API that listens on the port 8042.
 * Store the Orthanc database in a folder called ``OrthancStorage``.
 
+*Remark:* When specifying paths under Microsoft Windows, backslashes
+(i.e. ``\``) should be either escaped by doubling them (as in ``\\``),
+or replaced by forward slashes (as in ``/``).
+
 To obtain more diagnostic, you can use the ``--verbose`` or the
 ``--trace`` options::