[cmake-developers] Improving CPack Documentation (and may be others as well)

[Brad King]

On 1/22/2012 7:58 AM, Eric Noulard wrote:
> 2012/1/3 Eric Noulard<eric.noulard at 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