[moigagoo]

This is useful when including slices of code listings using start-after and end-before:

• code:

#anchorStartProcFoo
proc foo(x: int): int =
  x * 2
#anchorEndProcFoo

discard foo(123)

• include:

.. include:: foo.nim
  :code:
  :hide-lines-starting-with: #anchor

• result:

proc foo(x: int): int =
  x * 2

discard foo(123)

[Araq]

Is this a real RST feature that other RST processors also support?

[moigagoo]

Is this a real RST feature that other RST processors also support?

Not sure about other RST processors, probably not, but this feature brings Nim's include on par with shiftinclude, i.e. we'll be able to use comments as selective inclusion markers while not polluting the code listings.

Compare these:

• https://iftech.github.io/nim-lint/config.html
• https://status-im.github.io/nim-chronos/tutorials/http_client/chapter1.html

Both include the full file first and then explain separate sections. But the first one shows the control comments to the user and the second one doesn't.

[Araq]

If it is non-standard, we might as well do it like this:

.. include:: foo.nim
  :code:
  :from: #anchor :until: #anchor2

[moigagoo]

If it is non-standard, we might as well do it like this:

.. include:: foo.nim
  :code:
  :from: #anchor :until: #anchor2

start-after and end-before are standard though, so it feels strange replacing them with from and until: https://docutils.sourceforge.io/docs/ref/rst/directives.html#include

Also, I would argue that start-after better communicates the intention than from because it is clear that the anchor itself is not included. With from it is not clear IMO.

The only non-standard addition is skip-prefix. This doesn't exist in the rst spec.

[moigagoo]

I am not happy with the name skip-prefix... It just doesn't do a good job explaining what it does.

Also, I think it is reasonable to provide a default value for this option, e.g. #ANCHOR. This way it is immediately compatible with mdBook's syntax: https://rust-lang.github.io/mdBook/format/mdbook.html#including-files

I've moved the PR to draft.

[Araq]

start-after and end-before are standard though

Yeah, so implement that one then.

[moigagoo]

start-after and end-before are standard though

Yeah, so implement that one then.

I implemented only skip-prefix (now renamed to hide-lines-starting-with). I did not touch pre-existing :start-after: or :end-before:.

[Araq]

I did not touch pre-existing :start-after: or :end-before:.

I had no idea we already had these. So simply use them, why even add more of the same here?