Commit Graph

22058 Commits

Author SHA1 Message Date
Brad King a8c652342f cmListFileLexer: Convert CRLF -> LF newlines explicitly
Read input files in binary mode instead of text mode and convert CRLF
newlines to LF newlines explicitly in our own buffer.  This is necessary
to read CMake source files with CRLF newlines on platforms whose C
runtime libraries do not transform newlines in text mode.  For example,
a Cygwin or Linux binary may not transform CRLF -> LF in files read from
a Windows filesystem.  Perform the conversion ourselves to ensure that
multi-line string literals in CMake source files have LF newlines
everywhere.
2013-10-17 09:07:00 -04:00
Brad King dbd933365e cmListFileLexer: Allow a leading UTF-8 Byte-Order-Mark (#11137)
Teach the lexer to read a UTF-8, UTF-16 BE/LE, or UTF-32 BE/LE
Byte-Order-Mark from the start of a file if any is present.  Report an
error on files using UTF-16 or UTF-32 and accept a UTF-8 or missing BOM.
2013-10-17 09:06:59 -04:00
Brad King 56457837e2 cmListFileLexer: Allow command names with one letter (#14181)
Teach the lexer to treat a single letter as an identifier instead of an
unquoted argument.  Outside of a command invocation, the parser treats
an identifier as a command name and an unquoted argument as an error.
Inside of a command invocation, the parser treats an identifier as an
unquoted argument.  Therefore this change to the lexer will make what
was previously an error case work with no other behavioral change.
2013-10-17 09:06:59 -04:00
Brad King 8f2b0c3307 Merge topic 'help-manual-cleanup'
9b212ad Make --help-* options available from all command-line tools
5dde65a Help: De-duplicate manual/(cmake|ccmake).1.rst build options
ae944d1 Help: Organize manual/*.1.rst sections
4f7d708 Help: Drop leftover conversion content from manual/*.1.rst
2013-10-17 08:57:45 -04:00
Brad King fa8fc51aec Merge topic 'wix-documentation-escapes'
42b4f6c CPackWiX: prevent attribute references in docs from being interpreted
2013-10-17 08:57:41 -04:00
Brad King bffe96056d Merge topic 'readable-lupdate.pro'
51305f5 Qt4: make pro files generated for translations easier to read
2013-10-17 08:57:28 -04:00
Brad King ad9c5c54f3 Merge topic 'print-CMP0022-content-conflict-test'
4fd6024 CMP0022: Add unit test for null pointer check and message.
2013-10-17 08:57:23 -04:00
Kitware Robot ca498f0192 CMake Nightly Date Stamp 2013-10-17 00:01:07 -04: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 5dde65ac5b Help: De-duplicate manual/(cmake|ccmake).1.rst build options
Move common build options out of cmake and ccmake manuals into an
OPTIONS_BUILD.txt file and include it from the original locations.
2013-10-16 16:24:51 -04:00
Brad King ae944d176e Help: Organize manual/*.1.rst sections
Add "Synopsis", "Description", and "See Also" manual page section
headers.  These are typical of .1 man section pages.  Also de-duplicate
the See Also section links using a separate LINKS.txt file included from
each manual.
2013-10-16 16:23:32 -04:00
Nils Gladitz 42b4f6cbcf CPackWiX: prevent attribute references in docs from being interpreted 2013-10-16 22:20:10 +02:00
Rolf Eike Beer 51305f52f0 Qt4: make pro files generated for translations easier to read
-use one line for each input file and include directory
-remove duplicate include directories
2013-10-16 20:08:33 +02:00
Brad King 4f7d708ac7 Help: Drop leftover conversion content from manual/*.1.rst
Some text in these manuals is left from the old full help transition
text generated by the automatic conversion process.  Drop it.
2013-10-16 12:50:41 -04:00
Stephen Kelly 4fd60241c8 CMP0022: Add unit test for null pointer check and message. 2013-10-16 10:45:55 -04:00
Brad King c54fb6fede Merge topic 'update-kwsys'
0408415 Merge branch 'upstream-kwsys' into update-kwsys
c01e744 KWSys 2013-10-15 (6eab64c3)
2013-10-16 10:45:40 -04:00
Brad King c49083e9a4 Merge topic 'doc-reStructuredText'
7038a93 Modules/readme.txt: Update steps to add module documentation
a77e308 CPack: Replace #<type> markup with reStructuredText equivalent
e7ca48f Help: Factor out cmake-generator-expressions manual page
97e8650 Help: Factor out COMPILE_DEFINITIONS disclaimer duplication
8982161 Help: Factor out find_* command duplication
30b2186 Help: Factor out *_OUTPUT_(NAME|DIRECTORY).rst duplication
bfe07aa Build Help documentation during CMake build using Sphinx
53ded59 Drop unused builtin documentation APIs
0c39a75 Drop the 'Full' field from cmDocumentationEntry
e33d8d2 Drop builtin command documentation
399e9c4 Drop builtin property documentation
6035c04 get_property: Drop test for builtin property documentation
80a3273 Drop all documentation formatters except Usage
b336a1eb Teach COMPATIBLE_INTERFACE_* checks to use Help .rst documents
ec6df36 Teach --help-* options to load documentation from .rst files
25f2877 Add class cmRST to do basic reStructuredText processing
...
2013-10-16 09:28:12 -04:00
Brad King 7038a93a7e Modules/readme.txt: Update steps to add module documentation
Replace the old module documentation instructions with steps to add
reStructuredText documentation that will be built by Sphinx.
2013-10-16 09:22:39 -04:00
Kitware Robot a77e308693 CPack: Replace #<type> markup with reStructuredText equivalent
Drop #end and #module.  Convert #section to a subsection header.
Convert #variable to the cmake domain "variable" directive.
Convert #macro to the cmake domain "command" directive.
Perform minor formatting fixes in text near these changes.
2013-10-16 09:22:39 -04:00
Brad King e7ca48f226 Help: Factor out cmake-generator-expressions manual page
Generator expressions are supported in many places and are a distinct
concept worthy of their own manual page.  The old builtin documentation
was previously represented by preprocessor macros to generate it into
each place that supports them.  Factor out the duplicate content into a
dedicated cmake-generator-expressions manual page and reference it from
each original location.
2013-10-16 09:22:38 -04:00
Brad King 97e8650d7b Help: Factor out COMPILE_DEFINITIONS disclaimer duplication
The COMPILE_DEFINITIONS escaping disclaimer was represented in builtin
documentation using a preprocessor macro.  Factor the duplicate content
out into a separate .txt file and include it in each document with the
reStructuredText include directive.
2013-10-16 09:22:38 -04:00
Brad King 898216137a Help: Factor out find_* command duplication
These documents were represented in the builtin documentation using a
common starting point with placeholders substituted by each command.
Convert them back to this approach using the reStructuredText include
directive and substitutions to avoid duplication.
2013-10-16 09:22:38 -04:00
Brad King 30b21860ad Help: Factor out *_OUTPUT_(NAME|DIRECTORY).rst duplication
Portions of these documents contain duplicate content generated from
preprocessor macros in the original builtin documentation source.
Factor the common parts out into .txt files using reStructuredText
include directives and substitutions to avoid duplication.
2013-10-16 09:22:38 -04:00
Brad King bfe07aa97e Build Help documentation during CMake build using Sphinx
Add a Utilities/Sphinx directory to hold CMake build code to run the
Sphinx (sphinx-doc.org) documentation generation tool.  Create a
CMakeLists.txt file there capable of building either as a subdirectory
of the main CMake build, or as a standalone documentation build.

Add cache options SPHINX_MAN and SPHINX_HTML to select output formats
and SPHINX_EXECUTABLE to specify the sphinx-build executable.  Add
bootstrap options --sphix-man and --sphinx-html to select output formats
and --sphinx-build=<sb> to specify the sphinx-build executable.

Create a "conf.py.in" file to configure_file into "conf.py" to tell
sphinx-build how to build our documents.  Create a "cmake.py" Sphinx
extension module defining:

* The "cmake-module" directive used in Help/module/*.rst files to
  scan .rst markup from the corresponding Modules/*.cmake file.

* A Sphinx domain called "cmake" defining documentation object types
  for CMake Help/<type> directories: command, generator, manual,
  module, policy, prop_*, and variable.  Add a "role" for each type
  to perform cross-references.  Teach the roles to treat "<XYZ>"
  as placeholders instead of explicit targets if not preceded by
  a space.  Add cmake domain directives to define command and
  variable objects explicitly in .rst file content.  This will
  allow modules to define their own commands and variables and
  have them indexed and linkable.

* A Sphinx document transform that converts Help/<type>/*.rst documents
  into cmake domain objects of the corresponding <type> and adds index
  entries for them.  This will automatically index all CMake documentation
  objects and provide cross-reference targets for them with no special
  markup in the .rst files.
2013-10-16 09:22:37 -04:00
Brad King 53ded59515 Drop unused builtin documentation APIs
Now that all DefineProperty documentation calls have been dropped, drop
the supporting APIs.
2013-10-16 09:22:37 -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 e33d8d2d77 Drop builtin command documentation
Drop all GetTerseDocumentation and GetFullDocumentation methods from
commands.  The command documentation is now in Help/command/*.rst files.
2013-10-16 09:22:36 -04:00
Brad King 399e9c46d8 Drop builtin property documentation
Drop all DefineProperty calls for non-chained properties.  Drop the
documentation from the chained ones.  The documentation for all
properties is now in Help/prop_*/*.rst files.
2013-10-16 09:22:36 -04:00
Brad King 6035c0458e get_property: Drop test for builtin property documentation
Property documentation is no longer builtin, so the get_property command
will be unable to return the documentation.  Drop the test for it.
2013-10-16 09:22:36 -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 b336a1ebe4 Teach COMPATIBLE_INTERFACE_* checks to use Help .rst documents
These checks want to know if named target properties are builtin, which
is now known by checking the Help/prop_tgt directory.  (Previously the
check could be confused by a define_property call in the project.)
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 25f2877eef Add class cmRST to do basic reStructuredText processing
Create a cmRST class to perform just enough reStructuredText processing
to support display of Help documents in human-readable text format.
This will be used to implement --help-* command-line options.

Support directives "include", "replace", "parsed-literal", "toctree"
(Sphinx), and "cmake-module" (CMake Sphinx Extension to scan .cmake
modules).  Support inline CMake Sphinx Domain roles to convert
cross-references to corresponding title text.  Support inline
substitutions defined by the "replace" directive, but keep it simple by
requiring replacements to be defined before use.

Add a CMakeLib "testRST" case to cover processing of supported
constructs and compare results against expected output.
2013-10-16 09:22:35 -04:00
Kitware Robot 5029da5eac CMake Nightly Date Stamp 2013-10-16 00:01:08 -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 441f2808ec Help: Fix reStructuredText syntax in auto-generated documents 2013-10-15 14:12:49 -04:00
Brad King 6ceb651155 Help: Add index.rst top-level document
Add a top-level document holding the Sphinx root toctree.  List all
reference manuals from Help/manual/*.rst and the Sphinx-generated
general index (genindex) and search pages.
2013-10-15 14:12:49 -04:00
Brad King c717e2aa8b ExternalProject: Restore documentation indentation level
This module parses its own documentation to extract supported options.
Fix the indentation level to match that expected by the parser.
2013-10-15 14:12:48 -04:00
Kitware Robot f051814ed0 Convert builtin help to reStructuredText source files
Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.
2013-10-15 14:12:03 -04:00
Brad King e94958e99c Add bash script to convert builtin help to reStructuredText
Create a convert-help.bash script to extract builtin documentation as
reStructuredText sources in a new Help directory.  Run each executable
with the --help-full option targeting a .rst file to extract the
documentation.  Generate Sphinx "toctree" directives to point each man
page at the corresponding documents it should contain.  Organize
cmake-commands(7), cmake-properties(7), and cmake-variables(7) man pages
into sections similar to those generated by --help-properties and
--help-variables output previously.
2013-10-15 14:12:02 -04:00
Kitware Robot 81759c77af Add Help/generator/*.rst for Windows- and OS X-only generators
Run "cmake --help-full cmake.1.rst" by hand on Windows and OS X.
Copy the generator/*.rst documents for generators unique to those
platforms into Help/generator.
2013-10-15 11:17:08 -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
Brad King 946f0efb7c Drop definition of internal property
The property __CMAKE_DELETE_CACHE_CHANGE_VARS_ is not meant for public
exposure.
2013-10-15 10:47:39 -04:00
Brad King 277bd1db98 Drop CMAKE_STRICT mode
With our modern development workflow it is less likely a property will
be added to C++ code without documentation.  This mode only existed to
support the DocTest which had very limited coverage of the properties
anyway.
2013-10-15 10:47:38 -04:00
Brad King 678aaad133 Drop documentation generation during build
Drop the 'documentation' build target.  We will no longer use the
executables to generate their own documentation.  New infrastructure
will be introduced later to generate documentation.
2013-10-15 10:47:37 -04:00
Brad King 09be0bb049 Set IDE folder for CMake 'documentation' target only if it exists
The documentation target will be come optional, so do not reference it
when it does not exist.
2013-10-15 10:46:55 -04:00
Brad King e49efe9150 Drop xmllint documentation tests
Drop these tests since we will drop docbook output along with other
documentation formatters.
2013-10-15 10:46:54 -04:00
Brad King 189008ea5c Move cmake.m4 from Utilities to Auxiliary
The latter fits more consistently with other third party integration
files.
2013-10-15 10:46:54 -04:00
Brad King b601e2350a Rename Docs to Auxiliary
The directory contains auxiliary support files for integration with
other tools, not documentation.
2013-10-15 10:46:54 -04:00