o commit patch from Mantis 17191:

* Patch with new linear based IPF writer
    * patch for Interfaces Overview in all Linear writers
    * patch with new Linear Writer specific parameter to control
      if linked documentation should be duplicated or not.
      new parameter is: --duplinkeddoc
      Default is that linked docs are not duplicated.
    * patch for fixing minor spelling mistakes in fpdoc
    * patch to not create a section Errors if there isn't actually
      any specific documentation for errors. makeskel generates error
      nodes but most don't have any items. This caused an Errors title
      in the docs, but with no content.
    * patch to fix SeeAlso section in Linear writer. It never output
      the custom text, but always the node link as text.
    * new features for linear writer that could be overridden in
      descendants.
      - marked some protected methods as virtual so it can be overridden
        in descendants for customization.
      - new section for listing Types found in a unit. Default does nothing,
        except in IPF writer.
      - new section for listing Variables found in a unit. Default does
        nothing, except in IPF writer.
      - new section for listing Constants found in a unit. Default does
        nothing, except in IPF writer.

git-svn-id: trunk@15849 -

.gitattributes

@@ -11616,7 +11616,7 @@ utils/fpdoc/dglobals.pp svneol=native#text/plain
 utils/fpdoc/dw_dxml.pp svneol=native#text/plain
 utils/fpdoc/dw_html.pp svneol=native#text/plain
 utils/fpdoc/dw_htmlchm.inc svneol=native#text/plain
-utils/fpdoc/dw_ipf.pp svneol=native#text/plain
+utils/fpdoc/dw_ipflin.pas svneol=native#text/plain
 utils/fpdoc/dw_latex.pp svneol=native#text/plain
 utils/fpdoc/dw_linrtf.pp svneol=native#text/plain
 utils/fpdoc/dw_lintmpl.pp svneol=native#text/plain

utils/fpdoc/dglobals.pp

@@ -63,6 +63,7 @@ resourcestring
   SDocRemark                 = 'Remark:   ';
   SDocMethodOverview         = 'Method overview';
   SDocPropertyOverview       = 'Property overview';
+  SDocInterfacesOverview     = 'Interfaces overview';
   SDocPage                   = 'Page';
   SDocMethod                 = 'Method';
   SDocProperty               = 'Property';
@@ -119,6 +120,10 @@ resourcestring
   SCHMUsageAutoIDX = 'Automatically generate an Index. Ignores --index-file';
   SCHMUsageMakeSearch = 'Automatically generate a Search Index from filenames that match *.htm*';
 
+  // Linear usage
+  SLinearUsageDupLinkedDocsP1 = 'Duplicate linked element documentation in';
+  SLinearUsageDupLinkedDocsP2 = 'descendant classes.';
+
   STitle           = 'FPDoc - Free Pascal Documentation Tool';
   SVersion         = 'Version %s [%s]';
   SCopyright       = '(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org';
@@ -155,7 +160,7 @@ resourcestring
   SDone                       = 'Done.';
   SErrCouldNotCreateOutputDir = 'Could not create output directory "%s"';
   SErrCouldNotCreateFile      = 'Could not create file "%s": %s';
-  SSeeURL                     = '(See %s)';      // For lineair text writers.
+  SSeeURL                     = '(See %s)';      // For linear text writers.
 
 Const
   SVisibility: array[TPasMemberVisibility] of string =

utils/fpdoc/dw_latex.pp

@@ -77,8 +77,8 @@ Type
     procedure StartChapter(ChapterName : String); override;
     procedure StartOverview(WithAccess : Boolean); override;
     procedure EndOverview; override;
-    procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); override;
+    procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override;
-    procedure WriteOverviewMember(ALabel,AName,ADescr : String); override;
+    procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override;
     Class Function FileNameExtension : String; override;
     // Description node conversion
     procedure DescrBeginBold; override;
@@ -658,13 +658,13 @@ begin
   WriteLn('\end{tabularx}');
 end;
 
-procedure TLatexWriter.WriteOverviewMember(ALabel,AName,Access,ADescr : String);
+procedure TLatexWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String);
 
 begin
   WriteLnF('\pageref{%s} & %s & %s & %s \\',[ALabel,EscapeText(AName),Access,ADescr]);
 end;
 
-procedure TLatexWriter.WriteOverviewMember(ALabel,AName,ADescr : String);
+procedure TLatexWriter.WriteOverviewMember(const ALabel,AName,ADescr : String);
 
 begin
   WriteLnF('\pageref{%s} & %s  & %s \\',[ALabel,EscapeText(AName),ADescr]);

utils/fpdoc/dw_linrtf.pp

@@ -111,8 +111,8 @@ type
     procedure StartSubSubSection(SubSubSectionName : String);override;
     procedure StartChapter(ChapterName : String); override;
     procedure StartOverview(WithAccess : Boolean); override;
-    procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); override;
+    procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override;
-    procedure WriteOverviewMember(ALabel,AName,ADescr : String); override;
+    procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override;
     procedure EndOverview; override;
     Class Function FileNameExtension : String; override;
     // Description node conversion
@@ -714,7 +714,7 @@ begin
         [EscapeText(SDocPage), EscapeText(SDocProperty), EscapeText(SDocDescription)]);
 end;
 
-procedure TRTFWriter.WriteOverviewMember(ALabel,AName,Access,ADescr : String);
+procedure TRTFWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String);
 begin
   //TODO: Translate Latex \pageref to RTF
   //WriteLnF('\pageref{%s} & %s  & %s & %s \\',[ALabel,AName,Access,ADescr]);
@@ -722,7 +722,7 @@ begin
       [ALabel,AName,Access,ADescr]);
 end;
 
-procedure TRTFWriter.WriteOverviewMember(ALabel,AName,ADescr : String);
+procedure TRTFWriter.WriteOverviewMember(const ALabel,AName,ADescr : String);
 begin
   //TODO: Translate Latex \pageref to RTF
   //WriteLnF('\pageref{%s} & %s  & %s \\',[ALabel,AName,ADescr]);

utils/fpdoc/dw_txt.pp

@@ -80,8 +80,8 @@ Type
     procedure StartChapter(ChapterName : String); override;
     procedure StartOverview(WithAccess : Boolean); override;
     procedure EndOverview; override;
-    procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); override;
+    procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override;
-    procedure WriteOverviewMember(ALabel,AName,ADescr : String); override;
+    procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override;
     Class Function FileNameExtension : String; override;
     // Description node conversion
     procedure DescrBeginBold; override;
@@ -637,13 +637,13 @@ begin
   WriteLine(False);
 end;
 
-procedure TTxtWriter.WriteOverviewMember(ALabel,AName,Access,ADescr : String);
+procedure TTxtWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String);
 
 begin
   WriteLnF('%.30s %.10s  %s',[AName,Access,ADescr]);
 end;
 
-procedure TTxtWriter.WriteOverviewMember(ALabel,AName,ADescr : String);
+procedure TTxtWriter.WriteOverviewMember(const ALabel,AName,ADescr : String);
 
 begin
   WriteLnF('%.30s %s ',[AName,ADescr]);

utils/fpdoc/dwlinear.pp

@@ -14,19 +14,23 @@ Type
     FStream : TStream;
     PackageName: String;
     Module: TPasModule;
-    ModuleName: String;
     FLastURL : DomString;
   private
+    FDupLinkedDoc: Boolean;
   Protected
+    ModuleName: String;
     // Writing support.
     procedure Write(const s: String); virtual;
     procedure WriteLn(const s: String); virtual;
-    procedure WriteF(const s: String; const Args: array of const);
+    procedure WriteF(const s: String; const Args: array of const); virtual;
-    procedure WriteLnF(const s: String; const Args: array of const);
+    procedure WriteLnF(const s: String; const Args: array of const); virtual;
     Function  PushWriteContext(S : TStream) : TStream;
     Procedure PopWriteContext(S : TSTream);
     procedure WriteLabel(El: TPasElement);
     procedure WriteIndex(El: TPasElement);
+    procedure WriteTypeDecl(El: TPasElement); virtual;
+    procedure WriteVariableDecl(El: TPasElement); virtual;
+    procedure WriteConstDecl(El: TPasElement); virtual;
     // Auxiliary routines
     procedure DescrBeginURL(const AURL: DOMString); override; // Provides a default implementation
     procedure DescrEndURL; override;
@@ -64,6 +68,9 @@ Type
     function  GetLabel(AElement: TPasElement): String; virtual; abstract;
     procedure WriteLabel(Const S : String); virtual; abstract;
     procedure WriteIndex(Const S : String); virtual; abstract;
+    procedure WriteType(const s: string); virtual;
+    procedure WriteVariable(const s: string); virtual;
+    procedure WriteConstant(const s: string); virtual;
     procedure StartChapter(ChapterName : String); virtual; abstract;
     procedure StartSection(SectionName : String); virtual; abstract;
     procedure StartSubSection(SubSectionName : String); virtual; abstract;
@@ -73,8 +80,8 @@ Type
     Procedure WriteExampleFile(FN : String); virtual; abstract;
     procedure StartOverview(WithAccess : Boolean); virtual; Abstract;
     procedure EndOverview; virtual; Abstract;
-    procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); virtual; Abstract;
+    procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); virtual; Abstract;
-    procedure WriteOverviewMember(ALabel,AName,ADescr : String); virtual; Abstract;
+    procedure WriteOverviewMember(const ALabel,AName,ADescr : String); virtual; Abstract;
     procedure StartUnitOverview(AModuleName,AModuleLabel : String);virtual; Abstract;
     procedure WriteUnitEntry(UnitRef : TPasType);virtual; Abstract;
     procedure EndUnitOverview; virtual; Abstract;
@@ -82,6 +89,8 @@ Type
     Property LastURL : DomString Read FLastURL Write FLastURL;
   Public
     Constructor Create(APackage: TPasPackage; AEngine: TFPDocEngine); override;
+    function InterpretOption(const Cmd, Arg: String): Boolean; override;
+    class procedure Usage(List: TStrings); override;
     procedure WriteDoc; override;
     // Linear Documentation writing methods.
     Procedure ProcessPackage;
@@ -90,7 +99,7 @@ Type
     procedure WriteUnitOverview(ASection: TPasSection);
     procedure WriteVarsConstsTypes(ASection: TPasSection);
     procedure WriteConsts(ASection: TPasSection);
-    procedure WriteTypes(ASection: TPasSection);
+    procedure WriteTypes(ASection: TPasSection); virtual;
     procedure WriteEnumElements(TypeDecl : TPasEnumType);
     procedure WriteVars(ASection: TPasSection);
     procedure WriteFunctionsAndProcedures(ASection: TPasSection);
@@ -99,6 +108,7 @@ Type
     procedure WriteClassDecl(ClassDecl: TPasClassType);
     procedure WriteClassMethodOverview(ClassDecl: TPasClassType);
     procedure WriteClassPropertyOverview(ClassDecl: TPasClassType);
+    procedure WriteClassInterfacesOverView(ClassDecl: TPasClassType);
     procedure WriteProperty(PropDecl: TPasProperty);
     procedure WriteExample(ADocNode: TDocNode);
     procedure WriteSeeAlso(ADocNode: TDocNode);
@@ -109,6 +119,9 @@ Type
 
 implementation
 
+const
+  cDupLinkedDocParam = '--duplinkeddoc';
+
 { TLinearWriter }
 
 { ---------------------------------------------------------------------
@@ -157,9 +170,8 @@ begin
 end;
 
 procedure TLinearWriter.DescrWriteText(const AText: DOMString);
-
 begin
-  self.Write(EscapeText(AText));
+  Write(EscapeText(AText));
 end;
 
 Function TLinearWriter.GetDescrString(AContext: TPasElement; DescrNode: TDOMElement) : String;
@@ -201,6 +213,21 @@ begin
   WriteIndex(EL.Name);
 end;
 
+procedure TLinearWriter.WriteTypeDecl(El: TPasElement);
+begin
+  WriteType(El.Name);
+end;
+
+procedure TLinearWriter.WriteVariableDecl(El: TPasElement);
+begin
+	WriteVariable(El.Name);
+end;
+
+procedure TLinearWriter.WriteConstDecl(El: TPasElement);
+begin
+	WriteConstant(El.Name);
+end;
+
 procedure TLinearWriter.DescrBeginURL(const AURL: DOMString);
 begin
   FLastURL:=AURL;
@@ -346,6 +373,20 @@ begin
   Writeln('');
 end;
 
+procedure TLinearWriter.WriteType(const s: string);
+begin
+  // do nothing
+end;
+
+procedure TLinearWriter.WriteVariable(const s: string);
+begin
+  // do nothing
+end;
+
+procedure TLinearWriter.WriteConstant(const s: string);
+begin
+  // do nothing
+end;
 
 procedure TLinearWriter.WriteClassDecl(ClassDecl: TPasClassType);
 var
@@ -368,8 +409,14 @@ begin
       StartSubSection(SDocVersion);
       WriteDescr(ClassDecl,DocNode.Version);
       end;
+    if Assigned(DocNode.SeeAlso) then
+    begin
+      WriteSeeAlso(DocNode);
+    end;
   end;
 
+  // Write Interfaces Overview;
+  WriteClassInterfacesOverView(ClassDecl);
   // Write method overview
   WriteClassMethodOverView(ClassDecl);
   // Write Property Overview;
@@ -413,7 +460,7 @@ var
   L,N,S,A: String;
   DocNode: TDocNode;
   List : TStringList;
-
+  lNode: TDocNode;
 begin
   // Write property overview
   List:=TStringList.Create;
@@ -437,10 +484,20 @@ begin
         L:=StripText(GetLabel(Member));
         N:=EscapeText(Member.Name);
         DocNode := Engine.FindDocNode(Member);
-        If Assigned(DocNode) then
+        if Assigned(DocNode) then
-          S:=GetDescrString(Member, DocNode.ShortDescr)
+        begin
+          if FDupLinkedDoc and (DocNode.Link <> '') then
+          begin
+            lNode := Engine.FindLinkedNode(DocNode);
+            if not Assigned(lNode) then
+              lNode := DocNode;
+          end
+          else
+            lNode := DocNode;
+          S := GetDescrString(Member, lNode.ShortDescr);
+        end
         else
-          S:='';
+          S := '';
 
         A:='';
         if Length(TPasProperty(Member).ReadAccessorName) > 0 then
@@ -450,6 +507,7 @@ begin
         if Length(TPasProperty(Member).StoredAccessorName) > 0 then
           a := a + 's';
         WriteOverviewMember(L,N,A,S);
+        S := '';
         end;
       EndOverview;
       end;
@@ -459,6 +517,61 @@ begin
 end;
 
 
+procedure TLinearWriter.WriteClassInterfacesOverView(ClassDecl: TPasClassType);
+var
+  lInterface: TPasElement;
+  i: Integer;
+  L,N,S,A: String;
+  DocNode: TDocNode;
+  List : TStringList;
+  lNode: TDocNode;
+begin
+  // Write Interfaces overview
+  List:=TStringList.Create;
+  try
+    List.Sorted:=True;
+    for i := 0 to ClassDecl.Interfaces.Count-1 do
+    begin
+      lInterface := TPasElement(ClassDecl.Interfaces[i]);
+      List.AddObject(lInterface.Name,lInterface);
+    end;
+    if (List.Count>0) then
+    begin
+      StartSubSection(SDocInterfacesOverview);
+      WriteLabel(GetLabel(ClassDecl) + ':Interfaces');
+      StartOverView(False);
+      for i := 0 to List.Count-1 do
+      begin
+        lInterface := TPasElement(List.Objects[i]);
+        L := StripText(GetLabel(lInterface));
+        N := EscapeText(lInterface.Name);
+        DocNode := Engine.FindDocNode(lInterface);
+        if Assigned(DocNode) then
+        begin
+          if FDupLinkedDoc and (DocNode.Link <> '') then
+          begin
+            lNode := Engine.FindLinkedNode(DocNode);
+            if not Assigned(lNode) then
+              lNode := DocNode;
+          end
+          else
+            lNode := DocNode;
+          S := GetDescrString(lInterface, lNode.ShortDescr);
+        end
+        else
+          S := '';
+
+        WriteOverviewMember(L,N,S);
+        S := '';
+      end;
+      EndOverview;
+    end;
+  finally
+    List.Free;
+  end;
+end;
+
+
 function TLinearWriter.ConstValue(ConstDecl: TPasConst): String;
 begin
   if Assigned(ConstDecl) then
@@ -562,7 +675,7 @@ begin
     begin
       ResStrDecl := TPasResString(ASection.ResStrings[i]);
       StartListing(false, '');
-      Writeln(ResStrDecl.GetDeclaration(True));
+      DescrWriteText(ResStrDecl.GetDeclaration(True)); // instead of WriteLn() so we can do further processing like manual line wrapping in descendants
       EndListing;
       WriteLabel(ResStrDecl);
       WriteIndex(ResStrDecl);
@@ -683,6 +796,7 @@ begin
       begin
       DescrBeginParaGraph;
       ConstDecl := TPasConst(ASection.Consts[i]);
+      WriteConstDecl(ConstDecl);
       StartListing(False,'');
       WriteLn(EscapeText(ConstDecl.GetDeclaration(True)));
       EndListing;
@@ -746,16 +860,19 @@ begin
     StartSubSection(SDocTypes,ModuleName+'Types');
     for i := 0 to ASection.Types.Count - 1 do
     begin
-      DescrBeginParaGraph;
+      DescrBeginParagraph;
       TypeDecl := TPasType(ASection.Types[i]);
+      WriteTypeDecl(TypeDecl);
       StartListing(False,'');
       DocNode := Engine.FindDocNode(TypeDecl);
       If Assigned(DocNode) and 
          Assigned(DocNode.Node) and 
          (Docnode.Node['opaque']='1') then
           Writeln(TypeDecl.Name+' = '+SDocOpaque)
-      else    
+      else
-         Writeln(EscapeText(TypeDecl.GetDeclaration(True)));
+      begin
+        Writeln(EscapeText(TypeDecl.GetDeclaration(True)));
+      end;
       EndListing;
       WriteLabel(TypeDecl);
       WriteIndex(TypeDecl);
@@ -769,7 +886,7 @@ begin
         Writeln(Format('%s : ',[SDocVersion]));
         WriteDescr(TypeDecl, DocNode.Version);
         end;
-      DescrEndParaGraph;
+      DescrEndParagraph;
       end;
   end;
 end;
@@ -788,6 +905,7 @@ begin
     begin
       DescrBeginParaGraph;
       VarDecl := TPasVariable(ASection.Variables[i]);
+      WriteVariableDecl(VarDecl);
       StartListing(False,'');
       WriteLn(EscapeText(VarDecl.GetDeclaration(True)));
       EndListing;
@@ -857,7 +975,7 @@ begin
         StartDescription;
         WriteDescr(ProcDecl);
         end;
-      if Assigned(DocNode.ErrorsDoc) then
+      if Assigned(DocNode.ErrorsDoc) and (DocNode.ErrorsDoc.HasChildNodes) then
         begin
         StartErrors;
         WriteDescr(ProcDecl, DocNode.ErrorsDoc);
@@ -920,6 +1038,7 @@ procedure TLinearWriter.WriteProperty(PropDecl : TPasProperty);
 var
   DocNode: TDocNode;
   S: String;
+  lNode: TDocNode;
 begin
   With PropDecl do
     begin
@@ -928,11 +1047,23 @@ begin
     WriteIndex(Parent.Name+'.'+Name);
     StartProperty;
     DocNode := Engine.FindDocNode(PropDecl);
-    if Assigned(DocNode) and Assigned(DocNode.ShortDescr) then
+    if Assigned(DocNode) then
+    begin
+      if FDupLinkedDoc and (DocNode.Link <> '') then
       begin
-      StartSynopsis;
+        lNode := Engine.FindLinkedNode(DocNode);
-      WriteDescr(PropDecl, DocNode.ShortDescr);
+        if not Assigned(lNode) then
+          lNode := DocNode;
+      end
+      else
+        lNode := DocNode;
+
+      if Assigned(lNode.ShortDescr) then
+      begin
+        StartSynopsis;
+        WriteDescr(PropDecl, lNode.ShortDescr);
       end;
+    end;
     StartDeclaration;
     StartListing(False);
     WriteLn('Property '+GetDeclaration(True));
@@ -954,27 +1085,27 @@ begin
       end;
     Writeln(S);
     if Assigned(DocNode) then
-      begin
+    begin
-      if Assigned(DocNode.Descr) then
+      if Assigned(lNode.Descr) then     // lNode will be assigned if DocNode exists
         begin
         StartDescription;
-        WriteDescr(PropDecl);
+        WriteDescr(PropDecl, lNode);
         end;
-      if Assigned(DocNode.ErrorsDoc) then
+      if Assigned(lNode.ErrorsDoc) and (lNode.ErrorsDoc.HasChildNodes) then
         begin
         StartErrors;
         WriteDescr(PropDecl, DocNode.ErrorsDoc);
         end;
-      if Assigned(DocNode.Version) then
+      if Assigned(lNode.Version) then
         begin
         StartVersion;
-        WriteDescr(PropDecl, DocNode.Version);
+        WriteDescr(PropDecl, lNode.Version);
         end;
-      WriteSeeAlso(DocNode);
+      WriteSeeAlso(lNode);
       EndProperty;
-      WriteExample(DocNode);
+      WriteExample(lNode);
-      end
+    end
-     else
+    else
       EndProperty;
     end;
 end;
@@ -1004,6 +1135,8 @@ begin
         Writeln(',');
       S:=TDomElement(Node)['id'];
       DescrBeginLink(S);
+      if Node.FirstChild <> nil then
+        s := Node.FirstChild.NodeValue;
       Write(EscapeText(S));
       DescrEndLink();
       end;
@@ -1208,6 +1341,7 @@ var
   i: Integer;
 begin
   inherited ;
+  FDupLinkedDoc := False; // by default we don't duplicate linked element documentation
 
   { Allocate labels for all elements for which we are going to create
     documentation. This is needed for links to work correctly. }
@@ -1231,6 +1365,28 @@ end;
 
 procedure TLinearWriter.WriteEndDocument;
 begin
+  // do nothing
 end;
 
+function TLinearWriter.InterpretOption(const Cmd: String; const Arg: String): Boolean;
+begin
+  Result := True;
+  if Cmd = cDupLinkedDocParam then
+  begin
+    FDupLinkedDoc := True;
+  end
+  else
+    Result := False;
+end;
+
+class procedure TLinearWriter.Usage(List: TStrings);
+begin
+  List.Add(cDupLinkedDocParam);
+  List.Add(SLinearUsageDupLinkedDocsP1);
+  List.Add('');
+  List.Add(SLinearUsageDupLinkedDocsP2);
+end;
+
+
 end.
+

utils/fpdoc/fpdoc.pp

@@ -24,9 +24,9 @@ uses
   dw_XML,    // XML writer
   dw_dxml,   // Delphi XML doc.
   dw_HTML,   // HTML writer
-  dw_ipf,    // IPF writer
+  dw_ipflin, // IPF writer (new linear output)
   dw_man,    // Man page writer
-  dw_linrtf, // lineair RTF writer
+  dw_linrtf, // linear RTF writer
   dw_txt;    // TXT writer
 
 const