ontodev/droid

Revise how Workflow is written and rendered

Closed this issue · 6 comments

jamesaoverton commented

After a lot of thought, I want to rework how the Workflow section of a Makefile is translated into HTML for DROID.

The key difference is that I want to stop processing HTML a elements and process code elements instead. The main reason is that Markdown backticks read better in Makefiles than Markdown links. The secondary reasons are simplicity and consistency.

Old style:

### Workflow
#
# - [Build](all) stuff
# - [Run Script](./script.sh) 
# - [Commit](git commit)
# - [Directory](some/dir/)
# - [File](some/file.txt)

New style:

### Workflow
#
# - `make some-task` build
# - `./script.sh` some script
# - `git commit`
# - `some/dir/` some directory
# - `some/file.txt` some file

New result (mockup):

The current code renders the Workflow block to Markdown then searches for a elements and operates on them. Now I want to ignore a elements and look for code elements instead. The content of the code elements will be matched against the patterns below, and the code element will be replaced by a new a element styled as a Bootstrap button with a short label (from the Button column below).

  • Order: order in which patterns should be matched; first match is accepted
  • Button: a short label for the resulting button
  • Restricted: true if the user must be authorized in to press this button; if not authorized, the button should be disabled
  • Class: the Bootstrap class for the button
  • Pattern: regex for matching the code element contents (this is just rough)
Order Button Restricted Class Pattern Description
1 Run true btn-primary make (\w+) Run a Make task
2 Run true btn-primary ./(\w+) ?(.*) Run a local (CGI) script with arguments
3 [varies] true [varies] git (\w+) ?(.*) Run a git command*
4 Open false btn-success (\w+)/ Open a directory
5 Open false btn-success (\w+) Open a file

The git commands are a little trickier, but we already handle them properly: If the git command matches one of our buttons, then use the same label and colour. For example, git commit corresponds to our yellow "Commit" button.

People can still use Markdown links and arbitrary HTML in their Workflow blocks, and DROID should leave this content alone.

lmcmicu commented

Does this issue supersede #91?

lmcmicu commented

Further question: In the new style, is there a particular reason why we need to have text after the back-ticked code? It seems like there is already enough information in (for example)

`make some-task`

to be able to render:

Run some-task

And similarly for all of the others mentioned above.

jamesaoverton commented

That's a good suggestion. Let me think about it a bit more. It shouldn't require a big change to the code to implement that.

jamesaoverton commented

@lmcmicu has proposed ways to display some of the information in the code span as the link/button text, rather than just replacing it all with a simple verb. We'll try out his proposals.

Here are some edge cases and my opinions on them:

code button note edit
make IMP=false refresh-imports refresh-imports only show goals No, we don't support variables
make clean all clean all show multiple goals No, we only handle one task at time
build/file.ext file.ext show basename and extension (preferably a noun)
./src/view.py view show basename without extension (preferably a verb)
./src/view.py --foo=bar --bat=man view do not show arguments

[EDIT: I wrote a long rant here about command-line arguments in general, but @lmcmicu has convinced me that we should stick to CGI scripts and a restricted set of allowed arguments.]

For CGI scripts, the idea is that we allow a restricted set of arguments that map to query parameters. So --foo=bar --bat=man becomes ?foo=bar&bat=man. DROID will pass this as the QUERY_STRING to the CGI script. In order to support copy-paste from the Makefile to the command-line, the CGI script should also accept these as command-line arguments. That's a good idea that I wanted anyway. We'll provide examples on how to handle both sorts of input. The main design principle is "DROID is optional", but I don't mind bending that a little when it comes to CGI scripts.

lmcmicu commented

@jamesaoverton and I discussed this further a little earlier, and we decided that we will not be handling the first two cases (handling the IMP=false and clean all cases).

This is how it will work. When DROID sees something in backticks it will consider four possibilities:

  1. The code is in the form make <single-phony-target>. (No other way of invoking make is allowed)
  2. The code is in the form: ./some_script.sh [--foo=bar --bat=man ...](an "executable view")
  3. The code is in the form: build/file.ext (a "file view")
  4. The code is in the form: build/mydir/ (a "directory view").

Nothing else is supported.

  • 👍1
lmcmicu commented

I forgot the git actions. These are allowed too (as before).