📄 uicbasehtmldoc.pas
字号:
{ JADD - Just Another DelphiDoc: Documentation from Delphi Source Code
Copyright (C) 2003-2008 Gerold Veith
This file is part of JADD - Just Another DelphiDoc.
DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.
DelphiDoc 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. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
}
unit UICBaseHTMLDoc;
{Contains the base class ~[linkClass TICBaseHTMLDoc] for documentation
generators to generate documentation about the parsed data in the HTML
format.
}
interface
uses Windows, Classes,
{$IFNDEF LINUX}
Graphics,
{$ELSE}
QGraphics,
{$ENDIF}
General,
UPascalConsts,
UBaseIdents,
UDiagram,
UOptions, UMakeDoc,
UDocumentationTexts,
UICDocumentDoc, UICCommentDoc,
UICNodes, UICBaseGeneratorVisitor,
UImages, UICGUIHelpData;
//the name of the Cascading Style-Sheets file to create and include
const CSSFileName = 'DelphiDoc.css';
//the base name (without extension) of the file used to redirect to
//topics based a help context
HelpContextRedirectBaseFileName = 'helpcontext';
//the base name (without extension) of the file used to redirect to
//topics based a help context and showing visual links in case that fails
HelpContextVisualRedirectBaseFileName = 'helpcontextvis';
//text to be replaced with the topic in the header of the HTML files
HeaderReplaceTitle = '<topic>';
//text to be replaced with the key words in the header of the HTML files
HeaderReplaceKeyWords = '<keywords>';
//text to be replaced with the path to the main directory of the
//documentation in the header of the HTML files
HeaderReplacePathToMain = '<mainpath>';
//text to be replaced with the object tag to register key words as used
//in CHM in the header of the HTML files
// HeaderReplaceKeyWordsTag = '<keywordstag>';
//text to be replaced with the character enconding of the HTML files
//in the header of the HTML files
HeaderReplaceCharacterEncoding = '<encoding>';
//the DTD of HTML files (the only true (portable/compatible) one
//(so far)!)
DTD_HTMLTrans_Text = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">';
//the DTD of XHTML files
DTD_XHTML_Text = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">';
//the default file extension for HTML files
FileExtension_HTML = '.html';
//the file extension for XHTML files
// FileExtension_XHTML = '.xhtml';
//the (additional) text to end empty HTML tags for XHTML
EmptyTagEnd: array[Boolean] of String = ('', ' /');
//format for images to be prefixed with to create unique file names
ImageSavePrefix = 'Img%d_';
type
{ * * * *** * * * *** TICHTMLVisitor *** * * * *** * * * }
//the base generator for documentation in the HTML format
TICBaseHTMLDoc = class;
//the format to be used to save diagrams in for the HTML documentation
THTMLDiagramFormat = (
dfPNG, //save diagrams as Portable Network Graphics
dfSVG, //save diagrams as Scalable Vector Graphics
//save diagrams as compressed Scalable Vector Graphics
dfSVGz);
{A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the
generators deriving from ~[linkClass TICBaseHTMLDoc] to write the COM to a
file in the HTML-format. They use this class as a base class for only
slightly modified visitors. }
TICHTMLVisitor = class(TICBaseGeneratorVisitor)
private
//the format to be used to save diagrams in
FDiagramsFormat: THTMLDiagramFormat;
//whether SVG images of diagrams should themselved contain the links instead
//via an image map
FSVGDiagramsWithLinks: Boolean;
//Returns the URI of the class or file of each box in a diagram.
function GetDiagramLinkTarget(TheClass: TRecordType;
TheFile: TPascalFile): String;
protected
//the HTML file to write the nodes to
FHTMLFile: TBufferStream;
//the generator for which the COM should be written in HTML
FGenerator: TICBaseHTMLDoc;
//Draws the created diagram on a bitmap and writes it with the generator.
procedure DrawDiagram(Diagram: TDiagram; DiagramIndex: Integer); override;
//Writes the created diagram.
procedure WriteDiagram(const DiagramCode: String;
ImageSize: TPoint); override;
//Called for each manual link to an identifier or file with a not empty
//text.
procedure LinkIdentifierWithText(Node: TICNLinkIdentifier); override;
//Ends the current line and starts a new one.
procedure EndLine;
//Ends the current paragraph and starts a new one.
procedure EndParagraph;
//Writes the localized version of the text.
procedure Localize(Text: TDocumentationTexts);
//Writes some text while encoding special characters in the HTML file.
procedure WriteEncodedText(const Text: String);
//Writes some text in the HTML file.
procedure WriteText(const Text: String);
//Writes the dictionary.
procedure HandleDictionary(Node: TICNCompound;
const CSSClass: String = '');
public
//Creates the visitor and saves the reference on its generator.
constructor Create(Generator: TICBaseHTMLDoc);
//Has to be called before visiting a COM to prepare the visitor.
procedure StartVisit;
//Has to be called after visiting a COM to perform follow-up operations.
procedure EndVisit;
//Called for all text nodes in the ~[link UICNodes COM].
procedure Text(const Text: String); override;
//Called for all raw text nodes/raw data in the ~[link UICNodes COM].
procedure RawText(const Text: String); override;
//Called for all nodes of all kinds of breaks in the ~[link UICNodes COM].
procedure Break(BreakStyle: TICBreakStyle); override;
//Called for nodes in the ~[link UICNodes COM] that change the style of the
//text for their contained nodes.
procedure TextStyle(Node: TICNTextStyle; var VisitChildren: Boolean);
override;
//Called for nodes in the ~[link UICNodes COM] that change the font of the
//text for their contained nodes.
procedure FontStyle(Node: TICNFontStyle; var VisitChildren: Boolean);
override;
//Called for nodes in the ~[link UICNodes COM] that let their contained
//nodes keep their format.
procedure Preformatted(Node: TICNPreformatted; var VisitChildren: Boolean);
override;
//Called for each link to an identifier or file.
procedure LinkTo(Identifier: TIdentifier; TheFile: TPascalFile); override;
//Called for each link to a file by one of its aliases (used in the uses
//clauses).
procedure LinkFileByAlias(TheFile: TPascalFile;
const Alias: String); override;
//Called for each link whose target could not be found.
procedure InvalidLink(Node: TICNInvalidLink; var VisitChildren: Boolean);
override;
//Called for each link to a target outside of the generated documentation.
procedure LinkExtern(Node: TICNLinkExtern; var VisitChildren: Boolean);
override;
//Called for each link to a page of the additional user documentation.
procedure LinkPage(Node: TICNLinkPage; var VisitChildren: Boolean);
override;
//Called for each link to a help topic in the documentation as a help on a
//GUI.
procedure LinkGUI(Node: TICNLinkGUI; var VisitChildren: Boolean); override;
//Called for each node representing an image.
procedure Image(Data: TICNImage); override;
//Called for each node representing a short token of pascal code.
procedure PascalCode(const Code: String; Kind: TICPascalCode); override;
//Called for each node representing a list. Each child node is an item in
//the list.
procedure List(Node: TICNList; var VisitChildren: Boolean); override;
//Called for each node representing a dictionary.
procedure Dictionary(Node: TICNDictionary; var VisitChildren: Boolean);
override;
//Called for each node representing a topic in the documentation of
//identifiers or files as derived from its comment.
procedure TopicComment(Node: TICNTopicForComment;
var VisitChildren: Boolean); override;
//Called for each node representing a topic of the additional attributes in
//the documentation of identifiers or files as derived from its comment.
procedure TopicCommentAdditional(Node: TICNTopicForCommentAdditional;
var VisitChildren: Boolean); override;
//Called for each node representing a topic in the documentation of
//identifiers.
procedure TopicCommentIdentifier(Node: TICNTopicForIdentifier;
var VisitChildren: Boolean); override;
//Called for each node representing a topic in the documentation of files.
procedure TopicCommentFile(Node: TICNTopicForFile;
var VisitChildren: Boolean); override;
//Called for each node representing a topic in the documentation of classes
//(record-like types).
procedure TopicCommentClass(Node: TICNTopicForClass;
var VisitChildren: Boolean); override;
//Called for each node representing the list of parameters of a function or
//function type as a dictionary.
procedure ParameterList(Node: TICNParameterlist;
var VisitChildren: Boolean); override;
//Called for each node representing the list of exceptions raised by a
//function or functions of a function type as a dictionary.
procedure ExceptionList(Node: TICNExceptionlist;
var VisitChildren: Boolean); override;
//Called for each node representing a token in the list of ancestors of a
//class or interface.
procedure AncestorListToken(Token: TICAncestorListToken); override;
//Called for each node representing a token in the hierarchy of classes
//(record-like types).
procedure ClassListToken(Token: TICClassListToken; Kind: TRecordKind);
override;
//Only used to set the reference of the file to write to.
property HTMLFile: TBufferStream {read FHTMLFile} write FHTMLFile;
property DiagramsFormat: THTMLDiagramFormat read FDiagramsFormat
write FDiagramsFormat;
property SVGDiagramsWithLinks: Boolean read FSVGDiagramsWithLinks
write FSVGDiagramsWithLinks;
end;
{ * * * *** * * * *** TICBaseHTMLDoc *** * * * *** * * * }
//a list of constants for common tags in the generated HTML which change
//depending on whether a HTML or XHTML document is generated
TTagConstants = object
public
//the tag to start a new line, a line break
br: String;
//the tag for a horizontal line
hr: String;
//the tag for an empty paragraph
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -