manual: corrected references

docs/manual/markdown/Makefile

@@ -1,15 +1,20 @@
 all:
 	./update_apis.py	
 	./update_listings.py
+	rm -rf docs_tmp
+	rm -rf docs_final
+	cp -r docs docs_tmp
+	cp -r docs docs_final
+	./markdown2mkdocs.py
+	rm -rf docs_tmp
 	mkdocs build --clean
-	echo "a.toctree-l4 { display: none; }" >> btstack/css/theme_extra.css
 	mkdir -p latex
 	cp -r docs/picts latex
 	cp ../picts/bklogo.pdf latex/picts
 	./markdown2pdf.py
 	cp btstack_gettingstarted.tex latex
 	cd latex && pdflatex btstack_gettingstarted.tex && pdflatex btstack_gettingstarted.tex
-	mv latex/btstack_gettingstarted.pdf btstack
+	mv latex/btstack_gettingstarted.pdf btstack.pdf
 	rm -rf latex
 
 	

docs/manual/markdown/btstack_gettingstarted.tex

@@ -1,6 +1,6 @@
 \documentclass[a4paper,titlepage,oneside,12pt]{amsart} %amsart
 \usepackage{graphicx}
-\usepackage{hyperref}
+\usepackage[colorlinks=true]{hyperref}
 %\usepackage{geometry} % see geometry.pdf on how to lay out the page. There's lots.
 \usepackage[margin=1.3in]{geometry}
 \geometry{a4paper} % or letter or a5paper or ... etc
@@ -147,6 +147,9 @@ morekeywords={*, timer_source_t, data_source_t, uint32_t, uint16_t, uint8_t, RUN
 \begin{document}
 
 \maketitle
+\hypersetup{linkcolor=blue}
+\hypersetup{urlcolor=blue}
+\hypersetup{citecolor=blue}
 
 \tableofcontents
 \pagebreak

docs/manual/markdown/docs/appendix/events_errors.md

@@ -1,6 +1,5 @@
 
-## L2CAP Events
+## L2CAP Events {#sec:eventsAndErrorsAppendix}
-<a name="appendix:events_and_errors"></a>
 
 L2CAP events and data packets are delivered to the packet handler
 specified by *l2cap_register_service* resp.

docs/manual/markdown/docs/architecture.md

@@ -42,7 +42,7 @@ events. During a run loop cycle, the callback functions of all
 registered data sources are called. Then, the callback functions of
 timers that are ready are executed.
 
-For adapting BTstack to multi-threaded environments check [here](integration/#adapting-btstack-for-multi-threaded-environments).
+For adapting BTstack to multi-threaded environments check [here](integration/#sec:multithreadingIntegration).
 
 ## No blocking anywhere
 

docs/manual/markdown/docs/how_to.md

@@ -12,9 +12,7 @@ an overview is provided here. Finally, we describe the RFCOMM
 credit-based flow-control, which may be necessary for
 resource-constraint devices.
 
-<a name ="section:memory_configuration"></a>
+## Memory configuration {#sec:memoryConfigurationHowTo}
-
-## Memory configuration
 
 The structs for services, active connections and remote devices can be
 allocated in two different manners:
@@ -53,9 +51,8 @@ The memory is set up by calling *btstack_memory_init* function:
 
     btstack_memory_init();
 
-<a name"section:run_loop"></a>
 
-## Run loop 
+## Run loop {#sec:runLoopHowTo}
 
 BTstack uses a run loop to handle incoming data and to schedule work.
 The run loop handles events from two different types of sources: data
@@ -91,7 +88,8 @@ before its event handler callback is executed. If you need a periodic
 timer, you can re-register the same timer source in the callback
 function, as shown in Listing [PeriodicTimerHandler]. Note that BTstack
 expects to get called periodically to keep its time, see Section
-[on time abstraction](#section:test) for more on the tick hardware abstraction.
+[on time abstraction](#sec:timeAbstractionPorting) for more on the 
+tick hardware abstraction.
 
 The run loop is set up by calling *run_loop_init* function for
 embedded systems:
@@ -100,7 +98,7 @@ embedded systems:
 
     run_loop_init(RUN_LOOP_EMBEDDED);
 
-The Run loop API is provided [here](appendix/apis/#appendix:api_run_loop). To
+The Run loop API is provided [here](appendix/apis/#sec:runLoopAPIAppendix). To
 enable the use of timers, make sure that you defined HAVE_TICK in the
 config file.
 
@@ -109,12 +107,11 @@ as shown in Listing [listing:btstackInit]. The application can register
 data sources as well as timers, e.g., periodical sampling of sensors, or
 communication over the UART.
 
-<a nam="sec:btstack_initialization"></a>
 
-## BTstack initialization {#section:test}
+## BTstack initialization {#sec:btstackInitializationHowTo}
 
-To initialize BTstack you need to [initialize the memory](#section:memory_configuration)
+To initialize BTstack you need to [initialize the memory](#sec:memoryConfigurationHowTo)
-and [the run loop](#section:run_loop) respectively, then setup HCI and all needed higher
+and [the run loop](#sec:runLoopHowTo) respectively, then setup HCI and all needed higher
 level protocols.
 
 The HCI initialization has to adapt BTstack to the used platform and
@@ -146,7 +143,7 @@ requires four arguments. These are:
     [src/hci_transport_h4_dma.c]() resp. [src/hci_transport_h4_ehcill_dma.c]()
     and then getting a pointer to HCI Transport implementation.
     For more information on adapting HCI Transport to different
-    environments, see [here](porting/#hci-transport-implementation).
+    environments, see [here](porting/#sec:hciTransportPorting).
 
 <!-- -->
 
@@ -173,7 +170,7 @@ requires four arguments. These are:
     keys or remote device names. This commonly requires platform
     specific code to access the MCU’s EEPROM of Flash storage. For the
     first steps, BTstack provides a (non) persistent store in memory.
-    For more see [here](porting/#persistent-storage-api).
+    For more see [here](porting/#sec:persistentStoragePorting).
 
 <!-- -->
 
@@ -190,9 +187,8 @@ themselves with the underlying layer. In addition, the application can
 register packet handlers to get events and data as explained in the
 following section.
 
-<a name="sec:services"></a>
 
-## Services
+## Services {#sec:servicesHowTo}
 
 One important construct of BTstack is *service*. A service represents a
 server side component that handles incoming connections. So far, BTstack
@@ -204,9 +200,8 @@ ID. Outgoing connections require no special registration, they are
 created by the application when needed.
 
 
-<a name="sec:packetHandlers"></a>
 
-## Where to get data - packet handlers
+## Where to get data - packet handlers {#sec:packetHandlersHowTo}
 
 
 After the hardware and BTstack are set up, the run loop is entered. From
@@ -216,7 +211,7 @@ resulting events are delivered back to the application. Instead of
 writing a single callback handler for each possible event (as it is done
 in some other Bluetooth stacks), BTstack groups events logically and
 provides them over a single generic interface. Appendix 
-[Events and Errors](generated/appendix/#events_and_errors)
+[Events and Errors](generated/appendix/#sec:eventsAndErrorsAppendix)
 summarizes the parameters and event
 codes of L2CAP and RFCOMM events, as well as possible errors and the
 corresponding error codes.
@@ -282,9 +277,8 @@ services for the HID Control and HID Interrupt PSMs using
 a packet handler to accept and receive keyboard data.
 
 
-<a name="sec:packetlogs"></a>
 
-## Bluetooth HCI Packet Logs 
+## Bluetooth HCI Packet Logs {#sec:packetlogsHowTo}
 
 
 If things don't work as expected, having a look at the data exchanged

docs/manual/markdown/docs/index.md

@@ -8,5 +8,6 @@ protocols and profiles.
 A series of examples show how BTstack can be used to implement common 
 use cases. 
 
-Finally, we outline the basic steps when integrating BTstack into existing single-threaded or even multi-threaded environments. The changes in the documentation are listed in the [Revision History](revision_history).
+Finally, we outline the basic steps when integrating BTstack into existing 
+single-threaded or even multi-threaded environments. 
 

docs/manual/markdown/docs/integration.md

@@ -11,9 +11,8 @@ contains the packet handler (PH) that handles all asynchronous events
 and data packets from BTstack. The Main Application makes use of the
 Communication Logic for its Bluetooth communication.
 
-<a name="sec:singlethreading"></a> 
 
-## Adapting BTstack for Single-Threaded Environments
+## Adapting BTstack for Single-Threaded Environments {#sec:singlethreadingIntegration}
 
 
 In a single-threaded environment, all application components run on the
@@ -41,9 +40,8 @@ Currently, we have two examples for this:
     managed in a linked list. Then, the*select* function is used to wait
     for the next file descriptor to become ready or timer to expire.
 
-<a name="sec:multithreading"></a> 
 
-## Adapting BTstack for Multi-Threaded Environments
+## Adapting BTstack for Multi-Threaded Environments {#sec:multithreadingIntegration}
 
 
 The basic execution model of BTstack is a general while loop. Aside from

docs/manual/markdown/docs/porting.md

@@ -1,9 +1,8 @@
 In this section, we highlight the BTstack components that need to be
 adjusted for different hardware platforms.
 
-<a name="section:timeAbstraction"></a>
 
-## Time Abstraction Layer
+## Time Abstraction Layer {#sec:timeAbstractionPorting}
 
 BTstack requires a way to learn about passing time.
 *run_loop_embedded.c* supports two different modes: system ticks or a
@@ -12,7 +11,7 @@ are quite low as only Bluetooth timeouts in the second range need to be
 handled.
 
 
-### Tick Hardware Abstraction ### {#section:tickAbstraction}
+### Tick Hardware Abstraction {#sec:tickAbstractionPorting}
 
 
 If your platform doesn’t require a system clock or if you already have a
@@ -37,9 +36,8 @@ After BTstack calls *hal_tick_init()* and
 *tick_handler* gets called every
 *hal_tick_get_tick_period_in_ms()* ms.
 
-<a name="sec:timeMSAbstraction"></a>
 
-### Time MS Hardware Abstraction 
+### Time MS Hardware Abstraction {#sec:timeMSAbstractionPorting}
 
 
 If your platform already has a system clock or it is more convenient to
@@ -57,9 +55,7 @@ future. It has to return the time in milliseconds.
     uint32_t hal_time_ms(void);
 
 
-<a name="sec:bt_hw_control"></a>
+## Bluetooth Hardware Control API {#sec:btHWControlPorting}
-
-## Bluetooth Hardware Control API 
 
 
 The Bluetooth hardware control API can provide the HCI layer with a
@@ -76,9 +72,8 @@ that is not covered by the Bluetooth specification. As an example, the
 struct suitable for the CC256x chipset.
 
 
-<a name="sec:hci_transport"></a>
 
-## HCI Transport Implementation 
+## HCI Transport Implementation {#sec:hciTransportPorting}
 
 
 On embedded systems, a Bluetooth module can be connected via USB or an
@@ -87,9 +82,8 @@ commands, events and data between a host and a Bluetooth module: HCI
 UART Transport Layer (H4) and H4 with eHCILL support, a lightweight
 low-power variant by Texas Instruments.
 
-<a name="sec:hciUART"></a>
 
-### HCI UART Transport Layer (H4) 
+### HCI UART Transport Layer (H4) {#sec:hciUARTPorting}
 
 
 Most embedded UART interfaces operate on the byte level and generate a
@@ -142,9 +136,8 @@ callback for CTS interrupts.
     void hal_uart_dma_set_cts_irq_handler(void(*cts_irq_handler)(void));
     void hal_uart_dma_set_sleep(uint8_t sleep);
 
-<a name="sec:persistent_storage"></a>
 
-## Persistent Storage API 
+## Persistent Storage API {#sec:persistentStoragePorting}
 
 On embedded systems there is no generic way to persist data like link
 keys or remote device names, as every type of a device has its own

docs/manual/markdown/docs/profiles.md

@@ -43,10 +43,15 @@ undiscoverable again, once a connection is established. See Listing
 ### Discover remote devices {#section:DiscoverRemoteDevices}
 
 To scan for remote devices, the *hci_inquiry* command is used. Found
-remote devices are reported as a part of HCI_EVENT_INQUIRY_RESULT,
+remote devices are reported as a part of:
-HCI_EVENT-_INQUIRY_RESULT_WITH_RSSI, or
+
-HCI_EVENT_EXTENDED_INQUIRY_RESPONSE events. Each response contains
+- HCI_EVENT_INQUIRY_RESULT,
-at least the Bluetooth address, the class of device, the page scan
+
+- HCI_EVENT-_INQUIRY_RESULT_WITH_RSSI, or
+
+- HCI_EVENT_EXTENDED_INQUIRY_RESPONSE events. 
+
+Each response contains at least the Bluetooth address, the class of device, the page scan
 repetition mode, and the clock offset of found device. The latter events
 add information about the received signal strength or provide the
 Extended Inquiry Result (EIR). A code snippet is shown in Listing
@@ -104,7 +109,7 @@ device implements Bluetooth Specification 2.1 or higher, the
 *hci_write_inquiry_mode* command enables reporting of this advanced
 features (0 for standard results, 1 for RSSI, 2 for RSSI and EIR).
 
-A complete GAP inquiry example is provided [here](examples/#gapinquiry).
+A complete GAP inquiry example is provided [here](examples/generated/#sec:gapinquiryExample).
 
 ### Pairing of Devices
 
@@ -150,8 +155,8 @@ user.
 
 Regardless of the authentication mechanism (PIN/SSP), on success, both
 devices will generate a link key. The link key can be stored either in
-the Bluetooth module itself or in a persistent storage, see [here](#examples/#persistent_storage). 
+the Bluetooth module itself or in a persistent storage, see 
-The next time the device connects and
+[here](porting/#sec:persistentStoragePorting). The next time the device connects and
 requests an authenticated connection, both devices can use the
 previously generated link key. Please note that the pairing must be
 repeated if the link key is lost by one device.
@@ -177,22 +182,21 @@ for its SPP services. Section [subsection:querysdp] shows how to query
 for all RFCOMM channels. For SPP, you can do the same but use the SPP
 UUID 0x1101 for the query. After you have identified the correct RFCOMM
 channel, you can create an RFCOMM connection as shown 
-[here](protocols/#sec:rfcommlient).
+[here](protocols/#sec:rfcommClientProtocols).
 
 ### Providing an SPP Server
 
 To provide an SPP Server, you need to provide an RFCOMM service with a
 specific RFCOMM channel number as explained in section on 
-[RFCOMM service](protocols/#sec:rfcomm_service). Then, you need to create 
+[RFCOMM service](protocols/#sec:rfcommServiceProtocols). Then, you need to create 
 an SDP record for it and publish it with the SDP server by calling
 *sdp_register_service_internal*. BTstack provides the
 *sdp_create_spp_service* function in that requires an empty buffer of
 approximately 200 bytes, the service channel number, and a service name.
-Have a look at the [SPP Counter example](examples/generated/#section:sppcounter].
+Have a look at the [SPP Counter example](examples/generated/#sec:sppcounterExample].
 
-<a name="section:pan_profile"></a>
 
-## PAN - Personal Area Networking Profile 
+## PAN - Personal Area Networking Profile {#sec:panProfiles}
 
 
 The PAN profile uses BNEP to provide on-demand networking capabilities
@@ -234,7 +238,7 @@ information, you can connect BNEP to the remote PANU service with the
 
 To provide a PANU service, you need to provide a BNEP service with the
 service UUID, e.g. the PANU UUID, and a a maximal ethernet frame size,
-as explained in Section [subsubsection:bnepserver]. Then, you need to
+as explained in Section [on BNEP service](protocols/#sec:bnepServiceProtocols). Then, you need to
 create an SDP record for it and publish it with the SDP server by
 calling *sdp_register_service_internal*. BTstack provides the
 *pan_create_panu_service* function in *src/pan.c* that requires an
@@ -266,8 +270,8 @@ To toggle privacy mode using private addresses, call the
 with *gap_random_address_set_update_period*.
 
 After a connection is established, the Security Manager will try to
-resolve the peer Bluetooth address as explained in Section
+resolve the peer Bluetooth address as explained in Section on 
-[section:smp].
+[SMP](protocols/#sec:smpProtocols).
 
 ### Advertising and Discovery
 
@@ -283,8 +287,8 @@ commands can be used:
 -   *hci_le_set_advertise_enable*
 
 As these are direct HCI commands, please refer to Section
-[subsubsection:sendinghci] for details and have a look at the SPP and LE
+[subsubsection:sendinghci] for details and have a look at the [SPP and LE
-Counter example in Section [example:sppandlecounter].
+Counter example](examples/generated/#sec:sppandlecounterExample).
 
 In addition to the Advertisement data, a device in the peripheral role
 can also provide Scan Response data, which has to be explicitly queried
@@ -317,9 +321,8 @@ Services are queried and modified via ATT operations.
 GATT defines both a server and a client role. A device can implement one
 or both GATT roles.
 
-<a name = "section:GATTClient"></a>
 
-### GATT Client 
+### GATT Client {#sec:GATTClientProfiles}
 
 The GATT Client is used to discover services, and their characteristics
 and descriptors on a peer device. It can also subscribe for
@@ -347,11 +350,10 @@ perform a GATT query on a particular connection using
 completes the query.
 
 For more details on the available GATT queries, please consult 
-[GATT Client API](#appendix:api_gatt_client).
+[GATT Client API](#sec:gattClientAPIAppendix).
 
-<a name="section:GATTServer"></a>
 
-### GATT Server
+### GATT Server {#sec:GATTServerProfiles}
 
 The GATT server stores data and accepts GATT client requests, commands
 and confirmations. The GATT server sends responses to requests and when

docs/manual/markdown/docs/protocols.md

@@ -137,8 +137,8 @@ and info on their parameters.
            S          Service Record (Data Element Sequence)  
   ------------------- ----------------------------------------------------
 
-### Sending HCI command based on a template 
+
-<a name ="sec:sendinghci"></a>
+### Sending HCI command based on a template {#sec:sendingHCIProtocols}
 
 You can use the *hci_send_cmd* function to send HCI command based on a
 template and a list of parameters. However, it is necessary to check
@@ -163,8 +163,9 @@ Please note, that an application rarely has to send HCI commands on its
 own. Instead, BTstack provides convenience functions in GAP and higher
 level protocols use HCI automatically.
 
-L2CAP - Logical Link Control and Adaptation Protocol
+
-----------------------------------------------------
+## L2CAP - Logical Link Control and Adaptation Protocol
+
 
 The L2CAP protocol supports higher level protocol multiplexing and
 packet fragmentation. It provides the base for the RFCOMM and BNEP
@@ -185,7 +186,7 @@ To communicate with an L2CAP service on a remote device, the application
 on a local Bluetooth device initiates the L2CAP layer using the
 *l2cap_init* function, and then creates an outgoing L2CAP channel to
 the PSM of a remote device using the *l2cap_create_channel_internal*
-function. The *l2cap_-create_channel_internal* function will initiate
+function. The *l2cap_create_channel_internal* function will initiate
 a new baseband connection if it does not already exist. The packet
 handler that is given as an input parameter of the L2CAP create channel
 function will be assigned to the new outgoing L2CAP channel. This
@@ -298,8 +299,8 @@ BTstack provides an optimized *l2cap_le* implementation in the *ble*
 folder. This L2CAP LE variant can be used for single-mode devices and
 provides the base for the ATT and SMP protocols.
 
-RFCOMM - Radio Frequency Communication Protocol
+
------------------------------------------------
+## RFCOMM - Radio Frequency Communication Protocol
 
 The Radio frequency communication (RFCOMM) protocol provides emulation
 of serial ports over the L2CAP protocol. and reassembly. It is the base
@@ -307,8 +308,8 @@ for the Serial Port Profile and other profiles used for
 telecommunication like Head-Set Profile, Hands-Free Profile, Object
 Exchange (OBEX) etc.
 
-### RFCOMM flow control. 
+
-<a name="sec:flowcontrol"></a>
+### RFCOMM flow control {#sec:flowControlProtocols}
 
 RFCOMM has a mandatory credit-based flow-control. This means that two
 devices that established RFCOMM connection, use credits to keep track of
@@ -326,24 +327,24 @@ is not much data transmitted and/or only one physical connection is
 used. If the management of credits is manual, credits are provided by
 the application such that it can manage its receive buffers explicitly.
 
-### Access an RFCOMM service on a remote device 
+
-<a name="sec:rfcommlient"></a>
+### Access an RFCOMM service on a remote device {#sec:rfcommClientProtocols}
 
 To communicate with an RFCOMM service on a remote device, the
 application on a local Bluetooth device initiates the RFCOMM layer using
 the *rfcomm_init* function, and then creates an outgoing RFCOMM channel
 to a given server channel on a remote device using the
 *rfcomm_create_channel_internal* function. The
-*rfcomm_create_channel_intern-al* function will initiate a new L2CAP
+*rfcomm_create_channel_internal* function will initiate a new L2CAP
 connection for the RFCOMM multiplexer, if it does not already exist. The
 channel will automatically provide enough credits to the remote side. To
 provide credits manually, you have to create the RFCOMM connection by
 calling *rfcomm_create_channel_with_initial_credits_internal* -
-see Section [on manual credit assignement](#sec:manualCredits).
+see Section [on manual credit assignement](#sec:manualCreditsProtocols).
 
 The packet handler that is given as an input parameter of the RFCOMM
 create channel function will be assigned to the new outgoing channel.
-This handler receives the RFCOMM_EVENT_OPEN_CHAN-NEL_COMPLETE and
+This handler receives the RFCOMM_EVENT_OPEN_CHANNEL_COMPLETE and
 RFCOMM_EVENT_CHANNEL_CLOSED events, and RFCOMM data packets, as shown in
 Listing [below](#lst:RFCOMMremoteService).
 
@@ -376,8 +377,7 @@ Listing [below](#lst:RFCOMMremoteService).
     }
 
 
-### Provide an RFCOMM service 
+### Provide an RFCOMM service {#sec:rfcommServiceProtocols}
-<a name="sec:rfcomm_service"></a>
 
 To provide an RFCOMM service, the application on a local Bluetooth
 device must first init the L2CAP and RFCOMM layers and then register the
@@ -449,8 +449,9 @@ provides the RFCOMM service example code.
         }
     }
 
-### Living with a single output buffer 
+
-<a name="sec:single_buffer"></a>
+### Living with a single output buffer {#sec:singleBufferProtocols}
+
 Outgoing packets, both commands and data, are not queued in BTstack.
 This section explains the consequences of this design decision for
 sending data and why it is not as bad as it sounds.
@@ -533,7 +534,7 @@ Listing [below](#lst:SingleOutputBufferTryPH).
 
 If the management of credits is manual, credits are provided by the
 application such that it can manage its receive buffers explicitly, see
-Listing [below].
+Listing [below](#lst:explicitFlowControl).
 
 <a name "lst:explicitFlowControl"></a>
 <!-- -->
@@ -549,7 +550,7 @@ Listing [below].
 
 
 Manual credit management is recommended when received RFCOMM data cannot
-be processed immediately. In the [SPP flow control example](examples/#sec:sppflowcontrol), 
+be processed immediately. In the [SPP flow control example](examples/generated/#sec:sppflowcontrolExample), 
 delayed processing of received data is
 simulated with the help of a periodic timer. To provide new credits, you
 call the *rfcomm_grant_credits* function with the RFCOMM channel ID
@@ -572,8 +573,8 @@ for a minimal memory footprint. If possible, multiple RFCOMM buffers
 should be used to avoid pauses while the sender has to wait for a new
 credit.
 
-### Slowing down RFCOMM data reception 
+
-<a name="sec:manualCredits"></a>
+### Slowing down RFCOMM data reception {#sec:manualCreditsProtocols}
 
 RFCOMM’s credit-based flow-control can be used to adapt, i.e., slow down
 the RFCOMM data to your processing speed. For incoming data, BTstack
@@ -595,8 +596,7 @@ connection is used. See Listing [below](#lst:automaticFlowControl).
     }
 
 
-SDP - Service Discovery Protocol
+## SDP - Service Discovery Protocol
---------------------------------
 
 The SDP protocol allows to announce services and discover services
 provided by a remote Bluetooth device.
@@ -627,11 +627,11 @@ a sub-DES. The returned pointer is used to add elements to this sub-DES.
 After adding all UUIDs, the sub-DES is “closed” with
 *de_pop_sequence*.
 
-### Query remote SDP service 
+
-<a name="sec:querysdp"></a>
+### Query remote SDP service {#sec:querySDPProtocols}
 
 BTstack provides an SDP client to query SDP services of a remote device.
-The SDP Client API is shown in [here](appendix/apis/#appendix:api_sdp). The
+The SDP Client API is shown in [here](appendix/apis/#sec:sdpAPIAppendix). The
 *sdp_client_query* function initiates an L2CAP connection to the
 remote SDP server. Upon connect, a *Service Search Attribute* request
 with a *Service Search Pattern* and a *Attribute ID List* is sent. The
@@ -735,11 +735,12 @@ of L2CAP, and it specifies a minimum L2CAP MTU of 1691 bytes.
 To receive BNEP events, please register a packet handler with
 *bnep_register_packet_handler*.
 
-### Access a BNEP service on a remote device {#subsubsection:bnepclient}
+
+### Access a BNEP service on a remote device {#sec:bnepClientProtocols}
 
 To connect to a remote BNEP service, you need to know its UUID. The set
 of available UUIDs can be queried by a SDP query for the PAN profile.
-Please see section on [PAN profile](profiles/#section:pan_profile) for details. 
+Please see section on [PAN profile](profiles/#sec:panProfiles) for details. 
 With the remote UUID, you can create a connection using the *bnep_connect* 
 function. You’ll receive a *BNEP_EVENT_OPEN_CHANNEL_COMPLETE* on success or
 failure.
@@ -756,7 +757,8 @@ multicast filters with *bnep_set_net_type_filter* and
 
 Finally, to close a BNEP connection, you can call *bnep_disconnect*.
 
-### Provide BNEP service {#subsubsection:bnepserver}
+
+### Provide BNEP service {#sec:bnepServiceProtocols}
 
 To provide a BNEP service, call *bnep_register_service* with the
 provided service UUID and a max frame size.
@@ -781,11 +783,11 @@ attribute database and provided by the *att_server* implementation. The
 constant data are automatically served by the ATT server upon client
 request. To receive the dynamic data, such is characteristic value, the
 application needs to register read and/or write callback. In addition,
-notifications and indications can be sent. Please see Section
+notifications and indications can be sent. Please see Section on 
-[section:GATTClient] for more.
+[GATT client](profiles/#sec:GATTClientProfiles) for more.
 
-## SMP - Security Manager Protocol 
+
-<a name="section:smp"></a>
+## SMP - Security Manager Protocol {#sec:smpProtocols}
 
 The SMP protocol allows to setup authenticated and encrypted LE
 connection. After initialization and configuration, SMP handles security
@@ -802,7 +804,8 @@ If you’re creating a product, you should also call *sm_set_ir()* and
 ER key seeds. If possible use a unique random number per device instead
 of deriving it from the product serial number or something similar. The
 encryption key generated by the BLE peripheral will be ultimately
-derived from the ER key seed. See [Bluetooth Specification](https://www.bluetooth.org/Technical/Specifications/adopted.htm) -
+derived from the ER key seed. See 
+[Bluetooth Specification](https://www.bluetooth.org/Technical/Specifications/adopted.htm) -
 Bluetooth Core V4.0, Vol 3, Part G, 5.2.2 for more details on deriving
 the different keys. The IR key is used to identify a device if private,
 resolvable Bluetooth addresses are used.

docs/manual/markdown/docs/quick_start.md

@@ -16,7 +16,7 @@ and optionally git :
     Windows: Add Python installation folder to the Windows Path in
     Environment Variables.
 
-Adding paths to the Windows Path variable <a name="sec:windowsPath"></a>:
+### Adding paths to the Windows Path variable {#sec:windowsPathQuickStart}
 
 -   Go to: Control Panel->System->Advanced tab->Environment Variables.
 
@@ -33,7 +33,7 @@ Adding paths to the Windows Path variable <a name="sec:windowsPath"></a>:
 
 Use git to clone the latest version:
 
-            git clone https://github.com/bluekitchen/btstack.git
+    git clone https://github.com/bluekitchen/btstack.git
         
 
 Alternatively, you can download it as a ZIP archive from
@@ -54,7 +54,8 @@ provided, too.
 
 ## Run the Example
 
-As a first test, we recommend [the SPP Counter example](examples/generated/#section:sppcounter). During the startup, for TI chipsets, the init
+As a first test, we recommend the [SPP Counter example](examples/generated/#sec:sppcounterExample). 
+During the startup, for TI chipsets, the init
 script is transferred, and the Bluetooth stack brought up. After that,
 the development board is discoverable as “BTstack SPP Counter” and
 provides a single virtual serial port. When you connect to it, you’ll
@@ -83,8 +84,8 @@ Bluetooth. For this, execute:
 
 It’s also possible to run the examples on Win32 systems. For this:
 
--   Install [MSYS](www.mingw.org/wiki/msys) and
+-   Install [MSYS](http://www.mingw.org/wiki/msys) and
-    [MINGW32](www.mingw.org) using the MINGW installer
+    [MINGW32](http://www.mingw.org) using the MINGW installer
 
 -   Compile and install libusb-1.0.19 to [/usr/local/]() in msys command
     shell
@@ -113,7 +114,7 @@ and installation instructions are provided on the
 On Windows, you need to download and extract 
 [mspgcc](http://sourceforge.net/projects/mspgcc/files/Windows/mingw32/)
 to [C:\mspgcc](). Add [C:\mspgcc\bin]() folder to the Windows Path in Environment 
-variable as explained [here](#sec:windowsPath).
+variable as explained [here](#sec:windowsPathQuickStart).
 
 **Loading Firmware.** To load firmware files onto the MSP430 MCU for the
 MSP-EXP430F5438 Experimeneter board, you need a programmer like the
@@ -129,7 +130,7 @@ following software tools:
 
 <!-- -->
 
-            MSP430Flasher.exe -n MSP430F5438A -w "BINARY_FILE_NAME.hex" -v -g -z [VCC]
+    MSP430Flasher.exe -n MSP430F5438A -w "BINARY_FILE_NAME.hex" -v -g -z [VCC]
            
 
 -   [MSPDebug](http://mspdebug.sourceforge.net/):
@@ -175,9 +176,8 @@ the BLE part. The conversion script has been updated to detect
 *bluetooth_init_cc256x_1.2.bts* and adds *BLE_init_cc256x_1.2.bts*
 if present and merges them into a single .c file.
 
-<a name="platform:msp430"></a>
 
-### MSP-EXP430F5438 + CC256x Platform 
+### MSP-EXP430F5438 + CC256x Platform {#sec:platformMSP430QuickStart}
 
 **Hardware Setup.** We assume that a PAN1315, PAN1317, or PAN1323 module
 is plugged into RF1 and RF2 of the MSP-EXP430F5438 board and the “RF3
@@ -196,10 +196,11 @@ BTM805 Bluetooth module. In the port, the UART on the DAC daughter board
 was used for the debug output. Please remove the DAC board and connect a
 3.3V USB-2-UART converter to GND and TX to get the debug output.
 
-In [platforms/pic32-harmony](), a project file for the MPLAB X IDE is provided as well as a regular
+In [platforms/pic32-harmony](), a project file for the MPLAB X IDE 
+is provided as well as a regular
 Makefile. Both assume that the MPLAB XC32 compiler is installed. The
 project is set to use -Os optimization which will cause warnings if you
 only have the Free version. It will still compile a working example. For
 this platform, we only provide the SPP and LE Counter example directly.
-Other examples can be run by replacing the spp_and_le_counter.c file
+Other examples can be run by replacing the *spp_and_le_counter.c* file
 with one of the other example files.

docs/manual/markdown/markdown2mkdocs.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+
+import sys, yaml
+import os, re
+
+def insert_anchor(mdout, reference):
+    mdout.write("<a name=\"" + reference + "\"></a>\n\n")
+
+def insert_reference(mdout, text, link):
+    mdout.write("")
+
+def fcopy(source_file, dest_file):
+    with open(dest_file, 'w') as mdout:
+        with open(source_file, 'r') as mdin:
+            for line in mdin:
+                mdout.write(line)
+
+def process_sections(temp_file, dest_file):
+    with open(dest_file, 'w') as mdout:
+        with open(temp_file, 'r') as mdin:
+            for line in mdin:
+                section = re.match('(#+.*){#(sec:.*)}',line)
+                if section:
+                    insert_anchor(mdout, section.group(2))
+                    mdout.write(section.group(1)+"\n")
+                else:
+                    mdout.write(line)
+                
+    fcopy(dest_file, temp_file)
+    return
+
+def process_figures(temp_file, dest_file):
+    with open(dest_file, 'w') as mdout:
+        with open(temp_file, 'r') as mdin:
+            for line in mdin:
+                # detect figure
+                figure = re.match('\s*(\!.*)({#(fig:.*)})',line)
+                if figure:
+                    insert_anchor(mdout, figure.group(3))
+                    mdout.write(figure.group(1)+"\n")
+                else:
+                    figure_ref = re.match('.*({@(fig:.*)})',line)
+                    if figure_ref:
+                        md_reference = "[below](#"+figure_ref.group(2)+")"
+                        line = line.replace(figure_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:
+#             for line in mdin:
+#                 mdout.write(line)
+#     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):
+    md_template = "docs"
+    md_temp = "docs_tmp"
+    md_final = "docs_final"
+    yml_file = "mkdocs.yml"
+    
+    with open(yml_file, 'r') as yin:
+        doc = yaml.load(yin)
+        for page in doc["pages"]:
+            source_file = md_template +"/"+ page[0]
+            temp_file   = md_temp +"/"+ page[0]
+            dest_file   = md_final +"/"+ page[0]
+            
+            process_sections(temp_file, dest_file)
+            process_figures(temp_file, dest_file)
+            # process_listings(temp_file, dest_file)
+            # process_tables(temp_file, dest_file)
+
+
+if __name__ == "__main__":
+   main(sys.argv[1:])

docs/manual/markdown/markdown2pdf.py

@@ -24,9 +24,15 @@ def main(argv):
                 with open(docs_folder +"/"+ md_file, 'r') as mdin:
                     aout.write("\n\n#"+ title +"\n\n")
                     for line in mdin:
+                        # remove path from section reference
+                        # e.g. [the SPP Counter example](examples/generated/#sec:sppcounterExample)
+                        # replace with [the SPP Counter example](#sec:sppcounterExample)
+                        section_ref = re.match('.*\(((.*)(#sec:.*))\).*',line)
+                        if section_ref:
+                            line = line.replace(section_ref.group(2),"")
                         aout.write(line)                
 
-    pandoc_cmd = "pandoc -f markdown -t latex --listings latex/btstack_generated.md -o latex/btstack_generated.tex"
+    pandoc_cmd = "pandoc -f markdown -t latex --filter pandoc-fignos --listings latex/btstack_generated.md -o latex/btstack_generated.tex"
     p = os.popen(pandoc_cmd,"r")
     while 1:
         line = p.readline()

docs/manual/markdown/mkdocs.yml

@@ -1,5 +1,6 @@
 site_name: BTstack Manual
 site_dir: btstack
+docs_dir: docs_final
 pages:
 - [index.md, Welcome]
 - [quick_start.md, Quick Start]

docs/manual/markdown/update_apis.py

@@ -16,8 +16,7 @@ code_identation = "    "
 
 api_header = """
 
-## API_TITLE API
+## API_TITLE API {#sec:API_LABLEAPIAppendix}
-<a name ="appendix:API_LABLE"></a>
 
 """
 
@@ -26,18 +25,18 @@ api_ending = """
 
 # [file_name, api_title, api_lable]
 list_of_apis = [ 
-    [btstack_folder+"include/btstack/run_loop.h", "Run Loop", "api_run_loop"],
+    [btstack_folder+"include/btstack/run_loop.h", "Run Loop", "runLoop"],
-    [btstack_folder+"src/hci.h", "HCI", "api_hci"],
+    [btstack_folder+"src/hci.h", "HCI", "hci"],
-    [btstack_folder+"src/l2cap.h", "L2CAP", "api_l2cap"],
+    [btstack_folder+"src/l2cap.h", "L2CAP", "l2cap"],
-    [btstack_folder+"src/rfcomm.h", "RFCOMM", "api_rfcomm"],
+    [btstack_folder+"src/rfcomm.h", "RFCOMM", "rfcomm"],
-    [btstack_folder+"src/sdp.h", "SDP", "api_sdp"],
+    [btstack_folder+"src/sdp.h", "SDP", "sdp"],
-    [btstack_folder+"src/sdp_client.h", "SDP Client", "api_sdp_client"],
+    [btstack_folder+"src/sdp_client.h", "SDP Client", "sdpClient"],
-    [btstack_folder+"src/sdp_query_rfcomm.h", "SDP RFCOMM Query", "api_sdp_queries"],
+    [btstack_folder+"src/sdp_query_rfcomm.h", "SDP RFCOMM Query", "sdpQueries"],
-    [btstack_folder+"ble/gatt_client.h", "GATT Client", "api_gatt_client"],
+    [btstack_folder+"ble/gatt_client.h", "GATT Client", "gattClient"],
-    [btstack_folder+"src/pan.h", "PAN", "api_pan"],
+    [btstack_folder+"src/pan.h", "PAN", "pan"],
-    [btstack_folder+"src/bnep.h", "BNEP", "api_bnep"],
+    [btstack_folder+"src/bnep.h", "BNEP", "bnep"],
-    [btstack_folder+"src/gap.h", "GAP", "api_gap"],
+    [btstack_folder+"src/gap.h", "GAP", "gap"],
-    [btstack_folder+"ble/sm.h", "SM", "api_sm"]
+    [btstack_folder+"ble/sm.h", "SM", "sm"]
 ]
 
 def replacePlaceholder(template, title, lable):

docs/manual/markdown/update_listings.py

@@ -32,12 +32,11 @@ examples_header = """
 """
 
 example_item = """
-    - [EXAMPLE_TITLE](#section:EXAMPLE_LABEL): EXAMPLE_DESC.
+    - [EXAMPLE_TITLE](#sec:EXAMPLE_LABELExample): EXAMPLE_DESC.
 """
 example_section = """
 
-## EXAMPLE_TITLE: EXAMPLE_DESC
+## EXAMPLE_TITLE: EXAMPLE_DESC {#sec:EXAMPLE_LABELExample}
-<a name="section:EXAMPLE_LABEL"></a>
 
 """
 example_subsection = """
@@ -72,7 +71,7 @@ def latexText(text, ref_prefix):
     refs = re.match('.*(Section\s+)(\w+).*',brief)
     if refs:
         brief = brief.replace(refs.group(1), "[here]")
-        brief = brief.replace(refs.group(2), "(#section:"+refs.group(2)+")")
+        brief = brief.replace(refs.group(2), "(#sec:"+refs.group(2)+")")
 
     return brief