John Mulligan avatar John Mulligan committed 4f8f2a1

clean up docs intro

Comments (0)

Files changed (1)

doc/source/index.rst

 -------------
 
 This library provides modules for Python 2.x that expose some of the
-more recent File System related API calls in POSIX.1-2008. This includes
-the functions openat, mkdirat, unlinkat, and other similar calls suffixed
+useful File System related API calls, including some of those added
+in POSIX.1-2008. This includes the functions openat, mkdirat, unlinkat,
+and other similar calls suffixed
 with "at". These calls exist to help defend against race conditions and
 support thread-level working directories. Typically these functions take
 one or more directory file descriptor and a relative path as arguments.
+This library also comes with custom directory listing functions that
+mimic os.listdir by default but can provide additional information
+(d_type) when passed a flag. Similarly, file discriptor and iterator
+based versions are also available.
 
 Additionally, this library provides a util module that has a higher level
 interface for working with open directories and other functions that
 use the lower level library calls.
 
-The api for these functions should be compatible with the functions
-that will be available in Python 3.3 and above, if said function is
-present in the posix module.
-
 
 Examples
 -----------
 ['0', '1', '3', '5', '7', '9', '11', '13', '15', '17']
 
 
+Compatibility
+-------------
 
+The api for the POSIX.1-2008 `*at` functions should be compatible with the
+functions that will be available in Python 3.3 and above,
+if said function is present in the posix module. If you use both and find
+differences, please let me know.
 
+The listdir-like functions should behave similarly to os.lisdir when
+not passed any flags. The extended listdir calls are designed only to
+vary where appropriate.
 
+I am currently testing against Linux and FreeBSD. Specifically,
+Fedora 14 and up and FreeBSD 9.0. If you think the module should work
+on your platform and it does not, please report a bug. Please be aware
+that I do not have access to proprietary/esoteric platforms. This module
+will not work on Windows systems.
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
 
 Indices and tables
 ==================
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.