Hi again,

since there were multiple complaints about missing documentation, where can I find a list of what is missing exactly in detail?

Is there a wiki page about it? Or a docs page collecting empty descriptions or the like?

Sometimes I'm bored, maybe there are items I'm able to add a couple of useful words to ...

TIA,
Marc

You are welcome.

If you want to write a tutorial about some topic or extend/update one existing, here are the existing:
http://wiki.lazarus.freepascal.org/Lazarus_Documentation

If you want to help with the source documentation, e.g. write some examples or add/extend description, there are fpdoc files. DoDi has added notes for the LCL fpdoc files, where he misses documentation/clarification. See lazarus/docs/xml/lcl.

Many other packages in the Lazarus sources need fpdoc entries too.

If you want to write some help about an IDE dialog: Use F1 to open the wiki page. If it does not open, or opens the wrong page, just write an email, so I can fix it.

Mattias

You can checkout e.g. rev. 34110, and search for "?]" in the xml files. These are the places where I couldn't find reliable infos myself.

DoDi

There were all converted to <notes>, were they not?

Mattias

> You can checkout e.g. rev. 34110, and search for "?]" in the xml files. > These are the places where I couldn't find reliable infos myself. There were all converted to <notes>, were they not?

Even if so, moving a note out of its context invalidates the note.

E.g. "the following doesn't look correct" is quite meaningless, when followed by nothing.

Or what's this:
<notes><note>!?</note>
</notes>
instead of
<descr>The overridden method may fail when the
TScrollingWinControl has only one scrollbar[!?]
</descr>

DoDi

Mattias Gaertner wrote

If you want to write some help about an IDE dialog: Use F1 to open the wiki page. If it does not open, or opens the wrong page, just write an email, so I can fix it.

If this happens rather often this is no possible way to go.

And it it does open: Is the helpful user supposed to use the wiki to improve the help text ? This would make the Wiki database the primary help source. I seem to remember that exactly this was discouraged in the recent "big" discussion on "offline help".-

-Michael

I do hope people use the provided help often.

And it it does open: Is the helpful user supposed to use the wiki to improve the help text ? This would make the Wiki database the primary help source.

It is since many years.
Have you seen any secondary help for the dialogs?

I seem to remember that exactly this was discouraged in the recent "big" discussion on "offline help".-

Maybe the discussion was mainly lead by people that "discourage" without doing something.

Mattias

Mattias Gaertner wrote

It is since many years. Have you seen any secondary help for the dialogs?

I don't understand what you mean. I think there should be single source for online and offline help. Everything else obviously is not manageable at all. (In fact I don't see how a Wiki can be part of this as - AFAIK - there is no solution for exporting or importing wiki database content for other formats. )

Maybe the discussion was mainly lead by people that "discourage" without doing something.

(I don't remember who said this, but I believe it was one from the "core-team".)

Unfortunately creating / improving the help creation and help viewing infrastructure is a rather complicated and far reaching issue that only can be managed by the core team. (Many thanks to DoDi for trying to get involved!). Using this infrastructure (if decently workable) to help to improve the documentation, non-core-team persons would be able to improve the product.

-Michael

Michael Schnell wrote

(Many thanks to DoDi for trying to get involved!).

Many thanks to Graeme as well !

-Michael

Mattias Gaertner wrote

Have you seen any secondary help for the dialogs?

How do you hook into the IDE dialog help system? Is this by registering yet another help package? How would the IDE decide between a HTML, CHM or INF help system for the dialogs in the IDE?

Also what HelpType does the IDE dialogs use? HelpContext or HelpText? Is there a specific naming conversion for the HelpContext or HelpText values in the various IDE dialogs?

Where is this documented? I couldn't find such information on the wiki (as usual).

Mattias Gaertner wrote

Have you seen any secondary help for the dialogs?

And, what's the point is me doing an HTML (from the wiki) to INF conversion, and then the next day somebody updates the wiki pages again. The INF (or CHM) help would always be out of date. So why should I bother doing the conversion work, when the Lazarus core team is NOT interested in a offline help solution. Until an official statement is being made that says something like "The Lazarus project is now moving away from online-only wiki help, to a much improved offline help system.", I'll not lift a finger, because my time and effort would be wasted.

I started it.

Have you even tried to edit wiki or use the fpdoc editor?

What needs improving is packaging the help and
creating the offline help.

Mattias

Yes.
There are some open issues. I'm working on this.

How would the IDE decide between a HTML, CHM or INF help system for the dialogs in the IDE?

Whatever the user installs.

I'm currently working on this.

Mattias

Mattias Gaertner wrote

I started it.

Please elaborate.

Is the wiki supposed to be the upcoming help source, thus invalidating FPDoc and friends ?

In fact I don't have a decent opinion on whether this is a good idea, but I do recommend considering the implications (including calculating a timeframe for making the transition i.e. importing all FPDoc generated files into the wiki, providing tools for importing the Pascal sources in a way FPDoc does, exporting The Wiki content to (what ??) offline help viewer, managing comments or "levels" in the viewer for allowing the help writers to decently organize their work - as an svn, allowing local modifications, for the wiki content is not available).

Have you even tried to edit wiki or use the fpdoc editor?

Re Wiki:
Up til now I did not know that the Wiki is even considered as the main help content source, so why do any modifications there which will die quite soon ?

Re FPDoc:
Why should I do this, if I am not able to create help viewer files that allow me to view my modifications and be sure that I did not destroy anything ?

-Michael

Not having top priority and being "NOT interested" are two different things. AFAIK everyone agreed that having all help offline would be nice feature.
The wiki is frequently edited by many people and already contains more than 2500 pages. It makes no sense to shut it down.

Mattias

This is nice (for the moment). But of course there need to be means to automatically keep the different options in sync.

I'm currently working on this.

This does sounds good (even if not many information on this is available right now).

In fact I don't understand why you did not mention this up til now ? (Or did I just miss it ?)

-Michael

Mattias Gaertner wrote

The wiki is frequently edited by many people and already contains more than 2500 pages. It makes no sense to shut it down.

But if there is no way to keep it in sync with the FPDoc files, how is the future of either considered to be ?

-Michael

On 02/29/2012 11:10 AM, Mattias Gaertner wrote: > I started it. Please elaborate.

I started a tool to download the wiki and convert it to other formats. I'm still evaluating possibilities.

Is the wiki supposed to be the upcoming help source, thus invalidating FPDoc and friends ?

Are you kidding?
fpdoc is great.

There are many possibilities. Abandoning fpdoc is none of them.

You must be kidding.

Re FPDoc: Why should I do this, if I am not able to create help viewer files that allow me to view my modifications and be sure that I did not destroy anything ?

Showing is simple: Just move the mouse over an identifier. About destroying: You apparently have not tried it.

Mattias

Graeme Geldenhuys wrote

And, what's the point is me doing an HTML (from the wiki) to INF conversion, and then the next day somebody updates the wiki pages again. The INF (or CHM) help would always be out of date.

I think it would be perfectly fine to generate 1 new offline IDE CHM for each release and ship Lazarus with it. The release won't change anyway, and the IDE dialogs can change, so it is not desirable to use the latest docs with a released Lazarus. If you can contribute something which can generate such a wiki to CHM conversion, then I suppose it could be repeated in the future with much less work then the first time.

For SVN users the best option would be the wiki still.

Felipe Monteiro de Carvalho wrote

If you can contribute something which can generate such a wiki to CHM conversion, then I suppose it could be repeated in the future with much less work then the first time.

Aha, I missed that Mattias is already working on it =) So I would rephrase to contribute with Mattias then instead of starting a newer wiki->chm convertor

FPDoc Wiki

FPDoc is about documentation of the source code, documentation of the LCL, etc.

The Wiki is used for documenting e.g. the usage of the IDE. You can't do
this using FPDoc.

Regards,
Sven

Mattias Gaertner wrote

Is the wiki supposed to be the upcoming help source, thus invalidating FPDoc and friends ? Are you kidding? fpdoc is great.

There only can be a single source for the help so either FPDoc or directly managing the Wiki kontent "is great" not both.

There are many possibilities. Abandoning fpdoc is none of them.

If you say so a will not disagree at all.

It dies at least as soon as somebody generates / uses offline help files.

Showing is simple: Just move the mouse over an identifier. About destroying: You apparently have not tried it.

I talked about showing / seeing my modifications.

I will not ever try to do any modifications unless I am able to see the result "life". And I did invest a decent amount of time trying to generate offline help from the svn sources and failed multiple times (in action with DocView, even trying to find out how this should be done with CHM.)

Supposedly I am just too stupid for this task :(

-Michael

Sven Barth wrote

The Wiki is used for documenting e.g. the usage of the IDE. You can't do this using FPDoc.

This would mean that there never will be any offline help for Lazarus users.

That would really be a bad thing.

-Michael

No, as I wrote the two are the source for two different kinds of help.

It won't, because the Wiki is the source for this kind of help and where editing takes place.

> Showing is simple: Just move the mouse over an identifier. > About destroying: You apparently have not tried it. I talked about showing / seeing my modifications.

The IDE parses the XML files. So as long as you did not move the edited file out of it's original location the IDE will display you your modified help.

Regards,
Sven

Felipe Monteiro de Carvalho wrote

I think it would be perfectly fine to generate 1 new offline IDE CHM for each release and ship Lazarus with it.

This discussion is about how to enable non-core members to help improving the docs.

Your claim would prevent this as the doc writers would not be able to review their own work.

-Michael

Felipe Monteiro de Carvalho wrote

For SVN users the best option would be the wiki still.

Resulting in their work never can be included in the offline help.

Very bad.

-Michael

Sven Barth wrote

It won't, because the Wiki is the source for this kind of help and where editing takes place.

I am sure that this will lead to perfect confusion and help content for ever unusable (for logical causes not for technical ones.)

-Michael

You mean, you are not able to do this.

I perfectly can, so can mattias, and presumably even DiDo can do it.

That your changes are not distributed at once after you've submitted them is another matter entirely.

Michael.

Why do you say that? Once a relese is about to be done the current versions of the wiki pages are converted to help files and provided as offline help. SVN users will use the Wiki pages directly, as they can change rather often in theory (of course nightly snapshots could be provided for those that can't be always online).

Regards,
Sven

Did you read Matthias' answers? He wrote that he's working on a tool to export the Wiki entries for e.g. CHM, so this is not a problem...

Regards,
Sven

That your changes are not distributed at once after you've submitted them is another matter entirely.

Submitting of course is another matter. I vote for a review by some kind of "committee" before submitting.

This is what svn is invented for: the changes are done locally, they are "compiled" and can be viewed in action. Submitting can be done by the normal svn means.

-Michael

Sven Barth wrote

(of course nightly snapshots...

Maybe automatic nightly snapshots fed into the svn might be more workable for potential doc writers than being able to decently review their work with the next "release", but anyway, splitting the help proceedings in two completely different source trees seems rather chaotic to me.

-Michael

Sven Barth wrote

Did you read Matthias' answers? He wrote that he's working on a tool to export the Wiki entries for e.g. CHM, so this is not a problem...

So some part of the offline help is produced by FPdoc and thus "privileged" (an non-core member of the community can't work on this) and other part is generated from the Wiki. The second thus can be worked on by "normal" members, but they will not be able to see (and search) the result in the offline help as same will be regenerate some day in the future.

To me this scenario is quite horrible and totally disappointing for any possible doc writer.

-Michael

Michael already wrote in one of the recent discussions that he wants to create a webpage (using fpweb of course ;) ) that will allow to edit the FPDoc help entries (I'll try to find the mail).

Also there is always the way that works today: edit the entry yourself and provide a patch.

Once you've shown enough interest in documentation work you might be granted SVN access to the documentation directory.

Regards,
Sven

Where did you see that fpdoc is priviledged ? Anyone can download and work on it, and submit patches.

Michael.

To me this sounds totally wrong. I will not provide a patch for something that I can't decently review first. This wastes the time of the reviewing "core member".

-Michael

The nightly snapshots were meant for the help users (not the contributors). Also I'm talking about the Wiki pages about e.g. IDE usage here. The contributors for those help pages should always work with the Wiki.

Contributors for source documentation need to edit the fpdoc files (e.g. those from the SVN checkout) and commit the changes (either as patch or directly if they have SVN write access).

Regards,
Sven

Where did you see that fpdoc is priviledged ? Anyone can download and work on it, and submit patches.

See my answer to Sven.

-Michael

Sven Barth hat am 29. Februar 2012 um 12:08
geschrieben:

There is no big difference between a link from one fpdoc file to another (e.g. LCL to RTL) and between a fpdoc element and a wiki page. If one of them changes you have to update references. Sometimes you have to update references even though target and source itself have not changed, e.g. something new has popped up.
Of course for a few special cases support tools can be written, but in general it needs manual work.
Documentation is not type safe like Pascal.

Well, at least not that comfortable.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/0d504de4/attachment.html>

Sven Barth wrote

Contributors for source documentation need to edit the fpdoc files (e.g. those from the SVN checkout) and commit the changes (either as patch or directly if they have SVN write access).

Regarding that this discussion started in the issue how to allow more contributors to enhance the documentation and thus improve the situation of the "Missing Documentation" (see subject), IMHO this goes in the wrong direction.

-Michael

Do you simetimes actually listen to what we say here ?

You can perfectly review your changes in at least 2 ways:

1. Hover the mouse over the identifier in the IDE. The IDE will show you the updated entry of fpdoc.

2. Simply generate the docs in whatever format you want. If DoDi can, then so can you. It's not black magic, it's using Dodi's tool, makefiles or in the worst case write a batch file that generates the docs for you.

All needed tools are in subversion. Generating HTML docs is very easy. All you need is fpdoc. It is even documented, would you believe it...

Michael.

Michael Schnell hat am 29. Februar 2012 um 12:25
geschrieben:

[...] There only can be a single source for the help

Where do you get this attitude?
You are using open source, you should know better.

[...] > Showing is simple: Just move the mouse over an identifier. > About destroying: You apparently have not tried it. I talked about showing / seeing my modifications.

Michael, PLEASE try to use the tools before complaining about them. The hints were always showing the current fpdoc files.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/20bac415/attachment.html>

Do you simetimes actually listen to what we say here ?

Seemingly I misunderstood and you are right to be angry .

The IDE knows the files FPDoc writes ? This is so advanced that I never considered it. I'll try ASAP. (Marking your mail as "important")

What I tried to accomplish was doing an addition to the LCL and the RTL offline help. I do admit that when Graeme (unsuccessfully) tried to lead me through the process of generating all those inf files for FPDoc, I did not decently try to generate CHM files (learning not before recently that the IDE in fact can search multiple of those in one action).

sounds nice :)

-Michael

Michael Schnell hat am 29. Februar 2012 um 12:57
geschrieben:

Is it just me or are your excuses for not-contributing getting desperate?

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/9c9b0bd4/attachment.html>

As already written:
* either use the editor hints of the IDE which work on the FPDoc files in %laz%\doc\xml
* or build the help files yourself

Regards,
Sven

As I already wrote in another mail Michael Van Canneyt plans to write a webpage which allows for easy contributions to the FPDoc based documentation.

Here is a link to the mail:
http://lists.lazarus.freepascal.org/pipermail/lazarus/2012-February/070600.html

Regards,
Sven

Obvious best option: * do nothing.

-Michael

Sven Barth hat am 29. Februar 2012 um 13:42
geschrieben:

yourself

It works on all fpdoc files of all Lazarus packages (e.g. tachart, ideintf).
If you add the path to the fpdocs svn it will work for RTL and FCL too.

* or build the help files yourself

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/8287e62e/attachment-0001.html>

Michael Schnell wrote

offline help from the svn sources and failed multiple times (in action with DocView, even trying to find out how this should be done with CHM.)

I created new LCL help in INF format over the weekend, using fpdoc from latest 2.7.1. The only issue I came across was due to a malformed xml file in LCL. I minor tweak, splitting one line into two lines by pressing Enter, of the generated lcl.ipf file, and I could compile that to a binary INF file - no problems.

I have no idea what was all the fuss a week or two ago about restructuring the LCL help. Maybe it is something specific with HTML output, but I didn't experience any real issues with the IPF output.

The new INF help generated from fpdoc files, now have a nice hyperlinked class hierarchy as well with each class description. A patch for fpdoc will be supplied soon.

Supposedly I am just too stupid for this task :(

That could possibly be. ;-)

Graeme Geldenhuys wrote

The new INF help generated from fpdoc files, now have a nice hyperlinked class hierarchy as well with each class description. A patch for fpdoc will be supplied soon.

It's a bit frustrating to see Graeme, DoDi, Sven and others try to improve the help itself and especially the help generation process, while I can't see the common "final goal" in focus (one or more online and offline versatile help viewers / file formats being fed and automatically synced from a well defined source tree for all issues (help on help, ide, compiler, language, rtl, lcl, user additions, ...)

-Michael

[ I apologise if I sound frustrated with you, but it probably is because I am. ]

* fpdoc is well documented. So usage should not be a problem.
* LCL, fpGUI etc all come with easy scripts to generate the class documentation in various formats.
* RTL, LCL docs come as pre-built binary help for your convenience, but you can build them yourself too. That too is documented.
* Docview (binary release download) includes the docview.inf help file, describing in
detail every feature of docview (thus help on help). It even includes a section called
"For Authors and Developers", where it again explains in detail how to use the IPF
Compiler to compile your IPF help source into binary INF help files.

THIS IS NOT ROCKET SCIENCE!

RTFM

None of this is an excuse for not contributing.

If you contribute now, by the time we come to a final version/solution, there will be lots of help included. Your work will not get lost if it is submitted and checked in.

As it is now, you don't contribute, wait for a final version to start contributing. Meaning that the 'lots of help' will be there only much later (if ever).

Even the work of DoDi on notes has not been lost. It was simply converted to the existing solution. Mattias went to great lengths to achieve that. One can only admire his patience and willingness to help.

So please stop mailing and actually start coding or documenting.

Michael.

Graeme Geldenhuys wrote

[ I apologise if I sound frustrated with you, but it probably is because I am. ] ...

No wonder regarding That I do complain about missing tools but don't have the the resources to decently follow the different paths suggest by you and others and try out all the new features currently under development / consideration.

(As I in fact right now don't have any urge to actually _use_ Lazarus) I'll try to keep my mouth shut and just watch what might come up and will test ASA something seems to have stabilized.

Maybe then I can actually try to do the (very minor) contributions to the documentation I have been planning (as you know) .

-Michael

None of this is an excuse for not contributing.

You are perfectly right, but ... (see my answer to Graeme).

-Michael

This IMO is a bad idea, as long as many Lazarus versions are used concurrently, with different dialog content :-(

DoDi

Not having top priority and being "NOT interested" are two different things. AFAIK everyone agreed that having all help offline would be nice feature.

ACK

The wiki is frequently edited by many people and already contains more than 2500 pages. It makes no sense to shut it down.

Nobody asked to shut down the wiki. But since it can be used only while online, the wiki should *not* be the primary source for context sensitive help.

Disregarding users like Graeme, who AFAIR is almost working offline, is another reason that prevents Lazarus from becoming more widely recognized and accepted.

DoDi

Oh Herr, schmei? Hirn ra!

Dear Michael, you're disqualifying yourself with such inappropriate questions :-(

Please try to understand first, that FPDoc is the only source for *code documentation*, and that all changes to the XML files are reflected immediately, in the FPDoc editor and hint windows. Every user can update these files and submit the patches.

WRT to offline documentation (by F1), every user is responsible for updating his local help himself.

DoDi

I'm sorry, but then I suggest you stop bothering the list with your posts...

People have been bending over backwards to explain to you the various options and you just don't want to accept any of it.

You don't want to contribute patches, you don't want to edit wiki pages, anything other people suggest is a problem.
Perhaps it's best if you start your own project, become wildly succesful and show us how things should be organized.

I have some problems with certain documentation aspects as well, but I try to help (submit documentation, patches to lazdoceditor)...

You seem to assume some kind of privileged group is out to keep everybody from improving form and content of the help, while I think that getting used to the way things are done takes some time but is perfectly acceptable.

Seems you're not interested in working with people but want things to be done your way... shame.

Hope you can see your way clear to get that help going and contribute something...

Regards,
Reinier

Mattias Gaertner wrote

Is it just me or are your excuses for not-contributing getting desperate?

I think I'm seeing a fair amount of miscommunication going on in this thread. I think that's the more likely reason why it goes on.

Again: please try to understand first, before writing nonsense :-(

As long as the IDE help is wiki-based, every user can edit the wiki, and he and all other users will see the changes immediately.

When this help is converted into FPDoc format, some day, the same procedure applies as to all XML-based documentation: every user has the files on his machine, and can update them locally. In the case of IDE help it may be required, then, to rebuild the local docs. This can be done for single HTML files almost instantly, while rebuilding entire CHM files requires more time, obviously.

DoDi

Please specify what *exactly* you feel missing, *after* becoming more familiar with the *current* state, not based on weird assumptions :-(

DoDi

Reinier Olislagers wrote

I'm sorry, but then I suggest you stop bothering the list with your posts...

Agreed.

- Michael

+1

Reading about this type of confusion - count me in - I need to ask:

Where is the process of building up help files documented? Seen from my current knowledge there are many new tools and facts I do not know or understand.

If not already done or trivial, I'd suggest writing or better drawing a chart of the targets, sources and tools to use when wanting to write documentation.

Although this may sound ugly to some of you, some sort of graph with notes and explanations would be very easy readable and understandable.

For now I stepped back to something that came to my mind very early as a task attractive for me. Taht is writing some (short) tutorials on topics where I myself have had problems understanding inner workings of components or documentation already written.

Graeme Geldenhuys wrote

On 29 February 2012 15:36, Michael Schnell wrote: [ I apologise if I sound frustrated with you, but it probably is because I am. ]

LOL

Hm, for me it looks like it is. And I'm not a total newbie.

The only type of project management stuff needed is some quickly understandable documentation about the processes that are used.

Developers of ?lazarus do know, they use it. For me as a user of lazarus, using it to make progrms and source libraries, it is pretty confusing to follow the threads about these non documented workflows.

Where is the process of building up help files documented? Seen from my current knowledge there are many new tools and facts I do not know or understand.

In the source directories, i.e. in $fpcdocs (wherever you checked it out), or in Lazarus/docs/html. The procedures vary, depending on the platform.

If not already done or trivial, I'd suggest writing or better drawing a chart of the targets, sources and tools to use when wanting to write documentation.

See e.g. http://wiki.lazarus.freepascal.org/Lazarus_Documentation, in detail "7 Missing documentation?"

Although this may sound ugly to some of you, some sort of graph with notes and explanations would be very easy readable and understandable.

Right, but I don't want to contribute to the wiki, because it is too unstructured, and I cannot find in it what I need :-(

DoDi

Marc Santhoff hat am 29. Februar 2012 um 17:54
geschrieben:

You are welcome to ask.
I hope your confusion is a completely different one.

Where is the process of building up help files documented?

The hints use the fpdoc files, which are simple text files, which can be edited by the fpdoc editor or lazde or the source editor.

What process do you mean?

Seen from my current knowledge there are many new tools and facts I do

not know or

understand.

What new tool are you speaking of?

Great!

Have you seen the tutorials in the wiki?

You may extend an existing or add a new.

Because of spammers, the wiki requires to register an account. That's all you need to write a tutorial.

Mattias

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/6d7f4bfd/attachment.html>

<g> Hopefully yes. ;)

(note to myself: wash your keyboard with soap for making naughty jokes)

I'm talking of the big picture, what type of sources are used, which tool is available and what does it do, ...

Not on detail level, but there seem to be misunderstandings regarding the overview. But I'll have to review existing material in a more organized and systematic manner to name whats missing exactly.

One name I remember (from huge masses of emails) is FPDocManager. Is that a class or a tool?

Yes.

You may extend an existing or add a new. Because of spammers, the wiki requires to register an account. That's all you need to write a tutorial.

Done.

Don't expect some results tomorrow. ;)

I'm not oinly thinking of myself here, in parallel stepping in for new contributors is targeted. If anyone wanting to help has to ask first, then there is some part of the documentation missing, me thinks.

Will read thoroughly, thanks.

That's what I was saying, there could be some index pages. But after looking ati those index pages are already there, you named one. No idea of a better organization of the wiki yet ...

An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/bfb89c4c/attachment.html>

Marc Santhoff wrote

Developers of ?lazarus do know, they use it. For me as a user of lazarus, using it to make progrms and source libraries, it is pretty confusing to follow the threads about these non documented workflows.

All the various documentations I mentioned at least have some readme file in the related directory explaining how each is used. Yes, it's not a 300 page book, but it is basic instructions on how to generate documentation for each of RTL, FCL, LCL, etc. All you need to do, is browse the folder, find the readme file, read it and follow the instructions. How else did I figure it out.

I asked this question in the FPC mailing list a few hours ago, and I am here to ask the same question about Lazarus. Hopefully I won't press the Send button in Gmail before I finish.

It is becoming obvious as shown in this thread that good documentation about Lazarus Documentation and more importantly the process, tools and procedures by which it is generated is lacking and that together with some documentation about how the Lazarus project itself is organized is necessary before any meaningful and friction free progress can be made. I have thought about starting a new thread but this one seems as good as any.

1. Are they created by a tool or hand edited? what are the tools used?

2. Is there some page where the original docs are created?

3. Are they text files that are stored under version control?

4. Is there some page where previous versions are available?

5. How is it structured, what are the formatting rules? Is based on standards like DocBook etc?

6. How much of the documentation is generated from the source code? Is information about input and output parameters, and a few lines about its usage and gotchas generated from source, or does all procedures need to be documented by hand using FPDoc? Graeme mentions IPF that in his view does a better job? Do other preferably Pascal based projects use other tools with which they have had more success?

7. Are there other tools that can do a better job, such as Jira, Github etc?

8. I assume that docs are generated by some build tool once created. Does the submitter compile the docs on their own system and test that they are fine before getting them committed into the repository? Are the tools used identical (I see messages in the mailing list about contributors being using different versions of the tools)?

I guess these are the questions I want to ask.

One name I remember (from huge masses of emails) is FPDocManager. Is that a class or a tool?

It's a project in examples/fpdocmanager. It shall allow even newbies to create their own local documentation. It also allows FPDoc documentation writers to create skeletons for packages or projects, and to syntax check their updates. These are what I was missing most, when working on the documentation myself.

DoDi

(Not that I'm volunteering, mind you, but ...)
Is it possible to get a listing of all of the wiki pages?

Every time I search the wiki or get terse responses to my questions (ie: RTFW - read the FINE wiki), I suspect there is a lot more info in the wiki than I find with my search queries.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/c4fa9ebb/attachment.html>

A complete index, yes. To the right on

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

under the headline "Navigation" there is a link to it. But you have to type in at least one char to see something, because there are so much pages that a full a-z index would be far too huge to show in one page.

Example for typing only an "a" and hitting search:

http://wiki.lazarus.freepascal.org/index.php?title=Special%3AAllpages&from=a&namespace=0

Sonds promising, I'll try it.

Thank you.

The results are very strange. Entering "documentation" finds almost all pages, because these have this keyword in the headline and navigation menu.

The search should be restricted to the *body* of the pages, excluding the framework.

DoDi

I used index to search for "VST" and the first links ("Var", "Varies") did not contain "VST".
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/154d8be9/attachment.html>

Duh - ignore me - Index shows the results STARTING AT the entered value string.

I agree - the results are strange. I used index to search for "VST" and the first links ("Var", "Varies") did not contain "VST".

Tried "Documentation" with a capital at the start?

That thingy is case sensitive ...

Hans-Peter Diettrich wrote

The results are very strange. Entering "documentation" finds almost all pages, because these have this keyword in the headline and navigation menu.

It even finds result pages where the entered word doesn't appear _anywhere_ in the wiki page. Not the header, not the navigation, not the body. See my example about "freebsd" and the tiOPF result page.

The wiki is utterly useless and broken!! If you don't know the directly link to what you are looking for, chances are you will never find it.

1. Are they created by a tool or hand edited? what are the tools used?

Source documentation is generated using FPDoc. The tool makeskel parses the source file and generates a xml file which the documentation will reside in.

Documentation for e.g. IDE usage is done in the Wiki.

2. Is there some page where the original docs are created?

Sorry, I don't understand what you mean here.

3. Are they text files that are stored under version control?

As already written on the FPC list, the files are XML files available in Subversion.

4. Is there some page where previous versions are available?

Released versions are available through downloads and a finer grained control is available through Subversion.

5. How is it structured, what are the formatting rules? Is based on standards like DocBook etc?

It's a custom XML format.

The skeleton is created using a tool, the rest is up to the persons documenting the code.

IPF is only one of the possible formats that the XML documentation can be generated to. Other examples are TXT, RTF, PDF, HTML and CHM (the latter being supported by the text mode IDE and in Lazarus through lHelp (which is distributed with Lazarus as source)). The text mode IDE can also use IPF files.

7. Are there other tools that can do a better job, such as Jira, Github etc?

GitHub has nothing to do with generating documentation. I don't know about Jira. Also FPDoc is working quite well, also it's under ower complete control, so we don't need to wait for some third party developer to extend the syntax his tool understands if we extend FPC by another language feature (hint directives and generics are nice examples).

They are built locally. There should be no major differences if they are built on different systems if the tools are setup correctly.

Regards,
Sven

Graeme Geldenhuys wrote

The wiki is utterly useless and broken!! If you don't know the directly link to what you are looking for, chances are you will never find it.

lol! Only if you don't know how to use Google. It flawlessly finds everything I need by searching for "lazarus wiki searchterm".

Op 1 maart 2012 08:12 heeft Graeme Geldenhuys
het volgende geschreven:

I guess you mean: I cannot use the wiki. Or: the index page doesn't work like a search page. Or: the textbox on the index page doesn't work like I expect.

In that case, you should not use the wiki, but it is not broken.

If you type in freebsd, it shows a page with all pages whose name start with freebsd or are later in the alphabetically, case sensitive sorted index of pages. It doesn't say anything about the contents of the page, just about its name.

Vincent

Marc Santhoff wrote

Reading about this type of confusion - count me in - I need to ask: Where is the process of building up help files documented?

In fact (after the work in progress has stabilized), the documentation should be quite short. Hopefully, finally, there should be a script to be called (with a limited count of parameters) that in one call creates all files for a selected help viewer (DocView, CHM, HTML, PDF, ... ???) for all "chapters" (like IDE, Language, RTL, LCL, ...) from the available sources (Sourcefiles, FPDoc XML, Wiki). Just dreaming ?

-Michael

Marc Santhoff wrote

> THIS IS NOT ROCKET SCIENCE! Hm, for me it looks like it is.

At least I feel that (regarding the initial thought that dives this thread) a quite "normal" User who wants to help improving the Documentation will be frustrated.

-Michael

Felipe Monteiro de Carvalho wrote

lol! Only if you don't know how to use Google. It flawlessly finds everything I need by searching for "lazarus wiki searchterm".

Totally defeats the point of the Search and Index features on the wiki then, doesn't it?

In that case, could we ask the wiki maintainers to please disable the wiki Search and Index functions, and rather embed a Google Search in it's place.

Graeme Geldenhuys wrote

In that case, could we ask the wiki maintainers to please disable the wiki Search and Index functions, and rather embed a Google Search in it's place.

Yes, that would be a great solution. Unfortunately I don't have access to the wiki server, and I am not sure who has.

Ah, now the results are significantly better. But why?

Does a capital character have a special meaning in a search?

That thingy is case sensitive ...

Somewhat, yes, but the proper formulation of search requests is unclear to me. It looks to me as if *all* pages are listed, when a search cannot find any exact match?

DoDi

Either case indicates the lack of a description, required to use an existing feature. This is one more example of the different viewpoints of implementors and users. When an implementor *believes* that no documentation is required, he may be the only one who ever uses his great invention.

If you type in freebsd, it shows a page with all pages whose name start with freebsd

No such pages exist, all names start with a capital letter.

or are later in the alphabetically, case sensitive sorted index of pages.

What is "are later"? All pages starting with 'g'..'z'?

It doesn't say anything about the contents of the page, just about its name.

This finally makes some sense.

DoDi

Op 1 maart 2012 14:28 heeft Hans-Peter Diettrich
het volgende geschreven:

Lack of reading the label, or lack of understanding what means "Display pages starting at:"
Remember: this is the *index* page. The text part asks you what part of the index to show.

False:
e.g. http://wiki.lazarus.freepascal.org/fcl-base

Yes, but not A .. Z and a .. e.

Glad you understood.

Vincent

That's true. The easy solution would be to write some short rules above or below the search field, about how the index search works.

I'd like to see a reminder, tending to forget this works a bit different...

No, but wiki names are CamelCase.

I don't know, only played around a bit.

If this is a standard MediaWiki search engine, the docs of MediaWiki would help.

Is it MediaWiki's search engine? If not, which one?

Googling brought up this link -
http://www.mediawiki.org/wiki/Extension:Google_Custom_Search_Engine

Who is the webmaster of the wiki and can this be forwarded to him?

Op 2 maart 2012 00:04 heeft Frank Church het
volgende geschreven:

Googling brought up this link - http://www.mediawiki.org/wiki/Extension:Google_Custom_Search_Engine Who is the webmaster of the wiki and can this be forwarded to him?

I was, but I want to stop doing it.

Vincent

That's disappointing, but could you at the very least add the Google Search Option, before you quit, PLEASE? :)

Op 2 maart 2012 09:39 heeft Frank Church het
volgende geschreven:

That's disappointing, but could you at the very least add the Google Search Option, before you quit, PLEASE? ?:)

I think the most honest answer is: no.

Vincent

Is anybody else lined up to take over?

Richard

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120302/7acbdf1f/attachment-0001.html>

Op 2 maart 2012 10:27 schreef Richard Mace het
volgende:

Is anybody else lined up to take over?

I don't know.

Vincent
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120302/3b5cf55f/attachment.html>

I'll be happy to do it.

I have silently benefitted from other peoples work on Lazarus/FreePascal for years, and maybe it's time to give some back.

Let me know ....

Samps Okholm
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120302/6a823d35/attachment.html>

Richard Mace
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120302/24e4021e/attachment.html>

Mattias Gaertner wrote

There is no big difference between a link from one fpdoc file to another (e.g. LCL to RTL) and between a fpdoc element and a wiki page.

1. One can be offline, the other not.
2. One is versioned per lazarus version, one is not.

You can make offline snapshots of the wiki.

2. One is versioned per lazarus version, one is not.

A release could have snapshots of both.

BTW:
The update problem already exists in the offline version of the LCL. There are already outdated links and examples.

Mattias

Mattias Gaertner wrote

> > 1. One can be offline, the other not. You can make offline snapshots of the wiki.

Ah, that is working again? Since when?

And how do I show it? Probably extracting the contents and properly relinking and indexing it needs to be redone after each wiki migration.

"wiki" is not an abstract format. Even microsoft word would be better, at least that is COM automatable.

> 2. One is versioned per lazarus version, one is not. A release could have snapshots of both.

That is not the same thing. A zipped copy is not the same as a branch.

BTW: The update problem already exists in the offline version of the LCL. There are already outdated links and examples.

There is a problem yes. But at least in theory, one could merge back doc fixes from trunk to a fixes branch for the next fixes release.

Admitted, neither does FPC, but Lazarus even lacks the theoretical base for this.

Marco van de Voort hat am 28. M?rz 2012 um 16:59
geschrieben:

A db dump is still disabled.
But with a small tool you can download the pages (in wiki format) and images. A chm converter basically works.

> And how do I show it? Probably extracting the contents and properly relinking and indexing it needs to be redone after each wiki migration.

The tool already does the linking.
I also implemented a simple search, which IMO already is quite useful.

The main problem is that currently ipro lacks many html/css features. And many pages have bugs and non portable tags. These need fixing. I guess a full week, which I don't have, because 1.0 bug has higher priority.

If someone wants to help, write me a mail.

"wiki" is not an abstract format. Even microsoft word would be better, at least that is COM automatable.

True.
But it is sufficient for a release.

In theory changed wiki pages can be merged back too. It's a simple xml file per page.

Admitted, neither does FPC, but Lazarus even lacks the theoretical base

for

this.

Mattias

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120328/dc9ac68f/attachment.html>