• • •
This manual guides readers from their first launch of TableHistory through the creation of subject-based archives and the export of material that can be shared with others. It is intended for teachers, researchers, students of history, collection managers, and anyone who needs to compare events, people, and documents over time.
TableHistory helps represent a chronology, but it does not automatically verify the accuracy of the data. Dates, names, places, attributions, and sources still need to be checked. The best results come from combining clear records, consistent conventions, transparent notes, and regular reviews.
The interface is currently available only in English.
1. What TableHistory is and who it is for
TableHistory is a free, open-source application for organizing historical records and visualizing their place in time using a Gantt-style chart. Records represent people, documents, or events. For each record, you can enter a name, a start year and an end year, whether either endpoint is uncertain, a place, and a free form note with basic formatting.
The grid lets you browse and sort items; the chart shows intervals, overlaps, and chronological sequences. For example, an archive about a cultural movement might contain authors, works, manifestos, and exhibitions: the list helps you check the data, while the chart reveals which items are contemporaneous and which belong to different phases.
TableHistory is suitable for timelines, document indexes, collective biographies, educational resources, local history, the history of science, and subject catalogues. Copying and pasting records between archives makes it possible to create subsets: a smaller collection can be extracted from a general archive for a research project, a lesson, or a PDF.
The program is not a precision calendar: the chart is based on years, while months, days, and times belong in the notes. It does not manage structured relationships between records, family trees, full bibliographies, or automatic source verification. You can mention other records, use tags, and insert links in notes, but these references are plain text and are not updated automatically when an item is renamed.
The simplicity of CSV files makes them easy to copy and preserve, but it also makes backups important. Furthermore, it is preferable to edit data through the application; editing a CSV directly in an external editor requires care with commas, quotation marks, and line breaks.
The program is written in C++ using the Qt libraries and supports Windows, macOS and Linux. Data is saved in .csv files, so no separate database or server is required. The spell-checking for English, Italian, Spanish, German, French, and Portuguese, is provided by Hunspell. The project is distributed under the GPLv3 license.
2. The basic model: records, archive, and timeline
The basic unit is a record (item). A collection of records is stored in a file in CSV format. The main window has a grid on the left, a note-viewing area beneath the grid, and a Gantt chart on the right. Selecting a row lets you read its note and see where it sits in time.
The main grid and note panel are read-only, which helps prevent accidental changes. To create a record, use Items - Add...; to edit one, use Items - Edit... or double-click its row. Changes are made in a dedicated form and take effect when you confirm them.
The chart is a compact representation, not a replacement for the underlying data. A bar shows the record's year range; if an endpoint is marked as uncertain, the bar is displayed with a light pattern. The chart helps compare chronologies, but temporal proximity does not in itself demonstrate a causal relationship: interpretation should be explained in the notes and supported by sources.
Records are independent: there are no structured links that connect them automatically. This limitation makes it easier to copy selected items into a new archive without leaving broken references. To organize relationships, use consistent names, tags, and mentions in notes. Remember, however, that renaming a record does not update textual mentions of it in other notes.
For long-term projects, it is useful to maintain a master archive and create separate subject files, for example European_History.csv, Renaissance.csv, and Printing_and_Books.csv. Copying records lets you focus an analysis and share relevant data without distributing everything you have collected. Copies do not synchronize with each other: a correction in the master must be propagated manually, or the sub archive must be recreated.
3. Installation, first launch, and updates
Download the setup package (Windows, Linux) or the app (Mac) from the GitLab repository.
The macOS app in the repository is built for Apple Silicon (M1 or later) and is not notarised by Apple. Use the following command after copying TableHistory.app to the Applications folder:
xattr -r -d com.apple.quarantine /Applications/TableHistory.app
This command removes the quarantine attribute from the specified path. Do not run it on an application from an unknown source.
Download the Windows setup package from the same repository and run it. After the first launch, create a test archive, add a record, save it, and reopen it to check that the workflow works correctly.
Download the .deb (Debian, Ubuntu, etc.) or .rpm (Fedora, etc.) package from the same repository and run it. After the first launch, create a test archive, add a record, save it, and reopen it to check that the workflow works correctly.
The application saves these configuration files:
Windows (System Registry): Path / Key: HKEY_CURRENT_USER\Software\Massimo Nardello\TableHistory
Windows: C:\Users\<YourUsername>\AppData\Local\Massimo Nardello\TableHistory\
macOS (Property List file): ~/Library/Preferences/Massimo Nardello/TableHistory.plist
macOS: ~/Library/Application Support/Massimo Nardello/TableHistory/
Linux: ~/.config/TableHistory/TableHistory.conf
Linux: ~/.local/share/TableHistory/
Before replacing an application version, save and duplicate your important CSV files. Install the new release, open a copy of the archive, and check the grid, notes, and chart before continuing with the working file. Keep the previous copy until you have confirmed that everything works as expected.
4. Navigating the main window
The window is organized around three areas: grid, notes, and chart. The grid lists the records; the panel below it shows the note for the selected row; the chart on the right illustrates the time intervals. This layout lets you review structure and context without opening every record in a form.
Click a grid column heading to sort in ascending order; click again to reverse the order. Columns help group types, compare years, find items with the same place, or check names. Sorting changes how the list is displayed, not the stored data.
Notes in the main window are read-only. Web and file links in them are formatted as active hyperlinks; in the edit form they are not active, since the text is instead prepared for easier editing without accidentally activating links. To change a note, open the record with Items - Edit....
The chart can be zoomed in or out and scrolled. If it covers many centuries, start with a wide view and then zoom in on the period of interest. If a bar looks wrong, check the years in the record first: zoom changes the visual scale, not the record's chronology.
The three main menus are File, for creating, opening, saving, and exporting files; Items, for adding, editing, finding, selecting, copying, or deleting records; and View, for adjusting zoom and switching to full-screen mode. Before carrying out a bulk operation, check which file is open and which rows are selected.
5. Creating an archive and saving your work
Choose File - New to create an empty archive. Before entering a large amount of data, decide on the topic, the scope of the collection, and a naming convention. Names such as History_of_Printing.csv or Town_1940-2000.csv are more useful than New.csv or Final2.csv, because they remain recognizable months later.
Use File - Open... to open an existing CSV. After opening it, check the contents and make sure you did not select a similarly named copy. File - Recent files lets you open the last eight files used, but the list is no substitute for a clear folder structure.
File - Save saves changes to the current file; File - Save As... saves the work under a different name. Use the latter before a major reorganization, to create a variant, or to make a backup copy. To create a sub archive, copy the selected records into a new file instead of deleting irrelevant records from the master.
Before a file is saved, its existing version is copied as a backup file with the extension .bak. To restore data contained in this backup file, remove the .bak extension and open it with the app.
A broader backup strategy is to keep the working CSV, a dated copy, and another copy on a separate storage device or service. Make the copy after saving and, if possible, with the application closed. The frequency depends on the importance of the project: for an archive used every day, saving a copy at the end of each session may be reasonable.
Always distinguish three types of files: the complete master, subject-based sub archives, and PDFs intended for reading. A PDF does not replace the editable CSV; a sub archive must not be mistaken for the complete collection; and a backup should not be overwritten until you are sure the working file is intact.
6. The three record types
The Kind field indicates whether an item is Person, Document, or Event. The choice should reflect the role the record plays in your research, not merely the way the item is named.
Use Person for a historical or contemporary individual: a politician, artist, scientist, author, witness, or participant in an event. In a biography, the start year normally represents birth and the end year death. For people who are still alive, repeat the birth year in both fields; the notes can state that the person was alive as of the last update.
If the goal is to study a cultural movement, the years might instead represent a person's period of activity rather than their entire life. This approach is possible, but the notes should explain it and the same convention should be used throughout the archive: do not mix life dates and years of activity without making the distinction clear.
Use Document for books, letters, treaties, official records, manifestos, laws, manuscripts, editions, and other documentary sources. The title should be recognizable; where useful, include the author in the name according to a convention, such as Author - Title or Title (Author). For a document dated to a single year, set the start and end years to the same value.
If drafting and publication took place in different years, decide which date to use in the chart and explain the others in the notes. Alternatively, you can create separate records for the document and the publication event if both perspectives matter to the project. Notes can retain summaries, provenance, editions, sources, and digital links.
Use Event for individual episodes and processes: battles, reforms, conferences, migrations, discoveries, construction projects, crises, revolutions, or periods such as the Enlightenment. For a single event, the start and end years are the same; for a period, enter the chosen endpoints. The name should distinguish the event from similar episodes.
If the location is broad or includes several places, the Place field can contain the general area, and the note can list individual locations. Use a consistent convention, for example City, Country. A text place name is not the same as a geographic coordinate system.
Ambiguous cases and naming
A decree is generally a Document; its promulgation may be an Event. A person is a Person, while their reign may be represented as an Event if the political period is what matters. If both aspects are important, use two separate records and explain the relationship in the notes.
For people, choose one preferred form of the name and record aliases or variants in the notes. For documents, maintain a uniform structure. For events, add a place or other details to the name only when needed to avoid ambiguity. The best convention is one that is used consistently and understood by someone consulting the archive who does not know its creator.
7. Years, intervals, and uncertain dates
TableHistory covers years from -20,000 to 3,000, to cover also chronology for science fiction novels or climate change previsions. Negative years represent the B.C. period and are displayed as B.C. in the chart; positive years represent the Common Era. For an event in 44 B.C., for example, enter -44 in the year fields. When importing data, do not replace the negative number with a string such as 44 B.C..
The chart uses a yearly scale. Months, days, and times belong in the notes. If an event has an exact date, you can write 15 March 44 B.C. in the note even though the time field contains only -44. A year range should follow the convention adopted for the record: a person's life, a period of activity, the duration of an event, or a chosen historical periodization.
Two flags, StartUncertain and EndUncertain, indicate whether the start or end point is uncertain. A bar in the chart is shown with a light pattern when an endpoint is marked as uncertain. The uncertainty should also be explained in the notes: for example, traditional dating, approximate year, conflicting sources, or disputed attribution. The pattern is a visual cue, not an automatic assessment of historical reliability.
To sort events from the same year by a more precise date, put this date at the beginning of the name and then sort by name. Use a consistent format: a four-digit year, a two-digit month and day, optionally followed by the time in two-digit hours and minutes. Examples:
Note, however, that this system does not allow for the entry of negative years. Therefore, to ensure that the dates contained in the name field are sorted correctly, they must all be either B.C. or C.E. Otherwise, B.C. dates would become intermixed with A.D. dates. Actually, the name field is text-based, not a date type.
For historical periods, choose the endpoints explicitly. The beginning of an era may vary by historiographical school or geographic area; record the adopted convention in the notes and distinguish conventional boundaries from documented facts. Apparent precision should not conceal a controversy.
8. Creating a record step by step
Choose Items - Add... to open the creation form. To modify an existing record, use Items - Edit... or double-click the row. Fill in the fields consistently and confirm only after checking the key details.
Type and name. Select Person, Document, or Event. Use a title that identifies the record without requiring the reader to open its notes.
Start and end years. Enter numeric years; use negative values for B.C. For an event that takes place within a single year, the two fields should match.
Uncertainty. Tick the flag for an uncertain endpoint and explain the reason in the note.
Place. Use a name consistent with the rest of the archive, such as Bologna, Italy, rather than alternating equivalent variants.
Notes. Begin with a summary, then add context, sources, and finer details.
Review. Check the title, years, and place; confirm with OK or Meta / Ctrl + Return; to save and continue writing, confirm with Save or Meta / Ctrl + S.
At the bottom, there is a field for searching for a word within the text of the current note, along with First and Next buttons to highlight the first occurrence and subsequent ones. You can also specify the language for spell-checking or disable it by selecting the option No spell-checking.
Press Esc in the form to discard changes. After saving, check the grid row, the displayed note, and the bar in the chart. This quick review helps catch a missing minus sign, a reversed interval, or a flag enabled by mistake.
For example, an urban-history record could use Kind = Event, the name Railway station opening, start and end years of 1932, and place Bologna, Italy. The note could contain the full date, the organizing body, the context, and a link to a local archive. If you later discover that the official opening and the start of operations took place at different times, create two records or explain the distinction clearly in the note.
9. Writing and formatting notes
Notes are the flexible field of each record. They can contain summaries, context, short bibliographies, links, precise dates, transcriptions, open questions, and explanations of uncertainty. A useful note begins with what readers need to know, then adds the details they need to verify it.
In the Add item / Edit item form, the buttons above the editor let you apply level 1, 2, or 3 headings, bold, italics, or no formatting to the selected text. The shortcuts are:
Heading level 1
Heading level 2
Heading level 3
Bold
Italic
Remove formatting
After these buttons, there is a combo followed by two buttons, Fill and Insert. The button Fill fills the combo with all the existing tags in the file in use. To be recognized as such, each tag must be wrapped by two hash tags (#), have no spaces inside, and be contained in a single paragraph. The button Insert inserts the selected tag in the combo within the text of the current note at the position of the cursor. This functionality makes it possible to use coherently the same tags.
A long note can be organized into Description, Dating, Context, Sources, and Observations. You do not need every section in every record; the benefit is that a repeatable structure makes information easier to find. A short record may need only one paragraph, as long as its name and date are understandable.
To paste text from the clipboard without bringing over the source formatting, use the proper command in the context menu or Ctrl + Shift + V. This is useful when copying material from a browser or word processor. After pasting, check that no page numbers, unrelated headers, or duplicated passages have been included.
Text size in the form can be adjusted with Ctrl + Alt + + and Ctrl + Alt + -. In the main window, the View menu provides note zoom.
In the main view, web links in notes are formatted and clickable. For an important source, do not store only the URL: record its title, responsible organization, access date, and the information used. A link may change or disappear; a readable bibliographic note helps identify the resource later.
You can include links to files using either absolute or relative paths. If the path or filename contains spaces, the entire link must be enclosed in quotation marks. Be careful not to use the smart quotation found in publishing (“ ”) instead of standard quotation (" "). For example:
• File in the same folder as the CSV file currently in use: "my document.pdf" or "./my document.pdf".
• File in a sub folder: "attachments/my picture.png" or "./attachments/my picture.png".
• File in the parent folder: "../my file.docx”.
Because there are no structured links between records, you can add tags to note text and later find them through search. Surround a tag with symbols, for example #roman-history#, to make searching more precise. Choose one spelling and avoid alternating between forms such as #Rome#, #rome#, and #ancient-Rome# if they refer to the same group. It is useful to distinguish subject tags (#archaeology#) from status tags (#needs-review#).
10. Sorting, selecting, copying, pasting, and deleting
Click a column heading to sort in ascending order; click it again to reverse the order. For sorting by multiple fields, work backwards from the last priority. For example, to sort by type first and start year second, sort by year first and then by type.
You can select multiple rows using Shift or Command, depending on the selection operation, and select all with Ctrl / Meta + A. Before running a bulk operation, check the highlighted rows: the selection may be broader than expected, especially after a search.
Items - Find... searches for the first record containing the text typed by the user in its name, place, or notes. Items - Find next and Items - Find previous select the subsequent or previous matches. To find all items containing a string or a tag, use Items - Find and select...: the command selects the results and can act as a temporary filter without permanently hiding all other rows. In the form opened by this command, you may select the available tags and insert them in the search field. Furthermore, you may insert more tags or words separated by | surrounded by spaces (like #rome# | Augustine) to find all the items that contain at least one of the specified substrings.
Tags are useful for targeted searches. For example, adding #local-history# to the notes of relevant records lets search select the subset without confusing similar names or incidental occurrences of a word. For large groups, use a distinctive string and check the selection before copying or deleting.
Items - Copy selected copies the selected records to the clipboard. In the destination file, use Items - Paste from selection to insert them. The same command can import an AI block of text having the expected header. Before pasting data into an important archive, test the process in a separate CSV file.
Items - Delete removes the selected records from the current file. If you want to create a smaller collection, it is safer to copy the relevant items into a new file than to delete unneeded items from the master. After a bulk operation, save and check the result; keep a backup before major clean-ups.
Search, selection, and copying make it possible to organize a modular archive. For example, in a master file called History of Science, select records tagged #astronomy#, copy them, and paste them into Astronomy.csv. The sub archive is independent, but future corrections to the master are not propagated automatically. Decide which file is the reference version and when copies should be recreated or updated.
11. Reading and adjusting the Gantt chart
The Gantt chart is the view that distinguishes TableHistory from a simple CSV list. It shows where the archive's items fall in time and helps reveal overlaps and intervals. It does not replace reading the records: it summarizes their temporal boundaries, while explanations and details remain in the notes.
The View menu includes Zoom In Diagram, Zoom Out Diagram, and Reset Zoom Diagram. Zooming in gives more visual space to the period displayed; zooming out shows a wider span. Reset Zoom Diagram restores the initial scale. There is also a zoom control at the bottom of the chart. You can scroll through the chart to explore the chronology.
For an overview spanning antiquity to the present day, begin with a scale wide enough to show many centuries. Then zoom in on a section to compare nearby events. If you are working only with a period of a few years, a very wide view may make differences look insignificant and labels harder to read.
The length of each bar reflects the recorded interval. A single-year event has identical endpoints; a person may cover a substantial part of the timeline; a historical period may span many years. A light pattern indicates an uncertain endpoint. If a bar does not match the expected chronology, return to the record and check the numeric fields: zoom does not change the underlying years.
Relative positions can raise useful questions: which documents are contemporary with a particular person? Which events precede a reform? How many generations overlap during a period? Temporal proximity, however, does not automatically prove causation. The chart shows co-existence or sequence; the interpretation must be argued in the notes and supported by sources.
11.3 Preparing the chart for an external reader
Before exporting, choose a zoom level that shows the relevant period without shrinking all the bars into unreadable marks. Check for out-of-range dates, overly generic names, and accidentally entered intervals. If the project spans a very long history, it may be better to export separate charts for different periods rather than force every detail into a single graphic.
The chart export creates a vector PDF with a white background, regardless of the operating system's light or dark theme. Vector graphics can be resized without the loss of sharpness typical of raster images. Even so, check the actual result, especially the readability of labels after placing the PDF in a presentation or larger document.
12. Exporting records and charts to PDF
TableHistory offers two main export functions for different purposes. File - Export diagram... exports the chronology chart as a vector PDF. File - Export selected items... creates a PDF document containing selected records. The second option asks for a title and prepares a summary of the items with their page numbers.
Use File - Export diagram... when you want to share a temporal overview—for a lesson, report, display panel, or comparison between periods. The exported chart has a white background, even when the interface is in dark mode. This makes the PDF suitable for printing and inserting into other documents.
The chart is vector-based, so it can be enlarged without becoming blurry. Vector quality does not solve layout problems, however: if the chronology is too dense, some elements will still look crowded. Adjust the zoom, divide the topic into subsets, and inspect the PDF before distributing it.
12.2 Exporting selected records
Select the items that should appear in the document in the grid, then use File - Export selected items.... Enter the title requested by the dialog. The resulting PDF includes an item summary and page references, allowing readers to locate records within the document.
This mode is suitable for a short catalogue, research appendix, handout, or subject booklet. Before exporting, check the selection and the quality of the notes. PDFs use fonts such as Helvetica Neue or Arial and have page numbers.
12.3 Checks before distribution
Open the PDF and verify that its title, pages, fonts, links, and content are readable. Make sure the notes do not contain internal comments that should not be shown to the public and that uncertain dates are explained. If the document will be printed, check readability at actual page size, not only at screen zoom.
Keep the CSV as the editable archive file; the PDF is the reading copy. If you correct a date after exporting, export the document again so it reflects the updated version.
13. Using AI to prepare data
It’s possible to import items prepared with tools such as Gemini, ChatGPT and Claude. The application should not be treated as a tool that independently verifies history: AI can suggest an initial set of records, but the information must be checked. The procedure requires a structured text block with a header and specific fields, not unrestricted prose.
The block must begin with these two lines::
TableHistoryItems:
Kind,Name,StartYear,StartUncertain,EndYear,EndUncertain,Place,Notes
Each record must be a single CSV row with eight fields. Event is represented by the value 0, Document by 1, and Person by 2. Years must be numeric; use negative numbers for B.C. dates. The two endpoints should be identical for a single-year event or document. For a person who is still alive, repeat the birth year in both time fields. Uncertainty flags must be true or false.
Enclose names and places in quotation marks when they contain spaces or commas. Notes containing commas, quotation marks, or formatting must be protected by valid CSV quoting. To avoid errors, do not ask an AI model for a Markdown table, bullet list, or JSON object: explicitly request the format shown here.
The following prompt is an operational template in English. Replace the topic and requested quantity before sending it to an AI assistant:
Prepare [50] important records of people, events, and documents about [INSERT TOPIC]. Return a single CSV code block, with no introductory text and no comments after the block. The first two lines must be exactly:
TableHistoryItems:
Kind,Name,StartYear,StartUncertain,EndYear,EndUncertain,Place,Notes
Each record must be a single CSV row with the eight fields above in exactly the same order. Kind must be 2 for Person, 1 for Document, and 0 for Event. StartYear and EndYear must be numbers; use negative numbers for B.C. years. For a one-year event or document, use the same year for start and end. For a person who is still alive, repeat the birth year in StartYear and EndYear. StartUncertain and EndUncertain must be true or false. Quote fields correctly if they contain commas or quotation marks. Notes must contain a summary in English, explain the dating where useful, and include verifiable sources or URLs when available. Do not invent bibliographic references; identify uncertain or unverified details in Notes. Avoid duplicates and keep names and places consistent.
For broad topics, 50 rows can already be a lot to verify; for a first test, request 5 or 10. Once the format works and the records are correct, generate a larger collection. Do not simultaneously request an enormous quantity, very long notes, and specialist-level precision: it is often more effective to split the work into subtopics and then combine the results.
This is another operational template in English far more complex than the previous one, in two steps. The first:
Create [300] entries for people, events, and documents related to [topic], drawn from [attached works] and other specialized sources, following this format:
(no. | type | name | start year | end year)
The ‘Type’ field must use these values: 2 = Person, 1 = Document, 0 = Event
The second:
Prepare 300 entries regarding [topic]. The entries are listed in the attached index file [file name, created in step 1] and follow this structure:
(no. | type | name | start year | end year). Provide them in batches of 2.
SOURCES
- Author1, Title1 (attached as PDF): primary source.
- Author2, Title2 (attached as PDF).
- Other specialized studies.
Do not read the files in their entirety: for each entry, search only for the relevant sections and extract those specific pages. If no relevant sections are found, please state this and rely on the other sources.
NOTES FIELD: MANDATORY STRUCTURE (always, in this order)
Length: at least [10,000] characters, in English; use only the following tags: h1, h2, h3, p, b, i.
<h1>Name of the entry</h1>
<h2>Essential Data</h2>
One line <p><b>Field:</b> value</p> for each field, depending on the type:
- PERSON: Name (name, nationality/religious affiliation, professional title); Birth (place and date; if living, state “currently living” along with current location); Death (place and date, only if deceased); Activities (positions held and academic chairs, with years); Major Works (titles in <i> with year); Method (or Position/Doctrine); Significance for the matter; Tags.
- DOCUMENT: Type; Original Title; Author; Date; Place; Thesis; Significance for the matter; Tags.
- EVENT: Type (nature of the event); Date (including any discussion regarding dating); Locations; Key Figures; Sources (with precise references); Significance for the matter; Tags.
Tags: always include 3–5 thematic tags in the format #tag#, separated by spaces, in lowercase, and using hyphens; the final tag must always be #to-be-verified#.
<h2>No. Title</h2> (numbered sequentially). First part, depending on the type:
- PERSON: 1. “The subject according to Author1” (reference paragraph,
short quotations in “...”, concluding with a note that the remainder is based on scholarly research); an optional general overview by Author1; two or three sections “(based on research)” covering life, methodology, and works; Evaluation (Author 1’s assessment).
- DOCUMENT: presentation according to Author1; the work and its structure “(based on research)”; reception and criticism; Author1’s assessment.
- EVENT: the historical event according to Author1, citing Author1 within the text; context and connections; interpretation within Christian texts, using <h3> for unresolved issues (e.g., “The chronological problem”). The title should include “(based on research)” only if the section relies on sources other than Author1.
Always include the following, at the end and in this order:
- Relevance for the matter
- Essential chronology: one line per entry, formatted as <p><b>year</b> - event</p>
- Keywords: a single <p> element with terms in <i>, separated by commas
- Essential bibliography: one <p> element per entry; list Author1 first (including chapter/paragraph), followed by primary sources (with specific passages), and then scholarly research.
CONTENT GUIDELINES
- Always distinguish between information provided by Author1 and information derived from scholarly research.
- Do not invent quotations or data. Add “(data to be verified)” after any
uncertain information. Cite Author1 using only brief, faithful phrases.
- Verify the years in the index and correct them, noting the correction.
CSV FORMAT (the file begins with “TableHistoryItems:” followed by the header):
Kind,Name,StartYear,StartUncertain,EndYear,EndUncertain,Place,Notes
- Kind: 2=Person, 1=Document, 0=Event
- Numeric years (BCE years are negative); for a living person: birth year
used for both StartYear and EndYear
- Uncertain: true/false
- Enclose Name and Place in quotation marks if they contain spaces or commas
- Notes: the entire entry on a SINGLE line, without line breaks, enclosed in quotation marks.
Within the entry, do not use straight double quotation marks; use «…» and ’ instead.
- Example row (Event):
0,”Census of Quirinius”,6,false,7,true,”Judea, Syria”,”<h1>...</h1>...”
- Include the “TableHistoryItems:” header and the title row before each submission in the same code block.
OUTPUT
For each of the two entries: provide only the complete CSV row, with no
introductions or comments. After each batch, wait for me to type “continue”.
Start from no. ___ (nos. ___ and ___).
After receiving the response, copy the code block and use Items - Paste from selection. Before using the entire block in an existing archive, test it in a new file or a copy. Check several records from each type: at least one person, one document, one single-year event, one period, and one record with a negative year.
If the years are wrong, names appear in the wrong fields, or notes are truncated, do not proceed with a larger import. Correct the prompt and test again. The import function follows the schema; it cannot know whether an event has been assigned the correct year or whether two documents are duplicates.
13.4 Verifying AI-generated data
The review should check at least: whether names exist and are spelled correctly; dates; negative values for B.C.; suitable record types; the distinction between point dates and intervals; consistency of the place field; whether URLs are relevant; and whether controversies are indicated. For historical work, it is important to read the source cited by the model, not merely confirm that the link exists.
One useful technique is to ask the AI for a separate short list of uncertain points. Even then, record only verified data and notes that clearly distinguish hypotheses from facts. If you keep a provisional record, add a tag such as #needs-review# and search for that tag periodically to complete the review.
13.5 Generating data for the master archive and subject archives
To build a large collection, request separate sets: one for people, one for documents, and one for events; or a series organized by period or geographic area. Twenty well-scoped items are easier to check than 200 heterogeneous ones. Once imported, use search and tags to identify duplicates, records without sources, and items outside the project's scope.
AI is most useful as an accelerator for guided research, not as a substitute for human judgement. The value of the archive comes from selecting, verifying, and explaining the items, not simply from the number of rows.
For a small project, it is enough to create a file, add records, and save. For an archive that will grow over time, use a regular six-stage process.
Define the question. Decide what you want to understand: a timeline of events, a source collection, a collective biography, or the history of a place.
Set conventions. Decide how to name records, how to use negative years, what a person's time interval represents, and which tags to use.
Collect records. Enter data manually or use a structured AI block. Work in small batches rather than focusing only on quantity.
Check and complete. Verify years, uncertainty, places, notes, and sources. Use tags to make items that still need review easy to find.
Create a subject view. Use Find and select... to search for tags or terms, copy relevant records into a separate archive, and adjust the chart.
Publish and preserve. Export a PDF, open it, and read it again. Keep both the CSV and PDF, then create a backup of the working file.
A record should be considered ready to share when a reader unfamiliar with the project can understand what it represents, why it is placed in that year, and where the information can be checked. The appropriate level of detail depends on the intended use: an introductory lesson needs concise notes, while a research catalogue may require more precise references.
The following cases are examples of methods, not historical archives that have already been verified. They show how to organize records and use search, selection, and the chart to answer different questions.
15.1 Preparing a lesson on the French Revolution
Create an archive named French_Revolution.csv and include relevant people, political documents, and major events. Use Person for key figures, Document for declarations and acts, and Event for assemblies, uprisings, reforms, and institutional transitions. In the notes, distinguish the date of a document from the date of the event that produced it.
Add the tag #french-revolution# to all central records. Sort by start year and inspect the chart to see which processes overlap. For a lesson focused on a single year, use Find and select... to make a narrower selection and copy it to a short archive. Export the chart for the presentation and the selected records as a handout with definitions and sources.
15.2 Reconstructing the history of a town
For a city's history, use Place consistently, for example Bologna, Italy, or a more specific location if the project concerns a neighborhood. Records may cover urban development, administrative documents, people associated with civic life, and periods of change. Notes can preserve the municipal archive reference, collection/fonds information, and links to digitized resources.
When the archive grows, use Find and select... for the city name or a neighborhood tag. Copy the selection into Historic_Centre.csv or Infrastructure.csv to produce more focused chronology PDFs. Do not delete records from the master merely because they are not needed in a sub archive.
15.3 Cataloguing an artistic movement
For an artistic movement, record individuals as Person, works or manifestos as Document when the record focuses on the documentary object, and events—exhibitions, group foundations, or manifesto publications—as Event. Decide in advance whether the years for people represent their lives or their period of artistic activity; do not mix these meanings without explanation.
Notes can include style, major works, influences, and museum sources. A tag such as #art-movement# connects the collection at the text-search level. The chart helps show which artists worked at the same time and which exhibitions fall within the same phases, but it does not by itself prove artistic influence; that must be argued in the records.
15.4 Organizing a collection of family documents
TableHistory can serve as a chronological index of family documents: letters, textually described photographs, certificates, contracts, and memoirs. Use Document for the documentary item and identify in Place where it was created or is held, according to an explicit convention. In the notes, record the reference number, owner or archive, digitization status, and contextual information.
If the date is approximate, use the uncertainty flags and explain the method. Do not include sensitive personal details in a PDF intended to circulate without first considering who will read it. A family archive shared with relatives may need a reduced public version, made by copying only appropriate records into a new file.
15.5 Comparing scientific discoveries and publications
For a history of science timeline, use Event for discoveries or demonstrations, Document for articles and books, and Person for researchers. The document name should distinguish its title from the publication date and any later reprint. In the notes, state whether the date refers to the discovery, public announcement, publication, or later recognition.
Sort first by year and then by type to compare results with publications more easily. For a finer chronology of releases within the same year, follow the convention described in Section 7 of placing a date at the start of the name. This method is still text-based, so consistency and review are essential.
15.6 Creating a catalogue of literary works
A literary archive may include authors, works, first editions, journals, manifestos, and awards. Decide how to represent people and works: a Person record may describe a life or literary activity; a Document record may represent the work; and an Event may represent a publication or literary gathering. This distinction prevents a record from carrying two different temporal meanings.
Use a consistent naming format for works, such as Author - Title, and record the first-edition year, translations, or title variants in the notes. Tags such as #poetry#, #novel#, and #first-edition# let you create focused collections. Sub archives can become course handouts or indexes.
15.7 Preparing a museum route
For an exhibition, the archive can bring together documentary objects, historical figures, and events that contextualize a collection. Each note should have a summary suitable for the public and, when needed, a second, more specialized level with sources and conservation information. If final captions will differ from internal notes, prepare a sub archive containing only records approved for publication.
The chart shows the temporal context of the objects, while the PDF of records can be used for editorial review. Before distributing the material, check names, attributions, and rights for any externally referenced images; TableHistory does not manage rights or museum-loans.
15.8 Building a subject collection with AI
A researcher can ask an AI model to suggest 10 records on a subtopic, import them into a test file, and check the structure and fields. After review, relevant records can be copied into the master archive or kept in a subject file. If the model produces duplicates, names and search can help identify them; if a date is disputed, notes and uncertainty flags can indicate that the work is not complete.
The most reliable process is iterative: generate a small set, verify sources, import it, review the chart, and then integrate the next set. Importing a huge block at once saves clicks only if the structure is already correct; otherwise, it increases the number of errors to repair.
15.9 Preparing a timeline for a presentation
Create a file containing only the records needed for the presentation's question. Use understandable names, notes that are not unnecessarily long, and a chart adjusted to the period being discussed. Export the chart to PDF and the selected records as a supporting booklet. Before presenting, make sure the PDF opens on the presentation computer and that the type remains readable on screen or in print.
To avoid overloading a slide, do not necessarily use the entire archive. A general chart may be accompanied by a second export focused on the central section. Selection should support an argument, not merely demonstrate that many data points have been collected.
16. Quality control and good practices
The quality of an archive depends above all on consistency. Correct data placed in the wrong field can confuse the reader; an accurate note paired with an incorrect year can produce a misleading bar; a tag spelled in several ways can make a selection incomplete. It is therefore worth setting aside time for regular checks.
Before declaring an archive ready, check:
that each record has the appropriate type;
that years are within the allowed range and are negative for B.C. dates;
that identical start and end years are intentional;
that uncertain endpoints are flagged and explained in notes;
that place names and personal names follow consistent conventions;
that notes distinguish verified facts from hypotheses and cite sources that can be consulted;
that tags are always spelled the same way;
that exported PDFs have been opened and reviewed;
that an up-to-date backup of the CSV exists.
16.1 Avoiding excessive detail in the chart
The chart should not contain every piece of information available: its purpose is to make temporal comparisons readable. If a chronology looks too crowded, reduce the number of records, create subsets, or export different views instead of trying to fit every detail into one chart.
16.2 Separating facts, hypotheses, and interpretations
In notes, use wording that makes the degree of certainty explicit. “The source documents” is different from “it is believed that”; “according to traditional chronology” is different from “a date confirmed by a contemporary document”. This precision improves educational use and reduces the risk of an editorial choice being mistaken for an undisputed fact.
A CSV file can be shared with other users through ordinary file-transfer methods. This does not mean that TableHistory provides built-in simultaneous collaboration, edit locking, or conflict resolution. If several people work on a project, agree on who updates the master, how copies are handed over, and how changes are consolidated.
If each collaborator edits an independent copy of the same CSV, the application does not reconcile the differences automatically. Before combining changes, compare the records and decide which version to keep. For a simple editorial collaboration, one person responsible for the master file and a review process for contributions may be enough.
A B.C. year is displayed incorrectly
Check that the field contains a negative number rather than the text, like 44 B.C.. If the numeric value is correct but the display does not match the description, check the file that is open.
The timeline bar is longer or shorter than expected
Open the record and check the start and end years. Also verify whether the archive represents a person's life or only their period of activity, and whether the endpoints were entered according to that convention. The chart reflects the record fields; it does not correct dates based on the item's name.
The PDF looks crowded or is hard to read
Adjust the chart zoom, narrow the selection, or create separate exports for different periods or topics. For a PDF of records, select only the entries you need and shorten notes that are not relevant to the audience. Open the PDF before sending or printing it.
AI data goes into the wrong fields or a note looks incomplete
Check the CSV format, the eight-field header, quotation marks, and internal commas. The response must begin with TableHistoryItems: and the expected header row. Test with five records in a new file, correct the prompt, and only then import a larger set.
I cannot find a record I know I added
Try Items - Find... with a distinctive part of the name, place, or a phrase in the notes. To move through matches, use Find next and Find previous. Also check that the correct file is open and that you have not opened a similarly named copy.
I selected too many records
Stop before running a command and review the selection. If your goal is to export or copy a subset, repeat the search with a more specific term or use a complete tag. Do not delete records from the master to simulate a filter; create a sub archive containing the desired records.
I edited the wrong file
If the work has not been saved, consider discarding the changes. If it has been saved already, compare the file with the latest backup. Do not overwrite the backup until you have established which version contains the correct data.
18. Frequently asked questions
Is TableHistory free?
Yes. The repository publishes it as free and open-source software under the GPLv3 license. For distribution, modification, or reuse of the code, consult the license text included in the repository.
Does the app use a database?
No. Data is stored in CSV files. This makes copying and archiving easy, but requires a good backup routine.
Can I enter months and days in the chart?
The time fields are annual. More precise details belong in the notes; to sort events from the same year, you can cautiously use the text-based convention of putting the date at the beginning of the name.
Can I link a person to all the documents they wrote?
There is no structured linking feature between records. You can mention other items in notes, use tags, and adopt naming conventions; these references are not updated automatically when a record is modified.
Can I create a smaller archive from a large one?
Yes. Search for and select the records you need, copy them with Items - Copy selected, create or open the destination file, and use Items - Paste from selection.
Can the chart be exported to PDF?
Yes, with File - Export diagram.... The PDF is vector-based and has a white background. To export records as a document, use File - Export selected items....
Is data produced by Gemini, ChatGPT or Claude verified?
No. AI can prepare rows in the required format, but names, dates, places, sources, and duplicates must be checked by a person.
Is the interface available in Italian?
The interface is available only in English.
What does a light-patterned bar mean?
It indicates that at least one endpoint has been marked as uncertain. The historical reason for the uncertainty should be explained in the note.
19. Glossary and quick reference
Archive: The collection of records contained in a CSV file.
Record / item: An entry representing a person, document, or event.
Kind: The record type: Person, Document, or Event.
StartYear / EndYear: The start and end years used in the chart.
StartUncertain / EndUncertain: Flags marking uncertainty about the start or end point.
Notes: Free-text field for description, context, sources, and links.
Grid: The list of records on the left side of the window.
Gantt chart: A bar-based timeline displayed on the right side.
Tag: A text label included in a note to find groups of records.
Sub archive: A separate file created by copying a group of records from the master.
CSV: A tabular text format in which fields are separated and, when necessary, enclosed in quotation marks.
Menu command
File - New • Create a new archive
File - Open... • Open an existing CSV
File - Save • Save the current file
File - Save As... • Save a copy under a new name
File - Recent files • Open one of the last eight files used
File - Export diagram... • Export the chart as a vector PDF
File - Export selected items... • Export selected records to PDF
Items - Add... • Create a record
Items - Edit... • Edit the selected record
Items - Delete • Delete the selected records
Items - Find... • Search for the first occurrence of text
Items - Find next/previous • Move between matches
Items - Find and select... • Select every matching item
Items - Copy selected • Copy selected records
Items - Paste from selection • Paste copied records or import structured data
View - Zoom In Diagram • Zoom in on the chart
View - Zoom Out Diagram • Zoom out on the chart
View - Reset Zoom Diagram • Restore the chart's zoom level
View - Zoom In Notes • Enlarge note text in the main view
View - Zoom Out Notes • Reduce note text in the main view
View - Enter full screen • Use the window in full-screen mode
Most useful shortcuts in the edit form
Meta / Ctrl + 1 • Heading level 1
Meta / Ctrl + 2 • Heading level 2
Meta / Ctrl + 3 • Heading level 3
Meta / Ctrl + B • Bold
Meta / Ctrl + I • Italic
Meta / Ctrl + 4 • Remove formatting
Ctrl + Shift + V • Paste plain text into the form
Meta / Ctrl + Return • Confirm and close the form
Meta / Ctrl + S • Confirm and don’t close the form
Esc • Discard changes in the form
TableHistory is effective when used for what it is: an archive of time-based records, a grid for browsing and checking data, a chart for seeing periods and events in chronological relation, and two PDF export tools for sharing results. Its simple structure does not prevent large collections; it does, however, require clear editorial conventions, regular saving, and careful review.
To get started, create a small archive with a few people, documents, and events. Experiment with manual entry, uncertainty flags, search, selection, and export. Later, tags and sub archives can help manage more complex projects. AI can speed up the initial collection, provided that the CSV format is followed and every significant item is verified.
The most important rule remains this: the chart helps ask questions and communicate a chronology, but the scientific or educational value of the result depends on accurate records and transparent statements about sources, conventions, and uncertainty.
Appendix A. Complete example and final checklist
This example record is fictional and is intended only to demonstrate how to fill in the fields consistently; it should not be interpreted as a real historical fact.
Kind: Event
Name: Opening of the municipal bridge
StartYear: 1984
StartUncertain: false
EndYear: 1984
EndUncertain: false
Place: Borgonuovo, Italy
Example notes:
Description. Opening of the municipal bridge to the public, as part of a project to connect the two banks of the river.
Dating. The year field records 1984. If the full opening date is verified later, enter it here without changing the annual resolution of the chart.
Context. Record the name of the sponsoring authority, the purpose of the construction, and any preparatory works. If the date of opening to traffic differs from the official ceremony, distinguish them clearly and consider whether two records are needed.
Sources. Add the reference to the municipal archive, the administrative resolution, or the local newspaper consulted. For a web page, record its title and URL; do not leave only a link without explaining which information it confirms.
This record is useful because each element has a clear role: the type states what the record represents, the name identifies the event, the years determine its position in the chart, the place provides a location, and the notes explain context and information provenance. In a real archive, replace the sample text with verified data and consult the cited sources directly.
Quick check before delivery
Before sharing an archive or PDF, carry out a final review from beginning to end. Open the correct CSV, choose some records from the beginning, middle, and end, and check that the main fields are consistent. Search for review tags such as #needs-review# and decide whether to complete, document, or exclude provisional records. Check that place names follow the same convention and that B.C. dates use negative numbers.
Next, inspect the chart at two scales: an overview to make sure the full-time span looks plausible, and a closer view to read a selection of bars. Uncertain dates should be flagged consistently and explained in the notes. The chart is a summary: if the history is complex, accompany it with a written explanation rather than relying on the image alone.
Before exporting, select only records intended for public release. Review each PDF for its title, page numbers, font size, notes, and links, and retain the source CSV plus a backup. For future updates, record the version or export date in the project metadata.
• • •