Hi,
since it came up in the package review I took a closer look on the state
and possibilities.
On 6/27/22 17:47, Vít Ondruch wrote:
Dne 27. 06. 22 v 13:21 Benson Muite napsal(a):
> Hi Pavel,
>
> Thanks. Is it also worth encouraging packaging of Ri documentation?
> These are very comandline friendly, Javascript is not. In principle,
> one might want to have HTML documentation as a separate package from
> Ri documentation giving the end user a choice of what to install.
Of course that would be nice in ideal world. If I only had a time to
implement this.
>
> Will see if can figure out some way of removing fonts.
There are several options:
1) Keep the status quo,
2) Just drop the fonts and leave the browser to use some substitutes
That seems simple enough, from limited local testing, it is absolutely
possible, but we would need probably the correct font requirement for
ruby-*doc (more on that down in the response...).
However we still have the JS files. We can take those out, in theory.
But it breaks code search and code expansion from my limited testing.
I'd be in favor of somehow not shipping the HTML at all than to remove
the JS. There is a way to not generate it with RDoc and have just the
.ri format, however I'd have to look into how it would work with our
`%gem_install`.
3) Symlink the system fonts.
I'd personally like to dodge symlinking the fonts
as the folder names
might change in the future. (Or might not, I am not well versed in
possibilities of the Font space of world)
Firefox (at least on my machine :) ) and the `fonts.css` generated with
the docs are smart enough to take it from the system folders if they are
not present in the expected relative location.
Tested in one of my Ruby projects like so:
~~~
rdoc
rm doc/fonts/*
~~~
When I open the index.html, there are no errors in the browser logs
regarding failure to load font files, as long as I have both the
required font packages.
So, I'd rather remove them from the package than to have symlinks that
might break later on. This approach will require generating `Requires:`
for the *-doc subpackages on the `adobe-source-code-pro-fonts` for
source code font
and the `lato-fonts` for non source code text.
Visually comparing the "pure" generated state right after running `rdoc`
and the state after removing the fonts with `rm doc/fonts/*` I observe
no loss in quality, so I think that should be the way go for HTML docs
in the fonts department as the mechanisms seem to be there.
As to the JS:
A) We could also somehow tell the generator where the JS assets live and
have it generate the paths into the HTML (I noticed there are some
variables around this in the darkfish.rb [0]), but we would have to
first find out how to even do that, second figure out where are those JS
files going to be as we are running in, IMHO into similar problem as
with symlinking, IMHO we do not want to depend on the whole
rubygem-rdoc. This approach to me seems time consuming, achieving
similar results as simple symlinking in the end.
B) Simply symlinking the files to expected location. Question is what
would happen if we will have to move the symlink for whatever reason,
but that's more general question around parts of RPM internals I do not
explore quite often, so I cannot effectively judge on that.
What form or solution should that take though is a harder question. Why
is that harder IMO is what form of requires are needed? Maybe
rubygem-rdoc? But that's a lot of files that we do not need when we need
just the JS files, probably some subpackage would be better fitting?
Regards,
Jarek
[0] `@template_dir`
https://github.com/ruby/rdoc/blob/master/lib/rdoc/generator/darkfish.rb#L220
I have never experimented with (2) / (3).
Of course ideal would be to have our own template for the RDoc
documentation which could be linked instead the copied version. This
would save us from these issues as well as saved disk space.
Vít