User:Dandorid/sandbox/PHD/doc

is a template for generating Augmented Packet Header Diagrams. An effort is underway to standardize diagrams in RFCs and to make them machine readable. This macro, however, is solely intended for generating diagrams for human consumption. As such, and building on Wikipedia's history, they will differ somewhat.

The generated diagram (a wiki table) has been designed and improved by many earlier editors on many wiki pages. This template merely standardizes this work and simplifies its use.

The diagram includes a header that numbers bits from 0 to 31, with 0 being the most significant bit. These bits are numbered in network byte order, since they are, with very few exceptions, transmitted over the line in this order.

Usage
The easiest way to see how it works is by giving an example. We start with the header, and we add a title, embellished with a reference.

Next we define two 16-bit fields, starting at octet 0:

We follow with two 32-bit fields, starting at octet 4 and 8. Suppose some emphasis is required on the name of a field, you can give it a different colour:

Now, things get interesting. Let's define 11 fields of various sizes and display some of them vertically. Note that we do not have to specify the widths of fields of only one bit.

Then we repeat a line with two 16-bit fields. You can include wikilinks in the fields' text, as well as references:

We end the fields with a large, 320-bit field, which would span ten lines but is summarized on just 3 lines. We give it a very light salmon colour ('misty rose') to indicate it is optional:

Background colours can be specified using a standard HTML colour name, or a hexadecimal colour code with 3 or 6 digits. Finally, we end the wikitable with:

It does not generate output, but ends the table in a proper manner. It should always be included at the end of the table.

As an example, we give a description of some of the fields:

(Notice the line break after 'zero.' and the start of the next line with a colon to indent it properly.)




 * Or you could just use extra text outside the start of the field definitions.

This is the result:


 * Or you could just use extra text outside the start of the field definitions.

Template data
{	"description": "Template is used to create augmented packet header diagrams, in close co-ordination with the writers of the standardization effort.", "params": { "1 (start)": { "description": "Generates the header.", "example": "start", "type": "string", "label": "table header", "suggested": true },		"1 (numerical)": { "description": "If this parameter is numerical then it is interpreted as the octet offset of this 4 octet-sized table row, which is displayed in the left header. The bit offset is calculated automatically.", "example": "4", "type": "number", "label": "offset", "suggested": true },		"1 (end)": { "description": "Generates the end of the table.", "example": "end", "type": "string", "label": "table end", "suggested": true },		"bits1-bits12": { "description": "Size of field field1 - field12 in bits.", "default": "1", "example": "16", "type": "string", "label": "field length", "suggested": false },		"field1-field12": { "description": "Field name of field1 - field12.", "example": "Options", "type": "string", "label": "field name", "suggested": false },		"vfield1-vfield12": { "description": "Field name of field1 - field12. Displayed vertically. A 'fieldX' takes precedence over a 'vfieldX'.", "example": "SYN", "type": "string", "label": "vertical field name", "suggested": false } } }