Re: [fpc-devel] Determin file size - how?
On 12/15/2011 04:48 PM, Marco van de Voort wrote: Afaik neither Lazarus nor the textmode IDE currently provide fulltext access to the help. Any help. I installed DocView in Lazarus. This creates a menu entry Tools - fpGUI DocView (ctrl-shift-F1). This used to work nicely (providing cross-inf-file search) as well when called by this menu as when used as context sensitive help in a Lazarus editor window and using this key combination for context sensitive help display. In fact it right now does not work any more as I unsuccessfully played around with the inf files. I am sure Greame can give more competent comments on this topic. Afaik docview does not work within the IDE at all, only via the external tools option? If you mean the text mode IDE, I don't know. But AFAIK, DocView does not have a text mode display option, so it does not seem to make sense to use Doc View with the text mode IDE. As said, DocView does work nicely with the Lazarus IDE, installed as a tool but integrating itself by providing a hot-key usable in the editor. That used to be CHM based, but is now using CHM's successor. But that is totally not crossplatform and the helpsystem is external to windows and requires a license to install. Yep. (Supposedly this is why DocView has been created.) Of course it is nice that in the Delphi Help you can installed third party CHM files. I don't know whether CHM files we don't have a source code of can be converted to inf files. -Michael ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?
On Fri, 16 Dec 2011, Hans-Peter Diettrich wrote: michael.vancann...@wisa.be schrieb: I repeat: you didn't search very well. Yes, I was not lucky enough :-( IMO a separation into topics File handling (FILE based) and File management (by filename) would be a good idea. Now I also found an topic General File handling routines, but it seems to list only Posix functions, not avaialble on other platforms - should read Posix File ... instead? Where did you find this topic ? Hmm, you didn't search very well, too? ;-) #rtl/oldlinux/filehandlingroutines.html Duh... This unit is really outdated :-) A search on file handling in rtl.chm returns a list of near 100 hits, some of which are really procedures. RenameFile is missing from that list, instead it contains many Reference for unit ... entries. I can't comment on the quality of the search engine in CHM. I will investigate what can be done to make the topics more clear and helpful. And make them more easy to find. I understand that entries without tags are hard to find, but adding tags only would open another can of worms sigh. So the only solution, that I can see, is adding overview topics for categories of routines, with a list of the overviews at least in every package. The lists of overviews for a unit are of little use in a general search, when the units of interest are not yet known. Yes. As already mentioned, I still miss platform independent versions of the file management routines. Lazarus implements some routines, but IMO these should become part of the RTL, not of FCL or LCL. Which ones do you think are missing apart from FileSize ? Give me a link to the directory handling topic, then I can tell you more. Ah, found it: FileName handling routines (sysutils). At a first glance there is nothing missing, except FileSize. Perhaps ForceDirectories... I don't understand. ForceDirectories exists in sysutils? Michael. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?
In our previous episode, Michael Schnell said: [ Charset ISO-8859-1 unsupported, converting... ] On 12/15/2011 04:48 PM, Marco van de Voort wrote: Afaik neither Lazarus nor the textmode IDE currently provide fulltext access to the help. Any help. I installed DocView in Lazarus. This creates a menu entry Tools - fpGUI DocView (ctrl-shift-F1). This used to work nicely (providing cross-inf-file search) as well when called by this menu as when used as context sensitive help in a Lazarus editor window and using this key combination for context sensitive help display. I meant more that docview doesn't use the lazarus internal help registration. The textmode IDE has .INF support that doesn't relate to Graeme's efforts afaik. (in TP dialect) That used to be CHM based, but is now using CHM's successor. But that is totally not crossplatform and the helpsystem is external to windows and requires a license to install. (CHMs are still available on the Embarcadero ftpserver iirc, though I haven't checked for the last two versions) Yep. (Supposedly this is why DocView has been created.) No, it doesn't. Graeme started working on it when CHM was already mostly operational. Most of his original arguments were based on disk sizes and little implementation gotchas, not on functionality. I still don't see the point of inf. Of course it is nice that in the Delphi Help you can installed third party CHM files. I don't know whether CHM files we don't have a source code of can be converted to inf files. Yes of course. The question is (1) why would you do that? (2) while possible with some work, the quality of the .inf would be doubtful. You are converting one markup to the next. I actually looked into the other way around to provide tph and inf to chm support so I could kill off those systems in the textmode ide. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?y
In our previous episode, Michael Van Canneyt said: A search on file handling in rtl.chm returns a list of near 100 hits, some of which are really procedures. RenameFile is missing from that list, instead it contains many Reference for unit ... entries. I can't comment on the quality of the search engine in CHM. It's fine, but like most built-in engines it is not google. It doesn't have a rating system, or anything else that builds up experience to rank hits. Thus you probably won't find general phrases like file handling if there are no exact matches. The said problems are not problems with CHM, but simply very shallow and arbitrary tests. That doesn't mean that the CHM can't be improved (e.g. by putting more metadata in the fpdoc format so that fpdoc can use it in the various formats generation), but if you want to find problems or make comparisons with Google, you will always find problems. A possible solution would be to make the entry (home) page an overview page that provides links to unit list (the current homepage), and e.g. a page with overviews like for stringhandling and filehandling. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?
In our previous episode, Hans-Peter Diettrich said: Search for rename and file in the chm help: Thanks, slowly I understand how a chm can be searched :-) This should be explained somewhere, too (using Help) I'm not sure I want to pull every IT education topic into the FPC help :-) ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?y
On 12/16/2011 12:42 PM, Marco van de Voort wrote: It's fine, but like most built-in engines it is not google. Can it do and and or and search for multi word strings ? (In fact I don't know wheter DocView can do these...) -Michael ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?y
In our previous episode, Michael Schnell said: [ Charset ISO-8859-1 unsupported, converting... ] On 12/16/2011 12:42 PM, Marco van de Voort wrote: It's fine, but like most built-in engines it is not google. Can it do and and or and search for multi word strings ? Afaik default is AND. I don't know if it can do OR. (and I'm not sure if that is that relevant for a helpsystem) (In fact I don't know wheter DocView can do these...) They are roughly from the same period, and nearly equivalent in any way. So I assume the fulltext possibilities too. I chose for CHM because we got first class CHM fileformat generation possibilities donated, and many parts of the generator could be shared between html and CHM. And because the format isn't dead. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?y
On 12/16/2011 01:51 PM, Marco van de Voort wrote: Afaik default is AND. I don't know if it can do OR. (and I'm not sure if that is that relevant for a helpsystem) Maybe or is not very important (but there are cases it can help), but I feel that and vs multi-word-string is necessary. I chose for CHM because we got first class CHM fileformat generation possibilities donated, and many parts of the generator could be shared between html and CHM. I might be inclined to follow in case that there is a script that creates an combined CHM file for fpc language, rtl, lazarus IDE, LCL, (and ...) from the svn sources. -Michael ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] Determin file size - how?
Michael Van Canneyt schrieb: Give me a link to the directory handling topic, then I can tell you more. Ah, found it: FileName handling routines (sysutils). At a first glance there is nothing missing, except FileSize. Perhaps ForceDirectories... I don't understand. ForceDirectories exists in sysutils? It is not listed in the overview. DoDi ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
[fpc-devel] MakeSkel and FPDoc projects
When MakeSkel shall use FPDoc projects, this can be achieved by adding something like: procedure LoadProject(const Arg: string); begin ProjectName := Arg; Project := TFPDocProject.Create(Nil); //owner component? With TXMLFPDocOptions.Create(Project) do try LoadOptionsFromFile(Project,Arg); if (PackageName = '') and (Project.Packages.Count 0) then PackageName := Project.Packages[0].Name; finally Free; end; end; Handling of the InputFiles and DescrFiles can be added similar to above handling of the (default) PackageName, e.g. if assigned(Project) then //the package *must* be part of the project Pkg := Project.Packages.FindPackage(PackageName) else Pkg := nil; //project not usable if assigned(Pkg) then begin InputFiles.Assign(Pkg.Inputs); DescrFiles.Assign(Pkg.Descriptions); //extract further options? end; DocumentPackage(...) Since new description files should be added to the project, I'd suggest that MakeSkel uses a Project and the lists as stored in it, instead of the InputFiles and DescrFiles variables. This change only affects the program code, which passes these lists to DocumentPackage. Then the created skeletons can be added to the DescrFiles list, and the updated project can be saved on exit. Furthermore it should be possible to process a single module from a project package, for which e.g. a skeleton shall be created, or which should be checked for errors by fpdoc. This requires that the --input value selects one of the input files in the project. This can be simplified by splitting the InputFile strings, into File and Options parts, as is already done in the project files. The stringlist representation could e.g. look like file=options, so that IndexOfName can be used to select an entry, and the = is replaced by an space before the entry is passed to the worker code. Then also another option --unit=unit-name can be used to select the specific input file to process. Then the stringlist representation also can be changed to unit-name=existing --input descriptor, and Values[unit-name] can be passed to the worker code. Currently FPDoc scans the commandline for a project first, before parsing the other options. This extra handling could be removed, with the effect that options before the --project option are defaults, which are overridden by the project settings, while options after --project override the project settings. This consideration applies to all programs, which accept an fpdoc project. I'm willing to provide clean patches, once I know which of above suggestions to implement. This would be much easier when the worker code would be moved out of the program files, into dedicated units. Then the modifications to the program files can be separated from modifications to the worker unit(s). DoDi ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
On Fri, 16 Dec 2011, Hans-Peter Diettrich wrote: When MakeSkel shall use FPDoc projects, this can be achieved by adding something like: procedure LoadProject(const Arg: string); begin ProjectName := Arg; Project := TFPDocProject.Create(Nil); //owner component? With TXMLFPDocOptions.Create(Project) do try LoadOptionsFromFile(Project,Arg); if (PackageName = '') and (Project.Packages.Count 0) then PackageName := Project.Packages[0].Name; finally Free; end; end; Handling of the InputFiles and DescrFiles can be added similar to above handling of the (default) PackageName, e.g. if assigned(Project) then //the package *must* be part of the project Pkg := Project.Packages.FindPackage(PackageName) else Pkg := nil; //project not usable if assigned(Pkg) then begin InputFiles.Assign(Pkg.Inputs); DescrFiles.Assign(Pkg.Descriptions); //extract further options? end; DocumentPackage(...) Since new description files should be added to the project, I'd suggest that MakeSkel uses a Project and the lists as stored in it, instead of the InputFiles and DescrFiles variables. This change only affects the program code, which passes these lists to DocumentPackage. Then the created skeletons can be added to the DescrFiles list, and the updated project can be saved on exit. I don't think this is good. makeskel creates a diff, you should not add this to the list of files; instead, after it was created, it should be merged with the original file. Furthermore it should be possible to process a single module from a project package, for which e.g. a skeleton shall be created, or which should be checked for errors by fpdoc. This requires that the --input value selects one of the input files in the project. This can be simplified by splitting the InputFile strings, into File and Options parts, as is already done in the project files. The stringlist representation could e.g. look like file=options, so that IndexOfName can be used to select an entry, and the = is replaced by an space before the entry is passed to the worker code. Then also another option --unit=unit-name can be used to select the specific input file to process. Then the stringlist representation also can be changed to unit-name=existing --input descriptor, and Values[unit-name] can be passed to the worker code. No. You forget that the coupling with unit names does not exist. Currently FPDoc scans the commandline for a project first, before parsing the other options. This extra handling could be removed, with the effect that options before the --project option are defaults, which are overridden by the project settings, while options after --project override the project settings. This consideration applies to all programs, which accept an fpdoc project. Well, I don't like the fact that order of command-line options is important. Given that, I don't see how you can avoid scanning for a project first. Michael. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
Michael Van Canneyt schrieb: Then the created skeletons can be added to the DescrFiles list, and the updated project can be saved on exit. I don't think this is good. makeskel creates a diff, you should not add this to the list of files; instead, after it was created, it should be merged with the original file. Plase keep --update mode (what you mean) distinct from normal mode (create new skeleton). Furthermore it should be possible to process a single module from a project package, for which e.g. a skeleton shall be created, or which should be checked for errors by fpdoc. This requires that the --input value selects one of the input files in the project. This can be simplified by splitting the InputFile strings, into File and Options parts, as is already done in the project files. The stringlist representation could e.g. look like file=options, so that IndexOfName can be used to select an entry, and the = is replaced by an space before the entry is passed to the worker code. Then also another option --unit=unit-name can be used to select the specific input file to process. Then the stringlist representation also can be changed to unit-name=existing --input descriptor, and Values[unit-name] can be passed to the worker code. No. You forget that the coupling with unit names does not exist. Please explain? Both FPDoc and MakeSkel accept one or more --input arguments, each representing one *unit*. When a project is used instead, either none or all units can be selected automatically, but not a single one. Consider an existing FPDoc project, which contains all input files and all currently existing description files. When you want to create a new skeleton for an not yet documented unit, how to achieve that? Should the user copy the stored --input specification for that unit *manually*, including all compiler options? And should he afterwards add the new description file to the project, by editing the project file manually again? Currently FPDoc scans the commandline for a project first, before parsing the other options. This extra handling could be removed, with the effect that options before the --project option are defaults, which are overridden by the project settings, while options after --project override the project settings. This consideration applies to all programs, which accept an fpdoc project. Well, I don't like the fact that order of command-line options is important. Well, I showed an practical use case, where such an order is useful. Given that, I don't see how you can avoid scanning for a project first. This means that you disallow for e.g. scripts which provide built-in defaults, that *should* be overridden by values stored in the project :-( Did you ever try to *work* with FPDoc projects? DoDi ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
On Fri, 16 Dec 2011, Hans-Peter Diettrich wrote: No. You forget that the coupling with unit names does not exist. Please explain? Both FPDoc and MakeSkel accept one or more --input arguments, each representing one *unit*. When a project is used instead, either none or all units can be selected automatically, but not a single one. Consider an existing FPDoc project, which contains all input files and all currently existing description files. When you want to create a new skeleton for an not yet documented unit, how to achieve that? Should the user copy the stored --input specification for that unit *manually*, including all compiler options? And should he afterwards add the new description file to the project, by editing the project file manually again? Your problem is a false one. I would never use a project file for this in the first place. You seem to assume that the project file *must* be used for makeskel. For me this is still highly questionable. If it can be done, fine. If not: also fine. Currently FPDoc scans the commandline for a project first, before parsing the other options. This extra handling could be removed, with the effect that options before the --project option are defaults, which are overridden by the project settings, while options after --project override the project settings. This consideration applies to all programs, which accept an fpdoc project. Well, I don't like the fact that order of command-line options is important. Well, I showed an practical use case, where such an order is useful. I must have missed that. How did you show this ? Given that, I don't see how you can avoid scanning for a project first. This means that you disallow for e.g. scripts which provide built-in defaults, that *should* be overridden by values stored in the project :-( Of course I disallow this. The working method is the opposite. The project provides defaults, to be overridden on the command line. The compiler functions exactly the same. Options on the command-line override ones in the config/project files. I don't know any tool that works opposite. Michael. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
Michael Van Canneyt schrieb: Consider an existing FPDoc project, which contains all input files and all currently existing description files. When you want to create a new skeleton for an not yet documented unit, how to achieve that? Should the user copy the stored --input specification for that unit *manually*, including all compiler options? And should he afterwards add the new description file to the project, by editing the project file manually again? Your problem is a false one. I would never use a project file for this in the first place. My argument for using projects is exactly that they contain the compiler options for all input files. You seem to assume that the project file *must* be used for makeskel. For me this is still highly questionable. If it can be done, fine. If not: also fine. ACK. There is no *need* to use MakeSkel with a project, but using this option offers many advantages. When we look at new packages, some general tasks come into mind: 1) Generate a working FPDoc project, containing all input files and their related compiler options. Collecting all input files is not normally a problem, but many files may deserve special compiler options. How to proceed, in case of problems? Running fpdoc until all settings are okay may be a bad solution, you better update and try individual options for the units with problems. 2) Add documentation. I'd prefer an option that creates skeletons for all units, others may prefer to create skeletons only for specific units, which then are documented one-by-one. In either case the description files should be added to the project automatically. 3) Check for updates. Here it depends on the amount of changes to the input files of a project (package), whether everything should go into an common update file, or into multiple files. Eventually the source directories should be scanned for moved or added input files, which should become part of the project as well. 4) Check documentation updates for syntax errors and bad links. Again a first run should reveal all errors, in all files, while fixing the errors will require multiple runs over the same input files. 5) Check documentation for completeness. A list of all not yet documented items should be generated, so that the user knows where the documentation should be completed. 6) Create final documentation. This is the typical use case for fpdoc, but now only one very specific case in the entire process of providing documentation. I'd prefer that all beforementioned tasks can be accomplished by a single program, by only giving it an project file, task, and task-specific options. Currently FPDoc scans the commandline for a project first, before parsing the other options. This extra handling could be removed, with the effect that options before the --project option are defaults, which are overridden by the project settings, while options after --project override the project settings. This consideration applies to all programs, which accept an fpdoc project. Well, I don't like the fact that order of command-line options is important. Well, I showed an practical use case, where such an order is useful. I must have missed that. How did you show this ? Think about an project file first, what does it contain? Then think about which of the stored options may deserve an override, or which require overrides in specific use cases. Also keep in mind that project files may be distributed, and that the target environments may deserve certain modifications. When I use make all, to create the full RTL/FCL documentation on Windows, the resulting commandline does not always reflect the intentions of the documentation writers (on Linux). It IMO is a bad idea to store the OS and CPU targets and the output format in an project file. Given that, I don't see how you can avoid scanning for a project first. This means that you disallow for e.g. scripts which provide built-in defaults, that *should* be overridden by values stored in the project :-( Of course I disallow this. The working method is the opposite. The project provides defaults, to be overridden on the command line. This is how you have learned or expect it to work. My approach may be quite different from your habits. Consider what has to be done when input files are added - the required updates depend on the source (script, Makefile) that creates a commandline. Currently only two options exist, to replace the existing project file by a new one, based on the generated command line, or to search for differences between the commandline and the existing project file. An automatic update wipes out all previously added (compiler) options, a manual compare is error prone by nature :-( DoDi ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
