From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Thomas S. Dye" Subject: Re: [RFC] Dog food, anyone? Date: Mon, 18 Dec 2017 11:02:24 -1000 Message-ID: References: <87efntod73.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:53107) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eR2YW-0006v9-Mj for emacs-orgmode@gnu.org; Mon, 18 Dec 2017 16:02:38 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eR2YS-0007g3-41 for emacs-orgmode@gnu.org; Mon, 18 Dec 2017 16:02:36 -0500 Received: from gproxy9-pub.mail.unifiedlayer.com ([69.89.20.122]:49908) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1eR2YR-0007eh-LJ for emacs-orgmode@gnu.org; Mon, 18 Dec 2017 16:02:32 -0500 Received: from cmgw2 (unknown [10.0.90.83]) by gproxy9.mail.unifiedlayer.com (Postfix) with ESMTP id 6350B1E09FD for ; Mon, 18 Dec 2017 14:02:29 -0700 (MST) In-reply-to: <87efntod73.fsf@nicolasgoaziou.fr> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Nicolas Goaziou Cc: Org Mode List --=-=-= Content-Type: text/plain 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 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=manual-introduction.patch Content-Description: Edits to the introductory section of "Working with source code" >From dc10dff3adf49783ef82ad43338f04ceb888ebc3 Mon Sep 17 00:00:00 2001 From: tsdye 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_{} -#+teinfo: @noindent +#+texinfo: @noindent or : src_[
]{} -- 2.14.2 --=-=-= Content-Type: text/plain -- Thomas S. Dye http://www.tsdye.com --=-=-=--