Re: [Lazarus] Documentation style
On Mon, Jul 25, 2011 at 2:31 PM, Graeme Geldenhuys wrote: >> Hmm I consider handling very decent Lazarus external tools, that enhance >> the Lazarus usability greatly, here is a quite good idea. > > Me too, but I have been in trouble quite a few times with posts that > seem to stray off-topic. [It's almost like being back in school. :)] I > would like to prevent such future disagreements, otherwise I would > probably get moderated here too. I think that discussions about DocView are on topic for the Lazarus mailling list considering that it is a tool that can be used with Lazarus IDE. -- Felipe Monteiro de Carvalho -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 02:15 PM, Michael Schnell wrote: >> Please get a repository update and try again. > Yep. It works now. Excellent. > Hmm I consider handling very decent Lazarus external tools, that enhance > the Lazarus usability greatly, here is a quite good idea. Me too, but I have been in trouble quite a few times with posts that seem to stray off-topic. [It's almost like being back in school. :)] I would like to prevent such future disagreements, otherwise I would probably get moderated here too. > fpGUI question at all. I have no idea where "legally" to post questions > about "wipfc" crashing. WIPFC is an Open Watcom project written in C++. So the correct place to post such issues would be on news://news.openwatcom.org server in the 'openwatcom.contributors' news group. At least that is where I post any issues with WIPFC. I have finally started with my own implement of an IPF Compiler, but unfortunately it will be some time before it's available or usable. It's still early days, but I'll notify you as soon as there is something to test. Regards, - Graeme - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 01:45 PM, Graeme Geldenhuys wrote: Yes, I don't supply binaries in the repository. :) Please get a repository update and try again. Yep. It works now. Thanks ! In future, the Lazarus mailing list admin [that's not me], would appreciate it if you post fpGUI specific questions in the fpGUI support newsgroup - instead of here in the Lazarus mailing list. AFAIR, I can't access same from here due to the firewall blocking DYNDNS addresses. Though I guess using DocView with Lazarus IDE and an alternative help viewer makes this subject a bit of a grey area. Hmm I consider handling very decent Lazarus external tools, that enhance the Lazarus usability greatly, here is a quite good idea. Moreover the question I posted was about not being able to build IPF and IF file. AFAIU, IPF has nothing to do with "build_lcl_docs" is not an fpGUI question at all. I have no idea where "legally" to post questions about "wipfc" crashing. -Michael -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 01:16 PM, Michael Schnell wrote: > Sill me. Of course I need to recompile the docview project. Yes, I don't supply binaries in the repository. > Buit after doing this I in fact can start the new docview as a stand > alone executable, but it does not show when I start it as an external > tool in Lazarus :(. I believe you triggered the error I fixed 2 minutes ago. :) The fpGUI framework handles some "global" command line parameters. DocView then also handles its own set of command line parameters. I did not handle such cases very well, and DocView could have silently crashed out. With the recent commits I have hopefully fixed this now. Please get a repository update and try again. PS: In future, the Lazarus mailing list admin [that's not me], would appreciate it if you post fpGUI specific questions in the fpGUI support newsgroup - instead of here in the Lazarus mailing list. Though I guess using DocView with Lazarus IDE and an alternative help viewer makes this subject a bit of a grey area. Regards, - Graeme - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Sill me. Of course I need to recompile the docview project. Buit after doing this I in fact can start the new docview as a stand alone executable, but it does not show when I start it as an external tool in Lazarus :(. -Michael -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 12:19 PM, Graeme Geldenhuys wrote: ...and with my commits of yesterday, DocView is even better. 5-10x faster at startup (the more fonts you have installed, the faster it is compared to the old DocView startup times). I have also reduced memory consumption by around 47%! GREAT ! Do I need to compile/install anything or does the binary come with a git update to fpGUI/docview/src/units/i386-linux/docview Any progress regarding the said crashes of both build_lcl_docs and wipfc ) -Michael ? -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 11:45 AM, Felipe Monteiro de Carvalho wrote: I think that the Lazarus IDE reads chm, not inf Yep. You need to install docview as an external tool package. But this does not provide any problems. You can trigger the keyword search from the source code editor with a hotkey (I use ctrl-shift F1). In fact I made docview use the rtl + fcl + lcl .inf files. Creating the rtl and fcl .inf files from the sources in the svn worked without a problem. I right now just failed to create the lcl.inf file. I currently use some old lcl.inf file and this does work nicely for docview. But with my effort5 to enhance the lcl help this does not help. ;) -Michael -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 11:45 AM, Felipe Monteiro de Carvalho wrote: > > I think that the Lazarus IDE reads chm, not inf Lazarus IDE doesn't read any help files (other that the limited tooltip help directly from the fpdoc XML files). "Real help" is supplied via external help viewers like your web browser, LHelp or DocView. The latter can be installed simply via an "External Tools" entry - no need to recompile Lazarus IDE. LHelp integrates via a Lazarus package - thus requires a Lazarus IDE recompile. Regards, - Graeme - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 11:45 AM, Michael Schnell wrote: > > Graeme convinced me that "Docview" is the best available help displaying > "plugin" for Lazarus. ...and with my commits of yesterday, DocView is even better. 5-10x faster at startup (the more fonts you have installed, the faster it is compared to the old DocView startup times). I have also reduced memory consumption by around 47%! Regards, - Graeme - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Felipe Monteiro de Carvalho hat am 25. Juli
2011 um 11:45 geschrieben:
> On Mon, Jul 25, 2011 at 11:45 AM, Michael Schnell wrote:
> > Right now I am unsuccessfully trying to create the appropriate file
> > ("lcl.inf") from the help source files (both build_lcl_docs and wipfc
> > crash).
>
> You could try chm. I think that the Lazarus IDE reads chm, not inf
The IDE code hints read the fpdoc xml files and pascal sources.
There is a mature chm help IDE package (chmhelppkg) plus viewer (lhelp), which
afaik comes preinstalled with the debian packages.
The installation instructions are in components/chmhelp/README.txt.
It seems this file does not cover the recent changes like help for keywords and
system identifiers.
Maybe the chmhelp maintainers can update the docs.
The wiki needs some update too:
http://wiki.lazarus.freepascal.org/chmhelp
It should link to the right page or explain how to install the chmhelp.
Mattias--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Mon, Jul 25, 2011 at 11:45 AM, Michael Schnell wrote:
> Right now I am unsuccessfully trying to create the appropriate file
> ("lcl.inf") from the help source files (both build_lcl_docs and wipfc
> crash).
You could try chm. I think that the Lazarus IDE reads chm, not inf
--
Felipe Monteiro de Carvalho
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/23/2011 03:59 PM, Howard Page-Clark wrote:
I suspect it is almost an endless task ...
Thanks for all contributors.
IMHO improving the help system is as very decent and beneficial task.
In fact this is (1) the help text, (2) the help displaying software and
(3) the infrastructure that creates the files readable for the help
displaying software from the source texts.
Graeme convinced me that "Docview" is the best available help displaying
"plugin" for Lazarus.
Right now I am unsuccessfully trying to create the appropriate file
("lcl.inf") from the help source files (both build_lcl_docs and wipfc
crash).
Thanks again,
-Michael
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 09:26 AM, Mattias Gaertner wrote: > > It's about the examples. They are stored in separate files, pascal > source snippets. Ah, I forgot about code samples inside the docs. Regards, - Graeme - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Mon, Jul 25, 2011 at 12:44 AM, Mattias Gaertner wrote: >> Why then have separate packages at all, when every GUI application >> depends on both? > > There are two type of output directories. My initial idea to improve this was to invert the packages: LCL containing forms, comctrls, lclintf, etc and LCLBase containing the widgetset interface units But now I see that this wouldn't work, because the widgetset interface units depend on the LCL, not the other way around ... -- Felipe Monteiro de Carvalho -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Mon, 25 Jul 2011 09:14:09 +0200 Graeme Geldenhuys wrote: > On 07/25/2011 07:56 AM, tim launchbury wrote: > > > > I feel that the documentaion formatting style consistency is important > > and therefore would support the suggestion that the jedi formatter be > > extended to cover this. > > Huh? "Jedi Formatter" (which I assume you are referring to is actual JCF > or Jedi Code Formatter) is just that... it formats source code. It has > nothing to do with documentation or the formatting of that documentation. It's about the examples. They are stored in separate files, pascal source snippets. > Class documentation is defined in XML, and it is the FPC's fpdoc program > that generates documentation from that XML using one of many output > writers (PDF, HTML, CHM, INF, Man, Text, RTF, Delphi XML etc). This > process is very similar to DocBook. Formatting of documentation output > is defined in how the "output writers" in fpdoc are coded - that is not > end-user configurable. True. Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 07/25/2011 07:56 AM, tim launchbury wrote: > > I feel that the documentaion formatting style consistency is important > and therefore would support the suggestion that the jedi formatter be > extended to cover this. Huh? "Jedi Formatter" (which I assume you are referring to is actual JCF or Jedi Code Formatter) is just that... it formats source code. It has nothing to do with documentation or the formatting of that documentation. Class documentation is defined in XML, and it is the FPC's fpdoc program that generates documentation from that XML using one of many output writers (PDF, HTML, CHM, INF, Man, Text, RTF, Delphi XML etc). This process is very similar to DocBook. Formatting of documentation output is defined in how the "output writers" in fpdoc are coded - that is not end-user configurable. Regards, - Graeme - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Mon, Jul 25, 2011 at 7:56 AM, tim launchbury wrote: > What is the procedure for editing / reviewing documentaion ? It works like this: 1> Download svn lazarus 2> Make changes to the docs 3> Build the docs to see the result 4> Send a patch to the bug tracker To edit the documentation I use simply a plain text editor. One can also use a tool in the IDE, but that tool refactors the XML, so it gets very hard to see what was changed =( -- Felipe Monteiro de Carvalho -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sun, 24 Jul 2011 23:52:44 +0100 Hans-Peter Diettrich wrote: > Mattias Gaertner schrieb: > > > The base units are independent of the widgetset units and the widgetset > > units use the base units. So the package of widgetset units must use > > the package of the base units. > > Theoretically: If the base package would be named 'LCL', then > > all existing projects would no longer work, because they misses the > > widgetset units. > > Why then have separate packages at all, when every GUI application > depends on both? There are two type of output directories. > >>From the users point of view the LCL split is the same as if > > a big package was split into two. The upper package keeps the original > > name for compatibility. Compilation works, but fpdoc links get into > > trouble. > > Building old projects (examples...) now fails, because these depend on > LCL, not on LCLbase :-( For example? > > This is because the inheriting of packages is not (yet) implemented for > > fpdoc. It's not a big task to implement this for the IDE code hints, > > but I don't know yet about the rest of fpdoc. I can take a look after > > my vacation. > > > > In other words: > > Eventually both fpdoc links "#LCL.Controls" and "#LCLBase.Controls" > > should work. But of course #LCLBase.Controls is more correct. > > IMO "#LCL.Controls" and "#Widgetsets.whateverelse" would be more > appropriate. An example for widgetsets: #LCL.gtk2wsstdctrls. Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Mattias Gaertner schrieb: The base units are independent of the widgetset units and the widgetset units use the base units. So the package of widgetset units must use the package of the base units. Theoretically: If the base package would be named 'LCL', then all existing projects would no longer work, because they misses the widgetset units. Why then have separate packages at all, when every GUI application depends on both? From the users point of view the LCL split is the same as if a big package was split into two. The upper package keeps the original name for compatibility. Compilation works, but fpdoc links get into trouble. Building old projects (examples...) now fails, because these depend on LCL, not on LCLbase :-( This is because the inheriting of packages is not (yet) implemented for fpdoc. It's not a big task to implement this for the IDE code hints, but I don't know yet about the rest of fpdoc. I can take a look after my vacation. In other words: Eventually both fpdoc links "#LCL.Controls" and "#LCLBase.Controls" should work. But of course #LCLBase.Controls is more correct. IMO "#LCL.Controls" and "#Widgetsets.whateverelse" would be more appropriate. DoDi -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sun, 24 Jul 2011 19:25:22 +0200 Felipe Monteiro de Carvalho wrote: > On Sun, Jul 24, 2011 at 1:52 AM, Hans-Peter Diettrich > wrote: > > I see absolutely no reason why the LCL should reside in a package of a > > different name, and a package named LCL refers to something else. > > I must say that I it seams to me that the inverse order would make more sense: > > The LCL package containing forms, comctrls, etc, and depending on a > package called LCLBase which has the widgetset interface units for > carbon, gtk, etc. > > But I don't know why the current dependency direction was choosen, so > I don't know if it is really required or not. The base units are independent of the widgetset units and the widgetset units use the base units. So the package of widgetset units must use the package of the base units. Theoretically: If the base package would be named 'LCL', then all existing projects would no longer work, because they misses the widgetset units. >From the users point of view the LCL split is the same as if a big package was split into two. The upper package keeps the original name for compatibility. Compilation works, but fpdoc links get into trouble. This is because the inheriting of packages is not (yet) implemented for fpdoc. It's not a big task to implement this for the IDE code hints, but I don't know yet about the rest of fpdoc. I can take a look after my vacation. In other words: Eventually both fpdoc links "#LCL.Controls" and "#LCLBase.Controls" should work. But of course #LCLBase.Controls is more correct. >[...] Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sun, Jul 24, 2011 at 1:52 AM, Hans-Peter Diettrich wrote: > I see absolutely no reason why the LCL should reside in a package of a > different name, and a package named LCL refers to something else. I must say that I it seams to me that the inverse order would make more sense: The LCL package containing forms, comctrls, etc, and depending on a package called LCLBase which has the widgetset interface units for carbon, gtk, etc. But I don't know why the current dependency direction was choosen, so I don't know if it is really required or not. > Once again the core developers deliberately break compatibility, for nothing > but lazyness, and to hide a stupid decision, made before :-( Please control your language. -- Felipe Monteiro de Carvalho -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Mattias Gaertner schrieb: On Sat, 23 Jul 2011 16:59:14 +0100 Hans-Peter Diettrich wrote: [...] As already mentioned in another mail, all links to #LCL are broken now. I changed the #LCL to #LCLBase in the lcl xml files. Argh :-( ? Why do you break existing documentation, which refers to the LCL? Even if you can fix this in the Lazarus documentation, all other documentation (of user packages or projects) will be broken now. This means that every user now has to provide two versions of his documentation, one compatible with the last Lazarus release (0.9.30), and another one compatbible with newer Lazarus versions. The same for all existing projects, which have to depend on LCLbase now, where formerly they had LCL as their dependency. I see absolutely no reason why the LCL should reside in a package of a different name, and a package named LCL refers to something else. Once again the core developers deliberately break compatibility, for nothing but lazyness, and to hide a stupid decision, made before :-( DoDi -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sat, 23 Jul 2011 16:59:14 +0100 Hans-Peter Diettrich wrote: >[...] > >> As already mentioned in another mail, all links to #LCL are broken now. > > > > I changed the #LCL to #LCLBase in the lcl xml files. > > Argh :-( ? Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Martin schrieb: Well, if the current documentation just repeats the name (with fillwords) then it is useless IMO and should be deleted. True and yet not... Sure there is no point in having documentation, that is empty... Removing empty documentation means work. It has to be ensured, that not accidentally real docs are also affected. It needs to be merged and commited... Useless repetitions can be marked, for now, so that nobody tries to add the same useless stuff again. Later sombeody may have an idea what to write instead, perhaps after an look at the old (D7) Delphi documentation. We also could start an contest, searching for the most creative contributor(s)... DoDi -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Howard Page-Clark schrieb: I also can assign doc files to those people, which are willing to proofread the documentation, so that we can avoid duplicate work. I'm a native English speaker, and I'm willing to proofread documentation, and make suggestions for improvements. However, I suspect it is almost an endless task, and probably too much for one person to undertake (although the ideal would be for one English-speaker to undertake this, to get a consistent 'house style' and consistent spelling [UK > US English?]). It's a big task, but not endless. The documentation must be provided by the developers, or by other experienced coders. Stylistic differences between multiple editors should be acceptable, unless paid for ;-) No idea about the UK/US differences. Except for Color instead of Colour ;-) Several questions arise immediately. Where precisely are the original documents? How can I (or anyone else) be trusted to edit them correctly? A proofreader should only make the provided text better readable, if required. Currently only few elements are described in a way, that justifies an final touch. What about formatting style, indenting etc. for code examples? You can try to work out an style guide for the documentation, so that others can help to establish the suggested arrangement and formatting of the full descriptions. Good examples are a source of inspiration :-) It would be good to have consistency here too. I notice quite a lot of fpc/Lazarus source is quite terse: [ result:=i*trunc(x/y); rather thanresult := i * Trunc( x/y ); ] I see no need for quoting code in a description. Examples instead should follow the formatting guidelines, more or less closely. DoDi -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Mattias Gaertner schrieb: > What if the method just does what the name says? Then no extra documentation is needed.[...] How to distinguish an item that needs documentation and an item that does not need documentation? Give an example? DoDi -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Mattias Gaertner schrieb: Often I come across "circles", referring to circular unit references. IMO the correct term instead would be "loops", in e.g. "avoid loops". AFAIK the correct term in graph theory is "cycle". Sounds good. Many descriptions only describe the obvious, like method names expressed in more words. Such descriptions are quite useless, and should be replaced by more informative ones. I'd suggest to remove all these descriptions (replace by a todo-marker?), until somebody can describe the elements better. I doubt that this should be done for all. What if the method just does what the name says? Who can know that for sure? The final documenation shows the element name, so that the short description should not duplicate this name, IMO. Opinions? What do you purpose instead? A description without duplication of the name. The need for a different description can remove mental barriers, which otherwise can cause repetition of the obvious. Related: the FPDoc Editor IMO should always show the short description, above the pages. Then it's easier to e.g. avoid duplication of the short description in the long description. The short description is already shown above the long description. Yes, I suggested that as a workaround. But the short description is not editable in that page. I prefer to have the long description visible while coding, and when I want to insert a missing (short) description, I have to switch pages. [...] The same for parameters, whose separate descriptions are not normally accessible in e.g. the FPDoc editor. ToDo. Please create a feature request. Okay. [...] As already mentioned in another mail, all links to #LCL are broken now. I changed the #LCL to #LCLBase in the lcl xml files. Argh :-( DoDi -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 23/07/2011 16:06, Jürgen Hestermann wrote: Mattias Gaertner schrieb: >> Then no extra documentation is needed.[...] > How to distinguish an item that needs documentation and an > item that does not need documentation? Well, if the current documentation just repeats the name (with fillwords) then it is useless IMO and should be deleted. True and yet not... Sure there is no point in having documentation, that is empty... Removing empty documentation means work. It has to be ensured, that not accidentally real docs are also affected. It needs to be merged and commited... This work ends up with the developers who have to commit. (Even if provided as patch, by someone else). So unless there is real value from removing it, it may as well be left as it is. One might argue, that once removed, people can identify the missing bits, and contribute. Such promises exist plenty, and are rarely fulfilled. So again, unless someone who has proven himslef by providing patches containing real quality replacement docs; unless such a person, asks for it, saying it would help him to *continue* his proven efforts; unless such time, there is no point in removing them. But I didn't mean that in these cases documentation is not *needed*, just the opposite. I think that all functions/methods/language constructs/types/... should be documented. It's just that the *current* documenation is often useless because of its simple name repeat. The important information about side effects and internal structure is missing often. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
Mattias Gaertner schrieb: >> Then no extra documentation is needed.[...] > How to distinguish an item that needs documentation and an > item that does not need documentation? Well, if the current documentation just repeats the name (with fillwords) then it is useless IMO and should be deleted. But I didn't mean that in these cases documentation is not *needed*, just the opposite. I think that all functions/methods/language constructs/types/... should be documented. It's just that the *current* documenation is often useless because of its simple name repeat. The important information about side effects and internal structure is missing often. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sat, 23 Jul 2011 14:59:20 +0100 Howard Page-Clark wrote: > On 23/7/11 1:20, Hans-Peter Diettrich wrote: > > During the development of the doc tracker I stumbled over several issues: > > > > The English wording often violates my feeling for the language. Can some > > native English speakers proofread the documentation, and correct > > stylistic flaws? > > > > I also can assign doc files to those people, which are willing to > > proofread the documentation, so that we can avoid duplicate work. > > I'm a native English speaker, and I'm willing to proofread > documentation, and make suggestions for improvements. However, I suspect > it is almost an endless task, and probably too much for one person to > undertake (although the ideal would be for one English-speaker to > undertake this, to get a consistent 'house style' and consistent > spelling [UK > US English?]). > > Several questions arise immediately. Where precisely are the original > documents? The LCL fpdoc files are lazarus/docs/xml/*.xml Some package have fpdoc files too. > How can I (or anyone else) be trusted to edit them correctly? It's open source. Developers read the patch before committing, users do bug reports. > What about formatting style, indenting etc. for code examples? It would > be good to have consistency here too. I notice quite a lot of > fpc/Lazarus source is quite terse: > > [ result:=i*trunc(x/y); rather thanresult := i * Trunc( x/y ); ] If someone finds it terse or broad depends on the viewer application and what you are used to. Some examples need special code formatting to highlight the important parts of the examples. Lazarus follows many of the Delphi coding styles: http://edn.embarcadero.com/article/10280 Maybe someday the viewer can use the jedi code formatter to present examples in the preferred style of the user. Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sat, 23 Jul 2011 15:29:45 +0200 Jürgen Hestermann wrote: > >> Many descriptions only describe the obvious, like method names > expressed > >> in more words. Such descriptions are quite useless, and should be > >> replaced by more informative ones. I'd suggest to remove all these > >> descriptions (replace by a todo-marker?), until somebody can describe > >> the elements better. > > I doubt that this should be done for all. > > What if the method just does what the name says? > > Then no extra documentation is needed.[...] How to distinguish an item that needs documentation and an item that does not need documentation? Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On 23/7/11 1:20, Hans-Peter Diettrich wrote: During the development of the doc tracker I stumbled over several issues: The English wording often violates my feeling for the language. Can some native English speakers proofread the documentation, and correct stylistic flaws? I also can assign doc files to those people, which are willing to proofread the documentation, so that we can avoid duplicate work. I'm a native English speaker, and I'm willing to proofread documentation, and make suggestions for improvements. However, I suspect it is almost an endless task, and probably too much for one person to undertake (although the ideal would be for one English-speaker to undertake this, to get a consistent 'house style' and consistent spelling [UK > US English?]). Several questions arise immediately. Where precisely are the original documents? How can I (or anyone else) be trusted to edit them correctly? What about formatting style, indenting etc. for code examples? It would be good to have consistency here too. I notice quite a lot of fpc/Lazarus source is quite terse: [ result:=i*trunc(x/y); rather thanresult := i * Trunc( x/y ); ] yours Howard -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
>> Many descriptions only describe the obvious, like method names expressed >> in more words. Such descriptions are quite useless, and should be >> replaced by more informative ones. I'd suggest to remove all these >> descriptions (replace by a todo-marker?), until somebody can describe >> the elements better. > I doubt that this should be done for all. > What if the method just does what the name says? Then no extra documentation is needed. But just repeating the name with other words is realy ridiculous. I am always annoyed by such obvious statements. If there is no further useful information then don't write anything. But I doubt that there is any function/method where the name is enough to fully make use of it. Even if the name already gives a hint of what a function does there is a lot more information needed to make fully use of it and to avoid side effects caused by (false) assumptions. I was trapped by such things already very often. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] Documentation style
On Sat, 23 Jul 2011 13:20:42 +0100 Hans-Peter Diettrich wrote: >[...] > Style related are field names like "childs", which IMO should read > "Children" Yes. >[...] > Often I come across "circles", referring to circular unit references. > IMO the correct term instead would be "loops", in e.g. "avoid loops". AFAIK the correct term in graph theory is "cycle". > Many descriptions only describe the obvious, like method names expressed > in more words. Such descriptions are quite useless, and should be > replaced by more informative ones. I'd suggest to remove all these > descriptions (replace by a todo-marker?), until somebody can describe > the elements better. I doubt that this should be done for all. What if the method just does what the name says? > The final documenation shows the element name, so that the short > description should not duplicate this name, IMO. Opinions? What do you purpose instead? > Related: the FPDoc Editor IMO should always show the short description, > above the pages. Then it's easier to e.g. avoid duplication of the short > description in the long description. The short description is already shown above the long description. >[...] > The same for parameters, whose separate descriptions are not normally > accessible in e.g. the FPDoc editor. ToDo. Please create a feature request. >[...] > As already mentioned in another mail, all links to #LCL are broken now. I changed the #LCL to #LCLBase in the lcl xml files. >[...] Mattias -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
