jomaway / typst-bytefield Goto Github PK

Thanks for this nice package. Much appreciated. I did not see in the documentation of bytefield that one should disable equation numbering for the bytefields. The alignment the implementation relies on breaks the display otherwise. The disablement approach works for me, but maybe a hint in the documentation or some change in implementation might help others too.

An example (not minimal, but using the official example):

#import "@preview/bytefield:0.0.6": *
== Bytefields

Bytefields seem to get squashed into mostly a vertical line and center text 
when `numbering` attribute of `math.equation()` is set e.g. to "(1)".

#set math.equation(block: false, numbering: "(1)")
// comment out the next line to see the example break with numbering of equations:
#set math.equation(block: false, numbering: none)

#bytefield(
// Config the header
bitheader(
"bytes",
// adds every multiple of 8 to the header.
0, [start], // number with label
5,
// number without label
12, [#text(14pt, fill: red, "test")],
23, [end_test],
24, [start_break],
36, [Fix], // will not be shown
angle: -50deg, // angle (default: -60deg)
text-size: 8pt, // length (default: global header_font_size or 9pt)
),
// Add data fields (bit, bits, byte, bytes) and notes
// A note always aligns on the same row as the start of the next data field.
note(left)[#text(16pt, fill: blue, font: "ITC Franklin Gothic Std", "Testing")],
bytes(3,fill: red.lighten(30%))[Test],
note(right)[#set text(9pt); #sym.arrow.l This field \ breaks into 2 rows.],
bytes(2)[Break],
note(left)[#set text(9pt); and continues \ here #sym.arrow],
bits(24,fill: green.lighten(30%))[Fill],
group(right,3)[spanning 3 rows],
bytes(12)[#set text(20pt); *Multi* Row],
note(left, bracket: true)[Flags],
bits(4)[#text(8pt)[reserved]],
flag[#text(8pt)[SYN]],
flag(fill: orange.lighten(60%))[#text(8pt)[ACK]],
flag[#text(8pt)[BOB]],
bits(25, fill: purple.lighten(60%))[Padding],
// padding(fill: purple.lighten(40%))[Padding],
bytes(2)[Next],
bytes(8, fill: yellow.lighten(60%))[Multi break],
note(right)[#emoji.checkmark Finish],
bytes(2)[_End_],
)

Thanks again for sharing the code.

PS: I tested using typst 0.11.1.

During the refactor a first draft of the bitheader api was introduced. But this has still some rough edges which needs to be fixed.

If this is done we are mostly ready for a v0.0.4 release.

The number spacing seems a little off to me. For example:

The 0 and 31 are pretty close to directly over their lines, but the other numbers are pretty clearly to the right of the line.

I think it would be better if each number was centered over that bit's position. I think most numbers are, it just seems like the outside numbers are not

Add possibility to set the headers background color, to create even more beautiful outputs.

regarding our placement
it could be practical to have special grid variable that holds the various grids and a mapping from positions to cell ids.
this would essentially be the final layout.

let grid = (
  center: (
    "(0,0)":0,
    "(1,0)":1,
    ...
  ),
  left: ( ... ),
  ...
)

this would make a neighbor search trivial, which we need when we are tackling borders.
and even more important, could warn us of any layout problems way before tablex,
which would allow us to annotate any errors and generate sexy debug stuff like mapping ids into a visual grid

Originally posted by @nopeslide in #13 (comment)

The import shown in the README does not work for me:
#import "@preview/bytefield:0.0.1": *
failed to load package (archive malformed)

Currently only a collection of examples exist.
A more thorough documentation would be needed for the upcoming bump in complexity.

Maybe switch to sth like mantys?

Small usage improvement.
Every field represents some text at the end and afaik fields do not use length or color arguments.
instead of

bytes(3)[
  #box(width:100%,height:100%,fill:green)[
    #text(8pt)[
      my bytes
    ]
  ]
]

passthrough length arguments to text and color arguments as box fill

bytes(3,8pt,green)[my bytes]

Currently if a field breaks into multiple cells labels are shown in the first cell of a field. and three dots '...' indicate that the following cells belong to the same field.

This seems as an good option on fields which only breaks and continues on the next row. But with fields spanning multiple rows this doesn't look as nice.

A better approach would be to center the label in those situations. This could be achieved by showing.the label in the middle cell or even better converting those separate cells into one cell with a rowspan.

If two note field are placed before the same data field or even two data fields which are shown in the same row, it will result in an error as by default each note has level 0.

This should be enhanced, so that the second note is placed on level higher next to the other note instead.

Idea: Use level:auto as default and then try to calculate the levels automatically.
Maybe the level argument can be removed completely and the order is always based on the position of the note field.

Instead of having a handy way to quickly instantiate the various protocols in common as standalone bytefield,
lets make them fields, that can be used in other bytefields.
these fields may allow their internal fields to be overwritten via arguments

#bytefield(
  ip(
    data: tcp(
      dst_port: [80] // set internal field content 
      src_port: bytes(2)[#box(width:100%,height:100%,fill:grey)[random]] //replace internal field
    )[
      GET ...
    ]
  )
)

#bytefield(byte(fill: pattern("-")) results in

error: assertion failed: expected fill to be an color or gradient, found pattern.
   ┌─ @preview/bytefield:0.0.5/lib/api.typ:48:20
   │
48 │   if fill != none { assert(type(fill) in (color, gradient), message: strfmt("expected fill to be an color or gradient, found {}.", type(fill)))}
   │                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

see typst/packages#198

This can be fixed with a simple if(msb_first) { bit_headers.rev() }

So if a field is too long it is broken across rows. But it doesn’t look very nice.

something like this example would be better. Or even a modified right and left edge on the wrap.

im not sure how it would be fixed? But it would be nice.

There is a typo in the UDP Packet definition.

"Destinatino Port"

Hello, I really appreciate your work; it has been quite helpful to me. By the way, would it be possible to incorporate something like an offset on the left side of the table? This would greatly enhance the representation of data structures when drawing them.

Introduce a new field that simply draws a gap of the specified height between two rows and a centered text.
I.e.
gap(1cm)[] or gap[] for some small default length (maybe 5pt + text height?)

If specified between two fields of the same row, draw blank fields after the previous field until the end of the row
draw the gap and in the next row start with blank fields up to the column of the field after the gap.

without gap:

bits(3)[XXX], bits(3)[OOO]
|XXXOOO|

with gap

bits(3)[XXX], gap[text], bits(3)[OOO]
|XXX   |
| text | 
|   OOO|