diff options
| -rw-r--r-- | Master/texmf-dist/doc/context/third/filter/filter.txt | 148 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/context/third/filter/t-filter.tex | 99 |
2 files changed, 187 insertions, 60 deletions
diff --git a/Master/texmf-dist/doc/context/third/filter/filter.txt b/Master/texmf-dist/doc/context/third/filter/filter.txt index 6487c818d89..62243a553ca 100644 --- a/Master/texmf-dist/doc/context/third/filter/filter.txt +++ b/Master/texmf-dist/doc/context/third/filter/filter.txt @@ -37,9 +37,9 @@ Installation ------------ Writing installation instructions is always boring. If you are using ConTeXt -minimals, you can install the module using +standalone, you can install the module using - first-setup.sh --extras="t-filter" + first-setup.sh --modules="t-filter" Depending on your TeX distribution, you may already have the module. To verify, check if @@ -158,6 +158,20 @@ definition: continue=yes, ...] +Sometimes you want to force a rerun of all filters, even when `continue=yes` is +set. This could be because the filters depend on an external script that might +have changed. To force a rerun of all filters, enable the +[mode](http://wiki.contextgarden.net/Modes) `force` either by adding +`mode=force` to the compiler: + + context --mode=force filename + +or adding + + \enablemode[force] + +somewhere near the top of your file. + Reading the input ---------------- @@ -254,29 +268,36 @@ do not work. If you try to use a absolute path like you will get an error message - t-filter : Fatal Error: Cannot use absolute path /tmp/ as directory + t-filter > Fatal Error: Cannot use absolute path /tmp/ as directory and compilation will stop. -Deleting temporary files ------------------------- +Disabling filters +---------------- -If you want to delete the temporary files generated by the module, pass -`--purge` option while calling `context`: +Adding `state=stop` option disables the filters. The +`\externalfilterinputfile` is still written, but the filter is not run. - context --purge filename +When used in conjunction with `continue=yes` and `directory=...`, this +is useful for sharing your files with others who do not have the +external program that you are using. -This will delete the temporary files at the end of the compilation. When using -`continue=yes`, deleting the files after each compilation defeats the purpose of -caching the results. In that case, it is better to simply use +Enabling the `reuse` mode (before the `filter` module is loaded) sets +`state=stop` as the default value. - context filename +Deleting temporary files +------------------------ -Once you are finished with your project and want to clean up the working -directory, call: +To delete the temporary files generated by the module, call + + context --purgeall --pattern=filename + +Do **not** use the file extension. To delete all temporary files in the +current directory, use context --purgeall + Standard options --------------- @@ -420,6 +441,71 @@ options: The options in the `[...]` are the same as those for `\defineexternalfilter`. +Prepend and append text +----------------------- + +**NOTE** Only works in MkIV + +Some external programs require boilerplate text at the beginning and end of each +file. Including this boilerplate code in each snippet can get verbose. The +filter module provides two options `bufferbefore` and `bufferafter` to shorten +such snippets. Define the boilerplate code in ConTeXt buffers and then use + + \defineexternalfilter + [...] + [... + bufferbefore={...list of buffers...}, + bufferafter={...list of buffers...}, + ] + +For example, suppose you want to generate images using a latex package that does +not work well with ConTeXt, say shak. One way to use this is as follows: first +define a file that processes its content using `latex`. + + \defineexternalfilter + [chess] + [filter=pdflatex, + output=\externalfilterbasefile.pdf, + readcommand=\readPDFfile, + ] + + \def\readPDFfile#1{\externalfigure[#1]} + + +Next create buffers containing boilerplate code needed to run latex: + + \startbuffer[chess::before] + \documentclass{minimal} + \usepackage{skak} + \usepackage[active,tightpage]{preview} + + \begin{document} + \begin{preview} + \newgame + \hidemoves{ + \stopbuffer + + \startbuffer[chess::after] + } + \showboard + \end{preview} + \end{document} + \stopbuffer + +and tell the filter to prepend and append these buffers + + \setupexternalfilter + [chess] + [bufferbefore={chess::before}, + bufferafter={chess::after}] + +Then you can use + + \inlinechess{1.e4 e5 2. Nf3 Nc6 3.Bb5} + +to get a chess board. + + Limitations ------------ @@ -447,32 +533,28 @@ indicate what is happening. Loading of the module is indicated by: Whenever a filter is executed, the expanded name of the command is displayed. For example, for the markdown filter we get: - t-filter : command : pandoc -w context -o markdown-temp-markdown.tex markdown-temp-markdown.tmp + t-filter > command : pandoc -w context -o markdown-temp-markdown.tex markdown-temp-markdown.tmp If, for some reason, the output file is not generated, or not found, a message similar to - t-filter : file markdown-temp-markdown.tex cannot be found + t-filter > file markdown-temp-markdown.tex cannot be found + t-filter > current filter : markdown + t-filter > base file : markdown-temp-markdown + t-filter > input file : markdown-temp-markdown.tmp + t-filter > output file : markdown-temp-markdown.tex is displayed on the console. At the same time, the string [[output file missing]] -is displayed in the PDF output. To debug what went wrong, add +is displayed in the PDF output. This data, along with the name of the filter +command, is useful for debugging what went wrong. To get more debugging +information add \traceexternalfilters -in your tex file. This shows the name of all input and output files on the -console: - - t-filter : current filter : markdown - t-filter : base file : markdown-temp-markdown - t-filter : input file : markdown-temp-markdown.tmp - t-filter : output file : markdown-temp-markdown.tex - -This data, along with the name of the filter command, is useful for debugging -what went wrong. - +in your tex file. This shows the name of the filters when they are defined. Version History @@ -502,8 +584,16 @@ Version History - **2011.02.27** - The external files are called `\jobname-temp-<filter>*` instead of `\jobname-externalfilter-<filter>*`. As a result, these files are deleted - by `context --purge`. + by `context --purgeall`. - **2011.03.06** - Complete rewrite of internal macro names. The internal macros are now named `\modulename::command_name`. This is an experiment to see if this style works better than the traditional naming convention in TeX. +- **2011.06.16** + - Added `force` mode to force recompilation of all filters that have + `continue=yes`. + - Added `reuse` mode to skip running all filters that have + `continue=yes`. + - Added `state=stop` option to skip running external filter. +- **2011.08.23** + - Added `bufferbefore` and `bufferafter` options diff --git a/Master/texmf-dist/tex/context/third/filter/t-filter.tex b/Master/texmf-dist/tex/context/third/filter/t-filter.tex index 6f95644953f..2d89f168ef4 100644 --- a/Master/texmf-dist/tex/context/third/filter/t-filter.tex +++ b/Master/texmf-dist/tex/context/third/filter/t-filter.tex @@ -1,6 +1,6 @@ %D \module %D [ file=t-filter, -%D version=2011.06.12, +%D version=2011.08.23, %D title=\CONTEXT\ User Module, %D subtitle=Filter, %D author=Aditya Mahajan, @@ -36,15 +36,6 @@ \setinterfaceconstant {readcommand} {readcommand} \stopinterface -\def\m!externalfilter{t-filter} - -%D \subsubject {Messages} - -\setinterfacemessage{externalfilter}{title} {\m!externalfilter} -\setinterfacemessage{externalfilter}{notfound} {file -- cannot be found} -\setinterfacemessage{externalfilter}{missing} {output file missing} -\setinterfacemessage{externalfilter}{forbidden} {Fatal Error: Cannot use absolute path -- as directory} -\setinterfacemessage{externalfilter}{slash} {Appending / to directory -- } %D \subsubject {Name space} @@ -62,6 +53,17 @@ \doifmode\s!mkiv {\installattributehandler \externalfilter::namespace \externalfilter::id} +\def\m!externalfilter{t-filter} + +%D \subsubject {Messages} + +\setinterfacemessage\m!externalfilter{title} {\m!externalfilter} +\setinterfacemessage\m!externalfilter{notfound} {file -- cannot be found} +\setinterfacemessage\m!externalfilter{missing} {output file missing} +\setinterfacemessage\m!externalfilter{forbidden} {Fatal Error: Cannot use absolute path -- as directory} +\setinterfacemessage\m!externalfilter{slash} {Appending / to directory -- } +\setinterfacemessage\m!externalfilter{reuse} {\c!state=\v!stop : Not running filter on file --} + % For backward compatibility \let\setupexternalfilters \setupexternalfilter @@ -72,12 +74,10 @@ \let\traceexternalfilters\traceexternalfilterstrue \starttexdefinition externalfilter::show_filenames - \iftraceexternalfilters - \writestatus\m!externalfilter{current filter : \externalfilter::name} - \writestatus\m!externalfilter{base file : \externalfilter::base_file} - \writestatus\m!externalfilter{input file : \externalfilter::input_file} - \writestatus\m!externalfilter{output file : \externalfilter::output_file} - \fi + \writestatus\m!externalfilter{current filter : \externalfilter::name} + \writestatus\m!externalfilter{base file : \externalfilter::base_file} + \writestatus\m!externalfilter{input file : \externalfilter::input_file} + \writestatus\m!externalfilter{output file : \externalfilter::output_file} \stoptexdefinition \starttexdefinition externalfilter::show_status #1 @@ -100,8 +100,8 @@ \starttexdefinition externalfilter::define [#1][#2] \externalfilter::show_status{defining filter : #1} + \setupexternalfilter[#1][\s!parent=\externalfilter::namespace,#2] \edef\externalfilter::name{#1} - \getparameters[\externalfilter::namespace#1][\s!parent=\externalfilter::namespace,#2] \doif{\externalfilterparameter\c!continue}\v!yes {\expandafter\newcounter\csname\externalfilter::count\endcsname} @@ -111,6 +111,7 @@ \setvalue{process#1file}{\dodoubleargument\externalfilter::process_file[#1]} \setvalue{inline#1}{\externalfilter::inline[#1]} + \stoptexdefinition \starttexdefinition externalfilter::start [#1][#2] @@ -121,7 +122,7 @@ \edef\externalfilter::name{#1} \begingroup % to keep assignments local - \getparameters[\externalfilter::namespace#1][\c!name=,#2] + \setupexternalfilter[#1][\c!name=,#2] \externalfilter::set_filenames @@ -133,7 +134,7 @@ \begingroup \edef\externalfilter::name{#1} - \getparameters[\externalfilter::namespace#1][\c!name=,#2] + \setupexternalfilter[#1][\c!name=,#2] \externalfilter::set_directory @@ -146,7 +147,7 @@ % \c!directory; even if the input is from some other directory \def\externalfilter::output_file{\externalfilter::get_directory\externalfilterparameter\c!output} - \externalfilter::show_filenames + \iftraceexternalfilters \externalfilter::show_filenames \fi \externalfilter::execute_filter \externalfilter::read_processed_file @@ -157,7 +158,7 @@ \edef\externalfilter::name{#1} \begingroup % to keep assignments local - \getparameters[\externalfilter::namespace#1][\c!name=] + \setupexternalfilter[#1][\c!name=] \externalfilter::set_filenames @@ -165,6 +166,7 @@ \futurelet\next\externalfilter::inline_aux \stoptexdefinition + %D \subsubject {Catcode tables} %D %D Just to be sure, I define all catcode tables that are needed within the @@ -272,13 +274,13 @@ \starttexdefinition externalfilter::set_directory_aux \doif{\externalfilter::get_first_character\externalfilter::get_directory}{/} {\writeline - \showmessage\externalfilter::id{forbidden}\externalfilter::get_directory + \showmessage\m!externalfilter{forbidden}\externalfilter::get_directory \batchmode \errmessage{} \normalend} \doifnot{\externalfilter::get_last_character\externalfilter::get_directory}{/} - {\showmessage\externalfilter::id{slash}\externalfilter::get_directory + {\showmessage\m!externalfilter{slash}\externalfilter::get_directory \edef\externalfilter::get_directory{\externalfilter::get_directory/}} \stoptexdefinition @@ -320,7 +322,7 @@ % Append directory name to the name of the output file \edef\externalfilter::output_file{\externalfilter::get_directory\externalfilterparameter\c!output} - \externalfilter::show_filenames + \iftraceexternalfilters \externalfilter::show_filenames \fi \stoptexdefinition @@ -330,7 +332,25 @@ \starttexdefinition externalfilter::process_filter % By defualt, buffers are in memory in MkIV. So, we save them to disk - \doifmode\s!mkiv{\savebuffer[\externalfilter::temp_file][\externalfilter::input_file]} + % To imitate the behavior of MkII, we need + % + % \doifmode\s!mkiv{\savebuffer[\externalfilter::temp_file][\externalfilter::input_file]} + % + % However, in MkIV, we can save a list of buffers to a file. The empty + % elements of the list are ignored. So, instead we use the following + %\doifmode\s!mkiv + %{\savebuffer[\externalfilterparameter{\c!buffer\c!before},\externalfilter::temp_file,\externalfilterparameter{\c!buffer\c!after}] + % [\externalfilter::input_file]} + \startmode[\s!mkiv] + \savebuffer[\externalfilterparameter{\c!buffer\c!before}, + \externalfilter::temp_file, + \externalfilterparameter{\c!buffer\c!after}] + [\externalfilter::id] + \startluacode + os.rename("\jobname-\externalfilter::id.\f!temporaryextension", "\externalfilter::input_file") + \stopluacode + \stopmode + \externalfilter::execute_filter \externalfilter::read_processed_file @@ -351,10 +371,16 @@ \externalfilter::show_filtercommand \doifelse{\externalfilterparameter\c!continue}\v!yes - {\doifmode{*first} - {\executesystemcommand - {mtxrun --ifchanged=\externalfilter::input_file\space - --direct \externalfilterparameter\c!filtercommand}}} + {\doifelse{\externalfilterparameter\c!state}\v!stop + {\showmessage\m!externalfilter{reuse}\externalfilter::input_file} + {\doifmode{*first} + {\doifmodeelse{force} + {\message{\externalfilterparameter\c!filtercommand} + \executesystemcommand + {\externalfilterparameter\c!filtercommand}} + {\executesystemcommand + {mtxrun --ifchanged=\externalfilter::input_file\space + --direct \externalfilterparameter\c!filtercommand}}}}} {\executesystemcommand {\externalfilterparameter\c!filtercommand}} \stoptexdefinition @@ -365,9 +391,10 @@ \doif{\externalfilterparameter\c!read}\v!yes {\doiffileelse{\externalfilter::output_file} {\externalfilter::read_processed_file_aux} - {\showmessage\externalfilter::id{notfound}\externalfilter::output_file + {\showmessage\m!externalfilter{notfound}\externalfilter::output_file + \externalfilter::show_filenames \blank - {\tttf [[\getmessage\externalfilter::id{missing}]]} + {\tttf [[\getmessage\m!externalfilter{missing}]]} \blank}} \stoptexdefinition @@ -402,12 +429,22 @@ \c!output=\externalfilterbasefile.tex, \c!filter=, \c!filtercommand={\externalfilterparameter\c!filter\space \externalfilter::input_file}, + \c!buffer\c!before=, + \c!buffer\c!after=, ] +\doifmodeelse{reuse} + {\setupexternalfilters[state=stop]} + {\setupexternalfilters[state=start]} + \def\externalfilterbasefile {\externalfilter::base_file} \def\externalfilterinputfile {\externalfilter::input_file} \def\externalfilteroutputfile{\externalfilter::output_file} \def\currentexternalfilter {\externalfilter::name} + +% Default value +\def\externalfilter::input_file {} +\def\externalfilter::output_file{} \protectmodulecatcodes \stopmodule |