CMake/Source/cmDocumentation.h

248 lines
8.7 KiB
C++

/*=========================================================================
Program: CMake - Cross-Platform Makefile Generator
Module: $RCSfile$
Language: C++
Date: $Date$
Version: $Revision$
Copyright (c) 2002 Kitware, Inc., Insight Consortium. All rights reserved.
See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details.
This software is distributed WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the above copyright notices for more information.
=========================================================================*/
#ifndef _cmDocumentation_h
#define _cmDocumentation_h
#include "cmStandardIncludes.h"
/** Class to generate documentation. */
class cmDocumentation
{
public:
cmDocumentation();
~cmDocumentation();
// High-level interface for standard documents:
/** Types of help provided. */
enum Type { None, Usage, Single, SingleModule, SingleProperty,
List, ModuleList, PropertyList,
Full, HTML, Man, Copyright, Version };
/**
* Check command line arguments for documentation options. Returns
* true if documentation options are found, and false otherwise.
* When true is returned, PrintRequestedDocumentation should be
* called.
*/
bool CheckOptions(int argc, const char* const* argv);
/**
* Print help requested on the command line. Call after
* CheckOptions returns true. Returns true on success, and false
* otherwise. Failure can occur when output files specified on the
* command line cannot be written.
*/
bool PrintRequestedDocumentation(std::ostream& os);
/** Print help of the given type. */
bool PrintDocumentation(Type ht, std::ostream& os);
/** Set the program name for standard document generation. */
void SetName(const char* name);
/** Set the program name section for standard document
* generation. */
void SetNameSection(const cmDocumentationEntry*);
/** Set the program usage for standard document generation. */
void SetUsageSection(const cmDocumentationEntry*);
/** Set the program description for standard document generation. */
void SetDescriptionSection(const cmDocumentationEntry*);
/** Set the program options for standard document generation. */
void SetOptionsSection(const cmDocumentationEntry*);
/** Set the listfile commands for standard document generation. */
void SetCommandsSection(const cmDocumentationEntry*);
/** Set the properties for standard document generation. */
void SetPropertiesSection(const cmDocumentationEntry*);
/** Set the generator descriptions for standard document generation. */
void SetGeneratorsSection(const cmDocumentationEntry*);
/** Set the see-also list of references to the other tools. */
void SetSeeAlsoList(const cmDocumentationEntry*);
// Low-level interface for custom documents:
/** Forms of documentation output. */
enum Form { TextForm, HTMLForm, ManForm, UsageForm };
/** Internal class representing a section of the documentation.
* Cares e.g. for the different section titles in the different
* output formats.
*/
class cmSection
{
public:
/** Create a cmSection, with a special name for man-output mode. */
cmSection(const char* name, const char* manName)
:Name(name), ManName(manName) {}
/** Has any content been added to this section or is it empty ? */
bool IsEmpty() const
{ return this->Entries.empty(); }
/** Clear contents. */
void Clear()
{ this->Entries.clear(); }
/** Return the name of this section for the given output form. */
const char* GetName(Form form) const
{ return (form==ManForm?this->ManName.c_str():this->Name.c_str()); }
/** Return a pointer to the first entry of this section. */
cmDocumentationEntry *GetEntries()
{ return &this->Entries[0]; }
/** Return a pointer to the first entry of this section. */
const cmDocumentationEntry *GetEntries() const
{ return &this->Entries[0]; }
/** Append an entry to this section. */
void Append(const cmDocumentationEntry& entry)
{ this->Entries.push_back(entry); }
/** Set the contents of this section. */
void Set(const cmDocumentationEntry* header,
const cmDocumentationEntry* section,
const cmDocumentationEntry* footer);
private:
std::string Name;
std::string ManName;
std::vector<cmDocumentationEntry> Entries;
};
/**
* Print documentation in the given form. All previously added
* sections will be generated.
*/
void Print(Form f, std::ostream& os);
/**
* Print documentation in the current form. All previously added
* sections will be generated.
*/
void Print(std::ostream& os);
/**
* Add a section of documentation. The cmDocumentationEntry pointer
* should point at an array terminated by an all zero ({0,0,0})
* entry. This can be used to generate custom help documents.
*/
void AddSection(const char* name, const cmDocumentationEntry* d);
/** Convenience function, does the same as above */
void AddSection(const cmSection& section);
/** 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;}
private:
void PrintHeader(const char* title, std::ostream& os);
void PrintFooter(std::ostream& os);
void PrintSection(std::ostream& os,
const cmDocumentationEntry* section,
const char* name);
void PrintSectionText(std::ostream& os,
const cmDocumentationEntry* section,
const char* name);
void PrintSectionHTML(std::ostream& os,
const cmDocumentationEntry* section,
const char* name);
void PrintSectionMan(std::ostream& os, const cmDocumentationEntry* section,
const char* name);
void PrintSectionUsage(std::ostream& os,
const cmDocumentationEntry* section,
const char* name);
void PrintFormatted(std::ostream& os, const char* text);
void PrintPreformatted(std::ostream& os, const char* text);
void PrintPreformattedText(std::ostream& os, const char* text);
void PrintPreformattedHTML(std::ostream& os, const char* text);
void PrintPreformattedMan(std::ostream& os, const char* text);
void PrintParagraph(std::ostream& os, const char* text);
void PrintParagraphText(std::ostream& os, const char* text);
void PrintParagraphHTML(std::ostream& os, const char* text);
void PrintParagraphMan(std::ostream& os, const char* text);
void PrintColumn(std::ostream& os, const char* text);
void PrintHTMLEscapes(std::ostream& os, const char* text);
bool CreateSingleModule(const char* fname, const char* moduleName);
bool CreateModulesSection();
bool PrintCopyright(std::ostream& os);
bool PrintVersion(std::ostream& os);
bool PrintDocumentationList(std::ostream& os);
bool PrintModuleList(std::ostream& os);
bool PrintPropertyList(std::ostream& os);
bool PrintDocumentationSingle(std::ostream& os);
bool PrintDocumentationSingleModule(std::ostream& os);
bool PrintDocumentationSingleProperty(std::ostream& os);
bool PrintDocumentationUsage(std::ostream& os);
bool PrintDocumentationFull(std::ostream& os);
void PrintDocumentationCommand(std::ostream& os,
cmDocumentationEntry* entry);
void CreateUsageDocumentation();
void CreateFullDocumentation();
void SetSection(const cmDocumentationEntry* header,
const cmDocumentationEntry* section,
const cmDocumentationEntry* footer,
std::vector<cmDocumentationEntry>&);
const char* GetNameString() const;
bool IsOption(const char* arg) const;
std::string NameString;
cmSection NameSection;
cmSection UsageSection;
cmSection DescriptionSection;
cmSection OptionsSection;
cmSection CommandsSection;
cmSection CompatCommandsSection;
cmSection ModulesSection;
cmSection PropertiesSection;
cmSection GeneratorsSection;
cmSection SeeAlsoSection;
cmSection CopyrightSection;
cmSection AuthorSection;
std::string SeeAlsoString;
std::string SingleCommand;
std::string SingleModuleName;
std::string SinglePropertyName;
std::string CMakeRoot;
std::vector< char* > ModuleStrings;
std::vector< const char* > Names;
std::vector< const cmDocumentationEntry* > Sections;
Form CurrentForm;
const char* TextIndent;
int TextWidth;
typedef std::map<Type, cmStdString> RequestedMapType;
RequestedMapType RequestedMap;
};
#endif