Re: [O] [RFC] Dog food, anyone?

[Nicolas Goaziou]

Hello,

"Thomas S. Dye" <address@hidden> writes:

> 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.

Great!

> 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 think it is a matter of "American English" vs "British English"
convention. See, e.g., <https://www.gsbe.co.uk/grammar-the-dash.html>.

I consistently used the latter because I find it more aesthetically
pleasing. As a GNU manual, we can switch to the American English
convention everywhere. In this case, however, em-dash are not
spaced-out.

In the same vein, we also need to use title case. This needs some
special care as fuzzy links need to be updated accordingly.

WDYT?

> 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.

Thank you. I applied it with the changes mentioned below.

> +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.

I changed it to

  ... by tweaking the header arguments (see [[* Using header
  arguments]]) for compiling...

For more information, see (info "(texinfo) @ref"), last paragraphs.
N.B.: I suggest to read it in regular info viewer, i.e., "info texinfo"
from the command line, instead of Emacs to make sense out of this.

> +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.

I changed it to

    ... or more sources files---a process known as...

per above.


Regards,

-- 
Nicolas Goaziou                                                0x80A93738