Commit Graph

57 Commits

Author SHA1 Message Date
Brad King b17729460b cmake: Implement placeholder --help-custom-modules compatibility
The implementation of the "cmake --help-custom-modules" was removed
along with the rest of the old help generation infrastructure when
documentation was converted to reStructuredText.  In order to avoid
breaking existing project builds outright when they use a custom command
that runs a command like "cmake --help-custom-modules foo.1", generate
the requested file with placeholder content explaining that the option
is not supported anymore.
2014-01-08 11:16:48 -05:00
Brad King e7434d43ab cmDocumentation: Fix exit after help output format warnings
After warning that a help output format is no longer supported, fix the
return value from cmDocumentation::CheckOptions to indicate that it was
still a help option that was parsed.  Otherwise CMake moves on to treat
the help output file name as a source tree and complains that it does
not exist.
2013-11-19 10:58:16 -05:00
Brad King d1526f825e Refactor internal resource location APIs and initialization
Rename cmSystemTools::FindExecutableDirectory to FindCMakeResources.
Teach it to compute the locations of cmake, ctest, cpack, ccmake, and
cmake-gui executables, and the location of CMAKE_ROOT.  Provide this
information from static cmSystemTools::Get<resource>() methods.
Refactor code that needs these locations to use the new APIs.

Teach FindCMakeResources to use the OS X system API to lookup the
executable location.  When running from the CMake build tree itself,
leave a file in the tree that FindCMakeResources can use to read the
location of the source tree.  This avoids the need to compile the source
tree location into a binary that may be installed and used without the
source tree.

Teach the QtDialog on OS X to create a "cmake-gui" symlink in the build
tree next to "cmake" and the other tools, as is already done in the
install tree for the application bundle.  This ensures a consistent set
of executables are available in one directory.
2013-11-12 08:23:35 -05:00
Brad King 9b212ad01a Make --help-* options available from all command-line tools
Make the standard --help-* options available from all command-line
tools.  Drop options that are no longer supported:

  --copyright, --help-full, --help-html, --help-man,
  --help-compatcommands, --help-custom-modules

De-duplicate Help/manual/*.1.rst help options by using an
OPTIONS_HELP.txt file included from each manual.
2013-10-16 16:24:51 -04:00
Brad King 0c39a757da Drop the 'Full' field from cmDocumentationEntry
We need only 'Brief' for usage documentation.  We no longer have builtin
'Full' documentation, which is now in Help/*/*.rst files.
2013-10-16 09:22:37 -04:00
Brad King 80a3273b5e Drop all documentation formatters except Usage
We now need only the Usage formatter to support command-line options
that print basic usage, and the supporting indented=>preformatted markup
processor to support CMake message formatting.  Drop all other
documentation formatters and move the remaining code up into the top
cmDocumentationFormatter class.
2013-10-16 09:22:35 -04:00
Brad King ec6df3675e Teach --help-* options to load documentation from .rst files
Install the Help directory next to Modules to make it available in CMake
distributions.  Use cmRST to read Help .rst documents and print them as
help output.

Add options

 --help-manual-list
 --help-manual

to list available manuals or print one of them.  Implement the options

 --help-commands
 --help-modules
 --help-policies
 --help-properties
 --help-variables

by mapping to the corresponding manual page.  Implement the options

 --help-command-list
 --help-module-list
 --help-policy-list
 --help-property-list
 --help-variable-list

by globbing the available Help .rst documents of the corresponding type
and reading their titles.  Implement the options

 --help-command
 --help-module
 --help-policy
 --help-property
 --help-variable

by globbing the matching Help .rst document(s) and printing them.
2013-10-16 09:22:35 -04:00
Brad King 87cc62cab9 Drop "full" documentation output types
We will no longer support full documentation generation from executables
and will instead generate documentation with other tools.  Disable (with
a warning left behind) the command-line options:

 --copyright
 --help-compatcommands
 --help-full
 --help-html
 --help-man

Drop supporting code.  Drop manual sections generation from executables.
Remove internal documentation construction APIs.  Drop unused sections
See Also, Author, Copyright, Compat Commands, Custom Modules.
2013-10-15 14:12:49 -04:00
Brad King f85405f551 Add reStructuredText (RST) documentation formatter
Temporarily add a RST formatter to convert builtin documentation to .rst
source files.  This will be removed shortly after we use it to convert
documentation.

Teach the RST formatter to:

* Output preformatted blocks as reStructuredText "::" literal blocks.

* Output option lists as bullet lists with option names enclosed in
  reStructuredText ``literal`` quoting.

* Output individual documentation objects (commands, variables, etc.)
  in separate .rst files organized in directories by type.

Replace references to cmVersion::GetCMakeVersion() in builtin
documentation with the literal placeholder "|release|" that will be
defined as a substitution later.
2013-10-15 10:47:39 -04:00
Brad King 0d0fec1524 Drop CPack module documentation markup extraction
This will be replaced by alternative markup later.
2013-10-15 10:47:39 -04:00
Sean McBride cb4ec606a9 cmDocumentation: Fix a few doxygen comment errors
Warned by clang -Wdocumentation
2013-10-08 09:16:32 -04:00
Alex Neundorf 20e133e38a man documentation: detect man section from the given filename
E.g. if you say cmake --help-custom-modules mymodules.7
cmake will now put section 7 into the generated manpage.

Alex
2012-06-21 23:19:55 +02:00
Alex Neundorf 38df155dd3 documentation: preparation for making the man section configurable
This patch adds a man section number, which is then used by the
DocumentationFormatterMan. The section number is right now always 1,
detecting this from the file name will be the next step.

Alex
2012-06-21 23:06:08 +02:00
Alex Neundorf e6a935f39b -remove trailing whitespace
Alex
2012-06-21 23:02:55 +02:00
Eric NOULARD a6bce55aef Dynamically add documentation section specified in documented script.
Modify CPackDeb and CPackRPM as an example
2012-02-18 22:07:39 +01:00
Eric NOULARD 02ccb3291b Create getDocumentedModulesListInDir which may be used in other context.
This should makes it easier to use the same "documented module"
techniques for CTest, CMake or user module.
2012-02-14 16:05:23 -05:00
Eric NOULARD cdbd1a9e39 Fix another compiler warning due to a typo 2012-02-14 16:05:23 -05:00
Eric NOULARD 1629615a10 CPack Documentation extraction from CMake script begins to work
- Enhance extract doc parser. Seems robust now. The legacy
   module documentation parser works as before ignoring
   the new markup.

 - Proof of concept for CPack (generic), CPack RPM and CPack Deb
   generator for macro and variables.
   Try cpack --help-command and cpack --help-variables
2012-01-22 13:31:24 +01:00
Eric NOULARD 83e34dd9e6 Implement simple CMake script comment markup language.
The language is very simple. It use ##<keyword> special comment
which opens a structured documentation block and ##end closes it.
This may be used to extract documentation for macro as 'command'
and 'variables' such that cpack --help-command and --help-variable
does parse builtin modules files (CPack.cmake, CPackComponent.cmake,
...) in order to extract the corresponding doc.
2012-01-22 11:44:05 +01:00
Eric NOULARD c6a0169442 CPack begin the implementation of --help-command* and --help-variables*
This modifications set tries to keep the unified doc for cmake/ctest/cpack
while introducing tool specific documentation separated.
Some documentation sections for CMake do not fit well to CPack.
2012-01-22 11:42:49 +01:00
Zach Mullen 0ae0780055 BUG 9961: ctest --help should not display a Generators section 2009-11-24 11:46:06 -05:00
Brad King 96afb12087 Convert CMake to OSI-approved BSD License
This converts the CMake license to a pure 3-clause OSI-approved BSD
License.  We drop the previous license clause requiring modified
versions to be plainly marked.  We also update the CMake copyright to
cover the full development time range.
2009-09-28 11:43:28 -04:00
Brad King 5a82a0b108 ENH: Improve generated documentation formatting
Applying patch provided in issue #7797.

Fixes to man-pages:
  - Character '-' must be espaced as '\-'
  - Surround preformatted text with '.nf' and '.fi' to adjust filling
  - Give every page a NAME section for indexing by mandb
  - Pass the man page filename without extension to .TH in its header

Also added a title to the HTML header.
2008-10-10 11:23:35 -04:00
Bill Hoffman d632b96841 BUG: fix 6647 arguments after -E should not be parsed by CMake 2008-08-19 15:42:48 -04:00
Ken Martin d47a5951ed ENH: add --help-policies and --help-policy command line options 2008-03-04 09:16:33 -05:00
Alexander Neundorf 969ea3f449 ENH: add support for creating the documentation in docbook format
(http://www.oasis-open.org/docbook/xml/4.2/), which users can then convert
to other formats.
Tested with meinproc from KDE, which generates HTML pages which look good.

Alex
2008-02-19 14:33:43 -05:00
Ken Martin c2f0aac146 ENH: some more cleanup, fixes, and patch for HTML output 2007-10-24 11:36:47 -04:00
Ken Martin 44cce51a1a COMP: fix some warnings and add some doc strings back in 2007-10-22 15:33:19 -04:00
Ken Martin 6cdf032505 ENH: change to make the documentation class more generic, about halfway there, also provides secitons for Variables now 2007-10-22 12:49:09 -04:00
Alexander Neundorf 31881265c7 ENH: add new help option --help-custom-modules, which generates
documentation for all modules found in CMAKE_MODULE_PATH, which currently
has to be specified via -D, this can later on be improved e.g. by reading a
special (to-be-created) file like CMakeFiles/ModulePath.cmake in the build
tree so that running cmake help in the build tree of a project will always
give you the current module path. (This could actually also help IDEs which
would like to support cmake for projects...)

Alex
2007-09-19 13:14:25 -04:00
Alexander Neundorf c5f249bdbd STYLE: move the code for the different formats of the generated help into
their own classes, making cmDocumentation smaller and also making it easier
to eventually add another format

Alex
2007-09-19 09:05:28 -04:00
Alexander Neundorf 9f16292b6a STYLE: sort the property documentation into
global/directory/target/test/sourcefile and variable sections

Alex
2007-07-11 15:53:58 -04:00
Alexander Neundorf ad2fe23f6f COMP: fix compile on HP-UX with aCC, reusing the same identifier for a
variable as for the enum type doesn't work here

Alex
2007-07-03 08:26:32 -04:00
Alexander Neundorf 611f86b7f6 COMP: fix build with msvc 6, the enums are now part of a class which is
already completely parsed

Alex
2007-07-02 11:24:44 -04:00
Alexander Neundorf 151d55557e ENH: generate separate documentation for the commands, compatiblity
commands, modules and properties as html, text and man pages.
The names of the man pages are cmcommands, cmcompat, cmprops and cmmodules,
so they are easy to type.

Alex
2007-06-28 15:04:28 -04:00
Alexander Neundorf c95dc91237 ENH:
-in the full documentation there is now an extra section for
compatibility commands, so users see which commands they shouldn't use
-cmake -h <command> now also works with lower case commands
--help-fullm --help-command, --help-module and --help-property now determine
the output format from the extension of the given filename

Let me know if there are some things I overlooked.

Alex
2007-06-28 11:00:57 -04:00
Alexander Neundorf 1d9889c5d3 ENH: put compatibility commands in extra section and prepare for creating
separate man pages for properties, modules, commands and compatibility
commands

Alex
2007-06-22 08:44:51 -04:00
Brad King 1feb4a09b0 COMP: Fix void return failure. 2007-02-02 14:13:51 -05:00
Brad King f8b898fa6d STYLE: Fixed line length and this-> convention violations from yesterday's patch. 2007-02-02 09:11:41 -05:00
Brad King 58bf0dbac1 ENH: Patch from Alex to improve implementation and prepare for splitting the man page into more sections. 2007-02-01 10:38:42 -05:00
Brad King 1e566707da COMP: Patch from Alex for const correctness. 2007-01-22 10:52:24 -05:00
Ken Martin 27379d7b08 ENH: make properties a bit more formal with documentation and chaining 2006-12-07 09:45:32 -05:00
Bill Hoffman 96a46bdb44 ENH: search for help modules in the correct place for install and source tree builds 2006-04-13 23:15:48 -04:00
Bill Hoffman b7fa820118 ENH: add documentation support for modules 2005-12-14 13:51:08 -05:00
Brad King 0c92cfb8c4 ENH: Renamed --help-list-commands to --help-command-list and split --help [command] into separate --help and --help-command cmd options. 2004-04-14 14:25:43 -04:00
Brad King 8020279dd6 ENH: Added --help-list-commands option. 2004-04-14 13:40:24 -04:00
Brad King b78888fe38 ENH: Added configuration of name of executable in man page header and version banner. 2003-08-06 14:49:52 -04:00
Brad King c4794319c7 ENH: Added support to --help to print help for a single command. 2003-08-05 18:10:45 -04:00
Brad King fde552ea6e ENH: CheckOptions now takes const argv. 2003-07-23 17:27:34 -04:00
Brad King 7c2b4e3a02 ENH: Added SEE ALSO section to generated man page. Minor formatting improvements for generated text-only documentation. 2003-07-10 23:15:45 -04:00