Re: [PATCH 4/5] www: allow specifying CSS @import or <link> tags

["Štěpán Němec" <stepnem@smrk.net>]

On Thu, 26 Sep 2024 00:55:04 +0000
Eric Wong wrote:

[...]

> diff --git a/Documentation/public-inbox-config.pod b/Documentation/public-inbox-config.pod
> index 50746b21..e968bc49 100644
> --- a/Documentation/public-inbox-config.pod
> +++ b/Documentation/public-inbox-config.pod
> @@ -255,13 +255,21 @@ Default: :all
>  
>  =item publicinbox.css
>  
> -The local path name of a CSS file for the PSGI web interface.
> -May contain the attributes "media", "title" and "href" which match
> -the associated attributes of the HTML <style> tag.
> -"href" may be specified to point to the URL of a remote CSS file
> +The local path name of a CSS file for the PSGI web interface.  May
> +contain the attributes C<media>, C<title> and C<href> which match the
> +associated attributes of the HTML C<E<lt>styleE<gt>> tag.
> +
> +As of public-inbox 2.0+, C<load> may be C<link> or C<import>;
> +C<link> forces the use of a C<E<lt>linkE<gt>> tag and disable inlining
                                                         ^^^^^^^
disables

I admit that reading this I had no idea what this was
talking about at first, as in, local path name "may contain
attributes"?  Looking at the code, it seems somewhat in the
style of gitattributes(5), plus you handle single-quoted
string values (i.e., embedded spaces), unlike git (looking
at attr.c:parse_attr).

I wonder if a bit of hand-holding (AKA documentation)
could/should be provided here?

Perhaps, if I understand the behavior correctly:

  The local path name of a CSS file for the PSGI web interface.
  Space-separated attributes (C<key=val> or C<key='val with spaces'>)
  may be specified after the path on the same line; C<media>, C<title>
  and C<href> are currently supported, and match the associated attributes
  of the HTML C<E<lt>styleE<gt>> tag.
  
  public-inbox 2.0+ also supports a C<load> attribute with values
  C<link> or C<import>; C<link> forces the use of a C<E<lt>linkE<gt>> tag
  and disables inlining [...]

> +CSS into the C<E<lt>styleE<gt>> tag while C<import> puts CSS C<@import>
> +statements into the C<E<lt>styleE<gt>> tag.  C<import> appears necessary
> +for some browser and C<media> query combinations.
> +C<href> may be specified to point to the URL of a remote CSS file
>  and the path may be "/dev/null" or any empty file.
> +
>  Multiple files may be specified and will be included in the
> -order specified.
> +order specified, but files specified via C<load=import> are
> +always handled first.

[...]

-- 
Štěpán