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 & => &amp; - 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