Tweaks in the documentation.

git-svn-id: http://svn.robofab.com/branches/ufo3k@553 b5fa9d6c-a76f-4ffd-b3cb-f825fc41095c

Lib/robofab/pens/angledMarginPen.py

@@ -15,19 +15,16 @@ __all__ = ["AngledMarginPen", "getAngledMargins",
 
 class AngledMarginPen(BasePen):
 	"""
-		Angled Margin Pen
+		Pen to calculate the margins according to a slanted coordinate system. Slant angle comes from font.info.italicAngle.
 
-		Pen to calculate the margins as if the margin lines were slanted
-		according to the font.info.italicAngle.
-
-		Notes:
 			- this pen works on the on-curve points, and approximates the distance to curves.
 			- results will be float.
-		- when used in FontLab, the resulting margins may be slightly
-			different from the values originally set, due to rounding errors.
+			- when used in FontLab, the resulting margins may be slightly different from the values originally set, due to rounding errors.
+
+			Notes:
+
 			- similar to what RoboFog used to do.
-		- RoboFog had a special attribute for "italicoffset", horizontal
-		shift of all glyphs. This is missing in Robofab.
+			- RoboFog had a special attribute for "italicoffset", horizontal shift of all glyphs. This is missing in Robofab.
 	"""
 	def __init__(self, glyphSet, width, italicAngle):
 		BasePen.__init__(self, glyphSet)
@@ -81,27 +78,27 @@ class AngledMarginPen(BasePen):
 		self.currentPt = pt3
 
 def getAngledMargins(glyph, font):
-	"""Get the angled margins for this glyph."""
+	"""Convenience function, returns the angled margins for this glyph. Adjusted for font.info.italicAngle."""
 	pen = AngledMarginPen(font, glyph.width, font.info.italicAngle)
 	glyph.draw(pen)
 	return pen.margin
 	
 def setAngledLeftMargin(glyph, font, value):
-	"""Set the left angled margin to value, adjusted for font.info.italicAngle."""
+	"""Convenience function, sets the left angled margin to value. Adjusted for font.info.italicAngle."""
 	pen = AngledMarginPen(font, glyph.width, font.info.italicAngle)
 	g.draw(pen)
 	isLeft, isRight = pen.margin
 	glyph.leftMargin += value-isLeft
 	
 def setAngledRightMargin(glyph, font, value):
-	"""Set the right angled margin to value, adjusted for font.info.italicAngle."""
+	"""Convenience function, sets the right angled margin to value. Adjusted for font.info.italicAngle."""
 	pen = AngledMarginPen(font, glyph.width, font.info.italicAngle)
 	g.draw(pen)
 	isLeft, isRight = pen.margin
 	glyph.rightMargin += value-isRight
 
 def centerAngledMargins(glyph, font):
-	"""Center the glyph on angled margins."""
+	"""Convenience function, centers the glyph on angled margins."""
 	pen = AngledMarginPen(font, glyph.width, font.info.italicAngle)
 	g.draw(pen)
 	isLeft, isRight = pen.margin

Lib/robofab/pens/marginPen.py

@@ -7,15 +7,31 @@ from sets import Set
 class MarginPen(BasePen):
 
 	"""
-		Pen to calculate the margins at a given value.
-			When isHorizontal is True, the margins at <value> are horizontal.
-			When isHorizontal is False, the margins at <value> are vertical.
+		Pen to calculate the margins at a given height or width.
 
-		When a glyphset or font is given, MarginPen will also calculate for glyphs with components.
+			- isHorizontal = True: slice the glyph at y=value.
+			- isHorizontal = False: slice the glyph at x=value.
 		
-		pen.getMargins() returns the minimum and maximum intersections of the glyph.
-		pen.getContourMargins() returns the minimum and maximum intersections for each contour.
+		>>> f = CurrentFont()
+		>>> g = CurrentGlyph()
+		>>> pen = MarginPen(f, 200, isHorizontal=True)
+		>>> g.draw(pen)
+		>>> print pen.getMargins()
+		(75.7881, 181.9713)
 
+		>>> pen = MarginPen(f, 200, isHorizontal=False)
+		>>> g.draw(pen)
+		>>> print pen.getMargins()
+		(26.385, 397.4469)
+		>>> print pen.getAll()
+		[75.7881, 181.9713]
+
+		>>> pen = MarginPen(f, 200, isHorizontal=False)
+		>>> g.draw(pen)
+		>>> print pen.getMargins()
+		(26.385, 397.4469)
+		>>> print pen.getAll()
+		[26.385, 171.6137, 268.0, 397.4469]
 				
 		Possible optimisation:
 		Initialise the pen object with a list of points we want to measure,
@@ -109,7 +125,7 @@ class MarginPen(BasePen):
 			glyph.draw(self)
 		
 	def getMargins(self):
-		"""Get the horizontal margins for all contours combined, i.e. the whole glyph."""
+		"""Return the extremes of the slice for all contours combined, i.e. the whole glyph."""
 		allHits = []
 		for index, pts in self.hits.items():
 			allHits.extend(pts)
@@ -118,7 +134,7 @@ class MarginPen(BasePen):
 		return None
 		
 	def getContourMargins(self):
-		"""Get the horizontal margins for each contour."""
+		"""Return the extremes of the slice for each contour."""
 		allHits = {}
 		for index, pts in self.hits.items():
 			unique = list(Set(pts))
@@ -127,7 +143,7 @@ class MarginPen(BasePen):
 		return allHits
 		
 	def getAll(self):
-		"""Get all the slices."""
+		"""Return all the slices."""
 		allHits = []
 		for index, pts in self.hits.items():
 			allHits.extend(pts)

Lib/robofab/pens/mathPens.py

@@ -92,7 +92,7 @@ class GetMathDataPointPen(AbstractPointPen):
 class CurveSegmentFilterPointPen(AbstractPointPen):
 	
 	"""
-	Point pen that turns curve segments that contain
+	Filtering Point pen that turns curve segments that contain
 	unnecessary anchor points into line segments.
 	"""
 	# XXX it would be great if this also checked to see if the