Difference between revisions of "FPDoc Editor"

From Free Pascal wiki
Jump to navigationJump to search
m (Fixed two typos)
(32 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{LazDoc}}
+
{{FPDoc Editor}}
  
 
== Introduction ==
 
== Introduction ==
LazDoc is short for lazarus documentation system, but should properly be referred to as FPDoc editor. It uses and extends the FPDoc system - the Free Pascal Documentation system. You can find information about FPDoc here [http://lazarus-ccr.sourceforge.net/fpcdoc/fpdoc/fpdoc.html Free Pascal documentation tool manual].
+
FPDoc is the Free Pascal documentation tool which is specifically designed to create help files for individual units of Pascal source code. For more information about FPDoc see here: [http://www.freepascal.org/docs-html/fpdoc/fpdoc.html Free Pascal documentation tool manual].
  
Lazarus extension for FPDoc:
+
[[image:FPDocEditorDescription.png]]
===FPDoc editor===
 
  
This is an integrated editor/viewer for Lazarus.
+
Lazarus provides inline FPDoc help viewer in hints and two help file editors either of which you can use to create or update source code documentation in FPDoc format.
 +
If you want to see it correctly formatted, you have to install Package TurboPowerIProDsgn.lpk!
 +
The simpler editor, integrated into the Lazarus IDE is called '''FPDoc Editor''', and is described on this page. There is also a more complete and complex editor called [[Lazarus_Documentation_Editor|LazDE]].  
  
===LazDE - Lazarus Documentation Editor===
+
'''LazDE''' is a bigger brother to '''FPDoc Editor''' and is the Lazarus Documentation Editor.  
The big brother of the ''FPDoc Editor'' is '''lazde''' the lazarus documentation editor. It is a standalone application which can be found in lazarus/doceditor/lazde.lpi.
+
It is a standalone application (not an integral part of the IDE). It is located at ($LazDir)/doceditor/lazde.lpi. Once you have compiled the lazde project (using Lazarus) LazDE then runs outside the IDE.
 +
You can add it into menu Tools as external tool.
  
== Where is the FPDoc Editor? ==
+
== Using the FPDoc Editor ==
The FPDoc Editor is integrated in the Lazarus IDE. It can be found under the '''View''' menu.
+
To use the FPDoc Editor you simply:
  
== Usage ==
+
1. Open the FPDoc Editor. You will find it under the View menu.
Using FPDoc editor is very simple.
 
  
1. Set the search path for FPDoc files:
+
2. In the Lazarus source code editor move the cursor to some code element. You will notice that the FPDoc Editor's Caption changes to show the selected source element together with the filename of the documentation file. Within FPDoc Editor you can select an appropriate page where you can edit a specific documentation tag. Of course it is also possible to use FPDoc Editor only to view documentation files, without changing them.
  
* for project: the Project | Project Options dialog, under the FPDoc editor tab page.
+
3. Click on the Create Help button. If you have not yet set up search paths for FPDoc the IDE will ask you where the FPDoc files it generates should be stored. For each of your projects you would normally provide a 'docs' subdirectory.
* for package: the package Options dialog, under the IDE Integration editor tab page.
 
* for LCL: the Environment | Environment options dialog, under the FPDoc editor tab page.
 
  
2. Open or select a file for which documentation exists.  
+
4. Write a short description.
  
3. Open the FPDoc Editor. You can find it under the menu View.
+
5. Click on the Save button to the left or go to the next item (the editor automatically saves a description when you move away from it).
  
4. Place and move the cursor. After placing the cursor on the source editor, you will notice that the caption of the fpdoc editor form changes. The caption shows the source element selected and the filename of the documentation file. By selecting the appropriate page in the editor you can edit a specific documentation tag. Of course it is also possible to use it only as a viewer.
+
== Editing FPDoc entries for the LCL sources and Lazarus sources ==
 +
 
 +
There are in folder ($LazDir)\docs\xml, You can add this folder to FPDoc paths at Tools / Options / Environment / FPDoc Editor
 +
 
 +
==Editing FPDoc entries for the FPC sources, RTL and FCL==
 +
 
 +
The FPDoc entries for the FPC sources can be downloaded from svn:
 +
<syntaxhighlight lang="bash">
 +
cd /home/username/yourchoice/
 +
svn co http://svn.freepascal.org/svn/fpcdocs/trunk fpcdocs
 +
</syntaxhighlight>
 +
 
 +
Add the path ''/home/username/yourchoice/fpcdocs'' to Tools / Options / Environment / FPDoc Editor
 +
 
 +
A good item to test FPDoc on is ''TComponent.Name''.
  
 
== Future plans ==
 
== Future plans ==
 
The todo list currently contains the following items, in no particular order:
 
The todo list currently contains the following items, in no particular order:
  
* Extend the link editor to show packages and identifiers.
+
*Write a help editor for topics.
 +
*Create nicer HTML output for the hint windows.
 +
*Support Operators
 +
*Jump to next/previous undocumented identifier
 +
 
 +
=== Already done ===
 +
* Extend the link editor to show packages and identifiers
 
* Add documentation tags "example" to FPDoc Editor
 
* Add documentation tags "example" to FPDoc Editor
 
* Add documentation tags "topic" to FPDoc Editor
 
* Add documentation tags "topic" to FPDoc Editor
 
+
* Make FPDoc Editor create new elements in documentation
== Done ==
+
* Make FPDoc Editor create new documentation files
* Make LazDoc create new elements in documentation
+
* Adding a small toolbar makes it possible to use the available markup tags
* Make LazDoc create new documentation files
+
* Make FPDoc Editor work on keydown in source code editor
* Adding a small toolbar makes it possible to use the available makeup tags.
+
* Add FPDoc Editor to IDE settings (showing and position in IDE)  
* Make LazDoc work on keydown in sourceeditor
 
* Add LazDoc to IDE settings (showing and position in IDE)  
 
 
* Make it work for fpc sources (rtl files already exist)
 
* Make it work for fpc sources (rtl files already exist)
 
* Add settings to environment menu
 
* Add settings to environment menu
Line 48: Line 65:
 
* Propose to expand documentation tags with: "todo" and "notes" (no need for that, as there are alternatives)
 
* Propose to expand documentation tags with: "todo" and "notes" (no need for that, as there are alternatives)
 
* Reduce overhead even further
 
* Reduce overhead even further
* All source elements are interpreted by LazDoc using codetools
+
* All source elements are interpreted by FPDoc Editor using codetools
* Find inherited entries. For example TControl.Align of TButton.Align.
+
* Find inherited entries. For example TControl.Align of TButton.Align
* Optimization: inherited Entries are parsed on idle.
+
* Optimization: inherited Entries are parsed on idle
 
* Optimization: xml files are cached, and only parsed once or if they changed on disk
 
* Optimization: xml files are cached, and only parsed once or if they changed on disk
* Add a HTML viewer. This is available by installing the turbopoweriprodsgn package.
+
* Add a HTML viewer. This is available by installing the turbopoweriprodsgn package
 +
* Checks for invalid xml tags and auto repairs them

Revision as of 10:51, 12 April 2021

Deutsch (de) English (en) français (fr) 日本語 (ja) polski (pl) português (pt) русский (ru)

Introduction

FPDoc is the Free Pascal documentation tool which is specifically designed to create help files for individual units of Pascal source code. For more information about FPDoc see here: Free Pascal documentation tool manual.

FPDocEditorDescription.png

Lazarus provides inline FPDoc help viewer in hints and two help file editors either of which you can use to create or update source code documentation in FPDoc format. If you want to see it correctly formatted, you have to install Package TurboPowerIProDsgn.lpk! The simpler editor, integrated into the Lazarus IDE is called FPDoc Editor, and is described on this page. There is also a more complete and complex editor called LazDE.

LazDE is a bigger brother to FPDoc Editor and is the Lazarus Documentation Editor. It is a standalone application (not an integral part of the IDE). It is located at ($LazDir)/doceditor/lazde.lpi. Once you have compiled the lazde project (using Lazarus) LazDE then runs outside the IDE. You can add it into menu Tools as external tool.

Using the FPDoc Editor

To use the FPDoc Editor you simply:

1. Open the FPDoc Editor. You will find it under the View menu.

2. In the Lazarus source code editor move the cursor to some code element. You will notice that the FPDoc Editor's Caption changes to show the selected source element together with the filename of the documentation file. Within FPDoc Editor you can select an appropriate page where you can edit a specific documentation tag. Of course it is also possible to use FPDoc Editor only to view documentation files, without changing them.

3. Click on the Create Help button. If you have not yet set up search paths for FPDoc the IDE will ask you where the FPDoc files it generates should be stored. For each of your projects you would normally provide a 'docs' subdirectory.

4. Write a short description.

5. Click on the Save button to the left or go to the next item (the editor automatically saves a description when you move away from it).

Editing FPDoc entries for the LCL sources and Lazarus sources

There are in folder ($LazDir)\docs\xml, You can add this folder to FPDoc paths at Tools / Options / Environment / FPDoc Editor

Editing FPDoc entries for the FPC sources, RTL and FCL

The FPDoc entries for the FPC sources can be downloaded from svn:

cd /home/username/yourchoice/
svn co http://svn.freepascal.org/svn/fpcdocs/trunk fpcdocs

Add the path /home/username/yourchoice/fpcdocs to Tools / Options / Environment / FPDoc Editor

A good item to test FPDoc on is TComponent.Name.

Future plans

The todo list currently contains the following items, in no particular order:

  • Write a help editor for topics.
  • Create nicer HTML output for the hint windows.
  • Support Operators
  • Jump to next/previous undocumented identifier

Already done

  • Extend the link editor to show packages and identifiers
  • Add documentation tags "example" to FPDoc Editor
  • Add documentation tags "topic" to FPDoc Editor
  • Make FPDoc Editor create new elements in documentation
  • Make FPDoc Editor create new documentation files
  • Adding a small toolbar makes it possible to use the available markup tags
  • Make FPDoc Editor work on keydown in source code editor
  • Add FPDoc Editor to IDE settings (showing and position in IDE)
  • Make it work for fpc sources (rtl files already exist)
  • Add settings to environment menu
  • Make it work on project files also
  • Propose to expand documentation tags with: "todo" and "notes" (no need for that, as there are alternatives)
  • Reduce overhead even further
  • All source elements are interpreted by FPDoc Editor using codetools
  • Find inherited entries. For example TControl.Align of TButton.Align
  • Optimization: inherited Entries are parsed on idle
  • Optimization: xml files are cached, and only parsed once or if they changed on disk
  • Add a HTML viewer. This is available by installing the turbopoweriprodsgn package
  • Checks for invalid xml tags and auto repairs them