[prev in list] [next in list] [prev in thread] [next in thread]
List: smarty-dev
Subject: [SMARTY-DEV] what's up with smarty/docs ?
From: 81.57.128.152
Date: 2004-03-29 11:54:24
Message-ID: 40680E70.5090203 () keliglia ! com
[Download RAW message or body]
Hi folks,
Just a little summary of the work accomplished by Nuno and I during the
last weeks.
1) - created a phpdoc-like build system :
- added the ./configure & make stuff
- added an entities/global.ent file containing the general entities
- created a "en" directory and moved english files there
- renamed all the files from .sgml to .xml
2) - fixed dockbook syntaxes :
- escaped some special chars like & => &
- switched from <functionsynopsis> to <methodsynopsis> in some files to
fix build
- added toons of roles for programlistings, added CDATA sections,
unescaped HTML encoding in CDATA (it's safe now)
3) - splits :
- splitted programmers.xml, designers.xml and appendices.xml by chapters
. Here's how the "en" directory looks like now :
.
|-- CVS
| |-- Entries
| |-- Repository
| |-- Root
| `-- Template
|-- appendixes
| |-- CVS
| | |-- Entries
| | |-- Repository
| | |-- Root
| | `-- Template
| |-- bugs.xml
| |-- resources.xml
| |-- tips.xml
| `-- troubleshooting.xml
|-- bookinfo.xml
|-- designers
| |-- CVS
| | |-- Entries
| | |-- Repository
| | |-- Root
| | `-- Template
| |-- chapter-debugging-console.xml
| |-- config-files.xml
| |-- language-basic-syntax.xml
| |-- language-builtin-functions.xml
| |-- language-combining-modifiers.xml
| |-- language-custom-functions.xml
| |-- language-modifiers.xml
| `-- language-variables.xml
|-- getting-started.xml
|-- language-defs.ent
|-- preface.xml
`-- programmers
|-- CVS
| |-- Entries
| |-- Repository
| |-- Root
| `-- Template
|-- advanced-features.xml
|-- api-functions.xml
|-- api-variables.xml
|-- caching.xml
|-- plugins.xml
`-- smarty-constants.xml
Why did we do it ? I remember when I tried to translate smarty's docs to
french last year, it was a pain in the ass. This will help new
translations and keeping the already translated files in sync easy.
BTW, I think we'll split others files (especially under programmers/ and
designers/)
4) - Added smarty to livedocs
Here's how I build the smarty manual now on my box :
didou@keliglia:~/cvs/livedocs$ ./configure --with-build-log=log.txt
--with-docs=/home/user/didou/cvs/smarty/docs
--with-output-dir=/home/user/didou/www/didou/php/livedocs-smarty
--with-build-type=smarty --with-web-base=/php/livedocs-smarty/
--with-languages="en fr de pt_BR"
Here's the result (english language only) :
http://didou.keliglia.com/php/livedocs-smarty/index.php?l=en&q=manual
The build process is really fast :
< messju> the build.sh takes ~8 seconds for 4 languages. but it's only a
celeron 533 mhz
5) - Various stuff
* fixed a big mess with french accents
* changed the ugly programlisting with modifiers of date_format to a
nice <itemizedlist>
6) - TODO
it's never over ;) here's a quick TODO that I'll commit to smarty/docs/,
there's two categories :
*normal mode* :
- add a PHP script that will generate dynamically all the files entity
in manual.xml
- add CDATA sections in all programlistings.
- add roles to programlisting (especially role="php") and add PHP tags
in PHP examples (short_open_tag is banned). This will help to :
-- colorize examples
-- check parse errors : for i in $(ls |grep xml); do php -d
short_open_tag=off -l $i; done
*pedentic mode* :
- fix indenting in all .xml files : don't uses tabs, indent by a space.
Here's a nice indentation :
<para>
<example>
<title />
<programlisting>
<![CDATA[
// ..
]]>
</programlisting>
</example>
</para>
- clean all the examples :
(if aggreed) examples should be XHTML compliant and should stick to
PEAR's coding standards.
Here's how a complete example, using PHP and templates, should be written :
<example>
<title>html_image example</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->display('index.tpl');
?>
]]>
</programlisting>
<para>
where index.tpl is:
</para>
<programlisting>
<![CDATA[
{html_image file="pumpkin.jpg"}
]]>
</programlisting>
<para>
a possible output would be:
</para>
<screen>
<![CDATA[
<img src="pumpkin.jpg" alt="" border="0" width="44" height="68" />
]]>
</screen>
</example>
7) - questions :
* may someone take care of smarty's theme for livedocs ?
8) - conclusions :
a big "thank you" to Nuno, he helped with the build process.
and thank you all for your great mood ! First time I don't get blamed
when screwing up docs ;)
Hope you'll enjoy it !
Mehdi Achour
--
Smarty Development Mailing List (http://smarty.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic