Detailed info about templates in templates list view

[bertfrees]

Info would include:

• A description
• "Input files and parameters", presented in the same compact way as at the bottom of a job page

[josteinaj]

A description

I'm not sure what the best way to implement this is, but I'm sure I can find a solution. Maybe add support to clientlib-java for attaching key/value metadata to jobs.

Input files and parameters

This can potentially take up a lot of space though... How many options do you think we'll end up with in the final script?

[bertfrees]

Maybe add some sort of folding? Because also a description can potentially take up a lot of space.

[josteinaj]

Good idea. A toggle for showing description + parameters.

[bertfrees]

+1 from @stesk

[bertfrees]

@stesk said:

What seems essential to me is that the system should be able to "expand" templates so as to show their content: what values they contain for which options, and which CSS files are included. In this way it should be possible for a more technically minded person to understand and possibly fix potential issues in production, provided that the developer documentation (of configurable options and CSS) is somewhat readable. Ideally this should be available in the UI, but I guess it could also be done by looking at the files (which reminds me that I need to ask Jostein where they are located).

[bertfrees]

Steffen also said in that email:

[...] I was also thinking that a relatively easy way of giving the end user at least some information would be to parse a subset the CSS contained in templates and display it in pretty print somewhere. The user would then be able to see basic properties like page dimensions, paragraph indentation, prefixes for various inline elements and so on. [...] An alternative would be to shift this responsibility to those creating the templates by allowing a simple comment field which could contain whatever information the template designer deems relevant.

In my response, I said that it probably far easier to make this the responsibility to the template author, who should be able to attach documentation files to the templates and somehow tag one (HTML) file as "main description". The benefits of HTML files over simple comment fields in a database table are obvious.

[josteinaj]

So do we want here the ability to upload and download generic files (DOCX for instance) to be used as documentation for templates? Or restrict it to HTML (more difficult to author, easier to parse)? And is this supposed to be retrieved and displayed in the templates listing? Can there be multiple files?

To simplify, I would rather suggest having only a plaintext field for writing template documentation in the web ui, and maybe also a URL field where you can put a link to more documentation stored wherever you want, for instance on the organizations intranet. That would match what we already do for scripts; which can have a plaintext description and a URL to more script documentation.

I think @stesk's idea of parsing a subset of the CSS is cool, but it might require a bit more work and I'm not sure if we can agree across organizations on what properties to display. We would achieve the same if the CSS properties we are interested in are exposed as script options.

(Also by the way, the templates are not stored in a database.)

[bertfrees]

Yes I was mainly thinking about HTML, not so much DOCX (shiver down spine). We could allow multiple files so the main page could have links to the other pages, but one page would already be more than enough.

I think we shouldn't limit ourselves just to get the simplest solution possible. And HTML doesn't have to add much complexity. HTML can be stored in the same way as plain text (it's just a string, at least if you don't allow relative links to images and other pages) and rendering it couldn't be easier when you're in a browser environment.

An approach that would match what we do for scripts makes perfect sense. However I find the documentation possibilities for scripts a tiny bit limiting. You can argue that since you can have a link to an external page you have all the freedom you need. But being able to have the documentation right within the user interface, possibly mixed with the option fields, also has its benefits. Also a downside of externally linked documentation is that those external pages must ideally never change and never taken offline because you could run old versions.

The question is: why a plain text field and a URL field when you could have a single field that can include the URL or anything else you want if any HTML is allowed? Especially because in the XProc file we are already using HTML+RDFa (i.e. exactly what I would like in the UI), parsing it and extracting plain text fields on the server seems backward, and also confusing because we are omitting certain parts. Why do we do this? The answer is to make it easier for user interfaces that don't support HTML (I guess). That's a perfectly valid reason for scripts but not really for templates because templates are a web UI feature. In other words, trying to be consistent between script and template documentation limits the possibilities for templates for reasons that only apply to scripts.

I suggest the following: could we have a combination of rich descriptions (not external and ideally one for each port and option as well) plus simple plain text descriptions for clients that need it? Something like HTML alt vs. longdesc?

At least for templates I think it's worth considering because there's nothing really stopping us from supporting HTML, technically. (For scripts it might be some more trouble because the web API needs to change.)

Related: https://github.com/daisy/pipeline-webui/issues/32

[josteinaj]

You're right, HTML seems pretty tempting.

I'm just worried about how the documentation should be authored and maintained? Say you create a new template, and you want to add some documentation to it. Wouldn't adding a text-editor that stores its content as HTML into the Web UI require too much work?

[bertfrees]

I hadn't thought about authoring yet. But I wouldn't worry about it too much. Main point is that we have a way to include documentation, how we create it is secondary. I would already be happy if I could just upload a template (https://github.com/daisy/pipeline-webui/issues/38) with documentation attached. If we want to have a user interface I think the most straightforward way is to do it exactly as we would do with plain text, and allow HTML in the documentation string value. Or markdown instead of HTML. And if you want to make it fancy you add a "preview" button. The alternative is to let the user tag certain uploaded files as "documentation".