3. Creating a documentation
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, there is a content written in the Markdown format. The exact syntax description can be found later. Here we would like to show, how to manage the chapter order.

TypeFriendly uses the file name to set the basic order and the parent/child dependency. Each name must consist of the .txt extension and a group of identifiers separated with dots. The identifiers define all the upper-level chapters which our file belongs to. Here is a sample file list:

  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 navigation for them. The API description is a bit more complex, because there are three levels. The api.txt contains an introduction, and inside it, we have a manual for the first class (api.class.txt). The class contains some functions, so we describe them in separate sub-chapters. Remember that if you have a path foo.bar.joe.txt, your documentation must have also the following files: foo.txt and foo.bar.txt, otherwise TypeFriendly will throw an error.

By default, TypeFriendly sorts everything alphabetically. However, most of the chapters must have some other order. You can change it by creating in the main documentation directory a file called sort_hints.txt with additional sorting hints. Without them, TF will apply the following default order to the file list you have seen above:

  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, this order does not make any sense. Yes, it is nice that the functions are sorted by default, but the reader may feel a bit confused, if he sees the preface at the end. Let's give some sorting hints to TF in the sort_hints.txt file:

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

As you see, in this file we declare a required order by placing every chapter name in the separate line. If we enjoy an alphabetical order in a chapter, we simply do not mention its subchapters in the hints (in the example, we have not added any functions from api.class and api.interface. However, TypeFriendly does not allow to write only a part of the subchapter names and do a mix. It will cause an error then.

Tips:

  1. All the language versions use the same hint file. Remember that your chapter must have the same file name in all the language versions.
  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 favourite editor.

See also:

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