3. Creating a new project
3.3. Chapters
3.2. settings.ini file
« Previous
3.4. File syntax
Next »

3.3. Chapters

The chapters are created as simple text files in the /input/language/ directory. Each of them consists of two parts:

  1. Header
  2. Content

In the header, there are several options (called "tags") that allow you to set the chapter title or connections to the other chapters. Under the header, we write the exact chapter content in the Markdown format. You can learn Markdown from this chapter, meanwhile we are going to show, how to manipulate the chapter order.

In every user manual or book, the chapters are organized in a specified order and they may contain subchapters. Sometimes we might want to leave the alphabetical order, for example if each chapter describes different functions and we need an index of them. In other cases, the chapters should be read one after another, as the latter ones may require the information from the earlier ones. With TypeFriendly, you can achieve all of these effects.

The chapter files use the *.txt file extension and the rest of the name is used to determine the dependencies. Each chapter has its own identifier constructed with letters, numbers, pauses and underscores. To specify that chapter A is the parent of B and C, we prepend the chapter A identifier to B and C identifiers and separate them with a dot. Below, you can find a sample list of chapter files:

  1. preface.txt
  2. installation.txt
  3. installation.simple.txt
  4. installation.advanced.txt
  5. api.txt
  6. api.class.txt
  7. api.class.function1.txt
  8. api.class.function2.txt
  9. api.interface.txt
  10. api.interface.function1.txt
  11. api.interface.function2.txt

Let's take a look at the installation chapter. We have a text file for it: installation.txt, where we can add some introductory text. But there are also two subchapters: installation.simple and installation.advanced. TypeFriendly sees that the first identifier is installation, so it links them to that chapter and generates a proper navigation structure. The API description is a bit more complex, because there are three levels. The api.txt contains an introduction, and inside it, we have the first class documented (api.class.txt). The class contains some functions, so we describe them in separate sub-chapters. Remember that if you have a file foo.bar.joe.txt, your project must have also the following files: foo.txt and foo.bar.txt, otherwise TypeFriendly will throw an error.

The default order for any chapter level is alphabetical:

  1. api.txt
  2. api.interface.txt
  3. api.interface.function1.txt
  4. api.interface.function2.txt
  5. api.class.txt
  6. api.class.function1.txt
  7. api.class.function2.txt
  8. installation.txt
  9. installation.simple.txt
  10. installation.advanced.txt
  11. preface.txt

Of course, in most cases this order makes no sense, as TypeFriendly put the preface and installation at the end of the user manual. To change the order, we use the sort_hints.txt file in the main project directory:

preface
installation
installation.simple
installation.advanced
api
api.class
api.interface

The sort_hints.txt file contains a list of the chapters in the new order. Note that you do not have to specify all the files here. If the alphabetical order suits you in some cases (for example, in the function list), you simply do not include this navigation level in the file.

You must either specify all the children of a chapter or none. TypeFriendly will throw you an error, if one of the subchapters is missing.

Tips:

  1. The chapter identifiers do not change across the various language versions of your project, moreover - the translations use the same sort_hints.txt file, as the original text.

  2. The file name is also used to create the links manually in the text. Choose short and intuitive names that can be memorized easily.

  3. TypeFriendly ignores the files with the different extension or with a tilde (~) character at the end of the name. This means you do not have to disable the backup options in your favorite editor.

See also:

3.3. Chapters
3. Creating a new project
« Previous
3.2. settings.ini file
Next »
3.4. File syntax