Re: [Lazarus] Documentation style
On Mon, Jul 25, 2011 at 7:56 AM, tim launchbury t...@tlaunchbury.ukfsn.org 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 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, 25 Jul 2011 09:14:09 +0200 Graeme Geldenhuys graemeg.li...@gmail.com 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 Mon, Jul 25, 2011 at 12:44 AM, Mattias Gaertner nc-gaert...@netcologne.de 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 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 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 Mon, Jul 25, 2011 at 11:45 AM, Michael Schnell mschn...@lumino.de 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
Felipe Monteiro de Carvalho felipemonteiro.carva...@gmail.com hat am 25. Juli 2011 um 11:45 geschrieben: On Mon, Jul 25, 2011 at 11:45 AM, Michael Schnell mschn...@lumino.de 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 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
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, 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 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
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 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
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 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 Mon, Jul 25, 2011 at 2:31 PM, Graeme Geldenhuys graemeg.li...@gmail.com 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 Sun, Jul 24, 2011 at 1:52 AM, Hans-Peter Diettrich drdiettri...@aol.com 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
On Sun, 24 Jul 2011 19:25:22 +0200 Felipe Monteiro de Carvalho felipemonteiro.carva...@gmail.com wrote: On Sun, Jul 24, 2011 at 1:52 AM, Hans-Peter Diettrich drdiettri...@aol.com 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
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 23:52:44 +0100 Hans-Peter Diettrich drdiettri...@aol.com 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
[Lazarus] Documentation style
Hello all Sorry for this not being in the thread.. I am a native English speaker and am willing to help with proofreading documentation ( and possibly writing some ). Regarding UK/US differences, my personal view is that they do not really matter as they are for the most part insignificant. 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. An observation I have been meaning to make for some time: As for the quality of english, over the months I have noticed that the standard of written english on this list is very high ( higher than I would expect from native speakers, in many cases ). What is the procedure for editing / reviewing documentaion ? Regards Tim -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
[Lazarus] Documentation style
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 don't want to discourage non-native speakers to contribute to the documentation, but they should mark their entries as raw (to be revised), so that a proofreader can easily find and check new or updated entries. I already started inserting markers into the docs, e.g. [?] for questionable and [???] for obviously wrong parts, and more [revised ...] notes. Accordingly above raw marker could e.g. read [~], and should be inserted wherever questionable wording has been found. Style related are field names like childs, which IMO should read Children (which was the name in the preceding document version!). IMO the core developers *also* should consult native English speakers, before adding items with poor names. Often I come across circles, referring to circular unit references. IMO the correct term instead would be loops, in e.g. avoid loops. 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. The final documenation shows the element name, so that the short description should not duplicate this name, IMO. Opinions? 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. What's the purpose of the *used units*, listed as elements of some units? The same for parameters, whose separate descriptions are not normally accessible in e.g. the FPDoc editor. While it may be nice to have all parameters (and Result) described explicitly in the final documentation, the separation of these items from the procedure description is not helpful for the documentation writers. I'd suggest a description list for all parameters and the result, inside the long description. Such a list would make the docs look more like the (old) Delphi or MSDN documentation, with a clear structure for all subroutines: - short description - declaration (maybe multiples for overloaded procedures) - parameter description - result description - long general description What's the purpose of the Errors tag? IMO it should not only contain links to the possible exceptions, but also should describe the exact reason, when an exception is raised. And it also should contain remarks on yet unhandled situations, which can or will cause an AV or wrong results. As already mentioned in another mail, all links to #LCL are broken now. I hope that this will be fixed soon, by renaming the packages. So much for now. I'm willing to coordinate all work on the documentation, and hope to get back write access to the repository soon. Then everybody can send me patches or notes on the documentation. Don't hesitate to report missing documentation or details; documentation writers often are so familiar with an topic, that they forget to mention the basic details, which are unknown to the *users* of the described elements. I also can assign doc files to those people, which are willing to proofread the documentation, so that we can avoid duplicate work. 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 13:20:42 +0100 Hans-Peter Diettrich drdiettri...@aol.com 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
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 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? snip 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
On Sat, 23 Jul 2011 15:29:45 +0200 Jürgen Hestermann juergen.hesterm...@gmx.de 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 Sat, 23 Jul 2011 14:59:20 +0100 Howard Page-Clark h...@talktalk.net 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? snip 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
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 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: 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
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
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
On Sat, 23 Jul 2011 16:59:14 +0100 Hans-Peter Diettrich drdiettri...@aol.com 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
Mattias Gaertner schrieb: On Sat, 23 Jul 2011 16:59:14 +0100 Hans-Peter Diettrich drdiettri...@aol.com 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
