Invenzzia... in English - Tag - documentation

Open Power Template 2.1 almost finished

Zyx — Mon, 01 Nov 2010 20:06:00 +0100

Works on Open Power Template 2.1, the greatly extended successor of OPT 2.0 are almost finished. I know it was a long year, but finally we reach a point where we can plan our next steps and think, what to do next. The current package will be soon packed as OPT 2.1-BETA2, and the remaining functionality will appear as a part of the first Release Candidate.

What is not finished yet?

Basically speaking, there are three things left to do:

Implement Opt_Format_NestedTree data format for opt:tree instruction which will allow to push a nested array in order to render a valid HTML tree.
Finish the migration module which will allow to run OPT 2.0 templates and convert them on-the-fly to the new release.
Finish the support for opt:append and opt:prepend tags in opt:switch instruction in order to make possible to add dynamic attributes in this way.

The list of implemented features and changes is really impressive. Just a quick look at the code repositories of 2.0 and 2.1 branch can tell us that OPT 2.1 is another revolution, with many clean-ups and improvements.

Further release process

Unfortunately, in order to see a stable release of OPT 2.1, we still need some time. Although I test the new branch in different situations and environments, including real projects, the debugging process is not finished yet. The test code coverage is not as high as I'd like and it needs to change. Another critical issue is the new documentation, where the progress is very low.

Plans

I'll do my best to release OPT 2.1 stable before February 2010, because that month I expect to start works on Open Power Template 3. Lots of things have changed in the PHP world last time, especially where it comes to the frameworks and the application design theory. Open Power Libs 2 was a pioneer in several library design concepts, such as universal autoloader or the need for a small, unified core, but its internal structure and design does not meet current code quality standards. Open Power Template 2 suffers from the same issue. Other development teams from such projects, as Doctrine and Symfony, have already started works on improving them, and so must we.

So, what is the exact plan for Open Power Template and Open Power Libs 3? The overall project philosophy will remain the same, which means that if you already know how to use OPT 2.x, you should not have any problems with 3.x. I plan not to make significant changes to the template language, because it has already been polished in the current releases. We will still use good, old XML syntax, sections, switches, components, etc. The only key goal is to make the language fully secure. It means that from the template level, it should not be possible to cause neither PHP fatal, parse error nor access any forbidden function and class.

The main revolution will take place in the library programming interface. The OPL core will use some third party components:

Symfony 2 Event Dispatcher
Symfony 2 Console

Furthermore, there will be fewer components:

the universal autoloader,
configuration object,
error handler,
debugging interface.

Open Power Template 3 public API will be more compact. I very like the job the guys from Doctrine did in Doctrine 2 project and I'd like to do the same with my library. The API should be simple and intuitive, there should be no magic, and the dependency injection should be done explicitely. The registry and the static stuff will be thrown away.

I'd also like to make the compiler itself completely independent from the standard public API which should allow to use it without it. Its API will be also polished, especially when it comes to data formats, instructions and extending. Here, the following things are going to be implemented:

data formats will be composed of simple PHP interfaces, which should simplify the entire API and ease the data format building.
the compiler will make a good use of the reflection mechanism to find out what a particular class provides.
function packages will simplify installing new template function sets.
the compiler internals will be separated from the concrete template language implementation - all the languages, including the default one, will be installed by registering a new language class object in the compiler.

The expected result is simple: the most advanced, the most powerful, the fastest, the one, where writing templates is also the fastest, and the greatest template engine in the world. Ever.

Invenzzia Summary #5

Zyx — Wed, 08 Jul 2009 13:28:00 +0200

Welcome back after a short break. Although there were no summaries in the last month, Invenzzia projects are still active and maintained. We have released two new versions in June, and now we are reaching the moment of releasing... the first stable version of Open Power Template 2! Stay with us and read more about the progress and the current status of the projects.

Open Power Template 2

The project is actually finished and we are expecting to deal with all the formalities in the next few days. There is only one chapter missing in the user documentation and if you would like to check the code right now, you can find it on our Subversion repository. So, what would take so long? The answer is simple: the tutorials. Since April, I have been working on a huge article entitled "A photogallery with Doctrine and Open Power Template 2.0" showing the process of writing a web gallery using the libraries mentioned in the title. Furthermore, it is going to be available in two language versions: Polish and English. We have to finish the translation and rewrite it into Markdown, so that it could be published on Invenzzia. Anyway, the development process is over and now we can focus on implementing the new features and the new libraries.

TypeFriendly 0.1.2

A couple of weeks ago, we released TypeFriendly 0.1.2 with many new features, such as appendix support and tag manager. Since then, there were new commits and new works-in-progress. eXtreme improves the layout of the chapter headers, there are expected new tags and fixed some minor bugs.

What's next?

I plan to finish the caching system for OPT that will be distributed with Open Power Classes, and start developing the source code of long-awaited Open Power Forms. We have an idea, what we want to get and how to achieve the goals.

Wiki.invenzzia.org

Zyx — Sun, 08 Feb 2009 17:06:00 +0100

Our new wiki is available on-line now. I've been working for last few days to customize it and add the necessary extra functionality. However, there is still a lot to do. As you can notice, there must be added many technical templates, help pages and some navigation structure. I hope I'll manage to deal with it in the nearest days. The wiki is intended to keep community-driven materials on our open-source projects, as well as extra information on add-ons, such as framework ports. Feel free to share your solutions with everyone - you need only the discussion board account and some knowledge on MediaWiki syntax.

New days for international Invenzzia

Zyx — Sat, 20 Sep 2008 17:31:00 +0200

Recently we found that developing Invenzzia projects in bilingual way was a big mistake. As you can probably see, the result is that for example OPL is now closed for programmers that do not live and work in Poland, even if it is a quite nice country with beautiful language. Since now, it is going to change. We understand that English language simply gives us more profits and we want to correct our mistakes. So, what changes are expected?

The documentation for the most complete development project, Open Power Template, is still written mostly in Polish. The translation is one of our goals.
The news, articles, etc. will be published in English first.
The English forums will we promoted.

This will take some time, as we have also our private lifes and other things to do. However, please give us some time and be patient. We are not afraid of foreign users and we think we can deal with it.

TypeFriendly

Zyx — Wed, 02 Jul 2008 21:38:00 +0200

Together with eXtreme, we work hard to make the first release available as soon as possible and we are quite close now. This is a perfect opportunity to tell something more about this project, which should be appreciated by those programmers who write their own scripts and libraries and look for a smart tool to make a documentation. The idea to write TypeFriendly was born in my head after I failed to add some necessary things to the XSLT sheets for DocBook. The PHP manual shows, what could be done with it (syntax coloring, lots of different formats, enormous amount of tags), but don't become too happy too fast. To achieve similar effects, we need weeks of coding and we must also fight against the portability. In fact, I'd rather use those weeks to write something more useful and friendly.

So, TypeFriendly is a documentation writing tool, but it works differently than for example phpDocumentor which scans the source code of your project and makes a reference list of all classes and functions. Here, we write all the chapters and put them in the required order on our own, like in DocBook. However, in this place the similarities end, because TF already contains everything we need. Moreover, it was designed to be intuitive and easy to learn.

Features:

In TF, we write our manual in standard text files using the Markdown syntax. We can put some extra information with tags placed at the beginning of the file. They allow us to define a title, version information or "See also" section.
TF automatically sorts our files and connects them into bigger chapters, basing on their file names. By default, all the content is sorted alphabetically, but we can easily change it for all the files we need. We just create an additional file with "sorting hints", where we write the required order.
There is a built-in syntax highlighting option.
TF generates all the navigation and table of contents.
TF is designed to create a multilingual documentation. Apart from storing many versions of the same file and interface texts, it contains a simple tool to detect whether the "derived language versions" are up-to-date.
TF allows to generate the XHTML version very quickly, on a single page, as well as on many. We are also creating a special format for importing the manual to the database (to publish it online and for example, to add user comments).
TF packs your manual by default in the nice, green layout.

Although there haven't been any release so far, you can always connect to our new SVN and download the code from there. The link to the checkout commands is: http://svn.invenzzia.org/svn/typefriendly/trunk/ - we encourage you to test the script now. In the repository, there is a README file and a nearly finished Polish version of the TF manual. But don't worry. The first release will be available with the English version, too. It's much shorter than OPL manual, and nice to translate :).

Now, I think it's a good idea to show an example. The first one would be one of the files from OPT template engine manual that we develop, too:

Title: optNode class
ShortTitle: optNode
Status: abstract
Extends: library.optcodebuffer
ExtendedBy:
 - library.optscannable
 - library.optcharacterdata
 - library.optexpression

----
An abstract XML node class. It provides the basic support for the most important features, such as type and parent.

Class fields
------------
All the fields are protected.

 Name          | Type      | Description
---------------|-----------|---------------------------------------
 $type         | Integer   | Numerical type identifier
 $parent       | optNode   | Node parent

Available type identifiers:

1. `OPT_CDATA_NODE` - `optCharacterData`
2. `OPT_TEXT_NODE` - `optText`
3. `OPT_EXPRESSION_NODE` - `optExpression`
4. `OPT_ELEMENT_NODE` - `optElement`
5. `OPT_ROOT_NODE` - `optRoot`

At the beginning, we have a header with tags. There we define the exact title, and in this case also the dependencies between the PHP classes. Notice that we refer to the other classes by writing the identifier of the chapter, where they are described. Of course, there are additional tag versions, where we can write the class names directly, for example if we inherit from some PHP built-in class. There are more available tags. Let's say we want to make a "See also" section:

SeeAlso:
 - chapter.text1
 - chapter.text2
 - chapter.text3

Once the tag list finishes, we begin the exact content in the Markdown format. The author designed it basing on the formatting used in text files and e-mails (it can be said that he wrote a parser for a syntax that self-evolved :)). This means that the source text is really clean and easy to read. In fact, it is just a bit lesser comfortable than a parsed one. The problem is, if someone is accustomed to some wiki syntax, because MD not always works in this way (take a look at the table). But it is quite easy to switch. We use Markdown even on our website and I must say that it is a very convienient tool. I'm sure you'll find it in more Invenzzia products. There is only one big shortcoming - the only available output is XHTML. For now, you have to forget about LaTeX and the rest, but I can assure you that we plan to add it, too.

The most frustrating problem while writing a manual is navigation. The links "Previous", "Next", "Up" are added by TypeFriendly, we create the "See also" section by adding a tag, but what about clickable function and class names? I thought about it a bit and I invended a brilliant and simple idea. We have an additional text file, where we define, what text points to what. For example, we write there that `optClass::parse()` must always be a link to library.optclass.parse and that's all. Unfortunately, we haven't hacked Markdown in this way so far and the first release will not contain it yet.

TypeFriendly works in the operating system command line. We've tested it both on Linux and Windows and it works there without any problems. All we need is a PHP parser. Togethet with a simple syntax and built-in multilingual support, TF should encourage much more people to help in translations of your manuals, improving the base version and maybe even writing new outputs. Generating the XHTML version is really easy:

php ./typefriendly.php -l en -o xhtml ./path/to/manual/

Let's compare it to DocBook. The format itself is a bit longer, but relatively easy to learn. However, the conversion needs more tools. We must download the DTD, DocBook XSL Stylesheets and an XSTL parser. The choice is important, because fast and easy xsltproc will not highlight your syntax in the examples. On the other hand, the Windows users are f@#$ off if the author decides to write half of the processing tools in Bash. We don't have to look such examples too far. Just take a look at the PHP manual. Guess, what is it written in? :)