diff --git a/.gitattributes b/.gitattributes index 0ebf3156ec..0427db17a1 100644 --- a/.gitattributes +++ b/.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 diff --git a/utils/fpdoc/dglobals.pp b/utils/fpdoc/dglobals.pp index ed432040a4..357fb2193b 100644 --- a/utils/fpdoc/dglobals.pp +++ b/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 = diff --git a/utils/fpdoc/dw_ipf.pp b/utils/fpdoc/dw_ipf.pp deleted file mode 100644 index f51cc1ba0d..0000000000 --- a/utils/fpdoc/dw_ipf.pp +++ /dev/null @@ -1,1341 +0,0 @@ -{ - - FPDoc - Free Pascal Documentation Tool - Copyright (C) 2000 - 2003 by - Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org - - * IPF output generator - - See the file COPYING, included in this distribution, - for details about the copyright. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -} - -unit dw_IPF; - -{$MODE objfpc} -{$H+} - -interface - -uses SysUtils, Classes, dWriter, DOM, dGlobals, PasTree; - -const - IPFHighLight : Boolean = False; - IPFExtension : String = '.ipf'; - -type - TLabelType = (ltConst,ltVar,ltType,ltFunction,ltProcedure,ltClass, - ltChapter,ltSection,ltSubsection, - ltTable,ltFigure); - - { TIPFWriter } - - TIPFWriter = class(TFPDocWriter) - protected - f: Text; - FLink: String; - PackageName: String; - Module: TPasModule; - ModuleName: String; - FTableCount : Integer; - TableRowStartFlag, TableCaptionWritten: Boolean; - - function GetLabel(AElement: TPasElement): String; - - procedure Write(const s: String); - procedure WriteF(const s: String; const Args: array of const); - procedure WriteLn(const s: String); - procedure WriteLnF(const s: String; const Args: array of const); - // Tex functions - procedure WriteLabel(El: TPasElement); - procedure WriteLabel(const s: String); - procedure WriteIndex(El: TPasElement); - procedure WriteIndex(const s: String); - procedure StartListing(Frames: Boolean; const name: String); - procedure StartListing(Frames: Boolean); - procedure EndListing; - Function EscapeTex(S : String) : String; - Function StripTex(S : String) : String; - - procedure WriteCommentLine; - procedure WriteComment(Comment : String); - procedure StartSection(SectionName : String; SectionLabel : String); -// procedure StartSection(SectionName : String); - procedure StartSubSection(SubSectionName : String; SubSectionLabel : String); -// procedure StartSubSection(SubSectionName : String); - procedure StartChapter(ChapterName : String; ChapterLabel : String); - procedure StartChapter(ChapterName : String); - // Description node conversion - procedure DescrWriteText(const AText: DOMString); override; - procedure DescrBeginBold; override; - procedure DescrEndBold; override; - procedure DescrBeginItalic; override; - procedure DescrEndItalic; override; - procedure DescrBeginEmph; override; - procedure DescrEndEmph; override; - procedure DescrWriteFileEl(const AText: DOMString); override; - procedure DescrWriteKeywordEl(const AText: DOMString); override; - procedure DescrWriteVarEl(const AText: DOMString); override; - procedure DescrBeginLink(const AId: DOMString); override; - procedure DescrEndLink; override; - procedure DescrWriteLinebreak; override; - procedure DescrBeginParagraph; override; - procedure DescrBeginCode(HasBorder: Boolean; const AHighlighterName: String); override; - procedure DescrWriteCodeLine(const ALine: String); override; - procedure DescrEndCode; override; - procedure DescrEndParagraph; override; - procedure DescrBeginOrderedList; override; - procedure DescrEndOrderedList; override; - procedure DescrBeginUnorderedList; override; - procedure DescrEndUnorderedList; override; - procedure DescrBeginDefinitionList; override; - procedure DescrEndDefinitionList; override; - procedure DescrBeginListItem; override; - procedure DescrEndListItem; override; - procedure DescrBeginDefinitionTerm; override; - procedure DescrEndDefinitionTerm; override; - procedure DescrBeginDefinitionEntry; override; - procedure DescrEndDefinitionEntry; override; - procedure DescrBeginSectionTitle; override; - procedure DescrBeginSectionBody; override; - procedure DescrEndSection; override; - procedure DescrBeginRemark; override; - procedure DescrEndRemark; override; - procedure DescrBeginTable(ColCount: Integer; HasBorder: Boolean); override; - procedure DescrEndTable; override; - procedure DescrBeginTableCaption; override; - procedure DescrEndTableCaption; override; - procedure DescrBeginTableHeadRow; override; - procedure DescrEndTableHeadRow; override; - procedure DescrBeginTableRow; override; - procedure DescrEndTableRow; override; - procedure DescrBeginTableCell; override; - procedure DescrEndTableCell; override; - function ConstValue(ConstDecl: TPasConst): String; - procedure ProcessSection(ASection: TPasSection); - // Documentation writing methods. - procedure WriteResourceStrings(ASection: TPasSection); - procedure WriteUnitOverview(ASection: TPasSection); - procedure WriteVarsConstsTypes(ASection: TPasSection); - procedure WriteConsts(ASection: TPasSection); - procedure WriteTypes(ASection: TPasSection); - procedure WriteEnumElements(TypeDecl : TPasEnumType); - procedure WriteVars(ASection: TPasSection); - procedure WriteFunctionsAndProcedures(ASection: TPasSection); - procedure WriteProcedure(ProcDecl: TPasProcedureBase); - procedure WriteClasses(ASection: TPasSection); - procedure WriteClassDecl(ClassDecl: TPasClassType); - procedure WriteClassMethodOverview(ClassDecl: TPasClassType); - procedure WriteClassPropertyOverview(ClassDecl: TPasClassType); - procedure WriteProperty(PropDecl: TPasProperty); - procedure WriteExample(ADocNode: TDocNode); - procedure WriteSeeAlso(ADocNode: TDocNode); - procedure SortElementList(List : TList); - Function ShowMember(M : TPasElement) : boolean; - public - constructor Create(APackage: TPasPackage; AEngine: TFPDocEngine); override; - procedure WriteDoc; override; - end; - - -implementation - - - - - -constructor TIPFWriter.Create(APackage: TPasPackage; AEngine: TFPDocEngine); - - procedure AddLabel(AElement: TPasElement); - begin - Engine.AddLink(AElement.PathName, GetLabel(AElement)); - end; - - procedure AddList(AElement: TPasElement; AList: TList); - var - i: Integer; - begin - for i := 0 to AList.Count - 1 do - AddLabel(TPasElement(AList[i])); - end; - - procedure ScanModule(AModule: TPasModule); - var - i, j, k: Integer; - s: String; - ClassEl: TPasClassType; - FPEl, AncestorMemberEl: TPasElement; - DocNode: TDocNode; - DidAutolink: Boolean; - begin - AddLabel(AModule); - with AModule do - begin - AddList(AModule, InterfaceSection.ResStrings); - AddList(AModule, InterfaceSection.Consts); - AddList(AModule, InterfaceSection.Types); - if InterfaceSection.Classes.Count > 0 then - begin - for i := 0 to InterfaceSection.Classes.Count - 1 do - begin - ClassEl := TPasClassType(InterfaceSection.Classes[i]); - AddLabel(ClassEl); - - for j := 0 to ClassEl.Members.Count - 1 do - begin - FPEl := TPasElement(ClassEl.Members[j]); - if ((FPEl.Visibility = visPrivate) and Engine.HidePrivate) or - ((FPEl.Visibility = visProtected) and Engine.HideProtected) then - continue; - - DocNode := Engine.FindDocNode(FPEl); - if not Assigned(DocNode) then - begin - DidAutolink := False; - if Assigned(ClassEl.AncestorType) and - (ClassEl.AncestorType.ClassType = TPasClassType) then - begin - for k := 0 to TPasClassType(ClassEl.AncestorType).Members.Count - 1 do - begin - AncestorMemberEl := - TPasElement(TPasClassType(ClassEl.AncestorType).Members[k]); - if AncestorMemberEl.Name = FPEl.Name then - begin - DocNode := Engine.FindDocNode(AncestorMemberEl); - if Assigned(DocNode) then - begin - DidAutolink := True; - Engine.AddLink(FPEl.PathName, - Engine.FindAbsoluteLink(AncestorMemberEl.PathName)); - break; - end; - end; - end; - end; - if not DidAutolink then - AddLabel(FPEl); - end else - AddLabel(FPEl); - end; - end; - end; - AddList(AModule, InterfaceSection.Functions); - AddList(AModule, InterfaceSection.Variables); - end; - end; - -var - i: Integer; -begin - inherited ; - - { Allocate labels for all elements for which we are going to create - documentation. This is needed for links to work correctly. } - - // Allocate label for the package itself, if a name is given (i.e. <> '#') - if Length(Package.Name) > 1 then - AddLabel(Package); - - for i := 0 to Package.Modules.Count - 1 do - ScanModule(TPasModule(Package.Modules[i])); -end; - -procedure TIPFWriter.WriteDoc; -var - i : Integer; - -begin - PackageName := LowerCase(Copy(Package.Name, 2, 255)); - If (Engine.OutPut='') then - Engine.Output:=PackageName+IPFExtension; - Assign(f, Engine.Output); - Rewrite(f); - try - WriteLn('.* This file has been created automatically by FPDoc,'); - WriteLn('.* (c) 2000-2003 by Areca Systems GmbH / Sebastian Guenther (sg@freepascal.org)'); - for i := 0 to Package.Modules.Count - 1 do - begin - Module := TPasModule(Package.Modules[i]); - ModuleName := LowerCase(Module.Name); - WriteLn(''); - Write(':h1 name='); - WriteLabel(Module); - WriteLnF('.%s', [EscapeTex(Format(SDocUnitTitle, [Module.Name]))]); - ProcessSection(Module.InterfaceSection); - end; - finally - Close(f); - end; -end; - -function TIPFWriter.GetLabel(AElement: TPasElement): String; -var - i: Integer; -begin - if AElement.ClassType = TPasUnresolvedTypeRef then - Result := Engine.ResolveLink(Module, AElement.Name) - else - begin - Result := AElement.PathName; - Result := LowerCase(Copy(Result, 2, Length(Result) - 1)); - end; - for i := 1 to Length(Result) do - if Result[i] = '.' then - Result[i] := '_'; -end; - -procedure TIPFWriter.Write(const s: String); -begin - System.Write(f, s); -end; - -procedure TIPFWriter.WriteF(const s: String; const Args: array of const); -begin - System.Write(f, Format(s, Args)); -end; - -procedure TIPFWriter.WriteLn(const s: String); -begin - System.WriteLn(f, s); -end; - -procedure TIPFWriter.WriteLnF(const s: String; const Args: array of const); -begin - System.WriteLn(f, Format(s, Args)); -end; - -Function TIPFWriter.EscapeTex(S : String) : String; - -var - i: Integer; - -begin - SetLength(Result, 0); - for i := 1 to Length(S) do - case S[i] of - '.': // Escape these characters - Result := Result + '&per.'; - ':': - Result := Result + '&colon.'; - ',': - Result := Result + '&comma.'; - '&': - Result := Result + '&.'; -(* -³&. ³ampersand ³& ³ -³&and. ³and ³^ ³ -³&apos. ³apostrophe ³' ³ -³&asterisk. ³asterisk ³* ³ -³&atsign. ³at sign ³@ ³ -³&bslash., &bsl. ³back slash ³\ ³ -³&caret. ³caret symbol ³^ ³ -³&cdq. ³close double quote ³" ³ -³&csq. ³close single quote ³' ³ -³&comma. ³comma ³, ³ -³&colon. ³colon ³: ³ -³&dash. ³dash ³- ³ -³°ree., °. ³degree ³ø ³ -³&dollar. ³dollar sign ³$ ³ -³&dot. ³dot ³ú ³ -³&darrow. ³down arrow ³ ³ -³&emdash. ³em dash ³- ³ -³&endash. ³en dash ³- ³ -³&eq., &equals., ³equal sign ³= ³ -³&eqsym. ³ ³ ³ -³&xclm., &xclam. ³exclamation point ³! ³ -³>sym., >. ³greater than ³> ³ -³&house. ³house ³ ³ -³&hyphen. ³hyphen ³- ³ -³&larrow. ³left arrow ³ ³ -³&lahead. ³left arrowhead ³ ³ -³&lbrace., &lbrc. ³left brace ³{ ³ -³&lbracket. &lbrk. ³left bracket ³[ ³ -³&lpar. , &lparen. ³left parenthesis ³( ³ -³&mdash. ³em dash ³- ³ -³&minus. ³minus sign ³- ³ -³&ndash. ³en dash ³- ³ -³&numsign. ³number sign ³# ³ -³&odq. ³open double quote ³" ³ -³&osq. ³open single quote ³` ³ -³&percent. ³percent ³% ³ -³&per. ³period ³. ³ -³&plus. ³plus sign ³+ ³ -³&rbrace., &rbrc. ³right brace ³} ³ -³&rbracket., &rbrk. ³right bracket ³] ³ -³&rpar., &rparen. ³right parenthesis ³) ³ -³&slash., &slr. ³slash ³/ ³ -³&splitvbar. ³split vertical bar ³| ³ -³ ³(piping symbol) ³ ³ -³&sqbul. ³square bullet ³þ ³ -³&tilde. ³tilde ³~ ³ -³&us. ³underscore ³_ ³ -*) - else - Result := Result + S[i]; - end; -end; - -Function TIPFWriter.StripTex(S : String) : String; - -var - I,L: Integer; - -begin - Result:=S; -// SetLength(Result, 0); -// for i := 1 to Length(S) do -// If not (S[i] in ['&','{','}','#','_','$','%','''','~','^', '\']) then -// Result := Result + S[i]; -end; - -procedure TIPFWriter.DescrWriteText(const AText: DOMString); - -begin - Write(EscapeTex(AText)); -end; - -procedure TIPFWriter.DescrBeginBold; -begin - Write(':hp2.'); -end; - -procedure TIPFWriter.DescrEndBold; -begin - WriteLn(':ehp2.'); -end; - -procedure TIPFWriter.DescrBeginItalic; -begin - Write(':hp1.'); -end; - -procedure TIPFWriter.DescrEndItalic; -begin - WriteLn(':ehp1.'); -end; - -procedure TIPFWriter.DescrBeginEmph; -begin - Write(':hp2.'); -end; - -procedure TIPFWriter.DescrEndEmph; -begin - Write(':ehp2.'); -end; - -procedure TIPFWriter.DescrWriteFileEl(const AText: DOMString); -begin - Write(':hp2.'); - DescrWriteText(AText); - Write(':ehp2.'); -end; - -procedure TIPFWriter.DescrWriteKeywordEl(const AText: DOMString); -begin - Write(':hp2.'); - DescrWriteText(AText); - Write(':ehp2.'); -end; - -procedure TIPFWriter.DescrWriteVarEl(const AText: DOMString); -begin - Write(':hp2.'); - DescrWriteText(AText); - Write(':ehp2.'); -end; - -procedure TIPFWriter.DescrBeginLink(const AId: DOMString); -var - i: Integer; -begin - FLink := Engine.ResolveLink(Module, AId); - While pos(':',flink)>0 do flink[pos(':',flink)]:='_'; -// System.WriteLn('Link "', AId, '" => ', FLink); - WriteF(':link reftype=hd refid=%s.', [flink]); -end; - -procedure TIPFWriter.DescrEndLink; -begin - Write(':elink.'); -end; - -procedure TIPFWriter.DescrWriteLinebreak; -begin - WriteLn('.br'); -end; - -procedure TIPFWriter.DescrBeginParagraph; -begin - WriteLn(':p.'); - // Do nothing -end; - -procedure TIPFWriter.DescrEndParagraph; -begin - WriteLn(''); - WriteLn(''); -end; - -procedure TIPFWriter.DescrBeginCode(HasBorder: Boolean; - const AHighlighterName: String); -begin - StartListing(HasBorder); -end; - -procedure TIPFWriter.DescrWriteCodeLine(const ALine: String); -begin - WriteLn(EscapeTex(ALine)); -end; - -procedure TIPFWriter.DescrEndCode; -begin - EndListing -end; - -procedure TIPFWriter.DescrBeginOrderedList; -begin - WriteLn(':ol.'); -end; - -procedure TIPFWriter.DescrEndOrderedList; -begin - WriteLn(':eol.'); -end; - -procedure TIPFWriter.DescrBeginUnorderedList; -begin - WriteLn(':ul.'); -end; - -procedure TIPFWriter.DescrEndUnorderedList; -begin - WriteLn(':eul.'); -end; - -procedure TIPFWriter.DescrBeginDefinitionList; -begin - WriteLn(':dl.'); -end; - -procedure TIPFWriter.DescrEndDefinitionList; -begin - WriteLn(':edl.'); -end; - -procedure TIPFWriter.DescrBeginListItem; -begin - Write(':li.'); -end; - -procedure TIPFWriter.DescrEndListItem; -begin - WriteLn(''); -end; - -procedure TIPFWriter.DescrBeginDefinitionTerm; -begin - Write(':li.'); -end; - -procedure TIPFWriter.DescrEndDefinitionTerm; -begin - WriteLn(''); -end; - -procedure TIPFWriter.DescrBeginDefinitionEntry; -begin - WriteLn(''); - // Do nothing -end; - -procedure TIPFWriter.DescrEndDefinitionEntry; -begin - WriteLn(''); -end; - -procedure TIPFWriter.DescrBeginSectionTitle; -begin - Write(':h3.'); -end; - -procedure TIPFWriter.DescrBeginSectionBody; -begin - WriteLn(''); -end; - -procedure TIPFWriter.DescrEndSection; -begin - WriteLn(''); - // Do noting -end; - -procedure TIPFWriter.DescrBeginRemark; -begin - WriteLn(':note.'); -end; - -procedure TIPFWriter.DescrEndRemark; -begin - WriteLn(''); -end; - -procedure TIPFWriter.DescrBeginTable(ColCount: Integer; HasBorder: Boolean); -begin - // !!!: How do we set the border? -// for i := 1 to ColCount do -// Write('l'); -// write('}{'); - TableCaptionWritten:=False; -end; - -procedure TIPFWriter.DescrEndTable; -begin - WriteLn(':etable.'); -end; - -procedure TIPFWriter.DescrBeginTableCaption; -begin - // Do nothing. -end; - -procedure TIPFWriter.DescrEndTableCaption; -begin - Write(''); -// Inc(FTableCount); -// Write(IntToStr(FTableCount)); -// Writeln('}'); - TableCaptionWritten := True; - Write(':table cols=''30 50''.'); -end; - -procedure TIPFWriter.DescrBeginTableHeadRow; -begin - if not TableCaptionWritten then - DescrEndTableCaption; - TableRowStartFlag := True; - WriteLn(':row.:c.'); -end; - -procedure TIPFWriter.DescrEndTableHeadRow; -begin - WriteLn(''); -end; - -procedure TIPFWriter.DescrBeginTableRow; -begin - if not TableCaptionWritten then - DescrEndTableCaption; - TableRowStartFlag := True; - WriteLn(':row.:c.'); -end; - -procedure TIPFWriter.DescrEndTableRow; -begin -end; - -procedure TIPFWriter.DescrBeginTableCell; -begin - if TableRowStartFlag then - TableRowStartFlag := False - else - WriteLn(':c.'); -end; - -procedure TIPFWriter.DescrEndTableCell; -begin - WriteLn(''); - // Do nothing -end; - - -function TIPFWriter.ConstValue(ConstDecl: TPasConst): String; -begin - if Assigned(ConstDecl) then - Result := ConstDecl.ClassName - else - Result := ''; -end; - -procedure TIPFWriter.WriteUnitOverview(ASection: TPasSection); -var - i: Integer; - UnitRef: TPasType; - DocNode: TDocNode; -begin - if ASection.UsesList.Count > 0 then - begin - WriteLnF(':h2.%s', [SDocUsedUnits]); - WriteLn(':ol.'); - for i := 0 to ASection.UsesList.Count - 1 do - begin - UnitRef := TPasType(ASection.UsesList[i]); - WriteLnF(':li.%s', [UnitRef.Name]); - end; - WriteLn(':eol.'); - end; - DocNode := Engine.FindDocNode(ASection.Parent); - if Assigned(DocNode) and not IsDescrNodeEmpty(DocNode.Descr) then - begin - WriteLnF(':h2.%s', [EscapeTex(SDocOverview)]); - WriteDescr(ASection.Parent, DocNode.Descr); - Writeln(''); - end; -end; - -procedure TIPFWriter.WriteResourceStrings(ASection: TPasSection); -var - ResStrDecl: TPasResString; - i: Integer; -begin - if ASection.ResStrings.Count > 0 then - begin - StartSubSection(SDocResStrings,ModuleName+'ResStrings'); - for i := 0 to ASection.ResStrings.Count - 1 do - begin - ResStrDecl := TPasResString(ASection.ResStrings[i]); - StartListing(false, ''); - Writeln(ResStrDecl.GetDeclaration(True)); - EndListing; - WriteLabel(ResStrDecl); - WriteIndex(ResStrDecl); - WriteDescr(ResStrDecl); - Writeln(''); - end; - end; -end; - -procedure TIPFWriter.WriteConsts(ASection: TPasSection); -var - i: Integer; - ConstDecl: TPasConst; -begin - if ASection.Consts.Count > 0 then - begin - WriteLnF(':h3 name=suse_%sconstants.%s', [EscapeTex(ModuleName), EscapeTex(SDocConstants)]); - for i := 0 to ASection.Consts.Count - 1 do - begin - ConstDecl := TPasConst(ASection.Consts[i]); - StartListing(False); - WriteLn(EscapeTex(ConstDecl.GetDeclaration(True))); - EndListing; -// WriteLabel(ConstDecl); -// WriteIndex(ConstDecl); - WriteDescr(ConstDecl); - end; - end; -end; - -procedure TIPFWriter.WriteEnumElements(TypeDecl : TPasEnumType); - -Var - EV : TPasEnumValue; - I : Integer; - DocNode : TDocNode; - -begin - With TypeDecl do - begin - SortElementList(Values); - DescrBeginTable(2,True); - DescrBeginTableCaption; - Writeln(EscapeTex(Format(SDocValuesForEnum,[TypeDecl.Name]))); - DescrEndTableCaption; - DescrBeginTableHeadRow; - DescrBeginTableCell; - Writeln(EscapeTex(SDocValue)); - DescrEndTableCell; - DescrBeginTableCell; - Writeln(EscapeTex(SDocExplanation)); - DescrEndTableCell; - DescrEndTableHeadRow; - For I:=0 to Values.Count-1 do - begin - EV:=TPasEnumValue(Values[i]); - DescrBeginTableRow; - DescrBeginTableCell; - Writeln(EscapeTex(EV.Name)); - DescrEndTableCell; - DescrBeginTableCell; - DocNode := Engine.FindDocNode(EV); - if Assigned(DocNode) and (not IsDescrNodeEmpty(DocNode.ShortDescr)) then - WriteDescr(EV,DocNode.ShortDescr); - DescrEndTableCell; - DescrEndTableRow; - end; - DescrEndTable; - end; -end; - -procedure TIPFWriter.WriteTypes(ASection: TPasSection); -var - i: Integer; - TypeDecl: TPasType; -begin - if ASection.Types.Count > 0 then - begin - StartSubSection(SDocTypes,ModuleName+'Types'); - for i := 0 to ASection.Types.Count - 1 do - begin - TypeDecl := TPasType(ASection.Types[i]); - WriteLn(':h4 name='+GetLabel(TypeDecl)+'.'); -// WriteLn(':hdref refid='+GetLabel(TypeDecl)+'.'); -// WriteLabel(TypeDecl); -// WriteIndex(TypeDecl); - StartListing(False); - Writeln(EscapeTex(TypeDecl.GetDeclaration(True))); - EndListing; - If TypeDecl is TPasEnumType then - begin - WriteENumElements(TypeDecl as TPasEnumType); - end; - WriteDescr(TypeDecl); - end; - end; -end; - -procedure TIPFWriter.WriteVars(ASection: TPasSection); -var - VarDecl: TPasVariable; - i: Integer; -begin - if ASection.Variables.Count > 0 then - begin - StartSubsection(SDocVariables,ModuleName+'Variables'); - for i := 0 to ASection.Variables.Count - 1 do - begin -// WriteIndex(VarDecl); - VarDecl := TPasVariable(ASection.Variables[i]); - WriteLn(':h4 name='+GetLabel(VarDecl)+'.'); - StartListing(False); - WriteLn(EscapeTex(VarDecl.GetDeclaration(True))); - EndListing; - WriteDescr(VarDecl); - end; - end; -end; - -procedure TIPFWriter.WriteVarsConstsTypes(ASection: TPasSection); -begin - With Asection do - if (Consts.Count > 0) or - (Types.Count > 0) or - (Variables.Count > 0) or - (ResStrings.Count>0) then - begin - StartSection(SDocConstsTypesVars, ModuleName+'ConstsTypesVars'); - WriteResourceStrings(ASection); - WriteConsts(ASection); - WriteTypes(ASection); - WriteVars(ASection); - end; -end; - -procedure TIPFWriter.WriteProcedure(ProcDecl : TPasProcedureBase); -var - DocNode: TDocNode; - OP : TPasOverloadedProc; - i : integer; -begin - With ProcDecl do - begin - if Not (Assigned(Parent) and Parent.InheritsFrom(TPasClassType)) then - begin - StartSubSection(Name, GetLabel(ProcDecl)); -// WriteLabel(ProcDecl); -// WriteIndex(ProcDecl); - end - else - begin // Parent assigned and hence method. - StartSubSection(Parent.Name+'&per.'+Name, GetLabel(ProcDecl)); -// WriteLabel(ProcDecl); -// WriteIndex(Parent.Name+'.'+Name); - end; -// Writeln('\begin{FPCList}'); - DocNode := Engine.FindDocNode(ProcDecl); - if Assigned(DocNode) and Assigned(DocNode.ShortDescr) then - begin - Writeln(':hp2.Synopsis:ehp2.&colon. '); - WriteDescr(ProcDecl, DocNode.ShortDescr); - WriteLn(''); - WriteLn('.br'); - end; - Writeln(':hp2.Declaration:ehp2.&colon. '); - StartListing(False); - if ClassType = TPasOverloadedProc then - begin - OP:=TPasOverloadedProc(ProcDecl); - for i := 0 to OP.Overloads.Count - 1 do - begin - WriteLn(TPasProcedure(OP.Overloads[i]).GetDeclaration(True)); - end; - end - else - WriteLn(GetDeclaration(True)); - EndListing; - WriteLn(''); - WriteLn('.br'); - If Assigned(Parent) then - begin - Writeln(':hp2.Visibility:ehp2.&colon. '); - Writeln(VisibilityNames[Visibility]); - WriteLn(''); - WriteLn('.br'); - end; - if Assigned(DocNode) and Assigned(DocNode.Descr) then - begin - Writeln(':hp2.Description:ehp2.&colon. '); - WriteDescr(ProcDecl); - WriteLn(''); - WriteLn('.br'); - end; - if Assigned(DocNode) and Assigned(DocNode.ErrorsDoc) then - begin - Writeln(':hp2.Errors:ehp2.&colon.'); - WriteDescr(ProcDecl, DocNode.ErrorsDoc); - WriteLn(''); - WriteLn('.br'); - end; - WriteSeeAlso(DocNode); - WriteLn(''); - WriteLn('.br'); -// Writeln('\end{FPCList}'); - WriteExample(DocNode); - end; -end; - -procedure TIPFWriter.WriteFunctionsAndProcedures(ASection: TPasSection); -var - i: Integer; -begin - if ASection.Functions.Count > 0 then - begin - StartSection(SDocProceduresAndFunctions,ModuleName+'Functions'); - for i := 0 to ASection.Functions.Count - 1 do - WriteProcedure(TPasProcedureBase(ASection.Functions[i])); - end; -end; - -procedure TIPFWriter.WriteExample(ADocNode: TDocNode); -var - Example: TDOMElement; -begin - if Assigned(ADocNode) then - begin - Example := ADocNode.FirstExample; - while Assigned(Example) do - begin - WritelnF(':xmp.%s:exmp.', [EscapeTex(Engine.GetExampleFileName(Example))]); - if Assigned(Example.NextSibling) then - WriteLn(''); - Example := TDomElement(Example.NextSibling); - end; - end; -end; - -procedure TIPFWriter.WriteSeeAlso(ADocNode: TDocNode); -var - Node: TDOMNode; - s: String; -begin - if Assigned(ADocNode) and Assigned(ADocNode.SeeAlso) and - Assigned(ADocNode.SeeAlso.FirstChild) then - begin - Writeln(':hp2.SeeAlso:ehp2.'); - Node := ADocNode.SeeAlso.FirstChild; - while Assigned(Node) do - begin - if (Node.NodeType = ELEMENT_NODE) and - (Node.NodeName = 'link') then - begin - S:=TDomElement(Node)['id']; - DescrBeginLink(S); - Writeln(S); - DescrEndLink(); - if Assigned(Node.NextSibling) Then - Writeln(','); - end; - Node:=Node.NextSibling; - end; - end; -end; - -procedure TIPFWriter.WriteClasses(ASection: TPasSection); -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 TIPFWriter.ProcessSection(ASection: TPasSection); -begin - With ASection do - begin - SortElementList(UsesList); - SortElementList(Declarations); - SortElementList(ResStrings); - SortElementList(Types); - SortElementList(Consts); - SortElementList(Classes); - SortElementList(Functions); - SortElementList(Variables); - end; - WriteUnitOverView(ASection); - WriteVarsConstsTypes(ASection); - WriteFunctionsAndProcedures(ASection); - WriteClasses(ASection); -end; - -Function TIPFWriter.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 TIPFWriter.WriteClassMethodOverview(ClassDecl : TPasClassType); -var - Member: TPasElement; - i: Integer; - DocNode: TDocNode; - List : TStringList; - -begin - List:=TStringList.Create; - Try - List.Sorted:=True; - for i := 0 to ClassDecl.Members.Count - 1 do - begin - Member := TPasElement(ClassDecl.Members[i]); - With Member do - if InheritsFrom(TPasProcedureBase) and ShowMember(Member) then - List.AddObject(Member.Name,Member); - end; - If List.Count>0 then - begin - StartSubSection(SDocMethodOverview, GetLabel(ClassDecl) + ':Methods'); -// WriteLabel(); - WriteLn(':parml.'); -// WriteLnF('%s & %s & %s \\ \hline', [EscapeTex(SDocPage), EscapeTex(SDocMethod), EscapeTex(SDocDescription)]); - For I:=0 to List.Count-1 do - begin - Member:=TPasElement(List.Objects[i]); - DocNode := Engine.FindDocNode(Member); - WriteF(':pt.:link reftype=hd refid=%s.%s:elink.:pd.',[StripTex(GetLabel(Member)), EscapeTex(Member.Name)]); - if Assigned(DocNode) and Assigned(DocNode.ShortDescr) then - WriteDescr(Member, DocNode.ShortDescr); - WriteLn(''); - WriteLn('.br'); - end; - WriteLn(':eparml.'); -// WriteLn('\end{tabularx}'); - end; - Finally - List.Free; - end; -end; - -procedure TIPFWriter.WriteClassPropertyOverview(ClassDecl : TPasClassType); -var - Member: TPasElement; - i: Integer; - s: String; - DocNode: TDocNode; - List : TStringList; - -begin - // Write property overview - List:=TStringList.Create; - Try - List.Sorted:=True; - for i := 0 to ClassDecl.Members.Count - 1 do - begin - Member := TPasElement(ClassDecl.Members[i]); - With Member do - if InheritsFrom(TPasProperty) and SHowMember(Member) then - List.AddObject(Member.Name,Member) - end; - If (List.Count>0) then - begin - StartSubSection(SDocPropertyOverview, GetLabel(ClassDecl) + ':Properties'); -// WriteLabel(GetLabel(ClassDecl) + ':Properties'); - WriteLn(':parml.'); -// WriteLn('\begin{tabularx}{\textwidth}{lllX}'); -// WriteLnF('%s & %s & %s & %s \\ \hline', -// [EscapeTex(SDocPage), EscapeTex(SDocProperty), EscapeTex(SDocAccess), EscapeTex(SDocDescription)]); - For I:=0 to List.Count-1 do - begin - Member:=TPasElement(List.objects[i]); - WriteF(':pt.:link reftype=hd refid=%s.%s:elink.:pd.',[StripTex(GetLabel(Member)), EscapeTex(Member.Name)]); - setlength(S,0); - if Length(TPasProperty(Member).ReadAccessorName) > 0 then - s := s + 'r'; - if Length(TPasProperty(Member).WriteAccessorName) > 0 then - s := s + 'w'; - if Length(TPasProperty(Member).StoredAccessorName) > 0 then - s := s + 's'; -// Write(s + ' & '); - DocNode := Engine.FindDocNode(Member); - if Assigned(DocNode) and Assigned(DocNode.ShortDescr) then - WriteDescr(Member, DocNode.ShortDescr); - WriteLn(''); - WriteLn('.br'); - end; - WriteLn(':eparml.'); - end; - Finally - List.Free; - end; -end; - - -procedure TIPFWriter.WriteClassDecl(ClassDecl: TPasClassType); -var - DocNode: TDocNode; - Vis: TPasMemberVisibilities; - Member: TPasElement; - i: Integer; -begin - StartSection(ClassDecl.Name, GetLabel(ClassDecl)); -// WriteLabel(ClassDecl); -// WriteIndex(ClassDecl); - DocNode := Engine.FindDocNode(ClassDecl); - if Assigned(DocNode) and ((not IsDescrNodeEmpty(DocNode.Descr)) or - (not IsDescrNodeEmpty(DocNode.ShortDescr))) then - begin -// StartSubSection(SDocDescription, GetLabel(ClassDecl) + ':Description'); - WriteDescr(ClassDecl); - end; - - // Write method overview - WriteClassMethodOverView(ClassDecl); - // Write Property Overview; - WriteClassPropertyOverView(ClassDecl); - - // Write method & property descriptions - - // Determine visibilities - - Vis := AllVisibilities; - if Engine.HidePrivate then - Exclude(Vis,visPrivate); - if Engine.HideProtected then - Exclude(Vis,visProtected); - - for i := 0 to ClassDecl.Members.Count - 1 do - begin - Member := TPasElement(ClassDecl.Members[i]); - if ((Member.InheritsFrom(TPasProcedureBase)) and - (Member.Visibility in Vis)) then - WriteProcedure(TPasProcedureBase(Member)); - end; - - // properties. - - for i := 0 to ClassDecl.Members.Count - 1 do - begin - Member := TPasElement(ClassDecl.Members[i]); - if ((Member.InheritsFrom(TPasProperty)) and - (Member.Visibility in Vis)) then - WriteProperty(TPasProperty(Member)); - end; - -end; - -procedure TIPFWriter.WriteProperty(PropDecl : TPasProperty); -var - DocNode: TDocNode; - S: String; -begin - With PropDecl do - begin - StartSubSection(Parent.Name+'&per.'+Name, GetLabel(PropDecl)); -// WriteLabel(PropDecl); -// WriteIndex(Parent.Name+'.'+Name); -// Writeln('\begin{FPCList}'); - DocNode := Engine.FindDocNode(PropDecl); - if Assigned(DocNode) and Assigned(DocNode.ShortDescr) then - begin - Writeln(':hp2.Synopsis:ehp2.&colon. '); - WriteDescr(PropDecl, DocNode.ShortDescr); - WriteLn(''); - WriteLn('.br'); - end; - Writeln(':hp2.Declaration:ehp2.&colon. '); - StartListing(False); - WriteLn('Property '+GetDeclaration(True)); - EndListing; - WriteLn(''); - WriteLn('.br'); - If Assigned(Parent) then - begin - Writeln(':hp2.Visibility:ehp2.&colon. '); - Writeln(VisibilityNames[Visibility]); - WriteLn(''); - WriteLn('.br'); - end; - Writeln(':hp2.Access:ehp2.&colon.'); - Setlength(S,0); - If Length(ReadAccessorName) > 0 then - S:='Read'; - if Length(WriteAccessorName) > 0 then - begin - If S<>'' then - S:=S+','; - S:=S+'Write'; - end; - Writeln(S); - WriteLn(''); - WriteLn('.br'); - if Assigned(DocNode) and Assigned(DocNode.Descr) then - begin - Writeln(':hp2.Description:ehp2.&colon.'); - WriteDescr(PropDecl); - WriteLn(''); - WriteLn('.br'); - end; - if Assigned(DocNode) and Assigned(DocNode.ErrorsDoc) then - begin - Writeln(':hp2.Errors:ehp2.&colon. '); - WriteDescr(PropDecl, DocNode.ErrorsDoc); - WriteLn(''); - WriteLn('.br'); - end; - WriteSeeAlso(DocNode); - WriteLn(''); - WriteLn('.br'); -// Writeln('\end{FPCList}'); - WriteExample(DocNode); - end; -end; - -Function CompareElements(P1,P2 : Pointer) : Integer; - -begin - Result:=CompareText(TPasElement(P1).Name,TPasElement(P2).Name); -end; - -procedure TIPFWriter.SortElementList(List : TList); - -begin - List.Sort(@CompareElements) -end; - - -procedure TIPFWriter.WriteLabel(El: TPasElement); -begin - WriteLabel(GetLabel(El)); -end; - -procedure TIPFWriter.WriteLabel(const s: String); -var - x: String; -begin - X:=s; - While pos(':',x)>0 do x[pos(':',x)]:='_'; - WriteF('%s', [LowerCase(StripTex(x))]); -end; - -procedure TIPFWriter.WriteIndex(El : TPasElement); -begin - WriteIndex(El.Name); -end; - -procedure TIPFWriter.WriteIndex(const s : String); -begin -// Write('\index{'); -// Write(EscapeTex(s)); -// Writeln('}'); -end; - -procedure TIPFWriter.StartListing(Frames: Boolean; const name: String); -begin - Writeln(':xmp.') -end; - -procedure TIPFWriter.StartListing(Frames : Boolean); -begin - StartListing(Frames,''); -end; - -procedure TIPFWriter.EndListing; -begin - Writeln(':exmp.') -end; - -procedure TIPFWriter.WriteCommentLine; -const - CommentLine = - '.* %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%'; -begin - WriteLn(''); - Writeln(CommentLine); -end; - -procedure TIPFWriter.WriteComment(Comment : String); -begin -// Write('.* '); -// Writeln(Comment); -end; - - -procedure TIPFWriter.StartSection(SectionName : String; SectionLabel : String); -begin -// StartSection(SectionName); - WriteCommentLine; - WriteComment(SectionName); - Write(':h2 name='); - WriteLabel(SectionLabel); - WriteLn('.'+EscapeTex(SectionName)); -end; - -//procedure TIPFWriter.StartSection(SectionName : String); -//begin -//end; - -procedure TIPFWriter.StartSubSection(SubSectionName : String; SubSectionLabel : String); -begin - Writeln(''); - WriteComment(SubsectionName); - Write(':h3 name='); - WriteLabel(SubsectionLabel); - WriteLn('.'+{EscapeTex(}SubSectionName{)}); -end; - -//procedure TIPFWriter.StartSubSection(SubSectionName : String); -//begin -//end; - -procedure TIPFWriter.StartChapter(ChapterName : String; ChapterLabel : String); -begin - StartChapter(ChapterName); - WriteLabel(ChapterLabel); -end; - -procedure TIPFWriter.StartChapter(ChapterName : String); -begin - Writeln(''); - WriteCommentLine; - WriteComment(ChapterName); - WriteCommentLine; - Writeln(':h1.'+{EscapeTex(}ChapterName{)}); -end; - - - -initialization - // Do not localize. - RegisterWriter(TIPFWriter,'ipf','IPF output.'); -finalization - UnRegisterWriter('ipf'); -end. diff --git a/utils/fpdoc/dw_ipflin.pas b/utils/fpdoc/dw_ipflin.pas new file mode 100644 index 0000000000..76b7758683 --- /dev/null +++ b/utils/fpdoc/dw_ipflin.pas @@ -0,0 +1,1010 @@ +{ + FPDoc IPF Writer + Copyright (c) 2010 by Graeme Geldenhuys (graemeg@gmail.com) + + * Linear IPF output for use with fpGUI or OS/2's help systems. + + See the file COPYING, included in this distribution, + for details about the copyright. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +} +unit dw_ipflin; + +{$mode objfpc}{$H+} + +interface + +uses + Classes, DOM, dGlobals, PasTree, dwLinear; + +const + { Change this into the name of your writer} + IPFWriterName = 'ipf'; + { Comprehensible description goes here:} + SIPFUsageWriterDescr = 'Writes output in fpGUI and OS/2''s IPF help format'; + { Extension for the template } + TIPFExtension = '.ipf'; + +type + TIPFNewWriter = class(TLinearWriter) + private + InPackageOverview: Boolean; + InHeading: Boolean; + FInHeadingText: string; + OrderedList: boolean; + TableRowStartFlag: Boolean; + TableCaptionWritten: Boolean; + InTableCell: Boolean; + InTypesDeclaration: Boolean; + SuspendWriting: Boolean; + LastSubSection: String; + protected + FLink: String; + FTableCount : Integer; + FInVerbatim : Boolean; + Inlist, + fColCount: integer; + // extras + procedure Write(const s: String); override; + procedure WriteBeginDocument; override; + procedure WriteEndDocument; override; + // Linear documentation methods overrides; + procedure WriteLabel(Const S : String); override; + procedure WriteIndex(Const S : String); override; + procedure WriteType(const s: string); override; + procedure WriteVariable(const s: string); override; + procedure WriteConstant(const s: string); override; + Procedure WriteExampleFile(FN : String); override; + Procedure StartProcedure; override; + Procedure EndProcedure; override; + Procedure StartProperty; override; + Procedure EndProperty; override; + Procedure StartSynopsis; override; + Procedure StartDeclaration; override; + Procedure StartVisibility; override; + Procedure StartDescription; override; + Procedure StartAccess; override; + Procedure StartErrors; override; + Procedure StartVersion; override; + Procedure StartSeealso; override; + Procedure EndSeealso; override; + procedure StartUnitOverview(AModuleName,AModuleLabel : String);override; + procedure WriteUnitEntry(UnitRef : TPasType); override; + Procedure EndUnitOverview; override; + function GetLabel(AElement: TPasElement): String; override; + procedure StartListing(Frames: Boolean; const name: String); override; + procedure EndListing; override; + Function EscapeText(S : String) : String; override; + Function StripText(S : String) : String; override; + procedure WriteCommentLine; override; + procedure WriteComment(Comment : String);override; + procedure StartSection(SectionName : String);override; + procedure StartSubSection(SubSectionName : String);override; + procedure StartSubSubSection(SubSubSectionName : String);override; + procedure StartChapter(ChapterName : String); override; + procedure StartOverview(WithAccess : Boolean); override; + procedure EndOverview; override; + procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override; + procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override; + class function FileNameExtension: string; override; + procedure DescrBeginURL(const AURL: DOMString); override; + procedure DescrEndURL; override; + // Description node conversion. Overrides for TFPDocWriter. + procedure DescrBeginBold; override; + procedure DescrEndBold; override; + procedure DescrBeginItalic; override; + procedure DescrEndItalic; override; + procedure DescrBeginEmph; override; + procedure DescrEndEmph; override; + procedure DescrWriteText(const AText: DOMString); override; + procedure DescrWriteFileEl(const AText: DOMString); override; + procedure DescrWriteKeywordEl(const AText: DOMString); override; + procedure DescrWriteVarEl(const AText: DOMString); override; + procedure DescrBeginLink(const AId: DOMString); override; + procedure DescrEndLink; override; + procedure DescrWriteLinebreak; override; + procedure DescrBeginParagraph; override; + procedure DescrBeginCode(HasBorder: Boolean; const AHighlighterName: String); override; + procedure DescrWriteCodeLine(const ALine: String); override; + procedure DescrEndCode; override; + procedure DescrEndParagraph; override; + procedure DescrBeginOrderedList; override; + procedure DescrEndOrderedList; override; + procedure DescrBeginUnorderedList; override; + procedure DescrEndUnorderedList; override; + procedure DescrBeginDefinitionList; override; + procedure DescrEndDefinitionList; override; + procedure DescrBeginListItem; override; + procedure DescrEndListItem; override; + procedure DescrBeginDefinitionTerm; override; + procedure DescrEndDefinitionTerm; override; + procedure DescrBeginDefinitionEntry; override; + procedure DescrEndDefinitionEntry; override; + procedure DescrBeginSectionTitle; override; + procedure DescrBeginSectionBody; override; + procedure DescrEndSection; override; + procedure DescrBeginRemark; override; + procedure DescrEndRemark; override; + procedure DescrBeginTable(ColCount: Integer; HasBorder: Boolean); override; + procedure DescrEndTable; override; + procedure DescrBeginTableCaption; override; + procedure DescrEndTableCaption; override; + procedure DescrBeginTableHeadRow; override; + procedure DescrEndTableHeadRow; override; + procedure DescrBeginTableRow; override; + procedure DescrEndTableRow; override; + procedure DescrBeginTableCell; override; + procedure DescrEndTableCell; override; + // TFPDocWriter class methods + public + constructor Create(APackage: TPasPackage; AEngine: TFPDocEngine); override; + end; + + + +implementation + +uses + SysUtils, dwriter; + + +{ TFPDocWriter overrides } + + +procedure TIPFNewWriter.DescrBeginBold; +begin + { Start bold output } + WriteLn(':hp2.'); +end; + +procedure TIPFNewWriter.DescrEndBold; +begin + { End bold output } + WriteLn(':ehp2.'); +end; + +procedure TIPFNewWriter.DescrBeginItalic; +begin + { Start italic output } + WriteLn(':hp1.'); +end; + +procedure TIPFNewWriter.DescrEndItalic; +begin + { End italic output } + WriteLn(':ehp1.'); +end; + +procedure TIPFNewWriter.DescrBeginEmph; +begin + { Start emphasized output } + Write(':hp1.'); +end; + +procedure TIPFNewWriter.DescrEndEmph; +begin + { End emphasized output } + Write(':ehp1.'); +end; + +procedure TIPFNewWriter.DescrWriteText(const AText: DOMString); +const + cMax = 100; +var + sl: TStringlist; + ns: string; + i: integer; + lText: string; +begin + // IPF has an imposed line length limit. + if (Length(AText) > cMax) then // then we need to wrap the text. + begin + lText := WrapText(AText, LineEnding, [' ', '-', #9], cMax); + sl := TStringlist.Create; + try + sl.Text := lText; + for i := 0 to sl.Count-1 do + inherited DescrWriteText(sl.Strings[i] + LineEnding); + finally + sl.Free; + end; + end + else + inherited DescrWriteText(AText); +end; + +procedure TIPFNewWriter.DescrWriteFileEl(const AText: DOMString); +begin + { format as file name } + Write(':hp3.'); + DescrWriteText(AText); + Write(':ehp3.'); +end; + +procedure TIPFNewWriter.DescrWriteKeywordEl(const AText: DOMString); +begin + { Format as keyword } + Write(':hp1.'); + DescrWriteText(AText); + Write(':ehp1.'); +end; + +procedure TIPFNewWriter.DescrWriteVarEl(const AText: DOMString); +begin + { Format as variable } + Write(':hp1.'); + DescrWriteText(AText); + Write(':ehp1.'); +end; + +procedure TIPFNewWriter.DescrBeginLink(const AId: DOMString); +begin + { Start link to label ID - links are never nested.} + FLink := Engine.ResolveLink(Module, AId); + FLink := StringReplace(FLink, ':', '_', [rfReplaceAll]); + FLink := StringReplace(FLink, '.', '_', [rfReplaceAll]); + WriteF(':link reftype=hd refid=%s.', [flink]); +end; + +procedure TIPFNewWriter.DescrEndLink; +begin + { End link to label ID} + Write(':elink.'); +end; + +procedure TIPFNewWriter.DescrWriteLinebreak; +begin + { Start a new line. } + WriteLn(''); + WriteLn('.br'); // must be at the beginning of a line, hence the previous writeln call +end; + +procedure TIPFNewWriter.DescrBeginParagraph; +begin + { Start a new paragraph } + Writeln(':p.'); +end; + +procedure TIPFNewWriter.DescrEndParagraph; +begin + { End current paragraph } + writeln(''); +end; + +procedure TIPFNewWriter.DescrBeginCode(HasBorder: Boolean; + const AHighlighterName: String); +begin + { Start block of code } + StartListing(HasBorder,''); +end; + +procedure TIPFNewWriter.DescrWriteCodeLine(const ALine: String); +begin + { Write line of code } + DescrWriteText(ALine + LineEnding); +// writeln(EscapeText(ALine)); +end; + +procedure TIPFNewWriter.DescrEndCode; +begin + { End block of code } + EndListing; +end; + +procedure TIPFNewWriter.DescrBeginOrderedList; +begin + { Start numbered list } + OrderedList := True; + writeln(''); + writeln(':ol.'); +end; + +procedure TIPFNewWriter.DescrEndOrderedList; +begin + { End numbered list } + writeln(''); + writeln(':eol.'); +// writeln(':p.'); +end; + +procedure TIPFNewWriter.DescrBeginUnorderedList; +begin + { Start bulleted list } + OrderedList := False; + writeln(''); + if not InTableCell then + writeln(':ul.') + else + writeln(':lines.'); +end; + +procedure TIPFNewWriter.DescrEndUnorderedList; +begin + { End bulleted list } + writeln(''); + if not InTableCell then + writeln(':eul.') + else + writeln(':elines.'); +end; + +procedure TIPFNewWriter.DescrBeginDefinitionList; +begin + { Start definition list } + writeln(''); + writeln(':dl tsize=25 compact.'); +end; + +procedure TIPFNewWriter.DescrEndDefinitionList; +begin + { End definition list } + writeln(''); + writeln(':edl.'); +// writeln(':p.'); +end; + +procedure TIPFNewWriter.DescrBeginListItem; +begin + { Start list item (both bulleted/numbered) } + if not InTableCell then + write(':li.'); +end; + +procedure TIPFNewWriter.DescrEndListItem; +begin + { End list item (both bulleted/numbered) } + writeln(''); +end; + +procedure TIPFNewWriter.DescrBeginDefinitionTerm; +begin + { Start definition term } + writeln(':dt.'); +end; + +procedure TIPFNewWriter.DescrEndDefinitionTerm; +begin + { End definition term } + writeln(''); +end; + +procedure TIPFNewWriter.DescrBeginDefinitionEntry; +begin + { start definition explanation } + writeln(':dd.'); +end; + +procedure TIPFNewWriter.DescrEndDefinitionEntry; +begin + { End definition explanation } + writeln(''); +end; + +procedure TIPFNewWriter.DescrBeginSectionTitle; +begin + { Start section title } +end; + +procedure TIPFNewWriter.DescrBeginSectionBody; +begin + { Start section body } +end; + +procedure TIPFNewWriter.DescrEndSection; +begin + { End section body } +end; + +procedure TIPFNewWriter.DescrBeginRemark; +begin + { Start remark paragraph } + writeln(''); + writeln(':nt text=''Remark: ''.'); +end; + +procedure TIPFNewWriter.DescrEndRemark; +begin + { End remark paragraph } + writeln(''); + writeln(':ent.'); +end; + +procedure TIPFNewWriter.DescrBeginTable(ColCount: Integer; HasBorder: Boolean); +var + i: integer; + cols: string; + f: string; +begin + { Start table with ColCount columns, and with border } + cols := ''; + for i := 0 to ColCount-1 do + begin + if i = 0 then + cols := cols + '35 ' // first colum is 30 characters + else + cols := cols + '50 '; // every other colum is 50 characters each + end; + if HasBorder then + f := ' frame=box.' + else + f := ' frame=none.'; + writeln(':table cols=''' + Trim(cols) + ''' rules=both' + f); +end; + +procedure TIPFNewWriter.DescrEndTable; +begin + writeln(':etable.'); +end; + +procedure TIPFNewWriter.DescrBeginTableCaption; +begin + //writeln('.* GG'); + SuspendWriting := True; + // do nothing +// TableCaptionWritten := False; +end; + +procedure TIPFNewWriter.DescrEndTableCaption; +begin + // do nothing + SuspendWriting := False; + writeln(''); +end; + +procedure TIPFNewWriter.DescrBeginTableHeadRow; +begin +// TableCaptionWritten := True; + SuspendWriting := False; + writeln(':row.'); +end; + +procedure TIPFNewWriter.DescrEndTableHeadRow; +begin + // do nothing +end; + +procedure TIPFNewWriter.DescrBeginTableRow; +begin +// TableCaptionWritten := True; + SuspendWriting := False; + writeln(':row.'); +end; + +procedure TIPFNewWriter.DescrEndTableRow; +begin + writeln(''); +end; + +procedure TIPFNewWriter.DescrBeginTableCell; +begin + write(':c.'); + InTableCell := True; +end; + +procedure TIPFNewWriter.DescrEndTableCell; +begin + // do nothing + writeln(''); + InTableCell := False; +end; + +constructor TIPFNewWriter.Create(APackage: TPasPackage; AEngine: TFPDocEngine); +begin + inherited Create(APackage, AEngine); + TableCaptionWritten := True; + SuspendWriting := False; + InTableCell := False; + InTypesDeclaration := False; +end; + +{ TLinearWriter overrides} + +class function TIPFNewWriter.FileNameExtension: String; +begin + Result := TIPFExtension; +end; + +procedure TIPFNewWriter.DescrBeginURL(const AURL: DOMString); +begin + //Write(EscapeText(AURL)); +end; + +procedure TIPFNewWriter.DescrEndURL; +begin + // do nothing +end; + +function TIPFNewWriter.GetLabel(AElement: TPasElement): String; +var + i: Integer; +begin + if AElement.ClassType = TPasUnresolvedTypeRef then + Result := Engine.ResolveLink(Module, AElement.Name) + else + begin + Result := AElement.PathName; + Result := LowerCase(Copy(Result, 2, Length(Result) - 1)); // Remove # infront of eg: '#Corelib' string + end; + Result := StringReplace(Result, '.', '_', [rfReplaceAll]); + Result := StringReplace(Result, ' ', '_', [rfReplaceAll]); +end; + +Function TIPFNewWriter.EscapeText(S : String) : String; +var + i: Integer; +begin + SetLength(Result, 0); + for i := 1 to Length(S) do + case S[i] of + '.': // Escape these characters + Result := Result + '&per.'; + ':': + Result := Result + '&colon.'; + ',': + Result := Result + '&comma.'; + '&': + Result := Result + '&.'; +// '_': +// Result := Result + '&us.'; + '^': + Result := Result + '&caret.'; + '''': + Result := Result + '&apos.'; + '*': + Result := Result + '&asterisk.'; + '@': + Result := Result + '&atsign.'; + '\': + Result := Result + '&bslash.'; + '"': + Result := Result + '&cdq.'; + '-': + Result := Result + '&hyphen.'; + //'°': + // Result := Result + '°ree.'; + '$': + Result := Result + '&dollar.'; + '=': + Result := Result + '&eq.'; + '!': + Result := Result + '&xclam.'; + '>': + Result := Result + '>.'; + '(': + Result := Result + '&lpar.'; + ')': + Result := Result + '&rpar.'; + '+': + Result := Result + '&plus.'; + '[': + Result := Result + '&lbracket.'; + ']': + Result := Result + '&rbracket.'; + else + Result := Result + S[i]; + end; +end; + +Function TIPFNewWriter.StripText(S : String) : String; +var + I,L: Integer; +begin + //Result := S; + SetLength(Result, 0); + for i := 1 to Length(S) do + if not (S[i] in ['&','{','}','#'{,'_'},'$','%','''','~','^', '\', ' ', '<', '>']) then + Result := Result + S[i]; +end; + +procedure TIPFNewWriter.Write(const s: String); +begin + if SuspendWriting then + Exit; + inherited Write(s); +end; + +procedure TIPFNewWriter.WriteBeginDocument; +begin + fColCount := 0; + Writeln(':userdoc.'); + WriteComment('This file has been created automatically by FPDoc'); + WriteComment('IPF output (c) 2010 by Graeme Geldenhuys (graemeg@gmail.com)'); + writeln(''); + Writeln(':docprof toc=12345.'); + WriteLn(':title.' + PackageName); + writeln(''); + writeln(''); + writeln(':h1.' + PackageName); + InPackageOverview := True; +// inherited WriteBeginDocument; +end; + +procedure TIPFNewWriter.WriteEndDocument; +begin + inherited WriteEndDocument; + writeln(''); + writeln(''); + writeln(':euserdoc.'); + writeln(''); +end; + +procedure TIPFNewWriter.WriteLabel(const s: String); +var + x: String; +begin + x := StringReplace(s, ':', '_', [rfReplaceAll]); + + if InHeading and (x <> '') then + begin + WriteLnF(FInHeadingText, [ ' name=' + LowerCase(x)]); // LowerCase(StripTexT(x))]); + Writeln(''); + FInHeadingText := ''; + InHeading := False; + end + else + begin + WriteLnF(FInHeadingText, [ '' ]); + Writeln(''); + FInHeadingText := ''; + InHeading := False; + end; +end; + +procedure TIPFNewWriter.WriteIndex(const s : String); +begin +// writeln(':i1 id=' + s + '.'); +end; + +procedure TIPFNewWriter.WriteType(const s: string); +begin + writeln(''); + Writeln('.* -------------------------------------------------'); + WriteLnF(':h5 name=%s.%s', [lowercase(PackageName+'_'+ModuleName+'_'+s), s]); +// inherited WriteType(s); +end; + +procedure TIPFNewWriter.WriteVariable(const s: string); +begin + writeln(''); + Writeln('.* -------------------------------------------------'); + WriteLnF(':h5 name=%s.%s', [lowercase(PackageName+'_'+ModuleName+'_'+s), s]); +end; + +procedure TIPFNewWriter.WriteConstant(const s: string); +begin + writeln(''); + Writeln('.* -------------------------------------------------'); + WriteLnF(':h5 name=%s.%s', [lowercase(PackageName+'_'+ModuleName+'_'+s), s]); +end; + +procedure TIPFNewWriter.StartListing(Frames: Boolean; const name: String); +begin +// writeln(''); + writeln(':xmp.'); +end; + +procedure TIPFNewWriter.EndListing; +begin + writeln(':exmp.'); +end; + +procedure TIPFNewWriter.WriteCommentLine; +begin + Writeln(''); + Writeln('.* %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%'); +end; + +procedure TIPFNewWriter.WriteComment(Comment : String); +begin + Writeln('.* ' + Comment); +end; + +procedure TIPFNewWriter.StartChapter(ChapterName : String); +begin + InHeading := True; + Writeln(''); + Writeln(''); + WriteCommentLine; + WriteComment('Chapter: ' + ChapterName); + WriteCommentLine; + FInHeadingText := ':h2%s. ' + ChapterName; + //Writeln(':h2.' + ChapterName); + //Writeln(''); +end; + +procedure TIPFNewWriter.StartSection(SectionName : String); +begin + InHeading := True; + Writeln(''); + Writeln(''); + WriteCommentLine; + WriteComment('Section: ' + SectionName); + WriteCommentLine; + writeln(''); + + if SameText(SectionName, SDocOverview) then + begin + writeln(':p.'); + writeln(':p.'); + writeln(':lm margin=1.'); + DescrBeginBold; + WriteLn(SDocOverview); + DescrEndBold; +// writeln(':lm margin=3.'); + writeln('.br'); + end; + + if InPackageOverview then + begin + FInHeadingText := ':h2%s. ' + SectionName; +// Writeln(':h2.' + SectionName); + InPackageOverview := False; + end + else + begin + FInHeadingText := ':h3%s. ' + SectionName; +// Writeln(':h3.' + SectionName); + end; +// Writeln(''); +end; + +procedure TIPFNewWriter.StartSubSection(SubSectionName : String); +begin + LastSubSection := Lowercase(SubSectionName); + InHeading := True; + Writeln(''); + WriteCommentLine; + FInHeadingText := ':h4%s. ' + SubSectionName; + //Writeln(':h4.' + SubSectionName); +end; + +procedure TIPFNewWriter.StartSubSubSection(SubSubSectionName : String); +begin + InHeading := True; + FInHeadingText := ':h5%s. ' + SubSubSectionName; + //Writeln(':h5.' + SubSubSectionName); +end; + +Procedure TIPFNewWriter.StartProcedure; +begin + //writeln(''); + //writeln(':ul.'); +end; + +Procedure TIPFNewWriter.EndProcedure; +begin + //writeln(''); + //writeln(':eul.'); +end; + +Procedure TIPFNewWriter.StartSynopsis; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocSynopsis + ':ehp2.'); + writeln('.br'); + writeln(':lm margin=3.'); +end; + +Procedure TIPFNewWriter.StartDeclaration; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocDeclaration + ':ehp2.'); + writeln(':lm margin=3.'); +end; + +Procedure TIPFNewWriter.StartVisibility; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocVisibility + ':ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); +end; + +Procedure TIPFNewWriter.StartDescription; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocDescription + ':ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); +end; + +Procedure TIPFNewWriter.StartErrors; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocErrors + ':ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); +end; + +procedure TIPFNewWriter.StartVersion; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocVersion +':ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); +end; + +Procedure TIPFNewWriter.StartAccess; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.' + SDocAccess + ':ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); +end; + +Procedure TIPFNewWriter.StartProperty; +begin + //writeln(''); + //Writeln('.* here I am'); + //writeln(':ul.'); +end; + +Procedure TIPFNewWriter.EndProperty; +begin + //writeln(''); + //writeln(':eul.'); +end; + +procedure TIPFNewWriter.WriteExampleFile(FN : String); +var + sl: TStringList; + i: integer; +begin + if (FN<>'') then + begin + writeln(''); + writeln(''); + Writeln(':p.'); + writeln(':lm margin=1.'); + Writeln(':hp2.Example:ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); + writeln('Filename&colon. :hp1.' + EscapeText(FN) + ':ehp1.'); + writeln(':p.'); + + writeln(':xmp.'); + //writeln(':im ' + FN); + sl := TStringList.Create; + try + sl.LoadFromFile(FN); + for i := 0 to sl.Count-1 do + Writeln(EscapeText(sl[i])); + finally + sl.Free; + end; + writeln(':exmp.'); + end; +end; + +procedure TIPFNewWriter.StartOverview(WithAccess : Boolean); +begin +{ + If With access then it is a property overview. + Otherwise it is a method/function overview. + If tabular output is generated, the preferred output order is: + With access: + Col 1 : Page reference + Col 2 : Property Name + Col 3 : Accessibility (r/w) + Col 4 : Description + Without access: + Col 1 : Page reference + Col 2 : Method name + Col 3 : Description + (See the two WriteOverviewMember functions) +} + writeln(''); + writeln(':parml tsize=30 break=none compact.'); +// FlushBuffer; +end; + +procedure TIPFNewWriter.EndOverview; +begin + { End of overview } + writeln(''); + writeln(':eparml.'); + writeln(':p.'); +// FlushBuffer; +end; + +procedure TIPFNewWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String); +var + s1, s2: string; +begin + { Write one entry in property overview: + ALabel : Label, as returned by GetLabel + AName : Property name + Access : Property acces (r/w/a) + Descr : Description + } + s1 := StringReplace(ALabel, ':', '_', [rfReplaceAll]); + s2 := StringReplace(AName, ':', '_', [rfReplaceAll]); + WriteLn(Format(':pt. :link reftype=hd refid=%s.%s:elink. [%s]',[s1, s2, Access])); + WriteLn(Format(':pd. %s', [ADescr])); +end; + +procedure TIPFNewWriter.WriteOverviewMember(const ALabel,AName,ADescr : String); +var + s1, s2: string; +begin + { Write one entry in method overview: + ALabel : Label, as returned by GetLabel + AName : Method name + Descr : Description + } + s1 := StringReplace(ALabel, ':', '_', [rfReplaceAll]); + s2 := StringReplace(AName, ':', '_', [rfReplaceAll]); + WriteLn(Format(':pt. :link reftype=hd refid=%s.%s :elink.',[s1, s2])); + WriteLn(Format(':pd. %s', [ADescr])); +end; + +Procedure TIPFNewWriter.StartSeeAlso; +begin + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + writeln(':hp2.See Also:ehp2.'); + writeln(':lm margin=3.'); + writeln('.br'); +end; + +procedure TIPFNewWriter.EndSeealso; +begin + writeln(''); +end; + +procedure TIPFNewWriter.StartUnitOverview(AModuleName,AModuleLabel : String); +begin + { Start of unit overview. + AModuleName : Name of current unit. + AModuleLabel : Label name of current unit. + } + writeln(''); + writeln(':p.'); + writeln(':lm margin=1.'); + DescrBeginBold; + writeln(EscapeText(Format(SDocUsedUnitsByUnitXY, [AModuleName]))); + DescrEndBold; + writeln(':lm margin=3.'); + writeln('.br'); + + writeln(':p.'); + writeln(':ol.'); +end; + +procedure TIPFNewWriter.WriteUnitEntry(UnitRef : TPasType); +begin + { Write one unit entry } + writeln(':li.' + EscapeText(UnitRef.Name)); +end; + +procedure TIPFNewWriter.EndUnitOverview; +begin + { end of unit overview } + writeln(':eol.'); +end; + + +initialization + // Do not localize IPFWriterName + RegisterWriter(TIPFNewWriter, IPFWriterName, SIPFUsageWriterDescr); +finalization + UnRegisterWriter(IPFWriterName); +end. diff --git a/utils/fpdoc/dw_latex.pp b/utils/fpdoc/dw_latex.pp index aee9c4c031..336f96d3f5 100644 --- a/utils/fpdoc/dw_latex.pp +++ b/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(ALabel,AName,ADescr : String); override; + procedure WriteOverviewMember(const ALabel,AName,Access,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]); diff --git a/utils/fpdoc/dw_linrtf.pp b/utils/fpdoc/dw_linrtf.pp index ff2fea434b..75222316e6 100644 --- a/utils/fpdoc/dw_linrtf.pp +++ b/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(ALabel,AName,ADescr : String); override; + procedure WriteOverviewMember(const ALabel,AName,Access,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]); diff --git a/utils/fpdoc/dw_txt.pp b/utils/fpdoc/dw_txt.pp index dc8ff1d194..17bc1a139b 100644 --- a/utils/fpdoc/dw_txt.pp +++ b/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(ALabel,AName,ADescr : String); override; + procedure WriteOverviewMember(const ALabel,AName,Access,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]); diff --git a/utils/fpdoc/dwlinear.pp b/utils/fpdoc/dwlinear.pp index 228a7ac4b6..b880c46019 100644 --- a/utils/fpdoc/dwlinear.pp +++ b/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 WriteLnF(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); 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(ALabel,AName,ADescr : String); virtual; Abstract; + procedure WriteOverviewMember(const ALabel,AName,Access,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 - S:=GetDescrString(Member, DocNode.ShortDescr) + 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(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 - Writeln(EscapeText(TypeDecl.GetDeclaration(True))); + else + 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; - WriteDescr(PropDecl, DocNode.ShortDescr); + lNode := Engine.FindLinkedNode(DocNode); + 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 - if Assigned(DocNode.Descr) then + begin + 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); - end - else + WriteExample(lNode); + end + 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. + diff --git a/utils/fpdoc/fpdoc.pp b/utils/fpdoc/fpdoc.pp index fa5da10dca..b7aa432980 100644 --- a/utils/fpdoc/fpdoc.pp +++ b/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