General Structured Text Files

From Topicscape
Jump to navigation Jump to search
Previous: Appendix F: Details of format for imported structured text files

(Go to:Topicscape Pro User Guide - contents list)

A General Structured Text File (STF) must be a plain text file with the extension .txt. Importing an MS Word file will not work, but you can edit the file in Word if you then save it as MS-DOS text. You must use arabic numbers for sections (so IV, ii. or a. would not be recognized) and the the Roman alphabet for text, but letters with diacritic marks (ä Ç ñ ß) should not present a problem. The exact diacritics that Topicscape can handle are set out here.


Example:

Reference material

1.	Job

1.1	Reference letters

1.2	Appraisals

1.2.1	McGuire Inc.

1.2.1.1	Year 2004

1.2.1.2	Year 2005

1.2.1.3	Year 2006

=>See also : Reference letters

The 2006 entry contains only my preps for 360 deg. review

2.	Hobbies

=>See also : Job

2.1	This is a much longer topic name than you would ever be likely to use, but is inserted as an illustration.  Topic names longer than 47 characters will be truncated, but the full name will be placed in the description.

3.	Sport

3.1 Extreme sport

3.2 Skiing and Snow-boarding

3.3 Off-roading

4.	Family

Here we keep images of family documents like marriage certificate, birth certificate and passport records.

4.1 Birth certificates

4.1.1 Dave's b.c.

=>See documentE:\Joe's shared\My Topicscapes\Reference material\Dave's bc.png

This is a poor copy -- need to re-scan.

=>See documentE:\Joe's shared\My Topicscapes\Reference material\Dave's bc b&w.png

This is a better image but black and white.

4.1.2 Ellen's b.c.

=>See documentE:\Joe's shared\My Topicscapes\Reference material\Ellen's bc.png


In the following, format definitions are in bold black. The blue boxes are description, and not part of the structured text.

Title

The title line is used to name the Home topic and the Topicscape itself. Any characters that are not permitted in a file or folder name will be changed to "_" but they will not be changed in the Home topic's name, so if you want to call a Topicscape "This is my \/first\/ try: Topicscape", go right ahead. The first line of an STF should not start with a number. If it does, the text file's name will be used instead and the title will appear as a topic.

<section number><separator(s)><topic name>

The section numbers you use provide the clues needed by Topicscape to get the structure right, so having this, for example:

1.

1.1

1.1.1

1.1.2

1.1.2.1

is important if these topics are to be associated correctly.

You can break the number sequence, provided you do not break the structure. So this is OK:

1.

1.1

1.1.2

1.1.2.1

(1.1.1 is missing, but it had no children anyway)


This, by contrast, will result in a structure that you probably did not intend:

1.

1.1.1

1.1.2

1.1.2.1

(1.1 is missing, so there's no parent for 1.1.1 or 1.1.2. They will be made children of the Home topic).

The separators between the number and the topic name may be one or several spaces, one or several tabs or a mixture of tabs or spaces. The number of separators is not significant.

The topic name can be anything you like. If it is longer than 47 characters, it will be truncated, but then the long text (up to 2000 characters) will be copied to the topic description.

=>See also : <loosely-associated topic name>
Lines that begin "=>See also : " prompt Topicscape to make a loose association. It searches by topic name, and makes a loose association, which puts a tunnel on each topic of the pair. If there is more than one topic with the same name, Topicscape has insufficient information to do the job, so it will tell you about the ambiguities, one by one and ask you to note them and resolve them manually.
<Description of this topic>
This will be transferred to the Description in the Details Panel for the topic just defined. Note that a description that starts with a number will be treated as a new topic instead of a description. So if the description in the example above: "The 2006 entry contains only my preps for 360 deg. review" had instead been: "2006 contains only my preps for 360 deg. review" this would result in an unwanted topic when imported. In cases of multiple description lines, lines will be joined with a space separating the contents of each line from the next one. Descriptions of more than 2000 characters will be truncated.
=>See document<full filepath to occurrence>
Lines that begin "=>See document" prompt Topicscape to make an occurrence, using the path information given to locate the file. If the file is not there, the information will still be stored, but a description will be added that says "The file is marked as missing because it was not found during import." If you can find the file and put it in the right place, the occurrence will be mended.
<Description of this occurrence >
This will be transferred to the Description in the Details Panel for the occurrence just defined. This has a similar restriction to the one mentioned for topic descriptions above -- it must not start with a number. It handles multiple lines and long entries in the same way, as well. If you are exporting from a Mind Manager mindmap, we know of no way to add a description to a file linked to the mindmap, so this facility will probably be of interest only in cases where you have some manual intervention when building the text file.

Next: Internal Structured Text Files

For an exciting free guide to all things visual, visit the
Visual Thinking Center