Invenzzia » Resources / Articles / TypeFriendly quickstart

TypeFriendly quickstart

  • Published on 19 May 2009 12:35:00 GMT, updated over 5 years ago by Tomasz Jędrzejewski

This is a quick start guide for the new users of TypeFriendly that wish to start their own HTML book.

TypeFriendly is an open-source HTML book and user manual generator. It was designed to be easy-in-use and provide the necessary tools to set up and manage a new project. Contrary to other solutions, such as DocBook, you do not need to implement the basic functionality, like modular design or syntax highlighting on your own. TypeFriendly gives you them out-of-box.

In this quick start guide we will show, how to write an user manual with simple API reference in TypeFriendly for a dummy project.

Installation

In order to use TypeFriendly, you must have a PHP5 parser installed. Pure PHP is extremely easy to install. On the Linux systems, all you have to do is to use your package manager. Under Windows, you must visit www.php.net website and download the latest PHP 5.x version. Extract the ZIP archive somewhere on your hard drive and go to the Control Panel. Then modify the system variable PATH to point to the directory with php.exe file. To test your installation you can write a simple script:

<?php phpinfo() ?>

And run it from the console:

php script.php

If you see a lot of technical details concerning PHP, you are at home.

TypeFriendly itself can be downloaded from the www.invenzzia.org website. The archive must be extracted somewhere to your hard drive. TF is a command-line application and the simplest way to check whether it works is to build its own documentation from the source:

cd Dir/With/TypeFriendly
php typefriendly.php -l en -o xhtml "./docs"

If everything goes well, you should find an XHTML documentation in the /docs/output/xhtml/ directory.

Starting your own book

Let's get to prepare our own book. The first thing we need to have is a topic - it could be your project or a set of articles with a book structure. Of course, we will not give here a detailed instructions, how to write a good article, but we will concentrate on the technical details of setting up a book in TypeFriendly. We start with creating a directory that could be named docs/ somewhere on your hard drive, for example in your project. You do not have to invent the directory structure for your book, because TypeFriendly offers you a ready solution. Now, create the configuration file named settings.ini directly in docs/. It is a simple INI file that contains some information about the book. Every line contains a pair name = "value" and the comments begin with a semicolon. Below, you can find a sample file:

title = "My project"
version = "1.0"
copyright = "My personal data"
copyrightLink = "http://www.example.org/"
license = "GNU Free Documentation License 2.1"
licenseLink = "http://www.gnu.org/licenses/fdl.html"
 
; Technical project settings
 
outputs = "xhtml, xhtml_single"
baseLanguage = "en"
navigation = "book"
showNumbers = true

The first six directives specify the details of your project, for example the name, author and the book license. They are necessary, especially the license issue. If you are writing a book about an open-source project, consider using the GNU FDL license. Otherwise, use the license you like. The second part are the technical issues. In TypeFriendly, the output book is generated by the output systems. Those that we wish to use in our book, we specify in the outputs directive, separating their names with a colon. Currently, the list of available outputs is not too long. You can choose from multi-page and single-page XHTML. In the near future, there will appear the extra outputs that will allow to publish an on-line version of your book with user comments etc.

Another thing you have to choose is the base language of the book. It is a part of the translation system that will be described later. The last two options specify the navigation style. The book navigation style generates a navigation, where the "Next" and "Previous" links allow to traverse through the whole book, similarly to the default DocBook behaviour. The alternative value, tree reflects the hierarchy of the chapters. If you reach the last sub-page in a chapter, you have to click "Up" in order to get to the next chapter. Check out both of the choices and choose the best that suits your needs.

Writing a chapter

It is a time to write your first chapter. You have to create a subdirectory /input/en/ in docs/ directory. Here, you will keep the English translation of your book. Each chapter has its own file with the TXT extension. TypeFriendly uses the names not only to identify the chapters, but also to define relationships between them (for example, A is a subchapter of B), so you have to follow the strict naming conventions. We will introduce them progressively.

The first chapter should be a preface to the whole book with the necessary marketing stuff. We will save it under the preface.txt name.

Title: Preface

----

Welcome to the My Project manual. It was created to illustrate establishing a new book in [TypeFriendly][] book generator. The main features of My Project are:

1. It does not exist.
2. You cannot download it from anywhere.
3. It does nothing.

I hope you will enjoy it.

[TypeFriendly]:
    http://www.invenzzia.org/ "TypeFriendly"

Preface is one of the main chapters, so its name consists of a simple identifier and the file extension. The file content itself is build of two parts:

  • The header with tags. They allow to specify various information about the chapter. In this case, we want only to specify a nice, printable title for it, so we use the Title tags. The syntax is very easy and should not require any extra explaination.
  • The body, separated from the tags with a line with four hyphens. The chapter body is written in Markdown that is fully described in TypeFriendly manual. Here we would like to point out its simplicity. This markup language was designed to be easily readable both in the output and the source form. The paragraphs are separated with an empty line and the ordered lists are created in a natural style. Please note that Markdown ignores the numbers you write in the source form. In the output, the list elements will be always numbered correctly, even if you give all the elements number one. The links can be created by references. In the first paragraph, we have enclosed the word "TypeFriendly" in the square brackets which makes a link from it. At the end of the file, we define where this link follows to.

Let's try to create a chapter that describes the installation of your project built of two subchapters. In the first one, the simple installation will be described, whereas the second one will explain advanced installation techniques. The first subchapter will be given the name installation.simple.txt and the second - installation.advanced.txt. This time, the name consists of two parts separated with a dot. It says that the subchapters are named simple and advanced and there are a part of the installation chapter. TypeFriendly requires from you creating the installation.txt file, too. Let's start from it:

Title: Installation

----

This chapter describes the installation issues.

System requirements
===================

1. Core 2 Quad 7 GHz processor
2. A graphic card with PixelShader 6.0 and 2 GB RAM
3. Fan

The initial text of the installation chapter is quite short, because the exact content is stored in the subchapters. TypeFriendly notices that there also two files that are related to this file and will automatically generate an appropriate Table of Contents and the navigation. Please also take a look at the chapter content, because here we have another Markdown syntax element - a header. Markdown allows you to use two styles of headers. By underlining the header title with the equality characters, you create the level 2 header (level 1 is reserved by TypeFriendly). Level 3 can be achieved by underlining the title with hyphens.

The content of the installation.simple.txt can be found below:

Title: Simple installation
SeeAlso:
 - installation.advanced

----

This chapter describes a simple installation.

1. Extract the downloaded archive.

2. Copy the files to the local folder, for example, `/usr/local/project/`.

3. Execute an installation script from a command line:

        [console]
        # ./install.sh

4. The project is installed.

In the header, we can find another tag, SeeAlso. It is used to create a "See also section" at the end of the chapter. As an argument, it takes a list of chapter identifiers that should be listed there. Each of them is specified in the new line and started with a hyphen, just like in the example. TypeFriendly offers also a tag SeeAlsoExternal which allows to specify the external "See also" links that are not a part of our book.

In the content, we have another style of writing a numbered list. The items are separated with an empty line. This informs Markdown that the items may consist of several block elements, such as paragraphs, other lists and source code blocks. In the second item, the path is enclosed in backticks that produce a verbatim text. In the third item, we added a piece of code to be executed in a system command line.

The source of code is moved from the left margin:

  • The first four spaces are required by the list syntax.
  • The last four spaces - by the code block itself.

The first line of the code block specifies the language we use. The name is enclosed in the square brackets and it is a hint for the syntax highlighter, which style to use. Markdown offers yet another code block syntax that is much easier in use - we will introduce it soon.

And this is the second installation subchapter - installation.advanced.txt:

Title: Advanced installation
SeeAlso:
 - installation.simple

----

This chapter describes the advanced installation.


It is quite similar to the simple installation, but we have to launch
`install_adv.sh` instead of `install.sh`. This script contains an advanced
installer that allows to configure more options.

This file contains nothing new.

API descriptions

In the next chapters, we are going to describe the API of our project. This is the right moment to introduce some helpful documentation tools for the programmers that TypeFriendly offers. Altgough the script is not able to generate the proper files directly from the source code yet, like phpDocumentor, but such feature is planned. This means that we should write the chapters manually, but fortunately it is not very complex. Creating stubs for five classes with 10 to 15 methods in each can be done manually within an hour, and moreover - the task can be automated as everything is a simple text file.

Firstly, we need to create the main chapter: api.txt with the class descriptions:

Title: API descriptions

----

This chapter describes the API of our project.

> [warning]
> In order to make the project work correctly, you need
> the newest versions of the system libraries.

At the end, we see a quote block (this is how it's called in Markdown) and TypeFriendly parses it so by default. However, if the first row contains a square bracket, we will get an information frame like this:

In order to make the project work correctly, you need the newest versions of the system libraries.

Let's create the chapters for our two classes now:

api.class1.txt:

Title: Class "Class1"
ShortTitle: Class1
EExtends: foo
ExtendedBy:
 - api.class2

----

This class performs the most important project
operations. The field list:

 Field          | Type        | Description
----------------|-------------|-----------------
 field1         | int         | Field description 1
 field2         | int         | Field description 2
 field3         | double      | Field description 3

This file introduces lots of new tags in the file header. Title is the basic chapter title - we know this. We may specify there the type of the described item ("Class") and its name. However, when creating the link to the chapter, it would be nice to get a class name only. ShortTitle allows us to do that, producing a shortened title for URL-s.

The next tags are very helpful to describe the object-oriented programming relationships. Currently, there are three types of them and each of them is available in two versions:

  1. Accepting the TypeFriendly chapter names.
  2. Accepding the external element names directly that are provided by the system or external libraries and are not described by our document. The names of such tags begin with the big letter E.

In the example above, the tag EExtends specifies the parent of the current class and tells that the class is not described by our document. On the other hand, ExtendedBy allows to specify the items that extend current class, and moreover - they are defined in the manual, so we would like to get links to them. Note that you can use both ExtendedBy and EExtendedBy in the same document.

In the content, we have another Markdown syntax element - a table. As you can see, the source text is very clean and the list of class fields is readable even in the source form. This technique has some limitations, through, but Markdown allows us to use pure HTML then.

The api.class2.txt looks like this:

Title: Class "Class2"
ShortTitle: Class2
Extends: api.class1

----

This class provides some extra functionality. It does not
add any new fields.

It's time to describe some class methods. Let's start with api.class1.foo.txt or - in other words - the method foo() in class class1

Title: foo()
ShortTitle: Class1::foo()
Reference: int Class1::foo(int arg)

----

This method performs the first project function. As an argument
`arg` it takes an integer. The sample use:

~~~~
[cpp]
my_object = new Class1;
if(my_object->foo(5))
{
   cout << "OK";
}
~~~~

The Reference tag is very helpful while describing functions and class methods. We can specify the function prototype there, with all the arguments, their types and returned values. Of course, the document would be nothing without an example that shows another way or placing the source code snippets in the text. The code is enclosed from both sides with four tilde characters and in the first line, we specify the language for the syntax highlighter.

The second method is described in api.class1.bar.txt file and it is very similar to the first one:

Title: bar()
ShortTitle: Class1::bar()
Reference: void Class1::bar(int arg1, int arg2)

----

This method performs the second project function. As
the arguments, it takes two integers. A sample use:

~~~~
[cpp]
my_object = new Class1;
if(my_object->bar(5, 8))
{
   cout << "OK";
}
~~~~

In order not to make the second class too sad, let's add a method to it, too: api.class2.joe.txt

Title: joe()
ShortTitle: Class2::joe()
Reference: void Class2::joe()

----

A helper method for the project.

We have written all the files for our documentation. The last thing we have to do is to switch to the TypeFriendly directory and run the generator from the command line:

./typefriendly.php -o xhtml "/path/to/docs/"

For Windows users:

php typefriendly.php -o xhtml "/path/to/docs/"

It is important to remember about the last slash in the path to the documentation. If everything went good, you should find a ready documentation in /output/xhtml.

Order management

You should have probably noticed that something's going wrong here. TypeFriendly sorted all the pages alphabetically which caused the introduction to land at the end. Of course, this is unacceptable, but fortunately it is just our mistake. We simply have not specified any custom order rules and TypeFriendly was forced to use the default alphabetical order. To change it, we need to create sort_hints.txt file in the main documentation directory:

preface
installation
installation.simple
installation.advanced
api
api.class1
api.class2

Its structure is very simple - we just specify the chapters in the requested order. There are only three issues that you must pay attention to:

  1. The chapters that have the same parent must be located one by another (for example, installation.simple and installation.advanced must be grouped in the same place, because they have the same parent: installation).
  2. We do not have to specify the sub-chapters, if the alphabetical order suits us. Take a look at api.class1 - we have not specified the methods here, so they will remain in the alphabetical order.
  3. If we have specified one subchapter of a chapter, the rest of subchapters has to be specified, too.

Multilingual books

TypeFriendly provides also a support for writing the multilingual books. Some project may find it useful, offering the readers different language versions: English, French, German, Polish etc. In this case, we always have to choose so-called "base language" which the original content is written in. The rest of the languages are treated as translations. We begin with making a new directory in /input for another language (the best way is to use a two-letter language code, as TypeFriendly uses this convention). Then we just translate the chapters and that's it. Remember that the file names of the translated chapters must match the original ones, as the script generates the structure from the main language directory content and the same ordering rules for all the translations. During the generation, TypeFriendly uses the following algorithm:

  1. If the translation contains the specified chapter, it is used.
  2. Otherwise the content is taken from the base language.

Before setting up a new language, please ensure that TypeFriendly contains also the language files for the documentation interface in the /languages directory. If there are no files for your language available, you must translate them in the first place. Do not forget to publish them on the Internet, so that the others could also use them!

Conclusion

We have created TypeFriendly to get a convenient tool with the simplicity that the other solutions lacked. Now, creating a new documentation here in Invenzzia takes only a couple of minutes and we get a nice documentation stub with less than an hour, with technical details reduced to minimum. We encourage you to try this tool and check yourself, how simple it is.

projects tutorial TypeFriendly 0.1

This text is licensed under Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 United States license.

Add new comment

You are writing a reply to comment

  • Will not be published | Gravatar supported
  • Type here the name of our group.