On 6/28/22 09:54, Vít Ondruch wrote:
Dne 27. 06. 22 v 19:51 Jarek Prokop napsal(a):
> 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?
Thank you for looking into this.
I agree that the proper font requires should be better and actually
enough to be able to drop the fonts and keep the visual output the same.
Please not that we still have js-jquery package around, that could
again help with removing the duplicated JS code.
Not by much :/ those files are
still present, with JQuery they were just
loaded in darkfish.js instead of the HTML `\<header\>` section. It would
perhaps even worsen the situation with additional JS dependency. (see:
https://github.com/ruby/rdoc/commit/b6206b943f95026872c9b690ef59f04ee2f54fec)
However, doing these two things get us closer to having separate
template for documentation. I.e. if we were able to extract the
darkfish from RDoc into separate package and symlink the whole
template, that would be win. I am pretty sure that RDoc can use custom
templates.
I agree with this form, we could have a template like that with darkfish
as source. I can try whipping something up, but I cannot promise
anything concrete ATM.
Jarek
Vít
>
> 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