RE: C-h r and Images

RE: C-h r and Images

[Drew Adams]

> > With the following MS Windows build I see no images in the GnuTLS
> > manual, and it does not even have a `TLS layers', node AFAICT.
> 
> Maybe you have a very old manual.

Perhaps.  The Emacs 24 build is from 2013-08-23, but that doesn't mean
the manual itself is recent.

> Mine says this at the very beginning (in node "Top"):
>
>   This manual is last updated 25 November 2011 for version 3.0.9 of
>   GnuTLS.

Mine says no such thing ("is" should be "was" in that text, BTW).
Nothing at all about a GnuTLS version.  This is all it says before the
copyright boilerplate text:

   This manual describes the Emacs GnuTLS integration.

   GnuTLS is a library that establishes encrypted SSL or TLS
   connections.  Emacs supports it through the `gnutls.c' and
   `gnutls.h' C files and the `gnutls.el' Emacs Lisp library.

   This file describes the Emacs GnuTLS integration.
 
> It does have the "TLS layers" node, and that node does show an image.

OK, clearly we have different versions of the manual.

Re: C-h r and Images

[Eli Zaretskii]

> Date: Mon, 2 Sep 2013 10:02:18 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: eggert@cs.ucla.edu, kjambunathan@gmail.com, emacs-devel@gnu.org
> 
> > > With the following MS Windows build I see no images in the GnuTLS
> > > manual, and it does not even have a `TLS layers', node AFAICT.
> > 
> > Maybe you have a very old manual.
> 
> Perhaps.  The Emacs 24 build is from 2013-08-23, but that doesn't mean
> the manual itself is recent.

I wasn't talking about the emacs-gnutls.info manual.  I was talking
about the gnutls.info manual, which is installed with the GnuTLS DLL.

> OK, clearly we have different versions of the manual.

Different manuals, not different versions.

RE: C-h r and Images

[Drew Adams]

> > > What's more, it would be helpful to hyperlink directly to an explanation
> > > of the term in question, rather than just saying "which see" or some
> > > such English alternative to "q.v."
> >
> > I made a patch for it.  See bug#15254.
> 
> Thanks.  However, I'm not sure doing this is useful.  The Glossary is
> a long series of short paragraphs, each one explaining one term.  What
> your patch does is add a cross-reference to many of these short
> paragraphs, which makes those paragraphs longer and more complex to
> read and grasp at first glance.  OTOH, since the terms are listed in
> alphabetic order, it is quite easy to find a given term, even if you
> just scroll and don't use the search commands.
> 
> So my take of this is that on balance this is not useful.

I haven't looked at the patch itself.  But the idea should be, if
possible, to have inline xrefs (links).  That is, not add any extra text
(e.g. "See"), but just turn the term used in the text into a link to its
own definition.

That's pretty common in glossaries these days (and in indexes, when
referring to another index entry).

And yes, it's a lot easier to click (or hit `RET' on) a term to look at
its definition, and then click `Back' (or hit `l') to get back to where
you were, than it is to scroll down to find its definition and then
scroll back and find where you were.

Now, if it is not possible today to have inline xrefs in Info then
that's too bad.  Then it's a tradeoff: Is the convenience of direct
access worth the extra verbage ("See" or whatever) added?

Re: C-h r and Images

[Juri Linkov]

> Now, if it is not possible today to have inline xrefs in Info then
> that's too bad.  Then it's a tradeoff: Is the convenience of direct
> access worth the extra verbage ("See" or whatever) added?

Today it's possible to have inline xrefs like they are
implemented for footnotes.  But the problem is how to
detect inline xrefs in Info files.  I mean when
inline and non-inline xrefs are defined in the source as:

The bindings of all key sequences are recorded in the keymaps
(@pxref{Glossary---Keymap}). @xref{Keymaps}.

How to distinguish them in the Info output of makeinfo
and render them differently in the Info reader?

> How would that be done on parts of an image (which is just pixels)?
> Can we do (the equivalent of) image maps, letting users, in effect,
> click a callout (e.g., for "Mode Line"), to go to an appropriate part
> of the manual for more info about it (e.g., `(emacs) Mode Line'), or to
> provide a tooltip with a little related info?

Maybe sliced images could help to do such image maps where
anchors will be attached to sliced parts of an image.

Re: C-h r and Images

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Xue Fuqiao <xfq.free@gmail.com>,  eggert@cs.ucla.edu,  kjambunathan@gmail.com,  emacs-devel@gnu.org
> Date: Tue, 03 Sep 2013 23:37:43 +0300
> 
> > Now, if it is not possible today to have inline xrefs in Info then
> > that's too bad.  Then it's a tradeoff: Is the convenience of direct
> > access worth the extra verbage ("See" or whatever) added?
> 
> Today it's possible to have inline xrefs like they are
> implemented for footnotes.  But the problem is how to
> detect inline xrefs in Info files.  I mean when
> inline and non-inline xrefs are defined in the source as:
> 
> The bindings of all key sequences are recorded in the keymaps
> (@pxref{Glossary---Keymap}). @xref{Keymaps}.
> 
> How to distinguish them in the Info output of makeinfo
> and render them differently in the Info reader?

For some reason you are talking only about the Info format.  Please
don't forget about other formats that can be generated from Texinfo,
notably HTML and the printable formats (DVI, PDF, etc.).  They all
need to work with whatever new machinery you want to use.  Texinfo
cross-references (@pxref, @ref, etc.) do work in all these formats,
but in the printed manual they will produce text that is quite.  And
if you will use just @ref, the printed result will look incorrect
English.

Re: C-h r and Images

[Xue Fuqiao]

On Wed, Sep 4, 2013 at 4:37 AM, Juri Linkov <juri@jurta.org> wrote:
>> Now, if it is not possible today to have inline xrefs in Info then
>> that's too bad.  Then it's a tradeoff: Is the convenience of direct
>> access worth the extra verbage ("See" or whatever) added?
>
> Today it's possible to have inline xrefs like they are
> implemented for footnotes.  But the problem is how to
> detect inline xrefs in Info files.  I mean when
> inline and non-inline xrefs are defined in the source as:
>
> The bindings of all key sequences are recorded in the keymaps
> (@pxref{Glossary---Keymap}). @xref{Keymaps}.

What about this version:

  The bindings of all key sequences are recorded in the
  @ref{Glossary---Keymap, keymaps}.  @xref{Keymaps}.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: C-h r and Images

[Xue Fuqiao]

On Thu, Sep 5, 2013 at 6:38 AM, Xue Fuqiao <xfq.free@gmail.com> wrote:
> On Wed, Sep 4, 2013 at 4:37 AM, Juri Linkov <juri@jurta.org> wrote:
>>> Now, if it is not possible today to have inline xrefs in Info then
>>> that's too bad.  Then it's a tradeoff: Is the convenience of direct
>>> access worth the extra verbage ("See" or whatever) added?
>>
>> Today it's possible to have inline xrefs like they are
>> implemented for footnotes.  But the problem is how to
>> detect inline xrefs in Info files.  I mean when
>> inline and non-inline xrefs are defined in the source as:
>>
>> The bindings of all key sequences are recorded in the keymaps
>> (@pxref{Glossary---Keymap}). @xref{Keymaps}.
>
> What about this version:
>
>   The bindings of all key sequences are recorded in the
>   @ref{Glossary---Keymap,  keymaps}.  @xref{Keymaps}.
                           ^
                           ,

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: C-h r and Images

[Eli Zaretskii]

> Date: Thu, 5 Sep 2013 06:38:44 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: Drew Adams <drew.adams@oracle.com>, Eli Zaretskii <eliz@gnu.org>, eggert@cs.ucla.edu, 
> 	kjambunathan@gmail.com, emacs-devel <emacs-devel@gnu.org>
> 
> What about this version:
> 
>   The bindings of all key sequences are recorded in the
>   @ref{Glossary---Keymap, keymaps}.  @xref{Keymaps}.

Did you look at what this produces in the printed version of the
manual?

Re: C-h r and Images

[Xue Fuqiao]

On Thu, Sep 5, 2013 at 3:07 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu, 5 Sep 2013 06:38:44 +0800
>> From: Xue Fuqiao <xfq.free@gmail.com>
>> Cc: Drew Adams <drew.adams@oracle.com>, Eli Zaretskii <eliz@gnu.org>, eggert@cs.ucla.edu,
>>       kjambunathan@gmail.com, emacs-devel <emacs-devel@gnu.org>
>>
>> What about this version:
>>
>>   The bindings of all key sequences are recorded in the
>>   @ref{Glossary---Keymap,, keymaps}.  @xref{Keymaps}.
>
> Did you look at what this produces in the printed version of the
> manual?

If it is weird in the printed version, we can use
@iftex/@ifnottex/@inlinefmt.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: C-h r and Images

[Eli Zaretskii]

> Date: Fri, 6 Sep 2013 18:53:08 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: juri@jurta.org, eggert@cs.ucla.edu, kjambunathan@gmail.com, 
> 	drew.adams@oracle.com, emacs-devel <emacs-devel@gnu.org>
> 
> On Thu, Sep 5, 2013 at 3:07 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >> Date: Thu, 5 Sep 2013 06:38:44 +0800
> >> From: Xue Fuqiao <xfq.free@gmail.com>
> >> Cc: Drew Adams <drew.adams@oracle.com>, Eli Zaretskii <eliz@gnu.org>, eggert@cs.ucla.edu,
> >>       kjambunathan@gmail.com, emacs-devel <emacs-devel@gnu.org>
> >>
> >> What about this version:
> >>
> >>   The bindings of all key sequences are recorded in the
> >>   @ref{Glossary---Keymap,, keymaps}.  @xref{Keymaps}.
> >
> > Did you look at what this produces in the printed version of the
> > manual?
> 
> If it is weird in the printed version, we can use
> @iftex/@ifnottex/@inlinefmt.

Yes, but the question is what to write inside @iftex.

RE: C-h r and Images

[Drew Adams]

> > > > With the following MS Windows build I see no images in the GnuTLS
> > > > manual, and it does not even have a `TLS layers', node AFAICT.
> > >
> > > Maybe you have a very old manual.
> >
> > Perhaps.  The Emacs 24 build is from 2013-08-23, but that doesn't mean
> > the manual itself is recent.
> 
> I wasn't talking about the emacs-gnutls.info manual.  I was talking
> about the gnutls.info manual, which is installed with the GnuTLS DLL.
> 
> > OK, clearly we have different versions of the manual.
> 
> Different manuals, not different versions.

I see.  Sorry for the noise.

But why is it, in that case, that the Emacs GNU TLS manual uses the
abbreviation "GnuTLS" in the Info menu?  Seems like a bug.

The file name is `emacs-gnutls' - e.g., `(emacs-gnutls)Top'.  Seems like
that should be used in the Info menu too: `EmacsGnuTLS' or some such.

C-h r and Images

[Jambunathan K]

C-h r and Images

Why does Emacs Info manual has no images?  

Is it because the Info browser doesn't support it.  Or is it authors are
 happy texting rather than doodling.

Just curious.

Re: C-h r and Images

[Eli Zaretskii]

> From: Jambunathan K <kjambunathan@gmail.com>
> Date: Mon, 02 Sep 2013 19:44:44 +0530
> 
> Why does Emacs Info manual has no images?  

Because no one bothered to produce them.

> Is it because the Info browser doesn't support it.

Of course, it does!  Try reading the GnuTLS Info manual, for example.

Re: C-h r and Images

[Paul Eggert]

Eli Zaretskii wrote:
>> > Is it because the Info browser doesn't support it.
> Of course, it does!  Try reading the GnuTLS Info manual, for example.

I just now tried that, and it didn't work for me.
I visited (gnutls)TLS layers, and it said "[broken image]"
instead of showing an image for Figure 3.1.  This is on
Fedora 19 x86-64.

Perhaps this is a problem with that distribution,
or perhaps with Emacs on GNUish platforms, but either
way I'm pretty sure that images won't work with the
standalone info viewer.

Furthermore, images won't work well for users who have
trouble seeing -- not only the 100% blind, but those who
have age-related macular degeneration and similar problems.
These people often use screen readers such as Orca, and so
can grok text fairly well, but the images' contents will
be difficult for them to see, or may be invisible to them.

For all these reasons, images in technical manuals should
generally not be the sole source of information that
they contain.  It's definitely OK to have images, but
there should be an alternative way of getting the gist
of any technical information that an image conveys.
Unfortunately, that doesn't appear to be
true for the GnuTLS manual, at least not if my cursory
examination of Figure 3.1 is correct.

Re: C-h r and Images

[Eli Zaretskii]

> Date: Mon, 02 Sep 2013 08:28:51 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: Jambunathan K <kjambunathan@gmail.com>, emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> >> > Is it because the Info browser doesn't support it.
> > Of course, it does!  Try reading the GnuTLS Info manual, for example.
> 
> I just now tried that, and it didn't work for me.
> I visited (gnutls)TLS layers, and it said "[broken image]"
> instead of showing an image for Figure 3.1.  This is on
> Fedora 19 x86-64.
> 
> Perhaps this is a problem with that distribution,
> or perhaps with Emacs on GNUish platforms, but either
> way I'm pretty sure that images won't work with the
> standalone info viewer.

I didn't mean the standalone Info reader, I meant the Emacs Info
reader.  Using Emacs, I see the images in GnuTLS on MS-Windows, so I'm
pretty sure a GNUish platform should be able to show them.

The standalone reader should show the ASCII-art variant of the image.

Re: C-h r and Images

[Eli Zaretskii]

> Date: Mon, 02 Sep 2013 18:38:24 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: kjambunathan@gmail.com, emacs-devel@gnu.org
> 
> Using Emacs, I see the images in GnuTLS on MS-Windows, so I'm pretty
> sure a GNUish platform should be able to show them.

Perhaps you don't have PNG support in that Emacs where you tried.  The
images that come with the GnuTLS manual are PNG files.

Re: C-h r and Images

[Paul Eggert]

Eli Zaretskii wrote:
> Perhaps you don't have PNG support in that Emacs where you tried.

No, I tracked down the problem: the Fedora 19
GnuTLS documenation package omits /usr/share/info/gnutls-layers.png,
i.e., it's a packaging error for that distro.

I suppose this is another reason our documentation should
have alternative text for each image that conveys technical
information.  ASCII art is one approach, but for the blind
it's better to have a textual summary than to have ASCII art.

(Ubuntu 13.04 (derived from Debian) does package the image, but
it doesn't package the info files, just HTML.)

While we're on the topic of images, we should prefer
SVG to PNG for diagrams, as SVG scales better.

Re: C-h r and Images

[Eli Zaretskii]

> Date: Mon, 02 Sep 2013 14:34:12 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: kjambunathan@gmail.com, emacs-devel@gnu.org
> 
> While we're on the topic of images, we should prefer
> SVG to PNG for diagrams, as SVG scales better.

If SVG is compiled in, yes.  Unfortunately, librsvg is extremely
unstable on Windows.

Re: C-h r and Images

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > If SVG is compiled in, yes.  Unfortunately, librsvg is extremely
 > unstable on Windows.

I imagine Paul is talking about the source form.  If you want to
support a platform deficient in this respect, bundle a rendered form,
as if it were .info or .elc.

Re: C-h r and Images

[Stephen Berman]

On Mon, 02 Sep 2013 14:34:12 -0700 Paul Eggert <eggert@cs.ucla.edu> wrote:

> Eli Zaretskii wrote:
>> Perhaps you don't have PNG support in that Emacs where you tried.
>
> No, I tracked down the problem: the Fedora 19
> GnuTLS documenation package omits /usr/share/info/gnutls-layers.png,
> i.e., it's a packaging error for that distro.

The images are also not displayed in my Emacs, but for a different
reason.  My distribution (openSUSE 12.2) includes the PNG images, but
compresses them (along with all the *.info files):

/usr/share/info/gnutls-layers.png.gz

Is it an Emacs bug (or missing feature) that it doesn't uncompress the
images for display, or is it an openSUSE bug that the images are
compressed?

Steve Berman

Re: C-h r and Images

[Stefan Monnier]

> /usr/share/info/gnutls-layers.png.gz

Applying two compression algorithms on top of each other is rarely
a good idea.  So think this is a bug in OpenSUSE.


        Stefan

Re: C-h r and Images

[Stephen Berman]

On Mon, 09 Sep 2013 10:07:03 -0400 Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> /usr/share/info/gnutls-layers.png.gz
>
> Applying two compression algorithms on top of each other is rarely
> a good idea.  So think this is a bug in OpenSUSE.

I agree, especially since I can't even view such files with image
viewers or web browsers that come with openSUSE; so I filed a bug report
there.

Steve Berman

Re: C-h r and Images

[Andreas Schwab]

Stephen Berman <stephen.berman@gmx.net> writes:

> The images are also not displayed in my Emacs, but for a different
> reason.  My distribution (openSUSE 12.2) includes the PNG images, but
> compresses them (along with all the *.info files):
>
> /usr/share/info/gnutls-layers.png.gz
>
> Is it an Emacs bug (or missing feature) that it doesn't uncompress the
> images for display, or is it an openSUSE bug that the images are
> compressed?

In 13.1 the images will be included uncompressed.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

Re: C-h r and Images

[Stephen Berman]

On Mon, 09 Sep 2013 17:01:50 +0200 Andreas Schwab <schwab@suse.de> wrote:

> Stephen Berman <stephen.berman@gmx.net> writes:
>
>> The images are also not displayed in my Emacs, but for a different
>> reason.  My distribution (openSUSE 12.2) includes the PNG images, but
>> compresses them (along with all the *.info files):
>>
>> /usr/share/info/gnutls-layers.png.gz
>>
>> Is it an Emacs bug (or missing feature) that it doesn't uncompress the
>> images for display, or is it an openSUSE bug that the images are
>> compressed?
>
> In 13.1 the images will be included uncompressed.

Oops, got your response just after I filed a report (for 12.2) with
bugzilla.

Steve Berman

Re: C-h r and Images

[Per Starbäck]

[-- Attachment #1: Type: text/plain, Size: 288 bytes --]

> The images are also not displayed in my Emacs, but for a different
> reason.  My distribution (openSUSE 12.2) includes the PNG images, but
> compresses them (along with all the *.info files):
>
> /usr/share/info/gnutls-layers.png.gz

Redhat does the same in their gnutls-devel package!

[-- Attachment #2: Type: text/html, Size: 411 bytes --]

Re: C-h r and Images

[Eli Zaretskii]

> Date: Mon, 02 Sep 2013 18:38:24 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: kjambunathan@gmail.com, emacs-devel@gnu.org
> 
> The standalone reader should show the ASCII-art variant of the image.

But I see that the authors of the GnuTLS manual didn't provide the
ASCII variant of the images, so you won't see them in the standalone
Info.

RE: C-h r and Images

[Drew Adams]

> >> > Is it because the Info browser doesn't support it.
> > Of course, it does!  Try reading the GnuTLS Info manual, for example.
> 
> I just now tried that, and it didn't work for me.
> I visited (gnutls)TLS layers, and it said "[broken image]"
> instead of showing an image for Figure 3.1.  This is on
> Fedora 19 x86-64.

Hope the following is relevant; dunno.  I also have no idea whether
I have GnuTLS dlls installed or whether that is relevant wrt the
GnuTLS Info manual.  I do have image support for Emacs; i.e., I can
generally see images in Emacs.

With the following MS Windows build I see no images in the GnuTLS
manual, and it does not even have a `TLS layers', node AFAICT.
Searching for "layer" finds hits only in node `Overview'.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-23 on ODIEONE
Bzr revision: 113986 rgm@gnu.org-20130823185841-zoy6h1qk433ibrlf
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

Re: C-h r and Images

[Eli Zaretskii]

> Date: Mon, 2 Sep 2013 08:44:41 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Jambunathan K <kjambunathan@gmail.com>, emacs-devel@gnu.org
> 
> Hope the following is relevant; dunno.  I also have no idea whether
> I have GnuTLS dlls installed or whether that is relevant wrt the
> GnuTLS Info manual.

It isn't.

> With the following MS Windows build I see no images in the GnuTLS
> manual, and it does not even have a `TLS layers', node AFAICT.

Maybe you have a very old manual.  Mine says this at the very
beginning (in node "Top"):

  This manual is last updated 25 November 2011 for version 3.0.9 of
  GnuTLS.

It does have the "TLS layers" node, and that node does show an image.

Re: C-h r and Images

[Jambunathan K]

Sorry for multiple posts.  

I am banging my head over multiple accounts, posting styles and
X-Message-SMTP-Method etc.  Gnus is awesome only because I can edit my
mail within Emacs.  Otherwise it's just ...

Paul Eggert <eggert@cs.ucla.edu> writes:

> Eli Zaretskii wrote:
>>> > Is it because the Info browser doesn't support it.
>> Of course, it does!  Try reading the GnuTLS Info manual, for example.
>
> I just now tried that, and it didn't work for me.
> I visited (gnutls)TLS layers, and it said "[broken image]"
> instead of showing an image for Figure 3.1.  This is on
> Fedora 19 x86-64.

Works fine on Debian/Squeeze x86 and Emacs Bzr trunk.  

The package I installed is gnutls-doc.  I can see the image just fine,
if I do

    (info "(gnutls) TLS layers")

The header says this:

,----
| GNU TLS
| *******
| 
| This manual is last updated 2 June 2009 for version 2.8.6 of GNU TLS.
| 
| Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
| Software Foundation, Inc.
`----

> Furthermore, images won't work well for users 

My motivation for the post was the thread in help list and a recurrent
confusion between a frame and a window.

It is easier to show 
 - a window
  - a frame
  - a minibuffer
  - a header line
  - a mode line 

with a single shot rather than explain it in Glossary.

Btw, looking at Glossary for Window, I am surprised that I don't know
what (q.v.) stands for.  The Emacs crowd *was* scholarly and academic
and it is to some extent even so today.  But using things like q.v. etc
and assuming that it will be understood by *lay* crowd is a bit too much
for the asking...

,----
| Window
|      Emacs divides a frame (q.v.) into one or more windows, each of
|      which can display the contents of one buffer (q.v.) at any time.
|      *Note Screen::, for basic information on how Emacs uses the screen.
|      *Note Windows::, for commands to control the use of windows.  Some
|      other editors use the term "window" for what we call a `frame'
|      (q.v.) in Emacs.
`----

Re: C-h r and Images

[Eli Zaretskii]

> From: Jambunathan K <kjambunathan@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Mon, 02 Sep 2013 23:01:36 +0530
> 
> Btw, looking at Glossary for Window, I am surprised that I don't know
> what (q.v.) stands for.

Quo vide, a.k.a. "which see".

Re: C-h r and Images

[Jambunathan K]

Thanks.   I wasn't confident of how q.v (q.g) [1] will work out.

> Quo  vide, a.k.a. "which see".
     ^
     d

http://en.wiktionary.org/wiki/quod_vide



[1] http://en.wiktionary.org/wiki/quod_google

Am I surprised that q.v leads me to q.g which leads me back again to
lisp and Emacs world?

RE: C-h r and Images

[Drew Adams]

> My motivation for the post was the thread in help list and a recurrent
> confusion between a frame and a window.
> 
> It is easier to show
>   - a window
>   - a frame
>   - a minibuffer
>   - a header line
>   - a mode line
> 
> with a single shot rather than explain it in Glossary.

Great idea.  (Not either/or, of course.)

> Btw, looking at Glossary for Window, I am surprised that I don't know
> what (q.v.) stands for.  The Emacs crowd *was* scholarly and academic
> and it is to some extent even so today.  But using things like q.v. etc
> and assuming that it will be understood by *lay* crowd is a bit too much
> for the asking...

Yes, it's silly, if not downright pretentious in this context.

What's more, it would be helpful to hyperlink directly to an explanation
of the term in question, rather than just saying "which see" or some such
English alternative to "q.v."

Re: C-h r and Images

[Juri Linkov]

>> My motivation for the post was the thread in help list and a recurrent
>> confusion between a frame and a window.
>>
>> It is easier to show
>>   - a window
>>   - a frame
>>   - a minibuffer
>>   - a header line
>>   - a mode line
>>
>> with a single shot rather than explain it in Glossary.
>
> Great idea.  (Not either/or, of course.)

Something like http://www.emacswiki.org/emacs/DrewsEmacsWindowCallouts
but in a plain vanilla `emacs -Q' rather than Drewmacs :-)

>> Btw, looking at Glossary for Window, I am surprised that I don't know
>> what (q.v.) stands for.  The Emacs crowd *was* scholarly and academic
>> and it is to some extent even so today.  But using things like q.v. etc
>> and assuming that it will be understood by *lay* crowd is a bit too much
>> for the asking...
>
> Yes, it's silly, if not downright pretentious in this context.

Which is also easy to confuse with "quo vadis" :-)

> What's more, it would be helpful to hyperlink directly to an explanation
> of the term in question, rather than just saying "which see" or some such
> English alternative to "q.v."

Linking directly to an explanation is possible with Info "anchors".

RE: C-h r and Images

[Drew Adams]

> >> My motivation for the post was the thread in help list and a recurrent
> >> confusion between a frame and a window.
> >>
> >> It is easier to show
> >>   - a window
> >>   - a frame
> >>   - a minibuffer
> >>   - a header line
> >>   - a mode line
> >>
> >> with a single shot rather than explain it in Glossary.
> >
> > Great idea.  (Not either/or, of course.)
> 
> Something like http://www.emacswiki.org/emacs/DrewsEmacsWindowCallouts
> but in a plain vanilla `emacs -Q' rather than Drewmacs :-)

;-)  I had forgotten about that image (from Emacs 20).

> > What's more, it would be helpful to hyperlink directly to an explanation
> > of the term in question, rather than just saying "which see" or some such
> > English alternative to "q.v."
> 
> Linking directly to an explanation is possible with Info "anchors".

Is that done in TexInfo?  Should Emacs doc be doing that already?

If it were done, and then changes were made that break that xref, would
that problem be caught/detected, similarly to an ordinary broken xref?
E.g. is there a check or report about missing anchors that are xref'd?

How would that be done on parts of an image (which is just pixels)?
Can we do (the equivalent of) image maps, letting users, in effect,
click a callout (e.g., for "Mode Line"), to go to an appropriate part
of the manual for more info about it (e.g., `(emacs) Mode Line'), or to
provide a tooltip with a little related info?

Re: C-h r and Images

[Kanthimathi R]

Juri Linkov <juri@jurta.org> writes:

> Something like http://www.emacswiki.org/emacs/DrewsEmacsWindowCallouts

It is missing a second frame and it doesn't show the minibuffer.

Re: C-h r and Images

[Xue Fuqiao]

On Tue, Sep 3, 2013 at 2:10 AM, Drew Adams <drew.adams@oracle.com> wrote:
>> Btw, looking at Glossary for Window, I am surprised that I don't know
>> what (q.v.) stands for.  The Emacs crowd *was* scholarly and academic
>> and it is to some extent even so today.  But using things like q.v. etc
>> and assuming that it will be understood by *lay* crowd is a bit too much
>> for the asking...
>
> Yes, it's silly, if not downright pretentious in this context.
>
> What's more, it would be helpful to hyperlink directly to an explanation
> of the term in question, rather than just saying "which see" or some such
> English alternative to "q.v."

I made a patch for it.  See bug#15254.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

RE: C-h r and Images

[Drew Adams]

> > it would be helpful to hyperlink directly to an explanation
> > of the term in question, rather than just saying "which see"
> 
> I made a patch for it.  See bug#15254.

Looks good - thanks.

(The original context here was wrt hyperlinking such terms when used
as callouts in images, as in image maps.  But this patch represents an
improvement on its own.)

Re: C-h r and Images

[Eli Zaretskii]

> Date: Tue, 3 Sep 2013 16:56:14 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Paul Eggert <eggert@cs.ucla.edu>,
> 	Jambunathan K <kjambunathan@gmail.com>, emacs-devel <emacs-devel@gnu.org>
> 
> On Tue, Sep 3, 2013 at 2:10 AM, Drew Adams <drew.adams@oracle.com> wrote:
> >> Btw, looking at Glossary for Window, I am surprised that I don't know
> >> what (q.v.) stands for.  The Emacs crowd *was* scholarly and academic
> >> and it is to some extent even so today.  But using things like q.v. etc
> >> and assuming that it will be understood by *lay* crowd is a bit too much
> >> for the asking...
> >
> > Yes, it's silly, if not downright pretentious in this context.
> >
> > What's more, it would be helpful to hyperlink directly to an explanation
> > of the term in question, rather than just saying "which see" or some such
> > English alternative to "q.v."
> 
> I made a patch for it.  See bug#15254.

Thanks.  However, I'm not sure doing this is useful.  The Glossary is
a long series of short paragraphs, each one explaining one term.  What
your patch does is add a cross-reference to many of these short
paragraphs, which makes those paragraphs longer and more complex to
read and grasp at first glance.  OTOH, since the terms are listed in
alphabetic order, it is quite easy to find a given term, even if you
just scroll and don't use the search commands.

So my take of this is that on balance this is not useful.