|
Notes |
|
|
(0038805)
|
|
Brad King
|
|
2015-05-27 08:29
|
|
|
Yes. When we first converted to reStructuredText it was done via an automated conversion from the older internal format. We've been incrementally converting documents prior to making other modifications to them. |
|
|
|
(0038817)
|
|
Michael Scott
|
|
2015-05-28 17:14
|
|
|
I've started having a look at the developer information on documentation. Is there a particular part of the documentation that could do with improving or is it the files all round that could with the kind of improvements given above? |
|
|
|
(0038819)
|
|
Brad King
|
|
2015-05-29 09:41
|
|
|
|
|
(0038881)
|
|
Michael Scott
|
|
2015-06-03 18:19
|
|
Hi Brad,
I've just uploaded a patch file containing changes to the Help/command rst files, to add in some more rst markup. Do they look okay?
There are a couple of things to mention with the proposed changes:
- create_test_sourcelist generates sphinx warnings because I added some variable cross references, but these apparently don't exist, I left them in as I figured it's probably better to know they're incorrect than not
- I tried to cross reference all the properties in get_cmake_property, but some of them don't seem to exist, so I left them as they were
- I was a bit unsure about the correct usage of " and `` at times, as there were cases of both being used, so there might be a few cases where I've used `` incorrectly, but generally when I was unsure about this I left it as is
Cheers,
Michael |
|
|
|
(0038883)
|
|
Brad King
|
|
2015-06-04 08:56
|
|
Re 0015587:0038881: Thanks! Please commit locally and use "git format-patch" to produce the patch file. Then send it to the developer mailing list for review as mentioned in CONTRIBUTING.rst. Most review should take place there.
In response to your bullets:
* We don't want any sphinx warnings to be left. The missing variables should either be added or just referenced by ``inline-literal`` syntax instead. When in doubt, check the source code to see if a variable is really defined or not.
* For the create_test_sourcelist variables you can define them locally with ".. variable:" directives right in that documentation. References to them within the same document can just be done with ``varname`` though as mentioned in the style guide I linked.
* The tiny subset of properties listed in get_cmake_property is left from before we had a dedicated cmake-properties manual. Instead of listing them here you could just say "see the :manual:`cmake-properties(7)` manual for available properties". You could dig into the source code to see if the non-documented properties actually exist. If so, please add documents for them.
* The ``inline-literal`` syntax should be used when referring to a defined technical/code construct. The "double-quotes" syntax can be used as it might be in prose normally. Many instances of "double-quotes" are likely left from before we used rst markup and may need to be converted to ``inline-literal`` syntax. |
|
|
|
(0038885)
|
|
Michael Scott
|
|
2015-06-04 18:05
|
|
Just so I don't submit the patch in the wrong way, do I simply email the contents of the patch file format-patch produces to the developer mailing list, or should it be an attachment with some general information on the batch in the message body? Does the email subject need to be in a specific format, e.g. contain the issue ID, or is it fine to just use the subject format-patch produces?
Sorry for all the questions, I haven't used git/patches particularly before now. |
|
|
|
(0038894)
|
|
Brad King
|
|
2015-06-08 10:36
|
|
Re 0015587:0038885: The simplest approach is to take the file produced by "git format-patch" and send it as an attachment. We have no requirements on the subject line or body of the outer message.
More advanced users can use "git send-email" to send the patch inline but that takes some experience to understand and is not necessary. |
|
|
|
(0042783)
|
|
Kitware Robot
|
|
2016-06-10 14:29
|
|
Resolving issue as `moved`.
This issue tracker is no longer used. Further discussion of this issue may take place in the current CMake Issues page linked in the banner at the top of this page. |
|
help_command.patch (76,148) 2015-06-03 18:10