+ Added unix man page output; Implemented usage

utils/fpdoc/Makefile.fpc

@@ -26,7 +26,7 @@ fpcpackage=y
 fpcdir=../..
 
 [clean]
-units=dglobals dwriter dw_xml sh_pas dw_html dw_latex dw_ipf dw_txt
+units=dglobals dwriter dw_xml sh_pas dw_html dw_latex dw_ipf dw_txt dw_man
 files=dwriter.rst fpdoc.rst dglobals.rst makeskel.rst
 
 [rules]

utils/fpdoc/dglobals.pp

@@ -26,59 +26,62 @@ interface
 
 uses Classes, DOM, PasTree, PParser;
 
+Var
+  LEOL : Integer;
+
 resourcestring
   // Output strings
-  SDocPackageTitle = 'Reference for package ''%s''';
+  SDocPackageTitle           = 'Reference for package ''%s''';
-  SDocPrograms = 'Programs';
+  SDocPrograms               = 'Programs';
-  SDocUnits = 'Units';
+  SDocUnits                  = 'Units';
-  SDocUnitTitle = 'Reference for unit ''%s''';
+  SDocUnitTitle              = 'Reference for unit ''%s''';
-  SDocInterfaceSection = 'Interface section';
+  SDocInterfaceSection       = 'Interface section';
-  SDocImplementationSection = 'Implementation section';
+  SDocImplementationSection  = 'Implementation section';
-  SDocUsedUnits = 'Used units';
+  SDocUsedUnits              = 'Used units';
-  SDocUsedUnitsByUnitXY = 'Used units by unit ''%s''';
+  SDocUsedUnitsByUnitXY      = 'Used units by unit ''%s''';
-  SDocConstsTypesVars = 'Constants, types and variables';
+  SDocConstsTypesVars        = 'Constants, types and variables';
-  SDocResStrings = 'Resource strings';
+  SDocResStrings             = 'Resource strings';
-  SDocTypes = 'Types';
+  SDocTypes                  = 'Types';
-  SDocConstants = 'Constants';
+  SDocConstants              = 'Constants';
-  SDocClasses = 'Classes';
+  SDocClasses                = 'Classes';
   SDocProceduresAndFunctions = 'Procedures and functions';
-  SDocVariables = 'Variables';
+  SDocVariables              = 'Variables';
+
+  SDocUnitOverview           = 'Overview of unit ''%s''';
+  SDocOverview               = 'Overview';
+  SDocSearch                 = 'Search';
+  SDocDeclaration            = 'Declaration';
+  SDocDescription            = 'Description';
+  SDocErrors                 = 'Errors';
+  SDocSeeAlso                = 'See also';
+  SDocExample                = 'Example';
+  SDocArguments              = 'Arguments';
+  SDocFunctionResult         = 'Function result';
+  SDocRemark                 = 'Remark:   ';
+  SDocMethodOverview         = 'Method overview';
+  SDocPropertyOverview       = 'Property overview';
+  SDocPage                   = 'Page';
+  SDocMethod                 = 'Method';
+  SDocProperty               = 'Property';
+  SDocAccess                 = 'Access';
+  SDocInheritance            = 'Inheritance';
+  SDocProperties             = 'Properties';
+  SDocMethods                = 'Methods';
+  SDocEvents                 = 'Events';
+  SDocByName                 = 'by Name';
+  SDocValue                  = 'Value';
+  SDocExplanation            = 'Explanation';
+  SDocProcedure              = 'Procedure';
+  SDocValuesForEnum          = 'Enumeration values for type %s';
+  SDocSourcePosition         = 'Source position: %s line %d';
+  SDocSynopsis               = 'Synopsis';
+  SDocVisibility             = 'Visibility';
 
-  SDocUnitOverview = 'Overview of unit ''%s''';
-  SDocOverview = 'Overview';
-  SDocSearch = 'Search';
-  SDocDeclaration = 'Declaration';
-  SDocDescription = 'Description';
-  SDocErrors = 'Errors';
-  SDocSeeAlso = 'See also';
-  SDocExample = 'Example';
-  SDocArguments = 'Arguments';
-  SDocFunctionResult = 'Function result';
-  SDocRemark = 'Remark:   ';
-  SDocMethodOverview = 'Method overview';
-  SDocPropertyOverview = 'Property overview';
-  SDocPage = 'Page';
-  SDocMethod = 'Method';
-  SDocProperty = 'Property';
-  SDocAccess = 'Access';
-  SDocInheritance = 'Inheritance';
-  SDocProperties = 'Properties';
-  SDocMethods = 'Methods';
-  SDocEvents = 'Events';
-  SDocByName = 'by Name';
-  SDocValue = 'Value';
-  SDocExplanation = 'Explanation';
-  SDocProcedure = 'Procedure';
-  SDocValuesForEnum = 'Enumeration values for type %s';
-  SDocSourcePosition = 'Source position: %s line %d';
-  SDocSynopsis = 'Synopsis';
-  SDocVisibility = 'Visibility';
-  
   // Topics
   SDocRelatedTopics = 'Related topics';
-  SDocUp = 'Up';
+  SDocUp            = 'Up';
-  SDocNext = 'Next';
+  SDocNext          = 'Next';
-  SDocPrevious = 'Previous';
+  SDocPrevious      = 'Previous';
 
   // Various backend constants
   SDocChapter    = 'Chapter';
@@ -87,16 +90,45 @@ resourcestring
   SDocTable      = 'Table';
   SDocListing    = 'Listing';
 
-  STitle = 'FPDoc - Free Pascal Documentation Tool';
+  // Man page usage
-  SCopyright = '(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org';
+  SManUsageManSection         = 'Use ASection as the man page section';
-  SCmdLineHelp = 'See documentation for usage.';
+  SManUsageNoUnitPrefix       = 'Do not prefix man pages with unit name.';
-  SCmdLineInvalidOption = 'Ignoring unknown option "%s"';
+  SManUsageWriterDescr        = 'UNIX man page output.';
-  SCmdLineInvalidFormat = 'Invalid format "%s" specified';
+  SManUsagePackageDescription = 'Use descr as the description of man pages';
-  SCmdLineOutputOptionMissing = 'Need an output filename, please specify one with --output=<filename>';
-  SWritingPages = 'Writing %d pages...';
-  SNeedPackageName = 'No package name specified. Please specify one using the --package option.';
-  SDone = 'Done.';
 
+  STitle                      = 'FPDoc - Free Pascal Documentation Tool';
+  SCopyright                  = '(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org';
+
+  SCmdLineHelp     = 'Usage: %s [options]';
+  SUsageOption010  = '--content         Create content file for package cross-references';
+  SUsageOption020  = '--cputarget=value Set the target CPU for the scanner.';
+  SUsageOption030  = '--descr=name      use name as description file. ';
+  SUsageOption040  = '                  This option is allowed more than once';
+  SUsageOption050  = '--format=fmt      Select output format.';
+  SUsageOption060  = '--help            Show this help.';
+  SUsageOption070  = '--hide-protected  Do not show protected methods in overview';
+  SUsageOption080  = '--import=file     Import content file for package cross-references';
+  SUsageOption090  = '--input=cmd       use cmd as input for the parser.';
+  SUsageOption100  = '                  At least one input option is required.';
+  SUsageOption110  = '--lang=lng        Select output language.';
+  SUsageOption120  = '--ostarget=value  Set the target OS for the scanner.';
+  SUsageOption130  = '--output=name     use name as the output name.';
+  SUsageOption140  = '                  Each backend interpretes this as needed.';
+  SUsageOption150  = '--package=name    Set the package name for which to create output';
+  SUsageOption160  = '--show-private    Show private methods.';
+  SUsageOption170  = '--warn-no-node    Warn if no documentation node was found.';
+  SUsageFormats        = 'The following output formats are supported by this fpdoc:';
+  SUsageBackendHelp    = 'Specify an output format, combined with --help to get more help for this backend.';
+  SUsageFormatSpecific = 'Output format "%s" supports the following options:';
+
+  SCmdLineInvalidOption       = 'Ignoring unknown option "%s"';
+  SCmdLineInvalidFormat       = 'Invalid format "%s" specified';
+  SCmdLineOutputOptionMissing = 'Need an output filename, please specify one with --output=<filename>';
+  SWritingPages               = 'Writing %d pages...';
+  SNeedPackageName            = 'No package name specified. Please specify one using the --package option.';
+  SDone                       = 'Done.';
+  SErrCouldNotCreateOutputDir = 'Could not create output directory "%s"';
+  
 Const
   SVisibility: array[TPasMemberVisibility] of string =
        ('Default', 'Private', 'Protected', 'Public',
@@ -240,6 +272,9 @@ type
 
 procedure TranslateDocStrings(const Lang: String);
 
+Function IsLinkNode(Node : TDomNode) : Boolean;
+Function IsExampleNode(Example : TDomNode) : Boolean;
+
 
 
 implementation
@@ -1162,14 +1197,29 @@ begin
   end;
 end;
 
+Function IsLinkNode(Node : TDomNode) : Boolean;
 
+begin
+  Result:=Assigned(Node) and (Node.NodeType = ELEMENT_NODE) and (Node.NodeName = 'link');
+end;
 
+Function IsExampleNode(Example : TDomNode) : Boolean;
+
+begin
+  Result:=Assigned(Example) and (Example.NodeType = ELEMENT_NODE) and (Example.NodeName = 'example')
+end;
+
+initialization
+  LEOL:=Length(LineEnding);
 end.
 
 
 {
   $Log$
-  Revision 1.7  2005-01-12 21:11:41  michael
+  Revision 1.8  2005-01-14 17:55:07  michael
+  + Added unix man page output; Implemented usage
+
+  Revision 1.7  2005/01/12 21:11:41  michael
   + New structure for writers. Implemented TXT writer
 
   Revision 1.6  2005/01/09 15:59:50  michael

utils/fpdoc/dw_ipf.pp

@@ -116,8 +116,6 @@ type
     procedure DescrEndTableRow; override;
     procedure DescrBeginTableCell; override;
     procedure DescrEndTableCell; override;
-    procedure WriteDescr(Element: TPasElement);
-    procedure WriteDescr(AContext: TPasElement; DescrNode: TDOMElement);
     function ConstValue(ConstDecl: TPasConst): String;
     procedure ProcessSection(ASection: TPasSection);
     // Documentation writing methods.
@@ -588,8 +586,6 @@ begin
 end;
 
 procedure TIPFWriter.DescrBeginTable(ColCount: Integer; HasBorder: Boolean);
-var
-  i: Integer;
 begin
   // !!!: How do we set the border?
 //  for i := 1 to ColCount do
@@ -658,26 +654,6 @@ begin
 end;
 
 
-procedure TIPFWriter.WriteDescr(Element: TPasElement);
-var
-  DocNode: TDocNode;
-begin
-  DocNode := Engine.FindDocNode(Element);
-  if Assigned(DocNode) then
-    begin
-    if not IsDescrNodeEmpty(DocNode.Descr) then
-      WriteDescr(Element, DocNode.Descr)
-    else if not IsDescrNodeEmpty(DocNode.ShortDescr) then
-      WriteDescr(Element, DocNode.ShortDescr);
-    end;
-end;
-
-procedure TIPFWriter.WriteDescr(AContext: TPasElement; DescrNode: TDOMElement);
-begin
-  if Assigned(DescrNode) then
-    ConvertDescr(AContext, DescrNode, False);
-end;
-
 function TIPFWriter.ConstValue(ConstDecl: TPasConst): String;
 begin
   if Assigned(ConstDecl) then
@@ -860,11 +836,6 @@ begin
       end;
 end;
 
-const
-  SVisibility: array[TPasMemberVisibility] of string =
-       ('Default', 'Private', 'Protected', 'Public',
-      'Published', 'Automated');
-
 procedure TIPFWriter.WriteProcedure(ProcDecl : TPasProcedureBase);
 var
   DocNode: TDocNode;
@@ -1036,9 +1007,7 @@ end;
 procedure TIPFWriter.WriteClassMethodOverview(ClassDecl : TPasClassType);
 var
   Member: TPasElement;
-  i, j: Integer;
+  i: Integer;
-  s: String;
-  Arg: TPasArgument;
   DocNode: TDocNode;
   List : TStringList;
 
@@ -1080,9 +1049,8 @@ end;
 procedure TIPFWriter.WriteClassPropertyOverview(ClassDecl : TPasClassType);
 var
   Member: TPasElement;
-  i, j: Integer;
+  i: Integer;
   s: String;
-  Arg: TPasArgument;
   DocNode: TDocNode;
   List : TStringList;
 
@@ -1376,7 +1344,10 @@ end.
 
 {
   $Log$
-  Revision 1.2  2005-01-12 21:11:41  michael
+  Revision 1.3  2005-01-14 17:55:07  michael
+  + Added unix man page output; Implemented usage
+
+  Revision 1.2  2005/01/12 21:11:41  michael
   + New structure for writers. Implemented TXT writer
 
   Revision 1.1  2003/10/08 11:41:54  yuri

utils/fpdoc/dw_txt.pp

@@ -25,9 +25,6 @@ const
   TxtHighLight : Boolean = False;
   TxtExtension   : String = '.txt';
 
-Var
-  LEOL : Integer;
-  
 Procedure CreateTxtDocForPackage(APackage: TPasPackage; AEngine: TFPDocEngine);
 
 implementation
@@ -679,7 +676,6 @@ end;
 
 initialization
   // Do not localize.
-  LEOL:=Length(LineEnding);
   RegisterWriter(TTXTWriter,'txt','Plain text.');
 finalization
   UnRegisterWriter('txt');
@@ -688,7 +684,10 @@ end.
 
 {
   $Log$
-  Revision 1.1  2005-01-12 21:11:41  michael
+  Revision 1.2  2005-01-14 17:55:07  michael
+  + Added unix man page output; Implemented usage
+
+  Revision 1.1  2005/01/12 21:11:41  michael
   + New structure for writers. Implemented TXT writer
 
   Revision 1.8  2005/01/09 15:59:50  michael

utils/fpdoc/dwlinear.pp

@@ -37,8 +37,6 @@ Type
     Function  GetDescrString(AContext: TPasElement; DescrNode: TDOMElement) : String;
     function  ConstValue(ConstDecl: TPasConst): String; virtual;
     procedure ProcessSection(ASection: TPasSection); virtual;
-    procedure WriteDescr(Element: TPasElement); virtual;
-    procedure WriteDescr(AContext: TPasElement; DescrNode: TDOMElement); virtual;
     // Procedures which MAY be overridden in descendents
     Function  EscapeText(S : String) : String; virtual;
     Function  StripText(S : String) : String; virtual;
@@ -157,28 +155,6 @@ begin
   self.Write(EscapeText(AText));
 end;
 
-procedure TLinearWriter.WriteDescr(Element: TPasElement);
-
-var
-  DocNode: TDocNode;
-
-begin
-  DocNode := Engine.FindDocNode(Element);
-  if Assigned(DocNode) then
-    begin
-    if not IsDescrNodeEmpty(DocNode.Descr) then
-      WriteDescr(Element, DocNode.Descr)
-    else if not IsDescrNodeEmpty(DocNode.ShortDescr) then
-      WriteDescr(Element, DocNode.ShortDescr);
-    end;
-end;
-
-procedure TLinearWriter.WriteDescr(AContext: TPasElement; DescrNode: TDOMElement);
-begin
-  if Assigned(DescrNode) then
-    ConvertDescr(AContext, DescrNode, False);
-end;
-
 Function TLinearWriter.GetDescrString(AContext: TPasElement; DescrNode: TDOMElement) : String;
 
 Var
@@ -854,7 +830,7 @@ begin
     Example := ADocNode.FirstExample;
     while Assigned(Example) do
       begin
-      if (Example.NodeType = ELEMENT_NODE) and (Example.NodeName = 'example') then
+      if IsExampleNode(Example) then
         begin
         if (S<>'') then // not first example, start new paragraph
           DescrBeginParagraph;
@@ -935,8 +911,7 @@ begin
   First:=True;
   while Assigned(Node) do
     begin
-    if (Node.NodeType = ELEMENT_NODE) and
+    if IsLinkNode(Node) then
-       (Node.NodeName = 'link') then
       begin
       If First then
         begin
@@ -981,10 +956,8 @@ var
   i: Integer;
 begin
   if (ASection.Classes.Count > 0) then
-  begin
     for i := 0 to ASection.Classes.Count - 1 do
       WriteClassDecl(TPasClassType(ASection.Classes[i]));
-  end;
 end;
 
 procedure TLinearWriter.WriteClassMethodOverview(ClassDecl: TPasClassType);

utils/fpdoc/dwriter.pp

@@ -153,6 +153,13 @@ type
     Function InterpretOption(Const Cmd,Arg : String) : Boolean; Virtual;
     Class Procedure Usage(List : TStrings); virtual;
     procedure WriteDoc; virtual; Abstract;
+    procedure WriteDescr(Element: TPasElement);
+    procedure WriteDescr(Element: TPasElement; DocNode: TDocNode);
+    procedure WriteDescr(AContext: TPasElement; DescrNode: TDOMElement); virtual;
+    Procedure FPDocError(Msg : String);
+    Procedure FPDocError(Fmt : String; Args : Array of Const);
+    Function  ShowMember(M : TPasElement) : boolean;
+    Procedure GetMethodList(ClassDecl: TPasClassType; List : TStringList);
   end;
 
   TFPDocWriterClass = Class of TFPDocWriter;
@@ -961,6 +968,64 @@ begin
   Inherited;
 end;
 
+procedure TFPDocWriter.WriteDescr(Element: TPasElement);
+
+begin
+  WriteDescr(ELement,Engine.FindDocNode(Element));
+end;
+
+procedure TFPDocWriter.WriteDescr(Element: TPasElement; DocNode: TDocNode);
+
+begin
+  if Assigned(DocNode) then
+    begin
+    if not IsDescrNodeEmpty(DocNode.Descr) then
+      WriteDescr(Element, DocNode.Descr)
+    else if not IsDescrNodeEmpty(DocNode.ShortDescr) then
+      WriteDescr(Element, DocNode.ShortDescr);
+    end;
+end;
+
+procedure TFPDocWriter.WriteDescr(AContext: TPasElement; DescrNode: TDOMElement);
+begin
+  if Assigned(DescrNode) then
+    ConvertDescr(AContext, DescrNode, False);
+end;
+
+procedure TFPDocWriter.FPDocError(Msg: String);
+begin
+  Raise EFPDocWriterError.Create(Msg);
+end;
+
+procedure TFPDocWriter.FPDocError(Fmt: String; Args: array of const);
+begin
+  FPDocError(Format(Fmt,Args));
+end;
+
+function TFPDocWriter.ShowMember(M: TPasElement): boolean;
+begin
+  Result:=not ((M.Visibility=visPrivate) and Engine.HidePrivate);
+  If Result then
+    Result:=Not ((M.Visibility=visProtected) and Engine.HideProtected)
+end;
+
+Procedure TFPDocWriter.GetMethodList(ClassDecl: TPasClassType; List : TStringList);
+
+Var
+  I : Integer;
+  M : TPasElement;
+  
+begin
+  List.Clear;
+  List.Sorted:=False;
+  for i := 0 to ClassDecl.Members.Count - 1 do
+    begin
+    M:=TPasElement(ClassDecl.Members[i]);
+    if M.InheritsFrom(TPasProcedureBase) and ShowMember(M) then
+       List.AddObject(M.Name,M);
+    end;
+  List.Sorted:=False;
+end;
 
 initialization
   InitWriterList;
@@ -971,7 +1036,10 @@ end.
 
 {
   $Log$
-  Revision 1.4  2005-01-12 21:11:41  michael
+  Revision 1.5  2005-01-14 17:55:07  michael
+  + Added unix man page output; Implemented usage
+
+  Revision 1.4  2005/01/12 21:11:41  michael
   + New structure for writers. Implemented TXT writer
 
   Revision 1.3  2004/08/28 18:05:17  michael

utils/fpdoc/fpdoc.pp

@@ -25,6 +25,7 @@ uses
   dw_XML,   // XML writer
   dw_HTML,  // HTML writer
   dw_ipf,   // IPF writer
+  dw_man,   // Man page writer
   dw_txt;   // TXT writer
 
 const
@@ -40,8 +41,61 @@ var
 
 Procedure Usage(AnExitCode : Byte);
 
+Var
+  I,P : Integer;
+  S : String;
+  L : TStringList;
+  C : TFPDocWriterClass;
+  
 begin
-  Writeln(SCmdLineHelp);
+  Writeln(Format(SCmdLineHelp,[ExtractFileName(Paramstr(0))]));
+  Writeln(SUsageOption010);
+  Writeln(SUsageOption020);
+  Writeln(SUsageOption030);
+  Writeln(SUsageOption040);
+  Writeln(SUsageOption050);
+  Writeln(SUsageOption060);
+  Writeln(SUsageOption070);
+  Writeln(SUsageOption080);
+  Writeln(SUsageOption090);
+  Writeln(SUsageOption100);
+  Writeln(SUsageOption110);
+  Writeln(SUsageOption120);
+  Writeln(SUsageOption130);
+  Writeln(SUsageOption140);
+  Writeln(SUsageOption150);
+  Writeln(SUsageOption160);
+  Writeln(SUsageOption170);
+  L:=TStringList.Create;
+  Try
+    If (Backend='') then
+      begin
+      Writeln;
+      Writeln(SUsageFormats);
+      EnumWriters(L);
+      For I:=0 to L.Count-1 do
+        begin
+        S:=L[i];
+        P:=Pos('=',S);
+        Writeln(Format(' %s - %s',[Copy(S,1,P-1)+Space(10-p),Copy(S,P+1,Length(S))]));
+        end;
+      Writeln(SUsageBackendHelp);
+      end
+    else
+      begin
+      Writeln;
+      Writeln(Format(SUsageFormatSpecific,[Lowercase(Backend)]));
+      C:=GetWriterClass(backend);
+      C.Usage(L);
+      For I:=0 to (L.Count-1) div 2 do
+        begin
+        S:=L[i*2];
+        Writeln(Format('%s %s',[S+Space(30-Length(S)),L[(i*2)+1]]));
+        end;
+      end;
+  Finally
+    L.Free;
+  end;
   Halt(AnExitCode);
 end;
 
@@ -229,7 +283,10 @@ end.
 
 {
   $Log$
-  Revision 1.7  2005-01-12 21:11:41  michael
+  Revision 1.8  2005-01-14 17:55:07  michael
+  + Added unix man page output; Implemented usage
+
+  Revision 1.7  2005/01/12 21:11:41  michael
   + New structure for writers. Implemented TXT writer
 
   Revision 1.6  2005/01/09 15:59:50  michael