GNU bug report logs - #53205
28.0.90; [PATCH] GNU ELPA: Provide more control over linked documentation

Previous Next

To reply to this bug, email your comments to 53205 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Y. E. <yet <at> ego.team>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.90; [PATCH] GNU ELPA: Provide more control over linked
 documentation
Date: Wed, 12 Jan 2022 13:47:30 +0200

[Message part 1 (text/plain, inline)]

The introductory text is longish, so if no additional context is needed,
please see the following attached patches:

- 0001-Provide-more-control-over-linked-documentation.patch

- 0001-README-doc-html-resources-Document-new-properties.patch

[0001-Provide-more-control-over-linked-documentation.patch (text/x-patch, attachment)]

[0001-README-doc-html-resources-Document-new-properties.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, inline)]

I've been locally testing configuration for Company documentation (to
add it to GNU ELPA) and noticed that an HTML version of the manual is
automatically generated from the '.texi' file. The generated HTML file
is linked under the label 'Manual' on the package page and served from
the 'archive-devel/doc/company/' directory.

I was pleased to see that automatic generation but there were two issues
(namely, images and styles).

The user manual for Company is shipped with the images; and it is
currently impossible to configure the addition of them to the
'elpaa--doc-subdirectory'.

My initial idea for fixing this issue was to add a property
':doc-asset', which could be configured to '(FROM . TO)' directories
names, then used for moving images to the 'archive-devel/doc/company/'
folder, as shown below:

#+BEGIN_SRC diff
diff --git a/elpa-admin.el b/elpa-admin.el
index d94cc7fd73..23bb582ceb 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1999,7 +1999,11 @@ directory; one of archive, archive-devel."
 	    (expand-file-name elpaa--doc-subdirectory tarball-dir)))))
     (when html-dir
       (when (not (file-readable-p html-dir)) ;FIXME: Why bother testing?
-	(make-directory html-dir t)))
+	    (make-directory html-dir t))
+      (when-let ((assets (elpaa--spec-get pkg-spec :doc-assets)))
+        (cl-loop for (from . to) in assets
+                 do (rename-file (expand-file-name from dir)
+                                 (expand-file-name to html-dir) t))))

     (plist-put (cdr pkg-spec) :internal--html-docs nil)
     (dolist (f docfiles)
-- 
2.34.1
#+END_SRC

That worked fine during my tests but thinking about how to apply CSS
styles to the manual (including to control the size of the shown
images), I've got the second idea: Company already has an online version
of the user manual with all the proper styles and images in place, so
why not link directly to it?

So, the suggested patch provides a way to do that. It introduces and
uses two new properties: ':doc-html' and ':resources'.

With it, for example, Company setup could be configured this way:

#+BEGIN_SRC lisp
("company"
  :url "https://github.com/company-mode/company-mode.git"
  :shell-command "mkdir images; mv doc/images/small images/"
  :doc "doc/company.texi"
  :doc-html ignore
  :resources (("User Manual" . "https://company-mode.github.io/manual/index.html"))
  :auto-sync t)
#+END_SRC


I also attach a version with a bit different (IMO less robust/clear)
approach. It introduces/uses one new property instead: ':doc-links'.

[0001-Add-doc-links-property-to-specifications.patch (text/x-patch, attachment)]

Message #8 received at 53205 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Y. E. <yet <at> ego.team>
Cc: 53205 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Thu, 13 Jan 2022 07:23:52 +0100

Y. E. <yet <at> ego.team> writes:

> My initial idea for fixing this issue was to add a property
> ':doc-asset', which could be configured to '(FROM . TO)' directories
> names, then used for moving images to the 'archive-devel/doc/company/'
> folder, as shown below:

I think that sounds OK...

> That worked fine during my tests but thinking about how to apply CSS
> styles to the manual (including to control the size of the shown
> images), I've got the second idea: Company already has an online version
> of the user manual with all the proper styles and images in place, so
> why not link directly to it?

[...]

>   :doc-html ignore
>   :resources (("User Manual" . "https://company-mode.github.io/manual/index.html"))

Well, the user wants to see the version of the manual that corresponds
to the version of the package they have installed, so just redirecting
them to an external web page doesn't seem very useful?  But perhaps I'm
misunderstanding the proposal.  (And I'm adding Stefan to the CCs;
perhaps he has some comments.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #11 received at 53205 <at> debbugs.gnu.org (full text, mbox):

From: Y. E. <yet <at> ego.team>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: yet <at> ego.team, 53205 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Thu, 13 Jan 2022 15:20:25 +0200

>Lars Ingebrigtsen <larsi <at> gnus.org> writes:

>> Y. E. <yet <at> ego.team> writes:
>>
>> My initial idea for fixing this issue was to add a property
>> ':doc-asset', which could be configured to '(FROM . TO)' directories
>> names, then used for moving images to the 'archive-devel/doc/company/'
>> folder, as shown below:
>
> I think that sounds OK...

Fine by me, though with a workaround to apply custom styles. The
generated plain HTML outputs images as is, which doesn't look well in
the described case.

>
>> That worked fine during my tests but thinking about how to apply CSS
>> styles to the manual (including to control the size of the shown
>> images), I've got the second idea: Company already has an online version
>> of the user manual with all the proper styles and images in place, so
>> why not link directly to it?
>
> [...]
>
>>   :doc-html ignore
>>   :resources (("User Manual" . "https://company-mode.github.io/manual/index.html"))
>
> Well, the user wants to see the version of the manual that corresponds
> to the version of the package they have installed, so just redirecting
> them to an external web page doesn't seem very useful?  But perhaps I'm
> misunderstanding the proposal.  (And I'm adding Stefan to the CCs;
> perhaps he has some comments.)

I agree, this is a good point. Currently, the most recent version of the
manual is displayed at Company website. But it's planned to output the
stable version there in the future. So, yes, it would be nice/convenient
to have a development version generated at GNU ELPA.

Message #14 received at 53205 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Y. E. <yet <at> ego.team>
Cc: 53205 <at> debbugs.gnu.org
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Thu, 13 Jan 2022 10:08:13 -0500

Hi,

Yay!  More people working on `elpa-admin.el`!

> +** =:doc-html=
> +By default, if =:doc= specification contains a Texinfo file, then HTML
> +documentation is generated from it; the link to the generated HTML
> +file is added to the package page.  To disable this behavior, set
> +=:doc-html= to ~ignore~.

Hmm... why would you want to disable it?

> +** =:resoures LINKS=
> +Enables 'Additional Resources' section on the package page.  This must
> +be an association list of the titles and URLs of online resources.
> +For example:
> +
> +    (("User Manual" . "https://example.tld/manual.html"))

Could you give more context as for why we want this?
More specifically, the `:readme` file can already contain links to other
places, so I'm not sure why we need special support for it here
(especially since the :readme file is much more flexible and can be
changed without write access to `elpa.git`).

> I was pleased to see that automatic generation but there were two issues
> (namely, images and styles).
>
> The user manual for Company is shipped with the images; and it is
> currently impossible to configure the addition of them to the
> 'elpaa--doc-subdirectory'.

Ah... yes, this is indeed a serious problem with the current code.
But we should fix it rather than disable the generation of the
HTML manual.
[ Note that the problem also applies to Org manuals, and to the
  `:readme`s.  ]

> My initial idea for fixing this issue was to add a property
> ':doc-asset', which could be configured to '(FROM . TO)' directories
> names, then used for moving images to the 'archive-devel/doc/company/'
> folder, as shown below:

That sounds like a good plan.  

> That worked fine during my tests but thinking about how to apply CSS
> styles to the manual (including to control the size of the shown
> images), I've got the second idea: Company already has an online version
> of the user manual with all the proper styles and images in place, so
> why not link directly to it?

There are various reasons why this would not be a good solution.
One Lars already mentioned the issue of the version that may not match,
another one is that some packages don't have such a separate web page.

> I also attach a version with a bit different (IMO less robust/clear)
> approach.  It introduces/uses one new property instead: ':doc-links'.

FWIW, I like this approach better than the first patch, tho I'd still
much prefer to get the "local HTML doc" working better.


        Stefan

Message #17 received at 53205 <at> debbugs.gnu.org (full text, mbox):

From: Y. E. <yet <at> ego.team>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: yet <at> ego.team, 53205 <at> debbugs.gnu.org
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Fri, 14 Jan 2022 13:11:07 +0200

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

> Ah... yes, this is indeed a serious problem with the current code.
> But we should fix it rather than disable the generation of the
> HTML manual.
> [ Note that the problem also applies to Org manuals, and to the
>   `:readme`s.  ]

I'm aware of the issues reported at
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=53069 (though the second
example images are loaded fine with my setup). I looked at it because of
the images load issue coincidence. It seemed to me that changes of a
different type than discussed here would be required for that bug.

>
>> My initial idea for fixing this issue was to add a property
>> ':doc-asset', which could be configured to '(FROM . TO)' directories
>> names, then used for moving images to the 'archive-devel/doc/company/'
>> folder, as shown below:
>
> That sounds like a good plan.

After getting back to this plan, appears there's one more issue for
which I don't see a good strategy to handle.

In the final part of the 'elpaa--html-build-doc' function, it creates a
symlink to the actual HTML file; this symlink is displayed at the
package page. Naturally, putting images the suggested way ('doc-assets'
diff) works fine for the actual HTML file, but not for the symlinked.

Creating a symlinked directory, with the name(s) only one particular
package needs, in the shared '/doc/' directory doesn't look like a good
idea to me. Neither does requiring packages to comply with some naming
for the ELPA needs only.

Any advice on which approach could be suitable to handle this?


> I'd still much prefer to get the "local HTML doc" working better.

This sounds good to me.

Thinking about improving images output for Company local HTML doc, may
it become possible to allow adding small quantity per-package page
styles directly to the ELPA repository?

Having an HTML "package-name wrapper" could allow doing something like:

#pkg-company img {
    max-width: 300px;
}

Message #20 received at 53205 <at> debbugs.gnu.org (full text, mbox):

From: Y. E. <yet <at> ego.team>
To: "Y. E." <yet <at> ego.team>
Cc: yet <at> ego.team, 53205 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Fri, 14 Jan 2022 16:59:18 +0200

> Y. E. <yet <at> ego.team> writes:

> Thinking about improving images output for Company local HTML doc, may
> it become possible to allow adding small quantity per-package page
> styles directly to the ELPA repository?
>
> Having an HTML "package-name wrapper" could allow doing something like:
>
> #pkg-company img {
>     max-width: 300px;
> }

Sorry, my mind was confused at that moment, so I shifted the focus from
the local HTML doc styles to the main package page styles. Even though
the suggested stays valid for the main page styles, the local HTML doc
styles would have to be included to the generated HTML first, of course.

I meant to suggest the following approach:

#+BEGIN_SRC diff
diff --git a/elpa-admin.el b/elpa-admin.el
index d570c3c6aa..cad33482cb 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -2047,7 +2047,12 @@ directory; one of archive, archive-devel."
 	  (concat (make-temp-name (expand-file-name "doc")) ".html")))
     (with-temp-buffer
       (elpaa--call-sandboxed
-       t "makeinfo" "--no-split" "--html" docfile "-o" tmpfile)
+       t "makeinfo" "--no-split" "--html" docfile
+       "-c"  (format "AFTER_BODY_OPEN=<div id=\"pkg-%s\">"
+                     (car pkg-spec))
+       "-c" "PRE_BODY_CLOSE=</div>"
+       "--css-ref" "../../html/doc-html.css" ; TODO: Use robust path.
+       "-o" tmpfile)
       (message "%s" (buffer-string)))
     (rename-file tmpfile html-file t)
     ;; FIXME: Use `push' in Emacs≥28
#+END_SRC

'<elpa>/html/doc-html.css' then could contain:

#+BEGIN_SRC css
#pkg-company img {
    /* Until images output is fixed, hide them. */
    display: none;
    /* max-width: 360px; */
    /* margin-bottom: 0.8em; */
}
#+END_SRC

Would it be fine to follow this route?

Message #23 received at 53205 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Y. E. <yet <at> ego.team>
Cc: 53205 <at> debbugs.gnu.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#53205: 28.0.90; [PATCH] GNU ELPA: Provide more control over
 linked documentation
Date: Thu, 08 Sep 2022 15:55:32 +0200

Y. E. <yet <at> ego.team> writes:

>      (with-temp-buffer
>        (elpaa--call-sandboxed
> -       t "makeinfo" "--no-split" "--html" docfile "-o" tmpfile)
> +       t "makeinfo" "--no-split" "--html" docfile
> +       "-c"  (format "AFTER_BODY_OPEN=<div id=\"pkg-%s\">"
> +                     (car pkg-spec))
> +       "-c" "PRE_BODY_CLOSE=</div>"
> +       "--css-ref" "../../html/doc-html.css" ; TODO: Use robust path.
> +       "-o" tmpfile)
>        (message "%s" (buffer-string)))
>      (rename-file tmpfile html-file t)
>      ;; FIXME: Use `push' in Emacs≥28
> #+END_SRC
>
> '<elpa>/html/doc-html.css' then could contain:
>
> #+BEGIN_SRC css
> #pkg-company img {
>     /* Until images output is fixed, hide them. */
>     display: none;
>     /* max-width: 360px; */
>     /* margin-bottom: 0.8em; */
> }
> #+END_SRC
>
> Would it be fine to follow this route?

This was half a year ago, but there was apparently no followup here.
Stefan, do you have any comments?

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.