Merge pull request #344 from hiddewie/markdown2

Actual Markdown for the README and HACKING files

HACKING.md

@@ -15,41 +15,54 @@ 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
+
+            $ 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 \
+            $ export CFLAGS="-Wall -g -O2 -Wextra -pipe -funsigned-char -fstrict-aliasing \
-          -Wuninitialized -Wpointer-arith -Wredundant-decls -Winline -Wformat \
+              -Wchar-subscripts -Wundef -Wshadow -Wcast-align -Wwrite-strings -Wunused \
-          -Wformat-security -Wswitch-enum -Winit-self -Wmissing-include-dirs \
+              -Wuninitialized -Wpointer-arith -Wredundant-decls -Winline -Wformat \
-          -Wmissing-prototypes -Wstrict-prototypes -Wold-style-definition \
+              -Wformat-security -Wswitch-enum -Winit-self -Wmissing-include-dirs \
-          -Wbad-function-cast -Wnested-externs -Wmissing-declarations"
+              -Wmissing-prototypes -Wstrict-prototypes -Wold-style-definition \
-        $ ./configure
+              -Wbad-function-cast -Wnested-externs -Wmissing-declarations"
-        $ make clean
+         $ ./configure
-        $ make
+         $ make clean
+         $ make
+
       2.2.2 Using clang:
-        You can use same CFLAGS but also "-Wunreachable-code"
+
-        $ scan-build ./configure
+        You can use same CFLAGS but also `-Wunreachable-code`
-        $ make clean
+
-        $ scan-build make
+            $ scan-build ./configure
-      2.2.3 Using cppcheck (v1.58 or higher):
+         $ make clean
-        $ make cppcheck
+         $ scan-build make
+
+      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 --info --display-info --display-experimental *deb
-      $ lintian -iIE *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

@@ -1,16 +1,16 @@
-*-
+    *-
-* Free/Libre Near Field Communication (NFC) library
+    * Free/Libre Near Field Communication (NFC) library
-*
+    *
-* Libnfc historical contributors:
+    * Libnfc historical contributors:
-* Copyright (C) 2009      Roel Verdult
+    * Copyright (C) 2009      Roel Verdult
-* Copyright (C) 2009-2013 Romuald Conty
+    * Copyright (C) 2009-2013 Romuald Conty
-* Copyright (C) 2010-2012 Romain Tartière
+    * Copyright (C) 2010-2012 Romain Tartière
-* Copyright (C) 2010-2013 Philippe Teuwen
+    * Copyright (C) 2010-2013 Philippe Teuwen
-* Copyright (C) 2012-2013 Ludovic Rousseau
+    * Copyright (C) 2012-2013 Ludovic Rousseau
-* Additional contributors of Windows-specific parts:
+    * Additional contributors of Windows-specific parts:
-* Copyright (C) 2010      Glenn Ergeerts
+    * Copyright (C) 2010      Glenn Ergeerts
-* Copyright (C) 2013      Alex Lian
+    * Copyright (C) 2013      Alex Lian
--*
+    -*
 
 Requirements
 ============
@@ -20,7 +20,7 @@ Requirements
 - CMake 2.8 [3]
 
 This was tested on Windows 7 64 bit, but should work on Windows Vista and
-Windows XP and 32 bit as well. 
+Windows XP and 32 bit as well.
 Only the ACS ACR122 and the ASK Logo readers are tested at the moment, so any feedback about other devices is very welcome.
 
 Community forum: http://www.libnfc.org/community/
@@ -33,34 +33,38 @@ 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:
 
-  C:\dev\libnfc-read-only> mkdir ..\libnfc-build
+        C:\dev\libnfc-read-only> mkdir ..\libnfc-build
-  C:\dev\libnfc-read-only> cd ..\libnfc-build
+      C:\dev\libnfc-read-only> cd ..\libnfc-build
-  C:\dev\libnfc-build> cmake-gui .
+      C:\dev\libnfc-build> cmake-gui .
-  
+
 Now you can configure the build. Press "Configure", specify "MinGW32 Makefiles"
 and then you have the opportunity to set some configuration variables. If you
 don't want a Debug build change the variable CMAKE_BUILD_TYPE to "Release".
 
 If a non-GUI solution is preferred one can use:
 
-  C:\dev\libnfc-build> cmake -G "MinGW Makefiles"
+    C:\dev\libnfc-build> cmake -G "MinGW Makefiles"
                                      -DCMAKE_BUILD_TYPE=Release ..\libnfc-read-only
 
 Now run mingw32-make to build:
 
-  C:\dev\libnfc-read-only\bin> mingw32-make
+    C:\dev\libnfc-read-only\bin> mingw32-make
-  
+
 The build will create a shared library for Windows (nfc.dll) to link your applications against. It will compile
-the tools against this shared library. 
+the tools against this shared library.
 
 References
 ==========
-[1] the easiest way is to use the TDM-GCC installer. 
+[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,6 +1,7 @@
+```
 *-
 * Free/Libre Near Field Communication (NFC) library
-* 
+*
 * Libnfc historical contributors:
 * Copyright (C) 2009      Roel Verdult
 * Copyright (C) 2009-2015 Romuald Conty
@@ -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,16 +67,20 @@ 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
+
+    ./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
+    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
+    sudo mkdir -p /etc/nfc/devices.d
-  printf 'name = "My second device"\nconnstring = "pn532_uart:/dev/ttyACM1"\n' | sudo tee /etc/nfc/devices.d/second.conf
+    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
 
 How to report bugs
 ==================
@@ -82,7 +89,7 @@ To report a bug, visit https://github.com/nfc-tools/libnfc/issues and fill
 out a bug report form.
 
 If you have questions, remarks, we encourage you to post this in the developers
-community: 
+community:
 http://www.libnfc.org/community
 
 Please make sure to include:
@@ -99,14 +106,17 @@ Please make sure to include:
 * A trace with debug activated.
 
   Reproduce the bug with debug, e.g. if it was:
-  $ nfc-list -v
+
+        $ nfc-list -v
+
   run it as:
-  $ LIBNFC_LOG_LEVEL=3 nfc-list -v
+
+        $ LIBNFC_LOG_LEVEL=3 nfc-list -v
 
 * How to reproduce the bug.
 
-  Please include a short test program that exhibits the behavior. 
+  Please include a short test program that exhibits the behavior.
-  As a last resort, you can also provide a pointer to a larger piece 
+  As a last resort, you can also provide a pointer to a larger piece
   of software that can be downloaded.
 
 * If the bug was a crash, the exact text that was printed out
@@ -128,8 +138,8 @@ Building
 
 It should be as simple as running these two commands:
 
-./configure
+    ./configure
-make
+    make
 
 Troubleshooting
 ===============
@@ -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,7 +182,8 @@ 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
+
+    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.
-