search

DocuBricks / docubricksViewer

1 stars 3 forks source link

Markdown or HTML in text fields #6

Open rwb27 opened 7 years ago

rwb27 commented 7 years ago

I have lots of feature requests, but this is probably the most important one: it would be fantastic to be able to include formatting (bold, newlines, lists, and hyperlinks) in the text for each step, and the other text fields. This would require a change to the file format so, while I'm happy to update the viewer to make this possible, it would be really great to discuss with Tobey and the team which option is best. I see two viable ways of doing it:

  1. Markdown (or similar), which has some advantages:
    • Easy to write
    • Human-readable in plain text
    • Doesn't confuse the XML parser (still shows up as a string) Markdown also has some disadvantages:
    • No longer specified by an XML format (assuming at some point there will be a formal XML spec)
    • Requires some white space preservation, which isn't normal in XML docs
  2. HTML tags in descriptions. The primary advantages are:
    • Unambiguous specification
    • It's valid XML and can be included in the DocuBricks format The disadvantage is that it's less human-readable and could open security holes

I would propose that the XML specification is amended to allow a small subset of HTML tags in what are currently multiline text fields (the <description> and <long_description> elements). This can be converted to and from markdown for easy GUI editing (see the bottom example on the react page or to-markdown). A decent working selection of tags would be <b>, <i>, <u>, <em>, <a>, <br>, <ul>, <ol>, <li>, <p> although of course more could be added later. I'm not sure if <p> is a good idea or not - if it's allowed, then it suggests everything should be in a paragraph for consistency...

As a bonus, doing it this way doesn't constrain us to just what markdown allows - for example we could introduce a tag that highlights some text with a little warning icon, as commonly seen in instruction manuals.

As and when I get time, I might make a start on this approach - I am very open to being steered, however, because the last thing I want to do is diverge from the standard!

rwb27 commented 7 years ago

I'm probably going to go for HTML, and might implement this in the next month or two...

rwb27 commented 6 years ago

I've now done this in my fork of the viewer - you can check it out at http://rwb27.github.io/openflexure_microscope/docubricks/current_master_version.html

Currently the descriptions of assembly steps in bricks, and the abstract, note, and long description of bricks are allowed to contain a small selection of safe-looking HTML tags (see the function I added to docubricksviewer.tsx). This should be fairly trivial to extend to other blocks of text.

I have an issue on my fork with more details.

MakerTobey commented 6 years ago

This would be super useful also for others users entering a lot of Meta information in a project. We should integrate these capabilities asap.

MakerTobey commented 4 years ago

This topic is now high priority. DocuBricks documentations should become portable and editable in other formats and web-platforms.