Re: GNU ELPA visibility

Re: GNU ELPA visibility

[Dmitry Gutov]

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

 >>> I.e. we need to replace the READMEs with more structured files which
 >>> can be easily turned into acceptable HTML (no need to be fancy, here)
 >>> as well as easy to render acceptably in Emacs (extra bonus points if
 >>> that same format can end up being used as a replacement for Info ;-).
 >> Org can be exported to HTML, Plain text (ASCII) and texi.
 >
 > So far, Org, ReST, Markdown, and Texinfo sound like the best
 > options, indeed.

I think you might as well support several formats, to cover the existing
README files.

That would complicate showing these files in the package.el interface in
a fancy way, but I think that's a reasonable tradeoff.
At least two of the above formats look quite reasonably in plain text.

Re: GNU ELPA visibility

[Dmitry Gutov]

Daniel Hackney <dan@haxney.org> writes:

 > Dmitry Gutov wrote:
 >> Tassilo Horn <address@hidden> writes:
 >> > It would be good if every package would at least complement 
Version and
 >> > Summary with a longer description, a link to its homepage (or 
emacswiki
 >> > page if it has no homepage), and the date when it was updated the last
 >> > time.
 >>
 >> You may find that, for single-file packages, even if they provide an
 >> extended "Commentary" section, it will not show up in the
 >> "list-packages" interface. At least when distributed over MELPA or
 >> Marmalade.
 >
 > The problem is with those repos. They don't create a
 > <pkg-name>-readme.txt file. It's particularly strange for Marmalade,
 > since the content which would go into the readme is displayed on the
 > website (though not in <pre> formatting) but isn't available through
 > `list-packages'.

Indeed. And there's been an issue filed on Marmalade's bug tracker for
close to a year now (#36).

I think I will take a stab at fixing this for MELPA.

 >> I think it's fixed in Daniel Haxney's package.el fork, though.
 >
 > Sorry for the confusion (my choice of domain could be clearer), but my
 > last name is "Hackney", not "Haxney". The domain name "haxney.org" is a
 > play on "hacks" => "hax" (sometimes used in videogame-speak) and
 > "Hackney". Also, the username "haxney" is available on every service I
 > have ever come across.

That's my fault, sorry.

 > I was careful not to make any changes to the HTTP and file-based APIs in
 > my branch, so if a repo doesn't provide a readme, then my branch can't
 > do anything about that.

Sorry again, duh.

--Dmitry

Re: GNU ELPA visibility

[Daniel Hackney]

(I just joined the list, so I can't reply with the original message-id.
This is a response to
https://lists.gnu.org/archive/html/emacs-devel/2012-10/msg00723.html)

Dmitry Gutov wrote:
> Tassilo Horn <address@hidden> writes:
> > It would be good if every package would at least complement Version and
> > Summary with a longer description, a link to its homepage (or emacswiki
> > page if it has no homepage), and the date when it was updated the last
> > time.
>
> You may find that, for single-file packages, even if they provide an
> extended "Commentary" section, it will not show up in the
> "list-packages" interface. At least when distributed over MELPA or
> Marmalade.

The problem is with those repos. They don't create a
<pkg-name>-readme.txt file. It's particularly strange for Marmalade,
since the content which would go into the readme is displayed on the
website (though not in <pre> formatting) but isn't available through
`list-packages'.

> I think it's fixed in Daniel Haxney's package.el fork, though.

Sorry for the confusion (my choice of domain could be clearer), but my
last name is "Hackney", not "Haxney". The domain name "haxney.org" is a
play on "hacks" => "hax" (sometimes used in videogame-speak) and
"Hackney". Also, the username "haxney" is available on every service I
have ever come across.

I was careful not to make any changes to the HTTP and file-based APIs in
my branch, so if a repo doesn't provide a readme, then my branch can't
do anything about that.

--
Daniel Hackney

Re: GNU ELPA visibility

[Eli Zaretskii]

> From: Daniel Hackney <dan@haxney.org>
> Date: Sun, 28 Oct 2012 12:29:09 -0400
> 
> (I just joined the list, so I can't reply with the original message-id.

Yes, you can, if you download the list archive in mbox format.  Just
so you know for the future.

Re: GNU ELPA visibility

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Daniel Hackney <dan@haxney.org>
>> Date: Sun, 28 Oct 2012 12:29:09 -0400
>> 
>> (I just joined the list, so I can't reply with the original message-id.
>
> Yes, you can, if you download the list archive in mbox format.

You can also reply via gmane.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: GNU ELPA visibility

[Dmitry Gutov]

Tassilo Horn <tsdh@gnu.org> writes:

 > Jeremiah Dodds <jeremiah.dodds@gmail.com> writes:
 >
 >>> When looking for an Elisp package or feature, most people reach for
 >>> their browser before reaching for M-x list-packages.  But packages
 >>> distributed via GNU ELPA won't show up because they're not visible to
 >>> search engines.
 >>
 >> I think it's very likely that M-x list-packages will get much more
 >> common as time progresses. It's certainly the first thing that I go to
 >> nowadays.
 >
 > Ditto, but the package explanations given there are far from informative
 > enough to find the package you need for your task at hand.  I look there
 > first, but then google up the packages that sound relevant, and in the
 > end that almost always leads to emacswiki.
 >
 > It would be good if every package would at least complement Version and
 > Summary with a longer description, a link to its homepage (or emacswiki
 > page if it has no homepage), and the date when it was updated the last
 > time.

You may find that, for single-file packages, even if they provide an
extended "Commentary" section, it will not show up in the
"list-packages" interface. At least when distributed over MELPA or
Marmalade.

I think it's fixed in Daniel Haxney's package.el fork, though.

Showing a link to the homepage (taken from the "URL" header) would be a
welcome addition to the interface, too.

--Dmitry

Re: GNU ELPA visibility

[Stefan Monnier]

> I think it's fixed in Daniel Haxney's package.el fork, though.

I hope it's not a real fork,


        Stefan

Re: GNU ELPA visibility

[chad]

On 26 Oct 2012, at 11:31, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> I think it's fixed in Daniel Haxney's package.el fork, though.
> 
> I hope it's not a real fork,

He was trying to get parts of it merged before the feature-freeze, so I doubt it's a lasting fork, but it might be a fork as far as 24.3 is concerned.

	https://lists.gnu.org/archive/html/emacs-devel/2012-10/msg00237.html

~Chad

Re: GNU ELPA visibility

[Stefan Monnier]

>>> I think it's fixed in Daniel Haxney's package.el fork, though.
>> I hope it's not a real fork,
> He was trying to get parts of it merged before the feature-freeze, so
> I doubt it's a lasting fork, but it might be a fork as far as 24.3
> is concerned.

Oh, right, sorry for that.  Now if I could only remember my name.


        Stefan

Re: GNU ELPA visibility

[Chong Yidong]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> It would be good if every package would at least complement Version and
>> Summary with a longer description, a link to its homepage (or emacswiki
>> page if it has no homepage), and the date when it was updated the last
>> time.
>
> You may find that, for single-file packages, even if they provide an
> extended "Commentary" section, it will not show up in the
> "list-packages" interface. At least when distributed over MELPA or
> Marmalade.

Please provide an example of what you mean.  I just checked with the GNU
ELPA packages, and the commentaries show up fine with "?" in the
*Packages* buffer.  Maybe MELPA or Marmalade are not providing the
*-readme.txt files which are supposed to be there.

> I think it's fixed in Daniel Haxney's package.el fork, though.

If there is a bug, it should be fixed orthogonally to all the rest of
the refactoring he is trying to do.

Re: GNU ELPA visibility

[Dmitry Gutov]

On 27.10.2012 9:18, Chong Yidong wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>>> It would be good if every package would at least complement Version and
>>> Summary with a longer description, a link to its homepage (or emacswiki
>>> page if it has no homepage), and the date when it was updated the last
>>> time.
>>
>> You may find that, for single-file packages, even if they provide an
>> extended "Commentary" section, it will not show up in the
>> "list-packages" interface. At least when distributed over MELPA or
>> Marmalade.
>
> Please provide an example of what you mean.  I just checked with the GNU
> ELPA packages, and the commentaries show up fine with "?" in the
> *Packages* buffer.  Maybe MELPA or Marmalade are not providing the
> *-readme.txt files which are supposed to be there.

That is the problem with those two repositories, yes.

In principle, though, when there is no readme.txt, the package manager 
could fetch the source file and parse the description from it.
I understand that not doing that saves traffic, although I wonder how much.

>> I think it's fixed in Daniel Haxney's package.el fork, though.
>
> If there is a bug, it should be fixed orthogonally to all the rest of
> the refactoring he is trying to do.

I'm sorry for the confusion, his code is not doing anything different in 
that regard. I guess I skimmed it a while ago, saw the related part of 
`describe-package-1', got excited and failed to notice both the 
condition (if built-in) and the fact that that code is the same in the 
Emacs trunk.

Re: GNU ELPA visibility

[Dmitry Gutov]

Jorgen Schaefer <forcer@forcix.cx> writes:
 >> It really is the most useful repository, though. And the only one
 >> still actively maintained, among alternative repos.
 >
 > Marmalade is still maintained (currently by nicferrier) and quite
 > useful, too:
 >
 > http://marmalade-repo.org/

Do you just mean "moderated"? The last commit to the engine was almost a
year ago: http://code.google.com/p/marmalade/source/list

 > That's also a great example (content-wise, not design-wise) of a
 > sensible *ELPA homepage: What is this, how to use it, quick list of
 > packages, easy way to search/browse packages, and, most importantly, a
 > guide on how to get your own packages in there.

Agree.

Re: GNU ELPA visibility

[Jorgen Schaefer]

On Fri, 26 Oct 2012 02:14:00 +0400
Dmitry Gutov <dgutov@yandex.ru> wrote:

> Jorgen Schaefer <forcer@forcix.cx> writes:
>  >> It really is the most useful repository, though. And the only one
>  >> still actively maintained, among alternative repos.
>  >
>  > Marmalade is still maintained (currently by nicferrier) and quite
>  > useful, too:
>  >
>  > http://marmalade-repo.org/
> 
> Do you just mean "moderated"? The last commit to the engine was
> almost a year ago: http://code.google.com/p/marmalade/source/list

Four months, actually: https://github.com/nicferrier/marmalade/ - and
he just confirmed to me that he is actively maintaining it. :-)

He has been working on a rewrite as far as I know, but not sure how
far that is.

But yeah, I'm not sure how much commits to the *engine* of an archive
say about its usefulness. Marmalade has multiple package uploads daily,
and a pretty long list of packages.

Regards,
	-- Jorgen

Re: GNU ELPA visibility

[Dmitry Gutov]

"Drew Adams" <drew.adams@oracle.com> writes:

 >> > When looking for an Elisp package or feature, most people reach for
 >> > their browser before reaching for M-x list-packages.
 >> > But packages distributed via GNU ELPA won't show up because
 >> > they're not visible to search engines.
 >>
 >> I think it's very likely that M-x list-packages will get much more
 >> common as time progresses. It's certainly the first thing that I go to
 >> nowadays.
 >
 > I vote for including more by default in `package-archives'.
 >
 > In particular, include ("melpa" . 
"http://melpa.milkbox.net/packages/").  That
 > might not be the blessed, "canonical" archive site, but it is 
certainly one of
 > the most used and most useful.

Maybe after they implement the feature "stable packages from tags"?

It really is the most useful repository, though. And the only one still
actively maintained, among alternative repos.

--Dmitry

RE: GNU ELPA visibility

[Drew Adams]

>  > I vote for including more by default in `package-archives'.
>  >
>  > In particular, include ("melpa" .
>  > "http://melpa.milkbox.net/packages/").  That might not be
>  > the blessed, "canonical" archive site, but it is certainly
>  > one of the most used and most useful.
> 
> Maybe after they implement the feature "stable packages from tags"?

You'll have to take that up with Milkypostman.  I know nothing about it.

> It really is the most useful repository, though. And the only 
> one still actively maintained, among alternative repos.

AFAIK, it also has the advantage of being automatically updated from its
upstream sources.  That's a great feature.

I imagine that automatic updating is configurable on MELPA (i.e., you can turn
it off (?)), but is that feature even available for GNU Elpa?

Re: GNU ELPA visibility

[Dmitry Gutov]

On 26.10.2012 1:34, Drew Adams wrote:
>>   > I vote for including more by default in `package-archives'.
>>   >
>>   > In particular, include ("melpa" .
>>   > "http://melpa.milkbox.net/packages/").  That might not be
>>   > the blessed, "canonical" archive site, but it is certainly
>>   > one of the most used and most useful.
>>
>> Maybe after they implement the feature "stable packages from tags"?
>
> You'll have to take that up with Milkypostman.  I know nothing about it.

You could have checked the issue tracker:
https://github.com/milkypostman/melpa/issues/7

>> It really is the most useful repository, though. And the only
>> one still actively maintained, among alternative repos.
>
> AFAIK, it also has the advantage of being automatically updated from its
> upstream sources.  That's a great feature.
>
> I imagine that automatic updating is configurable on MELPA (i.e., you can turn

You can choose not to upgrade at any given point in time, but the 
repository always shows the latest, so to speak, "nightly" versions.

> it off (?)), but is that feature even available for GNU Elpa?

AFAIK, ELPA just builds off a single branch in a single repository. 
That's automatic, but for each package where Emacs Bazaar repo is not 
the canonical source, the changes need to pushed to it manually.

RE: GNU ELPA visibility

[Drew Adams]

> > AFAIK, it also has the advantage of being automatically 
> > updated from its upstream sources.  That's a great feature.
>
> You can choose not to upgrade at any given point in time, but the 
> repository always shows the latest, so to speak, "nightly" versions.
> 
> > is that feature even available for GNU Elpa?
> 
> AFAIK, ELPA just builds off a single branch in a single repository. 
> That's automatic, but for each package where Emacs Bazaar repo is not 
> the canonical source, the changes need to pushed to it manually.

Too bad.

Re: GNU ELPA visibility

[Stefan Monnier]

>> it off (?)), but is that feature even available for GNU Elpa?
> AFAIK, ELPA just builds off a single branch in a single repository.

Not quite: The Org package is pulled from Org's repository.
Other packages can be handled similarly.

> That's automatic, but for each package where Emacs Bazaar repo is not
> the canonical source, the changes need to pushed to it manually.

But no, it's currently not automatic, only semi-automatic.
That's something we need to fix as well.


        Stefan

Re: GNU ELPA visibility

[Jorgen Schaefer]

On Fri, 26 Oct 2012 01:23:06 +0400
Dmitry Gutov <dgutov@yandex.ru> wrote:

> "Drew Adams" <drew.adams@oracle.com> writes:
> 
>  > In particular, include ("melpa" . 
> "http://melpa.milkbox.net/packages/").  That
>  > might not be the blessed, "canonical" archive site, but it is 
> certainly one of
>  > the most used and most useful.
> 
> Maybe after they implement the feature "stable packages from tags"?

Yes, that's annoying.

> It really is the most useful repository, though. And the only one
> still actively maintained, among alternative repos.

Marmalade is still maintained (currently by nicferrier) and quite
useful, too:

http://marmalade-repo.org/

That's also a great example (content-wise, not design-wise) of a
sensible *ELPA homepage: What is this, how to use it, quick list of
packages, easy way to search/browse packages, and, most importantly, a
guide on how to get your own packages in there.

Regards,
	-- Jorgen

Re: GNU ELPA visibility

[Dmitry Gutov]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

 > When looking for an Elisp package or feature, most people reach for
 > their browser before reaching for M-x list-packages.
 > But packages distributed via GNU ELPA won't show up because they're not
 > visible to search engines.
 >
 > So I think we should setup some GNU ELPA web-site that lists the
 > packages and where each package gets a web page which would be the
 > canonical web page for that package (so people can link to it from, say,
 > emacswiki) describing it (its README or "Commentary:") plus a link to
 > its repository.

Good suggestion, that would definitely help.

But what do you mean by "canonical web page"? I imagine most of the
packages these already have canonical home pages that are known to users
and search engines, and are generally easier to manage.

--Dmitry

Re: GNU ELPA visibility

[Stefan Monnier]

> But what do you mean by "canonical web page"? I imagine most of the
> packages these already have canonical home pages that are known to users
> and search engines, and are generally easier to manage.

Some GNU ELPA packages do, indeed.  Many don't or only have an old
out-of-date page.


        Stefan

GNU ELPA visibility

[Stefan Monnier]

When looking for an Elisp package or feature, most people reach for
their browser before reaching for M-x list-packages.
But packages distributed via GNU ELPA won't show up because they're not
visible to search engines.

So I think we should setup some GNU ELPA web-site that lists the
packages and where each package gets a web page which would be the
canonical web page for that package (so people can link to it from, say,
emacswiki) describing it (its README or "Commentary:") plus a link to
its repository.


        Stefan

Re: GNU ELPA visibility

[Jeremiah Dodds]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> When looking for an Elisp package or feature, most people reach for
> their browser before reaching for M-x list-packages.
> But packages distributed via GNU ELPA won't show up because they're not
> visible to search engines.

I think it's very likely that M-x list-packages will get much more
common as time progresses. It's certainly the first thing that I go to
nowadays.

>
> So I think we should setup some GNU ELPA web-site that lists the
> packages and where each package gets a web page which would be the
> canonical web page for that package (so people can link to it from, say,
> emacswiki) describing it (its README or "Commentary:") plus a link to
> its repository.
>
>
>         Stefan

I'm not sure how much this would help the problem stated -- certainly
more than none -- but do think it would be a nice thing to have for
packages distributed via GNU ELPA.

Just my 2 cents, as a user.

-- 
Jeremiah Dodds

blog       : http://jdodds.github.com
github     : https://github.com/jdodds
freenode   : exhortatory
twitter    : kaens

RE: GNU ELPA visibility

[Drew Adams]

> > When looking for an Elisp package or feature, most people reach for
> > their browser before reaching for M-x list-packages.
> > But packages distributed via GNU ELPA won't show up because 
> > they're not visible to search engines.
> 
> I think it's very likely that M-x list-packages will get much more
> common as time progresses. It's certainly the first thing that I go to
> nowadays.

I vote for including more by default in `package-archives'.

In particular, include ("melpa" . "http://melpa.milkbox.net/packages/").  That
might not be the blessed, "canonical" archive site, but it is certainly one of
the most used and most useful.

Re: GNU ELPA visibility

[Tassilo Horn]

Jeremiah Dodds <jeremiah.dodds@gmail.com> writes:

>> When looking for an Elisp package or feature, most people reach for
>> their browser before reaching for M-x list-packages.  But packages
>> distributed via GNU ELPA won't show up because they're not visible to
>> search engines.
>
> I think it's very likely that M-x list-packages will get much more
> common as time progresses. It's certainly the first thing that I go to
> nowadays.

Ditto, but the package explanations given there are far from informative
enough to find the package you need for your task at hand.  I look there
first, but then google up the packages that sound relevant, and in the
end that almost always leads to emacswiki.

It would be good if every package would at least complement Version and
Summary with a longer description, a link to its homepage (or emacswiki
page if it has no homepage), and the date when it was updated the last
time.

Bye,
Tassilo

Re: GNU ELPA visibility

[Bastien]

Tassilo Horn <tsdh@gnu.org> writes:

> It would be good if every package would at least complement Version and
> Summary with a longer description, a link to its homepage (or emacswiki
> page if it has no homepage), and the date when it was updated the last
> time.

On top of that, it'd be nice to be able to search through all the length
description.  For example M-x package-filter RET cursor RET would apply
a filter limiting the list of packages to that containing "cursor" in 
their (complete) description.

-- 
 Bastien

Re: GNU ELPA visibility

[Jambunathan K]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> When looking for an Elisp package or feature, most people reach for
> their browser before reaching for M-x list-packages.
> But packages distributed via GNU ELPA won't show up because they're not
> visible to search engines.

One can always do a targeted search at elpa.gnu.org.  Most importantly,
the http://elpa.gnu.org pages are indexed by search engines.

    http://lmgtfy.com/?q=auctex+%20site%3Aelpa.gnu.org

May be the archive-contents file in the packages directory can contain
some `magic' string say `GNU ELPA' that one can use for search queries.
This will be particularly useful as packages grow and people start
relying more and more on browsers for locating packages.

A targetted mailing list (or discussion group) for GNU ELPA packages is
also a good idea for targetted search or to keeping abreast of latest
ANNouncements in package world.

> So I think we should setup some GNU ELPA web-site that lists the
> packages and where each package gets a web page which would be the
> canonical web page for that package (so people can link to it from, say,
> emacswiki) describing it (its README or "Commentary:") plus a link to
> its repository.

One can standardize around TeX or Org markup for package readme files.
Org can be exported to ascii, as well as HTML.  It essentially means
that one gets a readme file (`?' in `*Packages*' buffer) or it's own
web page.

>         Stefan
>
>

-- 

Re: GNU ELPA visibility

[Bastien]

Jambunathan K <kjambunathan@gmail.com> writes:

> One can standardize around TeX or Org markup for package readme files.

Indeed.

On http://elpa.gnu.org 

- have a list of available packages in packages.html (translated 
  from a new packages.org page in the ELPA's root directory?)

- each package on this list would link to its corresponding
  readme.html file, exported from readme.org in the package dir.

-- 
 Bastien

Re: GNU ELPA visibility

[Stefan Monnier]

> So I think we should setup some GNU ELPA web-site that lists the
> packages and where each package gets a web page which would be the
> canonical web page for that package (so people can link to it from, say,
> emacswiki) describing it (its README or "Commentary:") plus a link to
> its repository.

Well, I just went ahead and took a first crack at it.  I'm an HTML
ignoramus, so the result is clearly unimpressive.  If you care to make
it better, the code that builds those files is in
elpa/admin/archive-contents.el, so feel free to submit patches for it.

As discussed in this thread, if we want this to work, we need some way
to get a sexier description than the plain-text readme.txt.  I.e. we
need to replace the READMEs with more structured files which can be
easily turned into acceptable HTML (no need to be fancy, here) as well
as easy to render acceptably in Emacs (extra bonus points if that same
format can end up being used as a replacement for Info ;-).


        Stefan

Re: GNU ELPA visibility

[Jambunathan K]

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

> I.e. we
> need to replace the READMEs with more structured files which can be
> easily turned into acceptable HTML (no need to be fancy, here) as well
> as easy to render acceptably in Emacs (extra bonus points if that same
> format can end up being used as a replacement for Info ;-).

Org can be exported to HTML, Plain text (ASCII) and texi.
-- 

Re: GNU ELPA visibility

[chad]

On 31 Oct 2012, at 22:10, Jambunathan K <kjambunathan@gmail.com> wrote:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
>> I.e. we
>> need to replace the READMEs with more structured files which can be
>> easily turned into acceptable HTML (no need to be fancy, here) as well
>> as easy to render acceptably in Emacs (extra bonus points if that same
>> format can end up being used as a replacement for Info ;-).
> 
> Org can be exported to HTML, Plain text (ASCII) and texi.

Also, Markdown (in some flavor) is more or less accepted standard for
this kind of thing (github, et al).

~Chad

Re: GNU ELPA visibility

[Jambunathan K]

chad <yandros@MIT.EDU> writes:

> On 31 Oct 2012, at 22:10, Jambunathan K <kjambunathan@gmail.com> wrote:
>
>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> 
>>> I.e. we
>>> need to replace the READMEs with more structured files which can be
>>> easily turned into acceptable HTML (no need to be fancy, here) as well
>>> as easy to render acceptably in Emacs (extra bonus points if that same
>>> format can end up being used as a replacement for Info ;-).
>> 
>> Org can be exported to HTML, Plain text (ASCII) and texi.
>
> Also, Markdown (in some flavor) is more or less accepted standard for
> this kind of thing (github, et al).

github can display simple Org files with no extra user intervention.

> ~Chad
>
>
>
>

-- 

Re: GNU ELPA visibility

[Stefan Monnier]

>> I.e. we need to replace the READMEs with more structured files which
>> can be easily turned into acceptable HTML (no need to be fancy, here)
>> as well as easy to render acceptably in Emacs (extra bonus points if
>> that same format can end up being used as a replacement for Info ;-).
> Org can be exported to HTML, Plain text (ASCII) and texi.

So far, Org, ReST, Markdown, and Texinfo sound like the best
options, indeed.

Texinfo requires an extra step (generate Info) before rendering in Emacs
but has the advantage that this rendering already exists and that
Texinfo is the standard GNU documentation format.  It has its
weaknesses, but it's a tool we know (i.e. which is why we already know
its weaknesses).

I'd be interested to see some sample rendering of Markdown, Org, and ReST
both in HTML and inside Emacs, for comparison.


        Stefan

Re: GNU ELPA visibility

[Daniel Hackney]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>> I.e. we need to replace the READMEs with more structured files which
>>> can be easily turned into acceptable HTML (no need to be fancy, here)
>>> as well as easy to render acceptably in Emacs (extra bonus points if
>>> that same format can end up being used as a replacement for Info ;-).
>> Org can be exported to HTML, Plain text (ASCII) and texi.
>
> So far, Org, ReST, Markdown, and Texinfo sound like the best
> options, indeed.

Put another vote in for Org. Aside from shipping with Emacs
out-of-the-box, all of its incredibly advanced stuff could come in handy
if we want to get fancy down the road. I'm thinking about the embedded
source code, which could be very useful as examples of the usage of a
library. Other formats allow for <pre> equivalents, but none have the
features of Org-babel. More generally, Org has an enormous ability to
store machine-extractable data (in its headers) and much more flexible
formatting. I think it is a no-brainer.

If you wanted to get crazy, you could distribute entire packages as
Org-mode files and unpack them with `org-babel-tangle' ;)

--
Daniel Hackney

Re: GNU ELPA visibility

[Jorgen Schaefer]

On Fri, 2 Nov 2012 03:12:46 -0400
Daniel Hackney <dan@haxney.org> wrote:

> > So far, Org, ReST, Markdown, and Texinfo sound like the best
> > options, indeed.
> 
> Put another vote in for Org. Aside from shipping with Emacs
> out-of-the-box, all of its incredibly advanced stuff could come in
> handy if we want to get fancy down the road. I'm thinking about the
> embedded source code, which could be very useful as examples of the
> usage of a library. Other formats allow for <pre> equivalents, but
> none have the features of Org-babel.

Github-flavored Markdown has syntax highlighting for a number of
languages.

From what I can see, Org is "the 'modern' Emacs solution", Texinfo "the
traditional solution", and Markdown "the pragmatic solution".

... Looking forward to Pymacs and similar packages, providing a
markdown README for Github, and an org README for elpa, but also a reST
README for PyPI. :-D Luckily, there is Pandoc which can convert all
this mess around. Of course, that means you don't get to use any of the
special features of any of those formats, but hey, *someone* can.

Regards,
Jorgen