Invenzzia... in English - Tag - typefriendly

Invenzzia goes to github

Zyx — Wed, 26 May 2010 13:42:00 +0200

So far, our projects have been hosted with Subversion control system installed on our own servers. While it is quite convenient and we are not limited by resources, it causes some problems with authentication and simplifying access for users that wish to help us developing our projects. In the last days, we have been discussing on that and decided to switch to Git. In the near future, all the projects will migrate to Github which will become our official hosting platform. I hope it will make the collaboration much easier.

Note that one of our projects has already been ported to Github - TypeFriendly. The others, including OPL will migrate in the next weeks, as this requires from us some effort and time. Basically, we have some scripts that help us publishing new versions and they must be rewritten from SVN to Git.

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.

Invenzzia Summary #4

Zyx — Wed, 20 May 2009 15:04:00 +0200

Welcome to the fourth episode of Invenzzia Summaries. The issues discussed today:

Incoming TypeFriendly 0.1.2 release
Revised plans for 0.2 branch of TypeFriendly
Open Power Classes
Release plan for Open Power Template

Incoming TypeFriendly 0.1.2 release

Before the end of May 2009, Invenzzia is going to release TypeFriendly 0.1.2, a HTML documentation builder with Markdown syntax. It will contain some new features and improvements that can be currently found in the SVN repository:

New tag manager that validates the contents and use of the tags in the chapters.
Support for creating appendices added.
New tags:
- MultiExtends - specifying the base classes for languages with multiple inheritance
- Throws - thrown exceptions.
- Construct - specifying the type of described programming construct (classes, interfaces etc.)
- Type - specifying the item type
- Arguments - specifying and describing the function arguments
- Returns - describing, what the function returns.
- VCSKeywords - a place for expanding SVN keywords that can be also optionally displayed in the output.
- Appendix - support for appendices
- FeatureInformation - allows to define a messages in the project configuration that may be later prepended to the chapters.
Improved command-line interface. The usage has been changed (please take a look at the details on wiki)
New book creation wizard.

The release will also fix some bugs found in the previous release.

Plans for TypeFriendly 0.2

The release of TypeFriendly 0.2.0 has been moved further to the future (Summer 2009) due to the recent revision of the goals. The new TypeFriendly will consist of three parts:

TypeFriendly library - the documentation management functionality will be collected into a library independent from the command-line interface code that can be used by the programmers to include the TypeFriendly documenting system features into their project.
Command-line interface - build with TypeFriendly library will provide the features similar to the current TypeFriendly 0.1 release.
Web interface - since 0.2.0, you will be able to install TypeFriendly web interface on your website to run a public documentation repository with automatic uploaders, user comments etc. This feature is addressed especially to the developer teams that wish to publish the on-line documentations for their products.

TypeFriendly 0.2 will use Open Power Template both to render the static documents and in the web interface. The Markdown parser will be expanded with new features, such as mathematical formulas support. However, generating the documents in other formats than HTML will not be still possible, as we need to design our own Markdown parser and this is a longer-term goal.

Open Power Classes

The development of Open Power Classes slowly begins. eXtreme added a nice paginator class with OPT support, and I am working on the native caching system for OPT that will be available as Opc_Cache. Open Power Classes is going to be a collection of small utility classes to support other libraries.

Release plan for Open Power Template

There will be another Release Candidate version, as there have been found some small, but annoying bugs in the parser. The first stable version will be released in the first half of June then.

They wrote about...

Last Saturday, a nice note about TypeFriendly was published by Federico Cargnelutti on his blog. We are looking forward to the next publications about Invenzzia projects.

What's new on Invenzzia?

Zyx — Sun, 22 Mar 2009 10:12:00 +0100

Hi everyone, in the last few days, we had a lot of work around Invenzzia and its projects. In this entry I would like to inform, what currently is going on. We will talk about OPT 2, TypeFriendly, our new website and the activity in open source project trackers.

Open Power Template 2

A few minutes ago, I have commited a quite big revision, an effect of four coding days. In this time I solved a number of problems:

I decided to reimplement the whole section handling code from scratch, because the old one had a significant problem with handling custom section attributes that I was unable to fix with the old design. The new code is much cleaner, simpler and seems to be more stable. To check it, I wrote more that 20 new unit tests to check various edge conditions and integration with other instructions. From the end-user side, you should see no difference and the old code should be still 100% functionable.
At the same time, I finally cleaned and "standarized" the data format structure. The definitions of the five default data formats have been improved, too. There is a small change that could break the backward compatibility - the "Generic" format has been renamed to "Array" to reflect its real nature. Unless you declared the use of this format explicitly, your code should still work.
Another, quite big part of PHP code was equipped with phpdoc and more comments. If you are using a good IDE, like NetBeans or Eclipse PDT, they should show you the complex information about much wider variety of OPT methods.
A number of bugs was fixed.

Significant improvements have been applied to the user manual, too. The API reference was moved to the bottom and the more practical chapters were exposed. I decided to create a new section, "Programmer's guide" that aims to be a complete guide over OPT API issues and its practical usage. It incorporated the old "API issues" chapter. The currently written parts show us, how to start and explain:

The initialization process.
Using views.
Using output systems.
Exception and error handling
Data formats
Internationalization
HTML escaping.

The user manual can be read here.

TypeFriendly 0.1.1

A week ago, Invenzzia has released TypeFriendly 0.1.1 with a number of bugfixes found since the first release. Currently, we are focusing on TypeFriendly 0.2 and we will try to release it much sooner :).

New Invenzzia Website

Finally, we are almost ready to launch our brand new website and replace the current temporary one. Yesterday, eXtreme ran it experimentally on our server and now tests it and implements the last remaining features. The website is equipped with a new design and logo (you can already see it on our wiki). It improves the navigation a lot and shows much more useful stuff to the visitors. I hope we will see it online in the next few days.

OPT on Ohloh.net

A few days ago, I created the profile of "Open Power Template 2" on Ohloh.net website. Currently, you can find there some links, a journal of the recent works and the code statistics. We encourage everyone that have an accoun on Ohloh and use OPT to track this project and vote for it :).

TypeFriendly 0.1.0 released

Zyx — Wed, 23 Jul 2008 10:34:00 +0200

At last, the translation of the manual into English is complete and the source code has been already released as the first version of TypeFriendly, the documentation generator. In is available in Files on the main site. The user manual is provided in the source form and it works also as an example, so please do not worry that something is missing. All the necessary information to build the HTML version can be found in /info/README.txt file. All you need is to type one command in the system console. The on-line documentation will be available soon, as we are preparing new website. To get more information about TypeFriendly, take a look at the previous note.

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? :)