[Booki-dev] requirements doc *feed back please

[Brewster Kahle]

terrific.  raj is on baby-leave but back pretty soon.  I am cc'ing 
george who is running the openlibrary project as that will be effected 
by this cool function.   I think we are ready.

-brewster




On 6/30/10 7:39 AM, adam hyde wrote:
> On Wed, 2010-06-30 at 07:34 -0700, Brewster Kahle wrote:
>> just thinking about you guys.  we just launched our books for the
>> blind/dyslexic and also our Digital Lending Library, so we will be
>> turning to adding capabilities like correcting books.
>>
>> is this a good time to go for integrating the services?
>
> very good time Brewster (good to hear from you). I actually emailed Raj
> a week or two ago to say we are good to start on it. Doug is back now
> and Aco is working hard on migration of Fm to booki. So I think we
> should make a plan...
>
> adam
>
>>
>> -brewster
>>
>>
>> On 6/30/10 6:35 AM, adam hyde wrote:
>>> my first attempt>
>>>
>>>
>>> 1 INTRODUCTION
>>>
>>> 1.1 Description
>>> Booki is designed to help you produce books, either by yourself or
>>> collaboratively. A book in this context is a `comprehensive text´ which
>>> can be output to book formatted PDF (for book production), epub, odt,
>>> screen readable PDF, templated HTML and other formats.
>>>
>>> Booki supports the rapid development of content. Booki has tools to
>>> support the development of content in 'Book Sprints'. Book Sprints are
>>> intensive collaborative events where collaborators in real and remote
>>> space focus on writing a book together in 3-5 days.
>>>
>>> While you can use Booki to support very traditional book production
>>> processes, the feature set matches the rapid pace of publishing possible
>>> in the era of print on demand and electronic readers. Booki can output
>>> content immediately to multiple electronic formats. Print ready source
>>> (book formatted PDF) can be immediately generated, and then uploaded to
>>> your favorite Print on Demand (PoD) service, taken to a local printer,
>>> or delivered to a publisher.
>>>
>>>
>>> 1.1 Purpose
>>> Booki embraces social and collaborative networked environments as the
>>> new production spaces for comprehensive (book) content.
>>> 	
>>> 1.2 Scope
>>> Booki is available online as a networked service (http://www.booki.cc)
>>> for free. This service is a production tool for the creation of free
>>> content and not a publishing/hosting service. Content produced within
>>> Booki.cc is intended to be published elsewhere, either under another
>>> domain, in paper form (ie. books), distributed in electronic formats, or
>>> re-used in other content. 		
>>> Booki can be installed by anyone wishing to utilise this software under
>>> their own domain or within private or local networks.
>>> 	
>>>
>>>
>>>
>>> 2 OVERALL DESCRIPTION
>>>
>>> 2.1 Product Perspective
>>> Booki takes what was learned from building the FLOSS Manuals tool set
>>> and posits these lessons within a more suitable architecture.
>>>
>>> Booki is the name of the collaborative production environment, however
>>> there are 2 associated softwares that provide all the services
>>> required :
>>> Booki - production environment
>>> Objavi - import and export engine
>>> This document refers to Booki 1.5 and Objavi 2.2
>>>
>>> 2.2 Booki Functions
>>> * User account creation requiring minimal information
>>> * One click book creation
>>> * Drag and drop Table of Contents creation
>>> * One click editing of chapters
>>> * Chapter level locks
>>> * Live chat on a book and group level
>>> * Live book status reports (editing, saving, chapter creation) delivered
>>> to the chat window
>>> * Drop down chapter status markers
>>> * One click to join a group
>>> * One click to add a book to a group
>>> * One click exporting to epub, screen pdf, book formatted pdf, odt, html
>>> with default templates
>>> * Easily accessible advanced styling options for export (CSS controlled)
>>> * User profile control (status, image, bio)
>>> * One click group creation
>>> * Easy importing of book content from Archive.org, Mediawiki, other
>>> Booki installations
>>> * Option to upload content to Archive.org
>>> 	
>>>
>>> 2.3 User Characteristics
>>> 2.3.1 Contributor
>>> The majority of users will be contributors to an existing project. They
>>> may contribute to one or more project and may produce text and/or
>>> images, provide feedback or encouragement, proof, spell check, or edit
>>> content. These are the primary users and the tool set should first meet
>>> their needs.
>>>
>>> 2.3.2 Maintainer
>>> These are advanced users that create their own books or have been
>>> elevated to maintainer status for a book by group admins. Maintainers
>>> have associated administrative tools for the books they maintain which
>>> are not available to other users.
>>>
>>> 2.3.3 Group admin
>>> These are advanced users that wish to establish and administrate their
>>> own group. They have maintenance tools for every book in their group
>>> plus additional group admin tools.
>>>
>>> 2.4 Operating Environment
>>> Booki is designed primarily for standards based Open Source browser
>>> comparability but is tested against other browsers.	
>>> 	
>>> 2.5 General Constraints
>>> * Booki and Objavi are Python based.
>>> * Booki is built with the (bare) Django framework.
>>> * Booki uses JQuery for dynamic user interface elements.
>>> * Booki uses Postgres as the database but sqlite3 can also be used
>>> * Redis is used by Booki for persistent data storage to mediate dynamic
>>> data delivery to the user interface
>>> * Objavi utilises Webkit for PDF generation. Later Gecko will be added.
>>> * Rendering of .odt by Objavi requires OpenOffice to be installed with
>>> unoconv.
>>> * The Booki Web/IRC gateway may eventually (and optionally) require a
>>> dedicated standalone IRC service hosted on domain.
>>> * Content editing in Booki is done by default with the Xinha WYSIWYG
>>> editor
>>> * XHTML is the file format for content.
>>> * Content will be ultimately be stored in GIT.
>>> * Localisation in Booki is managed with Portable Object files (.po).
>>> * The code repository for both projects is GIT with a dedicated Trac for
>>> bug reporting and milestone tracking :
>>> http://booki-dev.flossmanuals.net
>>> * A Dev mailing list is maintained here:
>>> http://lists.flossmanuals.net/listinfo.cgi/booki-dev-flossmanuals.net
>>> * Developers can be reached in IRC (freenode, #flossmanuals)
>>> * Each release will be as source. Beta and later releases will also be
>>> available as Debian .deb packages.
>>> * User and API Documentation will be maintained in the FLOSS Manuals
>>> Booki Group.
>>> * For development we use Apache2 for http delivery
>>> * The license is GPL2+ for all softwares
>>>
>>> 2.5 User Documentation
>>> Maintained here : http://www.booki.cc/booki-user-guide/
>>>
>>>
>>>
>>> 3 SYSTEM FEATURES
>>>
>>>
>>> 3.1 Booki Features
>>>
>>> 3.1.1 Booki-zip (Internal File Format)
>>> Status: High Priority, Implemented
>>> Function: A Booki-specific file structure for describing books
>>> Interface: Used for internal data exchange between Booki and Objavi.
>>> Notes: booki-zip definition maintained here :
>>> http://booki-dev.flossmanuals.net/git?p=objavi2.git;a=blob_plain;f=htdocs/booki-zip-standard.txt
>>>
>>> 3.1.2 Account Creation
>>> Status: High Priority, Partially Implemented
>>> Function: Quick access to a registration form from the front page for
>>> account creation
>>> Interface: Requires only username, password, email and real name
>>> (required for attribution). Email is sent to the user with autogenerated
>>> link for verification
>>> Notes: email confirmation mechanism missing
>>>
>>> 3.1.3 Sign in
>>> Status: High Priority, Implemented
>>> Function: Quick access to a sign-in form from the front page
>>> Interface: Username and Password form and submit button. Username and
>>> pass remembered.
>>>
>>> 3.1.4 Profile Control
>>> Status: Medium Priority, Implemented
>>> Function: When logged in the user can access a profile settings page to
>>> set personal details (email, name, bio, image). Personal details can be
>>> browsed by other users
>>> Interface: "My Settings" link in user-specific menu on left gives access
>>> to a form for changing the details.
>>>
>>> 3.1.5 Book Creation
>>> Status: High Priority, Implemented
>>> Function: Users can create a book from their homepage ("My Profile").
>>> Interface: User can click on "My Profile" link from the user-specific
>>> menu on the left. On the Profile page a text field for the name of the
>>> book, and a license drop down menu (license *must* be set) is presented.
>>> Clicking on "Create" adds the empty book with edit button to the listing
>>> of the users books on the same page.
>>>
>>> 3.1.6 Archive.org Book Import
>>> Status: Medium Priority, Implemented
>>> Function: Users can import books from Archive.org
>>> Interface: "My Books" link in the user-specific menu on the left
>>> presents the user with a field for inputting the ID of any book from
>>> Archive.org. The book is then imported when the user clicks "Import".
>>> Notes : Interface is through Booki but Objavi does the importing and
>>> returns Booki zip to Booki. Relies on Archive.org successfully
>>> delivering epub for each book but this is not always happening. Needs
>>> error catching and user friendly progress/error messages.
>>>
>>> 3.1.7 Wikibooks Book Import
>>> Status: Medium Priority, Implemented
>>> Function: Users can import books from Wikibooks
>>> (http://en.wikibooks.org)
>>> Interface: "My Books" link in the user-specific menu on the left
>>> presents the user with a field for inputting the URL of any book from
>>> Wikibooks. The book is then imported when the user clicks "Import".
>>> Notes : Interface is through Booki but Objavi does the importing and
>>> returns Booki zip to Booki. Needs thorough testing as it is sometimes
>>> failing possibly due to time-outs. Needs error catching and user
>>> friendly progress/error messages. Should be extended to be a "mediawiki
>>> import" tool, not just for Wikibooks.
>>>
>>> 3.1.8 Epub Book Import
>>> Status: Medium Priority, Implemented
>>> Function: Users can import any epub available online
>>> Interface: "My Books" link in the user-specific menu on the left
>>> presents the user with a field for inputting the URL of any epub. The
>>> book is then imported when the user clicks "Import".
>>> Notes : Interface is through Booki but Objavi does the importing and
>>> returns Booki zip to Booki. Needs thorough testing as it is sometimes
>>> failing possibly due to time-outs. Needs error catching and user
>>> friendly progress/error messages.
>>>
>>> 3.1.9 Group Creation
>>> Status: High Priority, Implemented
>>> Function: Users can create groups.
>>> Interface: "My Groups" link in the user-specific menu on the left
>>> presents user with 2 text fields - group name, and description. When a
>>> name for a group is entered and "Create" is clicked then the group is
>>> created.
>>> Notes: Group admin features missing.
>>>
>>> 3.1.10 Joining Groups
>>> Status: High Priority, Implemented
>>> Function: Users can join groups with one click.
>>> Interface: "Groups" link in the general menu on the left presents a list
>>> of all Groups, by clicking on link the user is transported to the
>>> homepage for that group. At the bottom of the page the user can click
>>> "Join this group" and they are subscribed.
>>>
>>> 3.1.11 Adding Books to Groups
>>> Status: High Priority, Implemented
>>> Function: Users can add their own books to groups they belong to.
>>> Interface: While on a Group page that the user is subscribed to the user
>>> can add their own books to the group.
>>> Notes: When Group Admin features are in place we will change this so
>>> that Group Admins set who can and cannot add books to groups. At present
>>> a book can only belong to one group.
>>>
>>> 3.1.12 Readable Book Display
>>> Status: High Priority, Implemented
>>> Function: Users can read stable content in Booki without the need to
>>> log-in.
>>> Interface: Upon clicking on the "Books" link in the general menu on the
>>> left a page listing all books is presented. Clicking on any of these
>>> presents a basic readable version of the stable content. Alternatively
>>> users can link to a book on the url http://[booki install domain]/[book
>>> name]
>>>
>>> 3.1.13 Edit Page
>>> Status: High Priority, Implemented
>>> Function: Page for editing content.
>>> Interface: The edit page is accessed by clicking on "edit" next to the
>>> name of a book in "My Books" or "Books" (all books) listings. The user
>>> is then presented with a page with tabs for : editing, notes, exporting,
>>> history
>>>
>>> 3.1.14 Edit Tab
>>> Status: High Priority, Implemented
>>> Function: Edit tools and TOC management tool.
>>> Interface: Table of Contents can be created by clicking "Add Chapter" or
>>> "Add Section" and dragging and dropping these elements in the
>>> appropriate order. Clicking on the title will make the title editable.
>>> Clicking edit on a chapter title will open the Xinha WYSIWYG editor with
>>> the content in place.
>>>
>>> 3.1.15 Notes Tab
>>> Status: High Priority, Implemented
>>> Function: A place for contributors to keep notes on the development of
>>> the book
>>> Interface: User clicks on the Notes tab for a book and is presented with
>>> a shared notepad for recording issues or discussing the development.
>>> Notes : Implemented but future direction TBD
>>>
>>> 3.1.16 History Tab
>>> Status: High Priority, Implemented
>>> Function: Shows edit history of the book
>>> Interface: User clicks on the history tab and can see the edit history
>>> with edit notes.
>>> Notes: Implemented but unreadable. Users should also be able to access
>>> diffs here.
>>>
>>> 3.1.17 Export Tab
>>> Status: High Priority, Implemented
>>> Function: Shows edit history of the book
>>> Interface: User clicks on the history tab and can see the edit history
>>> with edit notes.
>>> Notes: Implemented but unreadable. Users should also be able to access
>>> diffs here.
>>>
>>> 3.1.18 Subscribe to edit notifications
>>> Status: High Priority, Not Implemented
>>> Function: Users can subscribe to edit notifications
>>> Interface: User clicks "Subscribe to edit notifications" from the Edit
>>> Page for a book. If there are edits made a synopsis is emailed with
>>> basic edit information (time, chapter, person who made the change,
>>> version numbers) and a link to the diff.
>>>
>>> 3.1.19 Versioning
>>> Status: High priority, Not Implemented
>>> Function: Maintainers can easily freeze content at stable stages while
>>> work continues on the unstable version.
>>> Interface: Details TDB : basic idea is that from the Edit Page a
>>> maintainer sees an extra tab "Version". From here a maintainer can click
>>> "create stable version" - the last stable version is archived recorded
>>> and the current version becomes the new stable version.
>>>
>>> 3.1.20 Chat
>>> Status: High priority, Implemented
>>> Function: A real time chat (web /  IRC gateway).
>>> Interface : Persistent on the edit page for any book.
>>>
>>> 3.1.21 Localisation
>>> Status: High priority, Not Implemented
>>> Function: Booki needs to available in any language where it is needed.
>>> Hence we will integrate the mature Pootle code base into Booki to enable
>>> localisation of the environment.
>>> Interface: TBD
>>>
>>> 3.1.22 Translation
>>> Status: High priority, Not Implemented
>>> Function: Content can be forked and marked for translation. A
>>> translation version of a book will provide link backs to the original
>>> material, be placed in a translation work flow, and edited in a
>>> side-by-side view where the translator can also see the original
>>> source.
>>> Interface: TBD
>>>
>>> 3.1.23 Copyright Tracking (Attribution)
>>> Status: High Priority, Implemented
>>> Function: Any user contributions are recorded and attributed.
>>> Interface: All attributions are automated in Booki. Book level
>>> attribution is output in any chapter that contains the string
>>> "##AUTHORS##"
>>>
>>>
>>>
>>>
>>> 3.2 Objavi Features
>>>
>>> 3.2.1 Book Formatted PDF Output
>>> Status: High Priority, Implemented
>>> Function: the server side creation of Book Formatted PDF is a pivotal
>>> feature. This is managed by Objavi which runs as a separate service. The
>>> book formatted PDF supports Unicode, bi-directional text, and reverse
>>> binding for printing right-to-left texts on a left-to-right press and
>>> vice versa. The formatting engine outputs customisable sizes including
>>> split column PDF suitable for printing on large scale newsprint.
>>> Interface: This feature is managed by Objavi, an API is functional and
>>> feature rich but not well documented at present. Objavi also presents a
>>> web interface for those wanting more nuanced control (see
>>> http://objavi.flossmanuals.net/).
>>>
>>> 3.2.2 CSS Book Design
>>> Status: High Priority, Implemented
>>> Function: The default PDF rendering engine for Booki is now Webkit and
>>> will eventually be Mozilla Firefox hence there is full CSS support for
>>> creating book formatted PDF in Booki. This changes the language of
>>> design from Indesign to CSS – which means any web native can control the
>>> design of the book.
>>>
>>> 3.2.3 Export Formats
>>> Status: High Priority, Implemented
>>> Function: Users also can export to self contained templated (tar.gz)
>>> HTML, to .odt (OpenOffice rich text format), epub, and screen readable
>>> PDF. Other XML output options can be developed as required.
>>>
>