(This is an old first draft of the manual. We're working on a new one. The current version of MetaWrite is significanly different and improved. Take everything here with several grains of salt!)
MetaWrite is a computer program, an improvement over word processors, for people that create book length manuscripts.
MetaWrite is for writers whose manuscripts have internal structure and relationships. Example projects might include novels, histories, biographies, plays, or technical reports.
We'll use the creation of a novel as our example.
MetaWrite allows an author to capture auxiliary information about the manuscript (called "meta data") in the project itself, along with the manuscript text.
A novel manuscript is composed mostly of scenes. Other parts might be front matter, part and chapter divisions, and so on. Each of these component parts is represented in MetaWrite as a Manuscript Item.
In addition to the Items representing textual components there are Meta Data Items representing, for example, Characters, Notes, Comments, Plot Lines, and so on depending on the author's wishes.
Items have meta data relationships to other Items.
Finally, Items can be marked with meta data tags (words or short phrases).
Authors have always used meta data, often kept in their head, or perhaps on note cards (or if your name is Fanny Flagg, on a clothesline!), to guide their revision work.
A writer using MetaWrite records the text for the manuscript, as with a word processor, but also captures meta data at any stage of writing: during or after creating the first draft, or during the revision process.
The purpose of this demonstration and workshop is to
MetaWrite is not for everyone.
MetaWrite is probably not useful to these writers.
But many writers, more or less satisfied with their word processor, may find that MetaWrite can smooth the road between first draft to polished manuscript.
The Role Tab is for managing Item Roles. Conceptually, an Item's Role defines how it is used within the project.
The Folder role is mandatory and can not be deleted, other roles may be (re)defined, deleted, renamed, etc., to match the author's ideas about his/her project.
For example, if you're writing a novel you might have Roles for Book, Volume, Chapter, Scene, Character, PlotLine, Note, etc.
Notice that some of these Roles are for Items that will be part of your manuscript when it's published. Others are for "meta data," information you capture in the form of Items and relations between Items that are not of the manuscript but rather about the manuscript!
The Role Tab is intended to be largely self documenting. Let us know if it's not! (See "About MetaWrite" in the MetaWrite application menu for our email address.)
The Settings Tab is where the author can choose various options that affect how MetaWrite works. The options are accompanied by explanatory text to make them easier to understand.
When an error or warning to the author occurs, the first line appears at the bottom of the window in the status area, but the entire message is also placed into the Error/Warning/Information Log that is displayed in the Log Tab.
There are also buttons to display various kinds of data about the project. Some of these are meaningful only to the MetaWrite developers, but they can also be useful when seeking help about a problem you've encountered and while speaking with the developers.
The best word processors allow the author to arrange the manuscript into an hierarchy or tree, reflecting the (for example) Volume / Chapter / Scene structure.
But a word processor file typically contains only the manuscript text. Other information like relationships between parts of the text, and concepts that the author uses when he thinks about the writing project (especially during revision!) are not captured by a word processor. MetaWrite allows all this additional, "meta data" to be captured during the writing process.
Another difference is that the text for a scene in a word processor has a fixed position the the manuscript hierarchy. However, in a MetaWrite project, a scene might appear in the hierarchy more than once. For example,
All these different organizations of manuscript Items l may coexist within the project at the same time -- it's completely up to the writer.
The project is presented as a hierarchical tree, which can be manipulated freely.
The Tree Tab allows the author to examine and change the structural relationships of all the Items that are part of the project, select items for editing, preview all or part of the tree, and other operations.
The left pane shows Items arranged hierarchically. Each item is represented by a rectangular box with several icons to the left, and the item's role, title, and id. Each box is indented from the left edge to show it's hierarchical position in the tree. The color of an items box also indicates it's role. Clicking on an item box will select that item and show either the item preview or the item editor in the right pane of the tree tab. Right clicking on the Item Box will pop up a menu of operations on the Item and/or its portion of the hierarchy (aka "subtree").
Clicking the left-most (pencil) icon toggles the item between edit and preview. Right clicking the pencil icon will display some additional information about the item.
Clicking the folder icon will expand or collapse the portion of the tree below the Item in the hierarchy. Right clicking the folder icon will pop up a menu of operations on the Item's Content and Relations.
When the folder icon is open, the "plus" sign icon inside the item box toggle between showing just the Content of the Item and show the Content plus all the Item's relations.
The tree can also be operated on by dragging and dropping with the mouse.
Start a drag operation on an single Item by holding down the mouse over the Item Box.
Start a drag operation on an Item's Content by holding down the mouse over the Item's folder icon.
Holding down the Option key (Mac) will perform a copy operation, otherwise a move operation is performed.
Dropping on an Item box will move or copy to position in the tree at the same level as the Item, but immediately following it.
Dropping on a folder icon will move or copy to the first position in the Item's Content.
When showing both Contents and Relations in an Item's subtree, any Item boxes for an Item Relation will be labeled at the left edge with the name of the Relation. That label can also be a drop target for a move / copy to add Item(s) to the Relation.
In addition to the right click (context) menu on the folder icon and on the Item box, the Pane Context Menu pops up with a right click on the Tree Pane background. It has options to
While the Tree Tab is best for getting a bird's eye view of the entire project, the Desktop Tab is sometimes the best choice for selecting and then working with a group of Items you want to focus on.
The desktop tab has a left pane on which the contents of any one of the desktops defined by the author is displayed. Think of a desktop as a group of Cards (Items) you want to collect together for reference or to focus on.
Desktop contents look like index cards. Each card corresponds to a single item, and unlike physical cards, these virtual card can be reordered and resized by drag & drop, can display the complete Text of its Item (scrolling to do so), an may be edited merely by clicking on the card.
Selecting a card, by clicking on it, opens the card for editing in the Desktop Tab's right pane.
Cards may be placed on a desktop from the Tree Tab (see the "Item(s) to Desktop" command from the Item box context menu), or by using the Desktop Tab's Desktop Cards Picker, which appears in the right pane when no card is selected. (Unselect any card by clicking on the desktop background.)
The Desktop Cards Picker is takes some practice to use effectively, but it's powerful, allowing you to use the meta data captured in your project to find cards or groups of cards matching the criteria you specify. Details are available via the blue-question-mark help icon at the top of the Desktop Cards Picker.
You may define any number of desktops. The tool bar at the top of the Desktop Tab allows you to select the currently visible desktop, define new desktops, rename a desktop, or delete a desktop.
For example, if your writing a novel and have Character Items defined for your novel's cast, you might want to have a desktop containing all those Item/Cards so you can refer to them as you write.
Cards are in an order which depends on how they were added to the desktop, but you can reorder them, by dragging and dropping, the cards will automatically move to accommodate your new order. Cards are all displayed at the same size, but you can change the display size by grabbing the corner of any card and dragging it; when you release all the cards will resize to match the one you've changed.
The Desktop Cards Picker allows you to automatically sort through all the items in your project, find the ones of interest, and place those items in a form resembling index cards onto the desktop. The automation uses the concept of a "filter" to examine an initial set of cards, "filter out" those that don't match your description, leaving only the cards for items you want to see.
In step 1 you specify a group of cards you'd like to sort through.
In step 2 you select the filter to use to apply to the group of cards you specified in step 1. The 'No Filter" filter passes all the cards (it doesn't "filter out" any cards). You can define other filters (see Defining a Filter, below) name them, and save them as part of the project.
In step 3 you actually run the filter against the set of Items, either replacing the cards currently on the Desktop or adding cards to the Desktop.
(To Be Specified in More Detail!)
MetaWrite keeps everything associated with a project in its project folder, with the name extension of ".mw".
For example, the Test Example project is kept in the folder, TestExample.mw. You can open your operating systems file browser on any project by going to the
Tool menu and choosing,
"Open a File Explorer Window On This Project's Directory".
There are times when you'll want to use this window to manage your project, most commonly to add an image or a media file that you want to be part of the project.
The json file is the project database; the HTML file is also the complete data for the project but saved as an HTML Archive, in a format readable by both humans AND computers. The HTML Archive format is a good bet for being readable long most of the current tech companies are quaint memories.
This folder holds all the checkpoint files, dated in each file's name.s
.gif, .json, .png
MetaWrite can treat files with these extensions as images.
.mov, .mp4, .ogg, .webm
MetaWrite can treat files with these extensions as media (video) files.
You can also put any other files and/or folders in the project folder as long as you don't disturb the file described above. You might, for example, have some research material in it's own folder.
(Step by step, upgrading project folders, after installing a new version of MetaWrite.)
We recommend doing all your writing and revision in MetaWrite, but during and after your writing and revision you'll need to export your work or portions of it in a form you can show others. It's easy to make HTML and various word processor formats.
The formats available for the exported document are "HTML w/ Table of Contents" and "HTML".
This option is for viewing the exported file in an Internet Browser. It includes a "clickable" table of contents for quickly navigating the exported document.
This is the best option for printing the exported document, or for converting it to a word processor document.
When the HTML file is opened in an Internet browser you can use the browser to print it.
To turn the HTML file into a word processor file, for example a ".docx" file for MS Office or a ".odt" file for LibreOffice:
1. Open the HTML file in browser, if not already open.
"Select All", and
3. Create a new document in MS Word or LibreOffice.
4. Do a
"Paste" operation into the new document.
Copy & Paste does a better job of preserving formating than opening the HTML in the word processor does!
Both Microsoft Word and LibreOffice do an excellent job of converting HTML exports from MetaWrite into standard word processing formats (.doc, .docx, .odt, .rtf, etc.). These two word processors are highly compatible with files created by either and can be used interchangably.
However, while MS Word (part of MS Office) is sometimes expensive to obtain, LibreOffice is free and available on the web at https://libreoffice.org/. We highly recommend it!