From 5013e8f1f3f38c47bce469cb2af7eae9bf6c18b3 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 1/4] WebAssets: Fix interdoc links --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index 232162e..f765122 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -4,11 +4,11 @@ *Web Assets* are any static content that are shipped intact to web browsers, usually by web applications. These might be user interface frameworks, Flash video players, CSS frameworks, icon libraries, or lots of other possibilities. -If your package is primarily or solely shipped to a browser and not used locally, and is not JavaScript, it probably falls under these guidelines. JavaScript packages must follow the Packaging:JavaScript[JavaScript guidelines] in addition to these guidelines. +If your package is primarily or solely shipped to a browser and not used locally, and is not JavaScript, it probably falls under these guidelines. JavaScript packages must follow the xref:JavaScript.adoc[JavaScript guidelines] in addition to these guidelines. == Rationale -There are lots of little bits shipped to browsers that aren't just JavaScript that typically have been bundled along with web applications up to this point. Packaging:JavaScript#Rationale[There are a lot of good reasons why we shouldn't bundle JavaScript this way], so it only follows that we should fix it for the rest of that kind of stuff too. +There are lots of little bits shipped to browsers that aren't just JavaScript that typically have been bundled along with web applications up to this point. xref:JavaScript.adoc#_bundling_of_other_libraries[There are a lot of good reasons why we shouldn't bundle JavaScript this way], so it only follows that we should fix it for the rest of that kind of stuff too. == BuildRequires @@ -60,7 +60,7 @@ Regardless, web applications may want to make subdirectories of `+%{_webassetdir == Content Guidelines -Web Assets must follow the general guidelines for Packaging:Guidelines#CodeVsContent[content], unless stated otherwise in this document. +Web Assets must follow the general guidelines for xref:WhatCanBePackaged.adoc[what can be packaged], unless stated otherwise in this document. == CSS @@ -70,13 +70,13 @@ Pure CSS frameworks can be included as-is. CSS frameworks that use an alternativ Flash files (which typically use the `+.swf+` extension) must follow the general and licensing guidelines for code, not content, and must be built from source using a toolchain available in Fedora. -The Flash software needs to be compiled by a free software toolchain, such as `+swfc+`. Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] That compilation must be performed as part of the build process for the package. +The Flash software needs to be compiled by a free software toolchain, such as `+swfc+`. xref:WhatCanBePackaged.adoc#prebuilt-binaries-or-libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] That compilation must be performed as part of the build process for the package. If the flash software is not compilable using the toolchains inside of Fedora then the flash software cannot be shipped. In some cases you may be able to patch out use of the flash software (for instance, if it's a fallback in case the browser doesn't support HTML5) or you may have to give up on packaging the software until the flash software toolchain is enhanced to allow building. == Java applets -Java applets should follow the general and licensing guidelines for code, not content. Additionally, they should follow the Packaging:Java[Java guidelines], with the exception that the actual `+.jar+` file for the Java applet should be installed into a subdirectory of `+%{_webassetdir}+`. +Java applets should follow the general and licensing guidelines for code, not content. Additionally, they should follow the xref:Java.adoc[Java guidelines], with the exception that the actual `+.jar+` file for the Java applet should be installed into a subdirectory of `+%{_webassetdir}+`. == Images From 8684de54635fe169221188011099c0fa010dd0cb Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 2/4] Web Assets: Adoc code blocks don't need escaping --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index f765122..65bd4d1 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -53,7 +53,7 @@ All HTTP daemons in the distribution should make `+%{_webassetdir}+` available i Therefore, if the `+fabulous-web-icons+` package ships an icon as `+%{_webassetdir}/fabulous-web-icons/important.png+`, you can include it in a web application with the following HTML: .... -<img src="/.sysassets/fabulous-web-icons/important.png"> + .... Regardless, web applications may want to make subdirectories of `+%{_webassetdir}+` available under their own directory via aliases or symlinks for compatibility purposes or to eliminate needless deviation from upstream. From 569c109aedbe41cad914c5214dd1be4f7a113467 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 3/4] Web Assets: Semantic newlines --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index 65bd4d1..2cd8226 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -2,17 +2,31 @@ == Scope -*Web Assets* are any static content that are shipped intact to web browsers, usually by web applications. These might be user interface frameworks, Flash video players, CSS frameworks, icon libraries, or lots of other possibilities. - -If your package is primarily or solely shipped to a browser and not used locally, and is not JavaScript, it probably falls under these guidelines. JavaScript packages must follow the xref:JavaScript.adoc[JavaScript guidelines] in addition to these guidelines. +*Web Assets* are any static content that are shipped intact to web browsers, +usually by web applications. +These might be user interface frameworks, +Flash video players, CSS frameworks, icon libraries, +or lots of other possibilities. + +If your package is primarily or solely shipped to a browser +and not used locally, and is not JavaScript, +it probably falls under these guidelines. +JavaScript packages must follow the +xref:JavaScript.adoc[JavaScript guidelines] +in addition to these guidelines. == Rationale -There are lots of little bits shipped to browsers that aren't just JavaScript that typically have been bundled along with web applications up to this point. xref:JavaScript.adoc#_bundling_of_other_libraries[There are a lot of good reasons why we shouldn't bundle JavaScript this way], so it only follows that we should fix it for the rest of that kind of stuff too. +There are lots of little bits shipped to browsers +that aren't just JavaScript +that typically have been bundled along with web applications up to this point. +xref:JavaScript.adoc#_bundling_of_other_libraries[There are a lot of good reasons why we shouldn't bundle JavaScript this way], +so it only follows that we should fix it for the rest of that kind of stuff too. == BuildRequires -To ensure the presence of the necessary RPM macros, all packages that provide web assets must have: +To ensure the presence of the necessary RPM macros, +all packages that provide web assets must have: .... BuildRequires: web-assets-devel @@ -20,13 +34,15 @@ BuildRequires: web-assets-devel == Requires -To ensure the availability of the necessary directories, all packages that provide web assets must have: +To ensure the availability of the necessary directories, +all packages that provide web assets must have: .... Requires: web-assets-filesystem .... -Web application packages that ship configuration files for Apache HTTPd should ensure that the httpd configuration is installed as well: +Web application packages that ship configuration files for Apache HTTPd +should ensure that the httpd configuration is installed as well: .... Requires: web-assets-httpd @@ -42,50 +58,99 @@ Requires: web-assets-httpd == Install Location -All packages that contain static content useful to different web applications must install into a subdirectory of `+%{_assetdir}+`. For instance, the `+jquery-ui+` package should install itself into `+%{_webassetdir}/jquery-ui+`. +All packages that contain static content useful to different web applications +must install into a subdirectory of `+%{_assetdir}+`. +For instance, +the `+jquery-ui+` package should install itself into +`+%{_webassetdir}/jquery-ui+`. -All packages that contain static content that is only useful within the package in which they are shipped should continue to ship that content in the application's directory structure. However, they must follow the remainder of the guidelines outlined in this document. +All packages that contain static content +that is only useful within the package in which they are shipped +should continue to ship that content in the application's directory structure. +However, they must follow the remainder +of the guidelines outlined in this document. == Server Location -All HTTP daemons in the distribution should make `+%{_webassetdir}+` available in `+/.sysassets+`. +All HTTP daemons in the distribution +should make `+%{_webassetdir}+` available in `+/.sysassets+`. -Therefore, if the `+fabulous-web-icons+` package ships an icon as `+%{_webassetdir}/fabulous-web-icons/important.png+`, you can include it in a web application with the following HTML: +Therefore, if the `+fabulous-web-icons+` package +ships an icon as `+%{_webassetdir}/fabulous-web-icons/important.png+`, +you can include it in a web application with the following HTML: .... .... -Regardless, web applications may want to make subdirectories of `+%{_webassetdir}+` available under their own directory via aliases or symlinks for compatibility purposes or to eliminate needless deviation from upstream. +Regardless, web applications may want to +make subdirectories of `+%{_webassetdir}+` available +under their own directory via aliases or symlinks +for compatibility purposes or to eliminate needless deviation from upstream. == Content Guidelines -Web Assets must follow the general guidelines for xref:WhatCanBePackaged.adoc[what can be packaged], unless stated otherwise in this document. +Web Assets must follow the general guidelines +for xref:WhatCanBePackaged.adoc[what can be packaged], +unless stated otherwise in this document. == CSS -Pure CSS frameworks can be included as-is. CSS frameworks that use an alternative language that compiles to CSS, such as https://lesscss.org/[LESS], must compile to CSS as part of the build process. It is not acceptable to include pre-compiled CSS in Fedora packages. +Pure CSS frameworks can be included as-is. +CSS frameworks that use an alternative language that compiles to CSS, +such as https://lesscss.org/[LESS], +must compile to CSS as part of the build process. +It is not acceptable to include pre-compiled CSS in Fedora packages. == Flash -Flash files (which typically use the `+.swf+` extension) must follow the general and licensing guidelines for code, not content, and must be built from source using a toolchain available in Fedora. +Flash files (which typically use the `+.swf+` extension) +must follow the general and licensing guidelines for code, +not content, and must be built from source +using a toolchain available in Fedora. -The Flash software needs to be compiled by a free software toolchain, such as `+swfc+`. xref:WhatCanBePackaged.adoc#prebuilt-binaries-or-libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] That compilation must be performed as part of the build process for the package. +The Flash software needs to be compiled by a free software toolchain, +such as `+swfc+`. +xref:WhatCanBePackaged.adoc#prebuilt-binaries-or-libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] +That compilation must be performed as part of the build process for the package. -If the flash software is not compilable using the toolchains inside of Fedora then the flash software cannot be shipped. In some cases you may be able to patch out use of the flash software (for instance, if it's a fallback in case the browser doesn't support HTML5) or you may have to give up on packaging the software until the flash software toolchain is enhanced to allow building. +If the flash software is not compilable using the toolchains inside of Fedora +then the flash software cannot be shipped. +In some cases you may be able to patch out use of the flash software +(for instance, if it's a fallback in case the browser doesn't support HTML5) +or you may have to give up on packaging the software +until the flash software toolchain is enhanced to allow building. == Java applets -Java applets should follow the general and licensing guidelines for code, not content. Additionally, they should follow the xref:Java.adoc[Java guidelines], with the exception that the actual `+.jar+` file for the Java applet should be installed into a subdirectory of `+%{_webassetdir}+`. +Java applets should follow the general and licensing guidelines for code, +not content. +Additionally, they should follow the xref:Java.adoc[Java guidelines], +with the exception that the actual `+.jar+` file for the Java applet +should be installed into a subdirectory of `+%{_webassetdir}+`. == Images -Images that are part of a larger Web Asset package can be included in that package's subdirectory. For instance, a UI library might contain images for its UI components in its subdirectory. +Images that are part of a larger Web Asset package +can be included in that package's subdirectory. +For instance, a UI library might contain images for its UI components +in its subdirectory. -Web Asset packages that consist solely of images, such as a set of icons, may be shipped as their own package. +Web Asset packages that consist solely of images, +such as a set of icons, may be shipped as their own package. == Fonts -All system fonts (available in `+%{_datadir}/fonts+`) are automatically made available in `+%{_webassetdir}/fonts/+` via a symlink. For more information on packaging system fonts, see the xref:FontsPolicy.adoc[font guidelines]. Please note that [Web_Assets/Fonts|only fonts available in the Fedora package collection are made available on HTTP servers by default]. +All system fonts (available in `+%{_datadir}/fonts+`) +are automatically made available in `+%{_webassetdir}/fonts/+` via a symlink. +For more information on packaging system fonts, +see the xref:FontsPolicy.adoc[font guidelines]. +Please note that only fonts available in the Fedora package collection +are made available on HTTP servers by default. + +Please note that those guidelines prohibit packaging fonts elsewhere. +There is no compelling reason to support other font formats, +as most browsers that support web fonts +support the TTF or OTF formats used by system fonts, +therefore alternative web font formats like WOFF are prohibited. -Please note that those guidelines prohibit packaging fonts elsewhere. There is no compelling reason to support other font formats, as most browsers that support web fonts support the TTF or OTF formats used by system fonts, therefore alternative web font formats like WOFF are prohibited. From fcfaded2c17d148e7b1422990ea109d4fb8421cd Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 4/4] WebAssets: Tag specfile code blocks as rpm-spec --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index 2cd8226..e2a7d7c 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -28,25 +28,28 @@ so it only follows that we should fix it for the rest of that kind of stuff too. To ensure the presence of the necessary RPM macros, all packages that provide web assets must have: -.... +[source, rpm-spec] +---- BuildRequires: web-assets-devel -.... +---- == Requires To ensure the availability of the necessary directories, all packages that provide web assets must have: -.... +[source, rpm-spec] +---- Requires: web-assets-filesystem -.... +---- Web application packages that ship configuration files for Apache HTTPd should ensure that the httpd configuration is installed as well: -.... +[source, rpm-spec] +---- Requires: web-assets-httpd -.... +---- == RPM Macros