I really like HTML documentation instead PDF one in early stage of framework. Why? When I’m downloading nightly version from SVN, it is easy way to see what was changed in documentation in latest time. I suggest to include (maybe separated) documentation available there into SVN.
the guide IS in SVN (/doc/guide). It's in markdown format though.
I've seen this doc. Fine, but how can browse this as HTML? Is there any tool or how can I convert this into HTML? I still prefer this nice HTML instead markdown format
yes, there's tool in /build directory that can convert this format to either HTML or PDF.
Quote
Will you find a second to point me how to covert the user guide to HTML?
Sorry, I was too fast. The tool only converts the Guide to PDF.
In order to convert it to HTML, you need to use the included CMarkdownParser, and this is used by the project website as well.
Try, save it as docs/guide.php
<!--
Renders the guide similar to that found at http://www.yiiframework.com/doc/guide/
$Id$
-->
<style>
.php-hl-identifier{color:green}.php-hl-reserved{color:black;font-weight:700}
.php-hl-var{color:blue}ol.php-hl-main pre{margin:0;padding:0}.html-hl-default,
.php-hl-default{color:Black}.html-hl-code,.php-hl-code{color:Gray}
.html-hl-brackets,.php-hl-brackets{color:Olive}.html-hl-comment,
.php-hl-comment{color:gray;font-style:italic}.html-hl-quotes,
.php-hl-quotes{color:red}.html-hl-string,.php-hl-string{color:Red}
.html-hl-builtin,.php-hl-builtin{color:Teal}.html-hl-reserved{color:Green}
.html-hl-var{color:#000020}.html-hl-special,.php-hl-special{color:Navy}
.html-hl-number,.php-hl-number{color:Maroon}.html-hl-inlinetags,.html-hl-url,
.html-hl-inlinedoc,.html-hl-identifier,.php-hl-inlinetags,.php-hl-url,
.php-hl-inlinedoc{color:Blue}.content,.toc{font-family:Calibri, Helvetica, Arial, sans-serif}
.toc{float:left;width:250px}.content{text-align:justify;padding-left:20px;
vertical-align:top;margin-left:255px;width:650px;font-size:11pt}
pre{display:block;padding:1em;background:#fcfcfc;border-top:1px solid #eee;
border-bottom:1px solid #eee;font-family:Consolas, "Courier New", Courier, mono;
margin:1em 0;font-size:10pt}code{border-bottom:1px dotted #ccc;font-weight:700;
color:#666}div.revision{font-size:.8em;color:#999;margin-top:5em}blockquote.tip,
blockquote.info,blockquote.note{border-top:1px solid #0cf;border-bottom:1px solid #0cf;
padding:0 1em;margin:1em 0;border-color:#E4DFB8}blockquote.note{background-color:#FFE6E6;
border-color:#D9C3C3}blockquote.info{border-color:#B4DAA5;background-color:#EBFFCE}
span.type{float:left;font-size:1em;padding-right:.5em;font-weight:700}
</style>
<?php
require_once(dirname(__FILE__).'/../framework/yii.php');
require_once(dirname(__FILE__).'/../build/commands/GuideLatexCommand.php');
require_once(dirname(__FILE__).'/../build/commands/guideLatex/MarkdownParser.php');
function renderToc()
{
$guideCmd = new GuideLatexCommand('','');
$toc=$guideCmd->getGuideTopics();
$s='';
foreach($toc as $hd => $topics)
{
$s .= "<strong>{$hd}</strong><ul>";
foreach($topics as $link=>$title)
$s .= "<li><a href='?p={$link}'>{$title}</a></li>";
$s .= '</ul>';
}
return $s;
}
function renderPage()
{
$uri = isset($_GET['p']) ? $_GET['p'] : 'index';
$guideCmd = new GuideLatexCommand('','');
$sourcePath=$guideCmd->getGuideSourceDir();
$file=realpath("{$sourcePath}/{$uri}.txt");
if($file !== null && is_file($file))
{
$parser=new MarkdownParser;
$content=$parser->transform(file_get_contents($file));
$replace=array
(
'href="/doc/guide/' => 'href="?p=',
'src="' => 'src="guide/images/',
'/doc/api/' => 'http://www.yiiframework.com/doc/api/',
);
return str_replace(array_keys($replace), array_values($replace), $content);
}
}
?>
<div class="toc"><?php echo renderToc(); ?></div>
<div class="content"><?php echo renderPage(); ?></div>
Thx a lot Wei, karma++
Working on translating the Guide I noticed the docs/guide.php script need to have the meta charset="utf-8" directive added, or the browser's charset seems to be randomly selected.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style>
.php-hl-identifier{color:green}.php-hl-reserved{color:black;font-weight:700}
...
span.type{float:left;font-size:1em;padding-right:.5em;font-weight:700}
</style>
</head>
<?php
require_once(dirname(__FILE__).'/../framework/yii.php');
require_once(dirname(__FILE__).'/../build/commands/GuideLatexCommand.php');
require_once(dirname(__FILE__).'/../build/commands/guideLatex/MarkdownParser.php');
function renderToc()
...
function renderPage()
...
'/doc/api/' => '../api/',
...
?>
<body>
<div class="toc"><?php echo renderToc(); ?></div>
<div class="content"><?php echo renderPage(); ?></div>
</body>
</html>
As a really quick workaround, to see the result of my translation, I actually added the directorys, docs-sv and build/commands/guideLatex/output-sv. Thus, I can easily compare the translated version to the original.
Changes:
In docs-sv/guide.php:
require_once(dirname(__FILE__).'/../build/commands/GuideLatexCommand-sv.php');
In build/commands/GuideLatexCommand-sv.php:
function getGuideSourceDir() {
return dirname(__FILE__).'/../../docs-sv/guide';
}
function getOutputDir() {
return dirname(__FILE__).'/guideLatex/output-sv';
}
With new Yii were delivered some changes in structure and with method names. Therefore script pasted by Wei need to be changed to following
<!--
Renders the guide similar to that found at http://www.yiiframework.com/doc/guide/
$Id$
-->
<style>
.php-hl-identifier{color:green}.php-hl-reserved{color:black;font-weight:700}
.php-hl-var{color:blue}ol.php-hl-main pre{margin:0;padding:0}.html-hl-default,
.php-hl-default{color:Black}.html-hl-code,.php-hl-code{color:Gray}
.html-hl-brackets,.php-hl-brackets{color:Olive}.html-hl-comment,
.php-hl-comment{color:gray;font-style:italic}.html-hl-quotes,
.php-hl-quotes{color:red}.html-hl-string,.php-hl-string{color:Red}
.html-hl-builtin,.php-hl-builtin{color:Teal}.html-hl-reserved{color:Green}
.html-hl-var{color:#000020}.html-hl-special,.php-hl-special{color:Navy}
.html-hl-number,.php-hl-number{color:Maroon}.html-hl-inlinetags,.html-hl-url,
.html-hl-inlinedoc,.html-hl-identifier,.php-hl-inlinetags,.php-hl-url,
.php-hl-inlinedoc{color:Blue}.content,.toc{font-family:Calibri, Helvetica, Arial, sans-serif}
.toc{float:left;width:250px}.content{text-align:justify;padding-left:20px;
vertical-align:top;margin-left:255px;width:650px;font-size:11pt}
pre{display:block;padding:1em;background:#fcfcfc;border-top:1px solid #eee;
border-bottom:1px solid #eee;font-family:Consolas, "Courier New", Courier, mono;
margin:1em 0;font-size:10pt}code{border-bottom:1px dotted #ccc;font-weight:700;
color:#666}div.revision{font-size:.8em;color:#999;margin-top:5em}blockquote.tip,
blockquote.info,blockquote.note{border-top:1px solid #0cf;border-bottom:1px solid #0cf;
padding:0 1em;margin:1em 0;border-color:#E4DFB8}blockquote.note{background-color:#FFE6E6;
border-color:#D9C3C3}blockquote.info{border-color:#B4DAA5;background-color:#EBFFCE}
span.type{float:left;font-size:1em;padding-right:.5em;font-weight:700}
</style>
<?php
require_once(dirname(__FILE__).'/../framework/yii.php');
require_once(dirname(__FILE__).'/../build/commands/GuideLatexCommand.php');
require_once(dirname(__FILE__).'/../build/commands/markdown/MarkdownParser.php');
function renderToc()
{
$guideCmd = new GuideLatexCommand('','');
$toc=$guideCmd->getGuideTopics();
$s='';
foreach($toc as $hd => $topics)
{
$s .= "<strong>{$hd}</strong><ul>";
foreach($topics as $link=>$title)
$s .= "<li><a href='?p={$link}'>{$title}</a></li>";
$s .= '</ul>';
}
return $s;
}
function renderPage()
{
$uri = isset($_GET['p']) ? $_GET['p'] : 'index';
$guideCmd = new GuideLatexCommand('','');
$sourcePath=$guideCmd->getSourceDir();
$file=realpath("{$sourcePath}/{$uri}.txt");
if($file !== null && is_file($file))
{
$parser=new MarkdownParser;
$content=$parser->transform(file_get_contents($file));
$replace=array
(
'href="/doc/guide/' => 'href="?p=',
'src="' => 'src="guide/images/',
'/doc/api/' => 'http://www.yiiframework.com/doc/api/',
);
return str_replace(array_keys($replace), array_values($replace), $content);
}
}
?>
<div class="toc"><?php echo renderToc(); ?></div>
<div class="content"><?php echo renderPage(); ?></div>