paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-04-21 01:29:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

+ Added unix man page output; Implemented usage

Browse Source
This commit is contained in:
michael 2005-01-14 17:55:07 +00:00
parent 1a729a00a3
commit 1630ecdcb0
8 changed files with 2046 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
utils/fpdoc/Makefile.fpc
View File

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

164
utils/fpdoc/dglobals.pp
View File

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

41
utils/fpdoc/dw_ipf.pp
View File

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

1798
utils/fpdoc/dw_man.pp Normal file
View File

File diff suppressed because it is too large Load Diff

9
utils/fpdoc/dw_txt.pp
View File

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

31
utils/fpdoc/dwlinear.pp
View File

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

70
utils/fpdoc/dwriter.pp
View File

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

61
utils/fpdoc/fpdoc.pp
View File

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