ManPages

You can create a documentation or education system with files that you and others can read into Praat (with the Read from file... command). Your files will become a hypertext system very similar to the usual Manual.

## Example 1: a single document

If you create a single ManPages text file, it will look like a manual with a single page. Here is an example:

`ManPagesTextFile
` `"Welkom" "miep" 19970820 0
` `<intro> "Hallo allemaal!"
` `<entry> "Belangrijk..."
` `<normal> "Hoogge\e""erd publiek!"
` `<normal> "Einde."
`

A ManPages text file should start with the following information:

  1. The word “ManPagesTextFile” on the first line.
  2. The title of the manual page, between double quotes. This will be drawn at the top of the page. The name of the ManPages text file should be derived from this title (see below).
  3. The author of the manual page, between double quotes. This will be drawn at the bottom of the page.
  4. The date you created or modified the page, in the format year – month (two digits) – day (two digits), without spaces.
  5. The recording time. If this is not zero, three sound buttons (see below) will appear at the top of the page.
  6. A sequence of paragraph types and texts. You put the types between < and >, and the texts between double quotes (if your text contains a double quote, you should write two double quotes).

The format of a ManPages text file is rather free, as long as the first line is correct, the four required pieces of information are there in the correct order, and there is a correct alternation between paragraph texts and types. If you put multiple elements on a line, there should be at least one space between them. You may distribute texts across multiple lines, as long as you do not add any spaces:

`<normal> "Hoogge\e""erd
` `publiek!"
`

This will have exactly the same effect as above.

## Example 2: multiple documents

The above example with a single document is not very useful. You will usually want to refer to other documents:

`ManPagesTextFile
` `"Welcome" "Paul Boersma" 19970820 1.0
` `<intro> "Welcome to Paul's transcription course."
` `<entry> "Groups of speech sounds"
` `<normal> "You can listen to the following sounds
` `from the languages of the world,
` `pronounced by a %single speaker (#me):"
` `<list_item> "@Vowels, quite problematic for Dutch students!"
` `<list_item> "@@Dorsal fricatives@, equally problematic!"
`

With the symbol “`@`”, you create a link to another ManPages text file. A link will be drawn in blue on your screen. In this example, you have created links to the files `Vowels.man` and `Dorsal_fricatives.man` in the same folder as the current file (all `.man` files have to be in the same folder; this makes it likely that their names are unique). If the link contains spaces or other non-alphanumeric symbols, you have to use three “`@`” symbols, as shown; with a single word, you may use a single “`@`”.

In resolving the file name, the ManPages system replaces spaces and other special symbols with underscores, and converts any initial lower-case character by its upper-case variant. For instance, if your link is “`@@back vowels@`”, the file name will be `Back_vowels.man`.

The title in the second line of `Back_vowels.man` must be equal to the link name, though capitalization of the first letter is allowed. Thus, the title of `Back_vowels.man` will probably be “Back vowels”. Likewise, the starting file with the title “Welcome” should have the name `Welcome.man` if any other files refer to it.

## Paragraph types

A normal paragraph will have type ``. The hypertext system will leave a blank space between paragraphs with this type. The first paragraph of a manual page will normally have the type ``. Though this may look the same as ``, the search system of the Manual may take account of the distinction.

Headings (like the title “Paragraph types” of this subsection) have type ``. This will be drawn in a larger character size.

For lists, you use the type ``. You will often combine this with button symbols, like in the following:

`<normal> "Choose a colour:"
` `<list_item> "\bu @Red."
` `<list_item> "\bu @Green."
` `<list_item> "\bu @Blue."
`

For text that should appear with a fixed character width, you use the type ````.

For a paragraph that should be connected with the following paragraph without leaving a blank space (probably a definition), you use the type ``.

For a paragraph with a blank left margin, you use the type ``.

For a paragraph with an embedded script (a picture), you use the type `
`