📄 ubasehtmldoc.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 UBaseHTMLDoc;
{Contains the base class ~[linkClass TBaseHTMLDoc] for documentation generators
to generate documentation about the parsed data in the HTML format. }
interface
uses Windows, Classes,
{$IFNDEF LINUX}
Graphics,
{$ELSE}
QGraphics,
{$ENDIF}
UPascalConsts,
UBaseIdents,
UOptions,
UMakeDoc,
UCommentDoc, UImages, UOldGUIHelpData, UFormatCommentDoc;
{ * * * *** * * * *** TBaseHTMLDoc *** * * * *** * * * }
//the name of the Cascading Style-Sheets file to create and include
const CSSFileName = 'DelphiDoc.css';
//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 character enconding of the HTML files
//in the header of the HTML files
HeaderReplaceCharacterEncoding = '<encoding>';
//the DTD of the HTML file (the only true (portable/compatible) one
//(so far)!)
DTD_Text = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">';
type
{ * * * *** * * * *** TBaseHTMLDoc *** * * * *** * * * }
{This class is the base class of generator of documentation in the HTML
(Hypertext Mark-Up Language) format. HTML is the first format to be
generated by ~[em DelphiDoc], explaining, why most of the inline commands
are similar to the corresponding HTML-tags.~[br]
A lot of HTML files (*.html) will be created in the directory for the
documentation along with some images (*.gif) and a Cascading Style-Sheets
file (DelphiDoc.css). }
TBaseHTMLDoc = class(TFormatCommentDoc)
private
//the name (and path) of the file, whose content should be used instead of
//the default header of the HTML files
FTextHeaderFile: String;
//the name (and path) of the file, whose content should be used instead of
//the default footer of the HTML files
FTextFooterFile: String;
//if the CSS file shouldn't be overridden, if it already exists;
//useful if the default Cascading Style-Sheets has been customized
FDontOverrideCSSFile: Boolean;
//the character encoding to set for the HTML files; default: iso-8859-15
FCharacterEncoding: String;
//whether special characters should not be quoted, i.e. <>"
FDontQuoteSpecialCharacters: Boolean;
FImageMapIndex: Integer; //index of current image map of an image
protected
//the content of the file ~[link FTextHeaderFile]
FTextHeader: String;
//the content of the file ~[link FTextFooterFile]
FTextFooter: String;
//Writes a GIF image in the given color.
procedure WriteGIFImage(Color: TColor; const FilePrefix: String;
Portability: Boolean; Darker: Byte = 0);
//Writes a GIF image indicating an abstract method.
procedure WriteGIFImageAbstract(const FilePrefix: String);
//Writes the redefined header of a HTML file, replacing special strings
//with others.
procedure WriteFileHeader(var F: TextFile;
const TitlePart, KeyWords, MainPath: String);
{Creates a new HTML file and writes its header.
~param F the file variable to open the file with
~param FileName the name of the file to create
~param TitlePart the title of the HTML page
~param KeyWords the keywords of the HTML page in the index }
procedure CreateFile(var F: TextFile;
const FileName, TitlePart, KeyWords: String); virtual;
abstract;
{Writes the footer of a HTML file and closes it.
~param F the HTML file to end and close }
procedure EndFile(var F: TextFile); virtual; abstract;
//Returns the string token with an applied CSS style.
function FormatStringToken(const StringToken: String): String; override;
//Encodes special characters of external URIs.
function CodeURI(const Text: String): String;
//Returns a prefix for all links to images.
function GetImagePrefix(IsSymbol: Boolean): String; virtual;
//Returns the format needed to express the scope (as an icon).
function GetScope(Scope: TScope): String; override;
//Returns the format needed to express the portability issues (as icons).
function GetPortabilityIssues(Issues: TIdentPortabilities): String;
override;
//Gets the links to the generated files by ~[link WriteFileTreeFiles].
function GetFileListFileLinks: String; override;
//Writes the list of files.
procedure WriteFileList(const Text: String); override;
//Gets the text of an indentation by the given depth.
function ClassListIndent(Indent: Integer): String; override;
//Write the links to the generated files by ~[link WriteClassesTreeFiles].
function ClassListFileLinks(Kind: TRecordKind): String; override;
//Writes the hierarchy of the kind of the record-like types.
procedure WriteClassList(Kind: TRecordKind; const Text: String); override;
//Writes a part of the documentation of a class.
procedure WritePartOfClassDocumentation(Ident: TRecordType;
var F: TextFile);
//Starts a list of exported identifiers.
procedure StartExportsLists(var TheFile: TextFile; AFile: TPascalFile;
PreFirst: Boolean;
var First, Second, Third, Fourth, Fifth,
Sixth: String); override;
//Ends a list of exported identifiers.
procedure EndExportsLists(var TheFile: TextFile; AFile: TPascalFile;
PostLast: Boolean); override;
//Starts the list of all long functions.
procedure StartLongFunctionsLists(var TheFile: TextFile;
var Pre, Middle, Post: String); override;
//Ends the list of all long functions.
procedure EndLongFunctionsLists(var TheFile: TextFile); override;
//Generates an index about all identifiers and files beginning with the
//character.
function DoGenerateIndex(List: TIdentifierFileList; EntryIndex: Integer;
Index: Char): Integer; override;
//Writes the current page of the user documentation.
procedure CreateUserDocPage; override;
//Writes a file with a list of identifiers.
function WriteListFile(const FileName, Title,
Description, KeyWords: String;
List: TIdentifierFileList): Boolean;
//Writes a file of documentation as help for a GUI.
function GenerateGUIHelpOnData(Data: TOldGUIHelpData): String; override;
//Creates the Cascading Style-Sheets files of the documentation.
procedure CreateCSSFile;
//Creates all needed image files.
procedure CreateImageFiles;
//Prepares for creating the documentation.
procedure PrepareForDocumentation;
//Reinitializes any strings depending on current localization settings.
procedure ResetLanguageStrings; override;
property TextHeaderFile: String read FTextHeaderFile;
property TextFooterFile: String read FTextFooterFile;
property DontOverrideCSSFile: Boolean read FDontOverrideCSSFile;
property CharacterEncoding: String read FCharacterEncoding;
public
//Creates the generator object and initializes its fields.
constructor Create; override;
//Will be called for all reserved words.
function ReservedWord(const Word: String): String; override;
//Returns the number of available options in generators of this class.
class function GetOptionCount: Cardinal; override;
//Gets a description of an option.
class procedure GetOptionDescription(Index: Cardinal;
var Desc: TOptionDescription);
override;
//Gets the value of an option.
function GetOption(Index: Cardinal): TOptionValue; override;
//Sets the value of an option.
procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;
//Handles text by encoding special characters.
function HandleRawText(const Text: String): String; override;
//Handles text of the comment by encoding special characters of the format.
function HandleRawCommentText(const Text: String): String; override;
//Returns the text in the format; text may already include other formats.
function FormatText(TextFormat: TDocumentationTextFormat;
const Text: String;
var SkipWhitespaces: Boolean): String; override;
//Gets the (internal) identification (for links) of topics of documentation
//of a GUI.
function GetGUIHelpURIByIndex(FileIndex, TopicIndex: Integer): String;
override;
//Gets the (internal) identification (for links) of pages in the user
//documentation.
function GetPageURI(PageIndex: Integer): String; override;
//Writes a link to an identifier or file in the documentation.
function InternalLink(const URI, LinkLabel: String): String; override;
//Includes an image in the documentation.
function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
BMP: TBitmap; const FileName: String;
Links: TImageLinkList;
const AlternativeText: String): String; override;
//Resets the attributes to ready the generator for a new generation.
procedure ResetForNewGeneration; override;
end;
implementation
uses SysUtils,
{$IFNDEF LINUX}
ShellAPI,
{$ENDIF}
General,
UFilePaths,
UDocumentDoc,
UDocumentationTexts;
{ * * * *** * * * *** TBaseHTMLDoc *** * * * *** * * * }
{Creates the generator object and initializes its fields. }
constructor TBaseHTMLDoc.Create;
begin
inherited Create; //create the object
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -