Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On Sun, Feb 5, 2012 at 6:50 PM, Eric Noulard eric.noul...@gmail.com wrote: 2012/2/1 David Cole david.c...@kitware.com: There's no rush here. We won't be reviewing your changes again until next Tuesday at this point... Hi all, I did push the work and the branch a little further yesterday. I didn't get any big red on the dashboard this time and I think it was worth going a little further. There is this issue on the dashboard: http://cdash.org/CDash/viewBuildError.php?buildid=1981062 Use empty string assignment: std::string s; s = ; ...instead of clear to avoid this problem on our (yes, I know, ancient, but annoyingly still there) VS6 dashboards. Thanks, David -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/2/6 David Cole david.c...@kitware.com: On Sun, Feb 5, 2012 at 6:50 PM, Eric Noulard eric.noul...@gmail.com wrote: 2012/2/1 David Cole david.c...@kitware.com: There's no rush here. We won't be reviewing your changes again until next Tuesday at this point... Hi all, I did push the work and the branch a little further yesterday. I didn't get any big red on the dashboard this time and I think it was worth going a little further. There is this issue on the dashboard: http://cdash.org/CDash/viewBuildError.php?buildid=1981062 Use empty string assignment: std::string s; s = ; ...instead of clear to avoid this problem on our (yes, I know, ancient, but annoyingly still there) VS6 dashboards. OK noted. Just fixed and pushed to next as well. I'm subscribed to CMake dashboard and I don't think I received that alert? Any reason for that? -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/2/1 David Cole david.c...@kitware.com: There's no rush here. We won't be reviewing your changes again until next Tuesday at this point... Hi all, I did push the work and the branch a little further yesterday. I didn't get any big red on the dashboard this time and I think it was worth going a little further. It is not finished but it is already working relatively well so I think it's worth merging. Waiting for your feedback before going further, The next steps for this work may be: 0) Understand how to remove CMake leftovers from cpack --help-full (CMake properties and some CMake variables sections) May be some of you may be faster than for understanding that since CTest does not suffer from the same issue... At the same time it would be nice if we could create doc sections from ##section markup and not burry [All] section names in the C++ code. 1) Complete CPack variable doc * for variables common to all generators * for variable specific to each generator 2) Set up something for cmake --help- which makes it possible to parse doc in user scripts and/or cmake provided modules and get variables and command from it. 4) Do something with the ##module part of the doc. 5) Apply same principle in order to document CTest variables. Happy review :-] -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On Wed, Feb 1, 2012 at 2:27 AM, Rolf Eike Beer e...@sf-mail.de wrote: Am Dienstag, 31. Januar 2012, 23:39:30 schrieb Eric Noulard: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Eric Noulard wrote: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Should be fixed and pushed. Merge topic 'ImproveCPackDoc-reloaded' into next cc4ac32 Calm down compiler warning about unused var 1b31c19 Fix potential bad memory access, thanks to Rolf You should go and fix this or I will be angry with you for ages. ;) Is my approximate English wording giving me trouble again or are you just kidding? What's wrong with the comment? My name ;) -- Eike -- ok right sorry about that, won't happen again. Don't get me wrong: I wont bite because of that. And I tend to ignore if people always get it wrong in mails. I just don't want to see it wrong in changelogs ;) Eike -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers So it looks like Eike made the commit-log-only change to correct the spelling, re-writing the commit, and pushed the branch to stage again, but did NOT merge it to 'next'. Eric, please re-fetch from the stage, continue the topic development to clean up the dashboard warnings (configure and build) and then push it back to stage and merge to 'next' again when it's ready. Some examples of dashboard issues that are due to this branch: http://cdash.org/CDash/viewBuildError.php?type=1buildid=1966772 http://cdash.org/CDash/viewConfigure.php?buildid=1966511 http://cdash.org/CDash/viewBuildError.php?type=1buildid=1966456 Thanks, David -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/2/1 Eric Noulard eric.noul...@gmail.com: 2012/2/1 David Cole david.c...@kitware.com: On Wed, Feb 1, 2012 at 2:27 AM, Rolf Eike Beer e...@sf-mail.de wrote: Am Dienstag, 31. Januar 2012, 23:39:30 schrieb Eric Noulard: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Eric Noulard wrote: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Should be fixed and pushed. Merge topic 'ImproveCPackDoc-reloaded' into next cc4ac32 Calm down compiler warning about unused var 1b31c19 Fix potential bad memory access, thanks to Rolf You should go and fix this or I will be angry with you for ages. ;) Is my approximate English wording giving me trouble again or are you just kidding? What's wrong with the comment? My name ;) -- Eike -- ok right sorry about that, won't happen again. Don't get me wrong: I wont bite because of that. And I tend to ignore if people always get it wrong in mails. I just don't want to see it wrong in changelogs ;) Eike -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers So it looks like Eike made the commit-log-only change to correct the spelling, re-writing the commit, and pushed the branch to stage again, but did NOT merge it to 'next'. Yes right I've just seen that while trying to fix dashboard warnings. Eric, please re-fetch from the stage, continue the topic development to clean up the dashboard warnings (configure and build) and then push it back to stage and merge to 'next' again when it's ready. Should be done now. Some examples of dashboard issues that are due to this branch: http://cdash.org/CDash/viewBuildError.php?type=1buildid=1966772 http://cdash.org/CDash/viewConfigure.php?buildid=1966511 http://cdash.org/CDash/viewBuildError.php?type=1buildid=1966456 Those ones should be fixed. I did not fix all these at once so multiple commit may need squashing. Bill point me to this one: http://www.cdash.org/CDash/viewBuildError.php?buildid=1966258 but I don't thinks it come from this branch? Moreover I cannot anything on the reported lines? LEN : Line length exceed 81 (max=79) [Line Length = 79 max chars] (2207) LEN : Line length exceed 80 (max=79) [Line Length = 79 max chars] (2224) nor in the commit changes; http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=1629615a10df10296ba6588f66a680eed424f9ba#patch12 Did break it again. Sorry I should really avoid working in a hurry. fixing it. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On Wed, Feb 1, 2012 at 3:17 PM, Eric Noulard eric.noul...@gmail.com wrote: 2012/2/1 Eric Noulard eric.noul...@gmail.com: 2012/2/1 David Cole david.c...@kitware.com: On Wed, Feb 1, 2012 at 2:27 AM, Rolf Eike Beer e...@sf-mail.de wrote: Am Dienstag, 31. Januar 2012, 23:39:30 schrieb Eric Noulard: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Eric Noulard wrote: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Should be fixed and pushed. Merge topic 'ImproveCPackDoc-reloaded' into next cc4ac32 Calm down compiler warning about unused var 1b31c19 Fix potential bad memory access, thanks to Rolf You should go and fix this or I will be angry with you for ages. ;) Is my approximate English wording giving me trouble again or are you just kidding? What's wrong with the comment? My name ;) -- Eike -- ok right sorry about that, won't happen again. Don't get me wrong: I wont bite because of that. And I tend to ignore if people always get it wrong in mails. I just don't want to see it wrong in changelogs ;) Eike -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers So it looks like Eike made the commit-log-only change to correct the spelling, re-writing the commit, and pushed the branch to stage again, but did NOT merge it to 'next'. Yes right I've just seen that while trying to fix dashboard warnings. Eric, please re-fetch from the stage, continue the topic development to clean up the dashboard warnings (configure and build) and then push it back to stage and merge to 'next' again when it's ready. Should be done now. Some examples of dashboard issues that are due to this branch: http://cdash.org/CDash/viewBuildError.php?type=1buildid=1966772 http://cdash.org/CDash/viewConfigure.php?buildid=1966511 http://cdash.org/CDash/viewBuildError.php?type=1buildid=1966456 Those ones should be fixed. I did not fix all these at once so multiple commit may need squashing. Bill point me to this one: http://www.cdash.org/CDash/viewBuildError.php?buildid=1966258 but I don't thinks it come from this branch? Moreover I cannot anything on the reported lines? LEN : Line length exceed 81 (max=79) [Line Length = 79 max chars] (2207) LEN : Line length exceed 80 (max=79) [Line Length = 79 max chars] (2224) nor in the commit changes; http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=1629615a10df10296ba6588f66a680eed424f9ba#patch12 Did break it again. Sorry I should really avoid working in a hurry. fixing it. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org There's no rush here. We won't be reviewing your changes again until next Tuesday at this point... -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/25 Brad King brad.k...@kitware.com: On 1/25/2012 3:20 PM, Eric Noulard wrote: So with my proposal you can perfectly document a script in the middle of the file or as usual just in front of the concerned macro/function/var. This may be easier for doc maintenance because the function/macro would be closer to its doc. Nice. My idea for user script doc support may be to add an extra cdoc command that would be dedicated to documentation of script files: I think cmake --doc is better than a new command tool in the PATH. An alternative would be to defined something like: CMAKE_USER_DOC_PATHS CPACK_USER_DOC_PATHS CTEST_USER_DOC_PATHS If a module does not come with CMake I'd rather ask the user to explicitly list the modules to be included in a documentation request on the command line. The limitation I personnally see in such kind of markup is that it cannot be very much enhanced (cross-link, more text formatting like bold, italic, etc...) without breaking current doc parser. I'd rather switch to a real documentation engine like asciidoc than implement all those markup capabilities. We'd need one that can handle literate programming for .cmake modules though. Brad, Do you mean that I should drop the current work and go for asciidoc (and leaving backward compatibility alltogether) or that the current markup is ok (and could be merged to next) and that we could go a step further by using asciidoc later or only inside the current preformatted doc? Concerning asciidoc, do you want to examine alternative like RST http://blog.ser1.net/2011/06/restructuredtext-vs-asciidoc.html I did gave some example back in october: http://www.cmake.org/pipermail/cmake/2011-October/047071.html The main trouble with asciidoc or RST is that I didn't find a C/C++ parser to easily embed in CMake and it doesn't seem that easy to implement by hand. My personal best choice would be to keep the proposed markup and use asciidoc/RST inside the free text block. Such that --help- command could spit out asiidoc/RST that can be further processed by appropriate tools external to CMake. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
Ok Agreed.
Just merged the branch to next.
Just spotted a bug in it:
@@ -559,6 +511,8 @@ bool cmDocumentation::CreateSingleModule(const char*
fname,
{
if(line.size() line[0] == '#')
{
+ /* line beginnings with ## are mark-up ignore them */
+ if (line[1] == '#') continue;
// blank line
if(line.size() = 2)
Just assume line is #, then you will access beyond end of line.
Eike
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/31 Rolf Eike Beer e...@sf-mail.de:
Ok Agreed.
Just merged the branch to next.
Just spotted a bug in it:
@@ -559,6 +511,8 @@ bool cmDocumentation::CreateSingleModule(const char*
fname,
{
if(line.size() line[0] == '#')
{
+ /* line beginnings with ## are mark-up ignore them */
+ if (line[1] == '#') continue;
// blank line
if(line.size() = 2)
Just assume line is #, then you will access beyond end of line.
Nice catch I'll fix it later tonight.
--
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/31 Eric Noulard eric.noul...@gmail.com:
2012/1/31 Rolf Eike Beer e...@sf-mail.de:
Ok Agreed.
Just merged the branch to next.
Just spotted a bug in it:
@@ -559,6 +511,8 @@ bool cmDocumentation::CreateSingleModule(const char*
fname,
{
if(line.size() line[0] == '#')
{
+ /* line beginnings with ## are mark-up ignore them */
+ if (line[1] == '#') continue;
// blank line
if(line.size() = 2)
Just assume line is #, then you will access beyond end of line.
Nice catch I'll fix it later tonight.
Should be fixed and pushed.
Merge topic 'ImproveCPackDoc-reloaded' into next
cc4ac32 Calm down compiler warning about unused var
1b31c19 Fix potential bad memory access, thanks to Rolf
--
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
Eric Noulard wrote:
2012/1/31 Eric Noulard eric.noul...@gmail.com:
2012/1/31 Rolf Eike Beer e...@sf-mail.de:
Ok Agreed.
Just merged the branch to next.
Just spotted a bug in it:
@@ -559,6 +511,8 @@ bool cmDocumentation::CreateSingleModule(const char*
fname,
{
if(line.size() line[0] == '#')
{
+ /* line beginnings with ## are mark-up ignore them */
+ if (line[1] == '#') continue;
// blank line
if(line.size() = 2)
Just assume line is #, then you will access beyond end of line.
Nice catch I'll fix it later tonight.
Should be fixed and pushed.
Merge topic 'ImproveCPackDoc-reloaded' into next
cc4ac32 Calm down compiler warning about unused var
1b31c19 Fix potential bad memory access, thanks to Rolf
You should go and fix this or I will be angry with you for ages. ;)
Eike
--
signature.asc
Description: This is a digitally signed message part.
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
Am Dienstag, 31. Januar 2012, 23:39:30 schrieb Eric Noulard: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Eric Noulard wrote: 2012/1/31 Rolf Eike Beer e...@sf-mail.de: Should be fixed and pushed. Merge topic 'ImproveCPackDoc-reloaded' into next cc4ac32 Calm down compiler warning about unused var 1b31c19 Fix potential bad memory access, thanks to Rolf You should go and fix this or I will be angry with you for ages. ;) Is my approximate English wording giving me trouble again or are you just kidding? What's wrong with the comment? My name ;) -- Eike -- ok right sorry about that, won't happen again. Don't get me wrong: I wont bite because of that. And I tend to ignore if people always get it wrong in mails. I just don't want to see it wrong in changelogs ;) Eike signature.asc Description: This is a digitally signed message part. -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On 1/24/2012 5:50 PM, Eric Noulard wrote: cmake --help-module CPackComponent or any other (untouched module) cmake --help-module FindQt4 you'll see that the extra space are there as well. So yes there is too much space, but this is not due to my current proposal, it was there before. We can handle that separately. Agreed. Sorry, I forgot that this problem already existed. It was created by the original module documentation extractor. It inconsistently treats transitions from paragraph text to preformatted text and back, giving the latter extra blank lines. Now we can't fix it without changing the formatting of all the existing documentation. (Perhaps the markup can help with that later.) I won't be doing this now I'd rather agree on the new markup feature first. The markup feature looks fine to me. The markup syntax adds some information even for those reading the raw source. I don't know if others have an opinion though. -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/25 Brad King brad.k...@kitware.com: On 1/24/2012 5:50 PM, Eric Noulard wrote: cmake --help-module CPackComponent or any other (untouched module) cmake --help-module FindQt4 you'll see that the extra space are there as well. So yes there is too much space, but this is not due to my current proposal, it was there before. We can handle that separately. Agreed. Sorry, I forgot that this problem already existed. It was created by the original module documentation extractor. It inconsistently treats transitions from paragraph text to preformatted text and back, giving the latter extra blank lines. Now we can't fix it without changing the formatting of all the existing documentation. (Perhaps the markup can help with that later.) I won't be doing this now I'd rather agree on the new markup feature first. The markup feature looks fine to me. The markup syntax adds some information even for those reading the raw source. Yes and I forgot to mention that it has a extra feature compared to the current module doc parser. It does look for markup on the **whole** file unlike current module doc parser which only parse the header (at the beginning of the file). So with my proposal you can perfectly document a script in the middle of the file or as usual just in front of the concerned macro/function/var. This may be easier for doc maintenance because the function/macro would be closer to its doc. This could be further used for user script that could be documented this way as well. My idea for user script doc support may be to add an extra cdoc command that would be dedicated to documentation of script files: a) cdoc --help-command-list yourscript.cmake b) cdoc --help-variable-list yourscript.cmake c) cdoc --help yourscript.cmake may spit out: a) the doc for macro/function in the concerned script b) the doc for variables c) all doc this command may have more versatile option to include or exclude (cmake/ctest/cpack) doc and/or add some path where to parse all *.cmake files etc An alternative would be to defined something like: CMAKE_USER_DOC_PATHS CPACK_USER_DOC_PATHS CTEST_USER_DOC_PATHS that could contain a list of user set PATHS containing *.cmake files and then cmake ---help-command-list would also load and parse all *.cmake files found in CMAKE_USER_DOC_PATHS. whatever the idea we should be able to share: - the markup for CMake/CTest/CPack **and** user scripts - the doc parser and formatter. I don't know if others have an opinion though. Opinion/feedback from other are more than welcome. The limitation I personnally see in such kind of markup is that it cannot be very much enhanced (cross-link, more text formatting like bold, italic, etc...) without breaking current doc parser. So if we accept to break backward compatible module doc parser we could easily add more advance markup. An intermediate option would be to trap to more advanced markup only in a new markup section. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On 1/25/2012 3:20 PM, Eric Noulard wrote: So with my proposal you can perfectly document a script in the middle of the file or as usual just in front of the concerned macro/function/var. This may be easier for doc maintenance because the function/macro would be closer to its doc. Nice. My idea for user script doc support may be to add an extra cdoc command that would be dedicated to documentation of script files: I think cmake --doc is better than a new command tool in the PATH. An alternative would be to defined something like: CMAKE_USER_DOC_PATHS CPACK_USER_DOC_PATHS CTEST_USER_DOC_PATHS If a module does not come with CMake I'd rather ask the user to explicitly list the modules to be included in a documentation request on the command line. The limitation I personnally see in such kind of markup is that it cannot be very much enhanced (cross-link, more text formatting like bold, italic, etc...) without breaking current doc parser. I'd rather switch to a real documentation engine like asciidoc than implement all those markup capabilities. We'd need one that can handle literate programming for .cmake modules though. -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On Wednesday 25 January 2012, Eric Noulard wrote: 2012/1/25 Brad King brad.k...@kitware.com: On 1/24/2012 5:50 PM, Eric Noulard wrote: cmake --help-module CPackComponent or any other (untouched module) cmake --help-module FindQt4 you'll see that the extra space are there as well. So yes there is too much space, but this is not due to my current proposal, it was there before. We can handle that separately. Agreed. Sorry, I forgot that this problem already existed. It was created by the original module documentation extractor. It inconsistently treats transitions from paragraph text to preformatted text and back, giving the latter extra blank lines. Now we can't fix it without changing the formatting of all the existing documentation. (Perhaps the markup can help with that later.) I won't be doing this now I'd rather agree on the new markup feature first. The markup feature looks fine to me. The markup syntax adds some information even for those reading the raw source. Yes and I forgot to mention that it has a extra feature compared to the current module doc parser. It does look for markup on the **whole** file unlike current module doc parser which only parse the header (at the beginning of the file). So with my proposal you can perfectly document a script in the middle of the file or as usual just in front of the concerned macro/function/var. This may be easier for doc maintenance because the function/macro would be closer to its doc. This could be further used for user script that could be documented this way as well. My idea for user script doc support may be to add an extra cdoc command that would be dedicated to documentation of script files: a) cdoc --help-command-list yourscript.cmake b) cdoc --help-variable-list yourscript.cmake c) cdoc --help yourscript.cmake may spit out: a) the doc for macro/function in the concerned script b) the doc for variables c) all doc this command may have more versatile option to include or exclude (cmake/ctest/cpack) doc and/or add some path where to parse all *.cmake files etc An alternative would be to defined something like: CMAKE_USER_DOC_PATHS CPACK_USER_DOC_PATHS CTEST_USER_DOC_PATHS cmake already supports CMAKE_MODULE_PATH for generating help, e.g. like this: $ cmake -DCMAKE_MODULE_PATH=$HOME/src/kdelibs/cmake/modules/ --help-custom- modules This generates docs for all cmake files in CMAKE_MODULE_PATH. --help-module also looks in CMAKE_MODULE_PATH. I'm not sure it needs a new variable. Alex -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/25 Alexander Neundorf neund...@kde.org: On Wednesday 25 January 2012, Eric Noulard wrote: cmake already supports CMAKE_MODULE_PATH for generating help, e.g. like this: $ cmake -DCMAKE_MODULE_PATH=$HOME/src/kdelibs/cmake/modules/ --help-custom- modules This generates docs for all cmake files in CMAKE_MODULE_PATH. --help-module also looks in CMAKE_MODULE_PATH. I'm not sure it needs a new variable. Right, my idea was different than the current --help-module because I intend to get variable or command using --help-variable-* --help-command-* for (may be user) scripts files. This is not the same as generating all doc for a bunch of modules. In my case you could do: cmake -DCMAKE_MODULE_PATH=$HOME/src/kdelibs/cmake/modules/ --help-command-list and get all commands defined (in fact documented) in the module file found in CMAKE_MODULE_PATH. ** this does not work [yet], because currently the list of .cmake files to be loaded for doc parsing is builtin the C++ code ** Nevertheless, Alex is right we can use user provided CMAKE_MODULE_PATH, no need to add more vars. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On 1/22/2012 7:58 AM, Eric Noulard wrote: 2012/1/3 Eric Noularderic.noul...@gmail.com: back to cleaner way of work. I did update and clean-up my previous attempt to ease documentation for CPack. http://public.kitware.com/Bug/view.php?id=10067 Thanks for working on this. the new up-to-date branch is stage/ImproveCPackDoc-reloaded I'd rather wait for feedback before merging this to next. Fast try is: cpack --help-variable-list cpack --help-command-list then chose whatever var / command you like. The documentation is extracted from files (CPack.cmake, CPackComponent.cmake, CPackRPM.cmake, CPackDeb.cmake) using new markup. I glanced through the changes and built the branch. It looks okay to me. One nitpick I have is that the generated documentation adds extra blank lines between paragraphs: - The cmake_add_component command describes an installation component, which the user can opt to install or remove as part of the graphical installation process. compname is the name of the component, as provided to the COMPONENT argument of one or more CMake INSTALL commands. DISPLAY_NAME is the displayed name of the component, used in graphical installers to display the component name. This value can be any string. DESCRIPTION is an extended description of the component, used in graphical installers to give the user additional information about the component. Descriptions can span multiple lines using \n as the line separator. Typically, these descriptions should be no more than a few lines long. - The markup parser needs to avoid adding the extra newline which tells the output formatter to start a new paragraph. Also I got an unused variable warning (-Wunused-variable) in cmDocumentation::addCTestStandardDocSections during the build. Thanks, -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/24 Brad King brad.k...@kitware.com: On 1/22/2012 7:58 AM, Eric Noulard wrote: 2012/1/3 Eric Noularderic.noul...@gmail.com: back to cleaner way of work. I did update and clean-up my previous attempt to ease documentation for CPack. http://public.kitware.com/Bug/view.php?id=10067 Thanks for working on this. I don't like writing doc but sometimes I'd like reading some so may be the second needs the first... :-] the new up-to-date branch is stage/ImproveCPackDoc-reloaded [...] I glanced through the changes and built the branch. It looks okay to me. One nitpick I have is that the generated documentation adds extra blank lines between paragraphs: Agreed...but... The markup parser needs to avoid adding the extra newline which tells the output formatter to start a new paragraph. after 1 hour + reading testing I'm now pretty sure that the parser is not the cuprit... (In fact I did avoid 1 extra line after the brief) The cmDocumentationFormatterText should be in fact if you look at the output of: cmake --help-module CPackComponent or any other (untouched module) cmake --help-module FindQt4 you'll see that the extra space are there as well. So yes there is too much space, but this is not due to my current proposal, it was there before. We can handle that separately. I won't be doing this now I'd rather agree on the new markup feature first. Also I got an unused variable warning (-Wunused-variable) in cmDocumentation::addCTestStandardDocSections during the build. This one is fixed. I pushed the branch forward. I fixed some prog. style and avoid an extra newline just after the brief. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On 1/2/2012 7:43 PM, Eric Noulard wrote: I try to push forward the feature request: http://public.kitware.com/Bug/view.php?id=10067 [snip] Anybody have some time to try this? I'd like to have some feedback before going on. The branch is stage/ImproveCPackDoc. Please factor out the completion, top-level command help, and other changes that do not introduce the new functionality. Put them in their own topic for separate review, and then rebase the main changes on it. That will make this much easier to review and test. Currently the new logic is split across a few commits so it is hard to follow. Thanks, -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/3 Brad King brad.k...@kitware.com: On 1/2/2012 7:43 PM, Eric Noulard wrote: I try to push forward the feature request: http://public.kitware.com/Bug/view.php?id=10067 [snip] Anybody have some time to try this? I'd like to have some feedback before going on. The branch is stage/ImproveCPackDoc. Please factor out the completion, top-level command help, and other changes that do not introduce the new functionality. Put them in their own topic for separate review, and then rebase the main changes on it. That will make this much easier to review and test. Currently the new logic is split across a few commits so it is hard to follow. Ok right I'll do that. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/3 Eric Noulard eric.noul...@gmail.com: 2012/1/3 Brad King brad.k...@kitware.com: On 1/2/2012 7:43 PM, Eric Noulard wrote: I try to push forward the feature request: http://public.kitware.com/Bug/view.php?id=10067 [snip] Anybody have some time to try this? I'd like to have some feedback before going on. The branch is stage/ImproveCPackDoc. Please factor out the completion, top-level command help, and other changes that do not introduce the new functionality. Put them in their own topic for separate review, and then rebase the main changes on it. That will make this much easier to review and test. Currently the new logic is split across a few commits so it is hard to follow. stage/CMake-completion-improvement contains the completion update. This can be merged to next/master independently from other because the changes won't be used unless the new options appears stage/ImproveCPackDoc-part1 contains changes that do not add features but document existing ones. Those topics are based on master from this morning (CEST). As such they may be merged to next and then to master as they are. I'll start another branch which will contain new feature only concerning true enhancement. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On 1/3/2012 11:03 AM, Eric Noulard wrote:
stage/ImproveCPackDoc-part1
contains changes that do not add features but document existing ones.
This one looks good. Please merge to next.
stage/CMake-completion-improvement
contains the completion update.
This can be merged to next/master independently from other
because the changes won't be used unless the new options appears
So you purposely refer to options that don't yet exist so they will
complete when they do? Is that only this hunk:
+--help-variable)
+local running=$(for x in `cpack --help-variable-list | grep -v cpack
version `; do echo ${x} ; done )
+COMPREPLY=( $(compgen -W ${running} -- ${cur}) )
+return 0
+;;
+--help-command)
+local running=$(for x in `cpack --help-command-list | grep -v cpack
version `; do echo ${x} ; done )
+COMPREPLY=( $(compgen -W ${running} -- ${cur}) )
+return 0
+;;
? I think that can that be left out and then included in the new
enhancement topic. It won't make the topic any harder to review and
makes it clear when the options are added.
I'll start another branch which will contain new feature only concerning
true enhancement.
Thanks!
-Brad
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/3 Brad King brad.k...@kitware.com:
On 1/3/2012 11:03 AM, Eric Noulard wrote:
stage/ImproveCPackDoc-part1
contains changes that do not add features but document existing ones.
This one looks good. Please merge to next.
It does not merge without conflict:
d2c9626 Document undocumented (but existing) cpack options (fix #0010134)
Auto-merging Source/CPack/cpack.cxx
CONFLICT (content): Merge conflict in Source/CPack/cpack.cxx
this is due to the fact I did already merge it
(the beginning of the old stage/ImproveCPackDoc)
to next before 2.8.7 in the hope that it would be included in 2.8.7:
http://public.kitware.com/Bug/view.php?id=10067#c27793
It was dropped because ImproveCPackDoc as a whole wasn't considered ready
which was off course true...
I have to teach myself to provide finer-grain branch merge :-(
The left over commit of mine in next are:
commit ab6c9c03bcdb89717345d68bdc979d74fd776d04
Author: Eric NOULARD eric.noul...@gmail.com
Date: Sun Nov 13 22:47:25 2011 +0100
Update cmake bash completion file.
commit 1e38d6dd306522a0d08355a6c7ef57293b46b5a6
Author: Eric NOULARD eric.noul...@gmail.com
Date: Sun Nov 13 22:44:53 2011 +0100
CPack begin the implementation of --help-command* and --help-variables*
Author: Eric NOULARD eric.noul...@gmail.com
Date: Sat Nov 5 14:41:23 2011 +0100
Document undocumented (but existing) cpack options (fix #0010134)
Tell me how you would like me to handle my mess :-(
stage/CMake-completion-improvement
contains the completion update.
This can be merged to next/master independently from other
because the changes won't be used unless the new options appears
So you purposely refer to options that don't yet exist so they will
complete when they do?
Yes like I said, this is harmless.
In fact I may even implement all normalized options
(--help-[command|variable|property|policy]
completion for cmake/ctest/cpack, if they are not supported they
won't be triggered.
Is that only this hunk:
Yes:
+ --help-variable)
+ local running=$(for x in `cpack --help-variable-list | grep -v
cpack version `; do echo ${x} ; done )
+ COMPREPLY=( $(compgen -W ${running} -- ${cur}) )
+ return 0
+ ;;
+ --help-command)
+ local running=$(for x in `cpack --help-command-list | grep -v
cpack version `; do echo ${x} ; done )
+ COMPREPLY=( $(compgen -W ${running} -- ${cur}) )
+ return 0
+ ;;
? I think that can that be left out and then included in the new
enhancement topic. It won't make the topic any harder to review and
makes it clear when the options are added.
I can do that as well, no problem.
I'll start another branch which will contain new feature only concerning
true enhancement.
Thanks!
No problem.
--
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org
--
Powered by www.kitware.com
Visit other Kitware open-source projects at
http://www.kitware.com/opensource/opensource.html
Please keep messages on-topic and check the CMake FAQ at:
http://www.cmake.org/Wiki/CMake_FAQ
Follow this link to subscribe/unsubscribe:
http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
On 1/3/2012 11:45 AM, Eric Noulard wrote: this is due to the fact I did already merge it (the beginning of the old stage/ImproveCPackDoc) to next before 2.8.7 in the hope that it would be included in 2.8.7: http://public.kitware.com/Bug/view.php?id=10067#c27793 It was dropped because ImproveCPackDoc as a whole wasn't considered ready which was off course true... [snip] Tell me how you would like me to handle my mess :-( Start a new topic ImproveCPackDoc-revert from the last commit on the original topic that was merged to 'next'. Then revert all the commits that had been merged so far in reverse order. Merge that to next. Then your rebased topics should merge cleanly. -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/3 Brad King brad.k...@kitware.com: On 1/3/2012 11:45 AM, Eric Noulard wrote: this is due to the fact I did already merge it (the beginning of the old stage/ImproveCPackDoc) to next before 2.8.7 in the hope that it would be included in 2.8.7: http://public.kitware.com/Bug/view.php?id=10067#c27793 It was dropped because ImproveCPackDoc as a whole wasn't considered ready which was off course true... [snip] Tell me how you would like me to handle my mess :-( Start a new topic ImproveCPackDoc-revert from the last commit on the original topic that was merged to 'next'. Then revert all the commits that had been merged so far in reverse order. Merge that to next. Then your rebased topics should merge cleanly. OK, done for Merge topic 'ImproveCPackDoc-part1' into next d2c9626 Document undocumented (but existing) cpack options (fix #0010134) Pushing upstream next To g...@cmake.org:cmake.git I did remove old ImproveCPackDoc from stage. I did remove old CMake-completion-improvement from stage as well and I'll push something clean without reference to potential cpack enhancement in a new topic. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] Improving CPack Documentation (and may be others as well)
2012/1/3 Eric Noulard eric.noul...@gmail.com: I did remove old ImproveCPackDoc from stage. I did remove old CMake-completion-improvement from stage as well and I'll push something clean without reference to potential cpack enhancement in a new topic. Done as well: Merge topic 'CMake-bash-completion-enhance' into next 4d253d1 Enhance bash completion file for cmake and ctest df22472 KWSys Nightly Date Stamp back to cleaner way of work. Thanks for your help. -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
