Re: [RFC] Draft mode

[Aaron Ecay <aaronecay@gmail.com>]

Hi Nicolas,

This looks like a useful addition.

2015ko irailak 27an, "Charles C. Berry"-ek idatzi zuen:
> 
> On Sun, 27 Sep 2015, Nicolas Goaziou wrote:
> 
>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>> 
>>> The following patch implements a draft mode for export. When in draft
>>> mode, invalid macros and links do not throw an error. It can be toggled
>>> with `org-export-as-draft' variable, or using C-d in export dispatch.
>>> 
>>> It introduces a backward incompatible change since it modifies signature
>>> from `org-export-as' and alike.
>>> 
> 
> I don't get it.
> 
> Why not add the `draft' arg to the end of the `&optional' args? Won't that 
> preserve backward compatibility?
> 
> I maintain derived backends that use the `post-process' arg and are 
> distributed on github. So now I will need to make them version aware 
> and/or provide version specific branches so as not to break when used with 
> older org-mode versions, won't I?

This is a very good point.  OTOH, if backwards compatibility is going to
be broken, wouldn’t it be better to move to a keyword argument system?
IOW, the signature of ‘org-export-as’ and friends would change from:

(backend &optional subtreep visible-only body-only ext-plist)

to (using cl-defun):

(backend &key subtreep visible-only body-only ext-plist draft)

This would allow future changes to the API of this function without
breaking backwards compatibility.  It would also clean up messy
constructs like:

(lambda (a s v b d)
  (if a (org-org-export-to-org t s v b d)
    (org-open-file (org-org-export-to-org nil s v b d))))

which could become:

(lambda (&rest kwargs)
  (if (plist-get kwargs :async)
      (apply #'org-org-export-to-org kwargs)
    (org-open-file (apply #'org-org-export-to-org kwargs))))

and with further simplification the following, which is vastly clearer
than the original:

(lambda (&rest kwargs)
  (let ((result (apply #'org-org-export-to-org kwargs)))
    (unless (plist-get kwargs :async) (org-open-file result))))

Since this stanza recurs in the code for most (all?) backends, there’s
some value that org core can provide to backend authors by making it as
simple as possible.

With a non-trivial effort, the old calling convention could still be
supported (if the argument after ‘backend’ is not a :keyword, then
org-export-as knows that the old convention is in use, and it should
map the arguments 2 through 5 to the relevant keywords).  It could
trigger a deprecation warning and be phased out with the next major
version (or whenever).

On a different note, does this scheme make it possible for a backend
to see whether draft mode is enabled?  Latex provides a document-level
draft option, which enables certain optimizations that speed up compile
times (for example, graphics are not read in, but are replaced with a
placeholder).  It would be nice if ox-latex could emit this in the latex
code when draft mode is enabled from the org side.

Thanks,

-- 
Aaron Ecay