CDSoft
commented
7 years ago A lightweight workaround is using sed, head, tail instead of AsciiDoctor:
\pp(\sh(sed '1,3d' filename))removes the first 3 lines of a file and includes it\pp(\sh(sed -e '3,5p' -e 'd' filename))keeps lines 3 to 5\pp(\sh(sed -e '/tag1/,/tag2/p' -e 'd' filename))keeps lines between "tag1" and "tag2" (included)
A builtin macro would be better for portability. I have to find a way to add an optional argument to include and rawinclude. And maybe also src and csv.
It would be nice to have a macro to include only specific lines from an external file. I was thinking of something along the lines of AsciiDoctor's
includedirective:It allows to specify multiple lines and/or lines-ranges. Something like:
AsciiDoctor also allows to include file regions defined in the source doc via tags:
... region-tags are just paired opend/close tags in commented lines (using the target language's native commenting convention) which are formatted in a way that AsciiDoctor can reckognize during parsing — the commented lines are then omitted from the final emitted text, as well as from line-counting operations.
This last feature might be excessive, but it proves the point that when dealing with external source code files there is often a need to select specifc parts of the code from a same file — instead of having to either split the file in multiple parts or copy and paste those parts in the markdown/rst source.
This would make maintainance of code documentation much easier, especially so the tagged regions feature since it grants that even if the code changes the targeted include-part will always remain the same. It would, for example, allow commenting a long source file by including specific line-ranges, and have the doc reflect any changes made to the original file.
Currenty, I'm achieving this via a PP macro than invokes AsciiDoctor on the external source file. A small CLI binary could be created to achieve the same withouth requiring users to install Ruby and AsciiDoctor. But having this functionality built-in into PP would improve speed because it could be handled without having PP temporarily handle over control to an external tool/script.
Beside adding a new macro for this purpose, some of the existing built-in macros that deal with code and external files could integrate this feature (optionally).
These features would augment PP's support for literate code too.
What's your view on this? Is it something worth of being built-in or it should be handled as a custom macro via third party tools/scripts?