Re: styling flexibility for definitions

[Gavin Smith]

On Thu, Oct 29, 2020 at 03:46:23PM -0700, Per Bothner wrote:
> The html output for definitions only allows for very limited css styling.
> 
> As an example of the kind of styling it would be nice to enable, in my Kawa 
> and
> DomTerm manuals I move the "category" to the right margin,
> as you can see examples of here:
> https://www.gnu.org/software/kawa/Composable-pictures.html
> 

I think it's worth supporting this with CSS if all it needs is adding
some element classes to the output.

> I wrote an experimental patch (see attachment) which adds some class
> and other attributes, and wraps the "CATEGORY: " in an element.
> 
> For example, this:
> 
>     @deffn Function dtutils.set_notebook_mode (@var{enable=True})
>     @deffnx Macro dt_set_notebook_mode (@var{enable=True})
>     Controls how auto-display works.
>     @end deffn
> 
> becomes:
> 
>     <dl class="definition">
>     <dt id="index-dtutils_002eset_005fnotebook_005fmode" class="synopsis" 
> category="Function"><span class="category">Function: </span>     
> <strong>dtutils.set_notebook_mode</strong> 
> <em>(<var>enable=True</var>)</em></dt>
>     <dt id="index-dt_005fset_005fnotebook_005fmode" class="synopsis" 
> category="Macro"><span class="category">Macro: </span>  
> <strong>dt_set_notebook_mode</strong>    
> <em>(<var>enable=True</var>)</em></dt>
>     <dd><p>Controls how auto-display works.
>     </p></dd></dl>

I don't think non-standard HTML attributes should be used so the
category="Function" part should be removed.

> 
> With those changes, I can add these css rules to achieve the
> effect of the link above:
> 
>     dt.synopsis[category]:after { float: right; padding-left: 2em; content: 
> "["  attr(category) "]" }
>     dt.synopsis span.category { display: none }
> 
> This is incomplete - it only handles @deffn and a few other definitions.
> Specifically, @deftypeop and similar that generate "{category} of {class}"
> would need an extra "of-class" attribute and a css rule like:
> 
> dt.synopsis[category][of-class]:after { float: right; padding-left: 2em; 
> content:  "["  attr(category) " of " attr(of-class) "]" }

This bit could be left undone if it would be awkward.

> Before I work on the missing pieces it would be nice to get some feedback on
> the basic approach.  My understanding of the code and of Perl is limited,
> and I'm sure this can be done more cleanly.

More comments below.

> diff --git a/tp/Texinfo/Convert/HTML.pm b/tp/Texinfo/Convert/HTML.pm
> index 082004a59c..51daf3f6d5 100644
> --- a/tp/Texinfo/Convert/HTML.pm
> +++ b/tp/Texinfo/Convert/HTML.pm
> @@ -4132,6 +4132,15 @@ sub _convert_def_line_type($$$$)
>      } else {
>        $category = '';
>      }
> +    my $category_text = "";
> +    my $category_attr = "";
> +    my $brk = " ";
> +    my $sep = "";
> +    if ($self->get_conf('deftypefnnewline') eq 'on') {
> +        $brk = "<br/> ";
> +        $sep = "\@*";
> +    }
> +

I can't see where $brk and $sep are used in the patch.  If deftypefnnewline
is on could the category be wrapped in <span class="category">
anyway?

Some of the class names could be made more specific, e.g. def-synopsis
instead of synopsis.

>      if ($command_name eq 'deffn'
>          or $command_name eq 'defvr'
>          or $command_name eq 'deftp'
> @@ -4145,14 +4154,15 @@ sub _convert_def_line_type($$$$)
>               or ($command_name eq 'deftypecv'
>                   and !$command->{'extra'}->{'def_parsed_hash'}->{'type'}))
>              and !$command->{'extra'}->{'def_parsed_hash'}->{'class'})) {
> +      $category_text = $category ? $$category{text} : '';
> +      $category_attr = " category=\"".$category_text."\"";
> +      $category_text = "<span class=\"category\">".$category_text.": 
> </span>";

The $$ looks wrong.

There is an _attribute_class function that could be used to output the
<span class="category">.

>        if ($arguments) {
> -        $tree = $self->gdt("{category}: \@strong{{name}} 
> \@emph{{arguments}}", {
> -                'category' => $category,
> +        $tree = $self->gdt("\@strong{{name}} \@emph{{arguments}}", {
>                  'name' => $name,
>                  'arguments' => $arguments});
>        } else {
> -        $tree = $self->gdt("{category}: \@strong{{name}}", {
> -                'category' => $category,
> +        $tree = $self->gdt("\@strong{{name}}", {
>                  'name' => $name});
>        }
>      } elsif ($command_name eq 'deftypefn'
> @@ -4286,7 +4296,7 @@ sub _convert_def_line_type($$$$)
>        }
>      }
> -    return "<dt$index_label>".$self->convert_tree({'type' => '_code',
> +    return "<dt$index_label 
> class=\"synopsis\"$category_attr>".$category_text.$self->convert_tree({'type' 
> => '_code',
>                               'contents' => [$tree]}) . "</dt>\n";

This approach looks right to me; splitting the "{category}" part away from
the argument of gdt and adding it to the output separately.

>    } else {
>      my $category_prepared = '';
> @@ -4360,7 +4370,7 @@ sub _convert_def_command($$$$) {
>    return $content if ($self->in_string());
>    #print STDERR "IIII $self $cmdname command $command args $args content 
> $content\n";
>    if (!$self->get_conf('DEF_TABLE')) {
> -    return "<dl>\n". $content ."</dl>\n";
> +    return "<dl class=\"definition\">\n". $content ."</dl>\n";
>    } else {
>      return "<table width=\"100%\">\n" . $content . "</table>\n";
>    }