Markdown table support

[podborski]

Where is bikeshed on markdown table support? I'm investigating the possibilities of how I can best port the AV1 specification to bikeshed.

Take a look at this file for example 06.bitstream.syntax.md. Basically, every single syntax element is defined in a table, and I want to avoid writing HTML for each table.

I see there was a quite extensive discussion in #1128 on this topic and it seems like there was no agreement on adding this. Is this still the case? If yes, what would be the best way forward for me?

PS: Also it would be good to document that the markdown tables are not supported. At least I could not find anything about it in the documentation.

[tabatkins]

Right, I'm still moderately against Markdown tables. They don't actually save you any meaningful typing over just using HTML with omitted end tags, and they're (by a significant margin) more complex to parse than any other block. The main reason they're used is because many Markdown processors just don't support HTML, or don't support mixing it with Markdown well; Bikeshed very intentionally supports mixing the two syntaxes well.

PS: Also it would be good to document that the markdown tables are not supported. At least I could not find anything about it in the documentation.

Right, that's because "Markdown tables" aren't Markdown - they're just a common extension. The docs are clear that I support CommonMark with some documented exceptions and additions.

Parsing is... ill-defined, generally, for tables. For example, the first table in the page you link is making some interesting assumptions about how the table syntax parses. Instead, it could be written:

<table class=syntax>
	<tr>
		<td>
			<pre>
			open_bitstream_unit( sz ) {
			    obu_header()
			    if ( obu_has_size_field ) {
			        @@obu_size
			    } else {
			        obu_size = sz - 1 - obu_extension_flag
			    }
			    startPosition = get_position( )
			    if ( obu_type != OBU_SEQUENCE_HEADER &&
			         obu_type != OBU_TEMPORAL_DELIMITER &&
			         OperatingPointIdc != 0 &&
			         obu_extension_flag == 1 )
			    {
			        inTemporalLayer = (OperatingPointIdc \>\> temporal_id ) & 1
			        inSpatialLayer = (OperatingPointIdc \>\> ( spatial_id + 8 ) ) & 1
			        if ( !inTemporalLayer \|\| ! inSpatialLayer ) {
			            drop_obu( )
			            return
			        }
			    }
			    if ( obu_type == OBU_SEQUENCE_HEADER )
			        sequence_header_obu( )
			    else if ( obu_type == OBU_TEMPORAL_DELIMITER )
			        temporal_delimiter_obu( )
			    else if ( obu_type == OBU_FRAME_HEADER )
			        frame_header_obu( )
			    else if ( obu_type == OBU_REDUNDANT_FRAME_HEADER )
			        frame_header_obu( )
			    else if ( obu_type == OBU_TILE_GROUP )
			        tile_group_obu( obu_size )
			    else if ( obu_type == OBU_METADATA )
			        metadata_obu( )
			    else if ( obu_type == OBU_FRAME )
			        frame_obu( obu_size )
			    else if ( obu_type == OBU_TILE_LIST )
			        tile_list_obu( )
			    else if ( obu_type == OBU_PADDING )
			        padding_obu( )
			    else
			        reserved_obu( )
			    currentPosition = get_position( )
			    payloadBits = currentPosition - startPosition
			    if ( obu_size > 0 && obu_type != OBU_TILE_GROUP &&
			         obu_type != OBU_TILE_LIST &&
			         obu_type != OBU_FRAME ) {
			        trailing_bits( obu_size * 8 - payloadBits )
			    }
			}
			</pre>
		<td>
			**Type**

			leb128()
</table>