Small/vertical draw-gap function
Swiftb0y opened this issue · 10 comments
Is your feature request related to a problem? Please describe.
Currently, variable length data is being represented by using the draw-gap function which creates a horizontal gap, allocating at least an entire row of space.
When generating diagrams that only contain a single row of fields, using draw-gap to indicate variable length data takes up much more space than justified for the diagram.
Describe the solution you'd like
I propose to add a function to create a gap spanning only a single couple of cells on a single row.
This could either be accomplished by letting the draw-gap function draw this version of the diagram when the cap doesn't span past the row or by splitting that function into two different functions (eg draw-large-gap and draw-small-gap or draw-vertical-gap and draw-horizontal-gap.
Additional context
The produced SVG would rougly look like the following ascii art (spanning only a single row):
+----------/ /--------+
| / / +
+--------/ /----------+
After reflecting on it, the problem I have with this idea is that it makes the address offsets on subsequent boxes in that row and the address offset labels on subsequent rows hard to understand. That is why the vertical gap resets the offset of the beginning of the next row to i+00, meaning “the first byte after the gap”. The intention of the existing gap is to mean an unknown number of bytes, which may be less than or greater than a row. So the intent is whenever there is an undetermined number of bytes of any length in the diagram, you use the horizontal gap.
If you can think of a way this can be handled with a vertical gap, I will happily consider it, but the savings in space in the diagram would not be that large.
Ah, I just read a part of your description I missed, 🤦♂ You are talking about single-row diagrams. Yes, absolutely, this would be useful there. And easy to add in that case. But perhaps I would want to have the generator throw an exception if you then tried to move on to a new row.
You would also need to be careful to avoid drawing column headers for such diagrams.
Of course, but I think we can trust users with using this responsibility.
Quick example where this would be useful in my CDJ HID Protocol documentation. The last primitives describes a TLV structure but using draw-gap for the Value obviously bloats it.
I agree completely, I was just thinking aloud (or visibly, I suppose). 😄 This will be easy to implement, I will try to get to it this evening. Also, other projects are already pulling in bytefield-svg, so I would like to get improvements in quickly.
I forgot to mention, it would be great if the small draw-gap function was able to display text as well.
Where would it put the text? That would probably need to be configurable.
Well either left or right from the gap. But since the text in the current horizontal draw-gap is above the actual gap, it would probably be fine to force it to the left of the gap (for the vertical gap) as well.
In the end I decided to leave the text out; you draw it by drawing an open-ended box either before or after the gap, and labeling that.
You can see an example in the master branch of the language guide: https://bytefield-svg.deepsymmetry.org/bytefield-svg/funcs.html#draw-gap-inline