(Feature request) Include only parts of files

[Clément Aubert]

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.

[Clément Aubert]

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.

[Clément Aubert]

I've tested it and it seems to be working quite well (edit: I'm afraid it introduced a bug, though, #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 4ed50b1#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 :-)

[Clément Aubert]

The first point is addressed with #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.)

[Clément Aubert]

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.)

[Clément Aubert]

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.
       <!-- Snippet starts -->
       
       > A blockquote would look great below the second list item.
       <!-- Snippet ends -->
   * And here's the third list item 
   

   but

   !include`snippetStart=" <!-- 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.