[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: styling flexibility for definitions
From: |
Gavin Smith |
Subject: |
Re: styling flexibility for definitions |
Date: |
Fri, 30 Oct 2020 07:13:02 +0000 |
User-agent: |
Mutt/1.9.4 (2018-02-28) |
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";
> }