docubricks / docubricksviewer Goto Github PK

Default instructions must appear after assembly instructions - just like in the editor.

It would be good to have a formal specification for the XML format - the readme file doesn't define everything, and can't be validated by XML validation tools.

Long projects do not currently have an option to jump back to the top and the menu does not float along on the site. A floating or fixt-at-bottom button to jump back up would help user-friendliness a lot.

Hello,
I'm working on the documentation for the OpenFlexure Microscope. This is a not-entirely-straightforward problem because there's quite a few different options (e.g. different cameras, different optics, different sizes) that need different assembly instructions. Feedback from more or less everyone who has assembled this is that I need specific documentation for each version of the microscope - it's not enough just to have alternative steps in the instructions. So, I'm trying to auto-generate the DocuBricks XML as part of my build process.
I'd love to be able to preview what I've done without spamming the DocuBricks website with many half-finished versions, and I've got as far as being able to view the bundled example with this repository on my PC. However, I can't find the code that turns my DocuBricks XML file into the (JSON?) "hiddendata" div in the HTML file that launches the viewer.
Is there code somewhere that might be able to do this?

Thanks,

Richard

When the DocuBricks document is loaded from JSON in viewertest.html, the document tree is represented by the classes in docubricks.ts, for example there is a Project inside which you find Brick instances, etc. - but if I look at the assembly instructions, everything is just plain"object", i.e. the assembly instructions are not StepByStepInstruction instances, and the steps are not AssemblyStep instances. Is this intentional?

I guess it doesn't matter because it all renders OK, but it means my nice direct-from-XML code is broken.

Currently, there are a number of smaller documentation viewing issues:
When loading the page, there is a safety related security issue – Error: This page loads scripts from unauthenticated sources, when creating an exception, the documentation style is still not rendered properly and the parts, bill of material, and author links overlap (see screenshot). Persists in multiple browsers.

Abstract of Bricks of show up twice: Once under the header abstract, and once as plain text under the Description. I hadn't noticed that before. Conformed on multiple browsers and projects.

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!

Richard: Sections - could the bill of materials summary come before the parts? That would nicely split the "bricks" from the "parts". Parts could even be displayed by "expanding" rows of the BoM table, which I'd find quite nice (though I guess it then prints less nicely - so maybe hyperlinks are better).