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
CPack/cmCPackTarCompressGenerator.cxx
CPack/cmCPackZIPGenerator.cxx
CPack/cmCPackDocumentVariables.cxx
CPack/cmCPackDocumentMacros.cxx
)
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 @@
#include "cmake.h"
#include "cmDocumentation.h"
#include "cmCPackDocumentVariables.h"
#include "cmCPackDocumentMacros.h"
#include "cmCPackGeneratorFactory.h"
#include "cmCPackGenerator.h"
#include "cmake.h"
......@@ -45,18 +44,6 @@ static const char * cmDocumentationUsage[][3] =
{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] =
{
......@@ -129,14 +116,6 @@ static const char * cmDocumentationOptions[][3] =
{0,0,0}
};
//----------------------------------------------------------------------------
static const char * cmDocumentationSeeAlso[][3] =
{
{0, "cmake", 0},
{0, "ccmake", 0},
{0, 0, 0}
};
//----------------------------------------------------------------------------
int cpackUnknownArgument(const char*, void*)
{
......@@ -533,22 +512,8 @@ int main (int argc, char *argv[])
doc.SetName("cpack");
doc.SetSection("Name",cmDocumentationName);
doc.SetSection("Usage",cmDocumentationUsage);
doc.SetSection("Description",cmDocumentationDescription);
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;
cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt;
for( generatorIt = generators.GetGeneratorsList().begin();
......@@ -563,7 +528,6 @@ int main (int argc, char *argv[])
}
doc.SetSection("Generators",v);
doc.SetSeeAlsoList(cmDocumentationSeeAlso);
#undef cout
return doc.PrintRequestedDocumentation(std::cout)? 0:1;
#define cout no_cout_use_cmCPack_Log
......
......@@ -361,12 +361,6 @@ void cmCTestScriptHandler::CreateCMake()
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
// cmake instance and generators, and then reads in the script
......
......@@ -110,7 +110,6 @@ public:
void Initialize();
void CreateCMake();
void GetCommandDocumentation(std::vector<cmDocumentationEntry>& v) const;
cmake* GetCMake() { return this->CMake;}
private:
// reads in a script
......
......@@ -39,18 +39,6 @@ static const char * cmDocumentationUsage[][3] =
{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] =
{
......@@ -58,14 +46,6 @@ static const char * cmDocumentationOptions[][3] =
{0,0,0}
};
//----------------------------------------------------------------------------
static const char * cmDocumentationSeeAlso[][3] =
{
{0, "cmake", 0},
{0, "ctest", 0},
{0, 0, 0}
};
cmCursesForm* cmCursesForm::CurrentForm=0;
extern "C"
......@@ -106,21 +86,13 @@ int main(int argc, char** argv)
if(doc.CheckOptions(argc, argv))
{
cmake hcm;
std::vector<cmDocumentationEntry> commands;
std::vector<cmDocumentationEntry> compatCommands;
std::vector<cmDocumentationEntry> generators;
hcm.GetCommandDocumentation(commands, true, false);
hcm.GetCommandDocumentation(compatCommands, false, true);
hcm.GetGeneratorDocumentation(generators);
doc.SetName("ccmake");
doc.SetSection("Name",cmDocumentationName);
doc.SetSection("Usage",cmDocumentationUsage);
doc.SetSection("Description",cmDocumentationDescription);
doc.SetSection("Generators",generators);
doc.PrependSection("Options",cmDocumentationOptions);
doc.SetSection("Command",commands);
doc.SetSection("Compatibility Commands",compatCommands);
doc.SetSeeAlsoList(cmDocumentationSeeAlso);
return doc.PrintRequestedDocumentation(std::cout)? 0:1;
}
......
......@@ -40,18 +40,6 @@ static const char * cmDocumentationUsage[][3] =
{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] =
{
......@@ -76,24 +64,14 @@ int main(int argc, char** argv)
{
doc.SetCMakeRoot(root);
}
std::vector<cmDocumentationEntry> commands;
std::vector<cmDocumentationEntry> compatCommands;
std::map<std::string,cmDocumentationSection *> propDocs;
std::vector<cmDocumentationEntry> generators;
hcm.GetCommandDocumentation(commands, true, false);
hcm.GetCommandDocumentation(compatCommands, false, true);
hcm.GetGeneratorDocumentation(generators);
hcm.GetPropertiesDocumentation(propDocs);
doc.SetName("cmake");
doc.SetSection("Name",cmDocumentationName);
doc.SetSection("Usage",cmDocumentationUsage);
doc.SetSection("Description",cmDocumentationDescription);
doc.AppendSection("Generators",generators);
doc.PrependSection("Options",cmDocumentationOptions);
doc.SetSection("Commands",commands);
doc.SetSection("Compatilbility Commands", compatCommands);
doc.SetSections(propDocs);
return (doc.PrintRequestedDocumentation(std::cout)? 0:1);
}
......
This diff is collapsed.
......@@ -37,22 +37,6 @@ public:
~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
* true if documentation options are found, and false otherwise.
......@@ -73,7 +57,7 @@ public:
bool PrintRequestedDocumentation(std::ostream& os);
/** 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; }
......@@ -81,7 +65,7 @@ public:
void SetName(const char* name);
/** Set a section of the documentation. Typical sections include Name,
Usage, Description, Options, SeeAlso */
Usage, Description, Options */
void SetSection(const char *sectionName,
cmDocumentationSection *section);
void SetSection(const char *sectionName,
......@@ -123,17 +107,12 @@ public:
*/
void AddSectionToPrint(const char *section);
void SetSeeAlsoList(const char *data[][3]);
/** Clear all previously added sections of help. */
void ClearSections();
/** Set cmake root so we can find installed files */
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,
int* ManSection);
......@@ -149,62 +128,21 @@ public:
/** Add the CPack standard documentation section(s) */
void addCPackStandardDocSections();
/** Add automatic variables sections */
void addAutomaticVariableSections(const std::string& section);
private:
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 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 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* GetDocName(bool fallbackToNameString = true) const;
const char* GetDefaultDocName(Type ht) const;
bool IsOption(const char* arg) const;
bool ShowGenerators;
std::string NameString;
std::string DocName;
std::map<std::string,cmDocumentationSection*> AllSections;
std::string SeeAlsoString;
std::string CMakeRoot;
std::string CMakeModulePath;
std::set<std::string> ModulesFound;
std::vector< char* > ModuleStrings;
std::vector<const cmDocumentationSection *> PrintSections;
std::string CurrentArgument;
......@@ -226,9 +164,6 @@ private:
cmDocumentationFormatterRST RSTFormatter;
cmDocumentationFormatterText TextFormatter;
cmDocumentationFormatterUsage UsageFormatter;
std::vector<std::string> PropertySections;
std::vector<std::string> VariableSections;
};
#endif
......@@ -27,8 +27,8 @@ public:
enum Type
{ None, Usage, Single, SingleModule, SingleProperty, SingleVariable,
List, ModuleList, PropertyList, VariableList, PolicyList,
Full, Properties, Variables, Modules, CustomModules, Commands,
CompatCommands, Copyright, Version, Policies, SinglePolicy };
Properties, Variables, Modules, Commands,
Copyright, Version, Policies, SinglePolicy };
/** Forms of documentation output. */
enum Form { TextForm, HTMLForm, RSTForm, ManForm, UsageForm, DocbookForm };
......
......@@ -935,52 +935,6 @@ cmPolicies::GetPolicyStatus(cmPolicies::PolicyID id)
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
cmPolicies::GetRequiredAlwaysPolicyError(cmPolicies::PolicyID id)
......
......@@ -116,9 +116,6 @@ public:
///! return an error string for when a required policy is unspecified
std::string GetRequiredAlwaysPolicyError(cmPolicies::PolicyID id);
///! Get docs for policies
void GetDocumentation(std::vector<cmDocumentationEntry>& v);
/** Represent a set of policy values. */
typedef std::map<PolicyID, PolicyStatus> PolicyMap;
......
......@@ -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:
secName = "Properties of Global Scope";
break;
case cmProperty::TARGET:
secName = "Properties on Targets";
break;
case cmProperty::SOURCE_FILE:
secName = "Properties on Source Files";
break;
case cmProperty::DIRECTORY:
secName = "Properties on Directories";
break;
case cmProperty::TEST:
secName = "Properties on Tests";
break;
case cmProperty::CACHE:
secName = "Properties on Cache Entries";
break;
case cmProperty::VARIABLE:
secName = "Variables";
break;
case cmProperty::CACHED_VARIABLE:
secName = "Cached Variables";
break;
default:
secName = "Properties of Unknown Scope";
break;
}
}
if (!v[secName])
{
v[secName] = new
cmDocumentationSection(secName.c_str(),
cmSystemTools::UpperCase(secName).c_str());
}
cmDocumentationEntry e = j->second.GetDocumentation();
if (e.Brief.size() || e.Full.size())
{
v[secName]->Append(e);
}
}
}
bool cmPropertyDefinitionMap::IsPropertyDefined(const char *name)
{
if (!name)
......
......@@ -32,9 +32,6 @@ public:
// is a named property set to chain
bool IsPropertyChained(const char *name);
void GetPropertiesDocumentation(std::map<std::string,
cmDocumentationSection *>&) const;
};
#endif
......
......@@ -1995,45 +1995,6 @@ void cmake::UpdateProgress(const char *msg, float prog)
}
}
void cmake::GetCommandDocumentation(std::vector<cmDocumentationEntry>& v,
bool withCurrentCommands,
bool withCompatCommands) const
{
for(RegisteredCommandsMap::const_iterator j = this->Commands.begin();
j != this->Commands.end(); ++j)
{
if ((( withCompatCommands == false) && ( (*j).second->IsDiscouraged()))
|| ((withCurrentCommands == false) && (!(*j).second->IsDiscouraged()))
|| (!((*j).second->ShouldAppearInDocumentation()))
)
{
continue;
}
cmDocumentationEntry e((*j).second->GetName(),
(*j).second->GetTerseDocumentation(),
(*j).second->GetFullDocumentation());
v.push_back(e);
}
}
void cmake::GetPolicyDocumentation(std::vector<cmDocumentationEntry>& v)
{
this->Policies->GetDocumentation(v);
}
void cmake::GetPropertiesDocumentation(std::map<std::string,
cmDocumentationSection *>& v)
{
// loop over the properties and put them into the doc structure
std::map<cmProperty::ScopeType, cmPropertyDefinitionMap>::iterator i;
i = this->PropertyDefinitions.begin();
for (;i != this->PropertyDefinitions.end(); ++i)
{
i->second.GetPropertiesDocumentation(v);
}
}
void cmake::GetGeneratorDocumentation(std::vector<cmDocumentationEntry>& v)
{
for(RegisteredGeneratorsVector::const_iterator i =
......
......@@ -269,20 +269,7 @@ class cmake
///! Get the variable watch object
cmVariableWatch* GetVariableWatch() { return this->VariableWatch; }
/** Get the documentation entries for the supported commands.
* If withCurrentCommands is true, the documentation for the
* recommended set of commands is included.
* If withCompatCommands is true, the documentation for discouraged
* (compatibility) commands is included.
* You probably don't want to set both to false.
*/
void GetCommandDocumentation(std::vector<cmDocumentationEntry>& entries,
bool withCurrentCommands = true,
bool withCompatCommands = true) const;
void GetPropertiesDocumentation(std::map<std::string,
cmDocumentationSection *>&);
void GetGeneratorDocumentation(std::vector<cmDocumentationEntry>&);
void GetPolicyDocumentation(std::vector<cmDocumentationEntry>& entries);
///! Set/Get a property of this target file
void SetProperty(const char *prop, const char *value);
......@@ -519,13 +506,4 @@ private:
"Enable warnings that are meant for the author"\
" of the CMakeLists.txt files."}
#define CMAKE_STANDARD_INTRODUCTION \
{0, \
"CMake is a cross-platform build system generator. Projects " \
"specify their build process with platform-independent CMake listfiles " \
"included in each directory of a source tree with the name " \
"CMakeLists.txt. " \
"Users build a project by using CMake to generate a build system " \
"for a native tool on their platform.", 0}
#endif
......@@ -44,19 +44,6 @@ static const char * cmDocumentationUsage[][3] =
{0,0,0}