API for listing style sheet parameters
Closed this issue · 1 comments
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:
Possible values:
true
orfalse
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.
Done in daisy/pipeline-modules@52185c8