unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Info Pages for ELPA  packages
@ 2014-05-25  0:01 T. V. Raman
  2014-05-25  1:41 ` Glenn Morris
  2014-05-25 22:05 ` Mario Lang
  0 siblings, 2 replies; 16+ messages in thread
From: T. V. Raman @ 2014-05-25  0:01 UTC (permalink / raw)
  To: emacs-devel

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? 



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-25  0:01 Info Pages for ELPA packages T. V. Raman
@ 2014-05-25  1:41 ` Glenn Morris
  2014-05-25 22:05 ` Mario Lang
  1 sibling, 0 replies; 16+ messages in thread
From: Glenn Morris @ 2014-05-25  1:41 UTC (permalink / raw)
  To: raman; +Cc: Emacs developers


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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-25  0:01 Info Pages for ELPA packages T. V. Raman
  2014-05-25  1:41 ` Glenn Morris
@ 2014-05-25 22:05 ` Mario Lang
  2014-05-26  4:37   ` raman
  1 sibling, 1 reply; 16+ messages in thread
From: Mario Lang @ 2014-05-25 22:05 UTC (permalink / raw)
  To: T. V. Raman; +Cc: tv.raman.tv, emacs-devel

"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,
  ⡍⠁⠗⠊⠕



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-25 22:05 ` Mario Lang
@ 2014-05-26  4:37   ` raman
  2014-05-26 17:54     ` Stefan Monnier
  0 siblings, 1 reply; 16+ messages in thread
From: raman @ 2014-05-26  4:37 UTC (permalink / raw)
  To: emacs-devel; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-26  4:37   ` raman
@ 2014-05-26 17:54     ` Stefan Monnier
  2014-05-26 22:38       ` T.V Raman
                         ` (2 more replies)
  0 siblings, 3 replies; 16+ messages in thread
From: Stefan Monnier @ 2014-05-26 17:54 UTC (permalink / raw)
  To: raman; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-26 17:54     ` Stefan Monnier
@ 2014-05-26 22:38       ` T.V Raman
  2014-05-27  2:40       ` Eric Abrahamsen
  2014-05-27 10:06       ` Mario Lang
  2 siblings, 0 replies; 16+ messages in thread
From: T.V Raman @ 2014-05-26 22:38 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-26 17:54     ` Stefan Monnier
  2014-05-26 22:38       ` T.V Raman
@ 2014-05-27  2:40       ` Eric Abrahamsen
  2014-05-27  2:47         ` raman
  2014-05-27  3:26         ` Stefan Monnier
  2014-05-27 10:06       ` Mario Lang
  2 siblings, 2 replies; 16+ messages in thread
From: Eric Abrahamsen @ 2014-05-27  2:40 UTC (permalink / raw)
  To: emacs-devel

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




^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27  2:40       ` Eric Abrahamsen
@ 2014-05-27  2:47         ` raman
  2014-05-27  3:25           ` Stefan Monnier
  2014-05-27  3:26         ` Stefan Monnier
  1 sibling, 1 reply; 16+ messages in thread
From: raman @ 2014-05-27  2:47 UTC (permalink / raw)
  To: Eric Abrahamsen; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27  2:47         ` raman
@ 2014-05-27  3:25           ` Stefan Monnier
  2014-05-27 15:23             ` T.V Raman
  0 siblings, 1 reply; 16+ messages in thread
From: Stefan Monnier @ 2014-05-27  3:25 UTC (permalink / raw)
  To: raman; +Cc: Eric Abrahamsen, emacs-devel

> 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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27  2:40       ` Eric Abrahamsen
  2014-05-27  2:47         ` raman
@ 2014-05-27  3:26         ` Stefan Monnier
  2014-05-27  4:43           ` Eric Abrahamsen
  1 sibling, 1 reply; 16+ messages in thread
From: Stefan Monnier @ 2014-05-27  3:26 UTC (permalink / raw)
  To: Eric Abrahamsen; +Cc: emacs-devel

> 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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27  3:26         ` Stefan Monnier
@ 2014-05-27  4:43           ` Eric Abrahamsen
  0 siblings, 0 replies; 16+ messages in thread
From: Eric Abrahamsen @ 2014-05-27  4:43 UTC (permalink / raw)
  To: emacs-devel

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




^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-26 17:54     ` Stefan Monnier
  2014-05-26 22:38       ` T.V Raman
  2014-05-27  2:40       ` Eric Abrahamsen
@ 2014-05-27 10:06       ` Mario Lang
  2014-05-27 11:50         ` Michael Albinus
  2 siblings, 1 reply; 16+ messages in thread
From: Mario Lang @ 2014-05-27 10:06 UTC (permalink / raw)
  To: emacs-devel

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27 10:06       ` Mario Lang
@ 2014-05-27 11:50         ` Michael Albinus
  0 siblings, 0 replies; 16+ messages in thread
From: Michael Albinus @ 2014-05-27 11:50 UTC (permalink / raw)
  To: Mario Lang; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27  3:25           ` Stefan Monnier
@ 2014-05-27 15:23             ` T.V Raman
  2014-05-27 16:03               ` Stephen J. Turnbull
  2014-05-27 19:49               ` Stefan Monnier
  0 siblings, 2 replies; 16+ messages in thread
From: T.V Raman @ 2014-05-27 15:23 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Eric Abrahamsen, emacs-devel

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



^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27 15:23             ` T.V Raman
@ 2014-05-27 16:03               ` Stephen J. Turnbull
  2014-05-27 19:49               ` Stefan Monnier
  1 sibling, 0 replies; 16+ messages in thread
From: Stephen J. Turnbull @ 2014-05-27 16:03 UTC (permalink / raw)
  To: T.V Raman; +Cc: Eric Abrahamsen, Stefan Monnier, emacs-devel

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




^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: Info Pages for ELPA  packages
  2014-05-27 15:23             ` T.V Raman
  2014-05-27 16:03               ` Stephen J. Turnbull
@ 2014-05-27 19:49               ` Stefan Monnier
  1 sibling, 0 replies; 16+ messages in thread
From: Stefan Monnier @ 2014-05-27 19:49 UTC (permalink / raw)
  To: T.V Raman; +Cc: Eric Abrahamsen, emacs-devel

> 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



^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2014-05-27 19:49 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-05-25  0:01 Info Pages for ELPA packages T. V. Raman
2014-05-25  1:41 ` Glenn Morris
2014-05-25 22:05 ` Mario Lang
2014-05-26  4:37   ` raman
2014-05-26 17:54     ` Stefan Monnier
2014-05-26 22:38       ` T.V Raman
2014-05-27  2:40       ` Eric Abrahamsen
2014-05-27  2:47         ` raman
2014-05-27  3:25           ` Stefan Monnier
2014-05-27 15:23             ` T.V Raman
2014-05-27 16:03               ` Stephen J. Turnbull
2014-05-27 19:49               ` Stefan Monnier
2014-05-27  3:26         ` Stefan Monnier
2014-05-27  4:43           ` Eric Abrahamsen
2014-05-27 10:06       ` Mario Lang
2014-05-27 11:50         ` Michael Albinus

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).