[Booki-dev] requirements doc *feed back please

[adam hyde]

ok cool. I think what would be great if Doug and Raj talk directly and
keep the discussion on this list. I think we can get it done rather
quickly this way - reduce the overhead on implementation and leave it to
the guys that have their hands in the code...good for me if ok with you
guys

adam



On Wed, 2010-06-30 at 07:44 -0700, Brewster Kahle wrote:
> 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.
> >>>
> >

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