[Docutils-develop] [docutils:feature-requests] #90 Create a warning instead of an error for a missing "include" file?

[Günter M. <mi...@us...>]

- **status**: open --> closed-rejected
- **Comment**:

A missing "literally" included file means missing data in the output. This should be an error, not just a warning.



---

**[feature-requests:#90] Create a warning instead of an error for a missing "include" file?**

**Status:** closed-rejected
**Group:** Default
**Created:** Tue Feb 01, 2022 09:25 AM UTC by Günter Milde
**Last Updated:** Tue Feb 01, 2022 09:25 AM UTC
**Owner:** nobody


The Python Developers Guide documents the Sphinx directive "literalinclude" and adds in a footnote
> There is a standard `include` directive, but it raises errors if the file is not found. This one only emits a warning.
> -- https://devguide.python.org/documenting/#id5

Should Docutils follow Sphinx and let the ["include" directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment) only warn?

* No, an error is the right [report level](https://docutils.sourceforge.io/docs/user/config.html#report-level).
* For literal inclusions (options "literal", "code", "raw", "parser"):  they have only local effect.
* For all inclusions: an included reST file may have effects later in the document (defining a role or substitution, setting the default role, establishing a new section level, ...).

It boils down to an assesment of the "seriosity" of a missing include file:
Both, *warning* and *error* indicate a  problem but do not normally  [halt](https://docutils.sourceforge.io/docs/user/config.html#halt-level) processing.
A *warning* is easier to silence (other *errors* will still pop up).




---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.