Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

[Zhu Zihao]

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


Recently I checked my Emacs installation, and find two file named
elisp_type_hierarchy.{jpg|txt} in share/info directory(these two files
are placed in doc/lispref in source tree).

According to usual packaging convention, the share/info directory should
only contains compiled texinfo file (use 'info' as extension). It should
not contains txt or jpg (And I believe GNU info or other info reader
will ignore them).

One of my friend points me to a commit https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=415604c7a77205d91254a271f0112f69729eb3a9
In this commit, I found that emacs will use these two files to produce
info file. But IIRC, these source file should not be copied into the
destination of info file, they'll be contained in the compiled info.

Can someone tell me that it's purposed to do so, or just unintentional?
thanks! 
-- 
Retrieve my PGP public key:

  gpg --recv-keys B3EBC086AB0EBC0F45E0B4D433DB374BCEE4D9DC

Zihao

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 255 bytes --]

Re: Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

[Eli Zaretskii]

> From: Zhu Zihao <all_but_last@163.com>
> Date: Wed, 03 Apr 2024 16:13:12 +0800
> 
> Recently I checked my Emacs installation, and find two file named
> elisp_type_hierarchy.{jpg|txt} in share/info directory(these two files
> are placed in doc/lispref in source tree).

Yes.

> According to usual packaging convention, the share/info directory should
> only contains compiled texinfo file (use 'info' as extension). It should
> not contains txt or jpg (And I believe GNU info or other info reader
> will ignore them).

This is incorrect.  Info manuals can include images, for those Info
readers which (like Emacs) are capable of displaying images.  See the
node "Images" in the Texinfo manual.  The stand-alone Info reader,
maintained as part of the Texinfo project, cannot display images, so
it will display the text replacement instead.

If a manual includes images, they are distributed as image files,
which should be installed in the same directory tree as the Info files
themselves.  The simplest arrangement is to have them in the same
directory as the Info files.  (The Texinfo manual suggests to put them
in a subdirectory named 'PACKAGE-figures', but I have yet to see a GNU
package that uses such a convention -- they all put images in the same
place as the Info files, probably because that allows to avoid
hard-coding the subdirectory in the Texinfo sources.)  And that is
what Emacs does, starting from Emacs 30, which is the first release to
have images in its manuals.

> One of my friend points me to a commit https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=415604c7a77205d91254a271f0112f69729eb3a9
> In this commit, I found that emacs will use these two files to produce
> info file. But IIRC, these source file should not be copied into the
> destination of info file, they'll be contained in the compiled info.

That is also incorrect.  The images should be separate files, since
the Info format cannot include the image itself, only a reference to
it by its file name.

> Can someone tell me that it's purposed to do so, or just unintentional?
> thanks! 

It's definitely intentional, and also correct, see above.

Re: Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

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

  > This is incorrect.  Info manuals can include images, for those Info
  > readers which (like Emacs) are capable of displaying images.  See the
  > node "Images" in the Texinfo manual.

Do we publish any text about this issue
that we should update?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: all_but_last@163.com, emacs-devel@gnu.org
> Date: Fri, 05 Apr 2024 17:41:19 -0400
> 
>   > This is incorrect.  Info manuals can include images, for those Info
>   > readers which (like Emacs) are capable of displaying images.  See the
>   > node "Images" in the Texinfo manual.
> 
> Do we publish any text about this issue
> that we should update?

If you mean in files like INSTALL in our distribution, or in some
other GNU manuals, then no, I don't think we should update anything.
If you mean something else, please elaborate.

Re: Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

[Stephen Berman]

On Sat, 06 Apr 2024 09:45:19 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Richard Stallman <rms@gnu.org>
>> Cc: all_but_last@163.com, emacs-devel@gnu.org
>> Date: Fri, 05 Apr 2024 17:41:19 -0400
>>
>>   > This is incorrect.  Info manuals can include images, for those Info
>>   > readers which (like Emacs) are capable of displaying images.  See the
>>   > node "Images" in the Texinfo manual.
>>
>> Do we publish any text about this issue
>> that we should update?
>
> If you mean in files like INSTALL in our distribution, or in some
> other GNU manuals, then no, I don't think we should update anything.

Should INSTALL say anything about native compilation, e.g. that it
requires libgccjit, which Emacs uses by default if present, otherwise
configure with --with-native-compilation=no to build without it?  If so,
then should section 6 under DETAILED BUILDING AND INSTALLATION also
refer to the sibling directory ../native-lisp?

Beyond these possible updates, it might be helpful to augment section 6
to point out the following differences between in-tree and out-of-tree
builds (since section 3b refers to building "in a separate directory"):
When executing src/emacs in-place in an out-of-tree build, it uses the
top-level lisp and info directories of the source directory, not of the
build directory, but it uses the lib-src and native-lisp directories of
the build directory.

Steve Berman

Re: Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: rms@gnu.org,  all_but_last@163.com,  emacs-devel@gnu.org
> Date: Sat, 06 Apr 2024 13:39:20 +0200
> 
> On Sat, 06 Apr 2024 09:45:19 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >> From: Richard Stallman <rms@gnu.org>
> >> Cc: all_but_last@163.com, emacs-devel@gnu.org
> >> Date: Fri, 05 Apr 2024 17:41:19 -0400
> >>
> >>   > This is incorrect.  Info manuals can include images, for those Info
> >>   > readers which (like Emacs) are capable of displaying images.  See the
> >>   > node "Images" in the Texinfo manual.
> >>
> >> Do we publish any text about this issue
> >> that we should update?
> >
> > If you mean in files like INSTALL in our distribution, or in some
> > other GNU manuals, then no, I don't think we should update anything.
> 
> Should INSTALL say anything about native compilation, e.g. that it
> requires libgccjit, which Emacs uses by default if present, otherwise
> configure with --with-native-compilation=no to build without it?  If so,
> then should section 6 under DETAILED BUILDING AND INSTALLATION also
> refer to the sibling directory ../native-lisp?
> 
> Beyond these possible updates, it might be helpful to augment section 6
> to point out the following differences between in-tree and out-of-tree
> builds (since section 3b refers to building "in a separate directory"):
> When executing src/emacs in-place in an out-of-tree build, it uses the
> top-level lisp and info directories of the source directory, not of the
> build directory, but it uses the lib-src and native-lisp directories of
> the build directory.

Is this relevant to the issue discussed in this thread?

If you want to suggest additions and changes to INSTALL, feel free,
but please start a new thread about that.  This one is about a very
specific aspect of the Emacs installation: image files used by our
manuals.

Re: Undocumented elisp_type_hierarchy.{jpg|txt} in info directory.

[Stephen Berman]

On Sat, 06 Apr 2024 16:39:56 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Stephen Berman <stephen.berman@gmx.net>
>> Cc: rms@gnu.org,  all_but_last@163.com,  emacs-devel@gnu.org
>> Date: Sat, 06 Apr 2024 13:39:20 +0200
>>
>> On Sat, 06 Apr 2024 09:45:19 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
>>
>> >> From: Richard Stallman <rms@gnu.org>
>> >> Cc: all_but_last@163.com, emacs-devel@gnu.org
>> >> Date: Fri, 05 Apr 2024 17:41:19 -0400
>> >>
>> >>   > This is incorrect.  Info manuals can include images, for those Info
>> >>   > readers which (like Emacs) are capable of displaying images.  See the
>> >>   > node "Images" in the Texinfo manual.
>> >>
>> >> Do we publish any text about this issue
>> >> that we should update?
>> >
>> > If you mean in files like INSTALL in our distribution, or in some
>> > other GNU manuals, then no, I don't think we should update anything.
>>
>> Should INSTALL say anything about native compilation, e.g. that it
>> requires libgccjit, which Emacs uses by default if present, otherwise
>> configure with --with-native-compilation=no to build without it?  If so,
>> then should section 6 under DETAILED BUILDING AND INSTALLATION also
>> refer to the sibling directory ../native-lisp?
>>
>> Beyond these possible updates, it might be helpful to augment section 6
>> to point out the following differences between in-tree and out-of-tree
>> builds (since section 3b refers to building "in a separate directory"):
>> When executing src/emacs in-place in an out-of-tree build, it uses the
>> top-level lisp and info directories of the source directory, not of the
>> build directory, but it uses the lib-src and native-lisp directories of
>> the build directory.
>
> Is this relevant to the issue discussed in this thread?
>
> If you want to suggest additions and changes to INSTALL, feel free,
> but please start a new thread about that.  This one is about a very
> specific aspect of the Emacs installation: image files used by our
> manuals.

Oops, my eye just focussed on "I don't think we should update anything"
and disregarded the Subject line; sorry.  I've now proposed a patch in
bug#70246.

Steve Berman