what's up with smarty/docs ?

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