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