Improves documentation for tools (haddocking#45)

* Reformatted docstrings for consistency.

* Added full listing of tools to the manual page.

pdbtools/pdb_chainxseg.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Replaces the segment identifier column by the value in the chain identifier
-column of the PDB file.
+Swaps the segment identifier for the chain identifier.
 
 Usage:
     python pdb_chainxseg.py <pdb file>

pdbtools/pdb_chkensemble.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Performs a basic check on a multi-model PDB file (ensemble) to ensure all models
-have exactly the same atoms (as they should).
+Checks all models in a multi-model PDB file have the same composition.
+
+Composition is defined as same atoms/residues/chains.
 
 Usage:
     python pdb_chkensemble.py <pdb file>

pdbtools/pdb_delelem.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Deletes all atoms matching the given element in the PDB file. Elements are
-read from the element column.
+Deletes all atoms matching the given element in the PDB file. 
+
+Elements are read from the element column.
 
 Usage:
     python pdb_delelem.py -<option> <pdb file>

pdbtools/pdb_delinsertion.py

@@ -16,17 +16,18 @@
 # limitations under the License.
 
 """
-Deletes insertion codes in a PDB file, shifting the residue numbering of
-downstream residues. Allows for picking specific residues to delete insertion
-codes for.
+Deletes insertion codes in a PDB file.
+
+Deleting an insertion code shifts the residue numbering of downstream
+residues. Allows for picking specific residues to delete insertion codes for.
 
 Usage:
     python pdb_delinsertion.py [-<option>] <pdb file>
 
 Example:
-    python pdb_delinsertion.py 1CTF.pdb  # delete ALL insertion codes EVERYWHERE
-    python pdb_delinsertion.py -A99,B12 1CTF.pdb  # deletes ins. codes for residue
-                                              # 99 of chain A and 12 of chain B.
+    python pdb_delinsertion.py 1CTF.pdb  # delete ALL insertion codes
+    python pdb_delinsertion.py -A9,B12 1CTF.pdb  # deletes ins. codes for res
+                                                 # 9 of chain A and 12 of chain B.
 
 This program is part of the `pdb-tools` suite of utilities and should not be
 distributed isolatedly. The `pdb-tools` were created to quickly manipulate PDB

pdbtools/pdb_delres.py

@@ -16,12 +16,14 @@
 # limitations under the License.
 
 """
-Deletes a range of residues from a PDB file. The range option has three
-components: start, end, and step. Start and end are optional and if ommitted the
-range will start at the first residue or end at the last, respectively. The step
-option can only be used if both start and end are provided. Note that the start
-and end values of the range are purely numerical, while the range actually
-refers to every N-th residue, regardless of their sequence number.
+Deletes a range of residues from a PDB file. 
+
+The range option has three components: start, end, and step. Start and end
+are optional and if ommitted the range will start at the first residue or
+end at the last, respectively. The step option can only be used if both start
+and end are provided. Note that the start and end values of the range are
+purely numerical, while the range actually refers to every N-th residue,
+regardless of their sequence number.
 
 Usage:
     python pdb_delres.py -[resid]:[resid]:[step] <pdb file>

pdbtools/pdb_delresname.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Removes all residues matching the given name in the PDB file. Residues names are
-matched *without* taking into consideration spaces.
+Removes all residues matching the given name in the PDB file. 
+
+Residues names are matched *without* taking into consideration spaces.
 
 Usage:
     python pdb_delresname.py -<option> <pdb file>

pdbtools/pdb_element.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Assigns the element column to the PDB file, guessing the element from the atom
-names.
+Assigns the elements in the PDB file from atom names.
 
 Usage:
     python pdb_element.py <pdb file>

pdbtools/pdb_fetch.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Downloads a structure in PDB format from the RCSB website. Allows downloading
-the (first) biological structure if selected.
+Downloads a structure in PDB format from the RCSB website. 
+
+Allows downloading the (first) biological structure if selected.
 
 Usage:
     python pdb_fetch.py [-biounit] <pdb code>

pdbtools/pdb_fromcif.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Converts a mmCIF file to the PDB format. Will not convert if the file does not
-'fit' in PDB format, e.g. too many chains, residues, or atoms. Will convert
-only the coordinate section.
+Rudimentarily converts a mmCIF file to the PDB format. 
+
+Will not convert if the file does not 'fit' in PDB format, e.g. too many
+chains, residues, or atoms. Will convert only the coordinate section.
 
 Usage:
     python pdb_fromcif.py <pdb file>

pdbtools/pdb_gap.py

@@ -16,8 +16,10 @@
 # limitations under the License.
 
 """
-Detects gaps between consecutive residues in the sequence, both by a distance
-criterion or discontinuous residue numbering. Only applies for protein residues.
+Finds gaps between consecutive protein residues in the PDB.
+
+Detects gaps both by a distance criterion or discontinuous residue numbering.
+Only applies to protein residues.
 
 Usage:
     python pdb_gap.py <pdb file>

pdbtools/pdb_keepcoord.py

@@ -17,6 +17,7 @@
 
 """
 Removes all non-coordinate records from the file.
+
 Keeps only MODEL, ENDMDL, END, ATOM, HETATM, and CONECT.
 
 Usage:

pdbtools/pdb_merge.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Merges several PDB files into one. The contents are not sorted and no lines are
-deleted (e.g. END, TER statements) so we recommend piping the results through
-`pdb_tidy.py`.
+Merges several PDB files into one. 
+
+The contents are not sorted and no lines are deleted (e.g. END, TER
+statements) so we recommend piping the results through `pdb_tidy.py`.
 
 Usage:
     python pdb_merge.py <pdb file> <pdb file>

pdbtools/pdb_mkensemble.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Merges several PDB files into one multi-model (ensemble) file. Strips all
-HEADER information and adds REMARK statements with the provenance of each
-conformer.
+Merges several PDB files into one multi-model (ensemble) file.
+
+Strips all HEADER information and adds REMARK statements with the provenance
+of each conformer.
 
 Usage:
     python pdb_mkensemble.py <pdb file> <pdb file>

pdbtools/pdb_reatom.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Renumbers atom serial numbers of the PDB file starting from a given value
-(default 1).
+Renumbers atom serials in the PDB file starting from a given value (default 1).
 
 Usage:
     python pdb_reatom.py -<number> <pdb file>

pdbtools/pdb_rplresname.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Performs in-place replacement of a residue name by another. Affects all residues
-with that name.
+Performs in-place replacement of a residue name by another.
+
+Affects all residues with that name.
 
 Usage:
     python pdb_rplresname.py -<from>:<to> <pdb file>

pdbtools/pdb_segxchain.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Replaces the chain identifier column by the value in the segment identifier
-column of the PDB file. Truncates the segment identifier if longer than one
-character.
+Swaps the chain identifier by the segment identifier.
+
+If the segment identifier is longer than one character, the script will
+truncate it. Does not ensure unique chain IDs.
 
 Usage:
     python pdb_segxchain.py <pdb file>

pdbtools/pdb_selaltloc.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Picks one location for each atom with fractional occupancy values. By default,
-picks the atom with the highest occupancy value. User can define one specific
-location using an option.
+Selects altloc labels for the entire PDB file.
+
+By default, picks the label with the highest occupancy value for each atom, 
+but the user can define a specific label. Removes all labels afterwards.
 
 Usage:
     python pdb_selaltloc.py [-<option>] <pdb file>

pdbtools/pdb_selatom.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Selects all atoms matching the given name in the PDB file. Atom names are matched
-*without* taking into consideration spaces, so ' CA ' (alpha carbon) and 'CA  '
-(calcium) will both be kept if -CA is passed.
+Selects all atoms matching the given name in the PDB file.
+
+Atom names are matched *without* taking into consideration spaces, so ' CA '
+(alpha carbon) and 'CA  ' (calcium) will both be kept if -CA is passed.
 
 Usage:
     python pdb_selatom.py -<option> <pdb file>

pdbtools/pdb_selelem.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Selects all atoms that match the given element(s) in the PDB file. Elements are
-read from the element column.
+Selects all atoms that match the given element(s) in the PDB file.
+
+Elements are read from the element column.
 
 Usage:
     python pdb_selelem.py -<option> <pdb file>

pdbtools/pdb_selres.py

@@ -16,10 +16,11 @@
 # limitations under the License.
 
 """
-Extracts residues from a PDB file, either arbitrarily or in a range. The range
-option has three components: start, end, and step. Start and end are optional
-and if ommitted the range will start at the first residue or end at the last,
-respectively.
+Selects residues by their index, piecewise or in a range. 
+
+The range option has three components: start, end, and step. Start and end
+are optional and if ommitted the range will start at the first residue or
+end at the last, respectively.
 
 Usage:
     python pdb_selres.py -[resid]:[resid]:[step] <pdb file>

pdbtools/pdb_selresname.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Selects all residues matching the given name in the PDB file. Residues names are
-matched *without* taking into consideration spaces.
+Selects all residues matching the given name in the PDB file.
+
+Residues names are matched *without* taking into consideration spaces.
 
 Usage:
     python pdb_selresname.py -<option> <pdb file>

pdbtools/pdb_selseg.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Extracts one or more segments from a PDB file based on their segment
-identifiers.
+Selects all atoms matching the given segment identifier.
 
 Usage:
     python pdb_selseg.py -<segment id> <pdb file>

pdbtools/pdb_shiftres.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Renumbers the residues of the PDB file by adding/subtracting a given number
-from the original numbering.
+Shifts the residue numbers in the PDB file by a constant value.
 
 Usage:
     python pdb_shiftres.py -<number> <pdb file>

pdbtools/pdb_tidy.py

@@ -17,6 +17,7 @@
 
 """
 Modifies the file to adhere (as much as possible) to the format specifications.
+
 Expects a sorted file - REMARK/ATOM/HETATM/END - so use pdb_sort in case you are
 not sure.
 

pdbtools/pdb_tocif.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Converts a PDB file to the mmCIF format. Will convert only the coordinate
-section.
+Rudimentarily converts the PDB file to mmCIF format. 
+
+Will convert only the coordinate section.
 
 Usage:
     python pdb_tocif.py <pdb file>

pdbtools/pdb_tofasta.py

@@ -16,9 +16,10 @@
 # limitations under the License.
 
 """
-Extracts the residue sequence in a PDB file to FASTA format. Canonical amino
-acids and nucleotides are represented by their one-letter code while all others
-are represented by 'X'.
+Extracts the residue sequence in a PDB file to FASTA format. 
+
+Canonical amino acids and nucleotides are represented by their
+one-letter code while all others are represented by 'X'.
 
 The -multi option splits the different chains into different records in the
 FASTA file.

pdbtools/pdb_validate.py

@@ -17,6 +17,7 @@
 
 """
 Validates the PDB file ATOM/HETATM lines according to the format specifications.
+
 Does not catch all the errors though... people are creative!
 
 Usage: