* parser: verbatim or code?
@ 2014-02-15 13:43 Yasushi SHOJI
2014-02-15 14:23 ` Nick Dokos
0 siblings, 1 reply; 13+ messages in thread
From: Yasushi SHOJI @ 2014-02-15 13:43 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 13+ messages in thread* Re: parser: verbatim or code?
2014-02-15 13:43 parser: verbatim or code? Yasushi SHOJI
@ 2014-02-15 14:23 ` Nick Dokos
2014-02-16 8:51 ` Yasushi SHOJI
0 siblings, 1 reply; 13+ messages in thread
From: Nick Dokos @ 2014-02-15 14:23 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2014-02-15 14:23 ` Nick Dokos
@ 2014-02-16 8:51 ` Yasushi SHOJI
2014-02-16 9:20 ` Nicolas Goaziou
0 siblings, 1 reply; 13+ messages in thread
From: Yasushi SHOJI @ 2014-02-16 8:51 UTC (permalink / raw)
To: emacs-orgmode
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
^ permalink raw reply [flat|nested] 13+ messages in thread* Re: parser: verbatim or code?
2014-02-16 8:51 ` Yasushi SHOJI
@ 2014-02-16 9:20 ` Nicolas Goaziou
2014-02-16 9:43 ` Michael Brand
2014-02-18 4:19 ` Yasushi SHOJI
0 siblings, 2 replies; 13+ messages in thread
From: Nicolas Goaziou @ 2014-02-16 9:20 UTC (permalink / raw)
To: Yasushi SHOJI; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2014-02-16 9:20 ` Nicolas Goaziou
@ 2014-02-16 9:43 ` Michael Brand
2014-02-16 10:00 ` Nicolas Goaziou
2014-02-18 4:19 ` Yasushi SHOJI
1 sibling, 1 reply; 13+ messages in thread
From: Michael Brand @ 2014-02-16 9:43 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode
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
^ permalink raw reply [flat|nested] 13+ messages in thread* Re: parser: verbatim or code?
2014-02-16 9:43 ` Michael Brand
@ 2014-02-16 10:00 ` Nicolas Goaziou
2014-02-16 11:52 ` Michael Brand
0 siblings, 1 reply; 13+ messages in thread
From: Nicolas Goaziou @ 2014-02-16 10:00 UTC (permalink / raw)
To: Michael Brand; +Cc: Org Mode
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2014-02-16 10:00 ` Nicolas Goaziou
@ 2014-02-16 11:52 ` Michael Brand
2014-03-04 9:52 ` Bastien
0 siblings, 1 reply; 13+ messages in thread
From: Michael Brand @ 2014-02-16 11:52 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: Org Mode
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
^ permalink raw reply [flat|nested] 13+ messages in thread* Re: parser: verbatim or code?
2014-02-16 11:52 ` Michael Brand
@ 2014-03-04 9:52 ` Bastien
2015-01-23 11:33 ` Sebastien Vauban
0 siblings, 1 reply; 13+ messages in thread
From: Bastien @ 2014-03-04 9:52 UTC (permalink / raw)
To: Michael Brand; +Cc: Org Mode, Nicolas Goaziou
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2014-03-04 9:52 ` Bastien
@ 2015-01-23 11:33 ` Sebastien Vauban
2015-01-23 19:20 ` Sebastien Vauban
0 siblings, 1 reply; 13+ messages in thread
From: Sebastien Vauban @ 2015-01-23 11:33 UTC (permalink / raw)
To: Bastien, Michael Brand, Nicolas Goaziou; +Cc: Org Mode
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2015-01-23 11:33 ` Sebastien Vauban
@ 2015-01-23 19:20 ` Sebastien Vauban
2015-01-23 20:31 ` Aaron Ecay
0 siblings, 1 reply; 13+ messages in thread
From: Sebastien Vauban @ 2015-01-23 19:20 UTC (permalink / raw)
To: emacs-orgmode-mXXj517/zsQ
[-- 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
^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2015-01-23 19:20 ` Sebastien Vauban
@ 2015-01-23 20:31 ` Aaron Ecay
[not found] ` <87egqlgrws.fsf-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
0 siblings, 1 reply; 13+ messages in thread
From: Aaron Ecay @ 2015-01-23 20:31 UTC (permalink / raw)
To: Sebastien Vauban, emacs-orgmode
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: parser: verbatim or code?
2014-02-16 9:20 ` Nicolas Goaziou
2014-02-16 9:43 ` Michael Brand
@ 2014-02-18 4:19 ` Yasushi SHOJI
1 sibling, 0 replies; 13+ messages in thread
From: Yasushi SHOJI @ 2014-02-18 4:19 UTC (permalink / raw)
To: n.goaziou; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2015-01-30 11:02 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-02-15 13:43 parser: verbatim or code? Yasushi SHOJI
2014-02-15 14:23 ` Nick Dokos
2014-02-16 8:51 ` Yasushi SHOJI
2014-02-16 9:20 ` Nicolas Goaziou
2014-02-16 9:43 ` Michael Brand
2014-02-16 10:00 ` Nicolas Goaziou
2014-02-16 11:52 ` Michael Brand
2014-03-04 9:52 ` Bastien
2015-01-23 11:33 ` Sebastien Vauban
2015-01-23 19:20 ` Sebastien Vauban
2015-01-23 20:31 ` Aaron Ecay
[not found] ` <87egqlgrws.fsf-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2015-01-30 11:02 ` Sebastien Vauban
2014-02-18 4:19 ` Yasushi SHOJI
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).