Merge pull request #344 from hiddewie/markdown2

Actual Markdown for the README and HACKING files

HACKING.md

@@ -15,15 +15,19 @@ Here are some directions to get you started:
      Helper script to get some uniformity in the style:
      $ make style
 
-     If you use vim see the "Vim: How to prevent trailing whitespaces"
+     If you use vim see the [Vim: How to prevent trailing whitespaces](http://www.carbon-project.org/Vim__How_to_prevent_trailing_whitespaces.html).
-     http://www.carbon-project.org/Vim__How_to_prevent_trailing_whitespaces.html
 
   2. Chase warnings: no warning should be introduced by your changes
   Depending what you touch, you can check with:
+
     2.1 When using autotools
+
             $ autoreconf -Wall -vis
+
     2.2 When compiling
+
       2.2.1 Using extra flags:
+
             $ export CFLAGS="-Wall -g -O2 -Wextra -pipe -funsigned-char -fstrict-aliasing \
               -Wchar-subscripts -Wundef -Wshadow -Wcast-align -Wwrite-strings -Wunused \
               -Wuninitialized -Wpointer-arith -Wredundant-decls -Winline -Wformat \
@@ -33,23 +37,32 @@ Here are some directions to get you started:
          $ ./configure
          $ make clean
          $ make
+
       2.2.2 Using clang:
-        You can use same CFLAGS but also "-Wunreachable-code"
+
+        You can use same CFLAGS but also `-Wunreachable-code`
+
             $ scan-build ./configure
          $ make clean
          $ scan-build make
-      2.2.3 Using cppcheck (v1.58 or higher):
+
+      2.2.3 Using `cppcheck` (v1.58 or higher):
+
           $ make cppcheck
+
     2.3 When Debianizing
+
          $ lintian --info --display-info --display-experimental *deb
         or (shorter version)
          $ lintian -iIE *deb
 
   3. Preserve cross-platform compatility
+
      The source code should remain compilable across various platforms,
      including some you probably cannot test alone so keep it in mind.
      Supported platforms:
+
      - Linux
      - FreeBSD
      - Mac OS X
-     - Windows with Mingw
+     - Windows with MinGW

README-Windows.md

@@ -33,7 +33,9 @@ is an example of how to generate a distribution with the above mentioned
 requirements fulfilled (it is assumed the CMake binaries are in the system
 path, this is optional during installation of CMake):
 
-- Add the following directories to your PATH : c:\MinGW64\bin;c:\MinGW64\x86_64-w64-mingw32\lib32;c:\MinGW64\x86_64-w64-mingw32\include
+- Add the following directories to your PATH:
+
+        c:\MinGW64\bin;c:\MinGW64\x86_64-w64-mingw32\lib32;c:\MinGW64\x86_64-w64-mingw32\include
 
 - Now it is possible to run CMake and mingw32-make:
 
@@ -62,5 +64,7 @@ References
 [1] the easiest way is to use the TDM-GCC installer.
         Make sure to select MinGW-w64 in the installer, the regular MinGW does not contain headers for PCSC.
         http://sourceforge.net/projects/tdm-gcc/files/TDM-GCC%20Installer/tdm64-gcc-4.5.1.exe/download
+
 [2] http://sourceforge.net/projects/libusb-win32/files/
+
 [3] http://www.cmake.org

README.md

@@ -1,3 +1,4 @@
+```
 *-
 * Free/Libre Near Field Communication (NFC) library
 *
@@ -10,6 +11,7 @@
 * Additional contributors:
 * See AUTHORS file
 -*
+```
 
 General Information
 ===================
@@ -46,11 +48,12 @@ http://cutter.sf.net
 Installation
 ============
 
-See the file 'INSTALL' for configure, build and install details.
+See the file `INSTALL` for configure, build and install details.
 
 Additionnally, you may need to grant permissions to your user to drive your device.
 Under GNU/Linux systems, if you use udev, you could use the provided udev rules.
   e.g. under Debian, Ubuntu, etc.
+
     sudo cp contrib/udev/42-pn53x.rules /lib/udev/rules.d/
 
 Under FreeBSD, if you use devd, there is also a rules file: contrib/devd/pn53x.conf.
@@ -64,13 +67,17 @@ configuration file located in sysconfdir (as provided to ./configure).
 A sample commented file is available in sources: libnfc.conf.sample
 
 If you have compiled using:
+
     ./configure --prefix=/usr --sysconfdir=/etc
+
 you can make configuration directory and copy the sample file:
+
     sudo mkdir /etc/nfc
     sudo cp libnfc.conf.sample /etc/nfc/libnfc.conf
 
 To configure multiple devices, you can either modify libnfc.conf or create a
 file per device in a nfc/devices.d directory:
+
     sudo mkdir -p /etc/nfc/devices.d
     printf 'name = "My first device"\nconnstring = "pn532_uart:/dev/ttyACM0"\n' | sudo tee /etc/nfc/devices.d/first.conf
     printf 'name = "My second device"\nconnstring = "pn532_uart:/dev/ttyACM1"\n' | sudo tee /etc/nfc/devices.d/second.conf
@@ -99,8 +106,11 @@ Please make sure to include:
 * A trace with debug activated.
 
   Reproduce the bug with debug, e.g. if it was:
+
         $ nfc-list -v
+
   run it as:
+
         $ LIBNFC_LOG_LEVEL=3 nfc-list -v
 
 * How to reproduce the bug.
@@ -137,27 +147,27 @@ Troubleshooting
 Touchatag/ACR122:
 -----------------
 If your Touchatag or ACR122 device fails being detected by libnfc, make sure
-that PCSC-lite daemon (pcscd) is installed and is running.
+that PCSC-lite daemon (`pcscd`) is installed and is running.
 
 If your Touchatag or ACR122 device fails being detected by PCSC-lite daemon
-(pcsc_scan doesn't see anything) then try removing the bogus firmware detection
+(`pcsc_scan` doesn't see anything) then try removing the bogus firmware detection
 of libccid: edit libccid_Info.plist configuration file (usually
-/etc/libccid_Info.plist) and locate "<key>ifdDriverOptions</key>", turn
+`/etc/libccid_Info.plist`) and locate `<key>ifdDriverOptions</key>`, turn
-"<string>0x0000</string>" value into 0x0004 to allow bogus devices and restart
+`<string>0x0000</string>` value into `0x0004` to allow bogus devices and restart
 pcscd daemon.
 
 ACR122:
 -------
 Using an ACR122 device with libnfc and without tag (e.g. to use NFCIP modes or
 card emulation) needs yet another PCSC-lite tweak: You need to allow usage of
-CCID Exchange command.  To do this, edit libccid_Info.plist configuration file
+CCID Exchange command.  To do this, edit `libccid_Info.plist` configuration file
-(usually /etc/libccid_Info.plist) and locate "<key>ifdDriverOptions</key>",
+(usually `/etc/libccid_Info.plist`) and locate `<key>ifdDriverOptions</key>`,
-turn "<string>0x0000</string>" value into 0x0001 to allow CCID exchange or
+turn `<string>0x0000</string>` value into `0x0001` to allow CCID exchange or
-0x0005 to allow CCID exchange and bogus devices (cf previous remark) and
+`0x0005` to allow CCID exchange and bogus devices (cf previous remark) and
 restart pcscd daemon.
 
 Warning: if you use ACS CCID drivers (acsccid), configuration file is located
-in something like: /usr/lib/pcsc/drivers/ifd-acsccid.bundle/Contents/Info.plist
+in something like: `/usr/lib/pcsc/drivers/ifd-acsccid.bundle/Contents/Info.plist`
 
 SCL3711:
 --------
@@ -172,6 +182,7 @@ Since Linux kernel version 3.1, two kernel-modules must not be loaded in order
 to use libnfc : "nfc" and "pn533".
 To prevent kernel from loading automatically these modules, you can blacklist
 them in a modprobe conf file. This file is provided within libnfc archive:
+
     sudo cp contrib/linux/blacklist-libnfc.conf /etc/modprobe.d/blacklist-libnfc.conf
 
 Proprietary Notes
@@ -181,4 +192,3 @@ FeliCa is a registered trademark of the Sony Corporation.
 MIFARE is a trademark of NXP Semiconductors.
 Jewel Topaz is a trademark of Innovision Research & Technology.
 All other trademarks are the property of their respective owners.
-