[Lazarus] Building help files: the nitty-gritty

classic Classic list List threaded Threaded
111 messages Options
1234 ... 6
Reply | Threaded
Open this post in threaded view
|

[Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
I normally build Lazarus from svn, targeting bigide, so I'm not sure
that instructions that tell me to download prebuilt binary .chm files
are relevant to me. However, if I could ask two questions here about the
mechanics:

a)  Assuming that ChmHelpPkg is loaded but lhelp is not compiled. Since
the new version of Lazarus might not yet have been run, is there an
idiot-proof way of telling lazbuild what Lazarus directory etc. is to be
used when building lhelp.lpi?

b)  What is the easiest way of integrating .chm files for the RTL etc.,
to the extent that context-sensitive help works for things like
Format()? Again, if I'm building FPC from source I presume it makes more
sense to generate these locally (unless it expects lots of Latex
handling or equivalent).

Finally, if I just want to add a few lines of plain text as
context-sensitive help for a control or form, with the main
documentation having been prepared by e.g. Lyx and saved as a .pdf,
what's the way to do this?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
On 10 July 2012 14:52, Mark Morgan Lloyd
<[hidden email]> wrote:
> I normally build Lazarus from svn, targeting bigide, so I'm not sure that
> instructions that tell me to download prebuilt binary .chm files are
> relevant to me.

I may be wrong, but as far as I know doing a 'make bigide' will not
build the help files, just the LCL and IDE. Well that is how it works
here with 0.9.30.x - I don't know if Lazarus Trunk has changed this.


> b)  What is the easiest way of integrating .chm files for the RTL etc., to
> the extent that context-sensitive help works for things like Format()?

See, that is where CHM help lags behind, and why I mentioned INF some
time back. The way DocView integrates in the IDE (via the External
Tools menu, and not as a compiled in help-interface to the IDE), I can
get Object Pascal language help no problem. The CHM help (and the
other compiled help-interface addons to Lazarus IDE) only works well
for class / API help. The built-in Indexing and Full Text Search of
INF help makes in a no-brainer to find the correct help topic from a
keyword search.

You must remember that there is a difference between FPC's Language
Syntax help (built from LaTex and primarily targets PDF output) and
the Class / API help (built from XML files).


> Finally, if I just want to add a few lines of plain text as
> context-sensitive help for a control or form, with the main documentation

Which one is it? Control or Form?  If it's a Control, then it falls
under the Class / API help, which means XML files must be edited. If
it is a Form (as in application help describing a dialog in your
application), then it's something else. For the latter case, I don't
actually know what is the recommendation for application help with LCL
based applications. For fpGUI based applications, it is an IPF
plain-text file (the help source which gets compiled into binary INF
help).

If you are referring to the help viewer, then again, that is where
LHelp lags behind. DocView allows you to annotate (add inline
comments) any INF files. Those annotations are stored in a separate
file (<helpfile>.notes), which you can move around or copy with the
INF file to a new computer if you want. LHelp has no such
functionality.



--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Graeme Geldenhuys wrote:
> On 10 July 2012 14:52, Mark Morgan Lloyd
> <[hidden email]> wrote:
>> I normally build Lazarus from svn, targeting bigide, so I'm not sure that
>> instructions that tell me to download prebuilt binary .chm files are
>> relevant to me.
>
> I may be wrong, but as far as I know doing a 'make bigide' will not
> build the help files, just the LCL and IDE. Well that is how it works
> here with 0.9.30.x - I don't know if Lazarus Trunk has changed this.

You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
understand things correctly, the various viewers) while "all" doesn't.

>> b)  What is the easiest way of integrating .chm files for the RTL etc., to
>> the extent that context-sensitive help works for things like Format()?
>
> See, that is where CHM help lags behind, and why I mentioned INF some
> time back. The way DocView integrates in the IDE (via the External
> Tools menu, and not as a compiled in help-interface to the IDE), I can
> get Object Pascal language help no problem. The CHM help (and the
> other compiled help-interface addons to Lazarus IDE) only works well
> for class / API help. The built-in Indexing and Full Text Search of
> INF help makes in a no-brainer to find the correct help topic from a
> keyword search.

Right, so stop crowing about it FFS and just say HOW TO DO IT. Then
somebody else can come along and demonstrate that a .chm is no more
difficult.

>> Finally, if I just want to add a few lines of plain text as
>> context-sensitive help for a control or form, with the main documentation
>
> Which one is it? Control or Form?  If it's a Control, then it falls
> under the Class / API help, which means XML files must be edited.

So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?

> If it is a Form (as in application help describing a dialog in your
> application), then it's something else. For the latter case, I don't
> actually know what is the recommendation for application help with LCL
> based applications. For fpGUI based applications, it is an IPF
> plain-text file (the help source which gets compiled into binary INF
> help).

Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
please don't act all surprised :-)

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
Hi,

On 10 July 2012 16:40, Mark Morgan Lloyd
<[hidden email]> wrote:
>
> You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
> understand things correctly, the various viewers) while "all" doesn't.

As far as I understand it, that simply registers CHM help with the
IDE, and gives the IDE a default location of where to find LHelp. And
with newer Lazarus IDE versions, the IDE will automatically try to
compile LHelp if the executable doesn't exist. This still doesn't
compile/generate any of the CHM help files themselves.


> Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody
> else can come along and demonstrate that a .chm is no more difficult.

:-)  I've explained this many times before, and then created a web
page to stop repeating myself.

  http://fpgui.sourceforge.net/docview_ide_integration.shtml

I have to add that when DocView does a keyword search, it uses an
advanced search result algorithm and rating system, to try and make a
"best match". It even does spelling variations to the keyword. So I
believe this helps a lot in the result DocView gives after pressing
F1.


> So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?

Correct. But remember, that when you add comments, they become part of
the documentation. You cannot disable or switch off "user added
comments" at a later date.


> Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
> please don't act all surprised :-)

I know that all too well. :)

My question still stands though. I don't know what is the
recommendation for "application help" with LCL based applications. eg:
I create a new project which is a new Programming Editor. I want to
supply a end-user help file with my binary - like all good software
does. What help file format do I use (as the developer of that
product), and how do I create/edit that help file?

Now if you tell me CHM, that means I need to ship LHelp with my
product because Linux & Mac users don't have CHM help viewers out of
the box. But what is the source help format for CHM, and what tools
(help editor) do I use to edit that source format, and what tool do I
use to "compile" that source help format into the end result CHM file?
Also, how does my product know where to find LHelp (or whatever CHM
viewer I want to use)?


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
On Tue, 10 Jul 2012 17:39:05 +0100
Graeme Geldenhuys <[hidden email]> wrote:

> Hi,
>
> On 10 July 2012 16:40, Mark Morgan Lloyd
> <[hidden email]> wrote:
> >
> > You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
> > understand things correctly, the various viewers) while "all" doesn't.

make bigide does not include chmhelppkg. You have to pass
OPT=-dUseCHMHelp to do that.

 
> As far as I understand it, that simply registers CHM help with the
> IDE, and gives the IDE a default location of where to find LHelp. And
> with newer Lazarus IDE versions, the IDE will automatically try to
> compile LHelp if the executable doesn't exist. This still doesn't
> compile/generate any of the CHM help files themselves.

Correct.
The docs have references to the RTL+FCL docs, which are outside the
Lazarus sources and have references to programmers guide, which
requires latex. The whole doc build chain has too many dependencies and
need several minutes to build. That's not feasible for a simple make
command.

 
>[...]
> > So presumably that's where the (Lazarus) IDE's FPDoc editor comes into it?
>
> Correct. But remember, that when you add comments, they become part of
> the documentation. You cannot disable or switch off "user added
> comments" at a later date.

There is a feature request to hide comments when there is an fpdoc
entry.
And there is a feature request to support the new fpdoc notes.
I don't know the state of the annotation system.

 

> > Noted, but I'm using Lazarus (and this /is/ the Lazarus mailing list, so
> > please don't act all surprised :-)
>
> I know that all too well. :)
>
> My question still stands though. I don't know what is the
> recommendation for "application help" with LCL based applications. eg:
> I create a new project which is a new Programming Editor. I want to
> supply a end-user help file with my binary - like all good software
> does. What help file format do I use (as the developer of that
> product), and how do I create/edit that help file?
>
> Now if you tell me CHM, that means I need to ship LHelp with my
> product because Linux & Mac users don't have CHM help viewers out of
> the box. But what is the source help format for CHM, and what tools
> (help editor) do I use to edit that source format, and what tool do I
> use to "compile" that source help format into the end result CHM file?
> Also, how does my product know where to find LHelp (or whatever CHM
> viewer I want to use)?

I can't help you there.
Same for what image format to use, what installer to use, what version
control system or what upgrade system.

Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Graeme Geldenhuys
Graeme Geldenhuys wrote:

> Hi,
>
> On 10 July 2012 16:40, Mark Morgan Lloyd
> <[hidden email]> wrote:
>> You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
>> understand things correctly, the various viewers) while "all" doesn't.
>
> As far as I understand it, that simply registers CHM help with the
> IDE, and gives the IDE a default location of where to find LHelp. And
> with newer Lazarus IDE versions, the IDE will automatically try to
> compile LHelp if the executable doesn't exist. This still doesn't
> compile/generate any of the CHM help files themselves.

Agreed, and the various wiki pages etc. do appear to stress that the
final conversion of files to .chm is still work-in-progress (with
caveats on alignment etc.).

>> Right, so stop crowing about it FFS and just say HOW TO DO IT. Then somebody
>> else can come along and demonstrate that a .chm is no more difficult.
>
> :-)  I've explained this many times before, and then created a web
> page to stop repeating myself.
>
>   http://fpgui.sourceforge.net/docview_ide_integration.shtml

Relevance noted, will revisit. In that pretty pictcha of yours, should
FPCHELP be decorated with a $ to indicate it's a shell variable?

> My question still stands though. I don't know what is the
> recommendation for "application help" with LCL based applications. eg:
> I create a new project which is a new Programming Editor. I want to
> supply a end-user help file with my binary - like all good software
> does. What help file format do I use (as the developer of that
> product), and how do I create/edit that help file?

[Nod] I suspect that we're not the only people asking for guidance.

> Now if you tell me CHM, that means I need to ship LHelp with my
> product because Linux & Mac users don't have CHM help viewers out of
> the box.

Good point. But at the same time most unix-style OSes can't read .inf,
so one would need to bundle docview or whatever. Which I think suggests
that an important point is having a flexible and foolproof document
generation process, which can produce .inf, .chm or whatever...
basically, any format where a viewer can jump straight to the relevant
section (which specifically excludes .pdf, for this role).

> But what is the source help format for CHM, and what tools
> (help editor) do I use to edit that source format, and what tool do I
> use to "compile" that source help format into the end result CHM file?
> Also, how does my product know where to find LHelp (or whatever CHM
> viewer I want to use)?

[Nod] I suspect that we're not the only people asking for guidance.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Žilvinas Ledas
Hello,

On 2012-07-10 20:40, Mark Morgan Lloyd wrote:
>> But what is the source help format for CHM, and what tools
>> (help editor) do I use to edit that source format, and what tool do I
>> use to "compile" that source help format into the end result CHM file?
>> Also, how does my product know where to find LHelp (or whatever CHM
>> viewer I want to use)?
>
> [Nod] I suspect that we're not the only people asking for guidance.
>

fpc has chm "compiler" classes to make CHM files.
TChmProject is in chmfilewriter unit and TChmWriter is in chmwriter unit
(both in packages\chm\src\).
And there even is a GUI app to make chm files somewhere in Lazarus or
fpc examples :) I don't remember where exactly, because I did make my
own chm help maker application (it took about a day using existing chm
writing functionality) before I discovered that existing one. BTW I
posted my chm maker (app with sources) about two years ago on this (or
fpc) list ;)

Regarding LHelp - I myself package LHelp executable with the main app
and help files so I know that LHelp is besides main app.
You can register your help format system-wide and install LHelp in a
different place from your app - as with any other file viewer your app
may need :)

Regards,
Žilvinas

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Graeme Geldenhuys
Graeme Geldenhuys wrote:
> On 10 July 2012 14:52, Mark Morgan Lloyd
>> <[hidden email]> wrote:

>> Finally, if I just want to add a few lines of plain text as
>> context-sensitive help for a control or form, with the main documentation
>
> Which one is it? Control or Form?  If it's a Control, then it falls
> under the Class / API help, which means XML files must be edited. If
> it is a Form (as in application help describing a dialog in your
> application), then it's something else.

On reflection, in both cases I think I mean context-sensitive help in
the context of an app. In other words: either F1 on say a toolbar button
or an edit field, or a button labeled "Help" which describes a form. I'm
definitely not thinking about documentation for a new control, to be
displayed in the IDE.

I think .chm can be generated from DocBook (hence from e.g. Lyx), but
one is rapidly getting to the point where there is more documentation
software than development software on your computer. I've seen mention
of something called DITA Open Tools but again it appears pretty heavy.

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Mattias Gaertner
Mattias Gaertner wrote:

> On Tue, 10 Jul 2012 17:39:05 +0100
> Graeme Geldenhuys <[hidden email]> wrote:
>
>> Hi,
>>
>> On 10 July 2012 16:40, Mark Morgan Lloyd
>> <[hidden email]> wrote:
>>> You're right, but "bigide" explicitly includes ChmHelpPkg (i.e., if I
>>> understand things correctly, the various viewers) while "all" doesn't.
>
> make bigide does not include chmhelppkg. You have to pass
> OPT=-dUseCHMHelp to do that.

I made using bigide, and the package was in the installed list. I still
had to build lhelp manually.

>> As far as I understand it, that simply registers CHM help with the
>> IDE, and gives the IDE a default location of where to find LHelp. And
>> with newer Lazarus IDE versions, the IDE will automatically try to
>> compile LHelp if the executable doesn't exist. This still doesn't
>> compile/generate any of the CHM help files themselves.
>
> Correct.
> The docs have references to the RTL+FCL docs, which are outside the
> Lazarus sources and have references to programmers guide, which
> requires latex. The whole doc build chain has too many dependencies and
> need several minutes to build. That's not feasible for a simple make
> command.

So what's best to do here: download them as binaries and install where/how?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
In reply to this post by Mattias Gaertner
On 10 July 2012 18:11, Mattias Gaertner <[hidden email]> wrote:
> And there is a feature request to support the new fpdoc notes.
> I don't know the state of the annotation system.

I personally thing that is tackling the problem from the wrong end. I
definitely don't want other peoples annotations in my help documents.
Such functionality needs to be added at runtime by the docs viewer.
Just my 2c.


> I can't help you there.
> Same for what image format to use, what installer to use, what version
> control system or what upgrade system.

OK, then forget about me. :) What help do you use in your applications
-  what help format and help editor do you use?



--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
In reply to this post by Mark Morgan Lloyd
On Tue, 10 Jul 2012 19:45:46 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

>[...]
> > make bigide does not include chmhelppkg. You have to pass
> > OPT=-dUseCHMHelp to do that.
>
> I made using bigide, and the package was in the installed list.

See ide/lazarus.pp
Maybe you are confusing "installed" lists?


> I still had to build lhelp manually.

Check if you have local modifications. In trunk the makefile target
bigide includes lhelp.

 

> >> As far as I understand it, that simply registers CHM help with the
> >> IDE, and gives the IDE a default location of where to find LHelp. And
> >> with newer Lazarus IDE versions, the IDE will automatically try to
> >> compile LHelp if the executable doesn't exist. This still doesn't
> >> compile/generate any of the CHM help files themselves.
> >
> > Correct.
> > The docs have references to the RTL+FCL docs, which are outside the
> > Lazarus sources and have references to programmers guide, which
> > requires latex. The whole doc build chain has too many dependencies and
> > need several minutes to build. That's not feasible for a simple make
> > command.
>
> So what's best to do here: download them as binaries and install where/how?

Download the chm files and put them into "yourlazarus/docs/chm/".

Mattias


--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
In reply to this post by Mark Morgan Lloyd
Hi Mark,

On 10 July 2012 18:40, Mark Morgan Lloyd
<[hidden email]> wrote:
> Relevance noted, will revisit. In that pretty pictcha of yours, should
> FPCHELP be decorated with a $ to indicate it's a shell variable?

No, DocView will handle that automatically. DocView can handle many
types of parameters and all are tested when DocView starts up.  eg: It
queries the environment variables defined on your system for a match.
Yes/No. Query if it is a directory? Yes/No. Query if it is a one or
more help files without the .inf extension (in which case it then uses
a predefined help directory/directories specified by the BOOKSHELF
environment variable)? Yes/No.  Query if it is a full path to a .inf
(with the .inf extension). Yes/No.  If still nothing, simply start up
with no help file loaded.

DocView comes with its own extensive docview.inf application help
file, which explains all this and much more.


> [Nod] I suspect that we're not the only people asking for guidance.

And it seems everybody is reluctant to give an answer. I guess LCL
based applications simply don't ship with help? Well, for the few LCL
based apps I have tried (excluding Lazarus IDE), that sure was the
case.

I just remembered form years ago when I still used Delphi 5 & 7, we
used to use a product called HelpScribble to author our .HLP help
files. HelpScribble now supports .CHM authoring too. So I guess that
answers my own question. You need to purchase a proprietary CHM help
authoring tool to generate your own CHM help, and you'll probably be
limited to author those help files under Windows only.

I'm still fuzzy on how LCL based applications know which CHM help
viewer to use though. This is especially important under Linux & MacOS
because the free CHM help viewers available on those platforms have
vastly different features and functionality. Some don't support
searching, some don't have Index support, some don't support CSS etc
etc. And I'm 100% sure they have different parameter options, so the
LCL app needs to know what it can and can't pass the the CHM help
viewer.


> Good point. But at the same time most unix-style OSes can't read .inf, so
> one would need to bundle docview or whatever.

Correct, and I don't have a problem with that. What I was getting at
is that different CHM help viewers support different features, and
there command line parameters will differ too. So how does LCL based
apps know how to tell each of those CHM help viewers that they must
display Help Topic Index 1234, or Help Topic String 'MyDialog1', from
the CHM help file of application X.

These are the most basic things that need to be address for an
application help to have working application help. Amazing no LCL
developer has come across this yet. Maybe the little bit I know of LCL
is just too little. ;-)


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
In reply to this post by Mark Morgan Lloyd
Hi Mark,

On 10 July 2012 20:42, Mark Morgan Lloyd
<[hidden email]> wrote:
> On reflection, in both cases I think I mean context-sensitive help in the
> context of an app. In other words: either F1 on say a toolbar button or an


OK, then we are thinking of the same thing. :) Context sensitive help
used in our own developed applications.

The subject of "context sensitive help" gets a bit confusing when it
comes to something like an IDE, because in such a case you have
"application help" describing the dialogs of the IDE, and you have
Framework / API help for the programming language you are writing
using the IDE.


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
In reply to this post by Graeme Geldenhuys
On Tue, 10 Jul 2012 21:26:00 +0100
Graeme Geldenhuys <[hidden email]> wrote:

> On 10 July 2012 18:11, Mattias Gaertner <[hidden email]> wrote:
> > And there is a feature request to support the new fpdoc notes.
> > I don't know the state of the annotation system.
>
> I personally thing that is tackling the problem from the wrong end. I
> definitely don't want other peoples annotations in my help documents.
> Such functionality needs to be added at runtime by the docs viewer.
> Just my 2c.

I agree with the locality. The IDE is not a science project or critical
apparatus. Annotations of the LCL docs and probably all packages in the
Lazarus sources should be local.
I don't understand what you mean with "that is tackling the problem
from the wrong end".

 
> > I can't help you there.
> > Same for what image format to use, what installer to use, what version
> > control system or what upgrade system.
>
> OK, then forget about me. :) What help do you use in your applications
> -  what help format and help editor do you use?

So far my other applications never needed an extensive offline help
and therefore I do not dare to give an advice. I leave this to others.


Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Graeme Geldenhuys
Hi,

On 10 July 2012 23:45, Mattias Gaertner <[hidden email]> wrote:
>>
>> I personally thing that is tackling the problem from the wrong end. I
>> definitely don't want other peoples annotations in my help documents.
>> Such functionality needs to be added at runtime by the docs viewer.
>> Just my 2c.
>
> I agree with the locality. The IDE is not a science project or critical
> apparatus. Annotations of the LCL docs and probably all packages in the
> Lazarus sources should be local.

Yes, annotations are a personal thing. I might annotate a help topic I
struggle with, where somebody else could well have thought it pretty
obvious, and needed no further explanation.


> I don't understand what you mean with "that is tackling the problem
> from the wrong end".

I meant, in is not really the fpdoc XML files that need annotation
support, it is the Help Viewers than need the support. The Help
Viewers must be able to add annotations at runtime, store them
locally, and separate from the original help files.

The other problems I can see that will happen with the Lazarus IDE's
FPDoc Editor supporting annotations, is that if those annotations are
stored in the same fpdoc XML files as the LCL, then somebody might
submit those changes with actual LCL documentation fixes. Then the
burden will fall on the Lazarus core team to make sure they don't
accidentally commit such a contribution (somebody's personal
annotations mixed with legit documentation bug fixes) to the
repository.


> So far my other applications never needed an extensive offline help

Lucky you! :)


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Michael Schnell
In reply to this post by Graeme Geldenhuys
On 07/10/2012 05:12 PM, Graeme Geldenhuys wrote:
> If you are referring to the help viewer, then again, that is where
> LHelp lags behind. DocView allows you to annotate (add inline
> comments) any INF files. Those annotations are stored in a separate
> file (<helpfile>.notes), which you can move around or copy with the
> INF file to a new computer if you want. LHelp has no such functionality.

Hmm. While I personally agree, that DocView in many aspects has a lot
advantages, referring to the *big* discussion on that we had in this
forum, I had the impression, that the "powers" decided, that - if any
work is dedicated to improving the help system - that should be done for
a (rather new) method that allows to use (online) Wikis as a source for
offline files providing the advantage that there is a rather
standardized and commonly accepted and ubiquitously available way to
have users improve the help content.

I don't know how far this idea is advanced (e.g. regarding providing
search capability across multiple help "chapters") right now and which
and how offline help content files can already generated that way.

-Michael



--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Mattias Gaertner
Mattias Gaertner wrote:

> On Tue, 10 Jul 2012 19:45:46 +0000
> Mark Morgan Lloyd <[hidden email]> wrote:
>
>> [...]
>>> make bigide does not include chmhelppkg. You have to pass
>>> OPT=-dUseCHMHelp to do that.
>> I made using bigide, and the package was in the installed list.
>
> See ide/lazarus.pp
> Maybe you are confusing "installed" lists?

I mean in the sense of the "If you are using Lazarus from Subversion" in
the
http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE 
page which is cited by the trunk IDE's Help -> Online Help page: the
instructions are accurate (it's only page and link organisation that
I've been querying).

>> I still had to build lhelp manually.
>
> Check if you have local modifications. In trunk the makefile target
> bigide includes lhelp.

Same applies.

>>> The docs have references to the RTL+FCL docs, which are outside the
>>> Lazarus sources and have references to programmers guide, which
>>> requires latex. The whole doc build chain has too many dependencies and
>>> need several minutes to build. That's not feasible for a simple make
>>> command.
>> So what's best to do here: download them as binaries and install where/how?
>
> Download the chm files and put them into "yourlazarus/docs/chm/".

OK, so I get
ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and
unpack. The .txt file says copy the files to docs/html which I'm
assuming is wrong, so I end up with .chm (etc.) files in
/usr/local/share/lazarus-trunk/docs/chm and the Lazarus IDE picks them
up automatically.

Congratulations and thanks to everybody who's worked hard to get the IDE
to this point (and who's put up with my occasionally bull-headed questions).

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
In reply to this post by Graeme Geldenhuys
Graeme Geldenhuys wrote:

>> [Nod] I suspect that we're not the only people asking for guidance.
>
> And it seems everybody is reluctant to give an answer. I guess LCL
> based applications simply don't ship with help? Well, for the few LCL
> based apps I have tried (excluding Lazarus IDE), that sure was the
> case.
>
> I just remembered form years ago when I still used Delphi 5 & 7, we
> used to use a product called HelpScribble to author our .HLP help
> files. HelpScribble now supports .CHM authoring too. So I guess that
> answers my own question. You need to purchase a proprietary CHM help
> authoring tool to generate your own CHM help, and you'll probably be
> limited to author those help files under Windows only.

I didn't make a note of the URL, but I noticed a Debian bugtracker entry
yesterday where somebody was requesting that chmcmd/chmls be packaged
separately since they're the only free tools that do the job.

The bottom line appears to be: generate either XML or HTML files, make a
list of their names, and run the lot through chmcmd to produce a single
indexed file. In principle, it should be possible to postprocess
something like a .pdf to generate very simple context help entries (take
any heading prefixed by e.g. § as a help keyword, and the following
paragraph as the associated text).

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mattias Gaertner
In reply to this post by Mark Morgan Lloyd
On Wed, 11 Jul 2012 08:47:20 +0000
Mark Morgan Lloyd <[hidden email]> wrote:

> Mattias Gaertner wrote:
> > On Tue, 10 Jul 2012 19:45:46 +0000
> > Mark Morgan Lloyd <[hidden email]> wrote:
> >
> >> [...]
> >>> make bigide does not include chmhelppkg. You have to pass
> >>> OPT=-dUseCHMHelp to do that.
> >> I made using bigide, and the package was in the installed list.
> >
> > See ide/lazarus.pp
> > Maybe you are confusing "installed" lists?
>
> I mean in the sense of the "If you are using Lazarus from Subversion" in
> the
> http://wiki.freepascal.org/Installing_Help_in_the_IDE#Installing_CHM_Help_for_The_RTL.2C_FCL_and_LCL_in_the_Lazarus_IDE 
> page which is cited by the trunk IDE's Help -> Online Help page: the
> instructions are accurate (it's only page and link organisation that
> I've been querying).

It is true that the chmhelppkg was included with some binaries and
therefore many users had it preinstalled. But afaik it was never
enabled by default in target bigide.

Try this:
make clean bigide
./lazarus --pcp=testconfig

 
> >> I still had to build lhelp manually.
> >
> > Check if you have local modifications. In trunk the makefile target
> > bigide includes lhelp.
>
> Same applies.

If you don't have a components/chmhelp/lhelp/lhelp after doing a "make
bigide", then please report the bug.

 

> >>> The docs have references to the RTL+FCL docs, which are outside the
> >>> Lazarus sources and have references to programmers guide, which
> >>> requires latex. The whole doc build chain has too many dependencies and
> >>> need several minutes to build. That's not feasible for a simple make
> >>> command.
> >> So what's best to do here: download them as binaries and install where/how?
> >
> > Download the chm files and put them into "yourlazarus/docs/chm/".
>
> OK, so I get
> ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and
> unpack. The .txt file says copy the files to docs/html which I'm
> assuming is wrong, so I end up with .chm (etc.) files in
> /usr/local/share/lazarus-trunk/docs/chm and the Lazarus IDE picks them
> up automatically.

Yes, the paths are a little bit confusing.

Historically the default search path for chm files was docs/html. But
this is a source directory. Mixing svn files and downloaded files is
confusing. It is cleaner to put all downloaded files into a directory if
its own (docs/chm).
The docs/html directory is still in the search path for
compatibility.

 
> Congratulations and thanks to everybody who's worked hard to get the IDE
> to this point (and who's put up with my occasionally bull-headed questions).

:)

Mattias

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Building help files: the nitty-gritty

Mark Morgan Lloyd
Mattias Gaertner wrote:

>>>> I still had to build lhelp manually.
>>> Check if you have local modifications. In trunk the makefile target
>>> bigide includes lhelp.
>> Same applies.
>
> If you don't have a components/chmhelp/lhelp/lhelp after doing a "make
> bigide", then please report the bug.

I'll revisit that on a clean system as soon as I'm able.

>>>>> The docs have references to the RTL+FCL docs, which are outside the
>>>>> Lazarus sources and have references to programmers guide, which
>>>>> requires latex. The whole doc build chain has too many dependencies and
>>>>> need several minutes to build. That's not feasible for a simple make
>>>>> command.
>>>> So what's best to do here: download them as binaries and install where/how?
>>> Download the chm files and put them into "yourlazarus/docs/chm/".
>> OK, so I get
>> ftp://freepascal.stack.nl/pub/fpc/dist/2.6.0/docs/doc-chm.zip and
>> unpack. The .txt file says copy the files to docs/html which I'm
>> assuming is wrong, so I end up with .chm (etc.) files in
>> /usr/local/share/lazarus-trunk/docs/chm and the Lazarus IDE picks them
>> up automatically.
>
> Yes, the paths are a little bit confusing.

I've been working through this several times with the intention of
putting Lazarus docs build (from source) plus FPC docs copy (from
binaries) into my usual build/installation scripts, but am finding that
the FPC (RTL etc.) stuff is only picked up intermittently. Is there a
cache to be cleared somewhere or something comparable?

--
Mark Morgan Lloyd
markMLl .AT. telemetry.co .DOT. uk

[Opinions above are the author's, not those of his employers or colleagues]

--
_______________________________________________
Lazarus mailing list
[hidden email]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
1234 ... 6