Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

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

> On Wed, Mar 28, 2012 at 09:54:01AM +0200, 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?


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.



>  > > > 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.


True.
But it is sufficient for a release.



>  > > 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.


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marco van de Voort]

On Wed, Mar 28, 2012 at 09:54:01AM +0200, 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.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

On Tue, 27 Mar 2012 20:46:32 +0200
Marco van de Voort  wrote:

> On Wed, Feb 29, 2012 at 01:00:08PM +0100, 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.

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
 

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marco van de Voort]

On Wed, Feb 29, 2012 at 01:00:08PM +0100, 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.


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Richard Mace]

>
>  Is anybody else lined up to take over?
>>
>
> I don't know.
>
> Vincent
>
>
> --
> ___
> Lazarus mailing 
> listLazarus@lists.lazarus.freepascal.orghttp://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
>  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
>
> I am also happy todo it depending on time required.

Richard Mace
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Samps]

On 02/03/12 20:44, Vincent Snijders wrote:



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


Is anybody else lined up to take over?


I don't know.

Vincent


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

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
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Vincent Snijders]

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

> Is anybody else lined up to take over?
>

I don't know.

Vincent
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Richard Mace]

Is anybody else lined up to take over?

Richard

On 2 March 2012 07:40, Vincent Snijders  wrote:

> 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
>
> --
> ___
> Lazarus mailing list
> Lazarus@lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Vincent Snijders]

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Frank Church]

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

On 02/03/2012, Vincent Snijders  wrote:
> 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
>
> --
> ___
> Lazarus mailing list
> Lazarus@lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>


-- 
Frank Church

===
http://devblog.brahmancreations.com

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Vincent Snijders]

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Frank Church]

On 01/03/2012, Felipe Monteiro de Carvalho
 wrote:
> On Thu, Mar 1, 2012 at 10:36 AM, 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.
>
> --
> Felipe Monteiro de Carvalho
>
> --
> ___
> Lazarus mailing list
> Lazarus@lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>

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?

-- 
Frank Church

===
http://devblog.brahmancreations.com

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Donnerstag, den 01.03.2012, 14:15 +0100 schrieb Hans-Peter Diettrich:
> Marc Santhoff schrieb:
> > Am Donnerstag, den 01.03.2012, 01:22 +0100 schrieb Hans-Peter Diettrich:
> >> Marc Santhoff schrieb:
> >>
> >>> A complete index, yes. To the right on
> >>>
> >>>   http://wiki.lazarus.freepascal.org/
> >>>
> >>> under the headline "Navigation" there is a link to it.
> >> The results are very strange. Entering "documentation" finds almost all 
> >> pages, because these have this keyword in the headline and navigation menu.
> > 
> > Tried "Documentation" with a capital at the start?
> 
> Ah, now the results are significantly better. But why?
> 
> Does a capital character have a special meaning in a search?

No, but wiki names are CamelCase.

> > 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?

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

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

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

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Donnerstag, den 01.03.2012, 14:28 +0100 schrieb Hans-Peter Diettrich:
> Vincent Snijders schrieb:
> > Op 1 maart 2012 08:12 heeft Graeme Geldenhuys
> >  het volgende geschreven:
> >> On 1 March 2012 02:22, 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.
> > 
> > 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.
> 
> Either case indicates the lack of a description, required to use an 
> existing feature.

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...

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Vincent Snijders]

Op 1 maart 2012 14:28 heeft Hans-Peter Diettrich
 het volgende geschreven:
> Vincent Snijders schrieb:
>
>> Op 1 maart 2012 08:12 heeft Graeme Geldenhuys
>>  het volgende geschreven:
>>>
>>> On 1 March 2012 02:22, 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.
>>
>>
>> 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.
>
>
> 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.

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.

>
>
>>
>> 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.

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

>
>
>> or are later in the alphabetically, case sensitive
>> sorted index of pages.
>
>
> What is "are later"? All pages starting with 'g'..'z'?

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

>
>
>> It doesn't say anything about the contents of
>> the page, just about its name.
>
>
> This finally makes some sense.

Glad you understood.

Vincent

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Marc Santhoff schrieb:

Am Donnerstag, den 01.03.2012, 01:22 +0100 schrieb Hans-Peter Diettrich:

Marc Santhoff schrieb:


A complete index, yes. To the right on

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

under the headline "Navigation" there is a link to it.
The results are very strange. Entering "documentation" finds almost all 
pages, because these have this keyword in the headline and navigation menu.


Tried "Documentation" with a capital at the start?


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Vincent Snijders schrieb:

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

On 1 March 2012 02:22, 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.


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.


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Felipe Monteiro de Carvalho]

On Thu, Mar 1, 2012 at 10:36 AM, 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.

-- 
Felipe Monteiro de Carvalho

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 1 March 2012 10:09, 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.


-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 05:59 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 05:54 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Vincent Snijders]

Op 1 maart 2012 08:12 heeft Graeme Geldenhuys
 het volgende geschreven:
> On 1 March 2012 02:22, 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.

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Felipe Monteiro de Carvalho]

On Thu, Mar 1, 2012 at 8:12 AM, 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".

-- 
Felipe Monteiro de Carvalho

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

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.


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?


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).



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)?


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 1 March 2012 02:22, 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.

-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Donnerstag, den 01.03.2012, 01:22 +0100 schrieb Hans-Peter Diettrich:
> Marc Santhoff schrieb:
> 
> > A complete index, yes. To the right on
> > 
> >   http://wiki.lazarus.freepascal.org/
> > 
> > under the headline "Navigation" there is a link to it.
> 
> The results are very strange. Entering "documentation" finds almost all 
> pages, because these have this keyword in the headline and navigation menu.

Tried "Documentation" with a capital at the start?

That thingy is case sensitive ...

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[John Repucci]

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".

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[John Repucci]

>
> Date: Thu, 01 Mar 2012 01:22:34 +0100
> From: Hans-Peter Diettrich 
> Subject: Re: [Lazarus] Missing Documentation
> To: Lazarus mailing list 
> Message-ID: <4f4ec14a.9080...@aol.com>
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
> Marc Santhoff schrieb:
>
> > A complete index, yes. To the right on
> >
> >   http://wiki.lazarus.freepascal.org/
> >
> > under the headline "Navigation" there is a link to it.
>
> The results are very strange. Entering "documentation" finds almost all
> pages, because these have this keyword in the headline and navigation menu.
>
> I agree - the results are strange.
I used index to search for "VST" and the first links ("Var", "Varies") did
not contain "VST".
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Marc Santhoff schrieb:


A complete index, yes. To the right on

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

under the headline "Navigation" there is a link to it.


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Mittwoch, den 29.02.2012, 20:43 +0100 schrieb Hans-Peter Diettrich:
> Marc Santhoff schrieb:
> 
> > 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.

Sonds promising, I'll try it.

Thank you.

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Mittwoch, den 29.02.2012, 13:47 -0600 schrieb John Repucci:
> Date: Wed, 29 Feb 2012 19:32:47 +0100
> From: Marc Santhoff 
> Subject: Re: [Lazarus] Missing Documentation
> To: Lazarus mailing list
> 
> Message-ID: <1330540367.57395.61.ca...@zaphod.das.netz>
> Content-Type: text/plain
> 
> Am Mittwoch, den 29.02.2012, 18:15 +0100 schrieb Hans-Peter
> Diettrich:
> > Marc Santhoff schrieb:
> 
> 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 ...
>  
> (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.

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


-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Marc Santhoff schrieb:


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[John Repucci]

>
> Date: Wed, 29 Feb 2012 19:32:47 +0100
> From: Marc Santhoff 
> Subject: Re: [Lazarus] Missing Documentation
> To: Lazarus mailing list 
> Message-ID: <1330540367.57395.61.ca...@zaphod.das.netz>
> Content-Type: text/plain
>
> Am Mittwoch, den 29.02.2012, 18:15 +0100 schrieb Hans-Peter Diettrich:
> > Marc Santhoff schrieb:
>
> 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 ...
>
>
(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.
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Frank Church]

On 28 February 2012 18:43, Marc Santhoff  wrote:

> 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
> --
> Marc Santhoff 
>
>
> --
> ___
> Lazarus mailing list
> Lazarus@lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>

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.



-- 
Frank Church

===
http://devblog.brahmancreations.com
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 29 February 2012 18:59, 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.


-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Guionardo Furlan]

  
  
Em 28/02/2012 16:06, Mattias Gaertner escreveu:

  On Tue, 28 Feb 2012 19:43:48 +0100
Marc Santhoff  wrote:


  
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 ...

  
  
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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus



I would like to see a documentation format like php (
http://php.net/manual/en ): collaborative and with usage examples
and discussions.


-- 
  

  

  Guionardo Furlan


  Web-design e Hospedagem
Desenvolvimento Lazarus/Freepascal, PHP
Projetista SolidWorks


  Timeo hominem unius libri


  Site: guionardofurlan.com.br


  Blog: guionardo.blogspot.com

  

  

  


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Mittwoch, den 29.02.2012, 18:15 +0100 schrieb Hans-Peter Diettrich:
> Marc Santhoff schrieb:
> 
> > 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.

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.

> > 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?"

Will read thoroughly, thanks.

> > 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 :-(

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 ...

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Mittwoch, den 29.02.2012, 18:22 +0100 schrieb Mattias Gaertner:
> 
> Marc Santhoff  hat am 29. Februar 2012 um 17:54
> geschrieben: 
> 
> >[...] 
> > > > > 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. 
> > 
> > Reading about this type of confusion - count me in - I need to ask: 
>  
> 
> You are welcome to ask.
> 
> I hope your confusion is a completely different one.

 Hopefully yes. ;)

(note to myself: wash your keyboard with soap for making naughty jokes)
 
> 
> > 
> > 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?  

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.


> 
> > 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? 

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


> 
> >[...] 
> > 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. 
>  
> 
> Great!
> 
> Have you seen the tutorials in the wiki?

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. ;)

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

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

>[...]
> > > > 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.
>
> Reading about this type of confusion - count me in - I need to ask:


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?




>[...]
> 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.



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



--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Marc Santhoff schrieb:


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Mittwoch, den 29.02.2012, 15:45 +0200 schrieb Graeme Geldenhuys:
> 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

> * 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!

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.

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Marc Santhoff]

Am Mittwoch, den 29.02.2012, 13:07 +0100 schrieb Mattias Gaertner:
> 
> 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. 

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.

-- 
Marc Santhoff 


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Michael Schnell schrieb:

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, ...)


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


DoDi


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Michael Schnell schrieb:

On 02/29/2012 12:37 PM, 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.


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[waldo kitty]

On 2/29/2012 10:41, Rich Saunders wrote:

On 2/29/12 7:25 AM, 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.


+1


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 04:15 PM, Reinier Olislagers wrote:
I'm sorry, but then I suggest you stop bothering the list with your 
posts...

Agreed.

- Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Rich Saunders]

On 2/29/12 7:25 AM, 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.


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Reinier Olislagers]

On 29-2-2012 14:02, Michael Schnell wrote:
> On 02/29/2012 12:59 PM, Sven Barth wrote:
>>
>> 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
>>
> Obvious best option: * do nothing.
> 
> -Michael

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




--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Michael Schnell schrieb:

On 02/29/2012 11:26 AM, 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 ?


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

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.


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


DoDi


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 02:53 PM, michael.vancann...@wisa.be wrote:

None of this is an excuse for not contributing.


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

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 02:45 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[michael . vancanneyt]

On Wed, 29 Feb 2012, Michael Schnell wrote:


On 02/29/2012 02:27 PM, 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, ...)


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.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 29 February 2012 15:36, Michael Schnell  wrote:
>
> 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, ...)


[ 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


-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 02:27 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 29 February 2012 13:25, 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. ;-)


-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

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

> Am 29.02.2012 12:57, schrieb Michael Schnell:
>  > On 02/29/2012 12:54 PM, Sven Barth wrote:
>  >>
>  >> 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.
>  >>
>  > 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".
>
> As already written:
> * either use the editor hints of the IDE which work on the FPDoc files
> in %laz%\doc\xml


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
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:59 PM, Sven Barth wrote:


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


Obvious best option: * do nothing.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 13:01, schrieb Michael Schnell:

On 02/29/2012 12:57 PM, 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.


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 12:57, schrieb Michael Schnell:
> On 02/29/2012 12:54 PM, Sven Barth wrote:
>>
>> 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.
>>
> 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".

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

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

> On 02/29/2012 12:54 PM, Sven Barth wrote:
> >
> > 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.
> >
> 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".


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


Mattias
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 01:04 PM, michael.vancann...@wisa.be wrote:


Do you simetimes actually listen to what we say here ?

Seemingly I misunderstood and you are right to be angry .


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.
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")


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.
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).


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...


sounds nice :)

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

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.





>
> 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 :(



Mattias
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[michael . vancanneyt]

On Wed, 29 Feb 2012, Michael Schnell wrote:


On 02/29/2012 12:54 PM, Sven Barth wrote:


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.


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".


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.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:57 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

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

> Am 29.02.2012 11:33, schrieb Michael Schnell:
> > On 02/29/2012 11:26 AM, 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 ?
>
> FPDoc <> Wiki


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.



>
> 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.


Well, at least not that comfortable.

Mattias
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:54 PM, michael.vancann...@wisa.be wrote:
Where did you see that fpdoc is priviledged ? Anyone can download and 
work

on it, and submit patches.

See my answer to Sven.

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 12:48, schrieb Michael Schnell:

On 02/29/2012 12:37 PM, 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.


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:54 PM, Sven Barth wrote:


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.


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[michael . vancanneyt]

On Wed, 29 Feb 2012, Michael Schnell wrote:


On 02/29/2012 12:32 PM, 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.


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

Michael.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 12:50, schrieb Michael Schnell:

On 02/29/2012 12:32 PM, 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.



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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:32 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:37 PM, 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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:36 PM, michael.vancann...@wisa.be wrote:


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 12:28, schrieb Michael Schnell:
> On 02/29/2012 12:08 PM, 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.

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 12:31, schrieb Michael Schnell:

On 02/29/2012 11:34 AM, 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.


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[michael . vancanneyt]

On Wed, 29 Feb 2012, Michael Schnell wrote:


On 02/29/2012 11:34 AM, 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.


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.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:30 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 11:34 AM, 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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 12:25, schrieb Michael Schnell:

On 02/29/2012 11:33 AM, 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.


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


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

If you say so a will not disagree at all.

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 ?

You must be kidding.

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


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.



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 :(


Regards,
Sven

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 11:34 AM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 12:08 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 11:33 AM, 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.

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 ?

You must be kidding.

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Sven Barth]

Am 29.02.2012 11:33, schrieb Michael Schnell:

On 02/29/2012 11:26 AM, 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 ?


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


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Felipe Monteiro de Carvalho]

On Wed, Feb 29, 2012 at 11:34 AM, 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

-- 
Felipe Monteiro de Carvalho

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Felipe Monteiro de Carvalho]

On Wed, Feb 29, 2012 at 10:43 AM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

On Wed, 29 Feb 2012 11:24:31 +0100
Michael Schnell  wrote:

> 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.

 
> 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).

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


> > 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 ?

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 11:26 AM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 11:17 AM, Mattias Gaertner wrote:

How do you hook into the IDE dialog help system? Is this by
registering yet another help package?

Yes.

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

Whatever the user installs.
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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

On Wed, 29 Feb 2012 11:43:46 +0200
Graeme Geldenhuys  wrote:

> On 29 February 2012 10:57, 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.

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 11:10 AM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

On Wed, 29 Feb 2012 11:39:32 +0200
Graeme Geldenhuys  wrote:

> On 29 February 2012 10:57, 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?

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.

 
> 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).

I'm currently working on this.

Mattias
 

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

On Wed, 29 Feb 2012 10:23:18 +0100
Michael Schnell  wrote:

> On 02/29/2012 09:57 AM, 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. )

I started it.

 
> > 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.

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 29 February 2012 10:57, 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.


-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Graeme Geldenhuys]

On 29 February 2012 10:57, 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).

-- 
Regards,
  - Graeme -


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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 10:23 AM, Michael Schnell wrote:

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

Many thanks to Graeme as well !

-Michael

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/29/2012 09:57 AM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Mattias Gaertner]

On Wed, 29 Feb 2012 09:34:14 +0100
Michael Schnell  wrote:

> On 02/28/2012 08:06 PM, 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.

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] Missing Documentation

[Michael Schnell]

On 02/28/2012 08:06 PM, 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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus