parser: verbatim or code?

parser: verbatim or code?

[Yasushi SHOJI]

Hello,

While writing a new exporter I've noticed that `=' is actually for
verbatim and `~' is for code emphasis despite the fact that the
current org manual says:

	You can make words *bold*, /italic/, _underlined_, =code= and
	~verbatim~

Is this documentation bug?

regards,
-- 
            yashi

Re: parser: verbatim or code?

[Nick Dokos]

Yasushi SHOJI <yashi@atmark-techno.com> writes:

> Hello,
>
> While writing a new exporter I've noticed that `=' is actually for
> verbatim and `~' is for code emphasis despite the fact that the
> current org manual says:
>
> 	You can make words *bold*, /italic/, _underlined_, =code= and
> 	~verbatim~
>
> Is this documentation bug?
>

I think it's a code bug: ~verbatim~ is the precedent-setting latex
convention.

However fixing it might break existing documents (although in many
instances code and verbatim are treated equivalently, so that might
not be much of a problem).

-- 
Nick

Re: parser: verbatim or code?

[Yasushi SHOJI]

Hi,

At Sat, 15 Feb 2014 09:23:41 -0500,
Nick Dokos wrote:
> 
> I think it's a code bug: ~verbatim~ is the precedent-setting latex
> convention.
> 
> However fixing it might break existing documents (although in many
> instances code and verbatim are treated equivalently, so that might
> not be much of a problem).

A quick grep on export back-ends reveals that some back-ends uses them
differently. Namely

 - latex
 - man
 - org ;-)
 - texinfo

Should I just leave as-is?
-- 
           yashi

Re: parser: verbatim or code?

[Nicolas Goaziou]

Hello,

Yasushi SHOJI <yashi@atmark-techno.com> writes:

> Nick Dokos wrote:
>> 
>> I think it's a code bug: ~verbatim~ is the precedent-setting latex
>> convention.
>> 
>> However fixing it might break existing documents (although in many
>> instances code and verbatim are treated equivalently, so that might
>> not be much of a problem).
>
> A quick grep on export back-ends reveals that some back-ends uses them
> differently. Namely
>
>  - latex
>  - man
>  - org ;-)
>  - texinfo
>
> Should I just leave as-is?

If we leave it as-is, documentation needs to be updated anyway.

If we do change them, it should only happen in "org-element.el". I don't
think that would break existing documents, as code and verbatim are
really close to each other.

I don't care either way. Though, I lean towards the first option, as
I like "=" as verbatim (which may be the source of the initial
confusion).


Regards,

-- 
Nicolas Goaziou

Re: parser: verbatim or code?

[Michael Brand]

Hi Nicolas

On Sun, Feb 16, 2014 at 10:20 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> If we leave it as-is, documentation needs to be updated anyway.
>
> If we do change them, it should only happen in "org-element.el". I don't
> think that would break existing documents, as code and verbatim are
> really close to each other.
>
> I don't care either way. Though, I lean towards the first option, as
> I like "=" as verbatim (which may be the source of the initial
> confusion).

When I read org-element-text-markup-successor

    ((equal marker "~") 'code)
    ((equal marker "=") 'verbatim)

it confuses me because of the well known Org manual

    You can make words *bold*, /italic/, _underlined_, =code= and
    ~verbatim~

Michael

Re: parser: verbatim or code?

[Nicolas Goaziou]

Hello,

Michael Brand <michael.ch.brand@gmail.com> writes:

> When I read org-element-text-markup-successor
>
>     ((equal marker "~") 'code)
>     ((equal marker "=") 'verbatim)
>
> it confuses me because of the well known Org manual
>
>     You can make words *bold*, /italic/, _underlined_, =code= and
>     ~verbatim~

Indeed, that's the very issue we're discussing in this thread.

I'm not sure to understand what you mean here.


Regards,

-- 
Nicolas Goaziou

Re: parser: verbatim or code?

[Michael Brand]

Hi Nicolas

On Sun, Feb 16, 2014 at 11:00 AM, Nicolas Goaziou <n.goaziou@gmail.com> wrote:
> Indeed, that's the very issue we're discussing in this thread.
>
> I'm not sure to understand what you mean here.

For me it was not explicit enough that this

    ((equal marker "~") 'code)
    ((equal marker "=") 'verbatim)

is the part discussed.

I am not sure if it is that simple but just from the word "code" and
from the usage on Worg I tend to conclude that for inline code
snippets 'code should be preferred and 'verbatim only be used for
non-code things more similar to just like an inline quote. Only if
this distinction should really matter then keeping the above code
unchanged and changing the Org manual from =code= ~verbatim~ to ~code~
=verbatim= would have the following advantage:

The syntax for inline code snippets seems easier to read by human and
to parse with "~" than with "=" because inline code snippets use "~"
less often than "=". I avoid "~/" by using "$HOME/" in my notes about
shell and shell scripts. Some examples:

Bla ~a = 1~ bla,
bla ~b=2~ bla,
bla ~local my_variable= # Bash shell: Set to empty value.~ bla,
bla ~source $HOME/.profile~ bla.

vs.

Bla =a = 1= bla,
bla =b=2= bla,
bla =local my_variable= # Bash shell: Set to empty value.= bla,
bla =source $HOME/.profile= bla.

Michael

Re: parser: verbatim or code?

[Bastien]

Hi Yasushi, Michael and Nicolas,

Michael Brand <michael.ch.brand@gmail.com> writes:

> The syntax for inline code snippets seems easier to read by human and
> to parse with "~" than with "=" because inline code snippets use "~"
> less often than "=". I avoid "~/" by using "$HOME/" in my notes about
> shell and shell scripts. Some examples:

I've now fix those inconsistencies, both in the manual and in the
code.  I followed Michael suggestion to use ~code~ and =verbatim=.

We may need to update the way export backend treat this markup,
and try to be consistent here too.

Thanks,

-- 
 Bastien

Re: parser: verbatim or code?

[Sebastien Vauban]

Hello,

Bastien wrote:
> Hi Yasushi, Michael and Nicolas,
>
> Michael Brand <michael.ch.brand-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>> The syntax for inline code snippets seems easier to read by human and
>> to parse with "~" than with "=" because inline code snippets use "~"
>> less often than "=". I avoid "~/" by using "$HOME/" in my notes about
>> shell and shell scripts. Some examples:
>
> I've now fix those inconsistencies, both in the manual and in the
> code.  I followed Michael suggestion to use ~code~ and =verbatim=.
>
> We may need to update the way export backend treat this markup, and
> try to be consistent here too.

Since = and ~ have been inverted, I think it'd make sense to make
`org-babel-inline-result-wrap' now default to "~%s" (instead of "=%s"),
for markup that produces verbatim text.

That will put fix back as what they were for people having different CSS
or LaTeX styles applied to both markers.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: parser: verbatim or code?

[Sebastien Vauban]

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

Hello,

Sebastien Vauban wrote:
> Bastien wrote:
>> Hi Yasushi, Michael and Nicolas,
>>
>> Michael Brand <michael.ch.brand-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> writes:
>>> The syntax for inline code snippets seems easier to read by human
>>> and to parse with "~" than with "=" because inline code snippets use
>>> "~" less often than "=". I avoid "~/" by using "$HOME/" in my notes
>>> about shell and shell scripts. Some examples:
>>
>> I've now fix those inconsistencies, both in the manual and in the
>> code.  I followed Michael suggestion to use ~code~ and =verbatim=.
>>
>> We may need to update the way export backend treat this markup, and
>> try to be consistent here too.
>
> Since = and ~ have been inverted, I think it'd make sense to make
> `org-babel-inline-result-wrap' now default to "~%s" (instead of
> "=%s"), for markup that produces verbatim text.

Here is the patch.

Best regards,
  Seb

-- 
Sebastien Vauban

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Replace-by-in-org-babel-inline-result-wrap.patch --]
[-- Type: text/x-patch, Size: 1108 bytes --]

From 4168c424e3c112748951177121b1a4dcb5b712a5 Mon Sep 17 00:00:00 2001
From: Sebastien Vauban <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
Date: Fri, 23 Jan 2015 20:17:25 +0100
Subject: [PATCH] Replace `=' by `~' in `org-babel-inline-result-wrap'

* ob-core.el (org-babel-inline-result-wrap): Replace `=' by `~'.
---
 lisp/ob-core.el | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index 24b83d6..5fd4119 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -1,6 +1,6 @@
 ;;; ob-core.el --- working with code blocks in org-mode
 
-;; Copyright (C) 2009-2014 Free Software Foundation, Inc.
+;; Copyright (C) 2009-2015 Free Software Foundation, Inc.
 
 ;; Authors: Eric Schulte
 ;;	Dan Davison
@@ -162,7 +162,7 @@ See also `org-babel-noweb-wrap-start'."
   :group 'org-babel
   :type 'string)
 
-(defcustom org-babel-inline-result-wrap "=%s="
+(defcustom org-babel-inline-result-wrap "~%s~"
   "Format string used to wrap inline results.
 This string must include a \"%s\" which will be replaced by the results."
   :group 'org-babel
-- 
2.1.1

Re: parser: verbatim or code?

[Aaron Ecay]

Hi Sebastien,

2015ko urtarrilak 23an, Sebastien Vauban-ek idatzi zuen:
>> Since = and ~ have been inverted, I think it'd make sense to make
>> `org-babel-inline-result-wrap' now default to "~%s" (instead of
>> "=%s"), for markup that produces verbatim text.
> 
> Here is the patch.

If I understand this thread correctly, = is now consistently interpreted
as verbatim and ~ as code.  I think verbatim (i.e. the status quo) is
what makes sense for inline babel results – results are not generally
speaking code (though of course in special cases they can be).

I’m not sure what you mean by

> That will put fix back as what they were for people having different CSS
> or LaTeX styles applied to both markers.

It sounds like perhaps there are user customizations which are out of
date with this change.  Maybe an announcement is needed in ORG-NEWS to
raise awareness of this change.

Thanks,

-- 
Aaron Ecay

Re: parser: verbatim or code?

[Sebastien Vauban]

Aaron Ecay wrote:
> 2015ko urtarrilak 23an, Sebastien Vauban-ek idatzi zuen:
>>> Since = and ~ have been inverted, I think it'd make sense to make
>>> `org-babel-inline-result-wrap' now default to "~%s" (instead of
>>> "=%s"), for markup that produces verbatim text.
>> 
>> Here is the patch.
>
> If I understand this thread correctly, = is now consistently
> interpreted as verbatim and ~ as code.  I think verbatim (i.e. the
> status quo) is what makes sense for inline babel results – results are
> not generally speaking code (though of course in special cases they
> can be).
>
> I’m not sure what you mean by
>
>> That will put fix back as what they were for people having different
>> CSS or LaTeX styles applied to both markers.

I mean that some of us may have applied CSS to differentiate among
"code" and "verbatim" in HTML.

Anyway, I do agree with you that defaulting to verbatim (instead of
code) makes more sense, in fact, for results of inline babel code
blocks.

Case closed!

Best regards,
  Seb

-- 
Sebastien Vauban

Re: parser: verbatim or code?

[Yasushi SHOJI]

Hi Nicolas,

At Sun, 16 Feb 2014 10:20:55 +0100,
Nicolas Goaziou wrote:
> 
> If we do change them, it should only happen in "org-element.el". I don't
> think that would break existing documents, as code and verbatim are
> really close to each other.
> 
> I don't care either way. Though, I lean towards the first option, as
> I like "=" as verbatim (which may be the source of the initial
> confusion).

I'd suggest to keep documentation, and fix the code.

Because, our document serves our _user_ as the interface definition
and it's already been widely accepted.  Users expect to have marked up
code segment if they have =code= in their document.

;; It might be just me but I've been seen =code= in this mailing list
;; many times but never noticed ~code~, for example.
-- 
          yashi