Please help get ready for proofreading of Emacs manual

Please help get ready for proofreading of Emacs manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I'd like to ask the Emacs user community to check and proofread parts
of the Emacs manual.  The first step is to make a list of parts of the
manual so I can ask people to choose a part and check it.

I'd like each part to be between 10 and 20 pages (preferably not more
than 15).  Ideally, each piece would start and end on a chapter
boundary, but since some chapters are longer than that, some
exceptions are inevitable.

Would someone please make a suitable list of parts and send it to me?

Since some people will proofread the source code rather than the
formatted version, I'd like to offer a way of delimiting the same
parts in the source code.  A way to do this would be to list some text
at the start of the part and some text at the end of the part.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please help get ready for proofreading of Emacs manual

[Charles A. Roelli]

Here's a start, based on a recent build of the Emacs manual (644
pages).  "LONG" parts may still be further split, "SHORT" parts
combined.

Part 1
Preface..................................................1
Distribution..............................................2
Introduction ............................................. 5
1	The Organization of the Screen .......................... 6

Part 2
2	Characters, Keys and Commands........................11
3	Entering and Exiting Emacs............................ 14
4	Basic Editing Commands .............................. 16

Part 3
5	The Minibuffer.......................................26
6	Running Commands by Name .......................... 36

Part 4
7	Help............................................... 38

Part 5
8	The Mark and the Region.............................. 47
9	Killing and Moving Text............................... 54

Part 6
10	Registers ........................................... 66

Part 7
11	Controlling the Display................................ 71 LONG

Part 8
12	Searching and Replacement ............................ 94 LONG

Part 9
13	Commands for Fixing Typos...........................118
14	Keyboard Macros....................................124

Part 10
15	File Handling....................................... 132 LONG

Part 11
16	Using Multiple Buffers ............................... 157
17	Multiple Windows ................................... 166

Part 12
18	Frames and Graphical Displays ........................ 173

Part 13
19	International Character Set Support .................... 190 LONG

Part 14
20	Major and Minor Modes.............................. 212 SHORT
21      Indentation.........................................218

Part 15
22	Commands for Human Languages ...................... 221 LONG

Part 16
23	Editing Programs....................................254 LONG

Part 17
24	Compiling and Testing Programs ....................... 276

Part 18
25	Maintaining Large Programs...........................296 LONG

Part 19
26	Abbrevs ........................................... 327 SHORT

Part 20
27	Dired, the Directory Editor............................333

Part 21
28	The Calendar and the Diary........................... 350

Part 22
29	Sending Mail ....................................... 369 SHORT

Part 23
30	Reading Mail with Rmail ............................. 378

Part 24
31	Miscellaneous Commands ............................. 398 LONG

Part 25
32	Emacs Lisp Packages................................. 432 SHORT

Part 26
33	Customization ...................................... 437 LONG

Part 27
34	Dealing with Common Problems ....................... 469

Part 28
A	GNU GENERAL PUBLIC LICENSE ................... 487
B	GNU Free Documentation License...................... 498

Part 29
C	Command Line Arguments for Emacs Invocation.......... 506

Part 30
D	X Options and Resources ............................. 521
E	Emacs 25 Antinews .................................. 528

Part 31
F	Emacs and Mac OS / GNUstep ........................ 531
G	Emacs and Microsoft Windows/MS-DOS ................ 534

The following parts may not all need to be proofread:

Part 32
The GNU Manifesto ..................................... 544

Part 33
Glossary...............................................552

Part 34
Key (Character) Index ................................... 575
Command and Function Index............................. 585

Part 35
Variable Index.......................................... 599
Concept Index.......................................... 607

Re: Please help get ready for proofreading of Emacs manual

[Marcin Borkowski]

On 2017-09-18, at 20:53, Charles A. Roelli <charles@aurox.ch> wrote:

> Here's a start, based on a recent build of the Emacs manual (644
> pages).  "LONG" parts may still be further split, "SHORT" parts
> combined.

I could take one of the "Long" parts.  (I'd like especially to do part
15, since I edit documents in natural languages in Emacs _a lot_, but
part 16 would also be nice - I also happen to be a programmer.)

While I am fairly busy now, this is kind of work I do like a lot and
I will gladly do it in my spare time.  (Also, I've been doing
proofreading professionally for a journal for about 10 years now, though
not in English.)  I'd consider it also a way to give back to the Emacs
devs for the great work they have been doing for the last four decades.

What I absolutely _must_ know beforehand, though, is:

1. How much time do I have for this task.

2. What exactly should I pay attention to?  I assume that the most
important things to look for are parts which are impreciseor difficult
to understand, not ordinary typos.  But: should I check factual
correctness (for instance, whether the keys given really do correspond
to the command names in emacs -Q, or whether there are no mistakes in
command names)?  (I assume yes.)  Is there anything else?

3. In what format I should submit my corrections?  (A simple diff/patch
might not be enough, since I might have a suggestion which may be
controversial and hence should be discussed.  How would I mark such
places?)

I think these questions are relevant to other proofreaders, too.

Best,

and I'm really looking forward to this job.

--
Marcin Borkowski

Re: Please help get ready for proofreading of Emacs manual

[Eric Abrahamsen]

charles@aurox.ch (Charles A. Roelli) writes:

> Here's a start, based on a recent build of the Emacs manual (644
> pages).  "LONG" parts may still be further split, "SHORT" parts
> combined.

I'd be happy to take on a section, as well. I write, translate, and edit
professionally, and have done for more than a decade, and would also be
happy to give back in words what I can't in code!

Re: Please help get ready for proofreading of Emacs manual

[Nick Helm]

charles@aurox.ch (Charles A. Roelli) writes:

> Here's a start, based on a recent build of the Emacs manual (644
> pages).  "LONG" parts may still be further split, "SHORT" parts
> combined.

I can help with this effort too. 

Does Emacs have a documentation standard and/or style guide?

Nick

Re: Please help get ready for proofreading of Emacs manual

[Eli Zaretskii]

> From: Nick Helm <nick@tenpoint.co.nz>
> Date: Tue, 19 Sep 2017 11:36:29 +1200
> 
> I can help with this effort too. 

Thanks, this is appreciated.

> Does Emacs have a documentation standard and/or style guide?

Our style guide is the Texinfo documentation, it describes when and
how to use each markup, and how to structure manuals.

Some additional guidelines are in the GNU Coding Standards document.

Re: Please help get ready for proofreading of Emacs manual

[Petteri Hintsanen]

Hello,

I'd also like to help on this, if you accept non-native English
speakers.  Preferably a short section, please.

I do have some experience in proofreading from my previous life in
academia, where reading and writing research papers and such is the
standard state of things.

Thanks,
Petteri

Re: Please help get ready for proofreading of Emacs manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Thank you very much.

Would someone like to subdivide the long parts?

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please help get ready for proofreading of Emacs manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >   But: should I check factual
  > correctness (for instance, whether the keys given really do correspond
  > to the command names in emacs -Q, or whether there are no mistakes in
  > command names)?  (I assume yes.)  Is there anything else?

To do this efficiently, I suggest starting by reviewing the NEWS files
for the past few Emacs major releases to recall what has been changed.

You don't need to read the WHOLE NEWS file.  Most of it, you can
ignore.  For instance, ignore the parts that don't affect the editing
interface.  Ignore the modes not covered in the Emacs manual, which is
most of them.

Don't try to remember all the details of what you see in NEWS -- just
which areas have changed.

Then, as you read and check the manual, if any of those areas comes
up, you will notice it.  At that point, refer to NEWS to double-check
that the text is correct.  You won't need to do that very often.

  > 3. In what format I should submit my corrections?  (A simple diff/patch
  > might not be enough, since I might have a suggestion which may be
  > controversial and hence should be discussed.  How would I mark such
  > places?)

When it is a simple change, a diff is fine.  You could send it as a
bug report.  I recommend sending only 5 such simple changes in one bug
report -- then start another.  It's only a matter of the maintainers'
convenience.

If you see a more complex issue, please write about it on emacs-devel.
For complex issues, how you format your mail is not crucial, since
the hard part will be thinking about the issue itself.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please help get ready for proofreading of Emacs manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The following parts may not all need to be proofread:


  > Part 32
  > The GNU Manifesto ..................................... 544

That's right.  This is unchanged.

  > Part 33
  > Glossary...............................................552

That one should be checked, if it has changed since Emacs 21.

  > Part 34
  > Key (Character) Index ................................... 575
  > Command and Function Index............................. 585

  > Part 35
  > Variable Index.......................................... 599
  > Concept Index.......................................... 607

The indices need to be checked in two special, simple ways:

* Looking for items that are too long (so they mess up the formatting).

* Looking for items that are effectively duplicates.
If they start with the same word and go to the same page,
usually one should be deleted (but not absolutely always).
Here's an artificial example:

  string constant ......................................42
  string ...............................................42

Also, multiple pages for the same topic might mean one should be
deleted, keeping the one that gives the full explanation of that
topic.

Also, there can be spelling errors in the index as anywhere else.



-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please help get ready for proofreading of Emacs manual

[Marcin Borkowski]

On 2017-09-19, at 21:33, Richard Stallman <rms@gnu.org> wrote:

> When it is a simple change, a diff is fine.  You could send it as a
> bug report.  I recommend sending only 5 such simple changes in one bug
> report -- then start another.  It's only a matter of the maintainers'
> convenience.

How about a commit on some specialized branch?

> If you see a more complex issue, please write about it on emacs-devel.
> For complex issues, how you format your mail is not crucial, since
> the hard part will be thinking about the issue itself.

Fair enough.

-- 
Marcin Borkowski

Re: Please help get ready for proofreading of Emacs manual

[Charles A. Roelli]

> From: Richard Stallman <rms@gnu.org>
> CC: emacs-devel@gnu.org
> Date: Tue, 19 Sep 2017 15:33:20 -0400
> 
> Thank you very much.

And thank you for Emacs!

> Would someone like to subdivide the long parts?

Here's one attempt:

Part 7
11	Controlling the Display................................ 71 LONG
Part 7a Chapter Beginning - Font Lock mode..................... 71-82
Part 7b Interactive Highlighting - Chapter End ................ 82-93

Part 8
12	Searching and Replacement ............................ 94 LONG
Part 8a Chapter Beginning - Regular Expression Search ........ 94-103
Part 8b Syntax of Regular Expressions - Chapter End .......... 103-117

Part 10
15	File Handling....................................... 132 LONG
Part 10a Chapter Beginning - Saving Files .................. 132-143
Part 10b Reverting a Buffer - Chapter End .................. 143-156

Part 15
22	Commands for Human Languages ...................... 221 LONG
Part 15a Chapter Beginning - Outline Mode ................. 221 - 236
Part 15b TeX Mode - Chapter End ........................... 236 - 253

Part 16
23	Editing Programs................................... 254 LONG
Part 16a Chapter Beginning - Commands for editing w/ parentheses ... 254-263
Part 16b Manipulating Comments - Chapter End .............. 263-275

Part 18
25	Maintaining Large Programs.......................... 296 LONG
Part 18a Version Control ................................... 296-313
Part 18b Change Logs - Chapter End ......................... 313-326

Part 24
31	Miscellaneous Commands ............................. 398 LONG
Part 24a Chapter Beginning - Running Shell Commands from Emacs ... 398-415
Part 24b Using Emacs as a Server - Chapter End ............. 415-431

Part 26
33	Customization ...................................... 437 LONG
Part 26a Chapter Beginning - Variables ..................... 437-454
Part 26a Customizing Key Bindings - Chapter End ............ 454-468

Re: Please help get ready for proofreading of Emacs manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > When it is a simple change, a diff is fine.  You could send it as a
  > > bug report.  I recommend sending only 5 such simple changes in one bug
  > > report -- then start another.  It's only a matter of the maintainers'
  > > convenience.

  > How about a commit on some specialized branch?

It is for the Emacs maintainers to decide whether that method is ok.
They are the ones who will need to use it.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please help get ready for proofreading of Emacs manual

[John Wiegley]

>>>>> "RS" == Richard Stallman <rms@gnu.org> writes:

>> How about a commit on some specialized branch?
RS> It is for the Emacs maintainers to decide whether that method is ok. They
RS> are the ones who will need to use it.

I think having a branch devoted to manual edits is a good idea, something
branched off of emacs-26 that we can frequently merge back.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Please help get ready for proofreading of Emacs manual

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Date: Wed, 20 Sep 2017 15:03:43 -0700
> Cc: charles@aurox.ch, emacs-devel@gnu.org
> 
> >>>>> "RS" == Richard Stallman <rms@gnu.org> writes:
> 
> >> How about a commit on some specialized branch?
> RS> It is for the Emacs maintainers to decide whether that method is ok. They
> RS> are the ones who will need to use it.
> 
> I think having a branch devoted to manual edits is a good idea, something
> branched off of emacs-26 that we can frequently merge back.

Please don't.  Each additional branch brings some overhead to work
with it, and also a non-negligible probability of making mistakes,
like pushing to the wrong branch.  Separate branches are justified for
experimental code changes, because they avoid breaking the main
branches which many people follow.  But documentation can never break
anything, and any non-trivial changes in it need to be reviewed
anyway.  So I see no need for a branch, it would just be an
unnecessary nuisance and source of errors.

Proposed changes for the manuals should be posted in the usual manner:
with "M-x report-emacs-bug RET".

TIA

Re: Please help get ready for proofreading of Emacs manual

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> Proposed changes for the manuals should be posted in the usual manner: with
> "M-x report-emacs-bug RET".

OK, if that's what works best for you, let's do it that way. No extra branches
just for documentation.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Please help get ready for proofreading of Emacs manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Thanks.  With that, only a few steps are needed before I ask people to
volunteer for parts.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.