From: "Thomas S. Dye" <tsd@tsdye.com>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: Org Mode List <emacs-orgmode@gnu.org>
Subject: Re: [RFC] Dog food, anyone?
Date: Mon, 18 Dec 2017 11:02:24 -1000 [thread overview]
Message-ID: <m2mv2foilb.fsf@tsdye.com> (raw)
In-Reply-To: <87efntod73.fsf@nicolasgoaziou.fr>
[-- Attachment #1: Type: text/plain, Size: 1707 bytes --]
Aloha Nicolas,
Nicolas Goaziou writes:
>
> Ultimately, this file is going to serve as the source for a new
> "org.texi". IOW, it could go into "doc/" and "make info" should export
> "manual.org" to "org.texi". First, however, it would be nice to review
> it, either as an Org file, or within the Info viewer, with
>
> (require 'ox-texinfo)
>
> and
>
> `C-c C-e i o' from "manual.org".
I've spent a few hours with manual.org now and I like it very much. The
info file it produces looks clean to me and it compiled without a hitch
using Org mode from the master branch.
One change that might be made globally is the use of em-dash (---) to
set off text, versus en-dash (--) between numerals, e.g. "the range of
run times is 1--5 seconds". I've spotted several places where the
en-dash is used to set off text. See this web site for the convention
on dashes:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html
I appreciate your work on the chapter "Working with source code". I
think it is a big improvement over the original. The reorganization
seems effective to me, especially the integration of "Specific header
arguments" with the structural overview you provide in the first several
sections of the chapter. Thanks!
Attached, please find a patch with some copy editing to the introductory
section of the "Working with source code" chapter. The patch also
includes a correction for a typo elsewhere in the manual.
Like others on the list, I'm pleased by the prospect of being able to
contribute to the Org manual by editing an Org document. It is so much
easier for me than trying to work on org.texi!
Let me know if you have questions.
All the best,
Tom
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Edits to the introductory section of "Working with source code" --]
[-- Type: text/x-patch, Size: 7758 bytes --]
From dc10dff3adf49783ef82ad43338f04ceb888ebc3 Mon Sep 17 00:00:00 2001
From: tsdye <tsd@tsdye.com>
Date: Mon, 18 Dec 2017 10:21:11 -1000
Subject: [PATCH] Edit the introduction
---
contrib/manual.org | 123 +++++++++++++++++++++++++++--------------------------
1 file changed, 62 insertions(+), 61 deletions(-)
diff --git a/contrib/manual.org b/contrib/manual.org
index c497129e9..3781a57ec 100644
--- a/contrib/manual.org
+++ b/contrib/manual.org
@@ -15939,13 +15939,17 @@ keywords.
:END:
#+cindex: source code, working with
-Source code here refers to any code typed in Org documents. Org can
-manage source code in any Org file once such code is tagged with begin
-and end markers. Working with source code begins with tagging source
-code blocks. Tagged blocks are not restricted to the preamble or the
-end of an Org document; they can go anywhere -- with a few exceptions,
-such as not inside comments and fixed width areas. Here's a sample
-source code block in Emacs Lisp:
+Source code here refers to any plain text collection of computer
+instructions, possibly with comments, written using a human-readable
+programming language. Org can manage source code in an Org document
+when the source code is identified with begin and end markers.
+Working with source code begins with identifying source code blocks.
+A source code block can be placed almost anywhere in an Org document;
+it is not restricted to the preamble or the end of the
+document. However, Org cannot manage a source code block if it is
+placed inside an Org comment or within a fixed width section.
+
+Here is an example source code block in the Emacs Lisp language:
#+begin_example
,#+BEGIN_SRC emacs-lisp
@@ -15955,62 +15959,59 @@ source code block in Emacs Lisp:
,#+END_SRC
#+end_example
-Org can take the code in the block delimited by the =#+BEGIN_SRC=
-... =#+END_SRC= markup, and format, compile, execute, and show the
-results. Org can simplify many housekeeping tasks essential to modern
-code maintenance. That's why these blocks in Org mode literature are
-sometimes referred to as /live code/ blocks -- as compared to the
-static text and documentation around it. Users can control how live
-they want each block by tweaking the headers for compiling, execution,
-extraction.
-
-Org's source code block type is one of many block types, such as
-quote, export, verse, latex, example, and verbatim. This section
-pertains to blocks between =#+BEGIN_SRC= and =#+END_SRC=.
-
-For editing source code blocks, Org provides native Emacs major-modes.
-That leverages the latest Emacs features for that source code language
-mode.
-
-For exporting, Org can then extract source code blocks into compilable
-source files -- in a conversion process known as /tangling/ in
-literate programming terminology.
-
-For publishing, Org's back-ends can handle the code blocks and the
-text for output to a variety of formats with native syntax
-highlighting.
-
-For executing the source code in the code blocks, Org provides
-facilities that glue the tasks of compiling, collecting the results of
-the execution, and inserting them back to the Org file. Besides text
-output, results may include links to other data types that Emacs can
-handle: audio, video, and graphics.
-
-An important feature of Org's execution of the code blocks is passing
-variables, functions, and results between them. Such interoperability
-uses a common syntax even if these blocks are in different source code
-languages. The integration extends to linking the debugger's error
-messages to the line in the source code block in the Org file. That
-should partly explain why this functionality by the original
-contributors, Eric Schulte and Dan Davison, was called /Org Babel/.
-
-In literate programming, the main appeal is code and documentation
-co-existing in one file. Org mode takes this several steps further.
-First by enabling execution, and then by inserting results of that
-execution back into the Org file. Along the way, Org provides
-extensive formatting features, including handling tables. Org handles
-multiple source code languages in one file, and provides a common
-syntax for passing variables, functions, and results between source
-code blocks.
+Org can manage the source code in the block delimited by =#+BEGIN_SRC=
+... =#+END_SRC= in several ways that can simplify housekeeping tasks
+essential to modern source code maintenance. Org can edit, format,
+extract, export, and publish source code blocks. Org can also compile and
+execute a source code block, then capture the results. The Org mode
+literature sometimes refers to source code blocks as /live code/
+blocks because they can alter the content of the Org document or the
+material that it exports. Users can control how live they want each
+source code block by tweaking the [[*Using header arguments][header arguments]] for compiling,
+execution, extraction, and exporting.
+
+Source code blocks are one of many Org block types, which also include
+=quote=, =export=, =verse=, =latex=, =example=, and =verbatim=. This
+section pertains to blocks between =#+BEGIN_SRC= and =#+END_SRC=.
+
+For editing and formatting a source code block, Org uses an
+appropriate Emacs major-mode that includes features specifically
+designed for source code in that language.
+
+Org can extract one or more source code blocks and write them to one
+or more source files --- a process known as /tangling/ in literate
+programming terminology.
+
+For exporting and publishing, Org's back-ends can format a source code
+block appropriately, often with native syntax highlighting.
+
+For executing and compiling a source code block, the user can
+configure Org to select the appropriate compiler. Org provides
+facilities to collect the result of the execution or compiler output,
+insert it into the Org document, and/or export it. In addition to
+text results, Org can insert links to other data types, including
+audio, video, and graphics. Org can also link a compiler error message
+to the appropriate line in the source code block.
+
+An important feature of Org's management of source code blocks is the
+ability to pass variables, functions, and results to one another using
+a common syntax for source code blocks in any language. Although most
+literate programming facilities are restricted to one language or
+another, Org's language-agnostic approach lets the literate programmer
+match each programming task with the appropriate computer language and
+to mix them all together in a single Org document. This
+interoperability among languages explains why Org's source code
+management facility was named /Org Babel/ by its originators, Eric
+Schulte and Dan Davison.
Org mode fulfills the promise of easy verification and maintenance of
-publishing reproducible research by keeping all these in the same
-file: text, data, code, configuration settings of the execution
-environment, the results of the execution, and associated narratives,
-claims, references, and internal and external links.
+publishing reproducible research by keeping text, data, code,
+configuration settings of the execution environment, the results of
+the execution, and associated narratives, claims, references, and
+internal and external links in a single Org document.
-Details of Org's facilities for working with source code are shown
-next.
+Details of Org's facilities for working with source code are described
+in the following sections.
** Structure of code blocks
:PROPERTIES:
@@ -16046,7 +16047,7 @@ An inline code block conforms to this structure:
: src_<language>{<body>}
-#+teinfo: @noindent
+#+texinfo: @noindent
or
: src_<language>[<header arguments>]{<body>}
--
2.14.2
[-- Attachment #3: Type: text/plain, Size: 39 bytes --]
--
Thomas S. Dye
http://www.tsdye.com
next prev parent reply other threads:[~2017-12-18 21:02 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
2017-12-17 11:59 ` Vikas Rawal
2017-12-17 18:41 ` Thomas S. Dye
2017-12-17 19:01 ` Nicolas Goaziou
2017-12-17 21:58 ` Thomas S. Dye
2017-12-17 23:03 ` Adrian Bradd
2017-12-18 1:13 ` Thomas S. Dye
2017-12-17 23:44 ` Nicolas Goaziou
2017-12-18 1:15 ` Vikas Rawal
2017-12-18 1:23 ` Thomas S. Dye
2017-12-17 18:51 ` Kaushal Modi
2017-12-17 19:27 ` Nicolas Goaziou
2017-12-17 18:58 ` [RFC] Official Org manual in Org! (Was: Dog food, anyone?) Kaushal Modi
2017-12-21 8:00 ` Marcin Borkowski
2017-12-21 13:47 ` [RFC] Official Org manual in Org! Nicolas Goaziou
2017-12-17 23:10 ` [RFC] Dog food, anyone? Eric Abrahamsen
2017-12-18 21:02 ` Thomas S. Dye [this message]
2017-12-18 22:04 ` Nicolas Goaziou
2017-12-19 0:12 ` Thomas S. Dye
2017-12-19 19:25 ` Nicolas Goaziou
2017-12-19 20:11 ` Thomas S. Dye
2017-12-19 20:16 ` Jonathan Leech-Pepin
2017-12-19 23:11 ` Nicolas Goaziou
2017-12-20 0:05 ` Jonathan Leech-Pepin
2017-12-20 0:59 ` Thomas S. Dye
[not found] ` <WM!57dfd1c25b2c2af3021c1294841c916968d326cf362c32864a6fbc9615cf19dba6ceadc1960e4c3ef5578687af476fba!@mailhub-mx1.ncl.ac.uk>
2017-12-21 12:58 ` Phillip Lord
2017-12-21 13:37 ` Nicolas Goaziou
2017-12-21 17:26 ` Phillip Lord
2017-12-21 19:53 ` Nicolas Goaziou
[not found] ` <WM!3e1c2e8dc2d528e2348759d2a34555337e2f3a5782534bcece582121239ecf030ff1b6d5efd2b2c4955a04c496f00ac6!@mailhub-mx2.ncl.ac.uk>
2017-12-21 22:13 ` Phillip Lord
2017-12-22 18:30 ` Nicolas Goaziou
2017-12-23 6:56 ` Yasushi SHOJI
2017-12-23 14:12 ` Kaushal Modi
2017-12-25 1:44 ` Yasushi SHOJI
2018-04-26 23:34 ` Bastien
2018-04-28 10:56 ` Nicolas Goaziou
2018-04-28 12:43 ` Bastien
2018-05-09 0:30 ` Nicolas Goaziou
2018-05-09 18:16 ` Gregor Zattler
2018-05-09 19:12 ` Nicolas Goaziou
-- strict thread matches above, loose matches on Subject: below --
2018-05-09 18:11 Jon Snader
2018-05-10 8:02 ` Neil Jerram
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=m2mv2foilb.fsf@tsdye.com \
--to=tsd@tsdye.com \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/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).