/src/CMake/Source/cmRST.cxx

Source
/* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   file LICENSE.rst or https://cmake.org/licensing for details.  */
#include "cmRST.h"

#include <algorithm>
#include <cstddef>
#include <iterator>
#include <utility>

#include "cmsys/FStream.hxx"
#include "cmsys/String.h"

#include "cmAlgorithms.h"
#include "cmRange.h"
#include "cmStringAlgorithms.h"
#include "cmSystemTools.h"
#include "cmVersion.h"

cmRST::cmRST(std::ostream& os, std::string docroot)
  : OS(os)
  , DocRoot(std::move(docroot))
  , CMakeDirective("^.. (cmake:)?("
                   "command|envvar|genex|signature|variable"
                   ")::")
  , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$")
  , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$")
  , CodeBlockDirective("^.. code-block::[ \t]*(.*)$")
  , ReplaceDirective("^.. (\\|[^|]+\\|) replace::[ \t]*(.*)$")
  , IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$")
  , TocTreeDirective("^.. toctree::[ \t]*(.*)$")
  , ProductionListDirective("^.. productionlist::[ \t]*(.*)$")
  , NoteDirective("^.. note::[ \t]*(.*)$")
  , VersionDirective("^.. version(added|changed)::[ \t]*(.*)$")
  , ModuleRST(R"(^#\[(=*)\[\.rst:$)")
  , CMakeRole("(:cmake)?:("
              "cref|"
              "command|cpack_gen|generator|genex|"
              "variable|envvar|module|policy|"
              "prop_cache|prop_dir|prop_gbl|prop_inst|prop_sf|"
              "prop_test|prop_tgt|"
              "manual"
              "):`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`")
  , InlineLink("`(<*([^`<]|[^` \t]<)*)([ \t]+<[^`]*>)?`_")
  , InlineLiteral("``([^`]*)``")
  , Substitution("(^|[^A-Za-z0-9_])"
                 "((\\|[^| \t\r\n]([^|\r\n]*[^| \t\r\n])?\\|)(__|_|))"
                 "([^A-Za-z0-9_]|$)")
  , TocTreeLink("^.*[ \t]+<([^>]+)>$")
{
  this->Replace["|release|"] = cmVersion::GetCMakeVersion();
}

bool cmRST::ProcessFile(std::string const& fname, bool isModule)
{
  cmsys::ifstream fin(fname.c_str());
  if (fin) {
    this->DocDir = cmSystemTools::GetFilenamePath(fname);
    if (isModule) {
      this->ProcessModule(fin);
    } else {
      this->ProcessRST(fin);
    }
    this->OutputLinePending = true;
    return true;
  }
  return false;
}

void cmRST::ProcessRST(std::istream& is)
{
  std::string line;
  while (cmSystemTools::GetLineFromStream(is, line)) {
    this->ProcessLine(line);
  }
  this->Reset();
}

void cmRST::ProcessModule(std::istream& is)
{
  std::string line;
  std::string rst;
  while (cmSystemTools::GetLineFromStream(is, line)) {
    if (!rst.empty() && rst != "#") {
      // Bracket mode: check for end bracket
      std::string::size_type pos = line.find(rst);
      if (pos == std::string::npos) {
        this->ProcessLine(line);
      } else {
        if (line[0] != '#') {
          line.resize(pos);
          this->ProcessLine(line);
        }
        rst.clear();
        this->Reset();
        this->OutputLinePending = true;
      }
    } else {
      // Line mode: check for .rst start (bracket or line)
      if (rst == "#") {
        if (line == "#") {
          this->ProcessLine("");
          continue;
        }
        if (cmHasLiteralPrefix(line, "# ")) {
          line.erase(0, 2);
          this->ProcessLine(line);
          continue;
        }
        rst.clear();
        this->Reset();
        this->OutputLinePending = true;
      }
      if (line == "#.rst:") {
        rst = "#";
      } else if (this->ModuleRST.find(line)) {
        rst = "]" + this->ModuleRST.match(1) + "]";
      }
    }
  }
  if (rst == "#") {
    this->Reset();
  }
}

void cmRST::Reset()
{
  if (!this->MarkupLines.empty()) {
    cmRST::UnindentLines(this->MarkupLines);
  }
  switch (this->DirectiveType) {
    case Directive::None:
      break;
    case Directive::ParsedLiteral:
      this->ProcessDirectiveParsedLiteral();
      break;
    case Directive::LiteralBlock:
      this->ProcessDirectiveLiteralBlock();
      break;
    case Directive::CodeBlock:
      this->ProcessDirectiveCodeBlock();
      break;
    case Directive::Replace:
      this->ProcessDirectiveReplace();
      break;
    case Directive::TocTree:
      this->ProcessDirectiveTocTree();
      break;
  }
  this->MarkupType = Markup::None;
  this->DirectiveType = Directive::None;
  this->MarkupLines.clear();
}

void cmRST::ProcessLine(std::string const& line)
{
  bool lastLineEndedInColonColon = this->LastLineEndedInColonColon;
  this->LastLineEndedInColonColon = false;

  // A line starting in .. is an explicit markup start.
  if (line == ".." ||
      (line.size() >= 3 && line[0] == '.' && line[1] == '.' &&
       cmsysString_isspace(line[2]))) {
    this->Reset();
    this->MarkupType =
      (line.find_first_not_of(" \t", 2) == std::string::npos ? Markup::Empty
                                                             : Markup::Normal);
    // XXX(clang-tidy): https://bugs.llvm.org/show_bug.cgi?id=44165
    // NOLINTNEXTLINE(bugprone-branch-clone)
    if (this->CMakeDirective.find(line)) {
      // Output cmake domain directives and their content normally.
      this->NormalLine(line);
    } else if (this->CMakeModuleDirective.find(line)) {
      // Process cmake-module directive: scan .cmake file comments.
      std::string file = this->CMakeModuleDirective.match(1);
      if (file.empty() || !this->ProcessInclude(file, Include::Module)) {
        this->NormalLine(line);
      }
    } else if (this->ParsedLiteralDirective.find(line)) {
      // Record the literal lines to output after whole block.
      this->DirectiveType = Directive::ParsedLiteral;
      this->MarkupLines.push_back(this->ParsedLiteralDirective.match(1));
    } else if (this->CodeBlockDirective.find(line)) {
      // Record the literal lines to output after whole block.
      // Ignore the language spec and record the opening line as blank.
      this->DirectiveType = Directive::CodeBlock;
      this->MarkupLines.emplace_back();
    } else if (this->ReplaceDirective.find(line)) {
      // Record the replace directive content.
      this->DirectiveType = Directive::Replace;
      this->ReplaceName = this->ReplaceDirective.match(1);
      this->MarkupLines.push_back(this->ReplaceDirective.match(2));
    } else if (this->IncludeDirective.find(line)) {
      // Process the include directive or output the directive and its
      // content normally if it fails.
      std::string file = this->IncludeDirective.match(1);
      if (file.empty() || !this->ProcessInclude(file, Include::Normal)) {
        this->NormalLine(line);
      }
    } else if (this->TocTreeDirective.find(line)) {
      // Record the toctree entries to process after whole block.
      this->DirectiveType = Directive::TocTree;
      this->MarkupLines.push_back(this->TocTreeDirective.match(1));
    } else if (this->ProductionListDirective.find(line)) {
      // Output productionlist directives and their content normally.
      this->NormalLine(line);
    } else if (this->NoteDirective.find(line)) {
      // Output note directives and their content normally.
      this->NormalLine(line);
    } else if (this->VersionDirective.find(line)) {
      // Output versionadded and versionchanged directives and their content
      // normally.
      this->NormalLine(line);
    }
  }
  // An explicit markup start followed by nothing but whitespace and a
  // blank line does not consume any indented text following.
  else if (this->MarkupType == Markup::Empty && line.empty()) {
    this->NormalLine(line);
  }
  // Indented lines following an explicit markup start are explicit markup.
  else if (this->MarkupType != Markup::None &&
           (line.empty() || cmsysString_isspace(line[0]))) {
    this->MarkupType = Markup::Normal;
    // Record markup lines if the start line was recorded.
    if (!this->MarkupLines.empty()) {
      this->MarkupLines.push_back(line);
    }
  }
  // A blank line following a paragraph ending in "::" starts a literal block.
  else if (lastLineEndedInColonColon && line.empty()) {
    // Record the literal lines to output after whole block.
    this->MarkupType = Markup::Normal;
    this->DirectiveType = Directive::LiteralBlock;
    this->MarkupLines.emplace_back();
    this->OutputLine("", false);
  }
  // Print non-markup lines.
  else {
    this->NormalLine(line);
    this->LastLineEndedInColonColon =
      (line.size() >= 2 && line[line.size() - 2] == ':' && line.back() == ':');
  }
}

void cmRST::NormalLine(std::string const& line)
{
  this->Reset();
  this->OutputLine(line, true);
}

void cmRST::OutputLine(std::string const& line_in, bool inlineMarkup)
{
  if (this->OutputLinePending) {
    this->OS << "\n";
    this->OutputLinePending = false;
  }
  if (inlineMarkup) {
    std::string line = this->ReplaceSubstitutions(line_in);
    std::string::size_type pos = 0;
    for (;;) {
      std::string::size_type* first = nullptr;
      std::string::size_type role_start = std::string::npos;
      std::string::size_type link_start = std::string::npos;
      std::string::size_type lit_start = std::string::npos;
      if (this->CMakeRole.find(line.c_str() + pos)) {
        role_start = this->CMakeRole.start();
        first = &role_start;
      }
      if (this->InlineLiteral.find(line.c_str() + pos)) {
        lit_start = this->InlineLiteral.start();
        if (!first || lit_start < *first) {
          first = &lit_start;
        }
      }
      if (this->InlineLink.find(line.c_str() + pos)) {
        link_start = this->InlineLink.start();
        if (!first || link_start < *first) {
          first = &link_start;
        }
      }
      if (first == &role_start) {
        this->OS << line.substr(pos, role_start);
        std::string text = this->CMakeRole.match(3);
        // If a command reference has no explicit target and
        // no explicit "(...)" then add "()" to the text.
        if (this->CMakeRole.match(2) == "command" &&
            this->CMakeRole.match(5).empty() &&
            text.find_first_of("()") == std::string::npos) {
          text += "()";
        }
        this->OS << "``" << text << "``";
        pos += this->CMakeRole.end();
      } else if (first == &lit_start) {
        this->OS << line.substr(pos, lit_start);
        std::string text = this->InlineLiteral.match(1);
        pos += this->InlineLiteral.end();
        this->OS << "``" << text << "``";
      } else if (first == &link_start) {
        this->OS << line.substr(pos, link_start);
        std::string text = this->InlineLink.match(1);
        bool escaped = false;
        for (char c : text) {
          if (escaped) {
            escaped = false;
            this->OS << c;
          } else if (c == '\\') {
            escaped = true;
          } else {
            this->OS << c;
          }
        }
        pos += this->InlineLink.end();
      } else {
        break;
      }
    }
    this->OS << line.substr(pos) << "\n";
  } else {
    this->OS << line_in << "\n";
  }
}

std::string cmRST::ReplaceSubstitutions(std::string const& line)
{
  std::string out;
  std::string::size_type pos = 0;
  while (this->Substitution.find(line.c_str() + pos)) {
    std::string::size_type start = this->Substitution.start(2);
    std::string::size_type end = this->Substitution.end(2);
    std::string substitute = this->Substitution.match(3);
    auto replace = this->Replace.find(substitute);
    if (replace != this->Replace.end()) {
      std::pair<std::set<std::string>::iterator, bool> replaced =
        this->Replaced.insert(substitute);
      if (replaced.second) {
        substitute = this->ReplaceSubstitutions(replace->second);
        this->Replaced.erase(replaced.first);
      }
    }
    out += line.substr(pos, start);
    out += substitute;
    pos += end;
  }
  out += line.substr(pos);
  return out;
}

void cmRST::OutputMarkupLines(bool inlineMarkup)
{
  for (auto line : this->MarkupLines) {
    if (!line.empty()) {
      line = cmStrCat(' ', line);
    }
    this->OutputLine(line, inlineMarkup);
  }
  this->OutputLinePending = true;
}

bool cmRST::ProcessInclude(std::string file, Include type)
{
  bool found = false;
  if (this->IncludeDepth < 10) {
    cmRST r(this->OS, this->DocRoot);
    r.IncludeDepth = this->IncludeDepth + 1;
    r.OutputLinePending = this->OutputLinePending;
    if (type != Include::TocTree) {
      r.Replace = this->Replace;
    }
    if (file[0] == '/') {
      file = this->DocRoot + file;
    } else {
      file = this->DocDir + "/" + file;
    }
    found = r.ProcessFile(file, type == Include::Module);
    if (type != Include::TocTree) {
      this->Replace = r.Replace;
    }
    this->OutputLinePending = r.OutputLinePending;
  }
  return found;
}

void cmRST::ProcessDirectiveParsedLiteral()
{
  this->OutputMarkupLines(true);
}

void cmRST::ProcessDirectiveLiteralBlock()
{
  this->OutputMarkupLines(false);
}

void cmRST::ProcessDirectiveCodeBlock()
{
  this->OutputMarkupLines(false);
}

void cmRST::ProcessDirectiveReplace()
{
  // Record markup lines as replacement text.
  std::string& replacement = this->Replace[this->ReplaceName];
  replacement += cmJoin(this->MarkupLines, " ");
  this->ReplaceName.clear();
}

void cmRST::ProcessDirectiveTocTree()
{
  // Process documents referenced by toctree directive.
  for (std::string const& line : this->MarkupLines) {
    if (!line.empty() && line[0] != ':') {
      if (this->TocTreeLink.find(line)) {
        std::string const& link = this->TocTreeLink.match(1);
        this->ProcessInclude(link + ".rst", Include::TocTree);
      } else {
        this->ProcessInclude(line + ".rst", Include::TocTree);
      }
    }
  }
}

void cmRST::UnindentLines(std::vector<std::string>& lines)
{
  // Remove the common indentation from the second and later lines.
  std::string indentText;
  std::string::size_type indentEnd = 0;
  bool first = true;
  for (size_t i = 1; i < lines.size(); ++i) {
    std::string const& line = lines[i];

    // Do not consider empty lines.
    if (line.empty()) {
      continue;
    }

    // Record indentation on first non-empty line.
    if (first) {
      first = false;
      indentEnd = line.find_first_not_of(" \t");
      indentText = line.substr(0, indentEnd);
      continue;
    }

    // Truncate indentation to match that on this line.
    indentEnd = std::min(indentEnd, line.size());
    for (std::string::size_type j = 0; j != indentEnd; ++j) {
      if (line[j] != indentText[j]) {
        indentEnd = j;
        break;
      }
    }
  }

  // Update second and later lines.
  for (size_t i = 1; i < lines.size(); ++i) {
    std::string& line = lines[i];
    if (!line.empty()) {
      line = line.substr(indentEnd);
    }
  }

  auto it = lines.cbegin();
  size_t leadingEmpty = std::distance(it, cmFindNot(lines, std::string()));

  auto rit = lines.crbegin();
  size_t trailingEmpty =
    std::distance(rit, cmFindNot(cmReverseRange(lines), std::string()));

  if ((leadingEmpty + trailingEmpty) >= lines.size()) {
    // All lines are empty.  The markup block is empty.  Leave only one.
    lines.resize(1);
    return;
  }

  auto contentEnd = cmRotate(lines.begin(), lines.begin() + leadingEmpty,
                             lines.end() - trailingEmpty);
  lines.erase(contentEnd, lines.end());
}

Coverage Report

Created: 2026-03-12 06:35

Line	Count	Source
1		/* Distributed under the OSI-approved BSD 3-Clause License. See accompanying
2		file LICENSE.rst or https://cmake.org/licensing for details. */
3		#include "cmRST.h"
4
5		#include <algorithm>
6		#include <cstddef>
7		#include <iterator>
8		#include <utility>
9
10		#include "cmsys/FStream.hxx"
11		#include "cmsys/String.h"
12
13		#include "cmAlgorithms.h"
14		#include "cmRange.h"
15		#include "cmStringAlgorithms.h"
16		#include "cmSystemTools.h"
17		#include "cmVersion.h"
18
19		cmRST::cmRST(std::ostream& os, std::string docroot)
20	0	: OS(os)
21	0	, DocRoot(std::move(docroot))
22	0	, CMakeDirective("^.. (cmake:)?("
23	0	"command\|envvar\|genex\|signature\|variable"
24	0	")::")
25	0	, CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$")
26	0	, ParsedLiteralDirective("^.. parsed-literal::[ \t](.)$")
27	0	, CodeBlockDirective("^.. code-block::[ \t](.)$")
28	0	, ReplaceDirective("^.. (\\\|[^\|]+\\\|) replace::[ \t](.)$")
29	0	, IncludeDirective("^.. include::[ \t]+([^ \t\n]+)$")
30	0	, TocTreeDirective("^.. toctree::[ \t](.)$")
31	0	, ProductionListDirective("^.. productionlist::[ \t](.)$")
32	0	, NoteDirective("^.. note::[ \t](.)$")
33	0	, VersionDirective("^.. version(added\|changed)::[ \t](.)$")
34	0	, ModuleRST(R"(^#\[(=*)\[\.rst:$)")
35	0	, CMakeRole("(:cmake)?:("
36	0	"cref\|"
37	0	"command\|cpack_gen\|generator\|genex\|"
38	0	"variable\|envvar\|module\|policy\|"
39	0	"prop_cache\|prop_dir\|prop_gbl\|prop_inst\|prop_sf\|"
40	0	"prop_test\|prop_tgt\|"
41	0	"manual"
42	0	"):`(<([^`<]\|[^` \t]<))([ \t]+<[^`]*>)?`")
43	0	, InlineLink("`(<([^`<]\|[^` \t]<))([ \t]+<[^`]*>)?`_")
44	0	, InlineLiteral("``([^`]*)``")
45	0	, Substitution("(^\|[^A-Za-z0-9_])"
46	0	"((\\\|[^\| \t\r\n]([^\|\r\n]*[^\| \t\r\n])?\\\|)(__\|_\|))"
47	0	"([^A-Za-z0-9_]\|$)")
48	0	, TocTreeLink("^.*[ \t]+<([^>]+)>$")
49	0	{
50	0	this->Replace["\|release\|"] = cmVersion::GetCMakeVersion();
51	0	}
52
53		bool cmRST::ProcessFile(std::string const& fname, bool isModule)
54	0	{
55	0	cmsys::ifstream fin(fname.c_str());
56	0	if (fin) {
57	0	this->DocDir = cmSystemTools::GetFilenamePath(fname);
58	0	if (isModule) {
59	0	this->ProcessModule(fin);
60	0	} else {
61	0	this->ProcessRST(fin);
62	0	}
63	0	this->OutputLinePending = true;
64	0	return true;
65	0	}
66	0	return false;
67	0	}
68
69		void cmRST::ProcessRST(std::istream& is)
70	0	{
71	0	std::string line;
72	0	while (cmSystemTools::GetLineFromStream(is, line)) {
73	0	this->ProcessLine(line);
74	0	}
75	0	this->Reset();
76	0	}
77
78		void cmRST::ProcessModule(std::istream& is)
79	0	{
80	0	std::string line;
81	0	std::string rst;
82	0	while (cmSystemTools::GetLineFromStream(is, line)) {
83	0	if (!rst.empty() && rst != "#") {
84		// Bracket mode: check for end bracket
85	0	std::string::size_type pos = line.find(rst);
86	0	if (pos == std::string::npos) {
87	0	this->ProcessLine(line);
88	0	} else {
89	0	if (line[0] != '#') {
90	0	line.resize(pos);
91	0	this->ProcessLine(line);
92	0	}
93	0	rst.clear();
94	0	this->Reset();
95	0	this->OutputLinePending = true;
96	0	}
97	0	} else {
98		// Line mode: check for .rst start (bracket or line)
99	0	if (rst == "#") {
100	0	if (line == "#") {
101	0	this->ProcessLine("");
102	0	continue;
103	0	}
104	0	if (cmHasLiteralPrefix(line, "# ")) {
105	0	line.erase(0, 2);
106	0	this->ProcessLine(line);
107	0	continue;
108	0	}
109	0	rst.clear();
110	0	this->Reset();
111	0	this->OutputLinePending = true;
112	0	}
113	0	if (line == "#.rst:") {
114	0	rst = "#";
115	0	} else if (this->ModuleRST.find(line)) {
116	0	rst = "]" + this->ModuleRST.match(1) + "]";
117	0	}
118	0	}
119	0	}
120	0	if (rst == "#") {
121	0	this->Reset();
122	0	}
123	0	}
124
125		void cmRST::Reset()
126	0	{
127	0	if (!this->MarkupLines.empty()) {
128	0	cmRST::UnindentLines(this->MarkupLines);
129	0	}
130	0	switch (this->DirectiveType) {
131	0	case Directive::None:
132	0	break;
133	0	case Directive::ParsedLiteral:
134	0	this->ProcessDirectiveParsedLiteral();
135	0	break;
136	0	case Directive::LiteralBlock:
137	0	this->ProcessDirectiveLiteralBlock();
138	0	break;
139	0	case Directive::CodeBlock:
140	0	this->ProcessDirectiveCodeBlock();
141	0	break;
142	0	case Directive::Replace:
143	0	this->ProcessDirectiveReplace();
144	0	break;
145	0	case Directive::TocTree:
146	0	this->ProcessDirectiveTocTree();
147	0	break;
148	0	}
149	0	this->MarkupType = Markup::None;
150	0	this->DirectiveType = Directive::None;
151	0	this->MarkupLines.clear();
152	0	}
153
154		void cmRST::ProcessLine(std::string const& line)
155	0	{
156	0	bool lastLineEndedInColonColon = this->LastLineEndedInColonColon;
157	0	this->LastLineEndedInColonColon = false;
158
159		// A line starting in .. is an explicit markup start.
160	0	if (line == ".." \|\|
161	0	(line.size() >= 3 && line[0] == '.' && line[1] == '.' &&
162	0	cmsysString_isspace(line[2]))) {
163	0	this->Reset();
164	0	this->MarkupType =
165	0	(line.find_first_not_of(" \t", 2) == std::string::npos ? Markup::Empty
166	0	: Markup::Normal);
167		// XXX(clang-tidy): https://bugs.llvm.org/show_bug.cgi?id=44165
168		// NOLINTNEXTLINE(bugprone-branch-clone)
169	0	if (this->CMakeDirective.find(line)) {
170		// Output cmake domain directives and their content normally.
171	0	this->NormalLine(line);
172	0	} else if (this->CMakeModuleDirective.find(line)) {
173		// Process cmake-module directive: scan .cmake file comments.
174	0	std::string file = this->CMakeModuleDirective.match(1);
175	0	if (file.empty() \|\| !this->ProcessInclude(file, Include::Module)) {
176	0	this->NormalLine(line);
177	0	}
178	0	} else if (this->ParsedLiteralDirective.find(line)) {
179		// Record the literal lines to output after whole block.
180	0	this->DirectiveType = Directive::ParsedLiteral;
181	0	this->MarkupLines.push_back(this->ParsedLiteralDirective.match(1));
182	0	} else if (this->CodeBlockDirective.find(line)) {
183		// Record the literal lines to output after whole block.
184		// Ignore the language spec and record the opening line as blank.
185	0	this->DirectiveType = Directive::CodeBlock;
186	0	this->MarkupLines.emplace_back();
187	0	} else if (this->ReplaceDirective.find(line)) {
188		// Record the replace directive content.
189	0	this->DirectiveType = Directive::Replace;
190	0	this->ReplaceName = this->ReplaceDirective.match(1);
191	0	this->MarkupLines.push_back(this->ReplaceDirective.match(2));
192	0	} else if (this->IncludeDirective.find(line)) {
193		// Process the include directive or output the directive and its
194		// content normally if it fails.
195	0	std::string file = this->IncludeDirective.match(1);
196	0	if (file.empty() \|\| !this->ProcessInclude(file, Include::Normal)) {
197	0	this->NormalLine(line);
198	0	}
199	0	} else if (this->TocTreeDirective.find(line)) {
200		// Record the toctree entries to process after whole block.
201	0	this->DirectiveType = Directive::TocTree;
202	0	this->MarkupLines.push_back(this->TocTreeDirective.match(1));
203	0	} else if (this->ProductionListDirective.find(line)) {
204		// Output productionlist directives and their content normally.
205	0	this->NormalLine(line);
206	0	} else if (this->NoteDirective.find(line)) {
207		// Output note directives and their content normally.
208	0	this->NormalLine(line);
209	0	} else if (this->VersionDirective.find(line)) {
210		// Output versionadded and versionchanged directives and their content
211		// normally.
212	0	this->NormalLine(line);
213	0	}
214	0	}
215		// An explicit markup start followed by nothing but whitespace and a
216		// blank line does not consume any indented text following.
217	0	else if (this->MarkupType == Markup::Empty && line.empty()) {
218	0	this->NormalLine(line);
219	0	}
220		// Indented lines following an explicit markup start are explicit markup.
221	0	else if (this->MarkupType != Markup::None &&
222	0	(line.empty() \|\| cmsysString_isspace(line[0]))) {
223	0	this->MarkupType = Markup::Normal;
224		// Record markup lines if the start line was recorded.
225	0	if (!this->MarkupLines.empty()) {
226	0	this->MarkupLines.push_back(line);
227	0	}
228	0	}
229		// A blank line following a paragraph ending in "::" starts a literal block.
230	0	else if (lastLineEndedInColonColon && line.empty()) {
231		// Record the literal lines to output after whole block.
232	0	this->MarkupType = Markup::Normal;
233	0	this->DirectiveType = Directive::LiteralBlock;
234	0	this->MarkupLines.emplace_back();
235	0	this->OutputLine("", false);
236	0	}
237		// Print non-markup lines.
238	0	else {
239	0	this->NormalLine(line);
240	0	this->LastLineEndedInColonColon =
241	0	(line.size() >= 2 && line[line.size() - 2] == ':' && line.back() == ':');
242	0	}
243	0	}
244
245		void cmRST::NormalLine(std::string const& line)
246	0	{
247	0	this->Reset();
248	0	this->OutputLine(line, true);
249	0	}
250
251		void cmRST::OutputLine(std::string const& line_in, bool inlineMarkup)
252	0	{
253	0	if (this->OutputLinePending) {
254	0	this->OS << "\n";
255	0	this->OutputLinePending = false;
256	0	}
257	0	if (inlineMarkup) {
258	0	std::string line = this->ReplaceSubstitutions(line_in);
259	0	std::string::size_type pos = 0;
260	0	for (;;) {
261	0	std::string::size_type* first = nullptr;
262	0	std::string::size_type role_start = std::string::npos;
263	0	std::string::size_type link_start = std::string::npos;
264	0	std::string::size_type lit_start = std::string::npos;
265	0	if (this->CMakeRole.find(line.c_str() + pos)) {
266	0	role_start = this->CMakeRole.start();
267	0	first = &role_start;
268	0	}
269	0	if (this->InlineLiteral.find(line.c_str() + pos)) {
270	0	lit_start = this->InlineLiteral.start();
271	0	if (!first \|\| lit_start < *first) {
272	0	first = &lit_start;
273	0	}
274	0	}
275	0	if (this->InlineLink.find(line.c_str() + pos)) {
276	0	link_start = this->InlineLink.start();
277	0	if (!first \|\| link_start < *first) {
278	0	first = &link_start;
279	0	}
280	0	}
281	0	if (first == &role_start) {
282	0	this->OS << line.substr(pos, role_start);
283	0	std::string text = this->CMakeRole.match(3);
284		// If a command reference has no explicit target and
285		// no explicit "(...)" then add "()" to the text.
286	0	if (this->CMakeRole.match(2) == "command" &&
287	0	this->CMakeRole.match(5).empty() &&
288	0	text.find_first_of("()") == std::string::npos) {
289	0	text += "()";
290	0	}
291	0	this->OS << "``" << text << "``";
292	0	pos += this->CMakeRole.end();
293	0	} else if (first == &lit_start) {
294	0	this->OS << line.substr(pos, lit_start);
295	0	std::string text = this->InlineLiteral.match(1);
296	0	pos += this->InlineLiteral.end();
297	0	this->OS << "``" << text << "``";
298	0	} else if (first == &link_start) {
299	0	this->OS << line.substr(pos, link_start);
300	0	std::string text = this->InlineLink.match(1);
301	0	bool escaped = false;
302	0	for (char c : text) {
303	0	if (escaped) {
304	0	escaped = false;
305	0	this->OS << c;
306	0	} else if (c == '\\') {
307	0	escaped = true;
308	0	} else {
309	0	this->OS << c;
310	0	}
311	0	}
312	0	pos += this->InlineLink.end();
313	0	} else {
314	0	break;
315	0	}
316	0	}
317	0	this->OS << line.substr(pos) << "\n";
318	0	} else {
319	0	this->OS << line_in << "\n";
320	0	}
321	0	}
322
323		std::string cmRST::ReplaceSubstitutions(std::string const& line)
324	0	{
325	0	std::string out;
326	0	std::string::size_type pos = 0;
327	0	while (this->Substitution.find(line.c_str() + pos)) {
328	0	std::string::size_type start = this->Substitution.start(2);
329	0	std::string::size_type end = this->Substitution.end(2);
330	0	std::string substitute = this->Substitution.match(3);
331	0	auto replace = this->Replace.find(substitute);
332	0	if (replace != this->Replace.end()) {
333	0	std::pair<std::set<std::string>::iterator, bool> replaced =
334	0	this->Replaced.insert(substitute);
335	0	if (replaced.second) {
336	0	substitute = this->ReplaceSubstitutions(replace->second);
337	0	this->Replaced.erase(replaced.first);
338	0	}
339	0	}
340	0	out += line.substr(pos, start);
341	0	out += substitute;
342	0	pos += end;
343	0	}
344	0	out += line.substr(pos);
345	0	return out;
346	0	}
347
348		void cmRST::OutputMarkupLines(bool inlineMarkup)
349	0	{
350	0	for (auto line : this->MarkupLines) {
351	0	if (!line.empty()) {
352	0	line = cmStrCat(' ', line);
353	0	}
354	0	this->OutputLine(line, inlineMarkup);
355	0	}
356	0	this->OutputLinePending = true;
357	0	}
358
359		bool cmRST::ProcessInclude(std::string file, Include type)
360	0	{
361	0	bool found = false;
362	0	if (this->IncludeDepth < 10) {
363	0	cmRST r(this->OS, this->DocRoot);
364	0	r.IncludeDepth = this->IncludeDepth + 1;
365	0	r.OutputLinePending = this->OutputLinePending;
366	0	if (type != Include::TocTree) {
367	0	r.Replace = this->Replace;
368	0	}
369	0	if (file[0] == '/') {
370	0	file = this->DocRoot + file;
371	0	} else {
372	0	file = this->DocDir + "/" + file;
373	0	}
374	0	found = r.ProcessFile(file, type == Include::Module);
375	0	if (type != Include::TocTree) {
376	0	this->Replace = r.Replace;
377	0	}
378	0	this->OutputLinePending = r.OutputLinePending;
379	0	}
380	0	return found;
381	0	}
382
383		void cmRST::ProcessDirectiveParsedLiteral()
384	0	{
385	0	this->OutputMarkupLines(true);
386	0	}
387
388		void cmRST::ProcessDirectiveLiteralBlock()
389	0	{
390	0	this->OutputMarkupLines(false);
391	0	}
392
393		void cmRST::ProcessDirectiveCodeBlock()
394	0	{
395	0	this->OutputMarkupLines(false);
396	0	}
397
398		void cmRST::ProcessDirectiveReplace()
399	0	{
400		// Record markup lines as replacement text.
401	0	std::string& replacement = this->Replace[this->ReplaceName];
402	0	replacement += cmJoin(this->MarkupLines, " ");
403	0	this->ReplaceName.clear();
404	0	}
405
406		void cmRST::ProcessDirectiveTocTree()
407	0	{
408		// Process documents referenced by toctree directive.
409	0	for (std::string const& line : this->MarkupLines) {
410	0	if (!line.empty() && line[0] != ':') {
411	0	if (this->TocTreeLink.find(line)) {
412	0	std::string const& link = this->TocTreeLink.match(1);
413	0	this->ProcessInclude(link + ".rst", Include::TocTree);
414	0	} else {
415	0	this->ProcessInclude(line + ".rst", Include::TocTree);
416	0	}
417	0	}
418	0	}
419	0	}
420
421		void cmRST::UnindentLines(std::vector<std::string>& lines)
422	0	{
423		// Remove the common indentation from the second and later lines.
424	0	std::string indentText;
425	0	std::string::size_type indentEnd = 0;
426	0	bool first = true;
427	0	for (size_t i = 1; i < lines.size(); ++i) {
428	0	std::string const& line = lines[i];
429
430		// Do not consider empty lines.
431	0	if (line.empty()) {
432	0	continue;
433	0	}
434
435		// Record indentation on first non-empty line.
436	0	if (first) {
437	0	first = false;
438	0	indentEnd = line.find_first_not_of(" \t");
439	0	indentText = line.substr(0, indentEnd);
440	0	continue;
441	0	}
442
443		// Truncate indentation to match that on this line.
444	0	indentEnd = std::min(indentEnd, line.size());
445	0	for (std::string::size_type j = 0; j != indentEnd; ++j) {
446	0	if (line[j] != indentText[j]) {
447	0	indentEnd = j;
448	0	break;
449	0	}
450	0	}
451	0	}
452
453		// Update second and later lines.
454	0	for (size_t i = 1; i < lines.size(); ++i) {
455	0	std::string& line = lines[i];
456	0	if (!line.empty()) {
457	0	line = line.substr(indentEnd);
458	0	}
459	0	}
460
461	0	auto it = lines.cbegin();
462	0	size_t leadingEmpty = std::distance(it, cmFindNot(lines, std::string()));
463
464	0	auto rit = lines.crbegin();
465	0	size_t trailingEmpty =
466	0	std::distance(rit, cmFindNot(cmReverseRange(lines), std::string()));
467
468	0	if ((leadingEmpty + trailingEmpty) >= lines.size()) {
469		// All lines are empty. The markup block is empty. Leave only one.
470	0	lines.resize(1);
471	0	return;
472	0	}
473
474	0	auto contentEnd = cmRotate(lines.begin(), lines.begin() + leadingEmpty,
475	0	lines.end() - trailingEmpty);
476	0	lines.erase(contentEnd, lines.end());
477	0	}