include directive with start-at and end-before options

[noahmclean]

Context

It would be useful to duplicate portions of non-code text from one (e.g., markdown) document and in another (e.g., also markdown) document. Currently, it is possible to include a snippet of code as a code block using the literalinclude directive, but not text/markdown.

Proposal

Use the :start-at: and :end-before: options with the include directive.

For instance,

{include} includethis.txt
:start-at: Ut enim
:end-before: Excepteur

would insert the second and third sentences from the usual Lorem Ipsum text.

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[choldgraf]

Another approach to this might be to allow for including labels, similar to {embed}. For example, something like:

Sentence one.

(two)=
Sentence two.

and then later:

Here is:

```{include} #two
```

And this would result in:

Here is:

Sentence two.

[noahmclean]

The labels idea sounds cool, but I'm a bit unclear on how you'd specify the start and stop point of the label reference. Would you label one sentence at a time?

I come from a LaTeX background, so the include analogy makes perfect sense. The :start at: and :end-before: options would be a useful extension of that functionality. These options work for literalinclude in the simple test from my original post, but are limited (I think?) to creating a code block.

My use case is that I'm writing some scientific software help and documentation. The documentation is a deliverable for an NSF-funded project and also a research product itself. I'd like to provide it as a static website and a downloadable pdf -- MyST seems perfect here.

There are several cases where I want to reproduce a set of instructions -- e.g., a subsection including text and figures. In a digital medium, there's no real need to refer the reader to a different page, so I might as well reproduce the same content on several pages. My understanding is that I can do this with the current include statement if I place the repeated content in its own file and then include it each time I need it -- not a big deal, this is what I would do in LaTeX. But editing and maintenance would be easier if I could reference a portion of an existing page in-place.

Thank you all for your work on MyST -- this is really fun, and I've started another project in Curvenote that I hope to spin up later this summer!