Sentence Rebuilder User Guide

The Sentence Rebuilder User Guide will teach you everything you need to know before rebuilding broken sentences. This guide will cover how to manage rule profiles, what types of sentences the rebuilder will be able to successfully rebuild and of course, how to actually query the system to rebuild sentences. If you are just looking to use the Rebuilder, this part of the guide will be enough to get you started. However, this guide will also cover how to make your own grammar rules and how to manage your rule profiles. This second part of the guide is not necessary if you are just looking to rebuild sentences, but even if you do not plan on creating your own rules, learning about the rule builder can help you to better understand what kind of sentences can be rebuilt, and the underlying systems that allow the Sentence Rebuilder to do its job.

The Sentence Rebuilder

The Sentence Rebuilder "Ask" page is where you can actually query the application to rebuild broken sentences. The Ask page is divided into five main sections. The top left panel is where suggested rebuilt sentences will appear after a query. The bottom left panel is where you can actually enter your queries and change the missing word and letter characters. The three panels on the right are where rules can be enabled and disabled, and favourited. Above the grid is a menu for selecting the language for your query.

With a brand new account, the left three panels will likely look something like the figure below:

The top of these three panels is where rule profiles that you have created will appear. The middle panel is where your favourited rule profiles will appear. All other rule profiles that are currently being shared by other users appear in the bottom panel.

A good place to get started with rebuilding is with the default rulesets. These rulesets contain a large number of general purpose rules that will be able to rebuild a number of common sentences and phrases. The english default ruleset is favourited and enabled by default. As you become more familiar with rule profiles and you understand how rules are built, you can view these rule profiles to see what kind of sentences can be rebuilt using these rulesets. Additionally, you can then view other rule profiles that may be more specific to your particular needs. For now, the default rulesets are a good place to start.

Moving on from the rule management panels, the bottom left panel of the Ask page is where you can actually query the system in order to rebuild sentences.

The main text area at the top of the panel is where you can enter broken sentences to be rebuilt. Sentences entered in this section are period separated and the rebuilder is capable of rebuilding many sentences at the same time. The "Select a file" button at the bottom right of the panel facilitates an easier way to enter many sentences. Text files can be opened using this button and will be automatically placed in the text box. The missing word character and missing letter characters can also be selected in this panel. The following characters can be used as missing word and letter characters: @ # $ % ^ & *.

The Ask button will submit your broken sentences to the system. Alternatively, use the Enter key to submit your sentences. For now, try typing "h*w % you" into the text box and submitting the broken sentence.

Submit the broken sentence and the suggestion panel at the top right will be updated to show suggestions. In this case, a single suggestion is shown: "how are you". The Rebuilder will also inform you of the matching rule sentence from which the suggestion was made. In this case, the rule sentence is simply "how are you". Some of the examples below will show some more complex rule sentences.

The Sentence Rebuilder works well with common, general sentences and phrases. Unless you are using a ruleset specifically created for a particular context, the Rebuilder may have difficulties coming up with specific suggestions for broken sentences. This can lead to two scenarios. The first is that the Rebuilder will not be able to come up with a suggestion at all. Alternatively, the Rebuilder may provide a large number of general suggestions for your query. The same problem arises when the submitted broken sentence is too general. By too general, I mean that there are a large number of missing letter characters and especially missing word characters. Again, these cases may lead to no suggestions, or a large number of suggestions.

As an example of the above issues, and to explain some powerful grammar rule concepts, qeury the Rebuilder with "that % a v*ry n*ce ha*" or look at the output in the figure below.

In this example, there are a number of suggestions that are provided by the Rebuilder. This likely wouldn't lead to a large issue in this particular case because the user would have additional context for the sentence that the Rebuilder does not have. However, the example does demonstrate how a small generality can lead to a larger number of suggestions. Take a look what happens when we move a "*" from the end of the sentence and make that word "hat". Now add the word at the end of "v*ry" for the input "that % a v*r* n*ce hat":

Despite having the same number of missing letter and word characters, this query is given a single suggestion in "that is a very nice hat". This is because, while "v*r*" has a decent number of words that can fit with those missing letter characters, "ha*" is much more general in the context of the sentence. "That is a verb nice hat" doesn't make a lot of sense, but "that is a very nice ham" is a sentence that could be contextually correct (perhaps at a holiday dinner).

This example also introduced a wildcard grammar construct. You may have noticed that the matching rule sentence for this example was "that is a very !A! !N!". !A! and !N! are known as part-of-speech constructs. These are types of wildcards that match against any word that shares the given part-of-speech (verb, noun, adjective, adverb). These constructs provide a lot of power by allowing lists of possible words for words with missing letters to be reduced in size to match against the given part-of-speech. This improves the specificity of the grammar rules for words that would be generalized otherwise. !A!, !N!, !V! and !D! represent adjective, noun, verb and adverb parts-of-speech respectively. There are also two other wildcard constructs, "*" and "_" which represent multi-word and single-word wildcards respectively. The wildcard constructs will be discussed in more depth in the Rule Builder section below.

For the final two examples of simple sentences that can be rebuilt using the Rebuilder, enter the following into the Rebuilder or look at the output below: "What % yo* do**g. I % wat**ing horr*r f*lms."

This example demonstrates a powerful tool in the Rebuilder's arsenal. Using WordNet, the Sentence Rebuilder can determine synonyms and related words to words (broken or whole) that are entered into the application. This is powerful because it allows the sentence to match a sentence like "I like watching horror films" against the sentence "I like watching horror movies". This improves the generality of enabled grammar rules considerably. However, this can also sometimes cause the Rebuilder to suggest sentences that don't make complete sense. You may have noticed that the sentence "I % wat**ing horr*r f*lms" matched against two rule sentences. The first one is "I like watch horror movies". This sentence did not end up causing any wrong suggestions because the sentence "I like watching horror films" was still provided as the suggestion. However, since "watch" and "watching" are related words, the Rebuilder provides this suggestion twice because it matches two separate rule sentences. This situation becomes more apparent with the example below:

You should notice that while the Rebuilder provided the correct suggestion for the sentence "What % yo* do**g" (what are you doing), it also provides the suggestion "what did you doing" matching the rule sentence "what did you do". This particular scenario is caused because "doing" and "do" are related words. In this case, and in most other cases where this might happen, it should be easy to see which sentence is the correct suggestion. However, it is something that you should keep in mind when rebuilding sentences.

This concludes the users guide for the Sentence Rebuilder itself. The next section discusses the Rule Builder, and discusses the underlying markup language in more detail. While it is not necessary to read this part of the guide if you only want to rebuild sentences, it does provide insight into how the system works, and how you can create rules for your particular needs.

The Rule Builder

The Rule Builder web page is where you can actually create grammar rules for use by the Sentence Rebuilder. The Manage page is aligned in a similar format to the Ask page, but there are some obvious notable differences. The right three panels are again used to manage your rules, your favourite rules and other community rules. In your rule panel, you can see your rule profiles and you can choose to edit and/or share the profile for use by other users. Rules are not shared by default, but I would encourage you to share your profiles with other users to increase the number of rules available to them. The community rules panels allow you to duplicate or view the rule profiles. Choosing to view a rule profile will bring you to a similar page to the Manage page, however you will not actually be able to modify the profiles from this page. Choosing to duplicate a rule profile is a good option for when you may want to create a "fork" of one of your own rule profiles, or add to another user's rule profile. Duplicated profiles are saved as your own profile and do not alter the original profile.

The bottom left panel is where you can configure the rule profile that is currently being created or edited. It has options to give your profile a name, a description and a place to choose your language. These options must be set before a rule profile can be saved, and the Rule Builder is currently implemented in English and French. Additionally, there are buttons to save the profile or duplicate the profile, and a button to abandon the work on the current profile to create a new one.

The Rule Builder main area is pictured below:

This area of the Rule Builder is where actual grammar rules are created. The top right panel is where saved rules will appear after they are created. The left panel is the block-based visual editing environment in which grammar rules are created and altered. The bottom right panel is where rule constructs are selected and added to the editing environment.

The basic functionality of the Rule Builder is simple. Simply click on a construct in the rule construct area and it will appear in the Rule Builder area. Constructs are basically building blocks that can be used together to form grammar rules. For now, click on the "Create new atomic rule" construct. When clicked, you will notice that two things happen. The first is that the construct can now be seen in the Rule Builder area with a text box for the rule name. Rule names must be unique within a given profile and must not contain spaces. The second thing you may have noticed is that the available constructs in the rule constructs area have changed. The constructs change in a way that will guide you in making a structurally correct grammar rule. Whether or not a rule will actually have any practical use will be up to your abilities to create thoughtful rules.

You probably noticed that there were three options to choose from when creating a new rule. Atomic rules are simpler than response-based rules and represent a single rule entity. Several rule sentences can be created from a single atomic rule, due to the power of the rule constructs, but atomic rules will nonetheless tend to represent a singular grammatical theme. On the other hand, response-based rules group together several related rules that can be activated according to some trigger. This is a good way to group grammatically different sentences and phrases together that contain similar words and structures. For example, sentences like "how are you" and "how did you do that" can be grouped together based on the prompting "how". Categories are not really rules, but are more groupings of categories of words that can be referenced from other rules. Categories will be discussed in more detail later.

After clicking on "Create new atomic rule", the main lower-level constructs appear in the rule constructs area. I will discuss each of these constructs in turn, before moving on to some special constructs found when creating response-based rules and categories. The first lower-level construct is a simple text input. This construct allows you to enter textual content, and will sometimes comprise the majority of a rule. The power of the constructs system comes from having text input with spatterings of other constructs throughout the rule. Text inputs must have some textual content within them.

The multi-word and single-word wildcards were discussed briefly in the Sentence Rebuilder section. A multi-word wildcard will match against any number of words that are not explicitly in the grammar rule. For example, "how" followed by a multi-word wildcard would match against "how are you" though it could also match against "how now". The multi-word wildcard construct is represented by a "*" in the underlying markup, and any number of words (even no words) will match against this construct. Similarly, the single-word wildcard will match against a single word. This construct is represented as "_" in the underlying markup. A simple example of using this wildcard is in the rule "my name is _", which would match against any name ("my name is Joe", "my name is Sara" etc). The multi-word wildcard construct in particular is especially useful in creating rule triggers, which will be discussed a little later.

The four contructs at the bottom of the rule construct area are also types of wildcards. These green constructs are part-of-speech wildcards, which were also discussed in the Sentence Rebuilder section. These wildcards will match against any word with the given part-of-speech. These constructs are represented by !A!, !V!, !N!, and !D! for adjectives, verbs, nouns and adverbs respectively. For example, the rule "that is a very !A! !N!" would match against both "that is a very nice hat" and "that is a very big dog", since "nice" and "big" can both be adjectives, and "hat" and "dog" can both be nouns. As with all wildcards, these constructs will not match against missing word characters in the Rebuilder. This is because there is a very vast number of adjectives, nouns, verbs and adverbs that could match a missing word. The same concept is even more severe with multi-word and single-word wildcards. However, these constructs are still very powerful because they can narrow down potential suggestions and provide more specific suggestions when matching against broken sentences.

The three purplish constructs above the part-of-speech constructs are known as choice constructs. These constructs are often combined together to create a much larger number of rule sentences than would be possible using just text inputs. The word alternative construct allows for several words to take the place of the construct in a rule sentence. For example, the rule "that is a very [large, big] !N!" would lead to the rule sentences "that is a very large !N!" and "that is a very big !N!". This is a simple example, but there are many clever ways to use this construct which will be described later. Related to the word alternative construct is the category reference construct. With this construct, you can reference a category that you created earlier. For example, say that you created a category called "colours" with as many colours in it as you could think of. Then, in a rule like "my favourite colour is @colours", any colour in the cateogry "colours" would match against this rule. This is very useful for more general situations than the word alternative construct. Finally, the word optional construct allows for optional words to be added to rule sentences. For example, the rule "that is a {very} !A! !N!" would create rule sentences "that is a !A! !N!" and "that is a very !A! !N!".

Before going into some specific examples that should help clarify how to use these constructs, I will first discuss a little bit about creating categories and response-based rules. For now, click on "Delete Last Construct" or "Clear Rule" to be brought back to a clean slate. Now click on "Create new category".

Creating new categories is simple. The rule builder should now look like above, and you must give your category a name and add as many category members as you'd like. Try to choose a descriptive name, so that it will be easy to reference your category later.

Click on "Clear Rule" again, then click "Create new response-based rule". You will then notice that you are forced to first create a rule trigger.

A response-based rule is comprised of a single trigger, and two or more trigger responses. The general use case for this rule is to create a generalized rule trigger, then have more specific trigger responses that fall under the umbrella of the rule trigger. For example, the default ruleset contains many response-based rules that are named things like "how*" and "why*". The triggers for these rules are simply "how" and "why" followed by a multi-word wildcard. This way, any sentence beginning with "how" or "why" will trigger the correct rule and trigger responses can then be matched against the broken sentence. The trigger responses for these types of rules are usually simple phrases that can be logically grouped together, but are difficult or not necessary to create using atomic rules. For example, the trigger responses for "how*" include things like "how are you", "how did you do that", "how did that happen". Of course, you will not be able to add every single phrase starting with "how", but you can use the other lower-level constructs discussed above to cover a wide variety of phrases.

You probably still have some questions about what kind of rules can be created using these constructs. The remainder of this section will provide a few examples to get you started thinking about clever ways to use the constructs to cover a wide variety of sentences and phrases. I would also encourage you to view or duplicate the default ruleset to see all the rules in this profile to get even more inspiration.

The following examples will cover some clever atomic rules that can be created in the Rule Builder. Response-based rules are generally fairly simple and do not make as clever use of constructs as atomic rules. To start off, consider phrases beginning with "I like" or "she likes" or "he likes". Related phrases include "I do not like" or "she does not like" or "he does not like". We can cover a lot of possible ways this phrase can play out using just two atomic rules. To follow along with this example, create a new rule profile. Click on "create new atomic rule". Name this rule how you choose (I will name it "ilike"). These sentences all have a common starting point of I, she, he and we will also include it. To begin this rule, place a word alternative construct and add I, she, he and it all separated by spaces:

We could just create a rule that includes phrases like "I like cheese", but we can actually include phrases like "she does not like cheese" through clever use of constructs. There is no optional alternatives construct, so we will have to enter two separate optional words for "do" and "does". Add these optional constructs now. Next, add an optional construct for "not". Finally, add a word alternative construct and add the words "like", "likes" and "enjoy". So far, your rule should look like this:

From here, we have to cover what this individual likes or does not like. This can be best accomplished by using part-of-speech constructs. You may also want to use single-word or multi-word wildcards, but the part-of-speech constructs help to narrow down potential sentences, though you will lose some generality in the rule. Add a verb followed by a noun part-of-speech construct.

This simple atomic rule now covers a wide variety of possible sentences. For example, "I like playing sports", "She does not like eating cheese" and "he likes baking cakes" will all be covered by this one rule. Similar rules can also be created by adding a single verb or single noun part-of-speech construct at the end of the rule, instead of both the verb and noun construct. These alternate rules will also cover sentences like "he likes horses" and "she does not like driving". With just three simple rules, a wide variety of sentences have been covered. This is the power of the construct system for creating grammar rules.

You may notice that these rules could potentially create erroneous rule sentences like "I does not like playing soccer" or even more egregious, "I does do not likes eating beef". While this is true, the Rebuilder would only ever offer up these suggestions on deliberate attempts to mislead the Rebuilder using nonsensical sentences. This is a small price to pay for the power that the grammar constructs provide.

As a final example, lets begin by creating a category called "musicgenres". In this category, put as many music genres as you can think of:

Next, we'll create an atomic rule that references this category to handle phrases where an individual describes their preferred music. Start with a word alternative construct and enter "I she he". Then, add another alternative with "like", "enjoy", "likes" and "enjoys". Next, add an optional word "to", and a word alternative for "listen" and "listening". Add another optional construct with "to". Then add a category reference and enter the name of the category you created earlier. For me, this would be "musicgenres". Finally, add two more optional words with "music" and "songs". Your completed rule should look something like this:

You could also have included optional words for "does not" and "do not" like we did in the previous example. Nonetheless, this rule will match sentences like "she likes listening to country music", "I like jazz" and "he likes to listen to classical". You could even add a multi-word wildcard construct at the end of the rule to match against sentences like "I like listening to classical music before bed".

When you are done creating a rule, be sure to save it to the Rule Builder. The Manage page will alert you if you are doing something that could lead to you losing work on a rule or profile that you are currently creating. When you are finished making rules, be sure to give your profile a name, a description and choose your language in the profile information panel. Then, save your profile and share or edit the profile if you wish. After this, your rule profile is ready to use in the Sentence Rebuilder!

I hope that this guide provided you with enough information to begin creating grammar rules and rebuilding sentences. I look forward to seeing all of the unique grammar rules you create, and I encourage you to share your rules to empower the Rebuilding community.