INSTRUCTIONS
============
SCRSimpleCompileAndPrint.h + .m provides methods for compiling, exporting and printing on the iOS version.

The iOS version should have the following compile, export and print options:
1.  Send Draft - exports everything in the Draft folder as a single document.
    (Available in the main Tools menu.)
2.  Print Draft - prints everything in the Draft folder as a single document.
    (Available in the main Tools menu.)
3.  Send Copies - exports one or more files from the corkboard or outliner.
    (Available from the options menu in the corkboard/outliner footer.)
4.  Send Copy - exports the current document only.
    (Available from the sharing button in the document/inspector header.)
5.  Print Document - prints the current document only.
    (Available from the sharing button in the document/inspector header.)


1. SEND DRAFT
-------------
When you select "Send Draft" from the main Tools menu, the following options should appear in a popup/popover:
* Include Titles
* > Include Titles for Folders Only
* Include Labels and Status
* Include Synopses
* Include Main Text
* Include Notes
* Delete Comments and Annotations
* Plain Text / Rich Text (an option to choose between the two).

To implement:

# GENERATING THE COMPILED TEXT

Call -compiledTextForBinderDocuments:options:delegate: on [SCRSimpleCompileHelper sharedInstance].

- For the BinderDocuments parameter, pass in an array containing all descendants of the Draft folder.
- For the options parameter, use a combination of SCRSimpleCompileOptions that match the options selected by the user.
- Also be sure to pass in a delegate. The delegate should implement the following methods at the very least:

- (NSAttributedString *)mainTextForBinderDocument:(id)binderDoc;
- (NSAttributedString *)notesTextForBinderDocument:(id)binderDoc;
- (NSString *)synopsisStringForBinderDocument:(id)binderDoc;
- (NSString *)labelStringForBinderDocument:(id)binderDoc;
- (NSString *)statusStringForBinderDocument:(id)binderDoc;

For instance, if the user has chosen to include titles, synopses and main text, to generate the compiled text you would call the following:

NSMutableAttributedString *compiledText = [[SCRSimpleCompileHelper sharedInstance] compiledTextForBinderDocuments:[draftFolder exportableDescendants] options:SCRSimpleCompileIncludesTitles|SCRSimpleCompileIncludesSynopses|SCRSimpleCompileIncludesText delegate:(id <SCRSimpleCompileAndPrintDelegate>)self];

(Be sure to include the SCRSimpleCompilePlainTextOnly option if the user chose plain text instead of rich text for the export. This will ensure that line breaks are added instead of page breaks, and it will place markdown-style level-based hash characters before titles.)

Note: If "Ignore 'Include in Compile'" is ticked, you shoul dpass in [draftFolder descendants]; otherwise, you should pass in [draftFolder exportableDescendants] - where "draftFolder" is the SCRBinderDocument object representing the Draft folder, of course.

OPTIONAL DELEGATE METHODS:
There are optional delegate methods that allow you to provide different fonts for the title, synopsis and status. You might want to use a Courier font for the synopses, for instance. By default, the fonts are taken from UIFont's -preferredFontForTextStyle: method, which I believe is better for UI fonts. So you might want to use the delegate methods to provide more suitable fonts. Just make sure the title font is big!

There are also two optional delegate methods for providing a progress bar.
- simpleCompileHelper:willProcessDocumentNumber: is sent to the delegate every time a document is about to be added to the compiled text.
- simpleCompileHelperShouldCancelCompile: is sent to the delegate frequently during compile. If you return YES for this, the Compile will be cancelled and proceed no further.
Thus, you can provide a progress bar, set it up, and then increment it every time you receive a -simpleCompileHelper:willProcessDocumentNumber: message.
And you can provide a cancel button that sets an internal variable to YES, which you can then return from -simpleCompileHelperShouldCancelCompile:. (You'd probably need to set up an NSModalSession for this, if they are supported on iOS. I'm not 100% sure the cancel button will work, that might need more doing.)

# REMOVING COMMENTS AND ANNOTATIONS

If the user ticked "Delete Comments and Annotations", strip all comments and annotations as follows:

[compiledText removeCommentsAndAnnotations];

NOTE: This *must* be done before moving onto the next step.

# EXPORTING THE COMPILED TEXT

Once you have generated the compiled text using SCRSimpleCompileHelper's -compiledTextForBinderDocuments:... method, you will export it differently depending on whether you are exporting to plain or rich text.

RICH TEXT:
// (Note that -extendedRTFFromRange:documentAttributes: is in the NSAttributedString_RTFAdditions file I sent you.)
NSData *rtfData = [compiledText extendedRTFFromRange:NSMakeRange(0,[compiledText length]) documentAttributes:nil];
BOOL success = [rtfData writeToFile:file path atomically:YES];

PLAIN TEXT:
For plain text, you need to process the text first through another method (which is in the SCRSimpleCompileAndPrint files) that will convert all of the footnotes and comments to plain text, as follows:
[compiledText convertForSimplePrintingForPlainText:YES];
BOOL success = [[compiledText string] writeToFile:file atomically:YES encoding:NSUTF8StringEncoding error:nil];


2. PRINT DRAFT
--------------
Print Draft works the same as Send Draft, with the following differences:

- There is no "Plain Text / Rich Text" option in the popup/popover that appears when you select "Print Draft" (all of the other options remain the same as "Send Draft", though.
- You therefore *never* pass SCRSimpleCompilePlainTextOnly to -compiledTextForBinderDocuments:... when printing.

Once you have built the compiledText mutable attributed string using the SCRSimpleCompileHelper -compiledTextFromBinderDocuments:... method along with the relevant options:

1. Call -removeCommentsAndAnnotations on the compiledText object if the user ticked "Delete Comments and Annotations".

2. Call [compiledText convertForSimplePrintingForPlainText:NO] on your compiled text object. This will take all of the footnotes, give them numbers, add them to the end of the document, and it will place square brackets around annotations and comments if they weren't previously removed.

3. You are now ready to use the compiledText object for printing - print it using whatever print routines iOS has available. (I hope they are easier than OS X's, which involves building a bloomin' page layout view just for printing!)


3. SEND COPIES
--------------
When the user ticks one or more files in the outliner or corkboard Edit mode and then taps "Send Copies" in the options menu:

- IF there are any text documents selected, show the following options:
* Delete Comments and Annotations
* Rich Text / Plain Text

- Do *not* show the above options if no text files are selected.

For non-text files, just copy them from the .scriv /Docs folder to the desired location, making sure you give them the name of the document (instead of internal numerical ID). Also ensure that each file is given a unique name so that none overwrite one another (given that documents can have the same name in the binder) and that the document titles are valid file system titles.

For text files:

NSMutableAttributedString *textCopy = [mainText mutableCopy];
// (Where mainText is a KBTextStorage loaded from the project package using -initScrivenerPackageRTF:... etc.)
// Obviously it's important we use a *copy* here and don't edit the original!

If the user ticked "Delete Comments and Annotations":
[textCopy removeCommentsAndAnnotations];

- If the user selected "Rich Text";
NSData *rtfData = [textCopy extendedRTFFromRange:NSMakeRange(0, [textCopy length]) documentAttributes:nil];
BOOL success = [rtfData writeToFile:file atomically:YES];

- If the user selected "Plain Text":
[textCopy convertForSimplePrintingForPlainText:YES];	// Places footnotes at the end of the file using Markdown syntax etc.
BOOL success = [[textCopy string] writeToFile:file atomically:YES encoding:NSUTF8StringEncoding error:nil];


4. SEND COPY
------------
When the user taps the "Share" button at the top of the document and inspector header bar, two options appear in a popup/popover:
* Send Copy
* Print Document

If the user taps "Send Copy", the current document's main text is exported. The following options should then appear:
- Delete Comments and Annotations
- Rich Text / Plain Text

Exporting the text works exactly the same as it does for "3. Send Copies", above, except that we're only dealing with a single file instead of multiple files.


5. PRINT DOCUMENT
-----------------
When the user taps "Print Document" in the document and inspector header bar's "Share" menu, another option appears:
- Delete Comments And Annotations

When the user prints, the following happens:

NSMutableAttributedString *textCopy = [mainText mutableCopy];
// (Where mainText is a KBTextStorage loaded from the project package using -initScrivenerPackageRTF:... etc.)
// Obviously it's important we use a *copy* here and don't edit the original!

If the user ticked "Delete Comments and Annotations":
[textCopy removeCommentsAndAnnotations];

[textCopy convertForSimplePrintingForPlainText:NO];

// Now print textCopy.
