Following up on my previous email about updating `org-babel-execute:latex' for the org-latex-preview patchset:
I'm having trouble understanding what header options this function supports. Here is a list of relevant header args from the let-bindings inside this function. `params' is the plist of header args: ((out-file (cdr (assq :file params))) (border (cdr (assq :border params))) (imagemagick (cdr (assq :imagemagick params))) (im-in-options (cdr (assq :iminoptions params))) (im-out-options (cdr (assq :imoutoptions params))) (fit (or (cdr (assq :fit params)) border)) (height (and fit (cdr (assq :pdfheight params)))) (width (and fit (cdr (assq :pdfwidth params)))) (headers (cdr (assq :headers params))) (in-buffer (not (string= "no" (cdr (assq :buffer params))))) (org-latex-packages-alist (append (cdr (assq :packages params)) org-latex-packages-alist))) This is for blocks of the form #+begin_src latex ... ... #+end_src My understanding and questions: :file is the standard header-arg that all babel blocks support, to be used with `:result file'. Is `:file' a required argument for these blocks? If :file is not required and not supplied, what type should the result be? What should happen if `:result' is set to `value', `output' or `code'? :imagemagick is to force use of imagemagick to produce the image. But what if the :file specified is a .svg or .pdf? :iminoptions and :imoutoptions -- these are only meant to be used along with :imagemagick. Where is this documented? The :fit, :pdfheight, :pdfwidth and :border options are only meant to be used when :file has extension .pdf or when :imagemagick is true. Where is this documented? :headers is added to LaTeX header for the conversion. How should :headers be specified in the header line? Also :headers is ignored for most :file extension types. Where is this documented? How should :packages be specified in the header line? Also :packages is ignored for most :file extension types. Where is this documented? What is the purpose of :buffer here? When the file extension is .tikz, the contents of the block are returned verbatim in :file: ((string-suffix-p ".tikz" out-file) (when (file-exists-p out-file) (delete-file out-file)) (with-temp-file out-file (insert body))) Why are we doing this? Where is this documented? When the :file extension is .svg, the current process requires inkscape to be installed. Where is this documented? When the :file extension is .html, none of the other header args are respected. Further, there are clauses in the html case that check for .svg extension that can never trigger. --------------------- My opinion is that this function is a big mess that is difficult to understand, use or maintain. There are several incompatiable or unrespected header args, and there is no indication of what header args are available or which header args can be fruitfully combined. My suggestion is that parts of `org-babel-execute:latex' need to be rewritten. Here is what I propose: 1. Output file extension html: Leave the current code untouched. This does not respect any of the other header arguments and requires htlatex, and it will continue to be a special case. 2. Output file type pdf: Leave unchanged. Supports header args :header, :packages, :fit, :border, :pdfwidth and :pdfheight. 3. Output file type tikz: No change, just insert the body of the babel block into the file. 4. Output file type png or svg: Handle using org-latex-preview. Remove dependence on inkscape. Supported header args will be :headers and :packages. No support for :fit, :border, :pdfwidth, :pdfheight etc -- this is the current behavior as well. 5. Remove the :buffer header arg. 6. Header-arg :imagemagick: I don't know what to do. 7. On the whole, the behavior of this function will still be idiosyncratic, incosistent, confusing and undocumented. Documenting the combinations of allowed header args somewhere can help. Where should this user-facing documentation go? `org-babel-execute:latex' is not a user-facing function so it can't be its docstring. Karthik
