Patch adding from-logo commentary ox-koma-letter.el

Patch adding from-logo commentary ox-koma-letter.el

[Grant Rettke]

[-- Attachment #1: Type: text/plain, Size: 328 bytes --]

On Sat, Apr 28, 2018 at 1:32 AM, Bastien <bzg@gnu.org> wrote:
> Hi Grant,
>
> Grant Rettke <gcr@wisdomandwonder.com> writes:
>
>> Here is how it works, the same way as the other ones:
>
> If needed, don't hesitate to advertize this in the comment section
> of the code.

Here is a patch to a commentary on how to use FROM_LOGO.

[-- Attachment #2: 0001-exporters-koma-letter-export.org-Add-FROM_LOGO-comme.patch --]
[-- Type: application/octet-stream, Size: 1609 bytes --]

From 324fc4dc82d929cb9310d8f491b6613c421e6a6c Mon Sep 17 00:00:00 2001
From: Grant Rettke <gcr@wisdomandwonder.com>
Date: Mon, 18 Jun 2018 12:14:04 -0500
Subject: [PATCH] * exporters/koma-letter-export.org: Add FROM_LOGO commentary.

* koma-letter-export.org: Enhance commentary on FROM_LOGO

Using FROM_LOGO is noticeably different than using the other options because:

1. It requires providing an image file for the logo.

2. It requires providing LaTeX markup to specify that logo.

Although the function document ion mentions the markup to use, it
doesn't explain that the user needs to provide a logo file in the same
directory as the letter.
---
 contrib/lisp/ox-koma-letter.el | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index fc6599fe7..4c09b456a 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -77,6 +77,12 @@
 ;;     (See also `org-koma-letter-author'),
 ;;   - EMAIL: Same as AUTHOR. (see also `org-koma-letter-email'),
 ;;
+;; Unlike using other variables, FROM_LOGO requires LaTeX markup and
+;; an image file for the logo. This is the markup to provide:
+;; \includegraphics{logo}. It's argument is the name of the logo file
+;; but without the file extension. The logo file needs to be located in
+;; the same directory as the letter that you are writing.
+;;
 ;; Headlines are in general ignored.  However, headlines with special
 ;; tags can be used for specified contents like postscript (ps),
 ;; carbon copy (cc), enclosures (encl) and code to be inserted after
-- 
2.17.1

Re: Patch adding from-logo commentary ox-koma-letter.el

[Nicolas Goaziou]

Hello,

Grant Rettke <gcr@wisdomandwonder.com> writes:

> Although the function document ion mentions the markup to use, it
> doesn't explain that the user needs to provide a logo file in the same
> directory as the letter.

Is it really necessary? Couldn't you use, e.g., \includegraphics{subdir/logo}

regards,

-- 
Nicolas Goaziou

Re: Patch adding from-logo commentary ox-koma-letter.el

[Grant Rettke]

On Tue, Jun 19, 2018 at 3:11 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Hello,
>
> Grant Rettke <gcr@wisdomandwonder.com> writes:
>
>> Although the function document ion mentions the markup to use, it
>> doesn't explain that the user needs to provide a logo file in the same
>> directory as the letter.
>
> Is it really necessary?

If you are comfortable with LaTeX, then it probably isn't necessary
because you already know how \includegraphics{logo} works, or you
would look it up.

When I wrote this, I felt like because ox-koma-letter makes it so easy
for non LaTeX Org users, that a reminder would help because this
variable is I think the only one that requires any LaTeX knowledge.

That was the context for my statement. I'm making a big assumption
that non latex org users would benefit here.

> Couldn't you use, e.g., \includegraphics{subdir/logo}

Yes.

If you like the additional documentation, then I will update it with
this and send a new patch.

WDYT?

Re: Patch adding from-logo commentary ox-koma-letter.el

[Van L]

> If you like the additional documentation,
> then I will update it with
> this and send a new patch.

Can the documentation in the standard distribution 
include step-by-step example using XeTeX comparing 
plain TeX and LaTeX for writing a letter to PDF 
with an SVG logo placed well?

Re: Patch adding from-logo commentary ox-koma-letter.el

[Nicolas Goaziou]

Hello,

Grant Rettke <gcr@wisdomandwonder.com> writes:

> When I wrote this, I felt like because ox-koma-letter makes it so easy
> for non LaTeX Org users, that a reminder would help because this
> variable is I think the only one that requires any LaTeX knowledge.
>
> That was the context for my statement. I'm making a big assumption
> that non latex org users would benefit here.

The problem is that your assumption makes the wording inaccurate.
I think it would be better to expound this a bit, maybe with a couple of
examples, or by using meta syntactic variables:

  \includegraphics{path/to/logo}

> If you like the additional documentation, then I will update it with
> this and send a new patch.

Let's first merge the complete documentation, then apply it, if you
don't mind.

Thank you.

Regards,

-- 
Nicolas Goaziou

Re: Patch adding from-logo commentary ox-koma-letter.el

[Grant Rettke]

[-- Attachment #1: Type: text/plain, Size: 464 bytes --]

On Thu, Jun 21, 2018 at 4:37 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Grant Rettke <gcr@wisdomandwonder.com> writes:
>> If you like the additional documentation, then I will update it with
>> this and send a new patch.
>
> Let's first merge the complete documentation, then apply it, if you
> don't mind.

Happy to, mistakenly said patch.

Here is the new version. I included detail and examples.

The first one I sent was, well, woefully inadequate!

[-- Attachment #2: 0001-ox-koma-letter.el-Adds-FROM_LOGO-example.patch --]
[-- Type: application/octet-stream, Size: 2991 bytes --]

From b12a9f806cfc218bee2cfff1e550341f5999c70d Mon Sep 17 00:00:00 2001
From: Grant Rettke <gcr@wisdomandwonder.com>
Date: Sat, 23 Jun 2018 20:08:09 -0500
Subject: [PATCH] ox-koma-letter.el: Adds FROM_LOGO example

FROM_LOGO uses LaTeX markup probably unfamiliar to the user.

This example provides detailed documentation and examples of it's use.
---
 contrib/lisp/ox-koma-letter.el | 37 ++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el
index 37ea4d04c..77dc4ccac 100644
--- a/contrib/lisp/ox-koma-letter.el
+++ b/contrib/lisp/ox-koma-letter.el
@@ -77,6 +77,43 @@
 ;;     (See also `org-koma-letter-author'),
 ;;   - EMAIL: Same as AUTHOR. (see also `org-koma-letter-email'),
 ;;
+;; Unlike other variables, FROM_LOGO uses LaTeX markup. FROM_LOGO
+;; provides the 'includegraphics' command to tell LaTeX where to find
+;; the logo. 'includegraphics' needs to know the logo's directory and
+;; file name. The directory can either be relative or absolute, just
+;; as you would expect. LaTeX can use three file types for the logo:
+;; PDF, JPEG, or PNG. The logo can either include or exclude its
+;; extension, which might surprise you. When you exclude its
+;; extension, LaTeX will search the directory for the "best" quality
+;; graphics format. For example if it finds both logo.pdf and logo.png
+;; then it will identify the PDF as "better", and include
+;; logo.pdf. This can be useful, for example, when you are mocking up
+;; a logo in the PNG raster format and then switch over to the higher
+;; quality PDF vector format. When you include the file extension then
+;; LaTeX will include it without searching for higher quality file
+;; types. Whatever file type you choose, it will probably require a
+;; few design iterations to get the best looking logo size for your
+;; letter. Finally, the directory and file name are specified
+;; *without* quotes. Here are some examples with commentary, in the
+;; location of your letter, with a logo named 'logo', to get you
+;; started:
+;;
+;;   Logo in the same directory: \includegraphics{logo}
+;;       or a sub-directory:     \includegraphics{logos/production/logo}
+;;
+;;   Logos specified using absolute paths on Linux or Windows:
+;;
+;;       \includegraphics{/Users/you/correspondence/logo}
+;;       \includegraphics{/Users/you/correspondence/logos/production/logo}
+;;       \includegraphics{c:/you/correspondence/correspondence/logo}
+;;       \includegraphics{c:/you/correspondence/correspondence/logos/production/logo}
+;;
+;;   Logos in the same directory where the "better" quality PDF will
+;;   be chosen over the JPG:
+;;
+;;       \includegraphics{logo.pdf}
+;;       \includegraphics{logo.png}
+;;
 ;; Headlines are in general ignored.  However, headlines with special
 ;; tags can be used for specified contents like postscript (ps),
 ;; carbon copy (cc), enclosures (encl) and code to be inserted after
-- 
2.18.0

Re: Patch adding from-logo commentary ox-koma-letter.el

[Nicolas Goaziou]

Hello,

Grant Rettke <gcr@wisdomandwonder.com> writes:

> From b12a9f806cfc218bee2cfff1e550341f5999c70d Mon Sep 17 00:00:00 2001
> From: Grant Rettke <gcr@wisdomandwonder.com>
> Date: Sat, 23 Jun 2018 20:08:09 -0500
> Subject: [PATCH] ox-koma-letter.el: Adds FROM_LOGO example
>
> FROM_LOGO uses LaTeX markup probably unfamiliar to the user.
>
> This example provides detailed documentation and examples of it's use.

I applied it with some minor changes.

> +;; Unlike other variables, FROM_LOGO uses LaTeX markup. FROM_LOGO

I removed the "unlike other variables", which isn't true.

> +;; provides the 'includegraphics' command to tell LaTeX where to find
> +;; the logo. 'includegraphics' needs to know the logo's directory and

I added two spaces after the periods.

> +;;   Logos specified using absolute paths on Linux or Windows:
> +;;
> +;;       \includegraphics{/Users/you/correspondence/logo}
> +;;       \includegraphics{/Users/you/correspondence/logos/production/logo}

I used "~/correspondence", which is more common.

Thank you!

Regards,

-- 
Nicolas Goaziou

Re: Patch adding from-logo commentary ox-koma-letter.el

[Grant Rettke]

On Wed, Jun 27, 2018 at 9:28 AM, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> Grant Rettke <gcr@wisdomandwonder.com> writes:
>> From: Grant Rettke <gcr@wisdomandwonder.com>
>> +;; provides the 'includegraphics' command to tell LaTeX where to find
>> +;; the logo. 'includegraphics' needs to know the logo's directory and
>
> I added two spaces after the periods.

Thank you I will do that in the future.

Have a great day.