When I make projects with C++, I often use doxygen to generate the documentations, doxygen has a neat feature that generates interactive dependency graphs (like call dependencies, inheritance dependencies etc...)
This tool, embedded in the html docs, allows you to zoom in and out and drag things around.
I am trying to generate a dependency graph for the current crates of a project, this looks like this:
The image is generated using depgraph.
I have 2 issues.
Issue 1) is, as the dependency graph grows, the image becomes harder and harder to read:
This could be solved by having a zoom and pan feature like doxygen, but I have got no idea how to generate and inject that kind of html (and maybe js?) into the autodocs from rustod.
Issue 2) is that the svg file is unaffected by the css and having the white and black color scheme looks kinda ugly, this is less important but it would be nice if the svg could mirror the css theme.
Rustdoc allows for the injection of custom CSS and HTML/JS before and after the generated content. You can do this via various command-line arguments.
see: https://doc.rust-lang.org/rustdoc/command-line-arguments.html
To add custom HTML to the header you can use the --html-in-header argument.
$ rustdoc src/lib.rs --html-in-header header.html
Where header.html is your custom header HTML
This flag takes a list of files, and inserts them inside the <body>
tag but before the other content rustdoc would normally produce in the
rendered documentation.
see: https://doc.rust-lang.org/rustdoc/command-line-arguments.html#--html-before-content-include-more-html-before-the-content
$ rustdoc src/lib.rs --html-after-content extra.html
Where extra.html is your custom HTML to include after the content.
This flag takes a list of files, and inserts them before the </body>
tag but after the other content rustdoc would normally produce in the
rendered documentation.
see: https://doc.rust-lang.org/rustdoc/command-line-arguments.html#--html-after-content-include-more-html-after-the-content
Finally for custom CSS
$ rustdoc src/lib.rs --extend-css extra.css
Where extra.css is your custom css definitions.
With this flag, the contents of the files you pass are included at the
bottom of Rustdoc's theme.css file.
While this flag is stable, the contents of theme.css are not, so be
careful! Updates may break your theme extensions.
see: https://doc.rust-lang.org/rustdoc/command-line-arguments.html#-e--extend-css-extend-rustdocs-css
Unfortunately I don't have any example rust doc html - so it is hard to say exactly what should be included in your injected HTML/CSS/JS to achieve your desired results. My suggestion is that you try and if you get stuck to ask a more specific question and provide an example of the code.
Related
Colleagues, I'm trying Parcel as an alternative to webpack project builder and I like it, but there are two BUTs that I still can't beat (here are links to starting builds - build on Parcel
and build on webpack):
1) In the assembly under the webpack, I used svg-sprite-loader to create svg sprites, which adds immediately after opening body svg with symbols like this:
there is no such plugin in the parcel assembly, I tried to install parcel-plugin-svg-sprite, but it does not compile a separate sprite (at least I did not find such a solution in the documentation).
As a result, for now, I am inserting svg in the way described in the parcel documentation (I use a pug in the project):
svg
use (href = "../../ icons / facebook.svg")
but in this case, I only get an empty space ((
2) When building a project, i get one folder with a lot of files, which is not very convenient, in the documentation I found that i can use the -d flag to set a name for the folder in which building the project, but did not find how to separate html/css/js/imgs by folders.
Thanks in advance for any help.
I don't think that there is yet a plugin for parcel2 that will allow you to easily create svg sprites. The parcel-plugin-svg-sprite package you mentioned is for parcel 1, so it is not expected to work. (In general, you can expect parcel 2 plugins to conform to this naming scheme - packages that start with parcel-plugin are probably for parcel 1).
As a workaround, the easiest way to use svgs in a pug template built with parcel would be to use an <img> or an <object> tag with a src property, e.g:
img(src="../../icons/facebook.svg")
or
object(data="../../icons/facebook.svg")
Doing it this way, where the svg file is "external" has a few limitations(discussed in the docs), notably there will be an extra round trip to download each svg (this would be good for caching, but bad if there were hundreds of svgs on your site). Also, you can't style the svg with css from the surrounding document.
You can avoid the first limitation (extra server round trip) by using css background-image/background property with a data URL (see docs)
.pug file
.icon-test
.(s)css file
.icon-test {
background-image: url('data-url:../../icons/facebook.svg');
}
(In react-based projects there is a way to avoid both these limitations and get parcel to inject the SVG as inline JSX through the #parcel/transformer-react-svg plugin (see docs), but I'm not aware of a similar plugin (yet) for pug templates.)
You can control the structure of the output files in parcel's dist folder by writing a custom namer plugin. I explained how to do this in this answer.
The plugin developer for the first parcel made the build for the parcel v2, and I say thank you! Here is the plugin, tested it with html and pug, everything works! https://github.com/Epimodev/parcel-plugin-svg-sprite
On my TYPO3 v10 website I have some SVG icons in use, no problem.
I also have a few more complex SVG Figures (created with Inkscape), that I want to include in TYPO3 website. Of course I can upload the .svg files to the fileadmin/ folder, and link to them with the Text+Image (or Text+Media) Content Elements.
In the Backend, TYPO3 generates some fine png-thumbnails for preview. So far so good.
The file can be downloaded directly, from its fileadmin/images ... location.
However, inside web pages, my SVGs are not displayed as they should.
A lot of styling information gets removed from the SVG and I don't know where.
Here is a screenshot of the original vs corrupted image (as displayed in the TYPO3 frontend).
Here is a graphical diff that shows the difference between the figures.
It turns out that at some time during the rendering process, TYPO3 removes the values from the style="...." SVG attributes. See reddish boxes.
All my more complex SVGs look like the one on the right when embedded in TYPO3.
Here is the SVG if you want to try yourself: image on SVGshare.com
On the right, many style attributes have been set to style="".
but why?
It's Firefox, not TYPO3, who removes the style="..." attribute values. This seems to be a longstanding Firefox Issue, solved.
See Bugzilla Issue 1262842: [CSP] Blocks the use of style attributes inside SVG without generating console errors.
Look for "triply confusing" in the first comment.
Inline CSS styles can be a security Problem, and therefore Firefox has a Content-Security-Policy (CSP) in place, in order to correct this.
An explainer for the mitigation strategies, written jointly by professional Security Engineers is given in this Google Doc and in Gihub Repo (Content Security Policy), Issue 45, Further granularity of unsafe-inline styles.
Script inline attributes are a difficult subject to approach when it
comes to CSP, they have the same amount of power as any other script
element but they don’t have ways to be whitelisted, for example, by a
nonce or hash. This means that the actual content of the attribute is
mostly the only deciding factor.
I don't understand everything mentioned in these docs and discussions. Inline-style Elements seem to be vulnerable to XSS attacks, and then attacker can put CSS url() in there for instance.
Quick-and-dirty solution
Use Inkscape and save as "optimized SVG", and check the option "Convert CSS Attributes to XML attributes". See attached screenshot of the Inkscape Dialog (Linux).
This solution was proposed by a web-developer from the GIMP devteam.
TYPO3 9 introduced an SVG Sanitizer, which automatically modifies SVG files during "fileadmin upload time", meaning it removes any <style ...> elements from the uploaded SVG file.
In TYPO3 10 and later versions, this SVG Sanitizer is by default automatically set up via Symfony dependency injection via core's Services.yaml.
You can remove the SVG Sanitizer via your own site extension's Services.yaml, e.g. for your myextension/Configuration/Services.yaml:
services:
_defaults:
autowire: true
autoconfigure: true
public: false
# ...
# remove TYPO3's default-autowired SvgSanitizer, which tampers with filadmin uploaded SVGs (e.g. removes necessary <style> information)'
TYPO3\CMS\Core\Resource\Security\SvgEventListener: ~
The tilde (~) removes/overwrites the definition previously set up by core's Services.yaml ( https://symfony.com/doc/current/service_container/service_decoration.html ).
This seems to be a problem of your individual TYPO3 installation. I've just tested your SVG image in a brand new TYPO3 v10 installation and the image is rendered properly in backend and frontend.
Maybe you have some 3rd party extensions installed who postprocess the HTML output of TYPO3, e.g EXT:sourceopt or EXT:scriptmerger.
I am trying to use a 3rd party javascript control, Owl Carousel. The way I am reading the documentations is this:
In the zip file from Owl Carousel there is a folder called owlcarousel that contains the javascript and another folder that contains all the supporting files which need to be copied to /modules/base-accelerator/yacceleratorstorefront/web/webroot/_ui/responsive/common. Then I simply need to go into the javaScript.tag file and add this line towards the end of the file:
<script src="${commonResourcePathHtml}/owlcarousel/owl.carousel.min.js"></script>
Upon trying that, I get all sorts of loading errors and no images are display, even without using the control. So my question is:
What is the correct approach to include a 3rd party javascript?
Is there any way to control which pages actually get a javascript file or do simply ALL the pages get ALL the javascript includes?
See if "Storefront Web Application Deconstructed" will help: https://help.sap.com/viewer/4c33bf189ab9409e84e589295c36d96e/1905/en-US/8af03fda8669101491e4aac2acaeb2dd.html
web/webroot
_ui: Contains the JavaScript and CSS styling for the current theme.
shared/js: Shared JavaScript used by desktop and responsive pages.
responsive/common: Commonly used style sheets, JavaScript libraries and images.
responsive/theme-alpha: The blue theme definition.
responsive/theme-lambda: The black theme definition.
WEB-INF
_ui-src: Contains JS testing, full libraries, and the Less files used to generate the CSS for a theme.
common/tld: The tag library descriptor files for the CMS and ycommerce tags.
config: Spring application context files.
lib: The libraries required by the storefront.
messages: The localization files.
tags: The tags that are used within views.
views: The JSP pages, fragments and CMS components.
If I have something like the following:
The Manual
====================
Gregg Bolinger
v1.0, 2014-15
:doctype: book
:icons: font
:imagesdir: images
Preamble paragraph
include::chapter1.ad[]
include::chapter2.ad[]
I'd like so that each chapter renders in its own HTML file and is linked to from the TOC rather than everything being in a single book.html, for example. It seems to generate separate files already, but that's only because they are in the source directory. It is still combining everything into a single HTML page. I'm using the Gradle Asciidoctor plugin, if that helps to know.
Unless there's something in the gradle plugin that does chunked html, asciidoctor does not handle chunked output at the moment. It's on the list of things to do, but it hasn't been done. If you look at the issue, however, someone has create a custom script/converter to do it though, perhaps that will work for your case as well.
Using the asciidoctor-multipage extension, each chapter can be rendered in its own HTML file. The links in the TOC points to the respective HTML chapters rather than everything being in a single book.html. At the end of every HTML page, the extension also adds links to the next or previous page, as seen on this website.
Assuming you have already installed the asciidoctor, just do $ gem install asciidoctor-multipage in your command line to install the multipage extension.
After making your file-name.adoc with various chapters, $ cd to that folder and then do $ asciidoctor -r asciidoctor-multipage -b multipage_html5 -D test/out --backend multipage_html5 -a data-uri file-name.adoc. This command will embed any images in the file-name.adoc to the new .html files which will be saved in newly created test/out folder. I only tested this using Ubuntu 20.04.
As Sam Macharia answered, asciidoctor-multipage can achieve your goal.
Also, most Docbook toolchains let you control how content is "chunked" into HTML pages, including at the book, chapter, and section levels.
Antora is the "official" way to achieve your goal.
For a recent site, the client has 5 different brand styling colours. So to keep track of everything in the less files (which we use node to compile to one final css file), I've defined the colours as less variables and used the .button-variant() mixin to generate the styles. e.g.
#color-cta-light: #df134d;
#color-cta-dark: #860c2f;
#color-cta-background: #fcf7fa;
.btn-cta {
.button-variant(#ffffff, #color-cta-light, #color-cta-dark);
}
That works fine. However, I've done this with panels as well, and I've now ended up with an 11,000 line long css file. It is this long because we need the majority of the default Bootstrap styling (such as .btn styling) as well as my custom styles.
What I am wondering is, (and keeping it simply by using just buttons as an example) is there a good easy way to remove the lines in the css that pertain to the default Bootstrap button styling, i.e. btn-success, btn-warning, etc. By easy, I mean automatically. We're using the node lessc modules to compile the less files (using a grunt watcher), so I imagine whatever it is that would need to happen would be run after the compile.
Alternatively, should I just amend the default bootstrap mixins to do nothing, and use my own custom mixins? I feel like that should work but that would mean a bit of extra time each new version of Bootstrap (currently 3.1) spent making sure that the custom mixins are up to date.
What I'm hoping to end up with is a single stylesheet, with default button styling from button.less without the additional overload of unused CSS. With my understanding, it's not possible but I'm hoping there are some tools out there that I don't know of that would help my situation.
If I understand you correctly, looking at both your question and your comment to Bass Jobsen, you want to keep Bootstrap styling, but not for the "button styling."
I believe the LESS (reference) feature is still what you want, but just selectively applied.
Assuming you are using the "bootstrap.less" file, add the reference notation just before the "buttons.less" file, like so (I've elided much of the normal "boostrap.less" file for brevity):
// Core variables and mixins
#import "variables.less";
#import "mixins.less";
...
// Core CSS
...
#import (reference) "buttons.less";
// Components
...
// Utility classes
#import "utilities.less";
#import "responsive-utilities.less";
This will totally deactivate all classes from "buttons.less" from being generated in your output css code, but still keep those classes available for mixin purposes. Should you need a particular piece from that code, let us say you wanted to keep the base .btn class, then you would have to add it back into your css, like so:
.btn {
.btn;
}
The outer .btn will reform a class in your code, while the inner .btn will use the referenced "buttons.less" .btn to generate the code.
Using (reference) in this way lets you selectively remove aspects of boostrap by module, while keeping those aspects accessible for the rest of bootstrap and for any mixin uses you have for it. This is probably a preferable method if you desire to remove most of the code from a module (if you actually wanted to keep most of the code, it would probably be best to just let the unused portion remain and import it normally).
You can use import with reference:
#import (reference) "bootstrap.less";
#color-cta-light: #df134d;
#color-cta-dark: #860c2f;
#color-cta-background: #fcf7fa;
.btn-cta {
.button-variant(#ffffff, #color-cta-light, #color-cta-dark);
}
This will give you only the CSS for you button. (and some :before : after pseudo classes which seems a bug for me).