Chris Kirkpatrick wrote

> I have used the 'topic' tag in FPDoc to produce some general 'How-To' sections (see the documentation for StdCtrls, DBCtrls for examples)

This is exactly what I was thinking of doing as well.

Thinking about this a bit more and what could apply to my own applications context sensitive help. He is the requirements I have for application (not source code / class) documentation.

* Must be in a text format so it can be tracked by SCM systems.
* Must be able to apply for easy amendments via
patches from the community.
* Must be flexible enough to various output formats can be generated.
* Must be usable for online and offline viewing.
* Must not have a huge tool-chain requirement to view, edit and generate documentation.
* Possible archive format (single file) deployment.

So this immediately drops DocBook and LaTeX formats (sorry Michael) because they require large tool-chains to be installed before you can generate documentation output.

fpdoc format might not be ideal, because it is design specifically to document source code - classes and units etc.. Not application screens.

Wiki's are only online. You cannot edit documentation offline and submit a patch. Wiki pages are stored in a database (90% of the time).

Possible solution
-----------------
AsciiDoc or Markdown syntax. I first time I saw this used, was in the Git project. All documentation is written in AsciiDoc syntax.

AsciiDoc or Markdown on it's own is very much like a standard readme.txt document. Everything is in ascii art format with very little formatting tags. Just reading the raw AsciiDoc or Markdown text is possible, without even generating a specific output format.

Because it is text, it works very well in SCM systems.

There are tools (similar to DocBook and LaTeX) to generate various other output formats (man pages, pdf's, HTML, LaTeX etc.) from the raw syntax, but again it has a relatively large tool-chain requirement and doesn't come standard with most OSes. Good news is that AsciiDoc or Markdown syntax is very easy to parse, so it shouldn't take a lot of work to write our own document generator for markdown syntax. Similar as what fpdoc does for it's format. We can even include a AsciiDoc syntax highlighter in Lazarus, so you can use Lazarus IDE to write the documentation. No extra "document editors" required.

Here is an example of AsciiDoc used to document the git-annotate command. This is the actual git-annotate (raw syntax) documentation.

As you can see, the AsciiDoc syntax hardly has any formatting tags, so you can read it as-is without problems.

It would even be possible to write a "on-the-fly" generator, so when the user clicks the help button, the .txt help file is loaded and generates say an HTML format in memory and viewed with an HTML component in a window. No external web browsers or viewers required.

------------------[ git-annotate.txt ]------------------------ git-annotate(1)
===============

NAME
----
git-annotate - Annotate file lines with commit information

SYNOPSIS
--------
'git annotate' [options] file [revision]

DESCRIPTION
-----------
Annotates each line in the given file with information from the commit which introduced the line. Optionally annotates from a given revision.

The only difference between this command and linkgit:git-blame[1] is that they use slightly different output formats, and this command exists only for backward compatibility to support existing scripts, and provide a more familiar command name for people coming from other SCM systems.

OPTIONS
-------
include::blame-options.txt[]

SEE ALSO
--------
linkgit:git-blame[1]

AUTHOR
------
Written by Ryan Anderson .

GIT
---
Part of the linkgit:git[1] suite
--------------------[ end ]------------------------

This format should be just as easily applicable for any Lazarus based application that you write. So the same help format and "viewer" can be used in LCL based applications. We could even package the .txt help into a ZIP archive using TZipper or TZipFile so a single archive can be distributed with your application. And the help can be read directly from the help archive.

Your thoughts in this?

Regards,
- Graeme -

Zitat von Graeme Geldenhuys :

Almost any text format fits these requirements. You should be more specific. For example the documentation needs
* a toc
* possibility to combine docs to modules
* links to docs in the same module
* links to docs in other modules
* external links
* keywords to refer from outside
* viewers for all platforms:
** a good search engine
** allow to load/view several modules at the same time ** remote control in both directions

This looks like an info page.

Documentation need a good viewer.

Mattias

These are all supported by AsciiDoc.

* keywords to refer from outside

This can be created by us - using a documentation generator or something. Similar to what fpdoc does for CHM help.

* viewers for all platforms:

This is easy. Default help can be HTML format. Lazarus already includes an HTMl viewer component as used by 'lhelp'. I'm sure there are many more available.

** a good search engine ** allow to load/view several modules at the same time ** remote control in both directions

I don't understand these? What do they have to do with documentation? If you publish your docs online, a search engine will be able to index them.

This looks like an info page.

Well, that is the style Git writes there documentation in. So maybe that was a bad example. See the AsciiDoc website for many more examples. We don't have to strictly adhere to AsciiDoc syntax - we could pick the best bits from AsciiDoc, MarkDown etc.. Though it might be beneficial to stick to syntax that is already well thought out, documented and tested.

Maybe I should take one of the Lazarus IDE wiki help pages and convert it to AsciiDoc so we can see a "real" appropriate example and how the default asciidoc generated XHTML 1.1 output looks like.

Documentation need a good viewer.

Any HTML viewer component should do.

One extra nice thing is shown below. Icons for notes, tips etc.. http://www.methods.co.nz/asciidoc/userguide.html#X28

Such images can be embedded inside the generated HTML via data URI tags. No need to reference such images or CSS in external files. Again, makes for easier deployment. By the way "data URI" normally uses base64 encoding, which FCL has support for. Again, no external dependencies needed.

Regards,
- Graeme -

Zitat von Graeme Geldenhuys :

It's not sufficient to only have help files. The important piece is to find and present the help. Just take a look at the mails. We have thousands of help pages and still people say we have no usable help.

If you publish your docs online, a search engine will be able to index them.

And if you view them offline?
And: An index is not enough.

When someone needs help at a certain place, then a F1 should open the help for that - context sensitive help. For example when a user is in the compiler options dialog, a F1 should tell the help viewer to open the help for the 'compiler options dialog'.
That's what I mean with support for "keywords" and "remote control". The online help currently shows the help for the LCL and the FCL.

No.
Where is the search field?
Who produces the html from the doc files?

Mattias

FPDoc has support for keywords in the sense that you can refer to a topic with the name of the keyword.

For the HTML help (user/programmer/ref manual) I implemented the support for keywords at your request ?

Michael.

Mattias G?rtner wrote

It's not sufficient to only have help files. The important piece is to find and present the help. Just take a look at the mails. We have thousands of help pages and still people say we have no usable help.

I would say the biggest problem is because the help is only available online. If Lazarus includes off-line help by default, and they click "help" or F1 inside the IDE dialogs, then at least you will see something.

If I work from home, I am not online. Hence, I have no IDE help. At least I download the FPC html help, so I can view that.

When someone needs help at a certain place, then a F1 should open the help for that - context sensitive help. For example when a user is in the compiler options dialog, a F1 should tell the help viewer to

This is exactly what I want to address. Currently Lazarus doesn't have off-line help, and doesn't provide a help system for developers own programs.

open the help for the 'compiler options dialog'. That's what I mean with support for "keywords" and "remote control". The online help

fpdoc has keyword support and the new versions generate index pages. The "custom help viewer" that we right can work like 'lhelp'. Index, keyword and Search tabs on the left side and a HTML viewer component on the right side. Maybe we can even modify 'lhelp' to suite our needs.

As for context sensitive help. I think a HTML page can still be used, as long as the page has anchor tags included. That way you can tell the HTML viewer component to open the following urls in various situations.

Help button in Compiler Options dialog
help://docs/compiler_options.html

or Compiler Options diaglog and Linking tab active help://docs/compiler_options.html#linking
or
help://docs/compiler_options_linking.html

or Smart Link checkbox is focused and user presses F1 help://docs/compiler_options_linking.html#smartlink

It obviously depends on how we want to split the help of tab based dialogs. Each tab has it's own html page or the whole dialog has one html page, with many anchor sections we can jump to.

No. Where is the search field? Who produces the html from the doc files?

The same design as 'lhelp' or any other CHM help viewer. Index, keyword and Search tabs on the left and HTML viewer component on the right.

We can look at fpdoc code for how indexes and keywords are generated. We can even use grep (like 'find in files' dialog) or regex unit - all included with FPC or Lazarus already.

For the help viewer we can opt for the following:
1) Use the AsciiDoc (*.txt) files as-is, and render them as HTML in-memory only when needed (viewed by user). That we nobody needs to pre-compile and package the help.

2) Pre-compile the AsciiDoc to HTML and package it in a ZIP archive. Make that available for download. Help viewer can now display the help as-is.

Option 1:
---------
pros:
- Help will be instantly available - no extra work required by the user.
- Help would be more up-to-date even for users getting Lazarus from SVN or Git repositories.
- Also because the AsciiDoc doesn't really have much markup in them, we can grep / regex those files as-is for keyword searches.

cons:
- In memory rendering to HTML, so initial load might be slower, but honestly I don't think this will really be an issue.
- It might be easier to work with the row *.txt help if they are not in a single ZIP archive. Then again TZipFile allows standard file handling routines with files inside an archive, so this might not even be a problem.

Option 2:
---------
pros:
- Loading might be a bit quicker compared in in-memory rendering to HTML format.
- A single ZIP archive might be easier to use.

cons:
- More work is required because help needs to be compiled first.
- Help needs to be re-compiled after every help patch is applied.

I think option 1 is the best option. Similar in fashion as what Lazarus can read fpdoc xml directly without first having to pre-compile the help. Not to mention, it is much less effort.

Regards,
- Graeme -

Zitat von Michael Van Canneyt :

Hehe. Yes, Michael, fpdoc has all that already. The next step was to create good fpdoc editors. I think the current editors have matured enough to create fpdoc content easily.
The next step is to browse the content offline and to provide a good search. For example via lhelp.

Mattias

Yes.
it would also be good somehow to merge back some of the wiki content, so it could be used offline. I assume this task could be automated.

Michael.

That's a bit where the textmode IDE is ahead of Lazarus. It can search for keywords through all helpfiles.

Unfortunately, the FV component model only reserves an integer for help, but it shouldn't be too hard to make real help for it.

Does Lazarus already have a file (namespace) + keyword in TComponent for help purposes?

Zitat von Graeme Geldenhuys :

Why do you write that?
a) you don't know it
b) you don't like it

I think this discussion is somewhat fuzzy.
There are several help sources, each with their own problems. Here are the most prominent:

1. the FPC help as latex files
2. the FCL help as fpdoc files
3. the lazarus packages help as fpdoc files (e.g. LCL)
4. the lazarus and fpc wiki pages

1. the FPC help as latex files
* nice pages
* edit: latex, send patches to Michel VC
* as html:
** created via latex libs and scripts,
** viewed by webbrowser,
** search via google&co,
** reference from IDE: difficult
* as pdf:
** created via latex libs and scripts,
** viewed by pdf viewer,
** search via pdf viewer,
** reference from IDE: difficult

2. the FCL help as fpdoc files
* edit: lazde, in a separate svn branch, send patches to FPC team
* as html:
** created via scripts,
** viewed via webbrowser,
** search via google&co
** reference from IDE: via codetools
* as chm:
** created via scripts,
** viewed via chmhelp,
** search via chmhelp
** reference from IDE: via codetools

3. the lazarus packages help as fpdoc files (e.g. LCL)
* edit: fpdoc editor or lazde, send patches to bug tracker
* as html:
** create via scripts, eventually: by IDE
** viewed via webbrowser,
** search via google&co
** reference from IDE: via codetools
* as simple html:
** created on the fly by IDE,
** viewed via IDE,
** search not implemented
** reference from IDE: via codetools
* as chm:
** created via scripts, eventually: by IDE
** viewed via chmhelp,
** search via chmhelp
** reference from IDE: via codetools

4. the lazarus and fpc wiki pages
* edit: on the webserver
* as html:
** created by webserver
** viewed via webbrowser
** search via webserver and google&co
** reference from IDE: via URL table

Mattias

Mattias G?rtner wrote

Why do you write that? a) you don't know it b) you don't like it

Clearly I don't know how to use application help, if it exists.

See attached image...

If I write my own LCL based application with Lazarus, as shown in the screenshot. How do I implement help for my application.

- Click on main form and setup HelpXXX properties as shown in screenshot.
- Create Help Button and implement OnClick event handler as shown in screenshot.
- Make sure I have a mycoolapp.html file.
- Run application.

Test:
- Put focus it TEdit and press F1. ---> NOTHING HAPPENS.
- Click the Help button. ---> NOTHING HAPPENS

How do I implement help for my application?
What must the help format be? HLP, CHM, HTML, ???
What help viewer is it going to use?
- I'm running Linux, so no CHM help viewer comes standard.
- In both tests above the Web Browser never appeared with help either.

See my problem? As far as I can see, by looking at what I have done here, there is now built-in help support for applications built with Lazarus LCL.

I am NOT talking about LCL or FCL class documentation. That is handled by fpdoc and viewed with a Web Browser. Lazarus IDE has special support for view those help formats. But Lazarus LCL based application do not have that special support.

What I am proposing is being able to ship my application with help support. So my deployment will include the following files.

- MyCoolApp (executable)
- lhelp (or whatever the help viewer is called)
- help/mycoolapp.html (help files in help directory) or
- MyCoolApp-help.zip (help files packaged in a archive)

I would prefer a help viewer other than the Web Browser, otherwise I will not have Index, Search and Keyword support like WinHelp or LHelp gives.

Now if I can get by deployment example working as shown above, then the same could probably be applied for the Lazarus IDE (dialogs and setings help) as well.

Regards,
- Graeme -

Mattias G?rtner wrote

Why do you write that? a) you don't know it b) you don't like it

I searched the wiki for the keywords: context sensitive help

Nowhere could I find a wiki page describing how I can implement such help for my own applications. Hence the reason I believe it is not currently possible.

Regards,
- Graeme -

Graeme Geldenhuys wrote

Nowhere could I find a wiki page describing how I can implement such help for my own applications. Hence the reason I believe it is not currently possible.

The closest I could find was the "examples/helphtml" project include with Lazarus. I am using Linux. I compiled the project and ran it. Pressing F1 as the two TEdit boxes describe or by clicking the Help button, nothing happens. My web browser did not open and now custom viewer that gives mi Search, Index and Keyword support was shown either.

Seeing that those two help components are not documented anywhere on the wiki or the CCR website (the later only has skeleton fpdoc help), I have no idea if they are actually in a working state or ready for enduser usage.

Regards,
- Graeme -

And that's the problem :-(

A help system should allow to access *all* these sources, adding a usable organization.

Blog-like help topics are highly undesireable, where the user has to figure out essential information from a bunch of "X has said this, Y has said that...", or topics with a hughe list of related documents.

IMO we need kind of CSS for structuring and representing the essential information, about data types (classes...) and their members. Automated import of preformatted (annotated) text, and means for presenting the information in one or more ways, with HTML as the first choice. Backgrounders, overviews, examples and more can be added as links to external documentation, but to only one primary source for every category (except for examples).

DoDi

Since a few weeks as CHM too.

Ok. But how can the IDE tell the chmviewer to show the page for the keyword 'procedure'?

Mattias

Currently it can't, since the keywords are not part of the HTML and therefor not part of the CHM.

Michael.

keywords are difficult, but procedures work fine. Simply merge the indexes and do a lookup.

Note that I also converted the Windows CHM header, it will be in the next version.

Note that the keywords are in the html docs in the file ref/ref.pwd

type=refch3.html#keyword:type
integer=refsu5.html#keyword:integer
array=refsu14.html#keyword:array
record=refsu15.html#keyword:record

and that the anchors exist in the mentioned files, so the CHM generation could, in theory, make use of this.

Michael.

See
http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application

[...] Test: - Put focus it TEdit and press F1. ---> NOTHING HAPPENS. - Click the Help button. ---> NOTHING HAPPENS

Someone broke the example. I fixed it.

How do I implement help for my application? What must the help format be? HLP, CHM, HTML, ???

Your choice. :)
At the moment the LCL provides a help database for URLs and a viewer that simply starts the default browser. The URLs are html files in the example, but of course it can be any URL.

The IDEIntf has a class for fpdoc help databases.

The package ChmHelpPkg provides a viewer for chm files by starting and remote controlling lhelp.

What help viewer is it going to use? - I'm running Linux, so no CHM help viewer comes standard.

The chm viewer lhelp is part of lazarus.

[...]

Mattias

Mattias Gaertner wrote

Someone broke the example. I fixed it.

Thanks, I read the wiki pages and will give the helphtml example another try.

The package ChmHelpPkg provides a viewer for chm files by starting and remote controlling lhelp.

This sounds more promising, thanks for mentioning it.

Regards,
- Graeme -

Also if you assign HelpContext on a TControl chm help has a way to lookup url's from a context id.

Using TChmWriter.AddContext(AContextID, '/my/url/doc.html#heading'); or any url. I suppose you could even use another filename in the url like so: AddContext(AContextID,
'ms-its::mysupplemental.chm:/my/url/doc.html#heading'); That's not tested however :)

Using LHelpControlPkg you can load context's like so:

TLHelpConnection.OpenContext('mychm.chm', AContextID);

or urls

TLHelpConnection.OpenURL('mychm.chm, '/my/url/doc.html');

or just a file

TLHelpConnection.OpenFile('mychm.chm');

Regards,

Andrew

In our previous episode, Michael Van Canneyt said:

(Sorry was in Hasselt for a few days)

Could be. Due to tex4ht, you probably can't rely on the filename though, so you would have to index the anchors in all files, and then fixup the references.

I'll see if I can spend some time on this the coming days.

Done, was easier than I thought. It was .kwd btw.

First /~marcov/ref.chm

Hmm, no such luck. While it showed in *nix ones, it fails on windows.

Probably a : isn't allowed in labels.