diff --git a/bin/doc2rst.php b/bin/doc2rst.php
index 78b456795be..121bc93c6dc 100755
--- a/bin/doc2rst.php
+++ b/bin/doc2rst.php
@@ -73,7 +73,7 @@
$docbook = $opts->getOption('d');
if (!file_exists($docbook)) {
- echo "Error: the docbook file $docbook doesn't exist.\n";
+ echo "Error: the docbook file $docbook doesn't exist." . PHP_EOL;
exit(2);
}
@@ -83,8 +83,8 @@
}
if (is_dir($rstFile)) {
- $rstFile = realpath($rstFile) . DIRECTORY_SEPARATOR;
- $rstFile .= RstConvert::XmlFileNameToRst(basename($docbook));
+ $rstFile = realpath($rstFile) . DIRECTORY_SEPARATOR;
+ $rstFile .= RstConvert::xmlFileNameToRst(basename($docbook));
}
// Load the docbook file (input)
@@ -96,7 +96,7 @@
// Load the XSLT file
$xsl = new \DOMDocument;
if (!file_exists($xsltFile)) {
- echo "The $xsltFile is missing, I cannot procede with the conversion.\n";
+ echo "The $xsltFile is missing, I cannot proceed with the conversion." . PHP_EOL;
exit(2);
}
$xsl->load($xsltFile);
@@ -109,27 +109,33 @@
$output = $proc->transformToXml($xml);
if (false === $output) {
- echo "Error during the conversion\n";
+ echo 'Error during the conversion' . PHP_EOL;
exit(2);
}
// remove single spaces in the beginning of new lines
-$lines = explode("\n", $output);
+$lines = explode("\n", $output);
$output = '';
foreach ($lines as $line) {
- if (empty($line)) {
+ if ($line === '') {
$output .= "\n";
} elseif (($line[0] === ' ') && ($line[1] !== ' ')) {
$output .= substr($line, 1) . "\n";
} else {
- $output .= "$line\n";
+ // Remove trailing spaces
+ $output .= rtrim($line). "\n";
}
}
// Add the list of the external links at the end of the document
-$output .= "\n" . RstConvert::getLinks();
+if(!empty(RstConvert::$links)) {
+ $output .= "\n" . RstConvert::getLinks();
+}
+if(!empty(RstConvert::$footnote)) {
+ $output .= "\n" . join("\n", RstConvert::$footnote);
+}
file_put_contents($rstFile, $output);
-echo "Conversion done.\n";
+echo 'Conversion done.' . PHP_EOL;
exit(0);
/**
@@ -137,106 +143,92 @@
*/
class RstConvert
{
- public static $links = array();
+ public static $links = array();
+ public static $footnote = array();
/**
- * Convert the programlisting tag
+ * Indent a text 4 spaces
*
* @param string $text
- * @param string $language
* @return string
*/
- public static function programlisting($text, $language)
+ public static function indent($text)
{
- $language = ($language)?:'php';
$rows = explode("\n", $text);
- $output = "\n.. code-block:: $language\n :linenos:\n";
+ $output = '';
foreach ($rows as $row) {
- $output .= " $row\n";
+ if ($row === '' || preg_match('/^\s+$/', $row)) {
+ $output .= "\n";
+ } else {
+ $output .= " $row\n";
+ }
}
return $output;
}
/**
- * Convert the note tag
+ * Convert all the section/title, except for the first
*
* @param string $text
+ * @param string $sign decorator character by default paragraph character
+ * @param bool $top put decorator line on top too
* @return string
*/
- public static function note($text)
+ public static function title($text, $sign = '-', $top = false)
{
- $rows = explode("\n", $text);
- $tot = count($rows);
- if ('' !== trim($rows[0])) {
- $output = " **" . trim($rows[0]) . "**\n";
- } else {
- $output = '';
+ $text = trim(self::formatText($text));
+ $line = str_repeat($sign, strlen($text));
+ $output = $text . "\n" . $line . "\n";
+ if ($top) {
+ $output = $line . "\n" . $output;
}
- for ($i=1; $i < $tot; $i++) {
- if ('' !== trim($rows[$i])) {
- $output .= " {$rows[$i]}\n";
- }
- }
- return $output;
+ return "\n" . $output . "\n";
}
/**
- * Convert the listitem tag
+ * Format the string removing \n, multiple white spaces and \ in \\
*
- * @param string $text
+ * @param string $text
+ * @param \DOMDocument[] $preceding previously sibling
+ * @param \DOMDocument[] $following following sibling
* @return string
*/
- public static function listitem($text)
+ public static function formatText($text, $preceding = false, $following = false)
{
- $rows = explode("\n", $text);
- $output = "\n";
- foreach ($rows as $row) {
- if ('' !== trim($row)) {
- $output .= " - ". trim($row) . "\n";
+ $text = self::escapeChars(trim(preg_replace('/\s+/m', ' ', $text)));
+ if (!empty($preceding)) {
+ // Escape whitespace for plurals
+ if (preg_match('/^s\s/', $text)) {
+ $text = '\ ' . $text;
+ } elseif (!in_array($text[0],
+ array('-', '.', ',', ':', ';', '!', '?', '\\', '/', "'", '"', ')', ']', '}', '>', ' '))
+ ) {
+ $text = ' ' . $text;
}
}
- $output .= "\n";
- return $output;
- }
- /**
- * Convert the first section/title tag (maintitle)
- *
- * @param string $text
- * @return string
- */
- public static function maintitle($text)
- {
- $text = str_replace('\\', '\\\\', trim($text));
- $count = strlen($text);
- $output = $text . "\n";
- $output .= str_repeat('=', $count) . "\n";
- return $output;
+ if (!empty($following)) {
+ if ($following[0]->localName == 'superscript') {
+ $text .= '\ ';
+ } elseif (!in_array(substr($text, -1), array('-', '/', "'", '"', '(', '[', '{', '<', ' '))) {
+ // Omitted ':' in the list
+ $text .= ' ';
+ }
+ }
+ return $text;
}
/**
- * Convert all the section/title, except for the first
+ * Escape chars
*
* @param string $text
* @return string
*/
- public static function title($text)
+ public static function escapeChars($text)
{
- $text = str_replace('\\', '\\\\', trim($text));
- $count = strlen($text);
- $output = "\n" . $text . "\n";
- $output .= str_repeat('-', $count) . "\n";
- return $output;
- }
-
- /**
- * Format the string removing \n, multiple white spaces and \ in \\
- *
- * @param string $text
- * @return string
- */
- public static function formatText($text) {
- return str_replace('\\', '\\\\', preg_replace('/\s+/m', ' ', preg_replace('/(([\.:])|^\s([A-Z0-9]))\s*[\r\n]\s*$/', '$2$3', $text)));
+ // Exclude special character if preceded by any valid preceded character
+ return preg_replace('/((([-:\/\'"\(\[\{<\s])([_`\*\|][^\s]))|([_][-\.,:;!?\/\\\'"\)\]\}>\s]))/S', '$3\\\$4$5',
+ str_replace('\\', '\\\\', $text));
}
/**
@@ -256,6 +248,19 @@ public static function link($node)
}
}
+ /**
+ * Convert the footnote
+ *
+ * @param \DOMElement $value
+ * @return string
+ */
+ public static function footnote($value)
+ {
+ $value = self::formatText($value);
+ self::$footnote[] = ".. [#] $value";
+ return '[#]_';
+ }
+
/**
* Get all the external links of the document
*
@@ -297,7 +302,7 @@ public static function table($node)
$i = 0;
foreach ($cols as $col) {
$table[$j][$i] = self::formatText($col->nodeValue);
- $length = strlen($table[$j][$i]);
+ $length = strlen($table[$j][$i]);
if ($length > $widthCol[$i]) {
$widthCol[$i] = $length;
}
@@ -306,12 +311,12 @@ public static function table($node)
$j++;
}
$tableText = new Table\Table(array(
- 'columnWidths' => $widthCol,
- 'decorator' => 'ascii'
- ));
- for ($j=0; $j < $totRow; $j++) {
+ 'columnWidths' => $widthCol,
+ 'decorator' => 'ascii'
+ ));
+ for ($j = 0; $j < $totRow; $j++) {
$row = new Table\Row();
- for ($i=0; $i < $totCol; $i++) {
+ for ($i = 0; $i < $totCol; $i++) {
$row->appendColumn(new Table\Column($table[$j][$i]));
}
$tableText->appendRow($row);
@@ -319,9 +324,9 @@ public static function table($node)
$output = $tableText->render();
// if thead exists change the table style with head (= instead of -)
if ($head) {
- $table = explode("\n", $output);
+ $table = explode("\n", $output);
$newOutput = '';
- $i = 0;
+ $i = 0;
foreach ($table as $row) {
if ('+-' === substr($row, 0, 2)) {
$i++;
@@ -333,7 +338,7 @@ public static function table($node)
}
return $newOutput;
}
- return $output;
+ return $output . "\n";
}
/**
@@ -343,15 +348,15 @@ public static function table($node)
* @param string $name
* @return string
*/
- public static function XmlFileNameToRst($name)
+ public static function xmlFileNameToRst($name)
{
if ('.xml' === strtolower(substr($name, -4))) {
- $name = substr($name, 0, strlen($name)-4);
+ $name = substr($name, 0, strlen($name) - 4);
}
- $tot = strlen($name);
+ $tot = strlen($name);
$output = '';
- $word = false;
- for ($i=0; $i < $tot; $i++) {
+ $word = false;
+ for ($i = 0; $i < $tot; $i++) {
if (preg_match('/[A-Z]/', $name[$i])) {
if ($word) {
@@ -366,6 +371,18 @@ public static function XmlFileNameToRst($name)
$word = true;
}
}
- return $output.'.rst';
+ return $output . '.rst';
+ }
+
+ /**
+ * Convert an XML file name to the RST ZF2 standard naming convention
+ * For instance, Zend_Config-XmlIntro.xml become zend.config.xml-intro.rst
+ *
+ * @param string $href
+ * @return string
+ */
+ public static function imageFileName($href)
+ {
+ return '../images/' . basename($href);
}
}
diff --git a/bin/doc2rst.xsl b/bin/doc2rst.xsl
index 6dbd07b2f82..ae06c6f6775 100644
--- a/bin/doc2rst.xsl
+++ b/bin/doc2rst.xsl
@@ -1,119 +1,343 @@
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ version="1.0">
-
+
+
+
+
+
+
-
-
-
+
+
.. _:
-
-
-
-
-
+
-
-
-
-.. _:
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
+
+
+
+
-
-
-
-
+
+
+
+
+
+
-
-
-
+
+
+
+
+
+
+
+
+
+
-.. include::
+.. include::
-
-````
+
+
+````
+
-
-**
+
+**
+
-
-****
+
+****
+
-
-
-
+
+(tm)
+
+
+
+(c)
+
+
+
+:sup:``
+
+
+
+:t:``
+
+
+
+
+
+ |
+
+
+
+
+
+
+::
+
+
+
-
+
+
+.. code-block::
+ :linenos:
+
-
-
-
+
+
+
+
+ .. code-block::
+ :linenos:
+
+
+
+
+
+****
+
+
+
+
+
+
+ ****
+
+
+
+
+
+
.. _:
-
-****
+
-
- ``()``
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.. c:function:: ()
+
+
+
+
+
+
+
+ ****
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+-
+
+
+
+
+ -
+
+
+
+
+
+.
+
+
+
+
+ .
+
+
+
+
+
+
+
+
+.. ::
+ ****
-
+
-
-
-
+
+
+
+
+ .. ::
+ ****
+
+
+
+
-
-
-.. note::
- ****
+
+
+.. image::
+
+ :width:
- ****
+
+ :align:
+
+
+
+ .. image::
+
+ :width:
+
+
+ :align:
-
-
-
-
-.. _:
+
+
+
+.. table::
+
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/documentation/manual/en/tutorials/view-placeholders-standard.xml b/documentation/manual/en/tutorials/view-placeholders-standard.xml
index ad045bd2421..ae9e03ae326 100644
--- a/documentation/manual/en/tutorials/view-placeholders-standard.xml
+++ b/documentation/manual/en/tutorials/view-placeholders-standard.xml
@@ -441,7 +441,7 @@ site = {
- You can render your headScript() tag whereever you
+ You can render your headScript() tag wherever you
like in your layout script; just because the title references "head" does
not mean it needs to be rendered in that location.