From f3e2fd9696150e90a9ccdb1bd7ec21787df45e97 Mon Sep 17 00:00:00 2001 From: juha Date: Tue, 19 Jan 2021 13:54:29 +0000 Subject: [PATCH] Docs: Lazutils documentation update, includes directories for examples. Issue #38365, patch from Andrey Sobol. git-svn-id: trunk@64406 - --- .gitattributes | 3 + .../examples/fileutil.findallfiles.pas | 23 ++ docs/xml/lazutils/examples/readme.txt | 34 +++ docs/xml/lazutils/fileutil.xml | 277 +++++++++--------- docs/xml/lazutils/lazfileutils.xml | 164 +++++------ docs/xml/lcl/examples/readme.txt | 34 +++ 6 files changed, 304 insertions(+), 231 deletions(-) create mode 100644 docs/xml/lazutils/examples/fileutil.findallfiles.pas create mode 100644 docs/xml/lazutils/examples/readme.txt create mode 100644 docs/xml/lcl/examples/readme.txt diff --git a/.gitattributes b/.gitattributes index 1289674d46..aec36003c8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -6089,6 +6089,8 @@ docs/xml/lazutils/compwriterpas.xml svneol=native#text/plain docs/xml/lazutils/dynamicarray.xml svneol=native#text/plain docs/xml/lazutils/dynhasharray.xml svneol=native#text/plain docs/xml/lazutils/dynqueue.xml svneol=native#text/plain +docs/xml/lazutils/examples/fileutil.findallfiles.pas svneol=native#text/pascal +docs/xml/lazutils/examples/readme.txt svneol=native#text/plain docs/xml/lazutils/extendedstrings.xml svneol=native#text/plain docs/xml/lazutils/filereferencelist.xml svneol=native#text/plain docs/xml/lazutils/fileutil.xml svneol=native#text/plain @@ -6186,6 +6188,7 @@ docs/xml/lcl/dialogs/trymessagedlg.pas svneol=native#text/pascal docs/xml/lcl/dialogs/tryshowmessage.pas svneol=native#text/pascal docs/xml/lcl/dynamicarray/tarrayexample.pas svneol=native#text/plain docs/xml/lcl/editbtn.xml svneol=LF#text/xml eol=lf +docs/xml/lcl/examples/readme.txt svneol=native#text/plain docs/xml/lcl/extctrls.xml svneol=LF#text/xml eol=lf docs/xml/lcl/extctrls/radiobutton.pas svneol=native#text/pascal docs/xml/lcl/extctrls/statusbar.pas svneol=native#text/plain diff --git a/docs/xml/lazutils/examples/fileutil.findallfiles.pas b/docs/xml/lazutils/examples/fileutil.findallfiles.pas new file mode 100644 index 0000000000..b223d773d5 --- /dev/null +++ b/docs/xml/lazutils/examples/fileutil.findallfiles.pas @@ -0,0 +1,23 @@ +uses + FileUtil; +var + PascalFiles: TStringList; +begin + PascalFiles := TStringList.Create; + try + FindAllFiles(PascalFiles, LazarusDirectory, '*.pas;*.pp;*.p;*.inc', true); //find e.g. all pascal sourcefiles + ShowMessage(Format('Found %d Pascal source files', [PascalFiles.Count])); + finally + PascalFiles.Free; + end; +end; +// or +begin + //No need to create the stringlist; the function does that for you + PascalFiles := FindAllFiles(LazarusDirectory, '*.pas;*.pp;*.p;*.inc', true); //find e.g. all pascal sourcefiles + try + ShowMessage(Format('Found %d Pascal source files', [PascalFiles.Count])); + finally + PascalFiles.Free; + end; +end; diff --git a/docs/xml/lazutils/examples/readme.txt b/docs/xml/lazutils/examples/readme.txt new file mode 100644 index 0000000000..96a8cb44a2 --- /dev/null +++ b/docs/xml/lazutils/examples/readme.txt @@ -0,0 +1,34 @@ +This directory is intended for storing examples of Pascal code included in the documentation. + +You can include example code in the documentation as follows: + +1. Place an example of the code inside this directory as a unit with name UnitName.FunctionName.pas or similar. + Place the link in this example for the documentation tag as follows: + + + + + + The file attribute of the tag is used to specify the filename containing the example. The filename does not require an extension: if it is missing, .pp is assumed. + + If you use the fpdoc editor then use the example tab for that. + https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu70.html + +2. Place the example code into the section inside tags. + Note that any text surrounding the code tags should be placed inside

tags. + For example: + + + +

+ // Any description. +

+ + // Place example code here. + +

+ + + + https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu63.html + diff --git a/docs/xml/lazutils/fileutil.xml b/docs/xml/lazutils/fileutil.xml index 81620473c8..f17f1cba67 100644 --- a/docs/xml/lazutils/fileutil.xml +++ b/docs/xml/lazutils/fileutil.xml @@ -10,16 +10,10 @@ Miscellaneous procedures, functions, types, and classes for manipulating files and file names - -

- This unit contains functions, procedures, types, and classes used to maintain compatibility with the FileUtil unit in Delphi. File routines that deal with UTF-8 file names are located in the LazFileUtils unit. -

-

- File name handling in the unit is platform- or OS-specific. For the Windows, Darwin (MacOS), and Amiga platforms, file names are NOT case sensitive. In addition, under Darwin, the NotLiteralFilenames define is enabled. This indicates that file names cannot be compared using the = +

This unit contains functions, procedures, types, and classes used to maintain compatibility with the FileUtil unit in Delphi. File routines that deal with UTF-8 file names are located in the LazFileUtils unit. +

File name handling in the unit is platform- or OS-specific. For the Windows, Darwin (MacOS), and Amiga platforms, file names are NOT case sensitive. In addition, under Darwin, the NotLiteralFilenames define is enabled. This indicates that file names cannot be compared using the = string operator. -

-

- This unit contains basic functions similar to those in the RTL, but use UTF-8 instead of the defauilt system encoding. Please note that AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, and MacOSX. Normally these OS's use UTF-8 as system encoding so the WideStringManager is not needed. +

This unit contains basic functions similar to those in the RTL, but use UTF-8 instead of the defauilt system encoding. Please note that AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, and MacOSX. Normally these OS's use UTF-8 as system encoding so the WideStringManager is not needed.

@@ -33,8 +27,8 @@ Byte Order Mark (BOM) used at the beginning of UTF-8-encoded files - - + + @@ -44,7 +38,7 @@ The value is determined by the presence of the CaseInsensitiveFilenames compiler define. - + @@ -55,28 +49,28 @@ The value is determined by the presence of the NotLiteralFilenames compiler define. - + - - - + + + - - - + + + - - - + + + - - - + + + @@ -109,15 +103,15 @@ - - - + + + - + - + @@ -150,24 +144,24 @@ - - - + + + - + - - - + + + - + - + @@ -290,16 +284,16 @@ Deprecated. Use the function from the LazFileUtils unit. - + - + - + - + @@ -375,9 +369,9 @@ - - - + + + @@ -631,12 +625,12 @@ - - - + + + - + @@ -665,21 +659,21 @@ - - - + + + - - - + + + - - - + + + @@ -777,42 +771,42 @@ Character used as a delimiter between file masks in the search critera - - + + Character used as a delimiter between directory paths in the search criteria - - + + Indicates if a search should follow paths that are symbolic links - - + + - + FileAttribute is a Word property. The default value for the property is faAnyfile. - + - + DirectoryAttribute is a Word property. The default value for the property is faDirectory. - + @@ -829,8 +823,8 @@ Event handler signalled when the searcher enters a new directory - - + + @@ -841,7 +835,7 @@ TListFileSearcher is a TFileSearcher descendant used to used store files matching a specified search criteria in a TStrings class instance. - + @@ -852,8 +846,8 @@ Performs actions required to add a file name to the list of matches for the file searcher - - + + @@ -863,7 +857,7 @@ Create is the constructor for the class instance. Create calls the inherited constructor, and stores the TStrings instance in AList to the the internal member used in the class instance. - + TStrings class instance used to store matching file names @@ -876,7 +870,7 @@ TListDirectoriesSearcher is a TFileSearcher descendant used to store directory names matching the specified search criteria in a TStrings class instance. - + @@ -887,8 +881,8 @@ Performs actions needed to add a directory path to the list of matches for the searcher - - + + @@ -898,39 +892,39 @@ Create is the constructor for the class instance. Create calls the inherited constructor, and stores the value in AList to the internal member used to capture matching directory names in the class instance. - + TStrings class instance used to store directory names matching the specified search criteria - - + + Returns the list of files in the specified path matching the search criteria - -

- FindAllFiles is an overloaded method used to populate a TStringList class instance with a list of files match the specified search criteria. The procedure variant uses an existing TStringList class instance to store the matching file names. The function variant creates the TStringList - class instance used as the return value for the method. -

+

FindAllFiles is an overloaded method used to populate a TStringList class instance with a list of files match the specified search criteria. +The procedure variant uses an existing TStringList class instance to store the matching file names. +The function variant creates the TStringList class instance used as the return value for the method. +

 + + The function FindAllFiles creates the stringlist internally. This may look very convenient at first sight, but it is very easy to create memory leaks that way. + List of file names matching the search criteria - - The StringList is created in the FindAllFiles function; you should not instantiate it before calling the function. - + The StringList is created in the FindAllFiles function; you should not instantiate it before calling the function. + TStringList used to store file names matching the search criteria - - AList must be instantiated before it is passed as an argument to the method. The TStringList instance must also be freed by the routine where it was created. - + AList must be instantiated before it is passed as an argument to the method. The TStringList instance must also be freed by the routine where it was created. + Base path for searching files @@ -939,12 +933,13 @@ A list of masks, separated by a semicolon (;) to which found files should match - - A list of masks, separated by a semicolon (;) to which found files should match. The mask can contain wildcards like * and ? and it also supports sets like [a-d,x]. See the Masks unit for more details. - + A list of masks, separated by a semicolon (;) to which found files should match. The mask can contain wildcards like * and ? and it also supports sets like [a-d,x]. See the Masks unit for more details. + If search recursively sub directories + Parameter DirAttr is int file attribute: if file-system item has this attribute(s), it is considered as a directory. It can be faDirectory, faSymLink, (faDirectory+faSymLink) or maybe another bits can be used. + If search recursively sub directories @@ -954,58 +949,56 @@ Stores directory names matching the search criteria in a TStringList class instance - -

- FindAllDirectories is an overloaded routine used to store directory path names that match the specified search criteria in a TStringList class instance. The procedure variant uses an existing TStringList class instance to store the matching directory names. The function variant allocates a TStringList class instance used to capture the matching directory names. +

FindAllDirectories is an overloaded routine used to store directory path names that match the specified search criteria in a TStringList class instance. The procedure variant uses an existing TStringList class instance to store the matching directory names. The function variant allocates a TStringList class instance used to capture the matching directory names.

- + Stores directory names matching the search criteria - - + + Stores directory names matching the search criteria - - + + - - - + + + - - - + + + - - - + + + - - - + + + - + - + - + - - - + + + @@ -1026,39 +1019,39 @@ The destination filename for the Copy - + If True, the timestamp of the original file is preserved in the copied file - + - - - + + + - - - + + + - - - + + + - - - + + + - - - + + + @@ -1070,14 +1063,14 @@ An array of file extensions considered to be Pascal source code - - + + File masked used to match all directories entries - - + + diff --git a/docs/xml/lazutils/lazfileutils.xml b/docs/xml/lazutils/lazfileutils.xml index 7aa358c65e..6d2ae5b93a 100644 --- a/docs/xml/lazutils/lazfileutils.xml +++ b/docs/xml/lazutils/lazfileutils.xml @@ -81,7 +81,7 @@
Filename1 comes after Filename2
- + @@ -129,8 +129,8 @@ The return is 1 if Filename does not contain a file extension.

- - + + @@ -167,7 +167,7 @@

- + @@ -302,7 +302,7 @@ ExtractFileNameOnly is a String function used to extract the base file name (without the file extension) from the value in AFilename. Path information, up to the last directory separator ('/' or '\') or device separator (':') character, in AFileName is ignored. The file extension, starting at the '.' character, is also omitted.

- + @@ -337,7 +337,7 @@ The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment.

- + @@ -369,7 +369,7 @@ The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment.

- + @@ -395,7 +395,7 @@ In UNIX-like environments, the FilenameIsUnixAbsolute function is used in the implementation of FilenameIsAbsolute. The return value is False if TheFilename is an empty string (''), or does not start with the directory separator for the environment.

- + @@ -508,7 +508,7 @@ FileIsExecutable is a Boolean function used to determine if the specified file name is executable. For UNIX-like environments, a combination of FpStat, FPS_ISREG, and FpAccess are used to get the return value. For the Windows environment, the value from FileExistsUTF8 is used as the return value. In short, the function is not really useful in a Windows environment.

- + @@ -523,17 +523,11 @@ Indicates if the specified file is a symbolic link in the file system - -

- FileIsSymlink is a Boolean function used to determine if the specified file name is a symbolic link on the local file system. -

-

- The implementation of FileIsSymlink is platform-specific. For UNIX-like environments, the FpReadLink function is used to determine if the symbolic link can be resolved to a physical file name in the local file system. For the Windows platform, FileGetAttrUTF8 is called to get and examine the file attributes for the specified file name. The file attributes must include the value FILE_ATTRIBUTE_REPARSE_POINT, and one of the Windows API values such as IO_REPARSE_TAG_SYMLINK or IO_REPARSE_TAG_MOUNT_POINT for the corresponding file handle. For the Amiga platform, FileIsSymLink always returns False. +

FileIsSymlink is a Boolean function used to determine if the specified file name is a symbolic link on the local file system. +

The implementation of FileIsSymlink is platform-specific. For UNIX-like environments, the FpReadLink function is used to determine if the symbolic link can be resolved to a physical file name in the local file system. For the Windows platform, FileGetAttrUTF8 is called to get and examine the file attributes for the specified file name. The file attributes must include the value FILE_ATTRIBUTE_REPARSE_POINT, and one of the Windows API values such as IO_REPARSE_TAG_SYMLINK or IO_REPARSE_TAG_MOUNT_POINT for the corresponding file handle. For the Amiga platform, FileIsSymLink always returns False.

- - - + @@ -547,20 +541,12 @@ Indicates if the specified file has a descriptor or handle on the local file system - -

- FileIsHardLink is a Boolean function used to determine if the specified file name is represented by a file descriptor or handle on the local file system. -

-

- The implementation of FileIsHardLink is platform- or OS-specific. For UNIX-like environments, a file handle is retrieved by calling the FileOpenUTF8 function and passed to the FPFStat function to access the file information. For the Windows platform (excluding WinCE and Windows XP), the GetFileInformationByHandle Windows API routine is called to get information for the file handle. For the Amiga platform, FileIsHardLink always returns False. -

-

- The return value is False if a file handle could not be accessed for the specified file name or it is actually a symbolic link on the local file system. +

FileIsHardLink is a Boolean function used to determine if the specified file name is represented by a file descriptor or handle on the local file system. +

The implementation of FileIsHardLink is platform- or OS-specific. For UNIX-like environments, a file handle is retrieved by calling the FileOpenUTF8 function and passed to the FPFStat function to access the file information. For the Windows platform (excluding WinCE and Windows XP), the GetFileInformationByHandle Windows API routine is called to get information for the file handle. For the Amiga platform, FileIsHardLink always returns False. +

The return value is False if a file handle could not be accessed for the specified file name or it is actually a symbolic link on the local file system.

- - - + @@ -606,7 +592,7 @@ FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.

- + @@ -643,7 +629,7 @@ Content in the file (up to 1024 characters) is checked to ensure that invalid Null and Control characters are not found in the file. The return value is True when the specified file name exists in the local file system, and does not contain Null or Control characters.

- + @@ -663,7 +649,7 @@ - +

FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters. @@ -672,7 +658,7 @@ Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols.

- + @@ -703,7 +689,7 @@ TrimFilename is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//'). - + @@ -751,7 +737,7 @@ CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').

- + @@ -805,7 +791,7 @@ The return value is an empty string ('') if Filename contains an empty string ('').

- + @@ -873,7 +859,7 @@ CreateRelativePath is thread safe, and therefore, does not guarantee that the current directory is correct for file names like 'D:test.txt'. - + @@ -920,7 +906,7 @@ This is a logical test; FileIsInPath does not expand or follow symbolic links. - + @@ -951,7 +937,7 @@ Please note: PathIsInPath ensures that a trailing path delimiter is included in the Path and Directory arguments prior to performing its comparison. On Windows, this results in a Path like 'C:' being treated as if it contains 'C:\'. - + True when Directory exists in Path @@ -978,7 +964,7 @@ The return value is the same as the aFileName argument if the file name did not need to be shortened.

- + Shortened version of the specifed file name @@ -991,11 +977,11 @@ - + TPathDelimSwitch is an enumerated type with values that indicate how path delimiters in file names are handled in routines like SwitchPathDelims, CheckPathDelim, and IsCurrentPathDelim. Values in the enumeration represent the various platform- or OS-specific path delimiters available in the Lazarus LCL at run-time. - + No path delimiter changes were used @@ -1036,7 +1022,7 @@ For Windows, this means any UNIX path delimiters (/) in FileName are converted into the Windows path delimiter (\). Conversely, for all other platforms and environments, the Windows path delimiter (\) is converted to the UNIX notation (/). All path delimiter substitutions in FileName occur inline.

- + File name examined in the routine @@ -1070,7 +1056,7 @@ AppendPathDelim is a String function used to ensure that a trailing path delimiter is included in the specified Path. The return value includes the value in Path and the trailing path delimiter (when needed).

- + @@ -1093,7 +1079,7 @@ ChompPathDelim is a String function used to remove a trailing path delimiter from the specified value in Path. For environments where UNC paths are allowed, ChompPathDelim ensures that the UNC path delimiters are retained. Windows Device identifiers, such as "D:" are also retained in Path.

- + @@ -1186,7 +1172,7 @@ Value to compare to the current path delimiter for the system - + @@ -1219,7 +1205,7 @@ - + Boolean result of the path delimiter comparison @@ -1343,7 +1329,7 @@ Compiler defines determine the mechanism used to perform a comparison of the values in APath and SearchPath; i.e. CaseInsensitiveFilenames and NotLiteralFilenames. CompareFilenames is called to perform the comparison when inline comparison of string values in not supported.

- + Position or value for the located search path @@ -1371,7 +1357,7 @@ FileExistsUTF8 is a Boolean function which indicates if the specified file name exists in the local file system. For the Windows environment, FileExistsUTF8 uses FileGetAttrUTF8 to ensure that Filename does not have the FILE_ATTRIBUTE_DIRECTORY attribute. For UNIX-like environments, the FileExists function in SysUtils is used to get the return value.

- + @@ -1400,7 +1386,7 @@ The return value is in FileDate format, and can be transformed to a TDateTime value with the FileDateToDateTime function.

- + @@ -1423,7 +1409,7 @@ DirectoryExistsUTF8 is Boolean function used to determine if the specified path exists on the local file system. For the Windows environment, FileGetAttrUTF8 is called to see if FILE_ATTRIBUTE_DIRECTORY is included in the file attributes for the specified Directory. For UNIX-like environments, the DirectoryExists function in the SysUtils unit is used to get the return value.

- + @@ -1449,7 +1435,7 @@ If an empty string ('') is passed in Filename, it is expanded to the current directory using GetCurrentDirUTF8. When FileName contains the tilde character (~), it is converted to the path to the home directory for the user using the HOME environment variable. Relative paths in FileName are resolved by calling ResolveDots.

- + @@ -1487,7 +1473,7 @@ The return value contains the result from GetLastError; a non-zero value indicates that no files matching the criteria were found.

- + @@ -1529,7 +1515,7 @@ The return value contains the result from GetLastError; a non-zero value indicates that an error was encountered.

- + @@ -1552,7 +1538,7 @@ FindCloseUTF8 is a procedure used to free resources allocated to the search record in F by the FindFirstUTF8 routine. FindCloseUTF8 calls the FindClose function in the SysUtils unit.

- + @@ -1576,7 +1562,7 @@ The return value is the value from GetLastError; a non-zero value indicates that an error has occurred.

- + @@ -1633,7 +1619,7 @@ - + @@ -1688,7 +1674,7 @@ The return value contains the result from GetLastError; a non-zero value indicates that an error has occurred.

- + @@ -1722,7 +1708,7 @@ The return value contains True when Filename is successfully deleted from the local file system.

- + @@ -1751,8 +1737,8 @@ The return value is True if the file is renamed successfully.

- - + + @@ -1789,7 +1775,7 @@ When ImplicitCurrentDir is False, each path in DirList is searched for a file with the specified name. The search is stopped when the first file with the specified file name is found. The return value contains the path in DirList where the file name was located along with the file name, or an empty string ('') if the specified file is not found in the search.

- + @@ -1817,7 +1803,7 @@ FileIsReadOnlyUTF8 is a Boolean function used to determine if the specified file is marked as read-only in the local file system. FileIsReadOnlyUTF8 calls FileGetAttrUTF8 for the specified file name and checks to see if faReadOnly has been included in the file attributes value. The return value is True when faReadOnly has been included in the file attributes.

- + @@ -1883,7 +1869,7 @@ - + @@ -1914,7 +1900,7 @@ An error can occur if a directory with the specified name already exists in the local file system.

- + @@ -2148,7 +2134,7 @@ Modified: MM/DD/YYYY hh:mm The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.

- + String with the file information for the platform or OS @@ -2185,7 +2171,7 @@ Modified: MM/DD/YYYY hh:mm File attributes not found in Attrib are represented as '-' characters.

- + String with information about the file attributes @@ -2325,7 +2311,7 @@ Modified: MM/DD/YYYY hh:mm - +

GetAppConfigDirUTF8 is a String function used to get the directory on the local file system where application configuration and data files are stored. @@ -2449,7 +2435,7 @@ Modified: MM/DD/YYYY hh:mm GetTempFileNameUTF8 examines the files in the specified directory to determine if a file already exists which starts with the value in Prefix. If a file is located in the directory, a numeric suffix (starting at 0) is appended to the base file name in Prefix to build a temporary file name which does not already exist in the directory.

- + Temporary file name generated in the routine @@ -2482,7 +2468,7 @@ Modified: MM/DD/YYYY hh:mm Use ExtractUNCVolume to get host and path information from a file name expressed using UNC notation.

- + True when the path contains UNC notation @@ -2550,7 +2536,7 @@ Modified: MM/DD/YYYY hh:mm C:\ - + Root directory on the file system for the specified file name @@ -2560,34 +2546,34 @@ C:\ - + Implemented when the platform or OS includes the darwin compiler define. Used in the implementation of TryCreateRelativePath for the Darwin platform. - + - + - + - + Implemented when the platform or OS includes the darwin compiler define. Handles canonical string normalization forms for file names on the Darwin platform. - + - + - + - + @@ -2626,8 +2612,8 @@ C:\ Ensures that whitespace and quoting use the format required for command line parameters - - + + @@ -2640,8 +2626,8 @@ C:\ Generates a string with the specified list of parameters - - + + String representation for the list of parameters @@ -2652,8 +2638,8 @@ C:\ Splits the specified command line into program and parameter values - - + + Command line examined in the function @@ -2667,8 +2653,8 @@ C:\ Ensures command line options are formatted properly - - + + Command line option after quoting has been applied diff --git a/docs/xml/lcl/examples/readme.txt b/docs/xml/lcl/examples/readme.txt new file mode 100644 index 0000000000..96a8cb44a2 --- /dev/null +++ b/docs/xml/lcl/examples/readme.txt @@ -0,0 +1,34 @@ +This directory is intended for storing examples of Pascal code included in the documentation. + +You can include example code in the documentation as follows: + +1. Place an example of the code inside this directory as a unit with name UnitName.FunctionName.pas or similar. + Place the link in this example for the documentation tag as follows: + + + + + + The file attribute of the tag is used to specify the filename containing the example. The filename does not require an extension: if it is missing, .pp is assumed. + + If you use the fpdoc editor then use the example tab for that. + https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu70.html + +2. Place the example code into the section inside tags. + Note that any text surrounding the code tags should be placed inside

tags. + For example: + + + +

+ // Any description. +

+ + // Place example code here. + +

+ + + + https://www.freepascal.org/docs-html/current/fpdoc/fpdocsu63.html +