VivoKey/vsmartcard
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

respect sphinx style guide to some extent

Browse Source 
see http://documentation-style-guide-sphinx.readthedocs.org/en/latest/style-guide.html
This commit is contained in:
Frank Morgner
2013-03-05 20:42:09 +01:00
parent 9be74c7886
commit 37e5f9d514
74 changed files with 488 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ccid/README
View File

@@ -1 +1 @@
doc/README.rst
doc/README.txt

10
ccid/doc/Makefile.am
View File

@@ -16,13 +16,13 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(top_srcdir),g'
EXTRA_DIST = README.rst.in README.rst autotools.rst autotools.rst.in questions.rst questions.rst.in download.rst.in download.rst
EXTRA_DIST = README.txt.in README.txt autotools.txt autotools.txt.in questions.txt questions.txt.in download.txt.in download.txt
doc: *.in
$(do_subst) < autotools.rst.in > autotools.rst
$(do_subst) < questions.rst.in > questions.rst
$(do_subst) < download.rst.in > download.rst
$(do_subst) < README.rst.in > README.rst
$(do_subst) < autotools.txt.in > autotools.txt
$(do_subst) < questions.txt.in > questions.txt
$(do_subst) < download.txt.in > download.txt
$(do_subst) < README.txt.in > README.txt
touch doc
clean-local:

51
ccid/doc/README.rst → ccid/doc/README.txt
View File

@@ -1,17 +1,13 @@
.. highlight:: sh
.. _OpenSC: http://www.opensc-project.org/opensc
.. _GadgetFS: http://www.linux-usb.org/gadget/
.. _libccid: http://pcsclite.alioth.debian.org/ccid.html
.. |npa| replace:: :ref:`npa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _ccid-emulator:
********************************************************************************
#################
USB CCID Emulator
********************************************************************************
#################
:Author:
Frank Morgner <morgner@informatik.hu-berlin.de>
@@ -46,17 +42,15 @@ USB CCID PC/SC
================================== ============================================================
The USB CCID Emulator is implemented using GadgetFS_. Some fragments of the source
code are based on the GadgetFS example and on the source code of the OpenSC_
code are based on the GadgetFS example and on the source code of the OpenSC
tools.
.. [#f1] Note that the heavily outdated `Windows USB CCID driver <http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_ 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.
.. include:: download.txt
.. include:: download.rst
.. include:: autotools.rst
.. include:: autotools.txt
Running the USB CCID Emulator has the following dependencies:
@@ -69,13 +63,13 @@ needs a usable PC/SC middleware with USB CCID driver. This is the case for most
modern Windows and Unix-like systems by default.
-----------------
=================
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 `here
to run and compile GadgetFS, you can find in the `OpenMoko Wiki
<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
On OpenMoko it is likely that you need to `patch your kernel
@@ -88,14 +82,14 @@ loading the module, you maybe want to check out `this patch
<http://comments.gmane.org/gmane.linux.usb.general/47440>`_.
---------------
===============
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
installed (especially :file:`libopensc.so`). Here is an example of how to get
the standard installation of OpenSC_ without |PACE|::
the standard installation of OpenSC without |PACE|::
PREFIX=/tmp/install
OPENSC=opensc
@@ -112,12 +106,12 @@ configure the USB CCID Emulator to use it::
./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
=====
*****
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
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
@@ -126,4 +120,17 @@ and the `Windows USB CCID driver
.. program-output:: ccid-emulator --help
.. include:: questions.rst
.. include:: questions.txt
********************
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/
.. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html

79
ccid/doc/README.rst.in → ccid/doc/README.txt.in
View File

@@ -1,17 +1,13 @@
.. highlight:: sh
.. _OpenSC: http://www.opensc-project.org/opensc
.. _GadgetFS: http://www.linux-usb.org/gadget/
.. _libccid: http://pcsclite.alioth.debian.org/ccid.html
.. |npa| replace:: :ref:`npa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _ccid-emulator:
********************************************************************************
@PACKAGE_NAME@
********************************************************************************
#################
USB CCID Emulator
#################
:Author:
Frank Morgner <morgner@informatik.hu-berlin.de>
@@ -20,21 +16,21 @@
:Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
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
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|
also |PACE| can be performed by the emulator.
If the machine running :command:`@PACKAGE@` is in USB device mode, a local
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 @PACKAGE_NAME@
Applications on Windows and Unix-like systems can access the USB CCID Emulator
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 @PACKAGE_NAME@ with
Here is a subset of USB CCID commands supported by the USB CCID Emulator with
their PC/SC counterpart:
================================== ============================================================
@@ -45,37 +41,35 @@ USB CCID PC/SC
``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE``
================================== ============================================================
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_
The USB CCID Emulator 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.
.. [#f1] Note that the heavily outdated `Windows USB CCID driver <http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_ 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.
.. include:: download.txt
.. include:: download.rst
.. include:: autotools.txt
.. include:: autotools.rst
Running the @PACKAGE_NAME@ has the following dependencies:
Running the USB CCID Emulator has the following dependencies:
- Linux Kernel with GadgetFS_
- OpenSC_
- |npa| (only if support for |PACE| is enabled)
Whereas using the @PACKAGE_NAME@ on the host system as smart card reader only
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
modern Windows and Unix-like systems by default.
-----------------
=================
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 `here
to run and compile GadgetFS, you can find in the `OpenMoko Wiki
<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
On OpenMoko it is likely that you need to `patch your kernel
@@ -88,14 +82,14 @@ loading the module, you maybe want to check out `this patch
<http://comments.gmane.org/gmane.linux.usb.general/47440>`_.
---------------
===============
Hints on OpenSC
---------------
===============
Without the |npa| the @PACKAGE_NAME@ links against OpenSC, which is discouraged
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
installed (especially :file:`libopensc.so`). Here is an example of how to get
the standard installation of OpenSC_ without |PACE|::
the standard installation of OpenSC without |PACE|::
PREFIX=/tmp/install
OPENSC=opensc
@@ -107,23 +101,36 @@ the standard installation of OpenSC_ without |PACE|::
make install
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
configure the @PACKAGE_NAME@ to use it::
configure the USB CCID Emulator to use it::
./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
=====
*****
Usage
=====
*****
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_
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`).
.. program-output:: @PACKAGE@ --help
.. program-output:: ccid-emulator --help
.. include:: questions.rst
.. include:: questions.txt
********************
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/
.. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html

1
ccid/doc/autotools.rst.in
View File

@@ -1 +0,0 @@
../../doc/autotools.rst.in

4
ccid/doc/autotools.rst → ccid/doc/autotools.txt
View File

@@ -1,8 +1,8 @@
.. highlight:: sh
============
************
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

1
ccid/doc/autotools.txt.in Symbolic link
View File

@@ -0,0 +1 @@
../../doc/autotools.txt.in

1
ccid/doc/download.rst.in
View File

@@ -1 +0,0 @@
../../doc/download.rst.in

12
ccid/doc/download.txt Normal file
View File

@@ -0,0 +1,12 @@
.. highlight:: sh
********
Download
********
You can find the latest release of USB CCID Emulator `here
<http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository::
git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard/vsmartcard

1
ccid/doc/download.txt.in Symbolic link
View File

@@ -0,0 +1 @@
../../doc/download.txt.in

1
ccid/doc/questions.rst.in
View File

@@ -1 +0,0 @@
../../doc/questions.rst.in

4
ccid/doc/questions.rst → ccid/doc/questions.txt
View File

@@ -1,6 +1,6 @@
========
********
Question
========
********
Do you have questions, suggestions or contributions? Feedback of any kind is
more than welcome! Please use our `project trackers <http://sourceforge.net/projects/vsmartcard/support>`_.

1
ccid/doc/questions.txt.in Symbolic link
View File

@@ -0,0 +1 @@
../../doc/questions.txt.in