Emacs Manual topics to remove?

Emacs Manual topics to remove?

[Richard Stallman]

The Emacs Manual is getting bigger and bigger.  Could you suggest
some topics to move into the emacs-xtras manual, which we distribute
only on line?

Re: Emacs Manual topics to remove?

[Chong Yidong]

Richard Stallman <rms@gnu.org> writes:

> The Emacs Manual is getting bigger and bigger.  Could you suggest
> some topics to move into the emacs-xtras manual, which we distribute
> only on line?

I think emerge, picture, the more advanced parts of calendar/diary,
and rmail can be moved into emacs-xtras.

The chapter on Fortran mode can be moved out too -- there's no reason
to have a chapter on Fortran in Emacs, when there isn't one on Perl,
Python, or other (nowadays) more common languages.

Re: Emacs Manual topics to remove?

[Nick Roberts]

 > 
 > > The Emacs Manual is getting bigger and bigger.  Could you suggest
 > > some topics to move into the emacs-xtras manual, which we distribute
 > > only on line?
 > 
 > I think emerge, picture, the more advanced parts of calendar/diary,
 > and rmail can be moved into emacs-xtras.
 > 
 > The chapter on Fortran mode can be moved out too -- there's no reason
 > to have a chapter on Fortran in Emacs, when there isn't one on Perl,
 > Python, or other (nowadays) more common languages.

I think it could cause resentment to suggest removing chapters that others
have contributed.  I wonder if it's possible to count page hits on the online
version at www.gnu.org and generally remove those chapters that receive the
least hits?


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: Emacs Manual topics to remove?

[Jesper Harder]

Richard Stallman <rms@gnu.org> writes:

> The Emacs Manual is getting bigger and bigger.  Could you suggest
> some topics to move into the emacs-xtras manual, which we distribute
> only on line?

Dissociated Press.

Re: Emacs Manual topics to remove?

[Chong Yidong]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > 
>  > > The Emacs Manual is getting bigger and bigger.  Could you suggest
>  > > some topics to move into the emacs-xtras manual, which we distribute
>  > > only on line?
>  > 
>  > I think emerge, picture, the more advanced parts of calendar/diary,
>  > and rmail can be moved into emacs-xtras.
>  > 
>  > The chapter on Fortran mode can be moved out too -- there's no reason
>  > to have a chapter on Fortran in Emacs, when there isn't one on Perl,
>  > Python, or other (nowadays) more common languages.
>
> I think it could cause resentment to suggest removing chapters that others
> have contributed.  I wonder if it's possible to count page hits on the online
> version at www.gnu.org and generally remove those chapters that receive the
> least hits?

Well, they are only being moved to emacs-xtras, not deleted.

Re: Emacs Manual topics to remove?

[Miles Bader]

On 3/13/06, Chong Yidong <cyd@stupidchicken.com> wrote:
> > I think it could cause resentment to suggest removing chapters that others
> > have contributed.  I wonder if it's possible to count page hits on the online
> > version at www.gnu.org and generally remove those chapters that receive the
> > least hits?
>
> Well, they are only being moved to emacs-xtras, not deleted.

In any case, it seems silly to avoid doing necessary pruning because
of some vague fear of offending somebody.  Pretty much _everything_ in
Emacs is a contribution, so one simply can't think this way.

Not that it's an easy decision -- a great deal of what exists in emacs
is "marginal" in some sense (is only used by a relatively small
percentage of users).

It does seem that it would be courteous to bring the authors of the
text into the discussion; maybe they could suggest alternatives such
as abridgement?

Anyway, some possibilities for deletion that come to mind:

   + Nroff mode [obscure language these days, and not very useful content]

   + Asm Mode [fairly useless -- doesn't say much you wouldn't get
from just using the mode]

   + Table mode; I'm not sure about this one -- it could be very
popular, I suppose, but it _is_ quite large.  Maybe there could be a
shortened version in the printed manual (similar to the way that Gnus
has a short intro in the Emacs, manual, which links to the huge
standalone Gnus manual)?

Personally I think "Nroff Mode" and "Asm Mode" could just be deleted
entirely, there seems not much point to them, even in emacs-xtra.

-Miles
--
Do not taunt Happy Fun Ball.

Re: Emacs Manual topics to remove?

[Nick Roberts]

 > > > I think it could cause resentment to suggest removing chapters that
 > > > others have contributed.  I wonder if it's possible to count page hits
 > > > on the online version at www.gnu.org and generally remove those
 > > > chapters that receive the least hits?
 > >
 > > Well, they are only being moved to emacs-xtras, not deleted.

But it appears that emacs-xtras is not being distributed with Emacs which will
reduce its reach considerably.  If the size of the printed manual is the main
concern (I'm only guessing), then perhaps emacs-xtras could be distributed
too.  Then the distinction wouldn't be so great and stuff could be moved
across more freely.

 > In any case, it seems silly to avoid doing necessary pruning because
 > of some vague fear of offending somebody.  

I've not suggested not doing it, but just not doing it in an arbitrary manner.
In any case, in my experience, Emacs development has never seemed to worry
about offending somebody - quite the opposite, in fact!

Nick

Re: Emacs Manual topics to remove?

[Romain Francoise]

Nick Roberts <nickrob@snap.net.nz> writes:

> I think it could cause resentment to suggest removing chapters that
> others have contributed.  I wonder if it's possible to count page hits
> on the online version at www.gnu.org and generally remove those
> chapters that receive the least hits?

I think Richard meant "on line" as opposed to "in print", the goal being
to shave off a few pages from the *paper* version of the manual.

Those sections would still be distributed in the Emacs tarball etc.
(But in the Emacs-Xtra manual.)

-- 
Romain Francoise <romain@orebokech.com> | The sea! the sea! the open
it's a miracle -- http://orebokech.com/ | sea! The blue, the fresh, the
                                        | ever free! --Bryan W. Procter

Re: Emacs Manual topics to remove?

[Richard Stallman]

I agree about moving emerge, picture, and Fortran mode.
Would you like to move them?  Please replace them with brief mentions
in a suitable place, with links.

Re: Emacs Manual topics to remove?

[Richard Stallman]

    I think it could cause resentment to suggest removing chapters that others
    have contributed.

I will live with that.  Please give me suggestions anyway.

Re: Emacs Manual topics to remove?

[Richard Stallman]

    Dissociated Press.

It isn't very big, and it is funny, so on balance I don't think we gain
by moving it out.

Re: Emacs Manual topics to remove?

[Randal L. Schwartz]

>>>>> "Chong" == Chong Yidong <cyd@stupidchicken.com> writes:

Chong> Well, they are only being moved to emacs-xtras, not deleted.

I don't know how practical this is, but if a single page could be made in the
main manual that says "these things are now in the xtra manual" so that those
things can be indexed, that'd be useful.  Lots of places say "look up
dissociated press in 'the manual'", so a forward pointer would help.

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

RE: Emacs Manual topics to remove?

[Drew Adams]

My 2c -

Here are some more candidates for xtras, in addition to those already
identified by others:

* all mail stuff and all news stuff (including gnus)
* all calendar and diary stuff
* version contol (maybe)
* all language modes: C, Fortran, Tex, Nroff, ASM, ...
* running debuggers (GUD)
* international stuff
* AntiNews
* OS-specific stuff (MS Windows, Mac,...), except for basic Unix/GNU-Linux
stuff like man and grep (which is not grouped as OS-specific anyway)

If space permits, these should not be moved out, but if space is tight for
the printed manual, they are candidates.

The xtras "manual" needs a name that doesn't just say "extras". It could be
as simple as making the main manual "Volume 1" and the extras manual "Volume
2". A brief intro in each (printed) manual should describe (characterize)
both manuals. Each manual should include a complete TOC of all topics in
both manuals. It would be better to aim for two volumes that are not
terribly different in size.

In general, the main manual (Volume 1) should include editing that is not
mode-specific, how to get help, search, tags, license and reporting info, a
master index, and info on all major Emacs (user) objects and concepts
(display, frames, windows, buffers, inputting, commands, keys,
customization, ...).

In general, topics that could be moved to xtras include those that are
mode-specific, provide a special service or information, or are less
commonly used.

We should avoid splitting a topic (e.g. calendar/diary, as was suggested),
putting some of its topics in the main manual and others (e.g. advanced) in
the xtras manual. It's better to either include all of a large topic or move
it all to xtras. The content of each manual should be pretty clearly defined
by a set of topics. We should avoid making a division based on intro and
advanced aspects of the same topic.

I agree with those who mentioned that some way should be found to include
the emacs-xtras topics in the main Emacs-manual index, at least in Info. It
should be possible to use Info to navigate to all of the topics (including
xtras) more or less seamlessly.

RE: Emacs Manual topics to remove?

[Chip Coldwell]

On Mon, 13 Mar 2006, Drew Adams wrote:

> The xtras "manual" needs a name that doesn't just say "extras". It could be
> as simple as making the main manual "Volume 1" and the extras manual "Volume
> 2".

[ ... ]

> I agree with those who mentioned that some way should be found to include
> the emacs-xtras topics in the main Emacs-manual index, at least in Info. It
> should be possible to use Info to navigate to all of the topics (including
> xtras) more or less seamlessly.

I agree; and I'll point out that there is precedent.  The printed version 
of the GNU C Library is split in two volumes, but in Info it appears 
contiguous.

Chip

-- 
Charles M. "Chip" Coldwell
Senior Software Engineer
Red Hat, Inc

Re: Emacs Manual topics to remove?

[Luc Teirlinck]

Nick Roberts wrote:

   But it appears that emacs-xtras is not being distributed with Emacs
   which will reduce its reach considerably.

It is called emacs-xtra, not emacs-xtras and it is in the man
directory of the Emacs distribution.  If you use CVS Emacs, it should
be in the menu you get from `C-h i d'.  Otherwise, something is wrong.

Sincerely,

Luc.

Re: Emacs Manual topics to remove?

[Nick Roberts]

 >    But it appears that emacs-xtras is not being distributed with Emacs
 >    which will reduce its reach considerably.
 > 
 > It is called emacs-xtra, not emacs-xtras and it is in the man
 > directory of the Emacs distribution.  If you use CVS Emacs, it should
 > be in the menu you get from `C-h i d'.  Otherwise, something is wrong.

I don't have any trouble finding it, but AFAIK not all the files in CVS
will be used to make a distribution.  When Richard said "on line", I took
it to mean "on the Internet", but as Romain has said thats probably not the
case.

If the goal really is to the make paper version of the manual smaller, it
would be helpful to know by how much.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: Emacs Manual topics to remove?

[Richard Stallman]

    It does seem that it would be courteous to bring the authors of the
    text into the discussion; maybe they could suggest alternatives such
    as abridgement?

I have no time to discuss it with them.

Re: Emacs Manual topics to remove?

[Richard Stallman]

       + Nroff mode [obscure language these days, and not very useful content]

       + Asm Mode [fairly useless -- doesn't say much you wouldn't get
    from just using the mode]

They are so short that we won't save much by moving them.
I think their usefulness is sufficient to justify such a small
amount of text.

       + Table mode; I'm not sure about this one -- it could be very
    popular, I suppose, but it _is_ quite large.  Maybe there could be a
    shortened version in the printed manual (similar to the way that Gnus
    has a short intro in the Emacs, manual, which links to the huge
    standalone Gnus manual)?

This seems like a better candidate to move.  I don't know how
popular it is.

Re: Emacs Manual topics to remove?

[Richard Stallman]

    But it appears that emacs-xtras is not being distributed with Emacs which will
    reduce its reach considerably.

The file name is man/emacs-xtra.texi.

Re: Emacs Manual topics to remove?

[Miles Bader]

On 3/14/06, Drew Adams <drew.adams@oracle.com> wrote:
> Here are some more candidates for xtras, in addition to those already
> identified by others:
...
> If space permits, these should not be moved out, but if space is tight for
> the printed manual, they are candidates.

I think clearly we don't want to eliminate all those modes from the
main manual, because some of the specialized modes are important parts
of emacs, because they are often used by its primary audience, or are
historically significant.

Some things from your list that I think should _not_ be deleted:

   * all mail stuff and all news stuff (including gnus)

Sending mail is an important everyday function for most users, so this
clearly should stay (Gnus has only a short section in the main manual
anyway).

   * all calendar and diary stuff

If the calendar manual is large, maybe it could be moved to a separate
manual, and replaced by a short "basic calendar usage" section in main
manual, but I think this function is often used by many people, so it
shouldn't be deleted entirely.

   * version contol (maybe)

No, this is quite important for many users.

   * all language modes: C, Fortran, Tex, Nroff, ASM, ...

C mode should definitely stay -- it's an important part of emacs for
Emacs' main user base, and morever is something that people often want
to customize.

   * running debuggers (GUD)

This is also very important, it should stay.

   * international stuff

This is of _major_ importance to a large proportion of Emacs' users;
Emacs great support of non-ASCII text is one of its major strengths,

    * AntiNews

Both short and funny.  Should stay.

   * OS-specific stuff (MS Windows, Mac,...), except for basic Unix/GNU-Linux
stuff like man and grep (which is not grouped as OS-specific anyway)

I dunno; are the mac/windows sections long?

-miles

--
Do not taunt Happy Fun Ball.

Re: Emacs Manual topics to remove?

[Lennart Borgman]

Miles Bader wrote:
>    * OS-specific stuff (MS Windows, Mac,...), except for basic Unix/GNU-Linux
> stuff like man and grep (which is not grouped as OS-specific anyway)
>
> I dunno; are the mac/windows sections long?
>   
Any information that is there should be important to the users on the 
specific OS.

Re: Emacs Manual topics to remove?

[Richard Stallman]

    * all mail stuff and all news stuff (including gnus)
    * all calendar and diary stuff
    * version contol (maybe)
    * all language modes: C, Fortran, Tex, Nroff, ASM, ...
    * running debuggers (GUD)
    * international stuff
    * AntiNews

That would be too drastic.  Most of that is very important, and worth
printing in the manual.

RE: Emacs Manual topics to remove?

[Drew Adams]

        * all mail stuff and all news stuff (including gnus)
        * all calendar and diary stuff
        * version contol (maybe)
        * all language modes: C, Fortran, Tex, Nroff, ASM, ...
        * running debuggers (GUD)
        * international stuff
        * AntiNews

    That would be too drastic.

What would be too drastic? To consider them as _candidates_?

    Most of that is very important, and worth printing in the manual.

Of course it is. And not only most of it, but all of it.

I certainly was not proposing moving all of that (or even any of it) out of
the printed manual. And I made it clear that these topics could be looked at
after those that had already been proposed by others had been considered. As
I said, these are _additional_ candidates to consider, if need be.

You asked for candidates. These important topics are nevertheless less
fundamental than basic editing and such, which is the point. If only one or
two obvious candidates are proposed, that doesn't help if the intention or
need is to move more material. Given a long list, you can prioritize it and
pick those least important to move, as space permits. A list that is too
short is no help in moving more material.

You didn't say that enough had already been moved, after moving emerge,
picture, and Fortran. The implication was that you were still looking for
more (how much?) to move. Of the topics that remained and hadn't yet been
suggested (and were not trivially small), I listed the least fundamental
(IMO) as additional candidates.

You didn't make the requirement clear, if you had in mind a particular amout
of material to move. Lacking that, the most appropriate response to your
request would be a prioritized list of _all_ of the manual nodes.

Re: Emacs Manual topics to remove?

[Richard Stallman]

	That would be too drastic.

    What would be too drastic? To consider them as _candidates_?

I did consider them as candidates, and responded that
moving them would be too drastic.

    You didn't make the requirement clear, if you had in mind a particular amout
    of material to move.

I don't have a specific goal.  I am looking for things that are fairly
painless to move.

Re: Emacs Manual topics to remove?

[Chong Yidong]

Richard Stallman <rms@gnu.org> writes:

> I agree about moving emerge, picture, and Fortran mode.
> Would you like to move them?  Please replace them with brief mentions
> in a suitable place, with links.

Done.

By the way, how about moving the "Sorting" node from "Advanced
Features" to "Text", and both "Narrowing" and "Two-Column Windows"
from "Advanced Features" to "Windows"?

Re: Emacs Manual topics to remove?

[Richard Stallman]

    By the way, how about moving the "Sorting" node from "Advanced
    Features" to "Text", and both "Narrowing" and "Two-Column Windows"
    from "Advanced Features" to "Windows"?

Moving Sorting might make sense, but Narrowing has nothing to do with
multiple windows.  That should not be moved.