(Feature request) Include only parts of files

[aubertc]

It is my understanding that pandoc-include necessarily includes the included file in its entirety.

Pandoc-include-code have the ability of including only parts of the linked files, either by

• specifying line range,
• "tagging" the included file with comments

Adding such a feature to pandoc-include would be absolutely amazing, but I don't have a good sense of how feasible that is.

[DCsunset]

Thanks for your suggestions. I think the two ways to specify the range are both feasible. Especially, the second approach can be implemented by allowing users to set custom delimiters. I will work on this maybe in a few days.

[aubertc]

Thanks! I'm happy to beta-test it if you want.

[DCsunset]

Hello, I have implemented this feature in the master branch and add some tests under the test directory. You could test it if you have some time.

Feel free to comment here if you have any suggestions.

[aubertc]

I've tested it and it seems to be working quite well (edit: I'm afraid it introduced a bug, though, https://github.com/DCsunset/pandoc-include/issues/19 ). Leaving the start / end markers so open is a nice touch.

I can work on those, but I do have a couple of additional remarks / suggestions (in addition to https://github.com/DCsunset/pandoc-include/commit/4ed50b127d2ee17e3474d616c4f8e8ca27d9fa37#r51230553 ):

• You could specify in the doc that if the same "snippetStart"er is twice in the file, the filter will use the first one,
• You could make explicit that both the "snippetStart" and "snippetEnd" are required (you could imagine that no "snippetEnd" could be interpreted as "until the file terminates", which could be a nice feature, that would be similar to setting endLine to the end of the file by default),
• You could leave an option to decide if the snippet Start / End marker will be added to the output or not, (we could want to mark the limitation of the snippets without adding anything to it),
• You could accommodate negative line numbers, and interpret them as "counting from the end of the file" (this was a feature suggested here in the first place).

Those are my two cents :-)

[aubertc]

The first point is addressed with https://github.com/DCsunset/pandoc-include/pull/18

[DCsunset]

Thanks for your detailed suggestions and work. I think they are all reasonable, and I will try to add those features later.

BTW, the PR has been merged.

(Sorry for the late reply since I am a little busy recently.)

[aubertc]

You're fine, thanks for following, I appreciate. I'm happy to keep testing and editing the instructions, btw.

[DCsunset]

Hello, I have fixed the above issues according to your suggestions and I have already run some tests. You could try to run more tests if you'd like to.

(Sorry for the late update since I am quite busy last month.)

[aubertc]

Thanks a lot. I've tested the last changes quite intensively, and did not see any bug. I have two comments, though, for (possible) further improvments.

1. When using includeSnippetDelimiters=False, I think the rest of the line where the identifier is should be ignored if it's empty. That is, I believe it would be better for

   static void Main()
   {
   /* Start included */
       int yourAge;

   to be rendered with

   int yourAge;

   than with

   
   int yourAge;

(note the white line), especially since modifying the source code to

    static void Main()
    {
/* Start included */ int yourAge;

would seem fairly weird / ugly.

2. Pandoc-include-code offers the possibility of indenting / "dedenting" the included file. I can see at least two use cases for that:

   1. When including a source code, as above, (you would want int yourAge; to lose its indentation),
   2. If the included portion is within a list (or indented for other, similar, reasons). Typically, you may want to "extract" the quote from a snippet like follows:

      
      This is the file I will include in another.

   • This is the first list item.

   • Here's the second list item.

     A blockquote would look great below the second list item.

   • And here's the third list item

     but

     !includesnippetStart=" <!-- Snippet starts -->", snippetEnd="<!-- Snippet ends -->" in.md

     
     will result in the quote being preceded by 4 spaces, transforming it into a code block. I know, that's probably a corner case, but still, it would be nice to be able to "dedent" the included file.

[DCsunset]

Thanks for your detailed suggestions. Both of your comments are reasonable, and I have added these features. Feel free to comment here if there's anything that still needs improving.