Documentation cleanup.

Signed-off-by: Chris Lalancette <[email protected]>

docs/README.md

@@ -1,7 +1,7 @@
 # PyCdlib
 PyCdlib is a pure python library to parse, write (master), create, and manipulate ISO9660 files.  These files are suitable for writing to a CD or USB.
 
-The documentation for PyCdlib is split into several parts.  If you are unfamiliar with the ISO and related standards, it is probably best to read the pages in order.  If you already have a decent idea about ISO9660, Joliet, Rock Ridge, and UDF, you can skip directly to the examples.
+The documentation for PyCdlib is split into several parts.  If you are unfamiliar with the ISO and related standards, it is probably best to read the pages in order.  If you already have a decent idea about ISO9660, Joliet, Rock Ridge, El Torito, and UDF, you can skip directly to the examples.
 
 * [Standards](standards.md)
 * [Python compatibility](python-compatibility.md)

docs/design.md

@@ -17,7 +17,7 @@ The original motivation for writing the library was to replace the subprocess ca
 * Relatively simple API.
 * Python 2 and Python 3 compatibility.
 * Expansive test coverage.
-* Limited in-place modification of existing ISOs, something that none of the other libraries support.
+* In-place modification of existing ISOs, something that none of the other libraries support.
 * Performance approaching that of genisoimage.
 
 ## Non-Goals
@@ -31,7 +31,7 @@ The [cdrkit](https://launchpad.net/cdrkit) project mentioned in the Context sect
 
 ## PyCdlib solution
 
-PyCdlib allows the user to either open an existing ISO or create a new ISO from scratch.  From that point forward, the ISO can be manipulated or introspected in various ways by 
+PyCdlib allows the user to either open an existing ISO or create a new ISO from scratch.  From that point forward, the ISO can be manipulated or introspected in various ways by calling additional APIs on the object.  Once the filesystem has been modified to the users specification, it can then be written out to a file descriptor.
 
 ## Testing
 

docs/example-creating-bootable-iso.md

@@ -1,5 +1,4 @@
 # Example: Creating a bootable ISO (El Torito)
-
 This example will show how to create a bootable [El Torito](standards.md#el-torito) ISO.  Here's the complete code for the example:
 
 ```

docs/example-creating-hybrid-bootable-iso.md

@@ -1,5 +1,4 @@
 # Example: Creating a "hybrid" bootable ISO
-
 The first 32768 bytes of any ISO are designated as "system use".  In a normal ISO (even an El Torito bootable one), these bytes are all zero, but this space can also be used to add in alternative booting mechanisms.  In particular, this space can be used to embed boot code so that the file can be written to a USB stick and booted.  These so called "hybrid" ISO files thus have two booting mechanisms: if the file is actually burned to a CD, then "El Torito" is used to boot, but if it is written to a USB stick, then the system use boot code is used to boot.  PyCdlib supports creating hybrid bootable ISOs through the main API, and the following example will show how.
 
 Here's the complete code for the example:

docs/example-creating-joliet-iso.md

@@ -1,5 +1,4 @@
 # Example: Creating an ISO with Joliet extensions
-
 This example will show how to create an ISO with the [Joliet](standards.md#joliet) extensions.  Here's the complete code for the example:
 
 ```

docs/example-creating-new-basic-iso.md

@@ -1,5 +1,4 @@
 # Example: Creating a new, basic ISO
-
 This example will show how to create a new, basic ISO with no extensions.  Here's the complete code for this example:
 
 ```

docs/example-creating-rock-ridge-iso.md

@@ -1,5 +1,4 @@
 # Example: Creating an ISO with Rock Ridge extensions
-
 This example will show how to create an ISO with the [Rock Ridge](standards.md#rock-ridge) extensions.  Here's the complete code for the example:
 
 ```

docs/example-creating-udf-iso.md

@@ -1,5 +1,4 @@
 # Example: Creating an ISO with UDF
-
 This example will show how to create an ISO with the [UDF](standards.md#udf) bridge format.  Here's the complete code for the example:
 
 ```

docs/example-extracting-data-from-iso.md

@@ -1,5 +1,4 @@
 # Example: Extracting data from an existing ISO
-
 This example will show how to extract data from an existing ISO.  Here's the complete code for this example:
 
 ```

docs/example-forcing-consistency.md

@@ -1,9 +1,8 @@
 # Example: Forcing consistency
-
 As discussed in the example [introduction](examples.md#pycdlib-theory-of-operation), PyCdlib takes a lazy approach to updating metadata.  For performance reasons it is recommended to let PyCdlib handle when and how to update the metadata, but sometimes users need the metadata to be consistent immediately.  PyCdlib offers two solutions for this:
 
 1.  There is an API called [force_consistency](pycdlib-api.html#PyCdlib-force_consistency) that immediately updates all metadata to the latest.
-1.  When initially creating the PyCdlib object, the user can set the `always_consistent` parameter to True.  When this is True, PyCdlib will update the metadata after every operation, ensuring that it is always up-to-date.
+1.  When initially creating the PyCdlib object, the user can set the `always_consistent` parameter.  When this is True, PyCdlib will update the metadata after every operation, ensuring that it is always up-to-date.
 
 Of the two, using lazy metadata updating and only calling [force_consistency](pycdlib-api.html#PyCdlib-force_consistency) when absolutely needed is highly preferred.  Using `always_consistent` is only needed in specialized cases (such as first modifying, then introspecting the extent number that a file exists on the ISO).  The following example will use [force_consistency](pycdlib-api.html#PyCdlib-force_consistency) at a particular point to cause the metadata to be updated.  To learn how to use `always_consistent`, please see the documentation for the `__init__` method for PyCdlib.
 

docs/example-managing-hard-links.md

@@ -1,5 +1,4 @@
 # Example: Managing hard-links on an ISO
-
 PyCdlib supports an advanced concept called hard-links, which is multiple names for the same piece of data (this is somewhat similar to Unix hard-links).  Most users will not need to use this functionality and should stick with the standard [add_file](pycdlib-api.html#PyCdlib-add_file) and [rm_file](pycdlib-api.html#PyCdlib-rm_file) APIs.  However, for those that want to do more advanced things like hiding a file from Joliet while having it remain visible in ISO9660, this functionality can be useful.
 
 On an ISO, a piece of data can be referred to (possibly several times) from four different contexts:

docs/example-modifying-file-in-place.md

@@ -1,5 +1,4 @@
 # Example: Modifying a file in place
-
 This example will show how to use one of the unique features of PyCdlib, the ability to modify a file in place.  While this doesn't seem like a big deal, it is actually somewhat difficult to achieve in an ISO.  The reason is that modifying a file usually involves moving around a lot of metadata, and additionally may require moving around data as well.  For these reasons, PyCdlib has limitations when modifying a file in place.  In particular:
 
 1.  Only files can be modified in place; directories cannot be changed.

docs/example-opening-existing-iso.md

@@ -1,5 +1,4 @@
 # Example: Opening an existing ISO
-
 This example will show how to examine an existing ISO.  Here's the complete code for this example:
 
 ```

docs/example-reading-file-in-chunks.md

@@ -1,5 +1,4 @@
 # Example: Reading a large file in chunks
-
 It may be useful in some applications to be able to read a file from an ISO a bit at a time and do some processing on it.  PyCdlib provides the context manager [open_file_from_iso](pycdlib-api.html#PyCdlib-open_file_from_iso) API to allow opening a file and reading in parts of it.  Here's the complete code for this example:
 
 ```

docs/example-walking-iso-filesystem.md

@@ -1,5 +1,4 @@
 # Example: Walking the ISO filesystem
-
 In some circumstances it may be useful to walk all or some of the filesystem tree on the ISO.  For that purpose, PyCdlib provides the [walk](pycdlib-api.html#PyCdlib-walk) API.  Much like the built-in Python [os.walk](https://docs.python.org/3.6/library/os.html#os.walk) API, this method takes a PyCdlib full path, and iterates over the entire filesystem starting at that root.  For each directory, the method returns a 3-tuple of `(dirpath, dirnames, filenames)` that can be used by the user.  Here's the complete code for this example:
 
 ```

docs/examples.md

@@ -9,7 +9,6 @@ To start using the PyCdlib API, the user must create a new PyCdlib object.  A Py
 Due to some historical aspects of the ISO standards, making modifications to an existing ISO can involve shuffling around a lot of metadata.  In order to maintain decent performance, PyCdlib takes a "lazy" approach to updating that metadata, and only does the update when it needs the results.  This allows the user to make several modifications and effectively "batch" operations without significantly impacting speed.  The minor downside to this is that the metadata stored in the PyCdlib object is not always consistent, so if the user wants to reach into the object to look at a particular field, it may not always be up-to-date.  PyCdlib offers a [force\_consistency](pycdlib-api.html#PyCdlib-force_consistency) API that immediately updates all metadata for just this reason.
 
 ## Example format
-
 We'll start out each example with the entire source code needed to run the example, and then break down the code to show what the individual pieces do.  Note that in most cases, error handling is elided for brevity, though it probably shouldn't be in real code.
 
 * [Creating a new, basic ISO](example-creating-new-basic-iso.md)

docs/standards.md

@@ -3,7 +3,7 @@ The original ISO9660 standard is fairly old, having first been ratified in 1988.
 
 - [ISO 9660:1988](https://en.wikipedia.org/wiki/ISO_9660).  The original ISO9660 standard.  Also known as [Ecma-119](https://www.ecma-international.org/publications/standards/Ecma-119.htm).
 - [ISO/EIC 9660:1999](http://pismotec.com/cfs/iso9660-1999.html).  The extension to the original ISO9660 standard done in 1999.
-- [El Torito](http://wiki.osdev.org/El-Torito).  The standard for making ISO9660 compatible discs bootable.
+- [El Torito](http://wiki.osdev.org/El-Torito).  The standard for making ISO9660 compatible disks bootable.
 - [Joliet](https://en.wikipedia.org/wiki/Joliet_(file_system)) Specification.  The Microsoft extension to ISO9660 to allow deeper directories, longer filenames, etc.  The complete specification is [here](http://pismotec.com/cfs/jolspec.html).
 - [System Use Sharing Protocol (SUSP)](https://en.wikipedia.org/wiki/Rock_Ridge), Versions 1.09, 1.10, and 1.12.  The standard for extending the amount of metadata each ISO9660 filename or directory can have (necessary for Rock Ridge, below).
 - [Rock Ridge Interchange Protocol (RRIP)](https://en.wikipedia.org/wiki/Rock_Ridge), Version 1.09, 1.10, and 1.12.  The standard for adding Unix-like metadata and semantics to ISO9660 filenames and directories.
@@ -16,7 +16,7 @@ Unfortunately, accessing most of these standards requires a license, so the link
 While PyCdlib aims to be compliant with these standards, there are a number of complicating factors.  One such factor is that there are places in the standards that are ambiguous, and different implementations have taken different approaches to solving the same problem.  Another complicating factor is the fact that there are several "standard" parts of ISOs that have no relevant standard backing them up; they are just generally agreed to by the various implementations.  PyCdlib takes a middle road here, and tries to be pretty forgiving with the type of ISOs that it can open, but fairly strict with what it can produce.  When there are ambiguities in the standards, PyCdlib generally takes the approach of being compliant with whatever [cdrkit](https://launchpad.net/cdrkit) does.  However, there are several bugs in the cdrkit implementation, so in those cases, PyCdlib falls back to being standards compliant.
 
 ## Interchange levels
-The original ISO9660 standard defines "interchange" levels 1, 2, and 3.  The differences between the three interchange levels is mostly irrelevant now, as most modern ISOs use interchange level 3 (and supplement it with one of the extensions).  A newer version of the ISO9660 standard was put out in 1999 that lifts some of the restrictions of the original ISO9660 standard.  PyCdlib follows the lead of genisoimage here and defines this as interchange level 4, although that is not an "official" designation.  For almost all use cases, interchange level 3 should be used with the [Rock Ridge](#rock-ridge) and [Joliet](#joliet) extensions.
+The original ISO9660 standard defines "interchange" levels 1, 2, and 3.  The differences between the three interchange levels is practically irrelevant now, as most modern ISOs use interchange level 3 (and supplement it with one of the extensions).  A newer version of the ISO9660 standard was put out in 1999 that lifts some of the restrictions of the original ISO9660 standard.  PyCdlib follows the lead of genisoimage here and defines this as interchange level 4, although that is not an "official" designation.  For almost all use cases, interchange level 3 should be used with the [Rock Ridge](#rock-ridge) and [Joliet](#joliet) extensions.
 
 ## Rock Ridge and Joliet
 The two most common extensions to the original ISO9660 standard are Rock Ridge and Joliet, both of which allow ISOs to contain deeper directory structures, longer filenames, and other features usually used by modern filesystems.  While both standards aim to accomplish the same goal, they do it in entirely different ways, and some of those details leak through into the PyCdlib API.  Thus, a brief discussion of each of them is in order.

docs/tools.md

@@ -1,5 +1,4 @@
 # Tools
-
 PyCdlib comes with several tools built on the main library API.  These tools are useful in themselves, but also give (relatively) simple examples on how to use the PyCdlib API in a real application.
 
 ## pycdlib-genisoimage