[Booki-dev] requirements doc *feed back please

[adam hyde]

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

-- 
Adam Hyde
Founder FLOSS Manuals
German mobile : + 49 177 4935122
Email : adam at flossmanuals.net
irc: irc.freenode.net #flossmanuals

"Free manuals for free software"
http://www.flossmanuals.net/about