Re-design the API of new feature "alternate line color"

[muzimuzhi]

To improve the usability of the feature suggested in #8 , I am re-thinking the options and the beneath logic of the general highlight feature. The re-designed options

• use option highlight-lines to choose which highlight mode is used
• use option highlight-line-numbers to toggle whether highlight the line number part
• use three color options to specify corresponding colors, and these color options all have default values

This is only a design- and pseudo-level discussion, therefore the actual package code in my forked repo is not modified yet.

Original

Options

 - highlight-lines = <empty> | <selected lines>
    - default value <empty>
 - highlight-color = <color>
    - default value `LightCyan`

Logic

if (hightlight-lines is <empty>) then
    normal
else
    highlight <selected lines> in <color>
fi

Final

Options

(Modified)
 - highlight-lines = <empty> | <selected lines> | <alternate>
    - default value <empty>
 - highlight-color = <line color> | {<line color>, <line number color>}
    - default value `{LightCyan, LightYellow}`
(Added)
 - highlight-line-numbers = <boolean value>
    - default value `false`
 - highlight-odd-line-color = <odd line color> 
                | {<odd line color>, <odd line number color>}
    - default value `{LightCyan, LightYellow}`
 - highlight-even-line-color = <even line color> 
                | {<even line color>, <even line number color>}
    - default value `{LightCyan!60, LightYellow!60}`

Logic

if (highlight-lines is <empty>) then
    normal
else if (highlight-lines is <selected lines>) then
    if (line-number is typeset && highlight-line-numbers is `true`) then
        highlight <selected lines> in <line color>, 
          with line numbers in <line-number-color>
    else
        highlight line of <selected lines> in <line color>
    fi
else // (highlight-lines is <alternate>)
    if (line-number is typeset && highlight-line-numbers is `true`) then
        highlight odd lines in <odd-line-color>, even lines in <even-line-color>, 
          with line numbers in corresponding colors
    else
        highlight odd lines in <odd-line-color>, even lines in <even-line-color>
    fi
fi

Notes

1. To keep names of options clear, inter-word dashes are used.
2. By some searching, I think the phrase alternate rows is more popular than zebra effect, the following one is used in issue minted/#211.
3. We still need option linenumbersep, but its function is off-topic to this issue, so it's absent in the current issue.

[muzimuzhi]

This maybe an over-design, but what if we need an effect of highlight line number part only?

This may leads to an option highlight-part, substituting highlight-line-numbers. The new one could be designed as

 - highlight-part = <none> | <line> | <line number> | <both>

Also a new name, highlight-mode, of the option highlight-lines may be more appropriate.

[muzimuzhi]

Starting from option highlight-part, I came up with the following design:

Options

 - highlight-lines = <empty> | <selected lines> | <alternate>
    - default value <empty>
 - highlight-part = <line> | <line number> | <both>
    - default value <line>
 - background-color = <back line color> | {<back line color>, <back num color>}
    - default value {white, white}
 - foreground-color = <fore line color> | {<fore line color>, <fore num color>}
    - default value {LightCyan, white}

Explanations

• highlight-lines controls which highlight mode is chosen.
• highlight-part controls which part of each line will be highlighted.
• The rest two color-specify options introduce concepts background color and foreground color. This way, the new feature has relations to \FancyVerbHighlightLineFirst and its relatives.

Other considerations

• With back- and fore-ground colors, the demand, which wants to using more than two colors to highlight lines, will not be satisfied. In my point of view, this demand is rare.
• A more universal api would be highlight = {<selected lines> | <mode name>}{<line color> | <line number color>}. Here <mode name> could be even, odd, and others, and multiple usage of option hightlight would allow multiple (even more than two) sets of colors.
• Using white color as default color, other than empty color, may helps to unify implementation of highlight related code, but it may cause some problems if the option bgcolor from package minted is used. This is just a guess.

[gpoore]

I'd suggest highlightlines for lines and highlightnumbers for numbers. Within a given environment, someone may want to highlight some lines of code and also some line numbers, perhaps with no overlap between the two. That won't be possible if highlightlines governs all highlighting, at least not without a lot of additional complexity (basically, checking for how highlightpart is defined for each line). When highlightlines and highlightnumbers are identical, it should be possible to allow something like highlightnumbers=highlightlines or highlightlines=highlightnumbers.

I'm unclear about the distinction between background and foreground colors. When would each be used?

The default color must be none. A default white would give unexpected results with bgcolor, but also could conflict with page colors other than white, which are common in beamer slides, etc.

For the zebra effect (that term may be best just for the shorter spelling), I'd suggest highlightzebracolors={<odd_color>, <even_color>}. Whichever of highlightcolor and highlightzebracolors is used most recently has precedence. Similarly, highlightnumberszebracolors={<odd_color>, <even_color>}, with highlightnumberscolor vs. highlightnumberszebracolors. Things like highlightnumberszebracolors=highlightzebracolors would ideally be allowed.

It may be good to go ahead and define numbercolor and numberzebracolors to set the colors of the numbers themselves.

I don't think there's a need to allow for more than all colors the same, or zebra. That should cover the majority of standard cases. Anything more will probably introduce a lot of complexity.

I'm still thinking about whether any special options for the First/Middle/Last/Single cases are needed, and if so, what the order of precedence would look like.

[muzimuzhi]

Your response makes things much more clear. Thanks.

---

I'm unclear about the distinction between background and foreground colors. When would each be used?

It is supposed that if line a is in highlightlines, highlight it in foreground color. Otherwise, highlight it in background color.