[Booki-dev] requirements doc *feed back please

[Brewster Kahle]

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?

-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.
>