Documentation fix/update.

The return value of `io.FileOutput` (and hence of `core.publish_cmdline()`
and `core.publish_file()`) is a `str` instance (except for
binary output document formats) and has always been under Python 3.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9366 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 8 insertions, 3 deletions

diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt
index 9e18f2ed2..4d725e62c 100644
--- a/docutils/docs/api/publisher.txt
+++ b/docutils/docs/api/publisher.txt
@@ -42,13 +42,18 @@ a description of the function arguments.
 publish_cmdline()
 -----------------
 
-Function for command-line front-end tools, like ``rst2html.py`` with 
-file I/O. Also returns the output as `bytes` instance.
+Function for command-line front-end tools, like ``rst2html.py`` 
+or functions for `"console_scripts" entry points`_ like `core.rst2html()`
+with file I/O. 
+In addition to writing the output document to a file, also returns it as
+`str` instance (rsp. `bytes` for binary output document formats).
 
 There are several examples in the ``tools/`` directory of the Docutils
 repository. A detailed analysis of one such tool is in `Inside A Docutils
 Command-Line Front-End Tool`_.
 
+.. _"console_scripts" entry points:
+    https://packaging.python.org/en/latest/specifications/entry-points/
 .. _Inside A Docutils Command-Line Front-End Tool: ../howto/cmdline-tool.html
 
 
@@ -57,7 +62,7 @@ publish_file()
 
 For programmatic use with file-like I/O.
 In addition to writing the output document to a file, also returns it as
-a `bytes` instance.
+`str` instance (rsp. `bytes` for binary output document formats).
 
 
 publish_string()