Advanced calendar usage in emacs-xtra.texi

Advanced calendar usage in emacs-xtra.texi

[Eli Zaretskii]

> From: emacs-diffs-request@gnu.org
> Date: Sat, 26 Mar 2005 13:12:41 -0500
> 
> Message: 13
> Date: Sat, 26 Mar 2005 12:45:16 -0500
> From: Glenn Morris <gmorris@ast.cam.ac.uk>
> Subject: [Emacs-diffs] Changes to emacs/man/calendar.texi
> To: emacs-diffs@gnu.org
> Message-ID: <E1DFFLY-0007MX-00@savannah.gnu.org>
> 
> Index: emacs/man/calendar.texi
> diff -c emacs/man/calendar.texi:1.29 emacs/man/calendar.texi:1.30
> *** emacs/man/calendar.texi:1.29	Mon Mar 21 18:08:14 2005
> --- emacs/man/calendar.texi	Sat Mar 26 17:45:16 2005
> ***************
> *** 21,29 ****
>     @kbd{Mouse-2} in the calendar brings up a menu of operations on a
>   particular date; @kbd{C-Mouse-3} brings up a menu of commonly used
>   calendar features that are independent of any particular date.  To exit
> ! the calendar, type @kbd{q}.  @xref{Calendar, Customizing the Calendar
> ! and Diary,, elisp, The Emacs Lisp Reference Manual}, for customization
> ! information about the calendar and diary.
>   
>   @menu
>   * Calendar Motion::     Moving through the calendar; selecting a date.
> --- 21,29 ----
>     @kbd{Mouse-2} in the calendar brings up a menu of operations on a
>   particular date; @kbd{C-Mouse-3} brings up a menu of commonly used
>   calendar features that are independent of any particular date.  To exit
> ! the calendar, type @kbd{q}.  @xref{Advanced Calendar/Diary Usage,
> ! Customizing the Calendar and Diary,, emacs-xtra, Specialized Emacs
> ! Features}, for customization information about the calendar and diary.

Since emacs-xtra is not distributed with the Emacs manual, I think all
references to it should be inside @ifinfo.  That way, someone who
reads a printed version of the Emacs manual will not wonder where to
find the (non-existent) emacs-xtra manual.

Alternatively, change all references to emacs-xtra to use @inforef.

Re: Advanced calendar usage in emacs-xtra.texi

[Luc Teirlinck]

Eli Zaretskii wrote:

   Since emacs-xtra is not distributed with the Emacs manual, I think all
   references to it should be inside @ifinfo.  That way, someone who
   reads a printed version of the Emacs manual will not wonder where to
   find the (non-existent) emacs-xtra manual.

Somebody reading the Emacs manual presumably does so with the intent
of using emacs.  When using Emacs, he can read emacs-xtra using Info.
He can even print out hardcopy for emacs-xtra.  So things like this
should definitely _not_ be in @ifinfo.

   Alternatively, change all references to emacs-xtra to use @inforef.

That would be a lot better.

However, last time when I proposed something similar (for url.texi, if
I remember well), you and Karl and Dave opposed me on this and I wound
up using a regular @xref.  Did you change your mind on this or is
there a fundamental difference between emacs-xtra and url.texi?

Sincerely,

Luc.

Re: Advanced calendar usage in emacs-xtra.texi

[Eli Zaretskii]

> Date: Sat, 26 Mar 2005 14:00:42 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org, gmorris@ast.cam.ac.uk
> 
> However, last time when I proposed something similar (for url.texi, if
> I remember well), you and Karl and Dave opposed me on this and I wound
> up using a regular @xref.  Did you change your mind on this or is
> there a fundamental difference between emacs-xtra and url.texi?

Well, I didn't suggest @inforef as the first choice this time either,
did I?  I still think @ifinfo is a better choice.

One fundamental difference between emacs-xtra and url is that the
former holds material that was deliberately excluded from the Emacs
manual.  OTOH, url is the documentation of a package.

Re: Advanced calendar usage in emacs-xtra.texi

[Luc Teirlinck]

Eli Zaretskii wrote:

   One fundamental difference between emacs-xtra and url is that the
   former holds material that was deliberately excluded from the Emacs
   manual.  OTOH, url is the documentation of a package.

I do not know what the exact relevance of "deliberately excluded from
the Emacs" is.  What it definitely does _not_ mean is that it is
unimportant.  Due to the fact that we have to keep the size of the
physical Emacs manual down, we can unfortunately not include all
important info in the Emacs manual.  Things included in emacs-xtra
could very easily be of more interest to most people than, say, url,
which many people may never use.

Sincerely,

Luc.

Re: Advanced calendar usage in emacs-xtra.texi

[Glenn Morris]

"Eli Zaretskii" wrote:

> Since emacs-xtra is not distributed with the Emacs manual, I think
> all references to it should be inside @ifinfo. That way, someone who
> reads a printed version of the Emacs manual will not wonder where to
> find the (non-existent) emacs-xtra manual.
>
> Alternatively, change all references to emacs-xtra to use @inforef.

Thanks for the texinfo tip. I've changed all relevant @xref's to
@inforef's.

Re: Advanced calendar usage in emacs-xtra.texi

[Luc Teirlinck]

This leaves us with the question of what constitutes appropriate use
of @inforef.  (The one reference to emacs-xtra from the Emacs manual
which I put in a lot earlier also uses @inforef.)

I originally proposed that @inforef should refer to any manual for
which there is no _published_ rather than printable version available
or planned.  This was rejected.  Instead `(texinfo)inforef' says that
it is only appropriate to refer to text inside @info or to old Info
that did not have a corresponding .texi file and for which printed
text can not be produced.

I would say that it should be considered appropriate when used inside
a manual, such as the Emacs manual, for which a published version is
available and widely used, to refer to a manual without published
version.  Otherwise, the result could indeed be very confusing to a
reader of the published version who is not familiar with Texinfo.

Sincerely,

Luc.

Re: Advanced calendar usage in emacs-xtra.texi

[Richard Stallman]

    This leaves us with the question of what constitutes appropriate use
    of @inforef.

How about if you and whoever else is specifically interested
discuss this on bug-texinfo?