On 15/11/2019 05:02, Bruno P. Kinoshita wrote:
Hi Alex,
This cannot be included in the site descriptor for the project as the
<head> entry for each page is generated by commons-skin. This adds
javascript to allow pretty print of code inside <pre "prettyprint">
tags. I would like to add a javascript tag to allow inclusion of MathJax.
What about loading per page in RNG?
Thanks for the suggestion.
The main user guide is written in APT [1].
This cannot include html tags. I could covert APT to XDOC but there are
more issues with the commons-skin that should be fixed.
[1] https://maven.apache.org/doxia/references/apt-format.html
- Update commons-skin to add a MathJax script to the <head> section
Not sure if that's the best option. That would be loaded for every component I
assume. In case a new version was needed we would have to release a new version
of commons-skin too I guess?
I had a look at commons-parent and commons-skin. Looks like commons-parent
defines the body.head, as well as body.custom.footer. Which are places that we
could load the script.
I think only the menu can be extended in the child projects (ASF components),
so we have no way of using those elements to customize RNG (as you pointed
above).
The <head> and <custom> can be overwritten from the inherited site.xml
in commons parent. So this is OK if they worked. Unfortunately they do
not for the reasons outlined below.
I can include MathJax if I use a different skin that supports XHTML
injection into <head>. It just does not work with commons-skin.
This is because we now use maven site plugin 3.5+ which has to contain
injected XHTML <script> tags in CDATA for the <head> section.
The commons-skin was pre maven 3.5 so does not support this.
This is the crux of my problem where I cannot inject the MathJax script
into the <head>. If I remove the <![CDATA[ I get an error:
[ERROR] Failed to execute goal
org.apache.maven.plugins:maven-site-plugin:3.8.2:site (default-cli) on
project commons-rng-parent: SiteToolException: Error parsing site
descriptor: expected = after attribute name (position: TEXT seen
...>\n <script type="text/javascript" id="MathJax-script" async
s... @37:65) -> [Help 1]
It is not allowed with the current site plugin.
I've noticed that the following footer defined in commons-parent is also
using a CDATA tag:
<!-- inherited -->
<custom>
<![CDATA[
<!-- @project.name@ will be replaced by the template; if we used
${project.name} it would pick up Commons Parent -->
<footer>
<div class="center">
Apache Commons, Apache @project.name@, Apache, the Apache feather
logo, and the Apache Commons project logos are trademarks of The Apache
Software Foundation.
All other marks mentioned may be trademarks or registered
trademarks of their respective owners.
</div>
</footer>
]]>
</custom>
This does not work and all of our site pages do not have the copyright
notice on them.
It is not actually needed as the custom tag is ignored by the site
plugin [2]. You can put what you want in there.
If I update commons parent to fix this (drop the <![CDATA[ tag in the
custom footer) then the copyright notice does not work correctly as the
macros are outdated. The velocity macro in commons-skin is using:
$StringUtils.replace()
This does not appear to exist in velocity 1.7 [3]. So the copyright
footer is then rendered as:
Apache Commons, Apache Apache Commons RNG, Apache, the Apache feather
logo, and the Apache Commons project logos are trademarks of The Apache
Software Foundation. All other marks mentioned may be trademarks or
registered trademarks of their respective owners.
With the duplicate 'Apache Apache'.
So to render the copyright footer will require an update to commons-skin
and a fix for commons parent to drop the ![CDATA[ tag in the custom footer.
My other issue is that the pretty print functionality for code
highlighting does not work when APT pages are rendered into <pre> tags
as the classes used are now different to those targetted by the style
sheets in commons skin.
This has been fixed in the fluido skin 1.8. So I am working on bring the
changes made to fluido 1.3 for the commons skin to fluido 1.8.
[2]
https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html#Custom_content
[3]
https://velocity.apache.org/engine/1.7/apidocs/org/apache/velocity/util/StringUtils.html
Here's one way I found that works, where a component loads an extra JS script.
In this example I used commons-text (already had cloned in my notebook) and
loaded mathjax to render an equation from their tutorial.
https://github.com/apache/commons-text/compare/master...kinow:mathjax-site?expand=1
If that's not good, then I guess we would have to either change
maven-site-plugin to allow scripts to be loaded, or go with your original
suggestion.
Didn't have time to look at the other issues with JaCoCo and jacimp, sorry.
Those issue I have already fixed with updates to commons parent.
Hope that helpsBruno
ps: there is a CDATA element to prevent the maven-site-plugin from filtering
the JS script... maybe a bit too hacky?
On Thursday, 14 November 2019, 2:32:56 am NZDT, Alex Herbert
<alex.d.herb...@gmail.com> wrote:
The recent release of RNG has highlighted some issues with the commons
parent configuration for multi-module builds and a desirable change to
commons skin.
1. [parent] JaCoCo aggregate reports are included.
Aggregate reports show coverage of dependencies. Since most commons
components are stand-alone this should be disabled and the report set
updated to have non-aggregate reports.
An example of the output is shown for the recently release BCEL:
https://commons.apache.org/proper/commons-bcel/project-reports.html
The aggregate report is empty.
2. [parent] japicmp does not allow clean opt-in
The japicmp maven plugin is immature. If set to skip the report it still
creates a menu entry in the site reports page. See this release of
Collections:
https://commons.apache.org/proper/commons-collections/project-reports.html
The link for the japicmp report is a blank page.
For collections this could be fixed by running the report.
For a multi-module build using japicmp any module with no code (i.e. a
pom) has this empty entry if japicmp is enabled as the skip
functionality does not work.
The solution is to move the reporting section from the main
configuration into the japicmp profile. This allows opt-in on a
per-module basis to japicmp.
3. [skin] Customisation of the site <head> section
RNG uses formulas in the site documentation. Ideally this would be
rendered latex using MathJax [1].
This cannot be included in the site descriptor for the project as the
<head> entry for each page is generated by commons-skin. This adds
javascript to allow pretty print of code inside <pre "prettyprint">
tags. I would like to add a javascript tag to allow inclusion of MathJax.
I have rendered the RNG site using these changes and staged it here:
mvn package site site:stage -Dcommons.release.version=1.2
-DcomparisonVersion=1.2
https://home.apache.org/~aherbert/commons-rng-1.4-site/index.html
Top level reports page does not have japicmp:
https://home.apache.org/~aherbert/commons-rng-1.4-site/project-reports.html
Components do:
https://home.apache.org/~aherbert/commons-rng-1.4-site/commons-rng-simple/project-reports.html
(There are also no jacoco aggregate reports.)
You can view how MathJax is rendered on this page:
https://home.apache.org/~aherbert/commons-rng-1.4-site/developers.html
(search for 'will render an in-line formula')
AFAIK an update to commons-skin to include MathJax will not effect sites
that do not contain the \( or \[ characters in plain text on site pages.
I propose to:
- Update commons-skin to add a MathJax script to the <head> section
- Release commons-skin (last release was May 2015)
- Update commons-parent:
- Use the new commons-skin
- Remove JaCoCo aggregate reports
- Reconfigure japicmp for clean opt-in
Alex
[1] https://www.mathjax.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
