Rationale for *text* -> \alert{text} for Beamer export?

Rationale for *text* -> \alert{text} for Beamer export?

[John Hendy]

Greetings,

Just wondering about the rationale behind using *bold* markup for
\textbf{} in LaTeX export and to \alert{} in Beamer. Was this a
frequently voiced request? I'm sure I can dig into this somewhere and
change it, but if the majority prefers bold (not saying they do!),
should that be the default?

I'd prefer bold, personally. I don't like red table column titles or in lists.


Thanks,
John

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Marcin Borkowski]

Dnia 2013-05-01, o godz. 09:17:23
John Hendy <jw.hendy@gmail.com> napisał(a):

> Greetings,
> 
> Just wondering about the rationale behind using *bold* markup for
> \textbf{} in LaTeX export and to \alert{} in Beamer. Was this a
> frequently voiced request? I'm sure I can dig into this somewhere and
> change it, but if the majority prefers bold (not saying they do!),
> should that be the default?
> 
> I'd prefer bold, personally. I don't like red table column titles or
> in lists.

Just my 2 cents:

* In general, you shouldn't use boldface in printed documents (unless
  you have a good reason.  A /very/ good, thought out reason.  And
  usually you haven't one;).).

* In presentations, things are indeed quite different.

* Keeping that in mind, \alert{...} is /better/ than \textbf{...}, just
  like \emph{...} is better than \textit{...}: it is semantic, not
  visual markup.

* If you do insist on boldface as "alerting", just say
    \setbeamerfont{alerted text}{series=\bfseries}
  in your preamble.  Keep in mind, however, that this will break things
  if you use alert<...>{...}.  Take this document, for instance:

\documentclass{beamer}

\begin{document}
\begin{frame}
  This is \alert{alerted} text.

  And this is \alert<2>{alerted} only on the second slide.
\end{frame}
\end{document}

  In it, text will "wobble" when changing slides.  This is ugly.

* So, what you probably want, is to say
    \setbeamercolor{alerted text}{fg=red!50!black}
  in your preamble, so \alert{...} means a color in the midpoint (in RGB
  linear space) between red and black (you might want to experiment with
  percentages other than 50% or wholly different colors, of course).

> Thanks,
> John

HTH,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Rationale for *text* -> \alert{text} for Beamer export?

[John Hendy]

On Wed, May 1, 2013 at 10:00 AM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:
> Dnia 2013-05-01, o godz. 09:17:23
> John Hendy <jw.hendy@gmail.com> napisał(a):
>
>> Greetings,
>>
>> Just wondering about the rationale behind using *bold* markup for
>> \textbf{} in LaTeX export and to \alert{} in Beamer. Was this a
>> frequently voiced request? I'm sure I can dig into this somewhere and
>> change it, but if the majority prefers bold (not saying they do!),
>> should that be the default?
>>
>> I'd prefer bold, personally. I don't like red table column titles or
>> in lists.
>
> Just my 2 cents:
>
> * In general, you shouldn't use boldface in printed documents (unless
>   you have a good reason.  A /very/ good, thought out reason.  And
>   usually you haven't one;).).

Do you have sources for this? I googled "why you shouldn't use bold"
and "why you shouldn't use bold for papers" and some others. I
couldn't find anyone making that case in the first two pages of hits.
I guess I expected that if this was common knowledge it wouldn't be
hard to find.

>
> * In presentations, things are indeed quite different.
>
> * Keeping that in mind, \alert{...} is /better/ than \textbf{...}, just
>   like \emph{...} is better than \textit{...}: it is semantic, not
>   visual markup.

Can you explain semantic vs. visual? As in you can more easily
customize the meaning of \alert{} or \emph{} whereas \textbf{} and
\textit{} only has one meaning? Sort of like using a css tag which can
be later customized vs. specifically calling out exactly what you're
thinking you want to do at the moment?

> * If you do insist on boldface as "alerting", just say
>     \setbeamerfont{alerted text}{series=\bfseries}
>   in your preamble.  Keep in mind, however, that this will break things
>   if you use alert<...>{...}.  Take this document, for instance:
>
> \documentclass{beamer}
>
> \begin{document}
> \begin{frame}
>   This is \alert{alerted} text.
>
>   And this is \alert<2>{alerted} only on the second slide.
> \end{frame}
> \end{document}
>
>   In it, text will "wobble" when changing slides.  This is ugly.
>

Sure, and understood. In general, I'm using *text* simply to call
attention to something important. I work in product development, so
something like:

Customer response to product sampling:
- *US:* blah blah blah
- *China:* blah blah blah
- *India: blah blah blah

Using *text* is simply to call attention to the fact that the *word:*
is an "in-line header" of sorts for what is to follow. Also, it lets
readers easily compare the bolded text and pick the bucket they care
to explore vs. having it blend in with the prose that follows.
Regardless of the opinions on bold vs. red text, I find bold (or
italics) are more conventional, whereas red conveys "problem" or
"yikes" and simply seems more counter-conventional, so I feel it
distracts more than a more typical typeface emphasis method.

In essence, I simply want to call attention to text, but not too much
and red stand out like a sore thumb, in my opinion, far more than bold
or italic. It's so dominant that it over-does it's job of emphasizing.

> * So, what you probably want, is to say
>     \setbeamercolor{alerted text}{fg=red!50!black}
>   in your preamble, so \alert{...} means a color in the midpoint (in RGB
>   linear space) between red and black (you might want to experiment with
>   percentages other than 50% or wholly different colors, of course).
>

Thanks for letting me know how to tweak and mute down a bit. I can
play with that... though I probably just want *text* to equal bold, or
I'll decide to use /text/ instead.


John

>> Thanks,
>> John
>
> HTH,
>
> --
> Marcin Borkowski
> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
> Adam Mickiewicz University
>

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Thomas S. Dye]

Hi John,

Jumping in late here, with apologies if that's left me wide of the mark.

John Hendy <jw.hendy@gmail.com> writes:

> On Wed, May 1, 2013 at 10:00 AM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:

> Can you explain semantic vs. visual? As in you can more easily
> customize the meaning of \alert{} or \emph{} whereas \textbf{} and
> \textit{} only has one meaning? Sort of like using a css tag which can
> be later customized vs. specifically calling out exactly what you're
> thinking you want to do at the moment?

IMHO, the best discussion of this difference is the first chapter of
Lamport's LaTeX User's Guide and Manual.  Here is the gist as I
understand it:

1) A principle of typesetting is that the layout of a document should
reflect its logical structure.

2) A computer typesetting program can achieve this if it knows what key
parts of the document mean.

3) So, markup should be semantic, rather than visual.

It is possible to achieve identical results using visual markup, of
course, but why not let the computer keep track of things instead?
>
> Sure, and understood. In general, I'm using *text* simply to call
> attention to something important. I work in product development, so
> something like:
>
> Customer response to product sampling:
> - *US:* blah blah blah
> - *China:* blah blah blah
> - *India: blah blah blah

Here, to achieve semantic markup, you would use description lists

- US :: blah
- China :: blah
- India :: blah

The :: separator lets Org (and ultimately LaTeX) know that the part
before the separator is the term that is being described.

hth,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Marcin Borkowski]

Dnia 2013-05-01, o godz. 11:41:49
tsd@tsdye.com (Thomas S. Dye) napisał(a):

> Hi John,
> 
> Jumping in late here, with apologies if that's left me wide of the
> mark.
> 
> John Hendy <jw.hendy@gmail.com> writes:
> 
> > On Wed, May 1, 2013 at 10:00 AM, Marcin Borkowski
> > <mbork@wmi.amu.edu.pl> wrote:
> 
> > Can you explain semantic vs. visual? As in you can more easily
> > customize the meaning of \alert{} or \emph{} whereas \textbf{} and
> > \textit{} only has one meaning? Sort of like using a css tag which
> > can be later customized vs. specifically calling out exactly what
> > you're thinking you want to do at the moment?
> 
> IMHO, the best discussion of this difference is the first chapter of
> Lamport's LaTeX User's Guide and Manual.  Here is the gist as I
> understand it:
> 
> 1) A principle of typesetting is that the layout of a document should
> reflect its logical structure.
> 
> 2) A computer typesetting program can achieve this if it knows what
> key parts of the document mean.
> 
> 3) So, markup should be semantic, rather than visual.
> 
> It is possible to achieve identical results using visual markup, of
> course, but why not let the computer keep track of things instead?

+1

Notice also that even LaTeX breaks the rule of "use only semantic
markup in the document" (and in fact, there are cases when the rule is
a bit fuzzy anyway).  Finding examples of /visual/ markup in LaTeX
(without semantic counterparts) are left as an exercise for the
reader;).

(Hint: rahzrengvbaf fglyrf qrcraq abg ba gur punenpgre bs gur
rahzrengvba, ohg ba vgf qrcgu, naq jvgubhg cnpxntrf yvxr rahzvgrz vg'f
abg rnfl gb qrsvar lbhe bja rahzrengvba fglyrf.)

> > Sure, and understood. In general, I'm using *text* simply to call
> > attention to something important. I work in product development, so
> > something like:
> >
> > Customer response to product sampling:
> > - *US:* blah blah blah
> > - *China:* blah blah blah
> > - *India: blah blah blah
> 
> Here, to achieve semantic markup, you would use description lists
> 
> - US :: blah
> - China :: blah
> - India :: blah
> 
> The :: separator lets Org (and ultimately LaTeX) know that the part
> before the separator is the term that is being described.

And then use the enumitem package to customize the exact look of the
description environment.

> hth,
> Tom

Regards,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Suvayu Ali]

On Wed, May 01, 2013 at 11:41:49AM -1000, Thomas S. Dye wrote:
> John Hendy <jw.hendy@gmail.com> writes:
> 
> > On Wed, May 1, 2013 at 10:00 AM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:
> 
> 3) So, markup should be semantic, rather than visual.
> 
> It is possible to achieve identical results using visual markup, of
> course, but why not let the computer keep track of things instead?
> >
> > Sure, and understood. In general, I'm using *text* simply to call
> > attention to something important. I work in product development, so
> > something like:
> >
> > Customer response to product sampling:
> > - *US:* blah blah blah
> > - *China:* blah blah blah
> > - *India: blah blah blah
> 
> Here, to achieve semantic markup, you would use description lists
> 
> - US :: blah
> - China :: blah
> - India :: blah

Description lists align at the "::", which can look weird when you have
headings of very different lengths.  So I often use \structure{..}.  I
have a filter that translates +strikethrough+ text to structure[1].


Footnotes:

[1] <http://orgmode.org/worg/exporters/beamer/ox-beamer.html#export-filters>


-- 
Suvayu

Open source is the future. It sets us free.

Re: Rationale for *text* -> \alert{text} for Beamer export?

[James Harkins]

John Hendy <jw.hendy <at> gmail.com> writes:

> Just wondering about the rationale behind using *bold* markup for
> \textbf{} in LaTeX export and to \alert{} in Beamer. Was this a
> frequently voiced request? I'm sure I can dig into this somewhere and
> change it, but if the majority prefers bold (not saying they do!),
> should that be the default?
> 
> I'd prefer bold, personally. I don't like red table column titles or in 
lists.

I had asked the same question a while back, and I received some quite
amusing replies about \alert being "the Beamer way"... which I
promptly ignored and implemented my own hack to customize the LaTeX
command for beamer to use for *bold text* (pasted as a git patch
below).

I'm reading Marcin's recommendations carefully, since now, for the
first time, I need to learn more about tweaking LaTeX's output. I'm
not sure I agree with all of that line of thought, though.

~~
* Keeping that in mind, \alert{...} is /better/ than \textbf{...}, just
  like \emph{...} is better than \textit{...}: it is semantic, not
  visual markup.
~~

I can understand this rationale if the use case is to export from org
to a LaTeX file, and then continue to work with the LaTeX file. In
that case, you would want the exported LaTeX code to follow best
practices and be "maintainable." I'd guess a more common use case for
org export is to work exclusively with the org markup, and allow the
exporter to use LaTeX as an intermediary, on the way to PDF. At least,
this is how *I* use it; it doesn't really bother me if the LaTeX code
produced by org uses semantic or visual markup. Where I need semantic
markup (and I will, in my next article), I'll write the semantic
markup in org.

I guess I look at this in a way that FAUST [1] uses c++ as an
intermediary. You write the signal-processing graph in FAUST's own
purely-functional language, which the FAUST compiler translates into
c++ (with a variety of headers and wrappers for VST, OSX audio units,
SuperCollider plug-ins etc.). The resulting c++ is a mess, from the
standpoint of reading and maintenance, but you're not supposed to
maintain that code by hand. You're supposed to go back to the FAUST
code to make changes.

org --> LaTeX -- PDF
FAUST --> c++ --> DSP plugin

But, going a step further, if semantic markup is what you need,
wouldn't it be better to define a \newcommand wrapper for \textbf, and
then tell org to export *bold* using the wrapper? That would assume
that you can customize the string org uses for *bold*, which you can't
at present... so maybe my hack has some use after all.

hjh

[1] Functional AUdio STream language: http://faust.grame.fr/


From 8ccbc7cad43b520067b8b29d4660fc99587995fd Mon Sep 17 00:00:00 2001
From: James Harkins <jamshark70@dewdrop-world.net>
Date: Thu, 21 Feb 2013 09:51:02 +0800
Subject: [PATCH] hjh temp: add customize variable for bold/alert style

---
 lisp/ox-beamer.el |    9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
index dc427de..44c1c68 100644
--- a/lisp/ox-beamer.el
+++ b/lisp/ox-beamer.el
@@ -206,6 +206,12 @@ You might want to put e.g. \"allowframebreaks=0.9\" 
here."
   :group 'org-export-beamer
   :type '(string :tag "Outline frame options"))
 
+(defcustom org-beamer-bold-macro "alert"
+  "LaTeX macro to insert for bold text (delimited by asterisks in the org 
source file).
+The default \"alert\" renders as red text, normal weight.
+Substitute \"textbf\" to obtain boldface."
+  :group 'org-export-beamer
+  :type '(string :tag "Bold macro"))
 
 \f
 ;;; Internal Variables
@@ -334,7 +340,8 @@ Return overlay specification, as a string, or nil."
   "Transcode BLOCK object into Beamer code.
 CONTENTS is the text being bold.  INFO is a plist used as
 a communication channel."
-  (format "\\alert%s{%s}"
+  (format "\\%s%s{%s}"
+	  org-beamer-bold-macro
 	  (or (org-beamer--element-has-overlay-p bold) "")
 	  contents))
 
-- 
1.7.9.5

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Nicolas Goaziou]

Hello,

James Harkins <jamshark70@gmail.com> writes:

> That would assume that you can customize the string org uses for
> *bold*, which you can't at present... so maybe my hack has some use
> after all.

This has already been discussed, and there's a solution provided at:

  http://orgmode.org/worg/exporters/beamer/ox-beamer.html

No need to add another customize for that. Thank you for your patch,
though.


Regards,

-- 
Nicolas Goaziou

Re: Rationale for *text* -> \alert{text} for Beamer export?

[James Harkins]

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

On May 2, 2013 4:20 PM, "Nicolas Goaziou" <n.goaziou@gmail.com> wrote:
> James Harkins <jamshark70@gmail.com> writes:
>
> > That would assume that you can customize the string org uses for
> > *bold*, which you can't at present... so maybe my hack has some use
> > after all.
>
> This has already been discussed, and there's a solution provided at:
>
>   http://orgmode.org/worg/exporters/beamer/ox-beamer.html
>
> No need to add another customize for that. Thank you for your patch,
> though.

Fair enough -- that's far more flexible than what I did. I did the hack
months ago, when the documentation of the new exporter hadn't been written.
I never would have guessed that solution, based on the docstrings available
at the time.

FWIW, I wasn't submitting the patch for inclusion. It's only that a patch
was the easiest way to show the change. I guess I should have said so
specifically, since it's natural to assume that a patch posted to the list
is a proposal for a (permanent) change. Not my intent here.

hjh

[-- Attachment #2: Type: text/html, Size: 1398 bytes --]

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Marcin Borkowski]

Dnia 2013-05-02, o godz. 02:48:41
James Harkins <jamshark70@gmail.com> napisał(a):

> John Hendy <jw.hendy <at> gmail.com> writes:
> 
> > Just wondering about the rationale behind using *bold* markup for
> > \textbf{} in LaTeX export and to \alert{} in Beamer. Was this a
> > frequently voiced request? I'm sure I can dig into this somewhere
> > and change it, but if the majority prefers bold (not saying they
> > do!), should that be the default?
> > 
> > I'd prefer bold, personally. I don't like red table column titles
> > or in 
> lists.
> 
> I had asked the same question a while back, and I received some quite
> amusing replies about \alert being "the Beamer way"... which I
> promptly ignored and implemented my own hack to customize the LaTeX
> command for beamer to use for *bold text* (pasted as a git patch
> below).

So maybe consider \alert{...} being "the Beamer way" just like <strong>
being the HTML/CSS way.

> I'm reading Marcin's recommendations carefully, since now, for the
> first time, I need to learn more about tweaking LaTeX's output. I'm
> not sure I agree with all of that line of thought, though.
> 
> ~~
> * Keeping that in mind, \alert{...} is /better/ than \textbf{...},
> just like \emph{...} is better than \textit{...}: it is semantic, not
>   visual markup.
> ~~
> 
> I can understand this rationale if the use case is to export from org
> to a LaTeX file, and then continue to work with the LaTeX file. In
> that case, you would want the exported LaTeX code to follow best
> practices and be "maintainable." I'd guess a more common use case for
> org export is to work exclusively with the org markup, and allow the
> exporter to use LaTeX as an intermediary, on the way to PDF. At least,
> this is how *I* use it; it doesn't really bother me if the LaTeX code
> produced by org uses semantic or visual markup. Where I need semantic
> markup (and I will, in my next article), I'll write the semantic
> markup in org.

Fair point.  For me, Org-mode is more of a planner/outliner; using it
for markup/authoring seems awkward for me, since LaTeX is so
natural...  But then, I've been using LaTeX for something like 12 years
(and plain TeX earlier).  (One exception - for me - is authoring of
blog entries, and one day I'll play with an Oddmuse export...)  And I
imagine that for quite a few people, maintainability of the LaTeX code
resulting from Org-mode export might be essential.  And by
"maintainability", I mean one of two things: (1) possibility of further
work on the file by a human or (2) possibility of changing the
look-and-feel by just loading a package or a simple customization in
the preamble.  For both cases, sticking as much as possible to semantic
markup in the exported code is crucial.

> I guess I look at this in a way that FAUST [1] uses c++ as an
> intermediary. You write the signal-processing graph in FAUST's own
> purely-functional language, which the FAUST compiler translates into
> c++ (with a variety of headers and wrappers for VST, OSX audio units,
> SuperCollider plug-ins etc.). The resulting c++ is a mess, from the
> standpoint of reading and maintenance, but you're not supposed to
> maintain that code by hand. You're supposed to go back to the FAUST
> code to make changes.
> 
> org --> LaTeX -- PDF
> FAUST --> c++ --> DSP plugin
> 
> But, going a step further, if semantic markup is what you need,
> wouldn't it be better to define a \newcommand wrapper for \textbf, and
> then tell org to export *bold* using the wrapper? That would assume
> that you can customize the string org uses for *bold*, which you can't
> at present... so maybe my hack has some use after all.

Fair point again.  I think that the point is that - unlike HTML - you
have \emph{...} in LaTeX, but no \strong{...} (or \alert{...} - for
that you need beamer; strangley enough, in the beamerarticle class,
\alert{...} is mapped to \emph{...}).  Now I guess I know the reason,
though it is only my suspicion and not knowledge.

You know, LaTeX is being advertised as being a "document preparation
system".  But in fact it's not; it is a "scientific paper preparation
system", and more precisely a "computer science paper preparation
system".  Everything else are add-ons (packages and classes in
LaTeX-speak).  Even for maths publishing, pure LaTeX core is not
enough: you need at least amsmath/amssymb/amsfonts.  So, with the focus
being on /printed/ documents in a scientific field, boldface in text is
a no-no; basically, the /only/ reasonable use for boldface (apart from
some vector notation, but I'm speaking about text, not formulae here)
is in titles etc., where we don't use \textbf{...} (or {\bfseries ...})
anyway, since they are already packaged in higher-level, semantic
macros like \section{...} or \title{...}/\maketitle etc.

Now with documents other than papers on computer science actually
printed on physical paper, things are different.  But LaTeX (and again
- I mean core LaTeX2e, without additional packages etc.) simply does
not address that.  I wouldn't be surprised, though, if LaTeX3 gets
\strong{...} or \alert{...} in the core some day.

> hjh

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Rationale for *text* -> \alert{text} for Beamer export?

[Suvayu Ali]

On Thu, May 02, 2013 at 02:48:41AM +0000, James Harkins wrote:
> ... implemented my own hack to customize the LaTeX
> command for beamer to use for *bold text* (pasted as a git patch
> below).

 [...chomp...chomp...chomp...]

> From 8ccbc7cad43b520067b8b29d4660fc99587995fd Mon Sep 17 00:00:00 2001
> From: James Harkins <jamshark70@dewdrop-world.net>
> Date: Thu, 21 Feb 2013 09:51:02 +0800
> Subject: [PATCH] hjh temp: add customize variable for bold/alert style
> 
> ---
>  lisp/ox-beamer.el |    9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
> index dc427de..44c1c68 100644
> --- a/lisp/ox-beamer.el
> +++ b/lisp/ox-beamer.el
> @@ -206,6 +206,12 @@ You might want to put e.g. \"allowframebreaks=0.9\" 
> here."
>    :group 'org-export-beamer
>    :type '(string :tag "Outline frame options"))
>  
> +(defcustom org-beamer-bold-macro "alert"
> +  "LaTeX macro to insert for bold text (delimited by asterisks in the org 
> source file).
> +The default \"alert\" renders as red text, normal weight.
> +Substitute \"textbf\" to obtain boldface."
> +  :group 'org-export-beamer
> +  :type '(string :tag "Bold macro"))
>  
>  \f
>  ;;; Internal Variables
> @@ -334,7 +340,8 @@ Return overlay specification, as a string, or nil."
>    "Transcode BLOCK object into Beamer code.
>  CONTENTS is the text being bold.  INFO is a plist used as
>  a communication channel."
> -  (format "\\alert%s{%s}"
> +  (format "\\%s%s{%s}"
> +	  org-beamer-bold-macro
>  	  (or (org-beamer--element-has-overlay-p bold) "")
>  	  contents))

Not sure a patch introducing yet another variable is warranted when all
you need is a filter:

  <http://orgmode.org/worg/exporters/beamer/ox-beamer.html#export-filters>

-- 
Suvayu

Open source is the future. It sets us free.