* [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
@ 2023-12-31 15:24 Ihor Radchenko
2024-01-02 5:24 ` Thomas S. Dye
` (2 more replies)
0 siblings, 3 replies; 14+ messages in thread
From: Ihor Radchenko @ 2023-12-31 15:24 UTC (permalink / raw)
To: emacs-orgmode, Bastien
[-- Attachment #1: Type: text/plain, Size: 345 bytes --]
I'd like to amend the Org manual introduction as in the attached patch.
The idea is to highlight that Org markup is designed to be
human-readable first and foremost rather than just computer-readable.
This is the first section of the manual. Most of the new users will see
it. So, I'd like to hear any objections before installing the patch.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Summary-Clarify-the-Org-markup-is.patch --]
[-- Type: text/x-patch, Size: 1211 bytes --]
From f97e3d9b7e346506f0a87b98f4809e612d7e78b6 Mon Sep 17 00:00:00 2001
Message-ID: <f97e3d9b7e346506f0a87b98f4809e612d7e78b6.1704036076.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sun, 31 Dec 2023 16:20:24 +0100
Subject: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is
human-readable
Readability of raw Org text is one of the core principles we maintain
when designing Org markup language. Let's state it explicitly in the
manual.
---
doc/org-manual.org | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index ff1b9cffb..3ddce7d41 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -22,6 +22,10 @@ ** Summary
It relies on a lightweight plain-text markup language used in files
with the =.org= extension.
+Org files can be viewed using any text editor. You can read and
+understand raw Org markup with a naked eye. Although authoring Org
+files is best-supported inside Emacs.
+
As an authoring tool, Org helps you write structured documents and
provides exporting facilities. Org files can also be used for literate
programming and reproducible research. As a TODO lists manager, Org
--
2.42.0
[-- Attachment #3: Type: text/plain, Size: 224 bytes --]
--
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>
^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2023-12-31 15:24 [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
@ 2024-01-02 5:24 ` Thomas S. Dye
2024-01-03 7:52 ` Jean Louis
2024-01-02 22:47 ` Matt
2024-01-05 13:06 ` [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2 siblings, 1 reply; 14+ messages in thread
From: Thomas S. Dye @ 2024-01-02 5:24 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Bastien, emacs-orgmode
Aloha Ihor,
Ihor Radchenko <yantar92@posteo.net> writes:
> @@ -22,6 +22,10 @@ ** Summary
> It relies on a lightweight plain-text markup language used in
> files
> with the =.org= extension.
>
> +Org files can be viewed using any text editor. You can read
> and
> +understand raw Org markup with a naked eye. Although authoring
> Org
> +files is best-supported inside Emacs.
> +
> As an authoring tool, Org helps you write structured documents
> and
> provides exporting facilities. Org files can also be used for
> literate
> programming and reproducible research. As a TODO lists
> manager, Org
> --
> 2.42.0
How about this, assuming lightweight is equivalent to readable and
easy to understand?
It relies on a readable and easy to understand plain-text markup
language saved to files with the =.org= extension. Authoring Org
files is best supported by Emacs, but you can view and change them
with any text editor. As an authoring tool ...
All the best,
Tom
--
Thomas S. Dye https://tsdye.online/tsdye
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2023-12-31 15:24 [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2024-01-02 5:24 ` Thomas S. Dye
@ 2024-01-02 22:47 ` Matt
2024-01-03 13:44 ` Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable) Ihor Radchenko
2024-01-05 13:06 ` [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2 siblings, 1 reply; 14+ messages in thread
From: Matt @ 2024-01-02 22:47 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode, Bastien
---- On Sun, 31 Dec 2023 16:22:00 +0100 Ihor Radchenko wrote ---
>
> I'd like to amend the Org manual introduction as in the attached patch.
> The idea is to highlight that Org markup is designed to be
> human-readable first and foremost rather than just computer-readable.
>
> This is the first section of the manual. Most of the new users will see
> it. So, I'd like to hear any objections before installing the patch.
I like the points about using any text editor and understanding Org
without an editor. The main point, it seems, is Org mode avoids
lock-in. Two perspectives, the author and the reader, are addressed.
An important question is, "Who are we writing to?"
Addressing authors and readers covers pretty much everyone, I think :)
I believe that makes these good points for the intro.
The first paragraph of the current introduction reads,
"Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.
It relies on a lightweight plain-text markup language used in files
with the =.org= extension."
Since the first paragraph already mentions "lightweight plain-text
markup language," I think making a similar point in the next paragraph
is unnecessary. It may be better to say what you want in the first
paragraph.
I like "human-readable." It's clear and direct. However, trying to
incorporate it into the first paragraph becomes heavy:
"Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.
It relies on a human-readable, plain-text markup language used in
files with the =.org= extension."
That's a lot of hyphenated words and syllables! Maybe "legible" would
be better? It's more precise. But maybe precise isn't good. I'm
wondering if there's a simpler word that accommodates non-native
speakers better (and not just for this word).
"Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.
It relies on a legible, plain-text markup language used in files with
the =.org= extension."
Last comment on your changes. I understand what you mean by "with a
naked eye" and I think it's a valid point. However, not everyone who
uses Emacs can see. I wonder, do the benefits of Org syntax only
apply visually?
Several things in the first paragraph unrelated to your changes stick
out to me. I can't help but make some other remarks.
"TODO" should probably be "to-do". Every dictionary I looked in has
an entry for "to-do". I think that's the common spelling.
Regarding "markup language," that reads to me like programmer jargon.
What does it mean and why should someone care? Again, who are we
writing to? A markup language is a notation for formatting,
structure, and relationships. I think it would be best to directly
say that.
I would also soften that Org "relies" on its markup. It doesn't. I
used Org only for lists for a long time. I believe lists to be a
fundamental feature of Org (and hence a great item for the first
sentence). Lists are as simple as dashes. It's hard to say that
dashes before list items is a markup language.
Finally, I don't think the file extension is relevant for the first
paragraph. Technically, an extension isn't necessary. A person can
call M-x org-mode or use a file local variable. Worse, I think the
extension contradicts the point that any text editor can view an Org
file. Ever try to open a .org file in Windows? It asks for the
program. Yes, *technically* Windows could open a .org file *if* the
person opening it knew which program to use (or to change the
extension to something like .txt). Again, who are we writing to? If
it's someone who believes file extensions matter, then this would
introduce unnecessary friction. It seems best to avoid it. Better to
do as you've done and say Org is readable (which it is) rather than
specify the extension (which doesn't really matter).
Text encodings notwithstanding (plain-text is only as portable as far
as you can guess the encoding), what do you think of something like
this?
modified doc/org-manual.org
@@ -18,9 +18,10 @@
:END:
#+cindex: summary
-Org Mode is an authoring tool and a TODO lists manager for GNU Emacs.
-It relies on a lightweight plain-text markup language used in files
-with the =.org= extension.
+Org Mode is an authoring tool and a to-do lists manager for GNU Emacs.
+It uses a legible plain-text notation to show formatting, structure,
+relationships. Anyone able to edit text can write using Org. Anyone
+able to read text can view it.
As an authoring tool, Org helps you write structured documents and
provides exporting facilities. Org files can also be used for literate
--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-02 5:24 ` Thomas S. Dye
@ 2024-01-03 7:52 ` Jean Louis
2024-01-03 12:36 ` Bastien Guerry
2024-01-03 13:00 ` Ihor Radchenko
0 siblings, 2 replies; 14+ messages in thread
From: Jean Louis @ 2024-01-03 7:52 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Ihor Radchenko, Bastien, emacs-orgmode
* Thomas S. Dye <tsd@tsdye.online> [2024-01-02 08:39]:
> Aloha Ihor,
>
> Ihor Radchenko <yantar92@posteo.net> writes:
>
> > @@ -22,6 +22,10 @@ ** Summary
> > It relies on a lightweight plain-text markup language used in files
> > with the =.org= extension.
> > +Org files can be viewed using any text editor. You can read and
> > +understand raw Org markup with a naked eye. Although authoring Org
> > +files is best-supported inside Emacs.
> > +
> > As an authoring tool, Org helps you write structured documents and
> > provides exporting facilities. Org files can also be used for literate
> > programming and reproducible research. As a TODO lists manager, Org
> > --
> > 2.42.0
>
> How about this, assuming lightweight is equivalent to readable and easy to
> understand?
>
> It relies on a readable and easy to understand plain-text markup language
> saved to files with the =.org= extension. Authoring Org files is best
> supported by Emacs, but you can view and change them with any text editor.
> As an authoring tool ...
In my opinion, it's not that Org was intentionally designed to be
"lightweight markup readable for humans"; rather, it was maintained in
a manner that focused on preserving its readability and prevented it
from evolving into something less comprehensible.
It's primary use was for Emacs users to make notes, TODO tasks,
etc. It is secondary that it became leightweight markup language that
can export to various documents.
--
Jean
Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns
In support of Richard M. Stallman
https://stallmansupport.org/
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-03 7:52 ` Jean Louis
@ 2024-01-03 12:36 ` Bastien Guerry
2024-01-03 13:00 ` Ihor Radchenko
1 sibling, 0 replies; 14+ messages in thread
From: Bastien Guerry @ 2024-01-03 12:36 UTC (permalink / raw)
To: Jean Louis; +Cc: Thomas S. Dye, Ihor Radchenko, emacs-orgmode
Jean Louis <bugs@gnu.support> writes:
> It's primary use was for Emacs users to make notes, TODO tasks,
> etc. It is secondary that it became leightweight markup language that
> can export to various documents.
IMHO it has always been a _lightweight markup language_, used for
notes and TODO tasks, then soon enough for exporting too.
I got interested to Org back circa 2006 after I stopped working on a
small library called bhl.el: https://www.nongnu.org/bhl/
BHL was a lightweight markup language targetting export only. Org was
vastly superior in all accounts, so I contributed to Org.
--
Bastien Guerry
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-03 7:52 ` Jean Louis
2024-01-03 12:36 ` Bastien Guerry
@ 2024-01-03 13:00 ` Ihor Radchenko
1 sibling, 0 replies; 14+ messages in thread
From: Ihor Radchenko @ 2024-01-03 13:00 UTC (permalink / raw)
To: Jean Louis; +Cc: Thomas S. Dye, Bastien, emacs-orgmode
Jean Louis <bugs@gnu.support> writes:
> In my opinion, it's not that Org was intentionally designed to be
> "lightweight markup readable for humans"; rather, it was maintained in
> a manner that focused on preserving its readability and prevented it
> from evolving into something less comprehensible.
The point of my patch is not to show history of Org markup. Rather to
guide the future direction - if we ever add new or change the existing
Org syntax, readability is one of the design guidelines we should follow
(IMHO). Stating it explicitly in the manual will make this guidelines
explicit.
--
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>
^ permalink raw reply [flat|nested] 14+ messages in thread
* Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable)
2024-01-02 22:47 ` Matt
@ 2024-01-03 13:44 ` Ihor Radchenko
2024-01-03 20:43 ` Matt
0 siblings, 1 reply; 14+ messages in thread
From: Ihor Radchenko @ 2024-01-03 13:44 UTC (permalink / raw)
To: Matt; +Cc: emacs-orgmode, Bastien
Matt <matt@excalamus.com> writes:
> Several things in the first paragraph unrelated to your changes stick
> out to me. I can't help but make some other remarks.
>
> "TODO" should probably be "to-do". Every dictionary I looked in has
> an entry for "to-do". I think that's the common spelling.
Yet, we consistently use TODO keyword and TODO list across the whole
manual. Stackexchange tells that both variants are valid:
https://english.stackexchange.com/questions/46217/todo-list-or-to-do-list
although "todo" is much less widely used.
I do not see much benefit changing "todo list" to "to-do list". Both are
clear and both are grammatically correct.
> Regarding "markup language," that reads to me like programmer jargon.
> What does it mean and why should someone care? Again, who are we
> writing to? A markup language is a notation for formatting,
> structure, and relationships. I think it would be best to directly
> say that.
What about "plain text file format"?
> I would also soften that Org "relies" on its markup. It doesn't. I
> used Org only for lists for a long time. I believe lists to be a
> fundamental feature of Org (and hence a great item for the first
> sentence). Lists are as simple as dashes. It's hard to say that
> dashes before list items is a markup language.
Yet, it is. You cannot, for example, use "." as bullets in Org mode.
Also, indentation matters in Org lists, while it does not matter in more
free-style writing.
> Finally, I don't think the file extension is relevant for the first
> paragraph. Technically, an extension isn't necessary. A person can
> call M-x org-mode or use a file local variable. Worse, I think the
> extension contradicts the point that any text editor can view an Org
> file. Ever try to open a .org file in Windows? It asks for the
> program. Yes, *technically* Windows could open a .org file *if* the
> person opening it knew which program to use (or to change the
> extension to something like .txt). Again, who are we writing to? If
> it's someone who believes file extensions matter, then this would
> introduce unnecessary friction. It seems best to avoid it. Better to
> do as you've done and say Org is readable (which it is) rather than
> specify the extension (which doesn't really matter).
I am mostly neutral here, but I can see an argument why mentioning .org
extension may be useful - unlike Windows, GitHub does expect .org file
extension specifically to render Org mode files. The same goes for
non-Emacs editors that support Org markup. For example, Vim/Neovim.
--
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>
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable)
2024-01-03 13:44 ` Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable) Ihor Radchenko
@ 2024-01-03 20:43 ` Matt
2024-01-05 13:17 ` Ihor Radchenko
0 siblings, 1 reply; 14+ messages in thread
From: Matt @ 2024-01-03 20:43 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
---- On Wed, 03 Jan 2024 14:41:29 +0100 Ihor Radchenko wrote ---
> I do not see much benefit changing "todo list" to "to-do list". Both are
> clear and both are grammatically correct.
I said "TODO" to "to-do". I was reacting to it being all caps. I'm sorry I didn't say that.
When it's all caps, TODO is a keyword. Otherwise, it's prose. The following are different (AFAIK):
* TODO Finish this headline
* todo Finish this headline
* to-do Finish this headline
Agreed, it's a minor detail.
> > Regarding "markup language," that reads to me like programmer jargon.
> > What does it mean and why should someone care? Again, who are we
> > writing to? A markup language is a notation for formatting,
> > structure, and relationships. I think it would be best to directly
> > say that.
>
> What about "plain text file format"?
I like that it's less technical. I worry that it's less precise.
I still think a word like "notation," that doesn't derive from computer culture, has a greater chance of being meaningful to people from other domains, like authors, scientists, or engineers. Of course, these same people can easily understand the idea when they see it. It's more important to explain why it matters and that's something we're already doing.
"Markup language" is fine. It's correct. Org syntax is a markup language.
I'm happy to leave it rather than risk bike-shedding it more than I have. If we learn that it caused friction for a newcomer, we can change it easily enough.
> > I would also soften that Org "relies" on its markup. It doesn't. I
> > used Org only for lists for a long time. I believe lists to be a
> > fundamental feature of Org (and hence a great item for the first
> > sentence). Lists are as simple as dashes. It's hard to say that
> > dashes before list items is a markup language.
>
> Yet, it is. You cannot, for example, use "." as bullets in Org mode.
> Also, indentation matters in Org lists, while it does not matter in more
> free-style writing.
Fair points. I concede. :)
> > Finally, I don't think the file extension is relevant for the first
> > paragraph. Technically, an extension isn't necessary. A person can
> > call M-x org-mode or use a file local variable. Worse, I think the
> > extension contradicts the point that any text editor can view an Org
> > file. Ever try to open a .org file in Windows? It asks for the
> > program. Yes, *technically* Windows could open a .org file *if* the
> > person opening it knew which program to use (or to change the
> > extension to something like .txt). Again, who are we writing to? If
> > it's someone who believes file extensions matter, then this would
> > introduce unnecessary friction. It seems best to avoid it. Better to
> > do as you've done and say Org is readable (which it is) rather than
> > specify the extension (which doesn't really matter).
>
> I am mostly neutral here, but I can see an argument why mentioning .org
> extension may be useful - unlike Windows, GitHub does expect .org file
> extension specifically to render Org mode files. The same goes for
> non-Emacs editors that support Org markup. For example, Vim/Neovim.
That's a good point.
Knowing about the .org extension is useful. I don't think it hurts anything other than taking up valuable space. If we need to bump something from the first paragraph, this gets my vote.
--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode
^ permalink raw reply [flat|nested] 14+ messages in thread
* [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2023-12-31 15:24 [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2024-01-02 5:24 ` Thomas S. Dye
2024-01-02 22:47 ` Matt
@ 2024-01-05 13:06 ` Ihor Radchenko
2024-01-06 10:31 ` Matt
2024-02-01 12:16 ` Ihor Radchenko
2 siblings, 2 replies; 14+ messages in thread
From: Ihor Radchenko @ 2024-01-05 13:06 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Bastien
[-- Attachment #1: Type: text/plain, Size: 1477 bytes --]
Ihor Radchenko <yantar92@posteo.net> writes:
> This is the first section of the manual. Most of the new users will see
> it. So, I'd like to hear any objections before installing the patch.
Thanks for the comments!
I am attaching the next iteration of the patch.
"Thomas S. Dye" <tsd@tsdye.online> writes:
> How about this, assuming lightweight is equivalent to readable and
> easy to understand?
>
> It relies on a readable and easy to understand plain-text markup
> language saved to files with the =.org= extension. Authoring Org
> files is best supported by Emacs, but you can view and change them
> with any text editor. As an authoring tool ...
I used a shorter and modified version of your wording with more emphasis
that one can *understand* Org markup.
Matt <matt@excalamus.com> writes:
> +Org Mode is an authoring tool and a to-do lists manager for GNU Emacs.
> +It uses a legible plain-text notation to show formatting, structure,
> +relationships. Anyone able to edit text can write using Org. Anyone
> +able to read text can view it.
As a non-native speaker, I have some difficulties understanding
"legible" meaning in this context. Also, "anyone able to read text can
view it" would be a bit of a bold claim, I think. So, I went with more
moderate wording.
(I will limit this patch to the specific additions I had in mind.
Changes to the existing text you proposed can be discussed separately,
which is why I created a new branch in this thread.)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-doc-org-manual.org-Summary-Clarify-the-Org-markup.patch --]
[-- Type: text/x-patch, Size: 1156 bytes --]
From 9754dea7cca1bc525d0b39cc31e7b0596c5a2bf8 Mon Sep 17 00:00:00 2001
Message-ID: <9754dea7cca1bc525d0b39cc31e7b0596c5a2bf8.1704459551.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sun, 31 Dec 2023 16:20:24 +0100
Subject: [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is
human-readable
Readability of raw Org text is one of the core principles we maintain
when designing Org markup language. Let's state it explicitly in the
manual.
---
doc/org-manual.org | 3 +++
1 file changed, 3 insertions(+)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 65aa5dd30..c6c37441f 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -22,6 +22,9 @@ ** Summary
It relies on a lightweight plain-text markup language used in files
with the =.org= extension.
+Authoring Org files is best supported by Emacs, but you can view,
+understand, and change them with any text editor.
+
As an authoring tool, Org helps you write structured documents and
provides exporting facilities. Org files can also be used for literate
programming and reproducible research. As a TODO lists manager, Org
--
2.42.0
[-- Attachment #3: Type: text/plain, Size: 225 bytes --]
--
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>
^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable)
2024-01-03 20:43 ` Matt
@ 2024-01-05 13:17 ` Ihor Radchenko
0 siblings, 0 replies; 14+ messages in thread
From: Ihor Radchenko @ 2024-01-05 13:17 UTC (permalink / raw)
To: Matt; +Cc: emacs-orgmode
Matt <matt@excalamus.com> writes:
> ---- On Wed, 03 Jan 2024 14:41:29 +0100 Ihor Radchenko wrote ---
>
> > I do not see much benefit changing "todo list" to "to-do list". Both are
> > clear and both are grammatically correct.
>
> I said "TODO" to "to-do". I was reacting to it being all caps. I'm sorry I didn't say that.
>
> When it's all caps, TODO is a keyword. Otherwise, it's prose. The following are different (AFAIK):
>
> * TODO Finish this headline
> * todo Finish this headline
> * to-do Finish this headline
>
> Agreed, it's a minor detail.
Yeah. TODO may be a bit funny. Although, we consistently use "TODO list"
across the manual and often say something like "list of all TODO items",
which is resonant with the concept of TODO keywords in Org mode.
So, TODO in caps actually make some sense within the context of Org
manual. You can call it a style.
Unless I hear from people being seriously confused by "TODO" in caps, I
am inclined to keep the existing style convention.
> ...
> "Markup language" is fine. It's correct. Org syntax is a markup language.
>
> I'm happy to leave it rather than risk bike-shedding it more than I have. If we learn that it caused friction for a newcomer, we can change it easily enough.
+1
--
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>
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-05 13:06 ` [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
@ 2024-01-06 10:31 ` Matt
2024-01-06 12:55 ` Ihor Radchenko
2024-02-01 12:16 ` Ihor Radchenko
1 sibling, 1 reply; 14+ messages in thread
From: Matt @ 2024-01-06 10:31 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
---- On Fri, 05 Jan 2024 14:04:17 +0100 Ihor Radchenko wrote ---
> Thanks for the comments!
> I am attaching the next iteration of the patch.
Looks good
> Matt matt@excalamus.com> writes:
>
> > +Org Mode is an authoring tool and a to-do lists manager for GNU Emacs.
> > +It uses a legible plain-text notation to show formatting, structure,
> > +relationships. Anyone able to edit text can write using Org. Anyone
> > +able to read text can view it.
>
> As a non-native speaker, I have some difficulties understanding
> "legible" meaning in this context.
How does it come across to you?
> Also, "anyone able to read text can
> view it" would be a bit of a bold claim, I think. So, I went with more
> moderate wording.
Good call. That whole sentence is a mess. When I wrote "anyone able to read text", I intended to say something like "if a computer can render the text". However, that reduces to "if a computer can render it, then you can view it" which isn't very impressive.
When you say Org markup is "human-readable", I see that coming from it being plain-text. It requires no special tools. It's readable like "accessible, easily obtained". I'm contrasting that with Jupyter Notebooks. I think this aspect of readability is something we should emphasize.
Readability also means that what's written can be inferred without referencing other sources. It's readable like "apparent, easily understood". I think this is probably what you're thinking of.
What do you mean by "human-readable"?
--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-06 10:31 ` Matt
@ 2024-01-06 12:55 ` Ihor Radchenko
2024-01-06 12:56 ` Matt
0 siblings, 1 reply; 14+ messages in thread
From: Ihor Radchenko @ 2024-01-06 12:55 UTC (permalink / raw)
To: Matt; +Cc: emacs-orgmode
Matt <matt@excalamus.com> writes:
> > As a non-native speaker, I have some difficulties understanding
> > "legible" meaning in this context.
>
> How does it come across to you?
Mostly a confusion between "legible" and "eligible" (I know they have
completely different meanings).
Also, "legible" is not used as frequently as simple "readable", for
example. See "Trends" data in
https://www.collinsdictionary.com/us/dictionary/english/legible vs.
https://www.collinsdictionary.com/us/dictionary/english/readable
So, there are chances that non-native speakers are simply not familiar
with the meaning of "legible", making it more likely to confuse with
similarly-looking "eligible".
> What do you mean by "human-readable"?
This\_
> Readability also means that what's written can be inferred without referencing other sources. It's readable like "apparent, easily understood". I think this is probably what you're thinking of.
--
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>
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-06 12:55 ` Ihor Radchenko
@ 2024-01-06 12:56 ` Matt
0 siblings, 0 replies; 14+ messages in thread
From: Matt @ 2024-01-06 12:56 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
---- On Sat, 06 Jan 2024 13:53:28 +0100 Ihor Radchenko wrote ---
> Matt matt@excalamus.com> writes:
>
> > > As a non-native speaker, I have some difficulties understanding
> > > "legible" meaning in this context.
> >
> > How does it come across to you?
>
> Mostly a confusion between "legible" and "eligible" (I know they have
> completely different meanings).
>
> Also, "legible" is not used as frequently as simple "readable", for
> example. See "Trends" data in
> https://www.collinsdictionary.com/us/dictionary/english/legible vs.
> https://www.collinsdictionary.com/us/dictionary/english/readable
>
> So, there are chances that non-native speakers are simply not familiar
> with the meaning of "legible", making it more likely to confuse with
> similarly-looking "eligible".
Thanks, I understand. That makes sense.
> > What do you mean by "human-readable"?
>
> This\_
>
> > Readability also means that what's written can be inferred without referencing other sources. It's readable like "apparent, easily understood". I think this is probably what you're thinking of.
Gotcha.
--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
2024-01-05 13:06 ` [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2024-01-06 10:31 ` Matt
@ 2024-02-01 12:16 ` Ihor Radchenko
1 sibling, 0 replies; 14+ messages in thread
From: Ihor Radchenko @ 2024-02-01 12:16 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Bastien
Ihor Radchenko <yantar92@posteo.net> writes:
> Thanks for the comments!
> I am attaching the next iteration of the patch.
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=788af5675
--
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>
^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2024-02-01 12:14 UTC | newest]
Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-12-31 15:24 [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2024-01-02 5:24 ` Thomas S. Dye
2024-01-03 7:52 ` Jean Louis
2024-01-03 12:36 ` Bastien Guerry
2024-01-03 13:00 ` Ihor Radchenko
2024-01-02 22:47 ` Matt
2024-01-03 13:44 ` Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable) Ihor Radchenko
2024-01-03 20:43 ` Matt
2024-01-05 13:17 ` Ihor Radchenko
2024-01-05 13:06 ` [PATCH v2] doc/org-manual.org (Summary): Clarify the Org markup is human-readable Ihor Radchenko
2024-01-06 10:31 ` Matt
2024-01-06 12:55 ` Ihor Radchenko
2024-01-06 12:56 ` Matt
2024-02-01 12:16 ` Ihor Radchenko
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).