From: Matt <matt@excalamus.com>
To: "Ihor Radchenko" <yantar92@posteo.net>
Cc: "emacs-orgmode" <emacs-orgmode@gnu.org>, "Bastien" <bzg@gnu.org>
Subject: Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable
Date: Tue, 02 Jan 2024 23:47:19 +0100 [thread overview]
Message-ID: <18ccc5c24ab.11c0534ea910085.7925872212667260908@excalamus.com> (raw)
In-Reply-To: <87il4e75u8.fsf@localhost>
---- 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
next prev parent reply other threads:[~2024-01-02 22:48 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=18ccc5c24ab.11c0534ea910085.7925872212667260908@excalamus.com \
--to=matt@excalamus.com \
--cc=bzg@gnu.org \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).