link info/html files from the GNU ELPA package page

link info/html files from the GNU ELPA package page

[Stephen Leake]

How would I go about adding html files from the :doc entry for wisi in
elpa/elpa-packages to https://elpa.gnu.org/packages/wisi.html> ?

I assume there's some script/elisp in elpa/admin that generates that
page?
-- 
-- Stephe

Re: link info/html files from the GNU ELPA package page

[Stefan Monnier]

> How would I go about adding html files from the :doc entry for wisi in
> elpa/elpa-packages to https://elpa.gnu.org/packages/wisi.html> ?

I'm not completely sure what you mean by that, but currently the doc
shown in `wisi.html` taken from the wisi package can only be plaintext
(so it would show the HTML code itself rather than its rendering).

Patches welcome to improve that.

If at all possible, it's probably better to have a source format
different from HTML, which we can then convert to the kind of HTML
fragment we need.

> I assume there's some script/elisp in elpa/admin that generates
> that page?

It's in `elpa-admin.el`, e.g. around `elpaa--html-make-pkg`.


        Stefan

Re: link info/html files from the GNU ELPA package page

[Stephen Leake]

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

>> How would I go about adding html files from the :doc entry for wisi in
>> elpa/elpa-packages to https://elpa.gnu.org/packages/wisi.html> ?

I links to them, so users can read the user manuals from the ELPA
page. That also means the ELPA server needs to store the actual doc
files somewhere accessible, not just in the package tarball.

> I'm not completely sure what you mean by that, but currently the doc
> shown in `wisi.html` taken from the wisi package can only be plaintext
> (so it would show the HTML code itself rather than its rendering).

I could put the docs on the savannah home page for ada-mode and wisi (I
should do that anyway), and put links in that text to savannah.

> If at all possible, it's probably better to have a source format
> different from HTML, which we can then convert to the kind of HTML
> fragment we need.

The docs listed in ada-mode and wisi :doc have texinfo source.

>> I assume there's some script/elisp in elpa/admin that generates
>> that page?
>
> It's in `elpa-admin.el`, e.g. around `elpaa--html-make-pkg`.

Ok. So that could add a line for ada-mode:

    docs: <a href="ada-mode.html">ada-mode</a>, <a href="gpr-mode.html">gpr-mode</a>

and for wisi:

    docs: <a href="wisi.html">wisi</a>, <a href="wisitoken-user_guide.html">wisitoken-user_guide</a>

Instead of just the file name, maybe we could pull the doc title from
the texinfo file somehow?

And somewhere in elpaa--make-one-package it would have to save the doc
files somewhere, instead of deleting them after building the tarball.

-- 
-- Stephe

Re: link info/html files from the GNU ELPA package page

[Stefan Monnier]

>>> How would I go about adding html files from the :doc entry for wisi in
>>> elpa/elpa-packages to https://elpa.gnu.org/packages/wisi.html> ?
> I links to them, so users can read the user manuals from the ELPA
> page. That also means the ELPA server needs to store the actual doc
> files somewhere accessible, not just in the package tarball.

[ Not completely sure what you wanted to write for "I links",
  but I think the overall intent was clear enough.  ]

Yes, that would make sense.

>>> I assume there's some script/elisp in elpa/admin that generates
>>> that page?
>> It's in `elpa-admin.el`, e.g. around `elpaa--html-make-pkg`.
> Ok. So that could add a line for ada-mode:
>
>     docs: <a href="ada-mode.html">ada-mode</a>, <a href="gpr-mode.html">gpr-mode</a>

`ada-mode.html` would link back to the package's description page
I think, but we could have relative links like `doc/ada-mode/<foo>`.

> Instead of just the file name, maybe we could pull the doc title from
> the texinfo file somehow?

That would be swell ;-)

> And somewhere in elpaa--make-one-package it would have to save the doc
> files somewhere, instead of deleting them after building the tarball.

Actually, we would first have to generate HTML versions of the doc, so
it will take a bit more effort, but yes, it can probably be done
somewhere near the end of `elpaa--make-one-tarball-1` and the somewhere
would presumably be relative to the directory of `tarball`, e.g.
specified via a global like (defvar elpa--doc-subdirectory "doc/"),
controllable by `elpa-config` with a nil value preventing the creation
of that doc.


        Stefan

Re: link info/html files from the GNU ELPA package page

[Stephen Leake]

Ok, I'll try to work on this. I should work on a branch; any preferences
for the branch name?

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

>>>> How would I go about adding html files from the :doc entry for wisi in
>>>> elpa/elpa-packages to https://elpa.gnu.org/packages/wisi.html> ?
>> I links to them, so users can read the user manuals from the ELPA
>> page. That also means the ELPA server needs to store the actual doc
>> files somewhere accessible, not just in the package tarball.
>
> [ Not completely sure what you wanted to write for "I links",
>   but I think the overall intent was clear enough.  ]
>
> Yes, that would make sense.
>
>>>> I assume there's some script/elisp in elpa/admin that generates
>>>> that page?
>>> It's in `elpa-admin.el`, e.g. around `elpaa--html-make-pkg`.
>> Ok. So that could add a line for ada-mode:
>>
>>     docs: <a href="ada-mode.html">ada-mode</a>, <a href="gpr-mode.html">gpr-mode</a>
>
> `ada-mode.html` would link back to the package's description page
> I think, but we could have relative links like `doc/ada-mode/<foo>`.
>
>> Instead of just the file name, maybe we could pull the doc title from
>> the texinfo file somehow?
>
> That would be swell ;-)
>
>> And somewhere in elpaa--make-one-package it would have to save the doc
>> files somewhere, instead of deleting them after building the tarball.
>
> Actually, we would first have to generate HTML versions of the doc, so
> it will take a bit more effort, but yes, it can probably be done
> somewhere near the end of `elpaa--make-one-tarball-1` and the somewhere
> would presumably be relative to the directory of `tarball`, e.g.
> specified via a global like (defvar elpa--doc-subdirectory "doc/"),
> controllable by `elpa-config` with a nil value preventing the creation
> of that doc.
>
>
>         Stefan
>
>
>

-- 
-- Stephe

Re: link info/html files from the GNU ELPA package page

[Stefan Monnier]

> Ok, I'll try to work on this. I should work on a branch; any preferences
> for the branch name?

Just put it under a `scratch/` or a `feature/` prefix (the first means
that the result won't be just `merge`d but `merge --squash`d and hence
allows you to commit without proper commit messages).


        Stefan