working on documentation

Surfshub · May 23, 2013 · 54579ae · 54579ae
1 parent ae8c086
commit 54579ae
Show file tree

Hide file tree

Showing 25 changed files with 303 additions and 244 deletions.
diff --git a/ccid/doc/README.txt b/ccid/doc/README.txt
@@ -1,24 +1,24 @@
 .. highlight:: sh
 
-.. |npa| replace:: :ref:`npa`
+.. |libnpa| replace:: :ref:`libnpa`
 .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
 
 .. _ccid-emulator:
 
-#################
+################################################################################
 USB CCID Emulator
-#################
+################################################################################
 
 :Author:
-    Frank Morgner <[email protected]>
+    `Frank Morgner <[email protected]>`_
 :License:
     GPL version 3
 :Tested Platforms:
     Linux (Debian, Ubuntu, OpenMoko)
 
 The USB CCID Emulator forwards a locally present PC/SC smart card reader as a
 standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary
-enabling secure PIN entry and PIN modification. In combination with the |npa|
+enabling secure PIN entry and PIN modification. In combination with the |libnpa|
 also |PACE| can be performed by the emulator.
 
 If the machine running :command:`ccid-emulator` is in USB device mode, a local
@@ -56,7 +56,7 @@ Running the USB CCID Emulator has the following dependencies:
 
 - Linux Kernel with GadgetFS_
 - OpenSC_
-- |npa| (only if support for |PACE| is enabled)
+- |libnpa| (only if support for |PACE| is enabled)
 
 Whereas using the USB CCID Emulator on the host system as smart card reader only
 needs a usable PC/SC middleware with USB CCID driver. This is the case for most
@@ -69,8 +69,7 @@ Hints on GadgetFS
 
 To create a USB Gadget in both USB host and USB client mode, you need to load
 the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
-to run and compile GadgetFS, you can find in the `OpenMoko Wiki
-<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
+to run and compile GadgetFS, you can find in the `OpenMoko Wiki`_.
 
 On OpenMoko it is likely that you need to `patch your kernel
 <http://docs.openmoko.org/trac/ticket/2206>`_. If you also want to switch
@@ -86,24 +85,28 @@ loading the module, you maybe want to check out `this patch
 Hints on OpenSC
 ===============
 
-Without the |npa| the USB CCID Emulator links against OpenSC, which is discouraged
-and hindered since OpenSC version >= 0.12. You need the OpenSC components to be
+Without the |libnpa| the USB CCID Emulator needs the OpenSC components to be
 installed (especially :file:`libopensc.so`). Here is an example of how to get
 the standard installation of OpenSC without |PACE|::
 
     PREFIX=/tmp/install
-    OPENSC=opensc
-    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
-    cd $OPENSC
-    autoreconf -i
+    VSMARTCARD=vsmartcard
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard $VSMARTCARD
+    cd $VSMARTCARD/ccid/src/opensc
+    autoreconf --verbose --install
     ./configure --prefix=$PREFIX
-    make
-    make install
+    make install && cd -
 
 Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
 configure the USB CCID Emulator to use it::
 
-    ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
+    cd $VSMARTCARD/ccid
+    ./configure --prefix=$PREFIX OPENSC_LIBS="-L$PREFIX/lib -lopensc"
+    make install && cd -
+
+If you want |PACE| support for the emulated smart card reader the process is
+similar. Install |libnpa| and it should be recognized automatically by the
+:file:`configure` script.
 
 
 *****
@@ -113,9 +116,9 @@ Usage
 The USB CCID Emulator has various command line options to customize the appearance
 on the USB host. In order to run the USB CCID Emulator GadgetFS must be loaded
 and mounted.  The USB CCID Emulator is compatible with the unix driver libccid_
-and the `Windows USB CCID driver
-<http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_. To initialize
-|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`).
+and the `Windows USB CCID driver`_. To initialize |PACE| using the PC/SC API
+you need to patch libccid (see :file:`patches`). On Windows, the USB CCID Emulator
+currently has no support for |PACE|.
 
 .. program-output:: ccid-emulator --help
 
@@ -129,8 +132,9 @@ Notes and References
 
 .. target-notes::
 
-.. [#f1] Note that the heavily outdated `Windows USB CCID driver`_ does not support secure PIN entry or PIN modification. USB CCID Emulator comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.
-.. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509
-.. _`OpenSC`: http://www.opensc-project.org/opensc
 .. _`GadgetFS`: http://www.linux-usb.org/gadget/
+.. _`OpenSC`: http://www.opensc-project.org/opensc
 .. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html
+.. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509
+.. _`OpenMoko Wiki`: http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_
+.. [#f1] Note that the heavily outdated Windows USB CCID driver does not support secure PIN entry or PIN modification. USB CCID Emulator comes with a patch for libccid to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.
diff --git a/ccid/doc/README.txt.in b/ccid/doc/README.txt.in
@@ -1,36 +1,36 @@
 .. highlight:: sh
 
-.. |npa| replace:: :ref:`npa`
+.. |libnpa| replace:: :ref:`libnpa`
 .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
 
 .. _ccid-emulator:
 
-#################
-USB CCID Emulator
-#################
+################################################################################
+@PACKAGE_NAME@
+################################################################################
 
 :Author:
-    Frank Morgner <[email protected]>
+    `Frank Morgner <[email protected]>`_
 :License:
     GPL version 3
 :Tested Platforms:
     Linux (Debian, Ubuntu, OpenMoko)
 
-The USB CCID Emulator forwards a locally present PC/SC smart card reader as a
-standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary
-enabling secure PIN entry and PIN modification. In combination with the |npa|
+The @PACKAGE_NAME@ forwards a locally present PC/SC smart card reader as a
+standard USB CCID reader. @PACKAGE_NAME@ can be used as trusted intermediary
+enabling secure PIN entry and PIN modification. In combination with the |libnpa|
 also |PACE| can be performed by the emulator.
 
 If the machine running :command:`ccid-emulator` is in USB device mode, a local
 reader is forwareded via USB to another machine. If in USB host mode, the USB
 CCID reader will locally be present.
 
-Applications on Windows and Unix-like systems can access the USB CCID Emulator
+Applications on Windows and Unix-like systems can access the @PACKAGE_NAME@
 through PC/SC as if it was a real smart card reader. No installation of a smart
 card driver is required since USB CCID drivers are usually shipped with the
 modern OS. [#f1]_
 
-Here is a subset of USB CCID commands supported by the USB CCID Emulator with
+Here is a subset of USB CCID commands supported by the @PACKAGE_NAME@ with
 their PC/SC counterpart:
 
 ================================== ============================================================
@@ -41,7 +41,7 @@ USB CCID                           PC/SC
 ``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE``
 ================================== ============================================================
 
-The USB CCID Emulator is implemented using GadgetFS_. Some fragments of the source
+The @PACKAGE_NAME@ is implemented using GadgetFS_. Some fragments of the source
 code are based on the GadgetFS example and on the source code of the OpenSC
 tools.
 
@@ -52,13 +52,13 @@ tools.
 
 .. include:: autotools.txt
 
-Running the USB CCID Emulator has the following dependencies:
+Running the @PACKAGE_NAME@ has the following dependencies:
 
 - Linux Kernel with GadgetFS_
 - OpenSC_
-- |npa| (only if support for |PACE| is enabled)
+- |libnpa| (only if support for |PACE| is enabled)
 
-Whereas using the USB CCID Emulator on the host system as smart card reader only
+Whereas using the @PACKAGE_NAME@ on the host system as smart card reader only
 needs a usable PC/SC middleware with USB CCID driver. This is the case for most
 modern Windows and Unix-like systems by default.
 
@@ -69,8 +69,7 @@ Hints on GadgetFS
 
 To create a USB Gadget in both USB host and USB client mode, you need to load
 the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
-to run and compile GadgetFS, you can find in the `OpenMoko Wiki
-<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
+to run and compile GadgetFS, you can find in the `OpenMoko Wiki`_.
 
 On OpenMoko it is likely that you need to `patch your kernel
 <http://docs.openmoko.org/trac/ticket/2206>`_. If you also want to switch
@@ -86,36 +85,40 @@ loading the module, you maybe want to check out `this patch
 Hints on OpenSC
 ===============
 
-Without the |npa| the USB CCID Emulator links against OpenSC, which is discouraged
-and hindered since OpenSC version >= 0.12. You need the OpenSC components to be
+Without the |libnpa| the @PACKAGE_NAME@ needs the OpenSC components to be
 installed (especially :file:`libopensc.so`). Here is an example of how to get
 the standard installation of OpenSC without |PACE|::
 
     PREFIX=/tmp/install
-    OPENSC=opensc
-    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
-    cd $OPENSC
-    autoreconf -i
+    VSMARTCARD=vsmartcard
+    git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard $VSMARTCARD
+    cd $VSMARTCARD/ccid/src/opensc
+    autoreconf --verbose --install
     ./configure --prefix=$PREFIX
-    make
-    make install
+    make install && cd -
 
 Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
-configure the USB CCID Emulator to use it::
+configure the @PACKAGE_NAME@ to use it::
 
-    ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
+    cd $VSMARTCARD/ccid
+    ./configure --prefix=$PREFIX OPENSC_LIBS="-L$PREFIX/lib -lopensc"
+    make install && cd -
+
+If you want |PACE| support for the emulated smart card reader the process is
+similar. Install |libnpa| and it should be recognized automatically by the
+:file:`configure` script.
 
 
 *****
 Usage
 *****
 
-The USB CCID Emulator has various command line options to customize the appearance
-on the USB host. In order to run the USB CCID Emulator GadgetFS must be loaded
-and mounted.  The USB CCID Emulator is compatible with the unix driver libccid_
-and the `Windows USB CCID driver
-<http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_. To initialize
-|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`).
+The @PACKAGE_NAME@ has various command line options to customize the appearance
+on the USB host. In order to run the @PACKAGE_NAME@ GadgetFS must be loaded
+and mounted.  The @PACKAGE_NAME@ is compatible with the unix driver libccid_
+and the `Windows USB CCID driver`_. To initialize |PACE| using the PC/SC API
+you need to patch libccid (see :file:`patches`). On Windows, the @PACKAGE_NAME@
+currently has no support for |PACE|.
 
 .. program-output:: ccid-emulator --help
 
@@ -129,8 +132,9 @@ Notes and References
 
 .. target-notes::
 
-.. [#f1] Note that the heavily outdated `Windows USB CCID driver`_ does not support secure PIN entry or PIN modification. USB CCID Emulator comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.
-.. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509
-.. _`OpenSC`: http://www.opensc-project.org/opensc
 .. _`GadgetFS`: http://www.linux-usb.org/gadget/
+.. _`OpenSC`: http://www.opensc-project.org/opensc
 .. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html
+.. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509
+.. _`OpenMoko Wiki`: http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_
+.. [#f1] Note that the heavily outdated Windows USB CCID driver does not support secure PIN entry or PIN modification. @PACKAGE_NAME@ comes with a patch for libccid to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.
diff --git a/ccid/doc/autotools.txt b/ccid/doc/autotools.txt
@@ -5,10 +5,10 @@ Installation
 ************
 
 The USB CCID Emulator uses the GNU Build System to compile and install. If you are
-unfamiliar with it, please have a look at :file:`INSTALL`. If you have a look
-around and can not find it, you are probably working bleeding edge in the
-repository.  Run the following command in :file:`ccid-emulator` to
-get the missing standard auxiliary files::
+unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
+it, you are probably working bleeding edge in the repository.  Run the
+following command in :file:`ccid-emulator` to get the missing standard
+auxiliary files::
 
     autoreconf --verbose --install
 

diff --git a/ccid/doc/download.txt b/ccid/doc/download.txt
@@ -4,7 +4,7 @@
 Download
 ********
 
-You can find the latest release of USB CCID Emulator `here
+You can find the latest release of USB CCID Emulator on `Sourceforge
 <http://sourceforge.net/projects/vsmartcard/files>`_.
 
 Alternatively, you can clone our git repository::

diff --git a/doc/autotools.txt.in b/doc/autotools.txt.in
@@ -5,10 +5,10 @@ Installation
 ************
 
 The @PACKAGE_NAME@ uses the GNU Build System to compile and install. If you are
-unfamiliar with it, please have a look at :file:`INSTALL`. If you have a look
-around and can not find it, you are probably working bleeding edge in the
-repository.  Run the following command in :file:`@PACKAGE_TARNAME@` to
-get the missing standard auxiliary files::
+unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
+it, you are probably working bleeding edge in the repository.  Run the
+following command in :file:`@PACKAGE_TARNAME@` to get the missing standard
+auxiliary files::
 
     autoreconf --verbose --install
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -74,7 +74,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '*/questions.txt', '*/autotools.txt', '*/download.txt']
+exclude_patterns = ['_build', '*/questions.txt', '*/autotools.txt', '*/download.txt', '*/relay-note.txt']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -148,10 +148,10 @@
 #html_additional_pages = {}
 
 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = False
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False

diff --git a/doc/download.txt.in b/doc/download.txt.in
@@ -4,7 +4,7 @@
 Download
 ********
 
-You can find the latest release of @PACKAGE_NAME@ `here
+You can find the latest release of @PACKAGE_NAME@ on `Sourceforge
 <http://sourceforge.net/projects/vsmartcard/files>`_.
 
 Alternatively, you can clone our git repository::