API for listing style sheet parameters

[bertfrees]

For braille formatting, Pipeline supports Sass, a superset of CSS which can have parameters that the user can set via the Pipeline user interface.

Many of the braille scripts' options solely exist as a convenience for setting certain parameters, which may or may not actually be defined in the provided style sheets.

A generic option for setting any style sheet parameter also exists, but because of its genericness it is not very user friendly. This is the description of the option:

Style sheet parameters

A list of parameters passed to the style sheets.

Style sheets, whether they’re specified with the “stylesheets” option or associated with the source, may have parameters (Sass variables). The "stylesheet-parameters" option, which takes a list of parenthesis enclosed key-value pairs, can be used to set these variables.

For example, if a style sheet uses the Sass variable "foo":

@if $foo {
   /* some style that should only be enabled when "foo" is truthy */
}

you can control that variable with the following parameters list: (foo:true).

Possible values: A query

The syntax is as follows (described in terms of CSS grammar):

query
 : feature*
 ;
feature
 : '(' S* IDENT S* [ ':' S* value ]? ')' S*
 ;
value
 : string | integer | IDENT
 ;

Compare this with a dedicated option to set the specific parameter "show-braille-page-numbers":

Show braille page numbers

When enabled, will number braille pages.

Makes the variable $show-braille-page-numbers available in style sheets. In order to use the variable include a rule like the following in your custom style sheet:

@if $show-braille-page-numbers {
  @page {
    @top-right {
      content: counter(page);
    }
  }
}

This will create a page number in the top right corner of every braille page.

See the CSS specification for more info:

• the @page rule
• the counter() function

Possible values: true or false

Default value: true

As you can see, by making a dedicated option for this parameter, we are able to include documentation, which improves the usability a lot. However as you can also see, the effect of setting this option depends on the existence of a rule in the provided style sheet that actually does something with the $show-braille-page-numbers variable. Without such a rule, the option doesn't do anything! This is also not great, because it can be confusing. Moreover, there are several such options, and many options may overwhelm a user, so it would be good if we can only present options that actually do something.

Based on these observations, this is my proposal to improve the Pipeline API and user interface:

• Make the configuration of braille jobs a two-step process. In a first step, the user provides the input (content and style sheets) and sets a number of general options.

• The input is then sent to the Pipeline API for analysis, and a list of style sheet parameters is returned. This could perhaps be done using a format similar to the script XML format:

  <script id="dtbook-to-pef" href="...">
     <option name="..." nicename="..." desc="..." required="false" default="..."
             type="string" sequence="false" ordered="true"/>
     ...
  </script>

• In a second step, all the parameters declared in Sass style sheets are presented, after which the user can launch the job.

Ideally, the documentation of a style sheet parameter would be defined where the Sass variable is declared within the .scss file, so that it doesn't need to be done in XProc.

[bertfrees]

Done in https://github.com/daisy/pipeline-modules/commit/52185c89978114683350b0a27dbfa75b1c1144a1