manual: reference tables

docs/manual/docs/appendix/events_errors.md

@@ -31,15 +31,30 @@ L2CAP_DATA_PACKET packet type. L2CAP provides the following events:
 
 
 
-Event Code |Event / Event Parameters (size in bits) 
+Event      | Event Code
 -----------|----------------------------------------
-0x70 | L2CAP_EVENT_CHANNEL_OPENED<br/> *event(8), len(8), status(8), address(48), handle(16), psm(16), local_cid(16), remote_cid(16), local_mtu(16), remote_mtu(16)*  
+L2CAP_EVENT_CHANNEL_OPENED          | 0x70 
-0x71 | L2CAP_EVENT_CHANNEL_CLOSED<br/> *event (8), len(8), channel(16)* 
+L2CAP_EVENT_CHANNEL_CLOSED          | 0x71 
-0x72 | L2CAP_EVENT_INCOMING_CONNECTION<br/> *event(8), len(8), address(48), handle(16), psm (16), local_cid(16), remote_cid (16)* 
+L2CAP_EVENT_INCOMING_CONNECTION     | 0x72 
-0x74 | L2CAP_EVENT_CREDITS<br/> *event(8), len(8), local_cid(16), credits(8)*
+L2CAP_EVENT_CREDITS                 | 0x74 
-0x75 | L2CAP_EVENT_SERVICE_REGISTERED</br> *event(8), len(8), status(8), psm(16)* 
+L2CAP_EVENT_SERVICE_REGISTERED      | 0x75 
 
 
+Table: L2CAP Events. {#tbl:l2capEvents}
+
+L2CAP event paramaters, with size in bits:
+
+- L2CAP_EVENT_CHANNEL_OPENED: 
+    - *event(8), len(8), status(8), address(48), handle(16), psm(16), local_cid(16), remote_cid(16), local_mtu(16), remote_mtu(16)*  
+- L2CAP_EVENT_CHANNEL_CLOSED: 
+    - *event (8), len(8), channel(16)* 
+- L2CAP_EVENT_INCOMING_CONNECTION: 
+    - *event(8), len(8), address(48), handle(16), psm (16), local_cid(16), remote_cid (16)* 
+- L2CAP_EVENT_CREDITS:
+    - *event(8), len(8), local_cid(16), credits(8)*
+- L2CAP_EVENT_SERVICE_REGISTERED: 
+    - *event(8), len(8), status(8), psm(16)* 
+
 ## RFCOMM Events
 
 All RFCOMM events and data packets are currently delivered to the packet
@@ -64,21 +79,39 @@ by RFCOMM:
     RFCOMM credit-based flow-control.
 
 -   RFCOMM_EVENT_SERVICE_REGISTERED - Status not equal zero indicates
-    an error. Possible errors: service is already registered;
+    an error. Possible errors: 
-    MAX_NO_RFCOMM_SERVICES (defined in config.h) already registered.
+    
+    - service is already registered;
+    - MAX_NO_RFCOMM_SERVICES (defined in config.h) already registered.
 
 
-Event Code |Event / Event Parameters (size in bits) 
+Event      | Event Code
------------|----------------------------------------
+-----------|-----------------------------
-0x80 | RFCOMM_EVENT_OPEN_CHANNEL_COMPLETE<br/> *event(8), len(8), status(8), address(48), handle(16), server_channel(8), rfcomm_cid(16), max_frame_size(16)*
+RFCOMM_EVENT_OPEN_CHANNEL_COMPLETE | 0x80 
-0x81 | RFCOMM_EVENT_CHANNEL_CLOSED<br/> *event(8), len(8), rfcomm_cid(16)*
+RFCOMM_EVENT_CHANNEL_CLOSED        | 0x81 
-0x82 | RFCOMM_EVENT_INCOMING_CONNECTION<br/> *event(8), len(8), address(48), channel (8), rfcomm_cid(16)*
+RFCOMM_EVENT_INCOMING_CONNECTION   | 0x82 
-0x84 | RFCOMM_EVENT_CREDITS<br/> *event(8), len(8), rfcomm_cid(16), credits(8)*
+RFCOMM_EVENT_CREDITS               | 0x84 
-0x85 | RFCOMM_EVENT_SERVICE_REGISTERED<br/> *event(8), len(8), status(8), rfcomm server channel_id(8)*
+RFCOMM_EVENT_SERVICE_REGISTERED    | 0x85 
 
+Table: RFCOMM Events. {#tbl:rfcommEvents}
+
+
+RFCOMM event paramaters, with size in bits:
+
+- RFCOMM_EVENT_OPEN_CHANNEL_COMPLETE: 
+    - *event(8), len(8), status(8), address(48), handle(16), server_channel(8), rfcomm_cid(16), max_frame_size(16)*
+- RFCOMM_EVENT_CHANNEL_CLOSED: 
+    - *event(8), len(8), rfcomm_cid(16)*
+- RFCOMM_EVENT_INCOMING_CONNECTION: 
+    - *event(8), len(8), address(48), channel (8), rfcomm_cid(16)*
+- RFCOMM_EVENT_CREDITS: 
+    - *event(8), len(8), rfcomm_cid(16), credits(8)*
+- RFCOMM_EVENT_SERVICE_REGISTERED: 
+    - *event(8), len(8), status(8), rfcomm server channel_id(8)*
 
 ## Errors
 
+
 Error                                                                   |    Error Code
 ------------------------------------------------------------------------|-------------------
 BTSTACK_MEMORY_ALLOC_FAILED | 0x56
@@ -101,4 +134,5 @@ RFCOMM_CHANNEL_ALREADY_REGISTERED | 0x71
 RFCOMM_NO_OUTGOING_CREDITS | 0x72
 SDP_HANDLE_ALREADY_REGISTERED | 0x80
 
+Table: Errors. {#tbl:errors}
 

docs/manual/docs/how_to.md

@@ -233,6 +233,9 @@ use:
 -   RFCOMM packet handler - handles RFCOMM incoming/outgoing events and
     data.
 
+These handlers are registered with the functions listed in Table
+{@tbl:registeringFunction}.
+
   ------------------------------ --------------------------------------
                   Packet Handler Registering Function
               HCI packet handler *hci_register_packet_handler*
@@ -240,11 +243,9 @@ use:
     L2CAP service packet handler *l2cap_register_service_internal*
     L2CAP channel packet handler *l2cap_create_channel_internal*
            RFCOMM packet handler *rfcomm_register_packet_handler*
-     [table:registeringFunction] 
   ------------------------------ --------------------------------------
 
-These handlers are registered with the functions listed in Table
+Table: Functions for registering packet handlers. {#tbl:registeringFunction}
-[table:registeringFunction].
 
 HCI and general BTstack events are delivered to the packet handler
 specified by *l2cap_register_packet_handler* function, or

docs/manual/docs/protocols.md

@@ -120,7 +120,7 @@ command template from library:
 
 It uses OGF_CONTROLLER_BASEBAND as OGF,
 0x13 as OCF, and has one parameter with format “N” indicating a null
-terminated UTF-8 string. Table [table:hciformat] lists the format
+terminated UTF-8 string. Table {@tbl:hciCmdParamSpecifier} lists the format
 specifiers supported by BTstack. Check for other predefined HCI commands
 and info on their parameters.
 
@@ -137,6 +137,8 @@ and info on their parameters.
            S          Service Record (Data Element Sequence)  
   ------------------- ----------------------------------------------------
 
+Table: Supported Format Specifiers of HCI Command Parameter. {#tbl:hciCmdParamSpecifier}
+
 
 ### Sending HCI command based on a template {#sec:sendingHCIProtocols}
 

docs/manual/markdown2mkdocs.py

@@ -47,6 +47,25 @@ def process_figures(temp_file, dest_file):
     fcopy(dest_file, temp_file)
     return
 
+def process_tables(temp_file, dest_file):
+    with open(dest_file, 'w') as mdout:
+        with open(temp_file, 'r') as mdin:
+            for line in mdin:
+                # detect table
+                table = re.match('\s*(Table:.*)({#(tbl:.*)})',line)
+                if table:
+                    insert_anchor(mdout, table.group(3))
+                    mdout.write(table.group(1)+"\n")
+                else:
+                    table_ref = re.match('.*({@(tbl:.*)})',line)
+                    if table_ref:
+                        md_reference = "[below](#"+table_ref.group(2)+")"
+                        line = line.replace(table_ref.group(1), md_reference) 
+                    mdout.write(line)
+    fcopy(dest_file, temp_file)
+    return
+
+
 # def process_listings(temp_file, dest_file):
 #     with open(dest_file, 'w') as mdout:
 #         with open(temp_file, 'r') as mdin:
@@ -55,13 +74,6 @@ def process_figures(temp_file, dest_file):
 #     fcopy(dest_file, temp_file)
 #     return
 
-# def process_tables(temp_file, dest_file):
-#     with open(dest_file, 'w') as mdout:
-#         with open(temp_file, 'r') as mdin:
-#             for line in mdin:
-#                 mdout.write(line)
-#     fcopy(dest_file, temp_file)
-#     return
 
 
 def main(argv):
@@ -79,8 +91,8 @@ def main(argv):
             
             process_sections(temp_file, dest_file)
             process_figures(temp_file, dest_file)
+            process_tables(temp_file, dest_file)
             # process_listings(temp_file, dest_file)
-            # process_tables(temp_file, dest_file)
 
 
 if __name__ == "__main__":

docs/manual/markdown2pdf.py

@@ -34,6 +34,7 @@ def fix_figure_width_and_type(line):
             line = corr.group(1) + '[width='+width+'\\textwidth]' + corr.group(2).replace('png','pdf')
     return line
 
+
 def fix_appendix_pagebreak(line):
     corr = re.match('.*section{APIs}.*',line)
     if corr:
@@ -63,7 +64,7 @@ def main(argv):
                             line = line.replace(section_ref.group(2),"")
                         aout.write(line)               
 
-    pandoc_cmd = "pandoc -f markdown -t latex --filter pandoc-fignos --listings latex/btstack_generated.md -o latex/btstack_generated.tex"
+    pandoc_cmd = "pandoc -f markdown -t latex --filter pandoc-fignos --filter pandoc-tablenos --listings latex/btstack_generated.md -o latex/btstack_generated.tex"
     p = os.popen(pandoc_cmd,"r")
     while 1:
         line = p.readline()