Permit control over chapter layout.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@11147 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,9 @@
+2001-10-15  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Tools/AGSOutput.m: Added new 'unit' pseudo-markup to permit
+	control over chapter layout for a chapter containing class,
+	category, or protocol documentation.
+
 2001-10-14  Fred Kiefer <FredKiefer@gmx.de>
 
 	* Source/Unicode.m: 

Tools/AGSOutput.h

@@ -40,9 +40,9 @@
 - (BOOL) output: (NSDictionary*)d file: (NSString*)name;
 - (void) outputMethod: (NSDictionary*)d to: (NSMutableString*)str;
 - (void) outputUnit: (NSDictionary*)d to: (NSMutableString*)str;
-- (void) reformat: (NSString*)str
-       withIndent: (unsigned)ind
-	       to: (NSMutableString*)buf;
+- (unsigned) reformat: (NSString*)str
+	   withIndent: (unsigned)ind
+		   to: (NSMutableString*)buf;
 - (NSArray*) split: (NSString*)str;
 @end
 

Tools/AGSOutput.m

@@ -32,7 +32,7 @@ static BOOL snuggleEnd(NSString *t)
     }
   if (set == nil)
     {
-      set = [NSCharacterSet characterSetWithCharactersInString: @"]}).,;?!"];
+      set = [NSCharacterSet characterSetWithCharactersInString: @"]}).,;"];
       RETAIN(set);
     }
   return [set characterIsMember: [t characterAtIndex: 0]];
@@ -50,7 +50,16 @@ static BOOL snuggleStart(NSString *t)
   return [set characterIsMember: [t characterAtIndex: [t length] - 1]];
 }
 
-
+/**
+ * <unit>
+ *  <heading>The AGSOutput class</heading>
+ *  <p>This is a really great class ... but it's not really reusable since it's
+ *  far too special purpose.</p>
+ *  <unit />
+ *  <p>Here is the afterword for the class.</p>
+ * </unit>
+ * And finally, here is the actual class description ... outside the chapter.
+ */
 @implementation	AGSOutput
 
 - (void) dealloc
@@ -536,21 +545,96 @@ static BOOL snuggleStart(NSString *t)
   NSString	*name = [d objectForKey: @"Name"];
   NSString	*type = [d objectForKey: @"Type"];
   NSDictionary	*methods = [d objectForKey: @"Methods"];
+  NSString	*comment = [d objectForKey: @"Comment"];
   NSArray	*names;
   NSArray	*protocols;
   NSString	*tmp;
+  NSString	*unit;
+  NSRange	r;
+  unsigned	ind;
   unsigned	i;
+  unsigned	j;
 
-  [str appendString: @"    <chapter>\n"];
+  /*
+   * Make sure we have a 'unit' part and a class 'desc' part (comment)
+   * to be output.
+   */
+  r = [comment rangeOfString: @"<unit>"];
+  if (comment != nil && r.length > 0)
+    {
+      unsigned	pos = r.location;
 
-  [str appendString: @"      <heading>"];
-  [str appendString: @"Software documentation for the "];
-  [str appendString: name];
-  [str appendString: @" "];
-  [str appendString: type];
-  [str appendString: @"</heading>\n"];
+      r = [comment rangeOfString: @"</unit>"];
+      if (r.length == 0 || r.location < pos)
+	{
+	  NSLog(@"Unterminated <unit> in comment for %@", name);
+	  return;
+	}
+      
+      if (pos == 0)
+	{
+	  if (NSMaxRange(r) == [comment length])
+	    {
+	      unit = comment;
+	      comment = nil;
+	    }
+	  else
+	    {
+	      unit = [comment substringToIndex: NSMaxRange(r)];
+	      comment = [comment substringFromIndex: NSMaxRange(r)];
+	    }
+	}
+      else
+	{
+	  if (NSMaxRange(r) == [comment length])
+	    {
+	      unit = [comment substringFromIndex: pos];
+	      comment = [comment substringToIndex: pos];
+	    }
+	  else
+	    {
+	      unsigned	end = NSMaxRange(r);
 
-  [str appendString: @"      <"];
+	      r = NSMakeRange(pos, end-pos);
+	      unit = [comment substringWithRange: r];
+	      comment = [[comment substringToIndex: pos]
+		stringByAppendingString: [comment substringFromIndex: end]];
+	    }
+	}
+      unit = [unit stringByReplacingString: @"unit>" withString: @"chapter>"];
+    }
+  else
+    {
+      unit = [NSString stringWithFormat:
+        @"    <chapter>\n      <heading>Software documentation "
+	@"for the %@ %@</heading>\n    </chapter>\n", name, type];
+    }
+
+  /*
+   * Get the range of the location in the chapter where the class
+   * details should get substituted in.  If there is nowhere marked,
+   * create a zero length range just before the end of the chapter.
+   */
+  r = [unit rangeOfString: @"<unit />"];
+  if (r.length == 0)
+    {
+      r = [unit rangeOfString: @"<unit/>"];
+    }
+  if (r.length == 0)
+    {
+      r = [unit rangeOfString: @"</chapter>"];
+      r.length = 0;
+    }
+
+  /*
+   * Output first part of chapter and note indentation.
+   */
+  ind = [self reformat: [unit substringToIndex: r.location]
+	    withIndent: 4
+		    to: str];
+
+  for (j = 0; j < ind; j++) [str appendString: @" "];
+  [str appendString: @"<"];
   [str appendString: type];
   [str appendString: @" name=\""];
   if ([type isEqual: @"category"] == YES)
@@ -576,7 +660,9 @@ static BOOL snuggleStart(NSString *t)
     }
   [str appendString: @"\">\n"];
 
-  [str appendString: @"        <declared>"];
+  ind += 2;
+  for (j = 0; j < ind; j++) [str appendString: @" "];
+  [str appendString: @"<declared>"];
   [str appendString: [d objectForKey: @"Declared"]];
   [str appendString: @"</declared>\n"];
 
@@ -585,19 +671,21 @@ static BOOL snuggleStart(NSString *t)
     {
       for (i = 0; i < [protocols count]; i++)
 	{
-	  [str appendString: @"        <conform>"];
+	  for (j = 0; j < ind; j++) [str appendString: @" "];
+	  [str appendString: @"<conform>"];
 	  [str appendString: [protocols objectAtIndex: i]];
 	  [str appendString: @"</conform>\n"];
 	}
     }
 
-  [str appendString: @"        <desc>\n"];
-  tmp = [d objectForKey: @"Comment"];
-  if (tmp != nil)
+  for (j = 0; j < ind; j++) [str appendString: @" "];
+  [str appendString: @"<desc>\n"];
+  if (comment != nil)
     {
-      [self reformat: tmp withIndent: 10 to: str];
+      [self reformat: comment withIndent: ind + 2 to: str];
     }
-  [str appendString: @"        </desc>\n"];
+  for (j = 0; j < ind; j++) [str appendString: @" "];
+  [str appendString: @"</desc>\n"];
   
   names = [[methods allKeys] sortedArrayUsingSelector: @selector(compare:)];
   for (i = 0; i < [names count]; i++)
@@ -607,15 +695,23 @@ static BOOL snuggleStart(NSString *t)
       [self outputMethod: [methods objectForKey: mName] to: str];
     }
 
-  [str appendString: @"      </"];
+  ind -= 2;
+  for (j = 0; j < ind; j++) [str appendString: @" "];
+  [str appendString: @"</"];
   [str appendString: type];
   [str appendString: @">\n"];
-  [str appendString: @"    </chapter>\n"];
+
+  /*
+   * Output tail end of chapter.
+   */
+  [self reformat: [unit substringFromIndex: NSMaxRange(r)]
+      withIndent: ind
+	      to: str];
 }
 
-- (void) reformat: (NSString*)str
-       withIndent: (unsigned)ind
-	       to: (NSMutableString*)buf
+- (unsigned) reformat: (NSString*)str
+	   withIndent: (unsigned)ind
+		   to: (NSMutableString*)buf
 {
   CREATE_AUTORELEASE_POOL(arp);
   unsigned	l = [str length];
@@ -652,7 +748,7 @@ static BOOL snuggleStart(NSString *t)
       if (r.length == 0)
 	{
 	  NSLog(@"unterminated <example>");
-	  return;
+	  return ind;
 	}
       tmp = [str substringWithRange: NSMakeRange(i, NSMaxRange(r) - i)];
       [buf appendString: tmp];
@@ -737,6 +833,7 @@ static BOOL snuggleStart(NSString *t)
 	}
     }
   RELEASE(arp);
+  return ind;
 }
 
 - (NSArray*) split: (NSString*)str

Tools/autogsdoc.m

@@ -68,7 +68,7 @@
     <item><strong>&lt;chapter&gt;</strong>
       Placed immediately before any generated class documentation ...
       intended to be used to provide overall description of how the
-      code bing documented works.
+      code being documented works.<br />
     </item>
     <item><strong>&lt;copy&gt;</strong>
       Copyright of the content of the document ... placed in the head
@@ -88,6 +88,16 @@
       If this is omitted the tool will generate a (probably poor)
       title of its own.
     </item>
+    <item>
+      <strong>NB</strong>This markup may be used within
+      class, category, or protocol documentation ... if so, it is
+      extracted and wrapped round the rest of the documentation for
+      the class as the classes chapter.
+      The rest of the class documentation is normally
+      inserted at the end of the chapter, but may instead be sbstituted
+      in in place of the &lt;unit /&gt; pseudo-element within the
+      &lt;chapter&gt; element.
+    </item>
     <item><strong>&lt;version&gt;</strong>
       Version identifier of the document ... placed in the head
       of the gsdoc output.  If this is omitted the tool will try to