Commit 87cc62ca authored by Brad King's avatar Brad King
Browse files

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.
parent 441f2808
...@@ -499,7 +499,6 @@ set(CPACK_SRCS ...@@ -499,7 +499,6 @@ set(CPACK_SRCS
CPack/cmCPackTarCompressGenerator.cxx CPack/cmCPackTarCompressGenerator.cxx
CPack/cmCPackZIPGenerator.cxx CPack/cmCPackZIPGenerator.cxx
CPack/cmCPackDocumentVariables.cxx CPack/cmCPackDocumentVariables.cxx
CPack/cmCPackDocumentMacros.cxx
) )
if(CYGWIN) if(CYGWIN)
......
#include "cmCPackDocumentMacros.h"
void cmCPackDocumentMacros::GetMacrosDocumentation(
std::vector<cmDocumentationEntry>& )
{
// Commented-out example of use
//
// cmDocumentationEntry e("cpack_<macro>",
// "Brief Description"
// "which may be on several lines.",
// "Long description in pre-formatted format"
// " blah\n"
// " blah\n"
//);
//v.push_back(e);
}
/*============================================================================
CMake - Cross Platform Makefile Generator
Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
Distributed under the OSI-approved BSD License (the "License");
see accompanying file Copyright.txt for details.
This software is distributed WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the License for more information.
============================================================================*/
#ifndef cmCPackDocumentMacros_h
#define cmCPackDocumentMacros_h
#include "cmStandardIncludes.h"
class cmCPackDocumentMacros
{
public:
static void GetMacrosDocumentation(std::vector<cmDocumentationEntry>& v);
};
#endif
...@@ -15,7 +15,6 @@ ...@@ -15,7 +15,6 @@
#include "cmake.h" #include "cmake.h"
#include "cmDocumentation.h" #include "cmDocumentation.h"
#include "cmCPackDocumentVariables.h" #include "cmCPackDocumentVariables.h"
#include "cmCPackDocumentMacros.h"
#include "cmCPackGeneratorFactory.h" #include "cmCPackGeneratorFactory.h"
#include "cmCPackGenerator.h" #include "cmCPackGenerator.h"
#include "cmake.h" #include "cmake.h"
...@@ -45,18 +44,6 @@ static const char * cmDocumentationUsage[][3] = ...@@ -45,18 +44,6 @@ static const char * cmDocumentationUsage[][3] =
{0,0,0} {0,0,0}
}; };
//----------------------------------------------------------------------------
static const char * cmDocumentationDescription[][3] =
{
{0,
"The \"cpack\" executable is the CMake packaging program. "
"CMake-generated build trees created for projects that use "
"the INSTALL_* commands have packaging support. "
"This program will generate the package.", 0},
CMAKE_STANDARD_INTRODUCTION,
{0,0,0}
};
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
static const char * cmDocumentationOptions[][3] = static const char * cmDocumentationOptions[][3] =
{ {
...@@ -129,14 +116,6 @@ static const char * cmDocumentationOptions[][3] = ...@@ -129,14 +116,6 @@ static const char * cmDocumentationOptions[][3] =
{0,0,0} {0,0,0}
}; };
//----------------------------------------------------------------------------
static const char * cmDocumentationSeeAlso[][3] =
{
{0, "cmake", 0},
{0, "ccmake", 0},
{0, 0, 0}
};
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
int cpackUnknownArgument(const char*, void*) int cpackUnknownArgument(const char*, void*)
{ {
...@@ -533,22 +512,8 @@ int main (int argc, char *argv[]) ...@@ -533,22 +512,8 @@ int main (int argc, char *argv[])
doc.SetName("cpack"); doc.SetName("cpack");
doc.SetSection("Name",cmDocumentationName); doc.SetSection("Name",cmDocumentationName);
doc.SetSection("Usage",cmDocumentationUsage); doc.SetSection("Usage",cmDocumentationUsage);
doc.SetSection("Description",cmDocumentationDescription);
doc.PrependSection("Options",cmDocumentationOptions); doc.PrependSection("Options",cmDocumentationOptions);
// statically (in C++ code) defined variables
cmCPackDocumentVariables::DefineVariables(&cminst);
std::vector<cmDocumentationEntry> commands;
std::map<std::string,cmDocumentationSection *> propDocs;
cminst.GetPropertiesDocumentation(propDocs);
doc.SetSections(propDocs);
cminst.GetCommandDocumentation(commands,true,false);
// statically (in C++ code) defined macros/commands
cmCPackDocumentMacros::GetMacrosDocumentation(commands);
doc.SetSection("Commands",commands);
std::vector<cmDocumentationEntry> v; std::vector<cmDocumentationEntry> v;
cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt; cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt;
for( generatorIt = generators.GetGeneratorsList().begin(); for( generatorIt = generators.GetGeneratorsList().begin();
...@@ -563,7 +528,6 @@ int main (int argc, char *argv[]) ...@@ -563,7 +528,6 @@ int main (int argc, char *argv[])
} }
doc.SetSection("Generators",v); doc.SetSection("Generators",v);
doc.SetSeeAlsoList(cmDocumentationSeeAlso);
#undef cout #undef cout
return doc.PrintRequestedDocumentation(std::cout)? 0:1; return doc.PrintRequestedDocumentation(std::cout)? 0:1;
#define cout no_cout_use_cmCPack_Log #define cout no_cout_use_cmCPack_Log
......
...@@ -361,12 +361,6 @@ void cmCTestScriptHandler::CreateCMake() ...@@ -361,12 +361,6 @@ void cmCTestScriptHandler::CreateCMake()
this->AddCTestCommand(new cmCTestUploadCommand); this->AddCTestCommand(new cmCTestUploadCommand);
} }
void cmCTestScriptHandler::GetCommandDocumentation(
std::vector<cmDocumentationEntry>& v) const
{
this->CMake->GetCommandDocumentation(v);
}
//---------------------------------------------------------------------- //----------------------------------------------------------------------
// this sets up some variables for the script to use, creates the required // this sets up some variables for the script to use, creates the required
// cmake instance and generators, and then reads in the script // cmake instance and generators, and then reads in the script
......
...@@ -110,7 +110,6 @@ public: ...@@ -110,7 +110,6 @@ public:
void Initialize(); void Initialize();
void CreateCMake(); void CreateCMake();
void GetCommandDocumentation(std::vector<cmDocumentationEntry>& v) const;
cmake* GetCMake() { return this->CMake;} cmake* GetCMake() { return this->CMake;}
private: private:
// reads in a script // reads in a script
......
...@@ -39,18 +39,6 @@ static const char * cmDocumentationUsage[][3] = ...@@ -39,18 +39,6 @@ static const char * cmDocumentationUsage[][3] =
{0,0,0} {0,0,0}
}; };
//----------------------------------------------------------------------------
static const char * cmDocumentationDescription[][3] =
{
{0,
"The \"ccmake\" executable is the CMake curses interface. Project "
"configuration settings may be specified interactively through "
"this GUI. Brief instructions are provided at the bottom of the "
"terminal when the program is running.", 0},
CMAKE_STANDARD_INTRODUCTION,
{0,0,0}
};
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
static const char * cmDocumentationOptions[][3] = static const char * cmDocumentationOptions[][3] =
{ {
...@@ -58,14 +46,6 @@ static const char * cmDocumentationOptions[][3] = ...@@ -58,14 +46,6 @@ static const char * cmDocumentationOptions[][3] =
{0,0,0} {0,0,0}
}; };
//----------------------------------------------------------------------------
static const char * cmDocumentationSeeAlso[][3] =
{
{0, "cmake", 0},
{0, "ctest", 0},
{0, 0, 0}
};
cmCursesForm* cmCursesForm::CurrentForm=0; cmCursesForm* cmCursesForm::CurrentForm=0;
extern "C" extern "C"
...@@ -106,21 +86,13 @@ int main(int argc, char** argv) ...@@ -106,21 +86,13 @@ int main(int argc, char** argv)
if(doc.CheckOptions(argc, argv)) if(doc.CheckOptions(argc, argv))
{ {
cmake hcm; cmake hcm;
std::vector<cmDocumentationEntry> commands;
std::vector<cmDocumentationEntry> compatCommands;
std::vector<cmDocumentationEntry> generators; std::vector<cmDocumentationEntry> generators;
hcm.GetCommandDocumentation(commands, true, false);
hcm.GetCommandDocumentation(compatCommands, false, true);
hcm.GetGeneratorDocumentation(generators); hcm.GetGeneratorDocumentation(generators);
doc.SetName("ccmake"); doc.SetName("ccmake");
doc.SetSection("Name",cmDocumentationName); doc.SetSection("Name",cmDocumentationName);
doc.SetSection("Usage",cmDocumentationUsage); doc.SetSection("Usage",cmDocumentationUsage);
doc.SetSection("Description",cmDocumentationDescription);
doc.SetSection("Generators",generators); doc.SetSection("Generators",generators);
doc.PrependSection("Options",cmDocumentationOptions); doc.PrependSection("Options",cmDocumentationOptions);
doc.SetSection("Command",commands);
doc.SetSection("Compatibility Commands",compatCommands);
doc.SetSeeAlsoList(cmDocumentationSeeAlso);
return doc.PrintRequestedDocumentation(std::cout)? 0:1; return doc.PrintRequestedDocumentation(std::cout)? 0:1;
} }
......
...@@ -40,18 +40,6 @@ static const char * cmDocumentationUsage[][3] = ...@@ -40,18 +40,6 @@ static const char * cmDocumentationUsage[][3] =
{0,0,0} {0,0,0}
}; };
//----------------------------------------------------------------------------
static const char * cmDocumentationDescription[][3] =
{
{0,
"The \"cmake-gui\" executable is the CMake GUI. Project "
"configuration settings may be specified interactively. "
"Brief instructions are provided at the bottom of the "
"window when the program is running.", 0},
CMAKE_STANDARD_INTRODUCTION,
{0,0,0}
};
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
static const char * cmDocumentationOptions[][3] = static const char * cmDocumentationOptions[][3] =
{ {
...@@ -76,24 +64,14 @@ int main(int argc, char** argv) ...@@ -76,24 +64,14 @@ int main(int argc, char** argv)
{ {
doc.SetCMakeRoot(root); doc.SetCMakeRoot(root);
} }
std::vector<cmDocumentationEntry> commands;
std::vector<cmDocumentationEntry> compatCommands;
std::map<std::string,cmDocumentationSection *> propDocs;
std::vector<cmDocumentationEntry> generators; std::vector<cmDocumentationEntry> generators;
hcm.GetCommandDocumentation(commands, true, false);
hcm.GetCommandDocumentation(compatCommands, false, true);
hcm.GetGeneratorDocumentation(generators); hcm.GetGeneratorDocumentation(generators);
hcm.GetPropertiesDocumentation(propDocs);
doc.SetName("cmake"); doc.SetName("cmake");
doc.SetSection("Name",cmDocumentationName); doc.SetSection("Name",cmDocumentationName);
doc.SetSection("Usage",cmDocumentationUsage); doc.SetSection("Usage",cmDocumentationUsage);
doc.SetSection("Description",cmDocumentationDescription);
doc.AppendSection("Generators",generators); doc.AppendSection("Generators",generators);
doc.PrependSection("Options",cmDocumentationOptions); doc.PrependSection("Options",cmDocumentationOptions);
doc.SetSection("Commands",commands);
doc.SetSection("Compatilbility Commands", compatCommands);
doc.SetSections(propDocs);
return (doc.PrintRequestedDocumentation(std::cout)? 0:1); return (doc.PrintRequestedDocumentation(std::cout)? 0:1);
} }
......
This diff is collapsed.
...@@ -37,22 +37,6 @@ public: ...@@ -37,22 +37,6 @@ public:
~cmDocumentation(); ~cmDocumentation();
/**
* An helper type pair for [structured] documented modules.
* The comment of those module contains structure markup
* which makes it possible to retrieve the documentation
* of variables, macros and functions defined in the module.
* - first is the filename of the module
* - second is the section of the doc the module belongs too
*/
typedef std::pair<std::string,std::string> documentedModuleSectionPair_t;
/**
* A list of documented module(s).
*/
typedef std::list<documentedModuleSectionPair_t> documentedModulesList_t;
// High-level interface for standard documents:
/** /**
* Check command line arguments for documentation options. Returns * Check command line arguments for documentation options. Returns
* true if documentation options are found, and false otherwise. * true if documentation options are found, and false otherwise.
...@@ -73,7 +57,7 @@ public: ...@@ -73,7 +57,7 @@ public:
bool PrintRequestedDocumentation(std::ostream& os); bool PrintRequestedDocumentation(std::ostream& os);
/** Print help of the given type. */ /** Print help of the given type. */
bool PrintDocumentation(Type ht, std::ostream& os, const char* docname=0); bool PrintDocumentation(Type ht, std::ostream& os);
void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; } void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
...@@ -81,7 +65,7 @@ public: ...@@ -81,7 +65,7 @@ public:
void SetName(const char* name); void SetName(const char* name);
/** Set a section of the documentation. Typical sections include Name, /** Set a section of the documentation. Typical sections include Name,
Usage, Description, Options, SeeAlso */ Usage, Description, Options */
void SetSection(const char *sectionName, void SetSection(const char *sectionName,
cmDocumentationSection *section); cmDocumentationSection *section);
void SetSection(const char *sectionName, void SetSection(const char *sectionName,
...@@ -123,17 +107,12 @@ public: ...@@ -123,17 +107,12 @@ public:
*/ */
void AddSectionToPrint(const char *section); void AddSectionToPrint(const char *section);
void SetSeeAlsoList(const char *data[][3]);
/** Clear all previously added sections of help. */ /** Clear all previously added sections of help. */
void ClearSections(); void ClearSections();
/** Set cmake root so we can find installed files */ /** Set cmake root so we can find installed files */
void SetCMakeRoot(const char* root) { this->CMakeRoot = root;} void SetCMakeRoot(const char* root) { this->CMakeRoot = root;}
/** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
void SetCMakeModulePath(const char* path) { this->CMakeModulePath = path;}
static Form GetFormFromFilename(const std::string& filename, static Form GetFormFromFilename(const std::string& filename,
int* ManSection); int* ManSection);
...@@ -149,62 +128,21 @@ public: ...@@ -149,62 +128,21 @@ public:
/** Add the CPack standard documentation section(s) */ /** Add the CPack standard documentation section(s) */
void addCPackStandardDocSections(); void addCPackStandardDocSections();
/** Add automatic variables sections */
void addAutomaticVariableSections(const std::string& section);
private: private:
void SetForm(Form f, int manSection); void SetForm(Form f, int manSection);
void SetDocName(const char* docname);
bool CreateSingleModule(const char* fname,
const char* moduleName,
cmDocumentationSection &sec);
void CreateModuleDocsForDir(cmsys::Directory& dir,
cmDocumentationSection &moduleSection);
bool CreateModulesSection();
bool CreateCustomModulesSection();
void CreateFullDocumentation();
void AddDocumentIntroToPrint(const char* intro[2]);
bool PrintCopyright(std::ostream& os);
bool PrintVersion(std::ostream& os); bool PrintVersion(std::ostream& os);
bool PrintDocumentationGeneric(std::ostream& os, const char *section);
bool PrintDocumentationList(std::ostream& os, const char *section);
bool PrintDocumentationSingle(std::ostream& os);
bool PrintDocumentationSingleModule(std::ostream& os);
bool PrintDocumentationSingleProperty(std::ostream& os);
bool PrintDocumentationSinglePolicy(std::ostream& os);
bool PrintDocumentationSingleVariable(std::ostream& os);
bool PrintDocumentationUsage(std::ostream& os); bool PrintDocumentationUsage(std::ostream& os);
bool PrintDocumentationFull(std::ostream& os);
bool PrintDocumentationModules(std::ostream& os);
bool PrintDocumentationCustomModules(std::ostream& os);
bool PrintDocumentationPolicies(std::ostream& os);
bool PrintDocumentationProperties(std::ostream& os);
bool PrintDocumentationVariables(std::ostream& os);
bool PrintDocumentationCurrentCommands(std::ostream& os);
bool PrintDocumentationCompatCommands(std::ostream& os);
void PrintDocumentationCommand(std::ostream& os,
const cmDocumentationEntry &entry);
const char* GetNameString() const; const char* GetNameString() const;
const char* GetDocName(bool fallbackToNameString = true) const;
const char* GetDefaultDocName(Type ht) const;
bool IsOption(const char* arg) const; bool IsOption(const char* arg) const;
bool ShowGenerators; bool ShowGenerators;
std::string NameString; std::string NameString;
std::string DocName;
std::map<std::string,cmDocumentationSection*> AllSections; std::map<std::string,cmDocumentationSection*> AllSections;
std::string SeeAlsoString;
std::string CMakeRoot; std::string CMakeRoot;
std::string CMakeModulePath;
std::set<std::string> ModulesFound;
std::vector< char* > ModuleStrings;
std::vector<const cmDocumentationSection *> PrintSections; std::vector<const cmDocumentationSection *> PrintSections;
std::string CurrentArgument; std::string CurrentArgument;
...@@ -226,9 +164,6 @@ private: ...@@ -226,9 +164,6 @@ private:
cmDocumentationFormatterRST RSTFormatter; cmDocumentationFormatterRST RSTFormatter;
cmDocumentationFormatterText TextFormatter; cmDocumentationFormatterText TextFormatter;
cmDocumentationFormatterUsage UsageFormatter; cmDocumentationFormatterUsage UsageFormatter;
std::vector<std::string> PropertySections;
std::vector<std::string> VariableSections;
}; };
#endif #endif
...@@ -27,8 +27,8 @@ public: ...@@ -27,8 +27,8 @@ public:
enum Type enum Type
{ None, Usage, Single, SingleModule, SingleProperty, SingleVariable, { None, Usage, Single, SingleModule, SingleProperty, SingleVariable,
List, ModuleList, PropertyList, VariableList, PolicyList, List, ModuleList, PropertyList, VariableList, PolicyList,
Full, Properties, Variables, Modules, CustomModules, Commands, Properties, Variables, Modules, Commands,
CompatCommands, Copyright, Version, Policies, SinglePolicy }; Copyright, Version, Policies, SinglePolicy };
/** Forms of documentation output. */ /** Forms of documentation output. */
enum Form { TextForm, HTMLForm, RSTForm, ManForm, UsageForm, DocbookForm }; enum Form { TextForm, HTMLForm, RSTForm, ManForm, UsageForm, DocbookForm };
......
...@@ -935,52 +935,6 @@ cmPolicies::GetPolicyStatus(cmPolicies::PolicyID id) ...@@ -935,52 +935,6 @@ cmPolicies::GetPolicyStatus(cmPolicies::PolicyID id)
return pos->second->Status; return pos->second->Status;
} }
void cmPolicies::GetDocumentation(std::vector<cmDocumentationEntry>& v)
{
// now loop over all the policies and set them as appropriate
std::map<cmPolicies::PolicyID,cmPolicy *>::iterator i
= this->Policies.begin();
for (;i != this->Policies.end(); ++i)
{
cmOStringStream full;
full << i->second->LongDescription;
full << "\nThis policy was introduced in CMake version ";
full << i->second->GetVersionString() << ".";
if(i->first != cmPolicies::CMP0000)
{
full << " "
<< "CMake version |release| ";
// add in some more text here based on status
switch (i->second->Status)
{
case cmPolicies::WARN:
full << "warns when the policy is not set and uses OLD behavior. "
<< "Use the cmake_policy command to set it to OLD or NEW "
<< "explicitly.";
break;
case cmPolicies::OLD:
full << "defaults to the OLD behavior for this policy.";
break;
case cmPolicies::NEW:
full << "defaults to the NEW behavior for this policy.";
break;
case cmPolicies::REQUIRED_IF_USED:
full << "requires the policy to be set to NEW if you use it. "
<< "Use the cmake_policy command to set it to NEW.";
break;
case cmPolicies::REQUIRED_ALWAYS:
full << "requires the policy to be set to NEW. "
<< "Use the cmake_policy command to set it to NEW.";
break;
}
}
cmDocumentationEntry e(i->second->IDString.c_str(),
i->second->ShortDescription.c_str(),
full.str().c_str());
v.push_back(e);
}
}
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
std::string std::string
cmPolicies::GetRequiredAlwaysPolicyError(cmPolicies::PolicyID id) cmPolicies::GetRequiredAlwaysPolicyError(cmPolicies::PolicyID id)
......
...@@ -116,9 +116,6 @@ public: ...@@ -116,9 +116,6 @@ public:
///! return an error string for when a required policy is unspecified ///! return an error string for when a required policy is unspecified
std::string GetRequiredAlwaysPolicyError(cmPolicies::PolicyID id); std::string GetRequiredAlwaysPolicyError(cmPolicies::PolicyID id);
///! Get docs for policies
void GetDocumentation(std::vector<cmDocumentationEntry>& v);
/** Represent a set of policy values. */ /** Represent a set of policy values. */
typedef std::map<PolicyID, PolicyStatus> PolicyMap; typedef std::map<PolicyID, PolicyStatus> PolicyMap;
......
...@@ -35,63 +35,6 @@ void cmPropertyDefinitionMap ...@@ -35,63 +35,6 @@ void cmPropertyDefinitionMap
} }
} }
void cmPropertyDefinitionMap
::GetPropertiesDocumentation(std::map<std::string,
cmDocumentationSection *>& v) const
{
for(cmPropertyDefinitionMap::const_iterator j = this->begin();
j != this->end(); ++j)
{
// add a section if needed
std::string secName = j->second.GetDocumentationSection();
// if a section was not specified then use the scope
if (!secName.size())
{
switch (j->second.GetScope())
{
case cmProperty::GLOBAL: