Re: [fpc-devel] MakeSkel and FPDoc projects
Am 19.12.2011 04:05 schrieb Hans-Peter Diettrich drdiettri...@aol.com: Mattias Gaertner schrieb: I understand that conflicts can arise, when the same XML file is modified by different means. But it is not nice when the IDE then crashes. Can you create a stacktrace? How? The IDE only disappears, silently, including the console window :-( Then you need to start Lazarus with appropriate arguments from a cmd (or PowerShell) window. Regards, Sven ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
On Sun, 18 Dec 2011, Hans-Peter Diettrich wrote: Michael Van Canneyt schrieb: I have done so for years, with the existing tools, using the Makefiles. No changes were necessary. Can you explain that a bit more? I'm not a professional commandline user, perhaps I'm doing something stupid? I just do a make updatexml or make updatefclxml or make updatertlxml The makefile contains all commands necessary to create a unitname.new.xml for all units that have changed modifiers. It tries to remove empty ones. How can I know what the makefile contains? By opening it with a text editor and studying the contents. Does it also work for the LCL? ;-) I don't know, but if there is a makefile: check it. Michael. ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
On Sat, 17 Dec 2011 17:06:21 +0100 Hans-Peter Diettrich drdiettri...@aol.com wrote: Mattias Gaertner schrieb: On Sat, 17 Dec 2011 15:41:32 +0100 Hans-Peter Diettrich drdiettri...@aol.com wrote: [...] The documentation related features could become Lazarus plug-ins, of course, similar to or as an extension of the FPDoc Editor window. But this already existing support makes it *harder* to add further functionality - it's quite easy to crash the IDE when editing the documentation file for an open unit :-( How? Approximately like this: Edit an XML file in the IDE, then edit an entry in the FPDoc Editor window and press Save. I understand that conflicts can arise, when the same XML file is modified by different means. But it is not nice when the IDE then crashes. Can you create a stacktrace? Mattias ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
Mattias Gaertner schrieb: I understand that conflicts can arise, when the same XML file is modified by different means. But it is not nice when the IDE then crashes. Can you create a stacktrace? How? The IDE only disappears, silently, including the console window :-( 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 Sat, 17 Dec 2011, Hans-Peter Diettrich wrote: Michael Van Canneyt schrieb: 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: [snip] 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. Feel free to create this program. If I may give some advice: the tasks you outline belong in a Documentation writers IDE. fpdoc and makeskel are command-line tools, not IDEs. IMHO you should concentrate on enhancing lazde or lazdoc, so they call fpdoc and makeskel with whatever options you see fit. Just like Lazarus is a front-end for the compiler, with its own options, config files and whatnot. But in the end, it calls the compiler, and lets the compiler do what it does best: compile pascal code. The IDE itself manages 'projects' and packages and whatnot: it helps you organize your work. (the lazarus IDE does a lot more, of course) You seem to have the typical windows-users approach: all in one program. I am more an advocate of the Unix approach: many small programs that cooperate together. fpdoc and makeskel are the result of the latter approach. I will not cooperate on efforts to make them into one-tool-for-all-tasks programs. I will cooperate on additional options which enhance the operation of the tools within the frame of their purpose, as I have done recently. I think that makeskel can be enhanced to use a project file to create an update for a single unit file, to spare you the effort of typing all options again, but that's about it. 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. 1. No-one says that you must store all these options. While the fpdoc project file *can* contain all options, it does not mean that it *must* contain all options. 2. If command-line options override the defaults in the file (as they do), you just need to specify the correct options on the command-line in case the project file contains the wrong ones. 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 person has nothing to do with it. This is the result of many years of experience of many programmers in many open source projects: a config file for defaults, command-line options to override the defaults. It's simply standard operating procedure, which has proven its usefulness over the years. But yes, it is a typical Unix approach. 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: When we look at new packages, some general tasks come into mind: [snip] 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. Feel free to create this program. If I may give some advice: the tasks you outline belong in a Documentation writers IDE. To some degree, maybe. But checking for updates should be doable by a script, without a need to open an IDE - for every single package! fpdoc and makeskel are command-line tools, not IDEs. IMHO you should concentrate on enhancing lazde or lazdoc, so they call fpdoc and makeskel with whatever options you see fit. For that purpose such an IDE *also* must be extended with projects, what's much more complicated than making use of the projects in the commandline tools. I already tried to adopt LazDE to my needs, for use with kind of projects, but gave up after several weeks of fruitless tries. Tweaking the commandline tools is much easier, each one boils down to essentially a single worker procedure, which is easy to parametrize :-) Just like Lazarus is a front-end for the compiler, with its own options, config files and whatnot. But in the end, it calls the compiler, and lets the compiler do what it does best: compile pascal code. The IDE itself manages 'projects' and packages and whatnot: it helps you organize your work. (the lazarus IDE does a lot more, of course) The documentation related features could become Lazarus plug-ins, of course, similar to or as an extension of the FPDoc Editor window. But this already existing support makes it *harder* to add further functionality - it's quite easy to crash the IDE when editing the documentation file for an open unit :-( You seem to have the typical windows-users approach: all in one program. I am more an advocate of the Unix approach: many small programs that cooperate together. fpdoc and makeskel are the result of the latter approach. I will not cooperate on efforts to make them into one-tool-for-all-tasks programs. Right, I don't like the Unix approach, but almost only for one reason: building the commandlines for using these tools is a mess, hardly doable without obscure scripts in whatever additional langugage. I had much less problems with a *library* of tool components, configurable and callable from Pascal code. That's why I tried to separate the commandline interface from the worker code of FPDoc and MakeSkel, what turned out doable by a simple patch. Now I have all options to integrate the essential functionality of these tools into other programs, be GUI or CLI :-) I will cooperate on additional options which enhance the operation of the tools within the frame of their purpose, as I have done recently. I think that makeskel can be enhanced to use a project file to create an update for a single unit file, to spare you the effort of typing all options again, but that's about it. This would be very kind, of course :-) Can you also add this option to FPDoc, so that it will allow to do a test build for an single unit file? 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. 1. No-one says that you must store all these options. While the fpdoc project file *can* contain all options, it does not mean that it *must* contain all options. Consider what happens when FPDoc, MakeSkel or MkFpdocProj *update* a project - a new file will be created, that contains whatever the programs have extracted from the input project, and whatever else they find worth to store in the output project. When they do not update the projects themselves, how can the user be informed of possible changes, so that he can update the project file himself? Currently changes to the RTL and FCL (MakeFiles) require a dry-run of make, analysis of the resulting commandline, and a manual merge with the existing project. According to the Unix philosophy another tool is required, that automates the project file update, and one more for updating the project file when description files are added... 2. If command-line options override the defaults in the file (as they do), you just need to specify the correct options on the command-line in case the project file contains the wrong ones. This means in practice that almost all settings have to be given on the commandline (except the file lists), or to inspect
Re: [fpc-devel] MakeSkel and FPDoc projects
On Sat, 17 Dec 2011 15:41:32 +0100 Hans-Peter Diettrich drdiettri...@aol.com wrote: [...] The documentation related features could become Lazarus plug-ins, of course, similar to or as an extension of the FPDoc Editor window. But this already existing support makes it *harder* to add further functionality - it's quite easy to crash the IDE when editing the documentation file for an open unit :-( How? Mattias ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
On Sat, 17 Dec 2011, Hans-Peter Diettrich wrote: Michael Van Canneyt schrieb: Feel free to create this program. If I may give some advice: the tasks you outline belong in a Documentation writers IDE. To some degree, maybe. But checking for updates should be doable by a script, without a need to open an IDE - for every single package! I have done so for years, with the existing tools, using the Makefiles. No changes were necessary. So you'll hopefully excuse me if I think you are seeking problems where there are none... I will cooperate on additional options which enhance the operation of the tools within the frame of their purpose, as I have done recently. I think that makeskel can be enhanced to use a project file to create an update for a single unit file, to spare you the effort of typing all options again, but that's about it. This would be very kind, of course :-) Can you also add this option to FPDoc, so that it will allow to do a test build for an single unit file? Yes, this was already planned. Consider what happens when FPDoc, MakeSkel or MkFpdocProj *update* a project - a new file will be created, that contains whatever the programs have extracted from the input project, and whatever else they find worth to store in the output project. When they do not update the projects themselves, how can the user be informed of possible changes, so that he can update the project file himself? That is where your IDE jumps in. Currently changes to the RTL and FCL (MakeFiles) require a dry-run of make, analysis of the resulting commandline, and a manual merge with the existing project. According to the Unix philosophy another tool is required, that automates the project file update, and one more for updating the project file when description files are added... According to Unix philosophy, the person doing so is aware of what he is doing, and makes the necessary changes (if there are such changes) to the project file himself. I do not believe the tools can make the correct decisions, except in the most trivial circumstances. 2. If command-line options override the defaults in the file (as they do), you just need to specify the correct options on the command-line in case the project file contains the wrong ones. This means in practice that almost all settings have to be given on the commandline (except the file lists), or to inspect every single project for the contained settings, in order to find out what must not necessarily be overridden. Of course. No tool can do this for you, for the very simple fact that computers are very stupid. They can help you organize your life, but they do not organize your life for you. You are in the driver's seat, not the computer. But when I have to use Lazarus with different settings, for building applications (last release or trunk, with or without patches for a dockable IDE), and for different FPC versions (e.g. trunk for building the documentation tools), life can become very complicated :-( No doubt. But instead of blaming the tools, maybe you should reconsider the way you organize your work. I have many versions of FPC and Lazarus floating around, on various platforms. I seem not to have all these problems you are experiencing, yet I use the same tools. So excuse me for believing that the problem is not in the tools :-) 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.vancann...@wisa.be schrieb: On Sat, 17 Dec 2011, Hans-Peter Diettrich wrote: Michael Van Canneyt schrieb: Feel free to create this program. If I may give some advice: the tasks you outline belong in a Documentation writers IDE. To some degree, maybe. But checking for updates should be doable by a script, without a need to open an IDE - for every single package! I have done so for years, with the existing tools, using the Makefiles. No changes were necessary. Can you explain that a bit more? I'm not a professional commandline user, perhaps I'm doing something stupid? BTW I mean tracking changes in the source code, which require to update the documentation files accordingly (makeskel --update ...). I don't see how a Makefile is involved in this task? This is different from the following: Currently changes to the RTL and FCL (MakeFiles) require a dry-run of make, analysis of the resulting commandline, and a manual merge with the existing project. According to the Unix philosophy another tool is required, that automates the project file update, and one more for updating the project file when description files are added... According to Unix philosophy, the person doing so is aware of what he is doing, and makes the necessary changes (if there are such changes) to the project file himself. I do not believe the tools can make the correct decisions, except in the most trivial circumstances. The tool should update the file lists *only* (input, descr), and leave everything else in the project file unmodified. This has not been a big problem with textual INI files, but the XML project files can contain further information (element attributes...), that is interleaved with the filename entries. But when I have to use Lazarus with different settings, for building applications (last release or trunk, with or without patches for a dockable IDE), and for different FPC versions (e.g. trunk for building the documentation tools), life can become very complicated :-( No doubt. But instead of blaming the tools, maybe you should reconsider the way you organize your work. I have many versions of FPC and Lazarus floating around, on various platforms. I seem not to have all these problems you are experiencing, yet I use the same tools. So excuse me for believing that the problem is not in the tools :-) Depends on the tools. There is not much choice in using an hammer, but computer tools more ressemble complex production robots... DoDi ___ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel
Re: [fpc-devel] MakeSkel and FPDoc projects
Mattias Gaertner schrieb: On Sat, 17 Dec 2011 15:41:32 +0100 Hans-Peter Diettrich drdiettri...@aol.com wrote: [...] The documentation related features could become Lazarus plug-ins, of course, similar to or as an extension of the FPDoc Editor window. But this already existing support makes it *harder* to add further functionality - it's quite easy to crash the IDE when editing the documentation file for an open unit :-( How? Approximately like this: Edit an XML file in the IDE, then edit an entry in the FPDoc Editor window and press Save. I understand that conflicts can arise, when the same XML file is modified by different means. But it is not nice when the IDE then crashes. 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 Sat, 17 Dec 2011, Hans-Peter Diettrich wrote: michael.vancann...@wisa.be schrieb: On Sat, 17 Dec 2011, Hans-Peter Diettrich wrote: Michael Van Canneyt schrieb: Feel free to create this program. If I may give some advice: the tasks you outline belong in a Documentation writers IDE. To some degree, maybe. But checking for updates should be doable by a script, without a need to open an IDE - for every single package! I have done so for years, with the existing tools, using the Makefiles. No changes were necessary. Can you explain that a bit more? I'm not a professional commandline user, perhaps I'm doing something stupid? I just do a make updatexml or make updatefclxml or make updatertlxml The makefile contains all commands necessary to create a unitname.new.xml for all units that have changed modifiers. It tries to remove empty ones. BTW I mean tracking changes in the source code, which require to update the documentation files accordingly (makeskel --update ...). I don't see how a Makefile is involved in this task? This is different from the following: Currently changes to the RTL and FCL (MakeFiles) require a dry-run of make, analysis of the resulting commandline, and a manual merge with the existing project. According to the Unix philosophy another tool is required, that automates the project file update, and one more for updating the project file when description files are added... According to Unix philosophy, the person doing so is aware of what he is doing, and makes the necessary changes (if there are such changes) to the project file himself. I do not believe the tools can make the correct decisions, except in the most trivial circumstances. The tool should update the file lists *only* (input, descr), and leave everything else in the project file unmodified. This has not been a big problem with textual INI files, but the XML project files can contain further information (element attributes...), that is interleaved with the filename entries. It's not a technical issue. It's an issue that the tool does not know whether something requires changing or not. The makefile can create the .new.xml files, but a human (me) needs to examine them and decide if something needs to be merged to the original files or not. This decision cannot be automated. 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: I have done so for years, with the existing tools, using the Makefiles. No changes were necessary. Can you explain that a bit more? I'm not a professional commandline user, perhaps I'm doing something stupid? I just do a make updatexml or make updatefclxml or make updatertlxml The makefile contains all commands necessary to create a unitname.new.xml for all units that have changed modifiers. It tries to remove empty ones. How can I know what the makefile contains? Does it also work for the LCL? ;-) 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
