[Docutils-develop] [docutils:feature-requests] #91 reST: include directive should support root-relative paths

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

Moving this to "feature-requests", as there is no patch attached.

The heading is IMO misleading: The "include" directive supports "root-relative" (i.e. absolute) paths following the conventions of Python's `open()` standard function. (It  passes the path to `open()` after resolving  the special syntax for standard “include” data files.)
Mind that for most Docutils front-end tools (rst2html, rst2latex, ...), there is no notation of a "project root".

From the description, I guess the you may want a way to specify a "root directory" that differs from the file system's root. This would require a new configuration setting. 

Alternatives:

* Get Python's  `open()` to open paths starting with '\' relative to a "project root" in the custom build system.
* Tools like "chroot" or similar could be used on the system level to start a build system with  "project root" == "filesystem root".




---

** [feature-requests:#91] reST: include directive should support root-relative paths**

**Status:** open
**Group:** None
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Tue May 03, 2022 10:04 PM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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.