Commit Graph

109 Commits

Author SHA1 Message Date
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
Brad King 07b80021aa cmDocumentation: Drop version output from usage and text help
Drop the "cmake version ..." line from the top of usage and text help
formats.  Print it only when requested with --version or similar option.
2013-10-15 10:46:54 -04:00
Brad King 6e68bc2273 cmake: Add --help-policy-list option
All the other --help-<item> options have a corresponding option
--help-<item>-list.  Add one for --help-policy.
2013-10-15 10:46:54 -04:00
Brad King 2e7ba290a5 Merge topic 'minor_cleanup'
6931999 VS6: Add some delimiting between error message and content.
d1a5f12 cmTarget: Fix typo in comment.
961c0ba Fix comments to match the code.
7cca50c Remove unused include.
2013-10-07 15:43:23 -04:00
Stephen Kelly 961c0bae89 Fix comments to match the code. 2013-09-11 15:05:05 +02:00
Rolf Eike Beer 2a7fecc409 remove unused local typedef
Fixes this warning from g++ 4.8:

CMake/Source/cmDocumentation.cxx:835:23: warning: typedef 'sdoc_t' locally defined but not used [-Wunused-local-typedefs]
         SDOC_UNKNOWN} sdoc_t;
                       ^
2013-08-14 20:28:28 +02:00
Andreas Mohr ddac8d3d2d Fix spelling and typos (affecting binary data / module messages) 2013-05-07 08:39:19 -04:00
Brad King a4ae88bdb2 Update programmatically-reported copyright year (#13638)
Update the copyright year reported by 'bootstrap' and in the generated
documentation to report 2012.
2012-11-05 08:44:03 -05:00
Daniel Pfeifer 9ad85dbb25 docbook: Remove redundant docs that cause invalid DocBook
If a subsection with a title is added, all subsequent subsections need a
title too.  The "helpful links" just repeat preceding subsections
anyway.
2012-09-08 07:42:10 -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
Eric NOULARD 9a8103e929 Try to fix compile error on Win32-vs70 2012-02-19 00:01:39 +01:00
Eric NOULARD 9717727d5f Suppress unecessary (now empty) doc sections 2012-02-18 22:30:57 +01: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 9002f73f31 Fix non existent std::string::clear on VS6 2012-02-14 16:05:24 -05: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 543f1adfa4 Make the load of script documentation more efficient and dynamic.
CPack help will be searched in any CPack*.cmake file located
near to CPack.cmake file. The script files is parsed iff
the first line begin with ##section. Moreover the documentation
section name is specified on the remaining part of the line
minus the space immediately following ##section.
2012-02-14 16:05:23 -05:00
Eric NOULARD 7c82b7f51a Fix potential bad memory access, thanks to Eike 2012-01-31 22:44:58 +01:00
Eric NOULARD 62b589b4cd Suppress unused var, beautify code, avoid 1 extra newline.
There remains extra newlines in text Formatter output
but the parser does not seem to be the culprit.
The formatter should be.
2012-01-24 23:38:22 +01: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
Nicolas Despres 9ae0604a62 Usage: Document all options printing the version number. 2011-10-23 22:18:14 +02:00
Nicolas Despres 3353d84c14 Usage: Document all options printing usage information. 2011-10-23 22:18:14 +02:00
Nicolas Despres d3d7e45df2 Remove trailing white-spaces. 2011-10-23 22:15:20 +02:00
Alex Neundorf d62c51ddc2 -fix documentation from a module which has *only* documentation
This is #10466. It didn't crash for me, but also didn't work.
The issue was that a line ending with something else than a # was considered as the
end of the documentation block. If there was simply the end of the file we didn't
get into the correct branch.

Alex
2010-05-08 10:10:19 +02:00
Bill Hoffman 2c6f8de2cc Fix for bug #0010466, fix crash in --help-module. 2010-03-26 16:57:01 -04: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 32258b44bc ENH: Document CACHE entry properties
This adds a property documentation section for CACHE properties.
We document the ADVANCED, HELPSTRING, TYPE, and VALUE properties.
2009-03-10 11:11:15 -04:00
Brad King 46e3956349 COMP: Fix assignment inside condition 2008-10-11 15:35:30 -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
Brad King 657627c231 BUG: Fix help type for filenames with many dots
The help page type should be determined using only the extension after
the last dot.  See issue #7797.
2008-10-10 11:23:17 -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
Alexander Neundorf 4175b514fc ENH: handle HTML documentation for single items better: no warning about
ComputeSectionLinkPrefix, don't create an index for only one item

Alex
2008-07-21 17:52:59 -04:00
Bill Hoffman 7173f2db0e ENH: add master index into html full help 2008-03-05 11:05:22 -05: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
Alexander Neundorf 95ba817b2e BUG: actually print the docs for custom modules if this was requested
Alex
2008-02-17 14:04:01 -05:00
Alexander Neundorf f8f232bdd8 BUG: make -help-module-list work by filling the modules section first, also
for custom modules

Alex
2008-01-14 17:05:09 -05:00
Amitha Perera 4d9259c15b STYLE: Spelling fixes on documentation 2008-01-09 22:09:19 -05:00
Alexander Neundorf acb27977f0 ENH: sort the module files alphabetically when generating the documentation
of rht modules

Alex
2008-01-09 16:59:01 -05:00
Alexander Neundorf f3ea6a351a BUG: create modules documentation not only for the first documentation creation step
in cmake (the set ModulesFound wasn't cleared at the beginning of each
PrintDocumentation() function, so when documentation for modules was executed the second
time, ModulesFound already contained all modules and so no module was
documented)

Alex
2007-12-29 11:53:36 -05:00
Ken Martin ad581280a5 BUG: fix single module generation 2007-11-29 10:23:26 -05:00
Ken Martin c2f0aac146 ENH: some more cleanup, fixes, and patch for HTML output 2007-10-24 11:36:47 -04:00