Info Pages for ELPA packages

Info Pages for ELPA packages

[T. V. Raman]

I've noticed myself installing elpa packages, then pulling their
sources   from some git repo purely to get at the package's info
files or other documentation. Can we have  some  affordance in
elpa that allows packages to have info docs or documentation of
some sort alongside elpa? 

Re: Info Pages for ELPA packages

[Glenn Morris]

package.el already provides a mechanism for that.
It's up to package authors to make use of it.

Re: Info Pages for ELPA packages

[Mario Lang]

"T. V. Raman" <raman@google.com> writes:

> I've noticed myself installing elpa packages, then pulling their
> sources   from some git repo purely to get at the package's info
> files or other documentation. Can we have  some  affordance in
> elpa that allows packages to have info docs or documentation of
> some sort alongside elpa? 

We have that already.  Just place a package-name.info and a "dir" file
in the same directory as package-name.el.  It will automatically be
picked up on package installation.  Documented in a paragraph of the
"Multi-file package" section in the elisp info manual.

-- 
CYa,
  ⡍⠁⠗⠊⠕

Re: Info Pages for ELPA packages

[raman]

I'm not the one who needs that lesson, I was merely observing that on
elpa,  packages are consistent with respect to not including any info
documentation -- and traditionally that has been a strength of packages
in emacs.

Re: Info Pages for ELPA packages

[Stefan Monnier]

The situation w.r.t to documentation of ELPA packages indeed could be
improved at various stages:
- Many packages don't have much documentation.  That's also true of many
  Elisp packages bundled with Emacs, but it's probably more true of
  ELPA packages.  We could encourage people to provide docs, but that
  problem seems different from the one you raise.
- Some have documentation but it's not made easily accessible to
  the user.  This is because the GNU ELPA infrastructure is fairly
  limited in this respect:
  - package.el only knows how to use an Info doc and only if the package
    comes with a "dir" file.
  - the GNU ELPA scripts don't know how to build Info files nor "dir" files.

So improving the GNU ELPA scripts to generate the Info and "dir" files
would probably be a good first step.  If you have specific packages
which included docs in the Git repo but no Info&dir files, please send
them along, they'll be helpful to try and figure out how those scripts
could/should work.


        Stefan

Re: Info Pages for ELPA packages

[T.V Raman]

Stefan -- Yes, I was primarily refering to the latter.
I'll make a mental note to myself  to send along a note the next time I
find myself pulling down a git repo purely for the documentation.
-- 

Re: Info Pages for ELPA packages

[Eric Abrahamsen]

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

> The situation w.r.t to documentation of ELPA packages indeed could be
> improved at various stages:
> - Many packages don't have much documentation.  That's also true of many
>   Elisp packages bundled with Emacs, but it's probably more true of
>   ELPA packages.  We could encourage people to provide docs, but that
>   problem seems different from the one you raise.
> - Some have documentation but it's not made easily accessible to
>   the user.  This is because the GNU ELPA infrastructure is fairly
>   limited in this respect:
>   - package.el only knows how to use an Info doc and only if the package
>     comes with a "dir" file.
>   - the GNU ELPA scripts don't know how to build Info files nor "dir" files.
>
> So improving the GNU ELPA scripts to generate the Info and "dir" files
> would probably be a good first step.  If you have specific packages
> which included docs in the Git repo but no Info&dir files, please send
> them along, they'll be helpful to try and figure out how those scripts
> could/should work.

I think it would be *really* helpful to ask that developers write README
files, even if they can't be bothered to write a full Info manual. Being
able to hit "?" in the *Packages* buffer and get a description of a
package *before* you install it is invaluable. Half the time you can
barely tell what a package does from the description, nor do you know
the most basic invocation for getting it up and running. I'd almost
think a README should be a requirement...

2¢

Eric

Re: Info Pages for ELPA packages

[raman]

Of the many, many packages  I  have from elpa -- 

auctex includes both .texi and .info files; magit includes only .info
files.
For an example of a package that has emms info documentation in its
distribution -- but not  when obtained via elpa, see package emms.

Re: Info Pages for ELPA packages

[Stefan Monnier]

> For an example of a package that has emms info documentation in its
> distribution -- but not  when obtained via elpa, see package emms.

But emms is not in GNU ELPA, so it's largely outside of our control.


        Stefan

Re: Info Pages for ELPA packages

[Stefan Monnier]

> Being able to hit "?" in the *Packages* buffer and get a description
> of a package *before* you install it is invaluable.

Agreed.  If a GNU ELPA package doesn't include that info, do M-x
report-emacs-bug for it.


        Stefan

Re: Info Pages for ELPA packages

[Eric Abrahamsen]

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

>> Being able to hit "?" in the *Packages* buffer and get a description
>> of a package *before* you install it is invaluable.
>
> Agreed.  If a GNU ELPA package doesn't include that info, do M-x
> report-emacs-bug for it.

Will do

Re: Info Pages for ELPA packages

[Mario Lang]

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

> So improving the GNU ELPA scripts to generate the Info and "dir" files
> would probably be a good first step.  If you have specific packages
> which included docs in the Git repo but no Info&dir files, please send
> them along, they'll be helpful to try and figure out how those scripts
> could/should work.

packages/debbugs comes to mind, which has debbugs.texi but no .info.

packages/enwc also has a texi file but no info/dir, but the texi looks
rather short/incomplete.

packages/dismal also has a dismal-manual.texi (the name probably needs
changing) but no .info/dir files.

-- 
CYa,
  ⡍⠁⠗⠊⠕ | Debian Developer <URL:http://debian.org/>
  .''`. | Get my public key via finger mlang/key@db.debian.org
 : :' : | 1024D/7FC1A0854909BCCDBE6C102DDFFC022A6B113E44
 `. `'
   `-      <URL:http://delysid.org/>  <URL:http://www.staff.tugraz.at/mlang/>

Re: Info Pages for ELPA packages

[Michael Albinus]

Mario Lang <mlang@delysid.org> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> So improving the GNU ELPA scripts to generate the Info and "dir" files
>> would probably be a good first step.  If you have specific packages
>> which included docs in the Git repo but no Info&dir files, please send
>> them along, they'll be helpful to try and figure out how those scripts
>> could/should work.
>
> packages/debbugs comes to mind, which has debbugs.texi but no .info.

For the records, debbugs.texi deserves a major update. It's on my todo,
but my crystal ball is not so good in recognizing future events. So I
don't know when it will happen.

Best regards, Michael.

Re: Info Pages for ELPA packages

[T.V Raman]

Agreed that that package is in some sense outside our control. But it
demonstrates the problem  -- as you can see from the auctex package,
it's possible to include the info pages, but not easily.  Part of this
is perhaps the directory layout of elpa installations -- there seems to
be place for nothing but the elisp files at first glance ie each package
has to maintain a subdirectory structure of its own 

One simple first step might be to say that .el files of package foo
should go into elpa/foo/lisp -- and  then mandate that foo should also
have subdirs texi and info -- for texinfo sources and built info pages
respectively.  This will also open up space for then mandating foo/etc
foo/src etc over time.
-- 

Re: Info Pages for ELPA packages

[Stephen J. Turnbull]

T.V Raman writes:

 > there seems to be place for nothing but the elisp files at first
 > glance ie each package has to maintain a subdirectory structure of
 > its own

I hope you guys can find a good solution, but what XEmacs discovered
in trying to handle this problem in its package system is that there
are just too many ways of doing it in the real packages out there, and
we ended up with a horrible set of make variables to point the package
system to where various items live in the source tree for a package
(various data files are even worse, I think we have about 26
DATA_DIR_## make variables).

On the other hand, the system does work even if the internals are
klunky, and the installed tree is very regular.  (David K, don't
bother pointing out that it's suboptimal, I'm not suggesting that ELPA
emulate the XEmacs package system!)

Re: Info Pages for ELPA packages

[Stefan Monnier]

> is perhaps the directory layout of elpa installations -- there seems to
> be place for nothing but the elisp files at first glance ie each package
> has to maintain a subdirectory structure of its own

The directory layout expected from elpa packages is "everything at
top-level".  Which works great for simple packages.

> One simple first step might be to say that .el files of package foo
> should go into elpa/foo/lisp -- and  then mandate that foo should also
> have subdirs texi and info -- for texinfo sources and built info pages
> respectively.  This will also open up space for then mandating foo/etc
> foo/src etc over time.

There are too many options, so the way forward is not to impose
a structure, nor to try and provide support for the various structures
that make sense (because that would be too unwieldy).  Instead,
package.el should do less, letting the package do the work whichever way
it likes, instead.


        Stefan