Table of contents:
See also the introductory document, which currently only exists in html.
To assign a new meaning to a key, use the bind statement:
bind some-command key-description
The command name should be all lowercase, as .sheetsrc files are case sensitive.
Most key descriptions take the form of a modifier key (like control or shift) followed by the main key to be pressed. To specify the control key, write ctrl- in front of the main key; write shift- for the shift key. The two can be combined, as in ctrl-shift-F1. The name of the main key is always uppercase. For alphanumeric keys, the name of the key is the key itself. For other keys, we use the following abbreviations:
UP, DOWN, LEFT, RIGHT, PGUP, PGDN, HOME, END, ENTER, BACKSPACE, DELETE, TAB, BACKSLASH, LBRACKET, RBRACKET, F1-F12
Java refuses to recognize some key combinations, so don't be surprised if you can't assign a command to a not-so-ordinary key. Also, Sheets only allows rebindings involving alphanumeric keys if the ctrl key is specified. (In other words, you can rebind ctrl-A,but not A or shift-A) Rebinding the mouse buttons is not currently supported.
This is a list of all commands you can bind to a key. Most, but not all, of these commands have default key bindings.
See creating fragments in the Sheets reference for general information.
The following commands all create various XML fragment types:
If the auto-sync variable is true, then the database is updated after each command that modifies it, in which case there is no need and no point in calling this command. However, if auto-sync is false, you may want to manually sync occasionally. Note that syncing is in any case done when you exit and before running the compiler, so it isn't too dangerous to run with auto-sync off.
(For setup information, see the compile-command variable and the introduction to compilation.)
In order to allow pairs of strings to be specified, we make another creative extension to the set statement:
set java-documentation-url["java.*"] "http://some-url"
In a .sheetsrc file, you can change the value of a variable by writing
set variable-name value
The name of the variable should be in lowercase, as .sheetsrc files are case sensitive. Different variables have different sets of legal values. For boolean variables, the value should be either true or false. For string variables, the string should be surrounded by double quotes ("string").
The following is a list of variables that can be set in a .sheetsrc file; default values are given after the equal sign.
To compile programs within Sheets, you will need to set the following variables in your .sheetsrc file:
Note to non-Windows users: Java requires that you specify the full path to the executable file.
Note to Windows users: Because of limitations in some Windows virtual machines, command output may not be captured properly. We therefore provide a program named "wrapper.exe" which will redirect ouput properly. If Sheets detects that you are running on a windows architecture it will automatically wrap your compile commands with this program. As a pleasant side-effect, the wrapper program knows about your path environment variable, and thus you don't have to specify the full path of your program.
In order to allow pairs of strings to be specified, we make another creative extension to the set statement:
set java-documentation-url["java.*"] "http://some-url"
These variables are called preferences in that sheets will work as intended if you don't set any of them, however you may find that you very much want to set some of them.
Most fragments do recognize the views "summary", "header", and "full".
show-with java-package-name
View modifiers simply change some property of a fragment display. The modifiers java-package-name and java-class-name affect how the names of Java fragments are shown. The modifier sheet-contents affects whether sheets are displayed "open" or "closed".
In another amazing syntactic innovation, the .sheetsrc supports a record-like syntax for specifying information about how a particular sort of text should be displayed. You can specify the point size (an integer), the font-name (a string) and whether a bold face should be used (boolean).
Each kind of text is associated with a sort of variable which can be set with the set statement, but only when a particular font attribute is designated. For example, you say:
set code-font.font-name = "courier"
set all-fonts.size = 12
In Sheets, a documentation fragment is a piece of natural language text. Like everything else in Sheets, documentation is broken into fragments. Documentation fragments include paragraphs, sections, bulleted lists, and pre-formatted fragments.
Sheets documentation is based on XML. It looks a lot like HTML: you have angle brackets, and you have to use < and > instead of the < and > characters. Normally, when you view documentation fragments, the tags are invisible. However, when you begin editing a fragment, the tags become visible again.
Some differences from HTML: XML is case sensitive; HTML is not. XML supports minimization, which appears as a normal tag with a / character before the closing > -- this is a tag that closes itself. Examples:
blah blah <normal-tag> contents</normal> blah blah
blah blah <minimized-tag/> blah blah
(Minimization is not used much in DocSheet)
You can create a new documentation fragment by using the Insert new menu item, which is available on the pop up menu. You can also simply find an existing documentation fragment, and type new text at the bottom, much like you would with a Java fragment. When you commit the fragment, new documentation fragments will be created.
You can edit the text of the fragment in the usual way, just like you do code. Additional operations are available: you can turn a paragraph into a section using the transforms menu of the pop up menu. There are also DWIMish promote-doc-fragment and demote-doc-fragment commands, which attempt to mimic the behavior of the tab key in Microsoft Word's outline view . The promote command takes a documentation fragment and makes it "more important." For instance, a paragraph will turn into a section, and a section will be moved up in the hierarchy to make it a more important section. The promote command is by default bound to control-shift-TAB.
The demote command does roughly the opposite of promote, making a fragment less important. Sections turn into paragraphs, and paragraphs turn into items in lists. Demote is bound to control-TAB.
Note that promote are demote are not completely reversible -- demoting several times and then re-promoting the same number of times will give you something equally "important" as what you started with, but it may not be identical -- you may be left with a paragraph rather than, say, a preformatted.
Also note that promote and demote will refuse to work if the fragment is contained in more than one container (has more than one parent) -- this is a problem MS-Word never had to worry about!
A <list> is simply a list of fragments, and can be ordered or unordered. These are similar to HTML ordered and unordered lists: ordered lists should be displayed with numbers, and unordered lists are displayed with bullets. (This is how they appear when run through the XML->HTML renderer. Inside Sheets, however, both kinds of lists look identical, save for the title of the DocListFragment.)
A <definition> is where you give the definition of a word. There are two fields. In the Sheets representation, definitions look like sub-sheets; the title of the definition is the word being defined, while the body (contained fragments) is the descriptive text. Typically, the descriptive text will be a paragraph fragment, although you can put any kind of fragment there that you want. The title is not limited to a single term--if you want to have multiple terms, put each of them on their own line.
A <preformatted> fragment is like the HTML <pre> tag. In a preformatted fragment, there is no word wrap, and a fixed width font is used. Preformatteds do not yet use the rich text engine, so all entities and tags are quite visible and ugly within Sheets.
A style is font information that does not cross fragment boundaries. Styles are abstract concepts which apply to a range of concepts, but have no single visual representation. For instance, there is an emphasis style, which may be rendered in either italics or bold.
Styles may be nested, but they may not otherwse overlap, nor may they cross fragment boundaries. To add styles to existing text, you simply type in XML tags for the style.
The built-in styles are: emphasis, e-mail, gloss-term (a phrase being ntroduced for the first time), and computer (a fixed width font).
To create a hyperlink, copy the target of the link into the cut buffer. (Note that the target of the link does not have to be a documentation fragment) Then, select the start point of the link and execute the create-link command, which can be found on the pop up menu. This will create a link to the component in the cut buffer. You may then typing in a description of the link, or if you leave that space blank, Sheets will use a summary view of that component. (The link text will only appear when you export the file, unfortunately) This kind of linking is known as native links. Example:
blah blah <link slot="0">This is a link</link> blah blah
To traverse a hyperlink, simply click on the link with the middle mouse button. If your mouse does not have a third mouse button, you can simulate it by holding down the ALT key while pressing the left mouse button.
To remove a link, simply delete the start and end tags. To change a link, edit the links attribute.
Sheets also allows you to create documents that interact with HTML documents, using URL links and anchors. To link directly to a URL, rather than to a fragment, write it as <link URL = "whatever">. To create a URL anchor for a component, typing into the anchor attribute of the fragment. If you wish for the fragment to contain more than one anchor, put each anchor name on a new line. (Note that the anchor is for the entire fragment; there is no way to create an anchor for a specific point within a fragment)
Another form of linking is the documentation attribute, which all fragments have. Simply pick a fragment you wish to document, usually but not necessarily a Java code fragment, and display its documentation attribute by selecting the Show Attribute command from the pop up menu. Next, copy the target fragment (usually a documentation fragment) into the documentation lists attribute.
There is a corresponding attribute, documentation-for, which is the reverse of the documentation attribute. Sheets will automatically maintain the bi-directional of the of these attribute, and you can get it either one.
Sheets has three representations for documentation: an internal database representation, external representation based on XML (also known as DocSheet), and an HTML representation. The internal representation is what is used inside the database. To convert from the Internal representation to the ex mill representation, you must export the fragments. (This situation is analogous to the internal database representation vs. file representation of Java programs)
For best viewing, you need to convert the XML documentation into HTML format, a process known as rendering. There is no way to directly convert from the internal representation to HTML. There is more than one way to render a given XML document; for instance, you might render the emphasis style as either italics or bold. Sheets comes with one renderer, but you can use a different one if you want. To run the default renderer, type:
docsheet2html < input.html > output.xml
The default renderer will automatically create a table of contents for your HTML document. It will also create URL anchors for <edit-command>s and <edit-variable>s; the anchor will be the same as the name of the command/variable.
If you wish to write your own render, consider using the XSL style sheet facility available with most XML implementations. (The default renderer does not use XSL, because at the time of implementation XSL was unstable. However, it has probably gotten better in the intervening months...) You'll need to consult Appendix B for the structure of XML documentation.
Sheets comes with an html2docsheet utility (found in the util directory) to assist conversion from HTML into sheets documentation. The tool is not perfect, however. In fact, it can't be perfect--HTML is simply too unstructured to convert perfectly. Instead, the HTML to DocSheet tool uses heuristics to do the best it can.
One of the limitations of the conversion tool is that it only handles correct HTML. A surprising number of web pages are actually not legal HTML; the converter will not be able to handle them. If you encounter problems, try loading the HTML file into Netscape page composer, and then resaving the file. This will fix most errors; any remaining problems will have to be fixed by hand.
Command line usage:
html2docsheet < input.html > output.xml
Once you have a file in XML format, you can import it into Sheets much like you import Java files. Select Import from the File menu, and select the file you wish to import. You may need to do additional cleanup, as the HTML to XML converter is not perfect (see above). When you import XML files, any hyperlinks will use URL's rather than native links. (See section on linking for details) To convert these links into native links, select all fragments you wish to converge which contain links that you wish to convert, and run the convert-urls-to-native-links command. You'll be informed about any links that can be converted into native links, because the corresponding anchor could not be found.
To remove URL anchors from fragments, select the fragments which have encouraged that what you wish to remove, and run the strip-anchors command.
Tip: Use the recursive-flatten command to flatten all fragments in the a document, and then select all the fragments using a shift click with a mouse. That way, you can easily convert to native links or strip anchors in a single command.
An <edit-command> fragment is useful for describing the editor commands of Sheets. It is similar to a definition fragment, but allows you to optionally specify a default key binding for the command.
Similarly, <edit-variable> lets you describe variables that you can set in your .sheetrc profile. Variables have a name, and optionally a type and a default value.
Structure tags have a well defined grammar; some structure tags only go inside specific structures. In Sheets, structured tags act as fragment boundaries.
// Toplevels will probably be component boundaries in Sheets
toplevel
<para>
| <section>
| <block-quote>
| <itemized-list>
| <ordered-list>
| <definition>
| <literal-layout>
| <graphic>
| <edit-command>
| <edit-variable>
<para> styled-text
<section>
<title>
styled text
toplevel+
<unordered-list> <list-item>+
<ordered-list> <list-item>+
// DocSheet equivalent of HTML's <dt><dd> combo.
<definition>
<term>+
plain-text
top-level+
// Because Microsoft's XML parser throws out whitespace // (in violation of the XML spec), we make liberal use of entities. // Use for a space character, and <newline> for newlines. // Tools should hide this kluge from users. <preformatted> styled-text
// Description for one or more edit commands
<edit-command>
<command>+
<name>
<default-key-binding>?
top-level+
// Description for one or more edit variables
<edit-variable>
<variable>+
<name>
<type>?
<default-value>?
top-level+
Native links are always turned into URL links upon export, thus there is no XML representation of native links. We use object ids as the URL.
URL anchors are represented as XML attributes on the tag; if there is more than one anchor for a fragment, we have multiple attributes that begin with "anchor" and end with a unique integer. Example:
<para anchor1="what" anchor2="ever">
DocSheet (the XML representation of documentation) started off as a slimmed down version of DocBook, an industry standard SGML DTD. It diverged pretty quickly, however. I soon concluded that it was more important to be familiar to HTML users than to maintain similarity to DocBook. At this point, DocSheet has very little in common with DocBook.
Fix bugs w/ bidirectional attributes, and create the various promised attributes.
Implement <list-item> (currently, each item in the list is expected to be a single fragment).
Move ImageFragments into the Doc world.
Completely hide all aspects of XML from the user.
Have preformatteds do font-lock.
Allow links inside section titles.