Re: [PATCH] Justify/align image previews in org-mode

[Ihor Radchenko]

Karthik Chikmagalur <karthikchikmagalur@gmail.com> writes:

> I've incorporated the following suggestions:
>
> - Order of precedence:
>   + #+attr_org overrides #+attr_html and #+attr_latex
>   + `:center t' overrides `:align ...'

Why only html and latex? I think that it will be more consistent to
follow what we do in `org-display-inline-image--width' - any #+attr_*
attribute. And apart from html/latex, we have
beamer/hugo/koma-letter/what not is implemented or will be implemented
deriving from html/latex backend or with support of :center attribute.

> - Add a checker for `:align nil' to org-lint.  `:align nil' is not
>   supported.

I meant :align <anything> being not supported in #+attr_org. Not just nil.

> +  #+vindex: org-image-align
> +  Org mode can left-align, center or right-align the display of inline
> +  images.  This setting is controlled (globally) by ~org-image-align~.
> +  Only standalone links, /i.e/ links with no surrounding text in their

Maybe "standalone images"?
Also, please avoid i.e - this is a general Emacs documentation guideline
to avoid specialized language like i.e., e.g., and iff.

> +  paragraphs (except whitespace) are affected.  Its value can be the
> +  following:
> +  - (default) nil, insert the image where the link appears in the
> +    buffer.

Why not simply setting the default to 'left and not having nil at all?

> +  - The symbol ~left~, which is the same as nil.
> +  - The symbol ~center~, which will preview standalone links centered
> +    in the Emacs window.
> +  - The symbol ~right~, which will preview standalone links
> +    right-aligned in the Emacs window.

"standalone" links is redundant here - you already mentioned that  

> +  Inline image alignment can be specified for each link using the
> +  =#+ATTR.*= keyword if it matches an alignment specification like:
> +  #+begin_example
> +  ,#+ATTR_HTML: :align center
> +  #+end_example
> +  Supported values for =:align= are =left=, =center= and =right=.

I think that we do not need to specify the supported values here - they
are the same as for `org-image-align' just above.

> +  Inline image display can also be centered using =:center=, as in

I'd explain that inline image adjustment is also taken from :center
attribute supported by some export backends (like HTML, LaTeX, and
Beamer), when #+attr_org is not set.

> +  #+begin_example
> +  ,#+ATTR_HTML: :center t
> +  #+end_example
> +  Org will use the alignment specification from any =#+ATTR.*=
> +  keyword, such as =#+ATTR_HTML= or =#+ATTR_LATEX=, but =#+ATTR_ORG=
> +  (if present) will override the others.  For instance, this link
> +  #+begin_example
> +  ,#+ATTR_HTML: :align right
> +  ,#+ATTR_ORG: :align center
> +  [[/path/to/image/file.png]]
> +  #+end_example
> +  will be displayed centered.

... "but exported right-aligned to HTML"

> +(defun org-lint-invalid-image-alignment (ast)
> +  (org-element-map ast 'paragraph
> +    (lambda (p)
> +      (let ((bad-align-re ":align[[:space:]]+nil")
> +            (keyword-string (mapconcat
> +                             (lambda (attr)
> +                               (or (car-safe (org-element-property attr p)) 
> ""))
> +                             '(:attr_org :attr_latex :attr_html) " ")))

:align nil is perfectly valid for HTML.
I thought to warn only about using anything but :align left/right/center
in #+attr_org. And about :center <anything> in #+attr_org.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>