vform_specs.txt

	/*
	 * 1. VForms
	 * =========
	 * 1.1. Recherche:
	 * -------------
	 * 16.12.2010 - Mischa Kuenzle
	 * Die Formen in formsOldSpelling werden nach neuer Rechtschreibung nicht 
	 * mehr gross geschrieben. Deshalb:
	 * 
	 * 1.1.1. Diskriminante Old/New
	 * --------------------------
	 * Suche alle Forms in formsOldSpelling, ob sie irgendwo im Text ausser 
	 * am Satzanfang vorkommen. Wenn ja, ist das Dokument nach alter 
	 * Rechtschreibung verfasst, und das Dokument sollte nach vforms im Array 
	 * oldSpelling abgesucht werden. Wenn nicht, frage diese Formen gar nicht 
	 * ab, sondern nur diejenigen im Array "forms".
	 * 
	 * 1.1.2. Binnen-Höflichkeitsformen
	 * ------------------------------
	 * 22.12.10 - Christian Waldvogel 
	 * Die "Binnen-Höflichkeitsformen" können in jedem Fall schon
	 * als vforms markiert werden, der Benutzer muss diese nicht auch noch
	 * abnicken!
	 * Es geht dann nur noch um die potentiellen vForms am Satzanfang.
	 * 
	 * 1.1.3. Frage: Was heisst Satzanfang?
	 * 
	 * 
	 * 
	 * 23.12.2010 - Mischa Kuenzle
	 *	
	 * 1.1.3.1. EBNF für Satzende
	 * ------------------------
	
	 Variations:
	 1. Punkt                        Whitespace
	 2. Punkt                        Whitespace QuoteSign
	 3. Punkt QuoteSign              Whitespace
	 4. Punkt QuoteSign              Whitespace QuoteSign

	 5. Punkt           ClosingBrace Whitespace
	 6. Punkt           ClosingBrace Whitespace QuoteSign 
	 7. Punkt QuoteSign ClosingBrace Whitespace
	 8. Punkt QuoteSign ClosingBrace Whitespace QuoteSign 
	
	 9. Punkt           ClosingBrace            QuoteSign Whitespace

	10. (1., 2., 3., 4.) -> Punkt [QuoteSign]                Whitespace [QuoteSign]
	11. (5., 6., 7., 8.) -> Punkt [QuoteSign]  ClosingBrace  Whitespace [QuoteSign]
	12. (10., 11.)       -> Punkt [QuoteSign] [ClosingBrace] Whitespace [QuoteSign]
	
	-> 9 | 12
	
	->  Punkt ((            ClosingBrace              QuoteSign Whitespace)|
		      ([QuoteSign] [ClosingBrace] Whitespace [QuoteSign]))

	PhraseEnd = Punkt (( ClosingBrace QuoteSign Whitespace)|
		      ([QuoteSign] [ClosingBrace] Whitespace [QuoteSign])
		      
	Problem with this syntax: We need 2-symbol lookahead!
	If Punkt [QuoteSign] is followed by ClosingBrace, we need to look at one more sign:
	Is it QuoteSign -> we're in the branch 9.
	Is it Whitespace -> we're in the branch 12.
	Is it something else -> we're not in a PhraseEnd.
	
	Punkt = "." | ":" | "!" | "?".
	
	QuoteSign = '"' | """ | "'" | "'" | "«" | "»" | "‹" | "›" | "〈" | "〉".
	
	ClosingBrace = ")" | "]" | "}".
	
	 * 1.1.3.2. DOM vs. Text
	 * -------------------

	Achtung: Warum wir auf DOM-Ebene und nicht Text-Ebene arbeiten sollten:
	Dies ist ein Beispiel für Satzende-Variation #2.
	Würde aber von der Regexp nicht erkannt, weil uns die pagenum in die Quere
	kommt.
	Beispiel 1 (dtbook-strukturelemente, welche unsere EBNF-Satzende-Grammatik stören):
	<p>
	Er ging zur Arbeit. <pagenum id="page-7" page="normal">7</pagenum> 
	»Sie sind zu spät, Herr Müller!« rief sein Chef.
	</p>
	Beispiel 2 (Markup, welche die EBNF-Grammatik stört):
	<p>
	Er ging zur <em>Migros.</em> 
	»Sie schon wieder, Herr Müller!« rief die Kassiererin.
	</p>
	
	-> Nachteile von DOM: Wie finden wir von der DOM-Repräsentation zurück in den Text?
	-> Ist es erlaubt, dass wir den Text parsen, im DOM verändern und dann zurückschreiben?
	-> dabei könnte Formatierung anders rauskommen.
	-> dabei könnten die Kommentare, Processing Instructions (sonstiges?) verloren gehen.
	-> DOM-Parser im Projekt DtBookParser (warum DOM? Sax nicht, weil ich sonst state
	   zwischen Events pflegen muss)
	
	 * 1.1.3.3. Auf Dtbook-Strukturebene
	 * -------------------------------
	 * - Am Anfang eines
	 * - Paragraphs (<p>)
	 * - Headings (<h[1-6]>)
	 * - <brl:running-line>
	 * - <brl:toc-line>
	 * - Doctitles (<doctitle>)
	 * - Poemzeile (<line>)
	 * - <li> (das keine <lic> enthält)
	 * - <lic>
	 * - <byline>
	 * 
	 * 
	 * Frage: Wann soll dieser Test (1.1.) ablaufen?
	 * Mögliche Zeitpunkte:
	 * 1. Beim Oeffnen eines Dokuments vom Typ dtbook.
	 * 1.1 das Plugin merkt sich *pro Dokument*: boolean oldSPelling.
	 *   1.2 sobald Benutzer nach vforms sucht, wird aufgrund das Flags
	 *       oldSpelling entschieden, ob nur forms oder auch formsOldSpelling
	 *       relevant sind.
	 *   Nachteil: 
	 *   1. Jedes dtbook Dokument wird beim Oeffnen abgesucht, obwohl
	 *      Benutzer evtl. gar nicht vforms checken möchte.
	 *   2. Wenn Benutzer Aenderungen am Dokument vornimmt, welche das Prädikat
	 *      oldSpelling beeinflussen. -> nach jeder Aenderung müsste das
	 *      Prädikat wieder geprüft werden.
	 *      
	 * 2. Sobald Benutzer vforms zu prüfen beginnt.
	 * 2.1 dies setzt voraus, dass wir wissen, wann er *beginnt* und wann er
	 *     fertig ist: Thematik "modal".
	 * 2.2 z.B. Menü PrepTools>VForms: Sobald Benutzer das wählt, wird:
	 *   2.2.1 die VForm Toolbox aktiviert (_3)
	 *   2.2.2 Prüfung auf oldSpelling durchgeführt und für das aktuelle 
	 *         Dokument vermerkt.
	 *   2.2.3 The first VForm is searched, user can choose find/accept
	 *         
	 *   Frage: Wenn Benutzer Dokument wechselt, müsste Toolbar angepasst werden.
	 *   Problem: es gibt showToolbar (_3) aber nicht hideToolbar (_2)
	 *   
	 *  DONE: keys for Toolbar! (_4)
	 *  DONE: skip form that has already been marked up.
	 *  DONE: Find VForms: muss sich merken, ob der Prozess neu gestartet wurde
	 *        wenn Ja: Cursor an Dokumentanfang setzen (_5) und von dort suchen.
	 *        
	 *  Optional:
	 *	- Inhibit text changes during the process
	 *	- Inhibit cursor moves during the process
	 *	- remove other toolbars (_2) until process has completed.
	 *    
	 *  Wenn in PrepTools VForms gewählt wird, und vor Beendigung
	 *  ein anderes Tool gewählt wird, sollte eine Abfrage kommen: Soll die
	 *  VForm-Suche vorzeitig abgebrochen werden?
	 *  What about:
	 (- chooses different document? No: Cursor-Position remains)
	 (- opens different document? No: Cursor-Position remains)
	 *
	 * 1.2. Hypothesis:
	 * ------------
	 * 1. There are 3 (4) Buttons in the toolbar:
	 * - start
	 * - find
	 * - accept
	 * (- continue)
	 * 
	 * DONE We maintain state per document, whether vForm is in process.
	 *      As long as it's not, only the button start is enabled (_e), find and
	 *      accept are disabled. If the document is not a dtbook, all buttons
	 *      are disabled.
	 * tooltips indicate why they are disabled. (_1)
	 * 
	 * 2. user opened dtbook document:
	 * DONE (nice: LED becomes green _g)
	 * DONE user clicks StartVForm. Flag isProcessingVforms = true; for this document
	 * DONE (nice: LED becomes yellow _g)
	 * 
	 * Gesamtes Dokument wird nach formsOldSpelling *ausser am Satzanfang* 
	 * abgesucht. Wenn etwas gefunden wird: Dialogbox mit Statistik anzeigen, wie oft
	 * formsOldSpelling auftreten, sowie der Frage, ob Benutzer alle alten Formen
	 * abnicken möchte. Wenn Benutzer möchte, wird isOldSpelling = true gesetzt und
	 * die Regex beinhaltet alte und neue vforms (Vereinigung von forms und formsOldSpelling).
	 * Alle Binnenvforms (sowohl die in formsOldSpelling und die in forms).
	 * (nice: Es werden dem Benutzer für jede der forms in formsOldSpelling die Häufigkeiten
	 * angezeigt, und er kann mittels Checkbox wählen, welche er abnicken möchte und welche
	 * nicht)
	 * werden schon als solche markiert <brl:v-form>. Ausserdem wird die erste 
	 * potentielle vForm gesucht, gehighlightet (_d) und die Buttons FindVForm,
	 * AcceptVForm werden enabled. Die Erwartung ist nun, dass der Benutzer nur anhand
	 * der Buttons Find/Accept durch das Dokument bis ans Ende navigiert. Wenn er ans
	 * Ende kommt (_6): Dialogbox: Dokument-Ende erreicht mit Angabe, 
	 * welches Tool/Prozess angeben, z.B.: VForms, Parentheses, sowie Statistik.
	 * Für dieses Dokument wird ausserdem Flag isProcessingVforms = false
	 * Benutzer in der Dialogbox eine Checkbox anbieten, ob Statistik in einem
	 * Kommentar <!-- --> oben eingefügt werden soll.
	 * DONE Unterstützung des Prozesses mit einer "LED" im Toolbar (nice):
	 *      Document not yet vformed: green, Document in progress: yellow, Document
	 *      done: blue.
	 * (nice: während der Bearbeitung sieht der Benutzer einen Progressbar und eine
	 * estimated completion time, welche aufgrund der Statistik und seiner persönlichen
	 * Arbeitsgeschwnindigkeit berechnet wird. Nach einem Timeout wird die Zeit nicht
	 * mehr berücksichtigt.)
	 * 
	 * Ausnahmen: Wenn Benutzer während des Prozesses (isProcessingVforms == true)
	 * DONE- StartVForm klickt, wird Dialogbox angezeigt "Start over?" 
	 * DONE (verworfen: startVForm Button disablen)
	 * - Wenn er Dokument schliesst (editorClosed _9), Dialogbox anzeigen "vorzeitig abbrechen?"
	 *   -> leider bekomme ich das erst mit, wenn der editor bereits geschlossen ist!
	 *   -> ich biete Dialog an, das Dokument nochmals zu öffnen. Leider wird beim Oeffnen
	 *      der Editor mit den neuen Dokument nicht automatisch aktiviert.
	 *      Ich finde auch keine Schnittstelle, wie ich einen Tab wählen kann.
	 * DONE Wenn er Applikation beendet (applicationClosing _c), Dialogbox anzeigen "vorzeitig abbrechen?"
	 * DONE Cursor selber plaziert: (_7) Toolbar hat einen weiteren Button "Continue".
	 * DONE  Implemenentation: für jedes Dokument wird die zuletzt bearbeitete Stelle 
	 *   vermerkt (_f).
	 * DONE  Wenn der Cursor bewegt wurde, kann anhand dieser Stelle der vform-Prozess wieder
	 *   aufgenommen werden. 
	 * DONE Text ändert: siehe "Cursor selber plaziert" (_8)?
	 * - anderes Tool wählt: Dialogbox anzeigen "vorzeitig abbrechen?"
	 * (verworfen:- anderes Dokument öffnet (editorOpened _a): siehe "Cursor selber plaziert")
	 * (verworfen:- zu anderem Dokument umschaltet (editorSelected _b):siehe "Cursor selber plaziert"
	 * 
	 * Expected Features of the Oxygen API
	 * _1: Dynamic Change of tooltips for toolbar buttons?
	 * _2: Removing Toolbars (only possible when )
	 * _3: Show Toolbars (StandalonePluginWorkspace.showToolbar)
	 * _4: Keyboard accelerators for toolbar buttons? Yes, except JCheckbox
	 * _5: Put cursor at document start: Yes
	 * _6: Get notified when reaching end of document? Yes.
	 * _7: Get notified by cursor movements? Yes, but only with my own bookkeeping.
	 *     Or by finding the Editorpane to which I can add a CaretListener
	 *     http://download.oracle.com/javase/6/docs/api/javax/swing/event/CaretListener.html
	 *     see addCaretHandler() method somewhere in WorkspacAccessPluginExtension
	 * _8: Get notified by Text changes? Yes.
	 * _9: Get notified by Editorclose? Yes, but I can't veto!
	 * _a: Get notified by EditorOpen? Yes. -> but not when "revert"ing!
	 * _b: Get notified by EditorSelect? Yes, but do I know which editor was selected before?
	 * _c: Get notified by applicationClosing? Yes, I can veto: return false
	 * _d: Highlight (Select) text: Yes.
	 * _e: toolbarbuttons enable/disable: Yes.
	 * _f: Bookmark, which marks a position in the text independently
	 *     of subsequent insertions/deletions? (javax.swing.text.Document): Yes
	 *     javax.swing.text.Position p = document.createPosition(start)
	 * _g: "LED" in the toolbar with configurable colour: Yes
	 * _h: Can I define what an atomic command is? (I'd like to define that
	 *     inserting </brl:v-form> after and <brl:v-form> before a word is
	 *     *one* command (not two separate ones), so an Undo will remove
	 *     both elements.
	 *     3. This is probably a Swing-specific question: How can I define that
	a change to a document is "atomic"? My plugin inserts custom tags
	around certain words found in the document. This is done via document.insertString(). Since these are two inserts, they are tracked as independent actions in the 
	http://download.oracle.com/javase/tutorial/uiswing/components/generaltext.html#undo
	http://download.oracle.com/javase/1.4.2/docs/api/javax/swing/text/Document.html
	 *     
	 * Empirical findings on WSEditorChangeListener:
	 * closing a document, if there's at least one other document open,
	 * we get:
	 * -> editorSelected + url next
	 * -> editorClosed + url closing
	 * -> editorSelected + url next

	 * closing a document, if this is the last document open,
	 * we get:
	 * -> editorClosed + url closing
	 * -> editorSelected + url null
	 * 
	 * Opening a document, we get:
	 * -> editorSelected + new url
	 * -> editorOpened + new url
	 * 
	 * Selecting a document (only possible if there's more than 1)
	 * -> editorSelected + new url
	 * 
	 * Starting the app we get:
	 * -> editorSelected + null (that's all we get when no docs where open)
	 * For each open file:
	 * -> editorSelected + url
	 * -> editorOpened + url
	 * At the end again for each open file:
	 * -> editorSelected + url
	 * 
	 * Conclusion:
	 * editorSelected always gets called when a document is opened.
	 * 
	 * Problems:
	 * - When "Revert" is done on a file, I don't get notified!
	 * - accelerator for checkbox didn't succeed.
	 * 
	 * 
	 * 2. Balanced Parentheses:
	 * ========================
	 * http://redmine.sbszh.ch/issues/show/1059
	 * 
	 */