Karthik Chikmagalur <karthikchikmaga...@gmail.com> writes: > 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: > ... > 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?
As you can see from the code, code body (expanded) is returned when no :file is specified. > What should happen if `:result' is set to `value', `output' or > `code'? This is currently undefined (code evaluation with :file is for side effects). Unless you are willing to do more work, there is no reason to implement value/output/code output. > :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? https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-LaTeX.html > :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? Looks like it is also only for pdf. (judging from worg docs) > How should :packages be specified in the header line? Also :packages is > ignored for most :file extension types. Where is this documented? I presume that it should be a lisp expression (whichever works in practice). This header argument is undocumented. > What is the purpose of :buffer here? See https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-LaTeX.html > 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? https://list.orgmode.org/orgmode/87zjtkeul6....@med.uni-goettingen.de/ They forgot to document this feature. > When the :file extension is .svg, the current process requires inkscape > to be installed. Where is this documented? Does not seem to be 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. This area is buggy. > My opinion is that this function is a big mess that is difficult to > understand, use or maintain. +1 > 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. +1 > 5. Remove the :buffer header arg. Check https://orgmode.org/worg/org-contrib/babel/languages/ob-doc-LaTeX.html :buffer sounds like a feature. > 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. I hope that reading the WORG documentation is going to help. -- Ihor Radchenko // yantar92, Org mode maintainer, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>
