Proposal: Include C Manual from RMS in Emacs git, and/or release

Proposal: Include C Manual from RMS in Emacs git, and/or release

[Jeremy Bryant]

Dear RMS and other maintainers,

The C manual at 
https://savannah.gnu.org/projects/c-intro-and-ref/

1.
could be a useful guide to include within the Emacs tree under doc/
2.
It could possibly be part of the release tarball given the usefulness of
Emacs for C programmers?
3.
Or ELPA?

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Philip Kaludercic]

Jeremy Bryant <jb@jeremybryant.net> writes:

> Dear RMS and other maintainers,
>
> The C manual at 
> https://savannah.gnu.org/projects/c-intro-and-ref/
>
> 1.
> could be a useful guide to include within the Emacs tree under doc/
> 2.
> It could possibly be part of the release tarball given the usefulness of
> Emacs for C programmers?
> 3.
> Or ELPA?

I don't know how useful it is for Emacs, but it should be more-or-less
easy to have it available via ELPA (of course a separate distribution
system for high-quality TeXinfo manuals would be even more preferable,
but I don't know of anything like that).

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Arsen Arsenović]

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

Jeremy Bryant <jb@jeremybryant.net> writes:

> Dear RMS and other maintainers,

I'm neither, but I hope my feedback is appreciated anyway :-)

> The C manual at 
> https://savannah.gnu.org/projects/c-intro-and-ref/
>
> 1.
> could be a useful guide to include within the Emacs tree under doc/

I don't see how.

> 2.
> It could possibly be part of the release tarball given the usefulness of
> Emacs for C programmers?

Generally, bundling stuff makes it hard to distribute independently.
For instance, many distributions do not install info.info with standalne
'info' as it is part of Emacs, which IMO has damaged the reputation of
the Texinfo documentation system, as anyone who does not have emacs
installed, or, worse, emacses non-DFSG documentation package could not
access the tutorial or manual.

> 3.
> Or ELPA?

I don't see the point to that personally, but at least it won't create
the trouble bundling (like info.info) creates.

Have a lovely day.
-- 
Arsen Arsenović

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

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Arsen Arsenović <arsen@aarsen.me>
> Cc: Emacs Devel <emacs-devel@gnu.org>,  Richard Stallman <rms@gnu.org>
> Date: Sat, 30 Nov 2024 14:38:42 +0100
> 
> For instance, many distributions do not install info.info with standalne
> 'info' as it is part of Emacs, which IMO has damaged the reputation of
> the Texinfo documentation system, as anyone who does not have emacs
> installed, or, worse, emacses non-DFSG documentation package could not
> access the tutorial or manual.

The Info tutorial was moved to Emacs because Emacs is de-facto the
only Info reader in wide use.  Texinfo comes with info-stnd.info,
which documents the stand-alone reader, which is part of Texinfo.

So I don't see how that move could damage the reputation of Texinfo.

Do you have any information to suggest that many people use the
stand-alone reader?

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Arsen Arsenović]

Hi Eli,

<#secure method=pgpmime mode=sign>
Eli Zaretskii <eliz@gnu.org> writes:

>> From: Arsen Arsenović <arsen@aarsen.me>
>> Cc: Emacs Devel <emacs-devel@gnu.org>,  Richard Stallman <rms@gnu.org>
>> Date: Sat, 30 Nov 2024 14:38:42 +0100
>> 
>> For instance, many distributions do not install info.info with standalne
>> 'info' as it is part of Emacs, which IMO has damaged the reputation of
>> the Texinfo documentation system, as anyone who does not have emacs
>> installed, or, worse, emacses non-DFSG documentation package could not
>> access the tutorial or manual.
>
> The Info tutorial was moved to Emacs because Emacs is de-facto the
> only Info reader in wide use.

I see no way to back up that statement.  Emacs is certainly not the only
Info reader in wide use.  In fact, I'd wager the standalone info reader
is far more widespread.

Not that it matters - there _is_ another info reader, that's meant to be
compatible, and currently, for the sake of Emacs, its self-documentation
is subpar.

> Texinfo comes with info-stnd.info, which documents the stand-alone
> reader, which is part of Texinfo.

... which also lacks the tutorial section.  In fact, the standalone info
readers manual starts with talking about the Emacs info reader, tells
you to navigate via <SPC> and <DEL> (which is good!  that should be
front and center), and then jumps into "node navigation" without
covering what a node is.  This is fine for a reference manual, but it
gets opened when one asks for a tutorial.

> So I don't see how that move could damage the reputation of Texinfo.

Emacs is extremely niche, while reading the documentation of various GNU
packages is not.  Ergo, we recommend people to read documentation using
info (see e.g. help2man generated output) - as we should.

As a result, on many systems (no complete empirical data for obvious
reasons, but at least on *all* Debian systems without the nonfree
repositories enabled, which is already quite a few systems - in fact,
looking at popcon, 13.64% of Debian systems have 'info' installed, only
6.68% have emacs-common, and 0.33% have emacs-common-non-dfsg, which is,
sadly, where info.info is[1][2]), a user will type 'info ls' or such,
get confused when the node being observed changes while they were
holding arrow-down, remember that the viewer told them to hit 'h' to
read a tutorial, then hit 'h', and silently fail to get a tutorial.

This is especially bad because there's more up-front cognitive load when
trying to use info: it has a hierarchical structure, opposed to the
awful flat page 'man' provides, and it is also a hypertext, so it can be
overwhelming initially.

I recommend Texinfo constantly, because I've observed that Texinfo is a
better documentation system among the existing Unix-ish documentation
systems, and this observation seems to be made by others if I take the
time to walk them through how to use 'info' (or M-x info if they're
using Emacs also).

> Do you have any information to suggest that many people use the
> stand-alone reader?

Do you have information to suggest that many people use the in-Emacs
reader?  I certainly do use it, so we can put that a mark on the
chalkboard.

My information comes from years of recommending people to try Texinfo
(and indeed recommending both readers as I do), but that's anecdotal.

Debians popcon seems to agree, though.

Obviously, popcon does not measure /use/, but it does measure un-use, as
someone who does not install a package cannot use it (except for manual
installation.. I doubt that's statistically significant).

The standalone info reader is also what GNU manpages recommend (to
preempt anyone questioning whether those matter because they are
best-effort: yes, they do, because a lot of people are accustomed to
checking 'man $cmd' and are told or trained to do that).

In conclusion, I'd wager a quality standalone reader is more important
than a quality info.el in a head-to-head comparison.  Asking
distributors to move info.info into a standalone package would be a step
in the right direction.

Have a lovely day.

[1] https://qa.debian.org/popcon.php?package=emacs
[2] https://qa.debian.org/popcon.php?package=emacs-non-dfsg
-- 
Arsen Arsenović

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Arsen Arsenović <arsen@aarsen.me>
> Cc: jb@jeremybryant.net,  emacs-devel@gnu.org,  rms@gnu.org
> Date: Sat, 30 Nov 2024 19:08:40 +0100
> 
> > So I don't see how that move could damage the reputation of Texinfo.
> 
> Emacs is extremely niche, while reading the documentation of various GNU
> packages is not.  Ergo, we recommend people to read documentation using
> info (see e.g. help2man generated output) - as we should.

Actually, I believe most people read the HTML version of the Texinfo
documentation.

> > Do you have any information to suggest that many people use the
> > stand-alone reader?
> 
> Do you have information to suggest that many people use the in-Emacs
> reader?  I certainly do use it, so we can put that a mark on the
> chalkboard.

I think Emacs users use Emacs (of course), and the rest read the
manuals in their HTML format.  I have yet to see a number of people
who use the stand-alone reader that cannot be counted on the fingers
of a single hand.  (And don't misunderstand me: I think the
stand-alone Info reader is great, and personally invested quite a few
efforts in developing and porting it.  My Windows port of Texinfo,
routinely available from the ezwinports site, is one of a couple,
perhaps even the only one, which includes a fully functional Windows
port of the stand-alone Info reader.)

Anyway, the initiative for moving info.info to Emacs was from the
Texinfo developers (I'm sure you can find the relevant discussions in
the archives).  So if you think it should be moved back, feel free to
take it up with them.

RE: [External] : Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Drew Adams]

> Actually, I believe most people read the HTML
> version of the Texinfo documentation.

Interesting.  Do you have some quantitative data
about the percentage of readings of HTML vs Info
by (non-Emacs) users?

I don't think otherwise - just wondering what
backs up your belief about this.

Re: [External] : Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "jb@jeremybryant.net" <jb@jeremybryant.net>,
>         "emacs-devel@gnu.org"
> 	<emacs-devel@gnu.org>,
>         "rms@gnu.org" <rms@gnu.org>
> Date: Sat, 30 Nov 2024 21:09:49 +0000
> 
> > Actually, I believe most people read the HTML
> > version of the Texinfo documentation.
> 
> Interesting.  Do you have some quantitative data
> about the percentage of readings of HTML vs Info
> by (non-Emacs) users?
> 
> I don't think otherwise - just wondering what
> backs up your belief about this.

My evidence is that when people report problems with GNU manuals, they
almost always show a URL of the HTML documentation.

Also, the number of bug reports about the stand-alone Info reader is
almost zero.

I don't have any other data, but I cannot think about any other way
people who don't use Emacs can read the documentation of GCC, GDB, GNU
Make, and other GNU tools.

Texinfo reputation (was: Re: [External] : Re: Proposal: Include C Manual from RMS in Emacs git, and/or release)

[Max Nikulin]

On 01/12/2024 13:15, Eli Zaretskii wrote:
> My evidence is that when people report problems with GNU manuals, they
> almost always show a URL of the HTML documentation.

I would include an http(s): link into an issue report to avoid ugly 
multistep style of addressing info nodes as in

> emacs --help
[...]
> Run M-x info RET m emacs RET m emacs invocation RET inside Emacs to
> read the main documentation for these command-line arguments.

and to allow people reading the message from a mobile device to easily 
inspect the actual text. That is why I consider URLs in reports as a 
weak evidence. Side note: likely I would duplicate the reference as 
(info "(emacs) Emacs Invocation").

My impression based on debian-user mailing list messages is that people 
avoid info manuals due to inconvenience of the standalone reader. They 
have some workarounds for cases when length of a man page is excessively 
high for comfortable reading. An example is PDF generated from BASH man 
page despite BASH has the manual in the texinfo format.

Those who read .info documents may recommend e.g. pinfo. From my point 
of view, tkinfo is usually better than "info".

Another issue is that there is no standard way to share a link to a 
specific node of a texinfo document. khelpcenter and yelp use different 
URL schemes for this purpose. It may not be easy to get link to the 
currently displayed node and that style of links would not be helpful 
for Emacs or standalone info browsers.

Debian 12 bookworm: "emacs -f info-standalone" option is not included into

update-alternatives --list infobrowser
/usr/bin/info
/usr/bin/tkinfo

Feel free to forward this message to a texinfo mailing list. Another 
reason why I have decided to post it here is the following message:

On 30/11/2024 21:12, Eli Zaretskii wrote:
> Texinfo comes with info-stnd.info,
> which documents the stand-alone reader, which is part of Texinfo.
> 
> So I don't see how that move could damage the reputation of Texinfo.
> 
> Do you have any information to suggest that many people use the
> stand-alone reader?

Re: Texinfo reputation (was: Re: [External] : Re: Proposal: Include C Manual from RMS in Emacs git, and/or release)

[Eli Zaretskii]

> From: Max Nikulin <manikulin@gmail.com>
> Date: Mon, 2 Dec 2024 10:00:56 +0700
> 
> Those who read .info documents may recommend e.g. pinfo. From my point 
> of view, tkinfo is usually better than "info".

Are they being developed?  ISTR that someone said they were no longer
updated.

Re: Texinfo reputation

[Max Nikulin]

On 02/12/2024 19:47, Eli Zaretskii wrote:
>> From: Max Nikulin Mon, 2 Dec 2024 10:00:56 +0700
>>
>> Those who read .info documents may recommend e.g. pinfo. From my point
>> of view, tkinfo is usually better than "info".
> 
> Are they being developed?  ISTR that someone said they were no longer
> updated.

I have not tried to report bugs for tkinfo (it hangs sometimes on search 
attempts, but I am unaware of really serious issues). It has some 
advantages and disadvantages in comparison to other means of reading 
texinfo documents. It is not perfect, but in some sense it is feature 
complete. I am grateful to its developers and maintainers. It is 
available in Debian:
<https://tracker.debian.org/pkg/tkinfo>

I was not inspired by pinfo description, so I have not tried it. It has 
some issue with maintenance and it has been kicked out of Debian 
testing. It is still available in current stable (bookworm):
<https://tracker.debian.org/pkg/pinfo>

In my opinion, it means that texinfo docs in general and .info format in 
particular are becoming less useful outside of Emacs. Formatting of PDF 
is too rigid. HTML files are either excessively huge or uncomfortably 
granular with enough nodes containing just a handful lines of text. 
Moreover, there is a fraction of users who prefers locally installed 
documents.

A container format like EPUB might be an option for distributing 
formatted documents, but the issue is decent free viewers for various 
platforms. It seems they must be based on almost full fledged web 
browser engines.

Re: Texinfo reputation

[Eli Zaretskii]

> From: Max Nikulin <manikulin@gmail.com>
> Date: Tue, 3 Dec 2024 09:51:49 +0700
> 
> On 02/12/2024 19:47, Eli Zaretskii wrote:
> >> From: Max Nikulin Mon, 2 Dec 2024 10:00:56 +0700
> >>
> >> Those who read .info documents may recommend e.g. pinfo. From my point
> >> of view, tkinfo is usually better than "info".
> > 
> > Are they being developed?  ISTR that someone said they were no longer
> > updated.
> 
> I have not tried to report bugs for tkinfo (it hangs sometimes on search 
> attempts, but I am unaware of really serious issues). It has some 
> advantages and disadvantages in comparison to other means of reading 
> texinfo documents. It is not perfect, but in some sense it is feature 
> complete. I am grateful to its developers and maintainers. It is 
> available in Debian:
> <https://tracker.debian.org/pkg/tkinfo>
> 
> I was not inspired by pinfo description, so I have not tried it. It has 
> some issue with maintenance and it has been kicked out of Debian 
> testing. It is still available in current stable (bookworm):
> <https://tracker.debian.org/pkg/pinfo>
> 
> In my opinion, it means that texinfo docs in general and .info format in 
> particular are becoming less useful outside of Emacs.

That was the conclusion in that discussion some years ago where it was
decided to move info.info to Emacs.

> Formatting of PDF 
> is too rigid. HTML files are either excessively huge or uncomfortably 
> granular with enough nodes containing just a handful lines of text. 
> Moreover, there is a fraction of users who prefers locally installed 
> documents.

IME, many users report issues with documentation using HTML and PDF
references.  HTML can also be installed locally.

Re: Texinfo reputation

[Dr. Arne Babenhauserheide]

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

Max Nikulin <manikulin@gmail.com> writes:
> My impression based on debian-user mailing list messages is that
> people avoid info manuals due to inconvenience of the standalone
> reader. They have some workarounds for cases when length of a man page
> is excessively high for comfortable reading. An example is PDF
> generated from BASH man page despite BASH has the manual in the
> texinfo format.

I used to be annoyed by the standalone reader, but with

info --usage <package>

it’s actually pretty good. It nowadays also gives a useful answer when
looking for a non-existing manual:

    info NOTEXISTING
    info: No menu item 'NOTEXISTING' in node '(dir)Top'

That was my main gripe with it, and I guess that most old timers don’t
know about that change.

You even get very fast full-text search through the manuals.

What I just found a bit lacking is tool support: pygments does not have
highlighting for texinfo (latex export of texinfo sources), export to
HTML doesn’t look great by default.

And: info --usage git does not give the invocation page — because that
node is missing in the manual. That’s not a problem of texinfo, but an
indication that something may be missing:

Is there a linter for texinfo that remarks such problems?

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Texinfo reputation

[Max Nikulin]

On 04/12/2024 01:51, Dr. Arne Babenhauserheide wrote:
> Max Nikulin writes:
> I used to be annoyed by the standalone reader, but with
> 
> info --usage <package>
> 
> it’s actually pretty good.

Certainly it is more convenient, but a more universal link is still

     or available locally via: info '(coreutils) ls invocation'

> It nowadays also gives a useful answer when
> looking for a non-existing manual:
> 
>      info NOTEXISTING
>      info: No menu item 'NOTEXISTING' in node '(dir)Top'

I prefer this behavior as well. It reminds me another recent thread 
however. "info git" renders the man page in my case. In the absence of 
apparent banner, it requires some cognitive efforts to recognize that 
the rendered document is not an info page. Citations in the following 
message gives a fair summary of that discussion
<https://lists.debian.org/msgid-search/Z0dZjysfE3HE2nJZ@tuxteam.de>
debian-user. Re: help, man, etc. (was Re: Using terminal commands - 
corner cases) Wed, 27 Nov 2024 18:40:31 +0100

> You even get very fast full-text search through the manuals.

I do not mind, but the real annoyance for new users is that key bindings 
do not match e.g. "less" ones for next match. Mouse support in tkinfo 
makes its usage significantly more intuitive.

> And: info --usage git does not give the invocation page — because that
> node is missing in the manual. That’s not a problem of texinfo, but an
> indication that something may be missing:
> 
> Is there a linter for texinfo that remarks such problems?

Perhaps it is possible to write TeX code that spits a warning/error at 
the end of the document when the "invocation" node is missed.

Re: Texinfo reputation

[Dr. Arne Babenhauserheide]

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

Max Nikulin <manikulin@gmail.com> writes:

> On 04/12/2024 01:51, Dr. Arne Babenhauserheide wrote:
>> info --usage <package>
>
> Certainly it is more convenient, but a more universal link is still
>
>     or available locally via: info '(coreutils) ls invocation'

That is pretty hard to memorize, so while it’s universal, it is
inconvenient (so many people won’t know it when they need it).

>> It nowadays also gives a useful answer when
>> looking for a non-existing manual:
>>      info NOTEXISTING
>>      info: No menu item 'NOTEXISTING' in node '(dir)Top'
>
> I prefer this behavior as well. It reminds me another recent thread
> however. "info git" renders the man page in my case.

That’s strange: it renders the Git User Manual for me (an infopage).

> Citations in the following
> message gives a fair summary of that discussion
> <https://lists.debian.org/msgid-search/Z0dZjysfE3HE2nJZ@tuxteam.de>

That boils down to "it’s nice but doesn’t always work". Which is a fair
criticism and something that would be great to address technically
(because it can be addressed that way).

>> You even get very fast full-text search through the manuals.
>
> I do not mind, but the real annoyance for new users is that key
> bindings do not match e.g. "less" ones for next match. Mouse support
> in tkinfo makes its usage significantly more intuitive.

Maybe it would be useful to borrow an idea from nano and show the most
important keybindings in the modeline — or initially in the echo area?

What comes to mind:

CTRL-s (search/next result)
N (next)
L (back)
U (up)
SPACE (scroll down)
< (start of manual)
D (directory of all manuals)

I think those are all I use.
(do you know more?)

Maybe alternatively a short list of common keybindings in the info help
manual (that’s pretty long right now, and it contains "please don’t
start skimming" on the third page).

>> And: info --usage git does not give the invocation page — because that
>> node is missing in the manual. That’s not a problem of texinfo, but an
>> indication that something may be missing:
>> Is there a linter for texinfo that remarks such problems?
>
> Perhaps it is possible to write TeX code that spits a warning/error at
> the end of the document when the "invocation" node is missed.

That would be such a linter, yes. And I think it would be pretty useful.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Texinfo reputation

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

  > Is there a linter for texinfo that remarks such problems?

We do not have "lint" programs in GNU.
Instead we make compilers issue error or warning messages
when the input has a flaw worth calling the user's attention to.

So if Texinfo input has a problem tha calls for an error or warning message,
it should be reported by makeinfo ot Tex.

Can you suggest a specific situation in which makeinfo or tex
ought to eit a diagnostic message for certain Texinfo input?
How about mailing that to bug-texinfo@gnu.org?

-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Arsen Arsenović]

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

Hi Eli,

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Arsen Arsenović <arsen@aarsen.me>
>> Cc: jb@jeremybryant.net,  emacs-devel@gnu.org,  rms@gnu.org
>> Date: Sat, 30 Nov 2024 19:08:40 +0100
>> 
>> > So I don't see how that move could damage the reputation of Texinfo.
>> 
>> Emacs is extremely niche, while reading the documentation of various GNU
>> packages is not.  Ergo, we recommend people to read documentation using
>> info (see e.g. help2man generated output) - as we should.
>
> Actually, I believe most people read the HTML version of the Texinfo
> documentation.

Yes, fair enough, that is likely overall most popular, but I still don't
doubt 'info' is more widespread than Emacs.

>> > Do you have any information to suggest that many people use the
>> > stand-alone reader?
>> 
>> Do you have information to suggest that many people use the in-Emacs
>> reader?  I certainly do use it, so we can put that a mark on the
>> chalkboard.
>
> I think Emacs users use Emacs (of course), and the rest read the
> manuals in their HTML format.  I have yet to see a number of people
> who use the stand-alone reader that cannot be counted on the fingers
> of a single hand.  (And don't misunderstand me: I think the
> stand-alone Info reader is great, and personally invested quite a few
> efforts in developing and porting it.  My Windows port of Texinfo,
> routinely available from the ezwinports site, is one of a couple,
> perhaps even the only one, which includes a fully functional Windows
> port of the stand-alone Info reader.)

Even those that do use the HTML format might sometimes not be able to
conveniently access it (e.g. on a remote machine, or because distros
don't install HTML versions of texinfo documentation).

Also, the HTML format is harder to browse (no convenient index
searching, for instance) currently.  There was a proposed JS-based
enhancement for this interface,[1](archive: [2]), developing that could
remedy this (as long as it implemented graceful degradation so that it
can be viewed without JS).

FTR I do hope that we manage to get a 'properly integrated', 'dir' node
and all, index-searchable, ... installed HTML version of Texinfo
documentation in GNU packages and GNU distributions.  I think the info
file format has some drawbacks (e.g. it's a catfile-style format, with
hard wrapping, which fails on narrow screens of course).  I wonder
whether Emacs could read (the relevant parts of) that HTML.

If not, then maybe a new more Emacs-friendly format to replace the
current info file format is needed.

> Anyway, the initiative for moving info.info to Emacs was from the
> Texinfo developers (I'm sure you can find the relevant discussions in
> the archives).  So if you think it should be moved back, feel free to
> take it up with them.

Yes, I've exchanged mail with Gavin about this before.  I was using
info.info as an example of problems caused by packaging up unrelated
things together in this thread.

In hindsight, I'd also not mind if info-stnd.texi contained a copy of
the Info tutorial that the Emacs info manual includes, so that the
standalone viewers get-info-help-node works always.  What do you think
of that?

If that was to be the case, info-stnd would not need to rely on
info.info (at least for any reason I can think of), and so, this would
become a non-issue.

Have a lovely day.

[1] https://www.gnu.org/software/texinfo/manual/texinfo-html/index.html
[2] https://web.archive.org/web/20190407054314/https://www.gnu.org/software/texinfo/manual/texinfo-html/index.html
-- 
Arsen Arsenović

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

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Arsen Arsenović <arsen@aarsen.me>
> Cc: jb@jeremybryant.net,  emacs-devel@gnu.org,  rms@gnu.org
> Date: Sun, 01 Dec 2024 10:53:20 +0100
> 
> > Anyway, the initiative for moving info.info to Emacs was from the
> > Texinfo developers (I'm sure you can find the relevant discussions in
> > the archives).  So if you think it should be moved back, feel free to
> > take it up with them.
> 
> Yes, I've exchanged mail with Gavin about this before.  I was using
> info.info as an example of problems caused by packaging up unrelated
> things together in this thread.
> 
> In hindsight, I'd also not mind if info-stnd.texi contained a copy of
> the Info tutorial that the Emacs info manual includes, so that the
> standalone viewers get-info-help-node works always.  What do you think
> of that?

Someone will have to do the job, and the non-traditional structure of
info.info makes that a tad harder.

There's also an additional problem for Emacs users: if info.info is
not in Emacs, then new users of Info have no way of learning to use
Info.  So I guess this will have to be some kind of duplication or
something?

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Arsen Arsenović]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> In hindsight, I'd also not mind if info-stnd.texi contained a copy of
>> the Info tutorial that the Emacs info manual includes, so that the
>> standalone viewers get-info-help-node works always.  What do you think
>> of that?
>
> Someone will have to do the job, and the non-traditional structure of
> info.info makes that a tad harder.
>
> There's also an additional problem for Emacs users: if info.info is
> not in Emacs, then new users of Info have no way of learning to use
> Info.  So I guess this will have to be some kind of duplication or
> something?

Hm, yes, I had taken it for granted that Texinfo is installed if Emacs
is, but that might not be true.  That makes duplicating the tutorial bit 
of info.info into info-stnd more appealing, I think.

My thinking was to break out the (info)Getting Started node and its
subnodes into info-tutorial.texi or such, and @include it into both
manuals.  There would need to be slight adjustment to the text, as not
all of the first paragraph is applicable to info-stnd.

Quickly skimming it, that node list appears to be closed under internal
(in the sense of "within the same manual") referencing, except for a
reference to *note Emacs Info Variables::, but that could be made
conditionally included or a conditionally external reference.

I think it's doable with fairly little cost.
-- 
Arsen Arsenović

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

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Johan Myréen]

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

One data point. From the Arch Linux Wiki (
https://wiki.archlinux.org/title/GNU):

While most GNU software also provides man pages
> <https://wiki.archlinux.org/title/Man_page>, the Info documents tend to
> be more comprehensive. To view an Info document, simply enter:

$ info
*page_name*

Admittedly, Arch Linux is a niche Linux distribution.


On Sat, 30 Nov 2024 at 22:06, Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Arsen Arsenović <arsen@aarsen.me>
> > Cc: jb@jeremybryant.net,  emacs-devel@gnu.org,  rms@gnu.org
> > Date: Sat, 30 Nov 2024 19:08:40 +0100
> >
> > > So I don't see how that move could damage the reputation of Texinfo.
> >
> > Emacs is extremely niche, while reading the documentation of various GNU
> > packages is not.  Ergo, we recommend people to read documentation using
> > info (see e.g. help2man generated output) - as we should.
>
> Actually, I believe most people read the HTML version of the Texinfo
> documentation.
>
> > > Do you have any information to suggest that many people use the
> > > stand-alone reader?
> >
> > Do you have information to suggest that many people use the in-Emacs
> > reader?  I certainly do use it, so we can put that a mark on the
> > chalkboard.
>
> I think Emacs users use Emacs (of course), and the rest read the
> manuals in their HTML format.  I have yet to see a number of people
> who use the stand-alone reader that cannot be counted on the fingers
> of a single hand.  (And don't misunderstand me: I think the
> stand-alone Info reader is great, and personally invested quite a few
> efforts in developing and porting it.  My Windows port of Texinfo,
> routinely available from the ezwinports site, is one of a couple,
> perhaps even the only one, which includes a fully functional Windows
> port of the stand-alone Info reader.)
>
> Anyway, the initiative for moving info.info to Emacs was from the
> Texinfo developers (I'm sure you can find the relevant discussions in
> the archives).  So if you think it should be moved back, feel free to
> take it up with them.
>
>

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

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

We want to support Info format and HTML for reading Info files,
and we want to provide good software for reading both.

We want all GNU/Linux distros to provide both formats and make them
easy and convenient to read.

Please let's focus on advancing these goals, not on arguing which is
of them is better than which.

-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Date: Sat, 30 Nov 2024 12:56:19 +0000
> 
> Dear RMS and other maintainers,
> 
> The C manual at 
> https://savannah.gnu.org/projects/c-intro-and-ref/
> 
> 1.
> could be a useful guide to include within the Emacs tree under doc/
> 2.
> It could possibly be part of the release tarball given the usefulness of
> Emacs for C programmers?
> 3.
> Or ELPA?

FWIW, I don't think this (IMO very useful and installed on my
machines) manual belongs to Emacs.  It should be a separate manual.

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Sean Whitton]

Hello,

On Sat 30 Nov 2024 at 03:50pm +02, Eli Zaretskii wrote:

> FWIW, I don't think this (IMO very useful and installed on my
> machines) manual belongs to Emacs.  It should be a separate manual.

Could we add a pointer to it somewhere in our development notes?  Maybe
CONTRIBUTE?  This is the first I have heard of it.

-- 
Sean Whitton

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: Jeremy Bryant <jb@jeremybryant.net>,  emacs-devel@gnu.org,  rms@gnu.org
> Date: Sun, 01 Dec 2024 12:02:58 +0800
> 
> Hello,
> 
> On Sat 30 Nov 2024 at 03:50pm +02, Eli Zaretskii wrote:
> 
> > FWIW, I don't think this (IMO very useful and installed on my
> > machines) manual belongs to Emacs.  It should be a separate manual.
> 
> Could we add a pointer to it somewhere in our development notes?  Maybe
> CONTRIBUTE?  This is the first I have heard of it.

Isn't the fact that it was mentioned here enough to have it found by a
browser search?

There are a lot of useful manuals that people might not hear about,
but it doesn't mean it's Emacs's job to solve those problems.

How about taking this up with the Texinfo developers?  After all,
Texinfo is a much more logical place to advertise GNU manuals, see
dir-example and htmlxref.cnf files in the Texinfo tree.

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Sean Whitton]

Hello,

On Sun 01 Dec 2024 at 09:45am +02, Eli Zaretskii wrote:

>> From: Sean Whitton <spwhitton@spwhitton.name>
>> Cc: Jeremy Bryant <jb@jeremybryant.net>,  emacs-devel@gnu.org,  rms@gnu.org
>> Date: Sun, 01 Dec 2024 12:02:58 +0800
>>
>> Hello,
>>
>> On Sat 30 Nov 2024 at 03:50pm +02, Eli Zaretskii wrote:
>>
>> > FWIW, I don't think this (IMO very useful and installed on my
>> > machines) manual belongs to Emacs.  It should be a separate manual.
>>
>> Could we add a pointer to it somewhere in our development notes?  Maybe
>> CONTRIBUTE?  This is the first I have heard of it.
>
> Isn't the fact that it was mentioned here enough to have it found by a
> browser search?
>
> There are a lot of useful manuals that people might not hear about,
> but it doesn't mean it's Emacs's job to solve those problems.
>
> How about taking this up with the Texinfo developers?  After all,
> Texinfo is a much more logical place to advertise GNU manuals, see
> dir-example and htmlxref.cnf files in the Texinfo tree.

My thought is that it might be particularly helpful for people learning
more C for Emacs development, because it's written by Richard.
Some of the thinking behind the less usual ways in which C gets used for
Emacs might become clearer, perhaps?

Having not yet read the manual, my opinion counts for little.

-- 
Sean Whitton

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: jb@jeremybryant.net,  emacs-devel@gnu.org,  rms@gnu.org
> Date: Sun, 01 Dec 2024 16:36:02 +0800
> 
> On Sun 01 Dec 2024 at 09:45am +02, Eli Zaretskii wrote:
> 
> >> From: Sean Whitton <spwhitton@spwhitton.name>
> >> Cc: Jeremy Bryant <jb@jeremybryant.net>,  emacs-devel@gnu.org,  rms@gnu.org
> >> Date: Sun, 01 Dec 2024 12:02:58 +0800
> >>
> >> Hello,
> >>
> >> On Sat 30 Nov 2024 at 03:50pm +02, Eli Zaretskii wrote:
> >>
> >> > FWIW, I don't think this (IMO very useful and installed on my
> >> > machines) manual belongs to Emacs.  It should be a separate manual.
> >>
> >> Could we add a pointer to it somewhere in our development notes?  Maybe
> >> CONTRIBUTE?  This is the first I have heard of it.
> >
> > Isn't the fact that it was mentioned here enough to have it found by a
> > browser search?
> >
> > There are a lot of useful manuals that people might not hear about,
> > but it doesn't mean it's Emacs's job to solve those problems.
> >
> > How about taking this up with the Texinfo developers?  After all,
> > Texinfo is a much more logical place to advertise GNU manuals, see
> > dir-example and htmlxref.cnf files in the Texinfo tree.
> 
> My thought is that it might be particularly helpful for people learning
> more C for Emacs development, because it's written by Richard.
> Some of the thinking behind the less usual ways in which C gets used for
> Emacs might become clearer, perhaps?
> 
> Having not yet read the manual, my opinion counts for little.

Then maybe let's talk again after you have read that manual?

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Sean Whitton]

Hello,

On Sun 01 Dec 2024 at 12:01pm +02, Eli Zaretskii wrote:

> Then maybe let's talk again after you have read that manual?

Yes, very fair!

-- 
Sean Whitton

Making the GNU C Manual easier to find in Info

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

  > Isn't the fact that it was mentioned here enough to have it found by a
  > browser search?

That is a very low standard of helpfulness.  We should aim to be more
helpful than that, with our Info manuals.

  > There are a lot of useful manuals that people might not hear about,
  > but it doesn't mean it's Emacs's job to solve those problems.

That is true -- helping to make users aware of the GNU C Manual is not
particularly the mission of GNU Emacs.  But it is the mission of the
GNU system.  We -- the GNU Project -- ought to do a better job of this.

Unfortunately, the GNU Project has no Info Tsar whose job is to plan
changes in various GNU packages to bring the Info system to full
fruition.  Can some of us join a discussion about this, perhaos with
some Texinfo developers and others who might be helpful?

How about if those who are interested reply to me.  We can have the
discussion somewhere else.

-- 
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: Making the GNU C Manual easier to find in Info

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: spwhitton@spwhitton.name, jb@jeremybryant.net, emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 00:05:14 -0500
> 
>   > Isn't the fact that it was mentioned here enough to have it found by a
>   > browser search?
> 
> That is a very low standard of helpfulness.  We should aim to be more
> helpful than that, with our Info manuals.

Agreed.  But the place to seek such help is not necessarily here.

>   > There are a lot of useful manuals that people might not hear about,
>   > but it doesn't mean it's Emacs's job to solve those problems.
> 
> That is true -- helping to make users aware of the GNU C Manual is not
> particularly the mission of GNU Emacs.  But it is the mission of the
> GNU system.  We -- the GNU Project -- ought to do a better job of this.
> 
> Unfortunately, the GNU Project has no Info Tsar whose job is to plan
> changes in various GNU packages to bring the Info system to full
> fruition.  Can some of us join a discussion about this, perhaos with
> some Texinfo developers and others who might be helpful?

I think the Texinfo developers are the de-fact "czars" of the GNU Info
documentation.  So the discussions about this are best held on Texinfo
mailing lists, IMO.

Integration of Info manuals in programming modes; was: Making the GNU C Manual easier to find in Info

[Dr. Arne Babenhauserheide]

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

Richard Stallman <rms@gnu.org> writes:

>   > There are a lot of useful manuals that people might not hear about,
>   > but it doesn't mean it's Emacs's job to solve those problems.
>
> That is true -- helping to make users aware of the GNU C Manual is not
> particularly the mission of GNU Emacs.  But it is the mission of the
> GNU system.  We -- the GNU Project -- ought to do a better job of this.

One thing where Info is on-topic here are Emacs integrations.

I remember how useful it was when I had texinfo links directly
available in Emacs:
https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs

This is something that would be really nice to have as default for most
GNU packages in most programming modes.

Do you know other info-to-programming-mode integrations?

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  spwhitton@spwhitton.name,
>   jb@jeremybryant.net,  emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 08:25:35 +0100
> 
> One thing where Info is on-topic here are Emacs integrations.
> 
> I remember how useful it was when I had texinfo links directly
> available in Emacs:
> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs

Sorry, I don't understand: info-look.el already supports "C-h S" for
Python code, assuming you have a Python manual in Info format
installed.  So why would a separate add-on package such as pydoc-info
be needed nowadays?  Perhaps it was needed many years ago, when
info-look.el didn't have the Python part?  Or what am I missing?

> This is something that would be really nice to have as default for most
> GNU packages in most programming modes.

What other GNU programming packages which have Info manuals and
suitable Emacs major modes are not supported by info-look.el?

Re: Integration of Info manuals in programming modes

[Visuwesh]

[வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:

>> This is something that would be really nice to have as default for most
>> GNU packages in most programming modes.
>
> What other GNU programming packages which have Info manuals and
> suitable Emacs major modes are not supported by info-look.el?

f90-mode could look up intrinsic procedures in the gfortran Info manual.
Maybe there is a better for Fortran that I am unaware of.  A start would
be

    (info-lookup-maybe-add-help
     :mode 'f90-mode
     :ignore-case t
     :regexp "[A-Za-z0-9_]+"
     :doc-spec '(("(gfortran)Keyword Index")))

but I do not understand how info-lookup works really.  C-h S RET on
'read' jumps to the FGET page which is not we want.

Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: "Dr. Arne Babenhauserheide" <arne_bab@web.de>,  rms@gnu.org,
>   spwhitton@spwhitton.name,  jb@jeremybryant.net,  emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 14:22:41 +0530
> 
> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
> 
> > What other GNU programming packages which have Info manuals and
> > suitable Emacs major modes are not supported by info-look.el?
> 
> f90-mode could look up intrinsic procedures in the gfortran Info manual.
> Maybe there is a better for Fortran that I am unaware of.  A start would
> be
> 
>     (info-lookup-maybe-add-help
>      :mode 'f90-mode
>      :ignore-case t
>      :regexp "[A-Za-z0-9_]+"
>      :doc-spec '(("(gfortran)Keyword Index")))

We could definitely add something like that, but is it specific to
f90-mode?  What about other Fortran modes?

> but I do not understand how info-lookup works really.  C-h S RET on
> 'read' jumps to the FGET page which is not we want.

Look at the index node you mentioned: what other menu item that
matches "read" there is more appropriate?  And what did you expect to
see instead?

The gfortran manual doesn't seem to describe the Fortran language,
only the GNU-specific extensions or something.  It lacks basic Fortran
keywords.  Perhaps that is the source of your confusion?

Re: Integration of Info manuals in programming modes

[Visuwesh]

[வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: "Dr. Arne Babenhauserheide" <arne_bab@web.de>,  rms@gnu.org,
>>   spwhitton@spwhitton.name,  jb@jeremybryant.net,  emacs-devel@gnu.org
>> Date: Thu, 05 Dec 2024 14:22:41 +0530
>> 
>> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
>> 
>> > What other GNU programming packages which have Info manuals and
>> > suitable Emacs major modes are not supported by info-look.el?
>> 
>> f90-mode could look up intrinsic procedures in the gfortran Info manual.
>> Maybe there is a better for Fortran that I am unaware of.  A start would
>> be
>> 
>>     (info-lookup-maybe-add-help
>>      :mode 'f90-mode
>>      :ignore-case t
>>      :regexp "[A-Za-z0-9_]+"
>>      :doc-spec '(("(gfortran)Keyword Index")))
>
> We could definitely add something like that, but is it specific to
> f90-mode?  What about other Fortran modes?

I am ignorant in that regard.  I only ever look at Fortran 90 code, I
rarely, if ever, need to look at Fortran 77 code (so I'm saved in that
regard).

>> but I do not understand how info-lookup works really.  C-h S RET on
>> 'read' jumps to the FGET page which is not we want.
>
> Look at the index node you mentioned: what other menu item that
> matches "read" there is more appropriate?  And what did you expect to
> see instead?

I would rather see a complain about no matches.  If someone could figure
out how to reject non-exact matches, that would be do the job.

> The gfortran manual doesn't seem to describe the Fortran language,
> only the GNU-specific extensions or something.  It lacks basic Fortran
> keywords.  Perhaps that is the source of your confusion?

It documents intrinsic functions and subroutines.  It is by no means a
complete manual for the Fortran language though.  It is no small wonder
that keywords are not documented.  I have been looking for such a manual
to no avail.

Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: arne_bab@web.de,  rms@gnu.org,  spwhitton@spwhitton.name,
>   jb@jeremybryant.net,  emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 15:19:13 +0530
> 
> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
> 
> >> but I do not understand how info-lookup works really.  C-h S RET on
> >> 'read' jumps to the FGET page which is not we want.
> >
> > Look at the index node you mentioned: what other menu item that
> > matches "read" there is more appropriate?  And what did you expect to
> > see instead?
> 
> I would rather see a complain about no matches.  If someone could figure
> out how to reject non-exact matches, that would be do the job.

That's a double-edge sword: rejecting non-exact matches could miss
valid hits.

However, maybe the regexp should only match keywords in upper-case,
and ignore-case should not be used?

Re: Integration of Info manuals in programming modes

[Visuwesh]

[வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: arne_bab@web.de,  rms@gnu.org,  spwhitton@spwhitton.name,
>>   jb@jeremybryant.net,  emacs-devel@gnu.org
>> Date: Thu, 05 Dec 2024 15:19:13 +0530
>> 
>> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
>> 
>> >> but I do not understand how info-lookup works really.  C-h S RET on
>> >> 'read' jumps to the FGET page which is not we want.
>> >
>> > Look at the index node you mentioned: what other menu item that
>> > matches "read" there is more appropriate?  And what did you expect to
>> > see instead?
>> 
>> I would rather see a complain about no matches.  If someone could figure
>> out how to reject non-exact matches, that would be do the job.
>
> That's a double-edge sword: rejecting non-exact matches could miss
> valid hits.

I agree, dismissing a invalid match is not too much trouble.

> However, maybe the regexp should only match keywords in upper-case,
> and ignore-case should not be used?

But Fortran is a case-insensitive language and recent style-guides ask
you to use lower case lettering for everything.  Other code that I've
seen use upper case lettering for keywords, not for functions and
subroutines so we cannot opt for this route unfortunately.

Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: arne_bab@web.de,  rms@gnu.org,  spwhitton@spwhitton.name,
>   jb@jeremybryant.net,  emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 16:58:22 +0530
> 
> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
> 
> >> From: Visuwesh <visuweshm@gmail.com>
> >> Cc: arne_bab@web.de,  rms@gnu.org,  spwhitton@spwhitton.name,
> >>   jb@jeremybryant.net,  emacs-devel@gnu.org
> >> Date: Thu, 05 Dec 2024 15:19:13 +0530
> >> 
> >> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
> >> 
> >> >> but I do not understand how info-lookup works really.  C-h S RET on
> >> >> 'read' jumps to the FGET page which is not we want.
> >> >
> >> > Look at the index node you mentioned: what other menu item that
> >> > matches "read" there is more appropriate?  And what did you expect to
> >> > see instead?
> >> 
> >> I would rather see a complain about no matches.  If someone could figure
> >> out how to reject non-exact matches, that would be do the job.
> >
> > That's a double-edge sword: rejecting non-exact matches could miss
> > valid hits.
> 
> I agree, dismissing a invalid match is not too much trouble.
> 
> > However, maybe the regexp should only match keywords in upper-case,
> > and ignore-case should not be used?
> 
> But Fortran is a case-insensitive language and recent style-guides ask
> you to use lower case lettering for everything.  Other code that I've
> seen use upper case lettering for keywords, not for functions and
> subroutines so we cannot opt for this route unfortunately.

What is important in this context is not whether Fortran is
case-insensitive, but how the index of the manual spells the keywords.

Re: Integration of Info manuals in programming modes

[Visuwesh]

[வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:

>> > However, maybe the regexp should only match keywords in upper-case,
>> > and ignore-case should not be used?
>> 
>> But Fortran is a case-insensitive language and recent style-guides ask
>> you to use lower case lettering for everything.  Other code that I've
>> seen use upper case lettering for keywords, not for functions and
>> subroutines so we cannot opt for this route unfortunately.
>
> What is important in this context is not whether Fortran is
> case-insensitive, but how the index of the manual spells the keywords.

I do not really understand how info-lookup does its job but 'read' still
matches if I use

    (info-lookup-maybe-add-help
     :mode 'f90-mode
     :parse-rule "[A-Za-z0-9_]+"
     :regexp "[A-Z0-9_]+"
     :doc-spec '(("(gfortran)Keyword Index")))

instead.  Perhaps I do not understand what you have in mind.

Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: arne_bab@web.de,  rms@gnu.org,  spwhitton@spwhitton.name,
>   jb@jeremybryant.net,  emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 18:09:39 +0530
> 
> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
> 
> >> > However, maybe the regexp should only match keywords in upper-case,
> >> > and ignore-case should not be used?
> >> 
> >> But Fortran is a case-insensitive language and recent style-guides ask
> >> you to use lower case lettering for everything.  Other code that I've
> >> seen use upper case lettering for keywords, not for functions and
> >> subroutines so we cannot opt for this route unfortunately.
> >
> > What is important in this context is not whether Fortran is
> > case-insensitive, but how the index of the manual spells the keywords.
> 
> I do not really understand how info-lookup does its job but 'read' still
> matches if I use
> 
>     (info-lookup-maybe-add-help
>      :mode 'f90-mode
>      :parse-rule "[A-Za-z0-9_]+"
>      :regexp "[A-Z0-9_]+"
>      :doc-spec '(("(gfortran)Keyword Index")))
> 
> instead.  Perhaps I do not understand what you have in mind.

Maybe it's deeper in the bowels of the code, maybe even in info.el.
E.g., info.el could bind case-fold-search non-nil when looking up
index items.

Re: Integration of Info manuals in programming modes

[Visuwesh]

[வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: arne_bab@web.de,  rms@gnu.org,  spwhitton@spwhitton.name,
>>   jb@jeremybryant.net,  emacs-devel@gnu.org
>> Date: Thu, 05 Dec 2024 18:09:39 +0530
>> 
>> [வியாழன் டிசம்பர் 05, 2024] Eli Zaretskii wrote:
>> 
>> >> > However, maybe the regexp should only match keywords in upper-case,
>> >> > and ignore-case should not be used?
>> >> 
>> >> But Fortran is a case-insensitive language and recent style-guides ask
>> >> you to use lower case lettering for everything.  Other code that I've
>> >> seen use upper case lettering for keywords, not for functions and
>> >> subroutines so we cannot opt for this route unfortunately.
>> >
>> > What is important in this context is not whether Fortran is
>> > case-insensitive, but how the index of the manual spells the keywords.
>> 
>> I do not really understand how info-lookup does its job but 'read' still
>> matches if I use
>> 
>>     (info-lookup-maybe-add-help
>>      :mode 'f90-mode
>>      :parse-rule "[A-Za-z0-9_]+"
>>      :regexp "[A-Z0-9_]+"
>>      :doc-spec '(("(gfortran)Keyword Index")))
>> 
>> instead.  Perhaps I do not understand what you have in mind.
>
> Maybe it's deeper in the bowels of the code, maybe even in info.el.
> E.g., info.el could bind case-fold-search non-nil when looking up
> index items.

It wasn't info.el but info-look.el that does not bind case-fold-search
to nil so case-sensitive :regexp fails above.  To get info-look.el to
restrict to upper case entries in the node, I had to add a TRANS-FUNC in
:doc-spec like below:

    (info-lookup-maybe-add-help
     :mode 'f90-mode
     :regexp "[A-Z0-9_]+"
     :parse-rule "[a-zA-Z0-9_]+"
     :doc-spec `(("(gfortran)Keyword Index"
                  ,(lambda (item)
                     (let ((case-fold-search nil))
                       (and (string-match-p "\\`[A-Z0-9_]+\\'" item)
                            item))))))

fortran-mode should have this too but I am unsure how to specify two
modes.  Saying :other-modes '(fortran-mode) did not do the job.

BTW, all :ignore-case does is downcase the matched Info index items when
creating info-lookup-cache and bind completion-ignore-case accordingly
for C-h S.

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[James Thomas]

Eli Zaretskii <eliz@gnu.org> writes:

>> One thing where Info is on-topic here are Emacs integrations.
>>
>> I remember how useful it was when I had texinfo links directly
>> available in Emacs:
>> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
>
> Sorry, I don't understand: info-look.el already supports "C-h S" for
> Python code, assuming you have a Python manual in Info format
> installed.

Just wanna chime in that this is not perfect, for other reasons: For
e.g. 'C-h S' on 'print' does not give the index item "* built-in
function; print" because, as you can see, it's not named appropriately
in Sphinx's generation.

> What other GNU programming packages which have Info manuals and
> suitable Emacs major modes are not supported by info-look.el?

Speaking about python, many libraries (such as PyTorch & NumPy) use
Sphinx, but the info generation has bug when it uses 'numpydoc' that
requires a little manual fixing of the .texi.

--

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[James Thomas]

James Thomas <jimjoe@gmx.net> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> One thing where Info is on-topic here are Emacs integrations.
>>>
>>> I remember how useful it was when I had texinfo links directly
>>> available in Emacs:
>>> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
>>
>> Sorry, I don't understand: info-look.el already supports "C-h S" for
>> Python code, assuming you have a Python manual in Info format
>> installed.
>
> Just wanna chime in that this is not perfect, for other reasons: For
> e.g. 'C-h S' on 'print' does not give the index item "* built-in
> function; print" because, as you can see, it's not named appropriately
> in Sphinx's generation.
>
>> What other GNU programming packages which have Info manuals and
>> suitable Emacs major modes are not supported by info-look.el?
>
> Speaking about python, many libraries (such as PyTorch & NumPy) use
> Sphinx, but the info generation has bug when it uses 'numpydoc' that
> requires a little manual fixing of the .texi.

And a PSA for anyone who wants to use these:

Set 'Info-hide-note-references' to 'hide' to get rid of the "see" before
every link.

--

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: James Thomas <jimjoe@gmx.net>
> Date: Sun, 08 Dec 2024 13:43:58 +0530
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> One thing where Info is on-topic here are Emacs integrations.
> >>
> >> I remember how useful it was when I had texinfo links directly
> >> available in Emacs:
> >> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
> >
> > Sorry, I don't understand: info-look.el already supports "C-h S" for
> > Python code, assuming you have a Python manual in Info format
> > installed.
> 
> Just wanna chime in that this is not perfect, for other reasons: For
> e.g. 'C-h S' on 'print' does not give the index item "* built-in
> function; print" because, as you can see, it's not named appropriately
> in Sphinx's generation.

Please report that to whoever maintains the Python manual or Sphinx.
info-look.el can fix many problems in the manuals, but not all of
them.

That said, if the "built-in function" part is a general pattern, we
could change the regexps in info-look.el to use that to our advantage;
patches welcome.

> > What other GNU programming packages which have Info manuals and
> > suitable Emacs major modes are not supported by info-look.el?
> 
> Speaking about python, many libraries (such as PyTorch & NumPy) use
> Sphinx, but the info generation has bug when it uses 'numpydoc' that
> requires a little manual fixing of the .texi.

Yes, Sphinx is in many cases a bad idea, but what does this have to do
with the issue at hand here?

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Björn Bidar]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: James Thomas <jimjoe@gmx.net>
>> Date: Sun, 08 Dec 2024 13:43:58 +0530
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> One thing where Info is on-topic here are Emacs integrations.
>> >>
>> >> I remember how useful it was when I had texinfo links directly
>> >> available in Emacs:
>> >> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
>> >
>> > Sorry, I don't understand: info-look.el already supports "C-h S" for
>> > Python code, assuming you have a Python manual in Info format
>> > installed.
>> 
>> Just wanna chime in that this is not perfect, for other reasons: For
>> e.g. 'C-h S' on 'print' does not give the index item "* built-in
>> function; print" because, as you can see, it's not named appropriately
>> in Sphinx's generation.
>
> Please report that to whoever maintains the Python manual or Sphinx.
> info-look.el can fix many problems in the manuals, but not all of
> them.

That's a good idea. I want to add to context that Sphinx plugins can
break the Info output entirely.

I think it would be worth from Gnu put resources into improving the
Texinfo output in Sphinx as it is so wide used by many projects and thus
can provide the most manuals outside the Gnu project right now.

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: Björn Bidar <bjorn.bidar@thaodan.de>
> Cc: James Thomas <jimjoe@gmx.net>,  emacs-devel@gnu.org
> Date: Sun, 08 Dec 2024 22:10:59 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: James Thomas <jimjoe@gmx.net>
> >> Date: Sun, 08 Dec 2024 13:43:58 +0530
> >> 
> >> Eli Zaretskii <eliz@gnu.org> writes:
> >> 
> >> >> One thing where Info is on-topic here are Emacs integrations.
> >> >>
> >> >> I remember how useful it was when I had texinfo links directly
> >> >> available in Emacs:
> >> >> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
> >> >
> >> > Sorry, I don't understand: info-look.el already supports "C-h S" for
> >> > Python code, assuming you have a Python manual in Info format
> >> > installed.
> >> 
> >> Just wanna chime in that this is not perfect, for other reasons: For
> >> e.g. 'C-h S' on 'print' does not give the index item "* built-in
> >> function; print" because, as you can see, it's not named appropriately
> >> in Sphinx's generation.
> >
> > Please report that to whoever maintains the Python manual or Sphinx.
> > info-look.el can fix many problems in the manuals, but not all of
> > them.
> 
> That's a good idea. I want to add to context that Sphinx plugins can
> break the Info output entirely.
> 
> I think it would be worth from Gnu put resources into improving the
> Texinfo output in Sphinx as it is so wide used by many projects and thus
> can provide the most manuals outside the Gnu project right now.

This should be taken up with the Texinfo developers.  Not sure they
will be prepared to do that, but it's their call.

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

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

  > That's a good idea. I want to add to context that Sphinx plugins can
  > break the Info output entirely.

Could you please say what changes you have in mind for Sphinx?

I am interested in Sphinx because I think it could be developed into a
superior replacement for Texinfo, by adding ways to specify the output
style distinctions that Sphinx currently does not handle.  But it
would take some design work, not just simple programming.

-- 
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: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > That's a good idea. I want to add to context that Sphinx plugins can
>   > break the Info output entirely.
>
> Could you please say what changes you have in mind for Sphinx?

I'm not entirely sure but from what I have read it does appear like that
plugins can break the output by inserting their generated markup in
between a block which then causes for example syntax errors.

It's kinda like this (pseudo code)

@toc

toc items here

plugin inserts their markup but forgets and @end somewhere.

@end

The result is that the generated Texinfo contains formatting and or
syntax errors.

> I am interested in Sphinx because I think it could be developed into a
> superior replacement for Texinfo, by adding ways to specify the output
> style distinctions that Sphinx currently does not handle.  But it
> would take some design work, not just simple programming.

I think both are different types of software one uses reStructuredText
as input format while the other (Texinfo) uses well Texinfo.

I'm not a (La)Tex user outside of writing a few documents here and there
but bringing Texinfo closer to Tex could be a good idea while keeping
the output format the same.

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[Dr. Arne Babenhauserheide]

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

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Richard Stallman <rms@gnu.org> writes:
>> I am interested in Sphinx because I think it could be developed into a
>> superior replacement for Texinfo, by adding ways to specify the output
>> style distinctions that Sphinx currently does not handle.  But it
>> would take some design work, not just simple programming.
>
> I think both are different types of software one uses reStructuredText
> as input format while the other (Texinfo) uses well Texinfo.

I don’t think we need a replacement for texinfo. Having many different
tools to create info output is a superior path in my opinion.

We can for example also export from Org Mode to info, and that also does
not replace texinfo but rather extends the possibilities we have to
generate well-usable manuals.

Ideally all the different code documentation tools could export either
to texinfo or to info, and pandoc[1] can already convert most manual
formats to info.

Creating more info packages, so info has manuals for most software on
the computer (instead of having to navigate to websites) could make info
much more useful — the central place to find information about installed
software.

[1] https://pandoc.org/

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Integration of Info manuals in programming modes, Re: Integration of Info manuals in programming modes

[James Thomas]

James Thomas wrote:

> Eli Zaretskii wrote:
>
>>> Eli Zaretskii writes:
>>>
>>> >> One thing where Info is on-topic here are Emacs integrations.
>>> >>
>>> >> I remember how useful it was when I had texinfo links directly
>>> >> available in Emacs:
>>> >> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
>>> >
>>> > Sorry, I don't understand: info-look.el already supports "C-h S" for
>>> > Python code, assuming you have a Python manual in Info format
>>> > installed.
>>>
>>> Just wanna chime in that this is not perfect, for other reasons: For
>>> e.g. 'C-h S' on 'print' does not give the index item "* built-in
>>> function; print" because, as you can see, it's not named appropriately
>>> in Sphinx's generation.
>>
>> Please report that to whoever maintains the Python manual or Sphinx.
>> info-look.el can fix many problems in the manuals, but not all of
>> them.
>>
>> That said, if the "built-in function" part is a general pattern, we
>> could change the regexps in info-look.el to use that to our advantage;
>> patches welcome.
>
> Indeed, but I don't know this (FTR there's also 'module', 'operator' and
> a few others alongside).

FWIW I work around it now in the mode, with:

(info-lookup-add-help
 :doc-spec
 '(("(python3.12)Index" (lambda (item) (string-trim-left item ".*?; ")))))

I think I'll send in a patch (with a few tweaks) soon.

--

Re: Integration of Info manuals in programming modes

[Stephen Berman]

On Thu, 05 Dec 2024 09:46:05 +0200 Eli Zaretskii <eliz@gnu.org> wrote:

> What other GNU programming packages which have Info manuals and
> suitable Emacs major modes are not supported by info-look.el?

R (cf. https://www.r-project.org/about.html: "R is a language and
environment for statistical computing and graphics. It is a GNU
project...").  An R installation comes with several Info manuals.
However, I guess many or perhaps most Emacs users who use R use it with
ESS (available from GNU ELPA), which implements comprehensive help
itegration for R, so for such users info-look integration may be
superfluous.  But it would be helpful for those R+Emacs users who don't
use ESS.  (I could try to make a patch to add support for R to
info-look, but I'm not familiar with info-look, so it could take me some
time.)

Steve Berman

Re: Integration of Info manuals in programming modes

[Dr. Arne Babenhauserheide]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  spwhitton@spwhitton.name,
>>   jb@jeremybryant.net,  emacs-devel@gnu.org
>> Date: Thu, 05 Dec 2024 08:25:35 +0100
>> 
>> One thing where Info is on-topic here are Emacs integrations.
>> 
>> I remember how useful it was when I had texinfo links directly
>> available in Emacs:
>> https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs
>
> Sorry, I don't understand: info-look.el already supports "C-h S" for
…
> installed.  So why would a separate add-on package such as pydoc-info
> be needed nowadays?  Perhaps it was needed many years ago, when
> info-look.el didn't have the Python part?  Or what am I missing?

I’d rather think that *I* was missing info-look.el

>> This is something that would be really nice to have as default for most
>> GNU packages in most programming modes.
>
> What other GNU programming packages which have Info manuals and

Many Python packages *could have* info manuals when their documentation
can be parsed to info (as for example by Sphinx — that’s the essential
part of the article).

So that’s something we could encourage packagers to do.

Can I get info completion from LaTeX? I’d think that pandoc can
transpile most of the extensive LaTeX package documentation to
texinfo/info.

⇒ besides some (now) smaller tooling issues, I see the biggest drawback
  in not having all available that could be in info with not too much
  effort.

Do other distros have more info manuals than Guix?

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Integration of Info manuals in programming modes

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: rms@gnu.org,  spwhitton@spwhitton.name,  jb@jeremybryant.net,
>   emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 16:07:35 +0100
> 
> Can I get info completion from LaTeX?

Yes, if you have the manual.

> Do other distros have more info manuals than Guix?

I don't know.

Re: Integration of Info manuals in programming modes; was: Making the GNU C Manual easier to find in Info

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

  > One thing where Info is on-topic here are Emacs integrations.

Could you tell me what you mean by "Emacs integrations"?
That is a terse term that I don't using in the past.

I saw some emails today which used that term,
but I could not understand them because it was not clear
what practical issue they were about.

Could you please explain?
What does "Emacs integrations" mean,
what is the problem you would like addressed?

  > I remember how useful it was when I had texinfo links directly
  > available in Emacs:

What does "texinfo links directly available in Emacs" mean, concretely?
It isn't self-evident to me.

  > https://www.draketo.de/light/english/free-software/read-your-python-module-documentation-emacs

That article is long, and since I do not know Python, I can't tell what
problem it offers a solution for.

What you would like to do may be a fine thing to do, but in order to
understand it here, we need it to be explained in Emacs terms, not in
Python terms.



-- 
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: Integration of Info manuals in programming modes; was: Making the GNU C Manual easier to find in Info

[Dr. Arne Babenhauserheide]

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

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > One thing where Info is on-topic here are Emacs integrations.
>
> Could you tell me what you mean by "Emacs integrations"?
> That is a terse term that I don't using in the past.

I mean that information from texinfo can be used in other parts of
Emacs. But I now learned that there’s already an into-lookupp mode:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Info-Lookup.html

It may be interesting to extend this to provide an interactive
completion interface (with additional info from info) or overlays
similar to lsp-lens.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Integration of Info manuals in programming modes; was: Making the GNU C Manual easier to find in Info

[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 mean that information from texinfo can be used in other parts of
  > Emacs.

That gives me a start at understanding, but it is sketchy and general.
I think the area is interesting and I'd like to understand what you
are suggesting.

Could you possibly describe concretey one or two ideas for how this
would look to the user?  Then I would understand it and may have
ideas.

  > It may be interesting to extend this to provide an interactive
  > completion interface (with additional info from info)

What namespace would it try to complete over?

                                                          or overlays
  > similar to lsp-lens.

Sorry, I don't know about lsp-lens.  What does it do?

-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

  > FWIW, I don't think this (IMO very useful and installed on my
  > machines) manual belongs to Emacs.  It should be a separate manual.

As a general design principle, it doesn't seem to make sense to
include all GNU manuals in the Emacs distribution merely because they
are useful manuals.  The idea was to relese them separately and have
them installed separately into a combined info tree.

Why is that not working?  What needs to be changed in some GNU/Linux
distros?

-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: jb@jeremybryant.net, emacs-devel@gnu.org
> Date: Sun, 01 Dec 2024 23:10:09 -0500
> 
>   > FWIW, I don't think this (IMO very useful and installed on my
>   > machines) manual belongs to Emacs.  It should be a separate manual.
> 
> As a general design principle, it doesn't seem to make sense to
> include all GNU manuals in the Emacs distribution merely because they
> are useful manuals.  The idea was to relese them separately and have
> them installed separately into a combined info tree.
> 
> Why is that not working?  What needs to be changed in some GNU/Linux
> distros?

It does work in general.  However, some manuals, which don't belong to
any project in particular, are largely unknown to exist.  The two
prominent examples I have are for some reason both related to the C
language: gnu-c-manual.info and c.info.  The latter is not even
mentioned in dir-example file that the Texinfo project distributes.

[ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Jeremy Bryant]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Richard Stallman <rms@gnu.org>
>> Cc: jb@jeremybryant.net, emacs-devel@gnu.org
>> Date: Sun, 01 Dec 2024 23:10:09 -0500
>> 
>>   > FWIW, I don't think this (IMO very useful and installed on my
>>   > machines) manual belongs to Emacs.  It should be a separate manual.
>> 
>> As a general design principle, it doesn't seem to make sense to
>> include all GNU manuals in the Emacs distribution merely because they
>> are useful manuals.  The idea was to relese them separately and have
>> them installed separately into a combined info tree.
>> 
>> Why is that not working?  What needs to be changed in some GNU/Linux
>> distros?
>
> It does work in general.  However, some manuals, which don't belong to
> any project in particular, are largely unknown to exist.  The two
> prominent examples I have are for some reason both related to the C
> language: gnu-c-manual.info and c.info.  The latter is not even
> mentioned in dir-example file that the Texinfo project distributes.

Understood.
I have created a prototype ELPA package, comments welcome?

upstream url:
https://github.com/jeremy-bryant/c-intro-and-ref

As some manuals are available in GNU/Linux distros but not this one, it would provide a distribution mechanism for c.info
I also include a PDF output.

Current Package name, proposed for ELPA: c-intro-and-ref
This matches the existing manual distribution.
Perhaps a name such as: gnu-c-manual
would be easier to find, however on gnu.org this points to another,
maybe a predecessor manual.  (https://www.gnu.org/software/gnu-c-manual/gnu-c-manual.html)

Main file: c-intro-and-ref.el
This is simply a placeholder for the c.texi and other files

[-- Attachment #2: c-intro-and-ref.el --]
[-- Type: application/emacs-lisp, Size: 2838 bytes --]

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: rms@gnu.org,  emacs-devel@gnu.org, Philip Kaludercic <philipk@posteo.net>
> Date: Tue, 03 Dec 2024 23:03:42 +0000
> 
> I have created a prototype ELPA package, comments welcome?

Are we providing packages that include only Info manuals, which
document stuff that is not specific to Emacs?  Because I don't see how
it would be a good idea to have this as an ELPA package.

But if we do accept such packages on ELPA, then I have 2 additional
similar suggestions:

  . Git manual in Info format
  . Python 3 manual in Info format

> Current Package name, proposed for ELPA: c-intro-and-ref
> This matches the existing manual distribution.
> Perhaps a name such as: gnu-c-manual

That'd be wrong, since this manual doesn't describe GNU C, it
describes the C language in general.  (There's a separate GNU C
manual, btw.)

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Jeremy Bryant]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: rms@gnu.org, emacs-devel@gnu.org, Philip Kaludercic
>> <philipk@posteo.net>
>> Date: Tue, 03 Dec 2024 23:03:42 +0000
>> 
>> I have created a prototype ELPA package, comments welcome?
>
> Are we providing packages that include only Info manuals, which
> document stuff that is not specific to Emacs?  Because I don't see how
> it would be a good idea to have this as an ELPA package.

I hear that maybe it's not a good idea, as this is not Emacs specific.

From a complementary point of view, reading this list it appears that
there is a smaller number of C contributors to Emacs, compared to Lisp,
and more C contributors are needed to work on Emacs.

Can we facilitate C documentation?
For example.  The info-look.el subsystem already adds lookup facility for manuals such
as (libc).  Wouldn't it be useful to also have c.info similarly
available and to aid in Emacs C development?  That is
part of the motivation.


>
> But if we do accept such packages on ELPA, then I have 2 additional
> similar suggestions:
>
>   . Git manual in Info format
>   . Python 3 manual in Info format

Yes, I recently wrote about the second point for Python, so I would agree.
(https://onlisp.co.uk/Creating-an-info-manual-for-Python.html)
I may be able to volunteer towards a prototype, depending on time.

>
>> Current Package name, proposed for ELPA: c-intro-and-ref
>> This matches the existing manual distribution.
>> Perhaps a name such as: gnu-c-manual
>
> That'd be wrong, since this manual doesn't describe GNU C, it
> describes the C language in general.  (There's a separate GNU C
> manual, btw.)

Thanks for the perspective, I do find the several names overlapping,
possibly for historical reasons.

The c.texi file starts with a mention of GNU C

@direntry
* C: (c).       GNU C Language Intro and Reference Manual
@end direntry

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: rms@gnu.org,  emacs-devel@gnu.org,  philipk@posteo.net,  Stefan Monnier
>  <monnier@iro.umontreal.ca>
> Date: Wed, 04 Dec 2024 22:58:44 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Are we providing packages that include only Info manuals, which
> > document stuff that is not specific to Emacs?  Because I don't see how
> > it would be a good idea to have this as an ELPA package.
> 
> I hear that maybe it's not a good idea, as this is not Emacs specific.
> 
> >From a complementary point of view, reading this list it appears that
> there is a smaller number of C contributors to Emacs, compared to Lisp,
> and more C contributors are needed to work on Emacs.
> 
> Can we facilitate C documentation?
> For example.  The info-look.el subsystem already adds lookup facility for manuals such
> as (libc).  Wouldn't it be useful to also have c.info similarly
> available and to aid in Emacs C development?  That is
> part of the motivation.

It's okay to extend info-look.el to use this manual (and perhaps also
the sibling GNU C manual?), but please note that we do NOT provide the
glibc Info manual on ELPA, although it is referenced by info-look.el
(and I personally have that manual installed on my system, even though
my main development machine doesn't use glibc).

> The c.texi file starts with a mention of GNU C
> 
> @direntry
> * C: (c).       GNU C Language Intro and Reference Manual
> @end direntry

Yes.

Improving info-look.el for (c) -was- Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Jeremy Bryant]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> >From a complementary point of view, reading this list it appears that
>> there is a smaller number of C contributors to Emacs, compared to Lisp,
>> and more C contributors are needed to work on Emacs.
>> 
>> Can we facilitate C documentation?
>> For example.  The info-look.el subsystem already adds lookup
>> facility for manuals such
>> as (libc).  Wouldn't it be useful to also have c.info similarly
>> available and to aid in Emacs C development?  That is
>> part of the motivation.
>
> It's okay to extend info-look.el to use this manual (and perhaps also
> the sibling GNU C manual?), but please note that we do NOT provide the
> glibc Info manual on ELPA, although it is referenced by info-look.el
> (and I personally have that manual installed on my system, even though
> my main development machine doesn't use glibc).
>

Okay, on this particular change, after studying info-look.el, it is not
clear to me how info-look resolves multiple manuals, in order to make it
work with both (libc), (c) and other manuals on the same buffer.

Should we add another info-lookup-maybe-add-help, or amend the existing one?

Would you have suggestions on how to work on this, so I can experiment
with a patch?

Re: Improving info-look.el for (c) -was- Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: rms@gnu.org,  emacs-devel@gnu.org,  philipk@posteo.net,
>   monnier@iro.umontreal.ca
> Date: Sat, 07 Dec 2024 13:30:10 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > It's okay to extend info-look.el to use this manual (and perhaps also
> > the sibling GNU C manual?), but please note that we do NOT provide the
> > glibc Info manual on ELPA, although it is referenced by info-look.el
> > (and I personally have that manual installed on my system, even though
> > my main development machine doesn't use glibc).
> >
> 
> Okay, on this particular change, after studying info-look.el, it is not
> clear to me how info-look resolves multiple manuals, in order to make it
> work with both (libc), (c) and other manuals on the same buffer.

See how this is set up for emacs-lisp-mode: AFAIU, you just need to
specify a list of alternative index nodes, and they will be tried
until a match is found.  Note that the setup for c-mode already
mentions more than one manual.

> Should we add another info-lookup-maybe-add-help, or amend the existing one?

Amending the existing one is TRT, IMO.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Max Nikulin]

On 04/12/2024 19:33, Eli Zaretskii wrote:
> Are we providing packages that include only Info manuals, which
> document stuff that is not specific to Emacs?  Because I don't see how
> it would be a good idea to have this as an ELPA package.

It might be a dedicated ELPA instance if somebody is ready to maintain one.

>    . Git manual in Info format
>    . Python 3 manual in Info format

Debian offers /usr/share/info/python3.11.info.gz, but not git manual as 
info files.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Jeremy Bryant <jb@jeremybryant.net>
>> Cc: rms@gnu.org,  emacs-devel@gnu.org, Philip Kaludercic <philipk@posteo.net>
>> Date: Tue, 03 Dec 2024 23:03:42 +0000
>> 
>> I have created a prototype ELPA package, comments welcome?
>
> Are we providing packages that include only Info manuals, which
> document stuff that is not specific to Emacs?  Because I don't see how
> it would be a good idea to have this as an ELPA package.
>
> But if we do accept such packages on ELPA, then I have 2 additional
> similar suggestions:
>
>   . Git manual in Info format
>   . Python 3 manual in Info format

It would also make sense to make the Emacs manuals available for easy
download, as distributions like Debian do not include these by default.
Whether we distribute these by piggy-backing on package.el or have a
separate installer that could be distributed on ELPA is a different
matter, but it would be useful to have an index of already existing
manuals that would be interesting regardless of their relation to Emacs.

>> Current Package name, proposed for ELPA: c-intro-and-ref
>> This matches the existing manual distribution.
>> Perhaps a name such as: gnu-c-manual
>
> That'd be wrong, since this manual doesn't describe GNU C, it
> describes the C language in general.  (There's a separate GNU C
> manual, btw.)

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: Jeremy Bryant <jb@jeremybryant.net>,  rms@gnu.org,  emacs-devel@gnu.org,
>   Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 05 Dec 2024 18:47:31 +0000
> 
> It would also make sense to make the Emacs manuals available for easy
> download

The Emacs manuals are part of the release tarballs, so they are
already easily donwloadable: just download the release tarball, unpack
it, and take all the files from the info/ subdirectory.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: Jeremy Bryant <jb@jeremybryant.net>,  rms@gnu.org,  emacs-devel@gnu.org,
>>   Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Thu, 05 Dec 2024 18:47:31 +0000
>> 
>> It would also make sense to make the Emacs manuals available for easy
>> download
>
> The Emacs manuals are part of the release tarballs, so they are
> already easily donwloadable: just download the release tarball, unpack
> it, and take all the files from the info/ subdirectory.

While true, I think it is worth making it easier especially for people
who are not familiar with TeXinfo and TeXinfo tooling.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: jb@jeremybryant.net,  rms@gnu.org,  emacs-devel@gnu.org,
>   monnier@iro.umontreal.ca
> Date: Fri, 06 Dec 2024 10:44:16 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Philip Kaludercic <philipk@posteo.net>
> >> Cc: Jeremy Bryant <jb@jeremybryant.net>,  rms@gnu.org,  emacs-devel@gnu.org,
> >>   Stefan Monnier <monnier@iro.umontreal.ca>
> >> Date: Thu, 05 Dec 2024 18:47:31 +0000
> >> 
> >> It would also make sense to make the Emacs manuals available for easy
> >> download
> >
> > The Emacs manuals are part of the release tarballs, so they are
> > already easily donwloadable: just download the release tarball, unpack
> > it, and take all the files from the info/ subdirectory.
> 
> While true, I think it is worth making it easier especially for people
> who are not familiar with TeXinfo and TeXinfo tooling.

What Texinfo tooling is involved?  The release tarball includes the
generated Info files, so Texinfo doesn't have to be installed or used
(which is the primary reason why we include the Info files in the
tarball in the first place).

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: jb@jeremybryant.net,  rms@gnu.org,  emacs-devel@gnu.org,
>>   monnier@iro.umontreal.ca
>> Date: Fri, 06 Dec 2024 10:44:16 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> From: Philip Kaludercic <philipk@posteo.net>
>> >> Cc: Jeremy Bryant <jb@jeremybryant.net>, rms@gnu.org,
>> >> emacs-devel@gnu.org,
>> >>   Stefan Monnier <monnier@iro.umontreal.ca>
>> >> Date: Thu, 05 Dec 2024 18:47:31 +0000
>> >> 
>> >> It would also make sense to make the Emacs manuals available for easy
>> >> download
>> >
>> > The Emacs manuals are part of the release tarballs, so they are
>> > already easily donwloadable: just download the release tarball, unpack
>> > it, and take all the files from the info/ subdirectory.
>> 
>> While true, I think it is worth making it easier especially for people
>> who are not familiar with TeXinfo and TeXinfo tooling.
>
> What Texinfo tooling is involved?  The release tarball includes the
> generated Info files, so Texinfo doesn't have to be installed or used
> (which is the primary reason why we include the Info files in the
> tarball in the first place).

Ah, I missed that the tarball includes .info files (though that does
make sense).  The issue is that off the top of my head, I wouldn't know
what to do with these either.  That is not unsolvable, but I do think
that it involves a non-trivial process.  Having a `info-install'-ish
command as alternative way to fetch and manage the Emacs is something I
would have appreciated in the past.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Stefan Monnier]

>> Are we providing packages that include only Info manuals, which
>> document stuff that is not specific to Emacs?  Because I don't see how
>> it would be a good idea to have this as an ELPA package.

There is a precedent in the form of the [Ada reference
manual](http://elpa.gnu.org/packages/ada-ref-man.html).
FWIW, I'm not completely comfortable with this precedent.
Sadly Info is rarely used outside of Emacs FAICT, so there is a clear
tendency to consider Info manual as "manuals for use within Emacs".

> It would also make sense to make the Emacs manuals available for easy
> download, as distributions like Debian do not include these by default.
> Whether we distribute these by piggy-backing on package.el or have a
> separate installer that could be distributed on ELPA is a different
> matter, but it would be useful to have an index of already existing
> manuals that would be interesting regardless of their relation to Emacs.

A dedicated ELisp package that can download manuals and install them in
Info format (which may require converting from another format) would be
nice (or more generally in any format that Emacs can use, which may also
include HTML, nowadays, tho we still need extra work to make HTML
manuals as well integrated as Info manuals).


        Stefan

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[chad]

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

On Thu, Dec 5, 2024 at 2:18 PM Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> A dedicated ELisp package that can download manuals and install them in
> Info format (which may require converting from another format) would be
> nice (or more generally in any format that Emacs can use, which may also
> include HTML, nowadays, tho we still need extra work to make HTML
> manuals as well integrated as Info manuals).
>

Is there a good standardized place to store these? Does the answer
depend on format? (Note that there seem to be many doc formats in use
these days that are very likely to run non-obvious code in the
formatting or conversion processes.)

Once upon a time, I spent a lot of time & effort on centralizing
resources, but these days it seems like almost every machine people
use is either very personal or massively shared with a minimal
installation base (Docker et al excesses definitely notwithstanding),
so maybe it's safe, these days, to just assume personal repositories
unless explicitly configured otherwise.

I haven't played with it in a while (since I changed careers), but if
the above two concerns aren't problematic, it seems like some elisp to
drive pandoc, with a "default" library of sources, might work well
here. Anyone have recent experience with this? In particular, does it
currently produce decent-quality Texinfo?

~Chad

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

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Visuwesh]

[வியாழன் டிசம்பர் 05, 2024] Stefan Monnier wrote:

>> It would also make sense to make the Emacs manuals available for easy
>> download, as distributions like Debian do not include these by default.
>> Whether we distribute these by piggy-backing on package.el or have a
>> separate installer that could be distributed on ELPA is a different
>> matter, but it would be useful to have an index of already existing
>> manuals that would be interesting regardless of their relation to Emacs.
>
> A dedicated ELisp package that can download manuals and install them in
> Info format (which may require converting from another format) would be
> nice (or more generally in any format that Emacs can use, which may also
> include HTML, nowadays, tho we still need extra work to make HTML
> manuals as well integrated as Info manuals).

I know of two "standard" HTML manual "types": docsets/dashdocs and
devdocs.  We have a package in ELPA for the latter written by Augusto.
The former also has an Emacs client [1] but it invokes the sqlite3 CLI.
We can probably do better now with builtin SQLITE support.  It would be
nice to have a unifying UI for both of them but I it may be unlikely [2].

1. https://github.com/dash-docs-el/dash-docs
2. https://github.com/freeCodeCamp/devdocs/issues/117

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Philip Kaludercic]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> Are we providing packages that include only Info manuals, which
>>> document stuff that is not specific to Emacs?  Because I don't see how
>>> it would be a good idea to have this as an ELPA package.
>
> There is a precedent in the form of the [Ada reference
> manual](http://elpa.gnu.org/packages/ada-ref-man.html).
> FWIW, I'm not completely comfortable with this precedent.

MELPA also has a package distributing the TeXinfo version of SICP:
https://github.com/webframp/sicp-info.

> Sadly Info is rarely used outside of Emacs FAICT, so there is a clear
> tendency to consider Info manual as "manuals for use within Emacs".
>
>> It would also make sense to make the Emacs manuals available for easy
>> download, as distributions like Debian do not include these by default.
>> Whether we distribute these by piggy-backing on package.el or have a
>> separate installer that could be distributed on ELPA is a different
>> matter, but it would be useful to have an index of already existing
>> manuals that would be interesting regardless of their relation to Emacs.
>
> A dedicated ELisp package that can download manuals and install them in
> Info format (which may require converting from another format) would be
> nice (or more generally in any format that Emacs can use, which may also
> include HTML, nowadays, tho we still need extra work to make HTML
> manuals as well integrated as Info manuals).

I'd gladly implement the package, but right now the main manuals I know
of are the ones listed here: https://www.gnu.org/manual/.  Looking at
the page, it turns out to be more than I had assumed, so perhaps it is
a useful place to start from.

>
>         Stefan

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Max Nikulin]

On 06/12/2024 01:47, Philip Kaludercic wrote:
> It would also make sense to make the Emacs manuals available for easy
> download, as distributions like Debian do not include these by default.

<https://www.gnu.org/software/emacs/manual/emacs.html>
has a link to emacs.info.gz, there is no need to download whole source 
tarball. A couple of issues:
- this page does not contain "../" link to other manuals
- only one release is available (so "Updated: $Date: 2016/06/20 13:37:40 
$" might be confusing) while Emacs-28 is available from Debian stable 
repositories.

I still think that it is easier to install the emacs-common-non-dfsg 
package than to download info files from some other source.

At first I decided that you statement is related to applications other 
than Emacs as well, so I counted info files

     dpkg -S info.gz | wc -l
     101

and packages

     dpkg -S info.gz | cut -d : -f 1 | sort -u | wc -l
     28

on a machine with relatively low count of applications. It is up to 
package maintainer to build and ship info docs.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Max Nikulin <manikulin@gmail.com>
> Date: Fri, 6 Dec 2024 21:58:39 +0700
> 
> On 06/12/2024 01:47, Philip Kaludercic wrote:
> > It would also make sense to make the Emacs manuals available for easy
> > download, as distributions like Debian do not include these by default.
> 
> <https://www.gnu.org/software/emacs/manual/emacs.html>
> has a link to emacs.info.gz, there is no need to download whole source 
> tarball. A couple of issues:
> - this page does not contain "../" link to other manuals

Why should it?

> - only one release is available (so "Updated: $Date: 2016/06/20 13:37:40 
> $" might be confusing) while Emacs-28 is available from Debian stable 
> repositories.

When a new major release of Emacs happens, we produce the manuals for
that release and update the manuals in the "webpages" repository.
This then triggers the update of the Web page.  We never provided more
than the last major release's manuals from that place.  If someone
wants to work on the scripts used to do this such that they support
leaving the previous manuals (in some properly named directory)
instead of overwriting them, you can find the scripts in the admin/
directory.

> I still think that it is easier to install the emacs-common-non-dfsg 
> package than to download info files from some other source.

The fact that the Emacs manuals are available from the GNU
Documentation site doesn't prevent anyone from using other distros.
Each one should do it in the way that is the most convenient for them.
The important point is that the manuals are "available for easy
download" in more ways than one.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Max Nikulin]

On 06/12/2024 23:30, Eli Zaretskii wrote:
>> From: Max Nikulin Fri, 6 Dec 2024 21:58:39 +0700
>> On 06/12/2024 01:47, Philip Kaludercic wrote:
>>> It would also make sense to make the Emacs manuals available for easy
>>> download, as distributions like Debian do not include these by default.
>>
>> <https://www.gnu.org/software/emacs/manual/emacs.html>
>> has a link to emacs.info.gz, there is no need to download whole source
>> tarball. A couple of issues:
>> - this page does not contain "../" link to other manuals
> 
> Why should it?

It is common to have either breadcrumbs or "up" links for user 
convenience. Just the link to the project home page without
<https://www.gnu.org/software/emacs/manual/>
may make discovery of e.g. Tramp manual harder.

>> I still think that it is easier to install the emacs-common-non-dfsg
>> package than to download info files from some other source.
> 
> The fact that the Emacs manuals are available from the GNU
> Documentation site doesn't prevent anyone from using other distros.
> Each one should do it in the way that is the most convenient for them.
> The important point is that the manuals are "available for easy
> download" in more ways than one.

I do not mind. My point is that there is no real problem with Debian. As 
an alternative, it is not necessary to extract info files from source 
tarball if newer version of docs is acceptable.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

  > > It would also make sense to make the Emacs manuals available for easy
  > > download, as distributions like Debian do not include these by default.

How about if we make ALL the GNU manuals available in one place
as .deb packages, for the same of people with Debian-nased distros?

What is the emacs-common-non-dfsg package?

-- 
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: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Xiyue Deng]

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

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > > It would also make sense to make the Emacs manuals available for easy
>   > > download, as distributions like Debian do not include these by default.
>
> How about if we make ALL the GNU manuals available in one place
> as .deb packages, for the same of people with Debian-nased distros?
>
> What is the emacs-common-non-dfsg package?
>

(I'm not an official Debian Developer, but below are public knowledge in
the Debian community so hopefully I'm not giving incorrect information)

TL;DR: The Emacs documentation is under GFDL with an invariant section,
which is not considered compliant to Debian Free Software Guideline
(DFSG), so its documentation is split into a separate
emacs-common-non-dfsg[1] package and is only available in the "non-free"
section.

Longer story: According to one of Debian's General Resolutions[2], the
GNU Free Document License with an invariant section is considered too
restrictive and hence does not meet Debian's standards for free
software.  Therefore, documents under such licenses needs to be under
the "non-free" section, which is not enabled by default.  As a result,
many Emacs packages under GFDL with an invariant section that are
packaged in Debian have their documentation either removed or put in a
separate package in the "non-free" section.  Examples including Emacs[3]
(with emacs-common-non-dfsg split to the non-free section), compat[4],
dash[5], org-mode[6] (with org-mode-doc[7] split to the non-free
section), etc.  Note that their version numbers have "+dfsg" in it,
because the source packages included in Debian are modified by removing
the non-free part - documents.

As a quick overview for package sections: Debian packages are split into
several main sections: main, contrib, non-free, and recently
non-free-firmware.  "main" (and recently "non-free-firmware") is enabled
by default when installing Debian, and user can choose to enable
"contrib" and "non-free" later.  "non-free" section contains packages
that are under a license that is not DFSG-compliant (see [8] for more
detailed description), "contrib" is for packages that are DFSG-compliant
but depend on packages in the "non-free" section.  "non-free-firmware"[9]
is for firmware packages which are "non-free" but required for running
Debian in certain hardware, especially in recent hardware, and hence are
available during installation.

> -- 
> 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)
>
>
>

[1] https://packages.debian.org/sid/emacs-common-non-dfsg
[2] https://www.debian.org/vote/2006/vote_001
[3] https://packages.debian.org/sid/emacs
[4] https://packages.debian.org/sid/elpa-compat
[5] https://packages.debian.org/sid/elpa-dash
[6] https://packages.debian.org/sid/elpa-org
[7] https://packages.debian.org/sid/org-mode-doc
[8] https://www.debian.org/doc/debian-policy/ch-archive.html#the-non-free-archive-area
[9] https://www.debian.org/vote/2022/vote_003

-- 
Regards,
Xiyue Deng

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

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Max Nikulin]

On 08/12/2024 12:15, Richard Stallman wrote:
> How about if we make ALL the GNU manuals available in one place
> as .deb packages, for the same of people with Debian-nased distros?

At least installed to /usr/share/info, they will cause conflicts with 
native Debian packages.

I do not think you have spare resources to maintain multiple variants of 
the package with info files for versions matching specific releases of 
Debian and its derivatives.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

  > > How about if we make ALL the GNU manuals available in one place
  > > as .deb packages, for the same of people with Debian-nased distros?

  > At least installed to /usr/share/info, they will cause conflicts with 
  > native Debian packages.

Would you please flesh out that sketchy statement?  For instance,
give me an exaple of such a conflict, and what circumstances
would cause it to occur?  Which Debian packages might conflict with
a package that contains only a GNU manual?

-- 
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)

Debian package with GNU manuals (was: Re: [ELPA] New package c-intro-and-ref)

[Max Nikulin]

On 11/12/2024 11:32, Richard Stallman wrote:
> [[[ 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. ]]]
> 
>    > > How about if we make ALL the GNU manuals available in one place
>    > > as .deb packages, for the same of people with Debian-nased distros?
> 
>    > At least installed to /usr/share/info, they will cause conflicts with
>    > native Debian packages.
> 
> Would you please flesh out that sketchy statement?  For instance,
> give me an exaple of such a conflict, and what circumstances
> would cause it to occur?  Which Debian packages might conflict with
> a package that contains only a GNU manual?

Am I right that you are going to put e.g. coreutils and gnupg manuals in 
this package?

Perhaps it is possible to avoid installing dedicated native Debian 
packages with manuals, e.g. bash-doc, emacs-common-non-dfsg and 
org-mode-docs, but I would still prefer to have manual versions matching 
binaries. Another issue is that Debian packages may provide .pdf and 
.html file in addition to .info ones.

The main problem is that some packages contain both important tools and 
manuals for them:

dpkg -L coreutils gzip gnupg findutils | grep -F .info.gz
/usr/share/info/coreutils.info.gz
/usr/share/info/gzip.info.gz
/usr/share/info/gnupg.info.gz
/usr/share/info/find-maint.info.gz
/usr/share/info/find.info.gz

So you need to use some tricks if the new GNU package would contain e.g.
/usr/share/info/coreutils.info.gz
otherwise dpkg would fail in the case of install attempt.

By the way, why additional manuals obtained from net must be namely 
*installed*? Perhaps info browser may *cache* them in a temporary 
directory. Of course, nothing prevent users from downloading important 
manuals to a "persistent" directory.

-- 
P.S.
In my taste missed lines with citation attribution makes it harder to 
follow the discussion.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Suhail Singh]

Jeremy Bryant <jb@jeremybryant.net> writes:

> I have created a prototype ELPA package, comments welcome?
>
> upstream url:
> https://github.com/jeremy-bryant/c-intro-and-ref
>
> ...
>
> Main file: c-intro-and-ref.el
> This is simply a placeholder for the c.texi and other files

Thank you for packaging this in a repository to make it easily
accessible via package-vc-install.

It would help if the name of the texinfo file was the same as that of
the package.  Currently, when using package-vc-install, the name of the
checkout directory has to be specified as 'c (i.e., matching the name of
the texinfo file, as opposed to the repository), since that name is used
by package-vc when generating the info output from the texinfo source.

-- 
Suhail

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Suhail Singh]

Jeremy Bryant <jb@jeremybryant.net> writes:

>>> Main file: c-intro-and-ref.el
>>> This is simply a placeholder for the c.texi and other files
>>
>> Thank you for packaging this in a repository to make it easily
>> accessible via package-vc-install.
>>
>> It would help if the name of the texinfo file was the same as that of
>> the package.  Currently, when using package-vc-install, the name of the
>> checkout directory has to be specified as 'c (i.e., matching the name of
>> the texinfo file, as opposed to the repository), since that name is used
>> by package-vc when generating the info output from the texinfo source.
>
> The manual example ((emacs) Fetching Package Sources)
> seems to allow a :doc keyword?

This isn't about the :doc keyword.  It's a matter of consistency (or
inconsistency).  I shall leave it up to you and others to decide whether
the desire for consistency is foolish in this instance.

As things currently stand, one needs to do something like the below:

#+begin_src emacs-lisp
  (package-vc-install
   '(c :url "https://github.com/jeremy-bryant/c-intro-and-ref"
       :branch "master"
       :rev :newest
       :doc "./c.texi"))
#+end_src

Note, that while the name of the package is c-intro-and-ref, one needs
to provide the name "c" (i.e., that which matches the texinfo source) in
order for things to work.

The above clones the repository within ~/.emacs.d/elpa/c and compiles
the texinfo source to ~/.emacs.d/elpa/c/c.info.

If one is using use-package along with vc-use-package, the above
translates to:

#+begin_src emacs-lisp
  (use-package c-intro-and-ref :ensure nil
    :vc (c :url "https://github.com/jeremy-bryant/c-intro-and-ref"
           :branch "master"
           :rev :newest
           :doc "./c.texi"))
#+end_src

And in this form the inconsistency between the name being used by
use-package vs the name being used by package-vc-install becomes a
little more apparent.  Since the name given to package-vc-install
determines the name of the generated info file (as opposed to the name
of the texinfo source), this isn't optional.  The result is that the
phantom library "c-intro-and-ref" has to reside in ~/.emacs.d/elpa/c as
opposed to ~/.emacs.d/elpa/c-intro-and-ref.

If the file were instead named "c-intro-and-ref.texi", one could use
something like the below:

#+begin_src emacs-lisp
  (use-package c-intro-and-ref :ensure nil
    :vc (c-intro-and-ref :url "https://github.com/jeremy-bryant/c-intro-and-ref"
                         :branch "master"
                         :rev :newest
                         :doc "./c-intro-and-ref.texi"))
#+end_src

-- 
Suhail

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Jeremy Bryant]

Suhail Singh <suhailsingh247@gmail.com> writes:

> Jeremy Bryant <jb@jeremybryant.net> writes:
>
>>>> Main file: c-intro-and-ref.el
>>>> This is simply a placeholder for the c.texi and other files
>>>
>>> Thank you for packaging this in a repository to make it easily
>>> accessible via package-vc-install.
>>>
>>> It would help if the name of the texinfo file was the same as that of
>>> the package.  Currently, when using package-vc-install, the name of the
>>> checkout directory has to be specified as 'c (i.e., matching the name of
>>> the texinfo file, as opposed to the repository), since that name is used
>>> by package-vc when generating the info output from the texinfo source.
>>
>> The manual example ((emacs) Fetching Package Sources)
>> seems to allow a :doc keyword?
>
> This isn't about the :doc keyword.  It's a matter of consistency (or
> inconsistency).  I shall leave it up to you and others to decide whether
> the desire for consistency is foolish in this instance.
>
> As things currently stand, one needs to do something like the below:

Suhail, thanks for highlighting an inconsistency and providing example
code.  I'm currently closely following the actual upstream distribution,
with as little change as possible to the names c-intro-and-ref and
c.info, which are there.

In the meantime, I appreciate the detail and have updated the README as
follows so that users can start easily install this Manual when writing C code
in Emacs.

Installation instructions

(package-vc-install
 '(c-intro-and-ref :url "https://github.com/jeremy-bryant/c-intro-and-ref"
		   :branch "master"
		   :rev :newest
		   :doc "./c.texi"))

or

(use-package c-intro-and-ref :ensure nil
    :vc (c-intro-and-ref :url "https://github.com/jeremy-bryant/c-intro-and-ref"
           :branch "master"
           :rev :newest
           :doc "./c.texi"))

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Suhail Singh]

Jeremy Bryant <jb@jeremybryant.net> writes:

> In the meantime, I appreciate the detail and have updated the README as
> follows so that users can start easily install this Manual when writing C code
> in Emacs.

You're welcome.

> Installation instructions
>
> (package-vc-install
>  '(c-intro-and-ref :url "https://github.com/jeremy-bryant/c-intro-and-ref"
> 		   :branch "master"
> 		   :rev :newest
> 		   :doc "./c.texi"))
>
> or
>
> (use-package c-intro-and-ref :ensure nil
>     :vc (c-intro-and-ref :url "https://github.com/jeremy-bryant/c-intro-and-ref"
>            :branch "master"
>            :rev :newest
>            :doc "./c.texi"))

The above two should be equivalent, though I have not tested it.  The
latter form, which I did test, is precisely the one that does _not_
work.  Apologies in case this wasn't clear from my last message (or if I
had a typo in my explanation).

When the name specified to package-vc-install is c-intro-and-ref , the
generated info file is named c-intro-and-ref.info.  The relevant code
(in Emacs 29.4) which sets the name of the generated info file is in the
function package-vc--build-documentation :

#+begin_src emacs-lisp
  (output (expand-file-name (format "%s.info" pkg-name)))
#+end_src

This is problematic with the shipped "dir" file in the repository which
references c.info.  In order to generate c.info , one has to use the
name "c" (even though the repository as well as the phantom elisp
package are named c-intro-and-ref).

Please let me know in case this is not what you observe on your machine.

-- 
Suhail

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

We have learned that there is a general problem with the handling of
Info manuals so that the community will see they are available.
Several days ago I asked people to please help look for a general
solution for this general problem.

Packaging my GNU C Mnaual in Emacs will fix one special case of that
general problem.  But the general problem will remain.

Fixing special cases instead of general problems won't make a good
system.  Can we please try to fix this right?

-- 
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: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Jeremy Bryant]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
> We have learned that there is a general problem with the handling of
> Info manuals so that the community will see they are available.
> Several days ago I asked people to please help look for a general
> solution for this general problem.
>
> Packaging my GNU C Mnaual in Emacs will fix one special case of that
> general problem.  But the general problem will remain.
>
> Fixing special cases instead of general problems won't make a good
> system.  Can we please try to fix this right?

Ideas for discussion:

1.
Extend gnu.org:

There is a table of GNU Manuals here,
https://www.gnu.org/manual/manual.html
Many with Info documents.

If the maintainers of that site could also collate the same documents
into a location accessible programmatically, it would be easier to write
(as suggested by Stefan M), an Emacs ELPA package to download and
install these.


2.
Use NonGNU ELPA:

The Emacs packaging infrastructure already implements installation
mechanisms for Info manuals

How about using this, potentially within NonGNU ELPA rather than ELPA,
to allow an "Info area", to distribute certain Info manuals (not already
captured elsewhere).?

For example, manuals not originally written in Texinfo but converted.

This could even be a thin declaration, something like this to install
Info and HTML.

(define-manual
      ...)

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> Fixing special cases instead of general problems won't make a good
> system.  Can we please try to fix this right?

If the license of the manual would be more accessible the distribution
of the manual could proceed the regular manner.

I think making it as easy and attractive as possible to distribute info
manuals.

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

  > If the license of the manual would be more accessible the distribution
  > of the manual could proceed the regular manner.

Sorry, I don't follow you.  I don't see what it could mean
to decrine a license as "more accesible" or "less accessible."

There is nothing preventing the distribution of our manuals.

-- 
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: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > If the license of the manual would be more accessible the distribution
>   > of the manual could proceed the regular manner.
>
> Sorry, I don't follow you.  I don't see what it could mean
> to decrine a license as "more accesible" or "less accessible."
>
> There is nothing preventing the distribution of our manuals.

Sure their is depending on your POV. Their have been multiple arguments
of the GFDPL not being free (enough).

Some distribution but freedom before convenience. 

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Dr. Arne Babenhauserheide]

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

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Richard Stallman <rms@gnu.org> writes:
>
>> [[[ 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. ]]]
>>
>>   > If the license of the manual would be more accessible the distribution
>>   > of the manual could proceed the regular manner.
>>
>> Sorry, I don't follow you.  I don't see what it could mean
>> to decrine a license as "more accesible" or "less accessible."
>>
>> There is nothing preventing the distribution of our manuals.
>
> Sure their is depending on your POV. Their have been multiple arguments
> of the GFDPL not being free (enough).

Let’s speak frankly: Debian wants manuals distributed under licenses
that provide the same freedoms as free software licenses — the most
well-known of these is creative commons attribution sharealike.
https://creativecommons.org/licenses/by-sa/3.0/

But this is a discussion that can quickly turn sour within the GNU
project. I’m not happy about that, just pointing it out that it is a
path that may seem easier, but isn’t (because social issues usually
aren’t easier but much gnarlier to fix than technical ones).

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: [ELPA] New package c-intro-and-ref -- was Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: Richard Stallman <rms@gnu.org>,  suhailsingh247@gmail.com,
>   eliz@gnu.org,  emacs-devel@gnu.org
> Date: Sat, 14 Dec 2024 22:19:54 +0100
> 
> Björn Bidar <bjorn.bidar@thaodan.de> writes:
> 
> > Richard Stallman <rms@gnu.org> writes:
> >
> >>   > If the license of the manual would be more accessible the distribution
> >>   > of the manual could proceed the regular manner.
> >>
> >> Sorry, I don't follow you.  I don't see what it could mean
> >> to decrine a license as "more accesible" or "less accessible."
> >>
> >> There is nothing preventing the distribution of our manuals.
> >
> > Sure their is depending on your POV. Their have been multiple arguments
> > of the GFDPL not being free (enough).
> 
> Let’s speak frankly: Debian wants manuals distributed under licenses
> that provide the same freedoms as free software licenses — the most
> well-known of these is creative commons attribution sharealike.
> https://creativecommons.org/licenses/by-sa/3.0/
> 
> But this is a discussion that can quickly turn sour within the GNU
> project. I’m not happy about that, just pointing it out that it is a
> path that may seem easier, but isn’t (because social issues usually
> aren’t easier but much gnarlier to fix than technical ones).

Could you guys please move this off-topic discussion to a more
appropriate place?  Like the Texinfo mailing list or a Debian forum?
Or even emacs-tangents@gnu.org?  Discussing GNU manuals, let alone the
Debian philosophy of distributing manuals, is waaaay off-topic here.
We have enough of our own noise here, thank you.

Please don't post in this and related threads here anymore.  Enough is
enough.

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

  > > As a general design principle, it doesn't seem to make sense to
  > > include all GNU manuals in the Emacs distribution merely because they
  > > are useful manuals.  The idea was to relese them separately and have
  > > them installed separately into a combined info tree.
  > > 
  > > Why is that not working?  What needs to be changed in some GNU/Linux
  > > distros?

  > It does work in general.  However, some manuals, which don't belong to
  > any project in particular, are largely unknown to exist.

Have you got any ideas for the good ways to inform the community about them?

                                                              The two
  > prominent examples I have are for some reason both related to the C
  > language: gnu-c-manual.info and c.info.  The latter is not even
  > mentioned in dir-example file that the Texinfo project distributes.

What is c.info?  I don't recall hearing about it.

-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: jb@jeremybryant.net, emacs-devel@gnu.org
> Date: Thu, 05 Dec 2024 00:05:13 -0500
> 
>   > > As a general design principle, it doesn't seem to make sense to
>   > > include all GNU manuals in the Emacs distribution merely because they
>   > > are useful manuals.  The idea was to relese them separately and have
>   > > them installed separately into a combined info tree.
>   > > 
>   > > Why is that not working?  What needs to be changed in some GNU/Linux
>   > > distros?
> 
>   > It does work in general.  However, some manuals, which don't belong to
>   > any project in particular, are largely unknown to exist.
> 
> Have you got any ideas for the good ways to inform the community about them?

Not immediately, no.  I suggest to discuss that with the Texinfo
developers, since they distribute some files that are supposed to
reference all the GNU manuals in existence.

>                                                               The two
>   > prominent examples I have are for some reason both related to the C
>   > language: gnu-c-manual.info and c.info.  The latter is not even
>   > mentioned in dir-example file that the Texinfo project distributes.
> 
> What is c.info?  I don't recall hearing about it.

It's your "Introduction to the C language" manual.

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > FWIW, I don't think this (IMO very useful and installed on my
>   > machines) manual belongs to Emacs.  It should be a separate manual.
>
> As a general design principle, it doesn't seem to make sense to
> include all GNU manuals in the Emacs distribution merely because they
> are useful manuals.  The idea was to relese them separately and have
> them installed separately into a combined info tree.
>
> Why is that not working?  What needs to be changed in some GNU/Linux
> distros?

The issues the others mentioned mainly the lack of acceptance of the
format and for sometime the possibility to find info manual manly due
the first problem.

Some projects switched to documentation systems which don't provide
anything but HTML or PDF such as e.g. Doxygen or those where the info
output is available but fragile and usually not enabled due problem one.

In the instance of the this specific manual it's just that it's one
specific document which isn't distributed along other software which is
unusual but also that it doesn't get much exposure I think.

The last issue is that the license make it impossible to be distributed
for some namely those which are Debian based but not solely those.

Related: I package the manual for RPM based distribution below:
https://build.opensuse.org/package/show/home:Thaodan:Documentation/c-intro-and-ref

I will submit the manual to openSUSE unless some other issue comes up.

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Björn Bidar]

I submitted the manual now to the openSUSE Documentation project.
After it can be installed through the package manager and then used in
Emacs:
https://build.opensuse.org/requests/1229051

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

[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 issues the others mentioned mainly the lack of acceptance of the
  > format

"Lack of acceptance" is a broad term.  It can manifest in various
ways, and for this purpose, it matters which way.

           and for sometime the possibility to find info manual manly due
  > the first problem.

What does "the first problem" refer to?  It sounds like a reference to
something before this paragraph, but thee was no text from you before
that.

  > Some projects switched to documentation systems which don't provide
  > anything but HTML or PDF such as e.g. Doxygen or those where the info
  > output is available but fragile and usually not enabled due problem one.

This will have reduced the range of manuals available in Info format
and thus harmed the success of Info format.  But I don't see how it relates
to the difficulty getting the basic Info support ncluded in the distro.

  > In the instance of the this specific manual it's just that it's one
  > specific document which isn't distributed along other software which is
  > unusual but also that it doesn't get much exposure I think.

Should we recruit people to package it for various kinds of distros?

  > The last issue is that the license make it impossible to be distributed
  > for some namely those which are Debian based but not solely those.

We could pubish a .deb made from the manual, for distros less rigid
than Debian to include.  Should we do that?

  > Related: I package the manual for RPM based distribution below:
  > https://build.opensuse.org/package/show/home:Thaodan:Documentation/c-intro-and-ref

Would you like to distribute that package via gnu.org?
I'd rather point to it there than on opensuse.org.



-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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 issues the others mentioned mainly the lack of acceptance of the
>   > format
>
> "Lack of acceptance" is a broad term.  It can manifest in various
> ways, and for this purpose, it matters which way.
>
>            and for sometime the possibility to find info manual manly due
>   > the first problem.
>
> What does "the first problem" refer to?  It sounds like a reference to
> something before this paragraph, but thee was no text from you before
> that.

If I want to read manual in Emacs outside of smaller man-pages or
projects which split their manual of several man-pages than I would
prefer to find them in the Info format.  
Because of the limited acceptance finding manuals in the info format is hard.

>
>   > Some projects switched to documentation systems which don't provide
>   > anything but HTML or PDF such as e.g. Doxygen or those where the info
>   > output is available but fragile and usually not enabled due problem one.
>
> This will have reduced the range of manuals available in Info format
> and thus harmed the success of Info format.  But I don't see how it relates
> to the difficulty getting the basic Info support ncluded in the distro.
>
>   > In the instance of the this specific manual it's just that it's one
>   > specific document which isn't distributed along other software which is
>   > unusual but also that it doesn't get much exposure I think.
>
> Should we recruit people to package it for various kinds of distros?

Just make packaging easy. Packaging manuals is quite easy as long
as all the legal requirements are met. Outside of that there are already
methods for installing methods from other sources if necessary. 

>
>   > The last issue is that the license make it impossible to be distributed
>   > for some namely those which are Debian based but not solely those.
>
> We could pubish a .deb made from the manual, for distros less rigid
> than Debian to include.  Should we do that?

It could help but fixing some of the issues Debian mentioned would be
another, IMHO better way. Just printing out the manual is impractical
with it's current manual to e.g. use it for education as you would have
to print out the full license each time. Multiply that per student
handed a page in the manual and it gets expensive fast.

Debian is only rigid on the freedom of their users, just like Gnu is.
It all depends on your lens.

>
>   > Related: I package the manual for RPM based distribution below:
>   > https://build.opensuse.org/package/show/home:Thaodan:Documentation/c-intro-and-ref
>
> Would you like to distribute that package via gnu.org?
> I'd rather point to it there than on opensuse.org.

The package would be included in the distributions package manager just
like Emacs is already. If it is on gnu.org it would require the user to
add the repository to the package manager first.

Besides I think openSUSE can be trusted and the Open BuildService is
great software for this kind of purpose.
But nothing stops Gnu from creating their own OBS instance for their
packages to be build.

Improve access to documentation in Info format (was: Proposal: Include C Manual from RMS in Emacs git, and/or release)

[Suhail Singh]

Richard Stallman <rms@gnu.org> writes:

> Should we recruit people to package it for various kinds of distros?

While I am unable to volunteer time for this, I can nevertheless point
out two constructive steps that could be taken that would improve
matters for users.  In no particular order:

1. Providing an "easy" way for users to see available info manuals and
   install them.  Easiness here is defined in terms of number of
   invocations (either in Bash or within Emacs) that are necessary for
   users to either view the list of available manuals or to install some
   of them.  This could be done by spending development effort to
   provide packages for various distributions.  Alternatively, effort
   could perhaps be better utilized by packaging the existing info
   manuals into a (relatively) distribution-agnostic packaging system
   such as, say, Guix or GNU ELPA or NonGNU ELPA.
2. Make it easier to generate and perhaps also provide, via 1, Info
   manuals for packages that use other documentation generation systems.
   A popular candidate to target in this regard is Sphinx.  Sphinx has
   some existing support, IIUC, to generate Texinfo output.  However,
   that generation can, at times, have warts/bugs.  My understanding is
   that resolution of these bugs isn't prioritized by the existing
   Sphinx community.  It is possible that they simply aren't aware of
   these issues.  Investing effort into reporting and resolving such
   issues to improve Sphinx's support for output in Texinfo format would
   help.

-- 
Suhail

Re: Improve access to documentation in Info format (was: Proposal: Include C Manual from RMS in Emacs git, and/or release)

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

  > 1. Providing an "easy" way for users to see available info manuals and
  >    install them.

I think we should be able to do this.  The way I see is involves two
steps:

a, Set up some sort of download repo with all the Info manuals.

b. Write software to find the desired manual, fetch it, and install it
on your computer.

Would people like tp vplunteer to work on this?

  > 2. Make it easier to generate and perhaps also provide, via 1, Info
  >    manuals for packages that use other documentation generation systems.
  >    A popular candidate to target in this regard is Sphinx.  Sphinx has
  >    some existing support, IIUC, to generate Texinfo output.

In principle I think this is a good idea, but there is a technical
difficulty: it is impossible to produce a fully correct Info manual
from those other formats. because those other formats do not make
the necessary distincions.

It would not be terribly hard to write software which would do this
job _as well as could be done given the current formats_, but the
results will be visibly wrong.

What would be terribly hard is to do a better job than that.


-- 
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: Improve access to documentation in Info format

[Suhail Singh]

Richard Stallman <rms@gnu.org> writes:

> a technical difficulty: it is impossible to produce a fully correct
> Info manual from those other formats. because those other formats do
> not make the necessary distincions.
>
> It would not be terribly hard to write software which would do this
> job _as well as could be done given the current formats_, but the
> results will be visibly wrong.

Could you comment on the user-facing features that would no longer work
with such "visibly wrong" translated-from-other-formats Info manuals?
I.e., what would be the user-observable breakage if one were to, say,
convert sphinx-generated documentation into Info format?

Whether it would still be useful to do this would depend on how severely
broken the resulting Info format is.

-- 
Suhail

Re: Improve access to documentation in Info format

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> [[[ 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. ]]]
>
>   > 1. Providing an "easy" way for users to see available info manuals and
>   >    install them.
>
> I think we should be able to do this.  The way I see is involves two
> steps:
>
> a, Set up some sort of download repo with all the Info manuals.
>
> b. Write software to find the desired manual, fetch it, and install it
> on your computer.

That's the users package manager in almost all the cases. If not the
solutions mentioned by Suhail Singh are an option.

Writing a new software for this isn't a good idea IMHO.

Writing build scrits/descriptions for all the possible package managers
we could face should be much easier.

I wouldn't do this for ALL info manuals but only for those where are
no packages for. For those where a conversion to Texinfo is done
e.g. Sphinx like for example when packaging CMake it easier to add the
info manual packaging to existing packaging.

Add that is a very minor change and could be done by users interested
into having these info manuals with little amount of time.
Guix is a good place for examples of these efforts.

> Would people like tp vplunteer to work on this?
>
>   > 2. Make it easier to generate and perhaps also provide, via 1, Info
>   >    manuals for packages that use other documentation generation systems.
>   >    A popular candidate to target in this regard is Sphinx.  Sphinx has
>   >    some existing support, IIUC, to generate Texinfo output.
>
> In principle I think this is a good idea, but there is a technical
> difficulty: it is impossible to produce a fully correct Info manual
> from those other formats. because those other formats do not make
> the necessary distincions.

Info being the minority in this instance would be in the position
to improve the output of these engines.

It would be best to approach this diplomatic.

> It would not be terribly hard to write software which would do this
> job _as well as could be done given the current formats_, but the
> results will be visibly wrong.
>
> What would be terribly hard is to do a better job than that.

Re: Improve access to documentation in Info format

[Dr. Arne Babenhauserheide]

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

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> e.g. Sphinx like for example when packaging CMake it easier to add the
> info manual packaging to existing packaging.
>
> Add that is a very minor change and could be done by users interested
> into having these info manuals with little amount of time.
> Guix is a good place for examples of these efforts.

This is project effort I’d love to see.

It may look far less glamorous than building a user-repo of all info
manuals for every package, but I think it will have far bigger impact.

Also I think that it will actually bring a lot more buy-in by existing
projects, because they then have the added value of a further
documentation format. Reaching more audiences more easily, and being
shown in the local info directory listing.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

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

Re: Proposal: Include C Manual from RMS in Emacs git, and/or release

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

  > If I want to read manual in Emacs outside of smaller man-pages or
  > projects which split their manual of several man-pages than I would
  > prefer to find them in the Info format.  

I appreciate the wish for that.  I wish more Info manuals came in
my distro, and that installing a program would install its Info file.

  > Because of the limited acceptance finding manuals in the info format is hard.

"Hard" is an oversomplification of several related obstacles.  To
iprove this in general, we need to find the way that is effective in
general.

  > > Should we recruit people to package it for various kinds of distros?

  > Just make packaging easy.

Can you (or someone else) suggest specific changes to make specific
kinds of packaging easier?

  > Besides I think openSUSE can be trusted and the Open BuildService is
  > great software for this kind of purpose.

I don't usee that distro.  Would you like to give me a brief summary
of what it does?  What input does it need, and what output does it make?

What instructions are neededs to tell it how to package a specific manual?
How would it compare with usin writing and using a makefile to do that?


-- 
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: Proposal: Include C Manual from RMS in Emacs git, and/or release

[John ff]

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



⁣​

On 30 Nov 2024, 12:58, at 12:58, Jeremy Bryant <jb@jeremybryant.net> wrote:
>Dear RMS and other maintainers,
>
>The C manual at
>https://savannah.gnu.org/projects/c-intro-and-ref/
>
>1.
>could be a useful guide to include within the Emacs tree under doc/
>2.
>It could possibly be part of the release tarball given the usefulness
>of
>Emacs for C programmers?
>3.
>Or ELPA?

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