include-files: add support for inclusion of source code block from input files

b3 commented 4 years ago

I have just added the use of inclusion for classical code block from source files. I tried to let it be as simple as possible to use.

I took ideas from different sources such as https://groups.google.com/d/msg/pandoc-discuss/mj3G_DRloCs/ncZVJaeGAwAJ.

Even if it seems to work correctly, the code is not that pretty. Some redundancy could be avoided (the loop which parses files name), I do, however, not master lua enough for now to avoid it.

tarleb commented 4 years ago

Thanks for opening this! I'm of two minds here. On one hand, this would be a nice and simple method to extend the filter's functionality. On the other hand, code inclusion is quite different from transclusion, with complex filters dedicated just to code inclusion. This would mean that the filter will grow considerably more complex over time. Not sure if a separate filter would be better?

Also, maybe we should rename this filter to transclude if we decide against code inclusion?

b3 commented 4 years ago

I have no definitive nor sensible ideas on the subject.

I introduced the change because the first time I used the filter to include source code I misused the format attribute. I then looked for other already existing filters. When I found it, I did not want to use the complete dedicated pandoc-include-code one because I would rather use lua ones (easier to get them work since no compilation is necessary).

I agree with you that the filter could grow considerably if features are added specifically for code inclusion, in that case a dedicated filter could have sense (include-code maybe). Some code would be, however, similar in both filters. I do not master lua nor pandoc API enough to say it, but it may be possible that some of the pandoc-include-doc features (I mean Snippets for instance) may not be easy to implement.

Finally I am not sure that the transclude rename would be a good idea. Most people still use the include word instead (I do) and will not be able to find the filter easily with such a different name.

b3 commented 4 years ago

I added a include-code-files filter implementing part of pandoc-include-code, just in case that can make thinks easier to decide.

tarleb commented 4 years ago

The include-code-files filter looks great!

I lean towards the two-filters solution, but would love to hear what others think. If anyone else has an opinion on this, please chime in!

b3 commented 4 years ago

I created distincts PR (and closed this one) in order to ease the inclusion of code, if such a choice would be taken at one point:

128 a simple bugfix of the include-files filter ;
129 my initial modification of the include-files filter to add the possibility to include code from source files ;
130 the introduction of the include-code-files specific filter which mimics the pandoc-include-code behavior (for every aspect but the Snippet feature).

Hope I did not make too much noise and did not introduce to much mistake.

tarleb commented 4 years ago

Excellent, thanks

pandoc / lua-filters

include-files: add support for inclusion of source code block from input files #126

128 a simple bugfix of the `include-files` filter ;

129 my initial modification of the `include-files` filter to add the possibility to include code from source files ;

130 the introduction of the `include-code-files` specific filter which mimics the pandoc-include-code behavior (for every aspect but the Snippet feature).

pandoc / lua-filters

include-files: add support for inclusion of source code block from input files #126

128 a simple bugfix of the include-files filter ;

129 my initial modification of the include-files filter to add the possibility to include code from source files ;

130 the introduction of the include-code-files specific filter which mimics the pandoc-include-code behavior (for every aspect but the Snippet feature).

128 a simple bugfix of the `include-files` filter ;

129 my initial modification of the `include-files` filter to add the possibility to include code from source files ;

130 the introduction of the `include-code-files` specific filter which mimics the pandoc-include-code behavior (for every aspect but the Snippet feature).