Actions

OPOSSEM

Difference between revisions of "Specifications"

From OPOSSEM

m
 
(156 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
This page lists the proposed specifications for the development of the OPOSSEM wiki.  
 
This page lists the proposed specifications for the development of the OPOSSEM wiki.  
  
 +
The OPOSSEM project is currently (as of 21 May 2012) accepting bids from experienced mediawiki developers interested in completing the development described below. Interested individuals or firms should contact Michelle Dion (dionm@mcmaster.ca) to express interest. Bids should include a total project cost, timeline, and links to examples of previous work, including any contributed extensions or skins. Our funding source requires payment of a fixed price contract for the completed work. We will begin reviewing bids on June 15, 2012. We hope to choose an individual or firm to start development beginning in July 2012.
 +
 
=Wiki Objectives=
 
=Wiki Objectives=
  
Line 11: Line 13:
 
The wiki-based textbook project will address both of these needs by enabling instructors to design a custom textbook option from the wiki-based content that will suit their particular course and to provide that textbook to their students in either Adobe Acrobat (.pdf) format or as a hardcopy distributed through their university bookstore at significantly reduced cost. However, before this is possible, the MediaWiki site hosting the textbook content must be developed and customized.
 
The wiki-based textbook project will address both of these needs by enabling instructors to design a custom textbook option from the wiki-based content that will suit their particular course and to provide that textbook to their students in either Adobe Acrobat (.pdf) format or as a hardcopy distributed through their university bookstore at significantly reduced cost. However, before this is possible, the MediaWiki site hosting the textbook content must be developed and customized.
  
=Wiki Content=
+
= Wiki Content =
  
=Wiki Functional Requirements and Features=
+
Wiki content will include textbook topics related to social science research methods. The content will be written only by members of the OPOSSEM community, which includes both faculty and graduate students. ''This means editing access must be restricted to registered users.''
 +
 
 +
The content will include a number of topics, ideally organized in the smallest possible units, so that instructors can combine the topics they want to have included or covered in their version of a methods textbook.
 +
 
 +
==Custom OPOSSEM namespaces==
 +
In addition to the [[Help:Namespaces |standard namespaces]], OPOSSEM will have several custom namespaces:
 +
*Introductory: Folder in which secondary or basic undergraduate versions of textbook content should be stored. Introductory content should avoid the use of mathematical notation whenever possible.<ref>So what will be left in the "main" namespace? Or, should that be the default for the introductory level materials?  CNL: wouldn't our boilerplate textbook stuff (preface, etc.) go in the main namespace?</ref>
 +
*Intermediate: Folder in which undergraduate versions of textbook content should be stored. Intermediate content may include mathematical notation when needed, but should not go beyond linear algebra (no calculus, no matrix algebra).
 +
*Advanced: Folder in which postgraduate versions of textbook content should be stored. Advanced content is likely to include mathematical notation, including those using calculus and/or maxtrix algebra.
 +
*Notation: This namespace holds snippets of code that format and display math notation on pages. By adding notation here, it ensures that consistent equations and notation are used throughout the text. A custom extension [similar in function to the reference systems] will be developed so that on each page where notation is displayed it adds a section at the bottom of the page labeled "Notation" that would list in one place all the notation used in the page/chapter as a reference. NOTE: This namespace will replace the existing Equation namespace. All the content of the Equation namespace must be moved to the new Notation namespace and all existing links to the moved pages will need to be updated.
 +
*Def: This namespace holds glossary terms and definitions. A custom extension would enable authors to 'tag' or mark any word in the text with a special link that would not only link to the definition hosted by OPOSSEM, but it would also automatically reproduce at the end of the page a list of the links to all the definitions tagged on that page (similar to the Cite extension functions).<ref>Note: One way to populate these pages would be to import the corresponding page from Wikipedia in a static version, which would provide a starting point for the OPOSSEM community to edit/refine the definition for our purposes. So during the initial drafting of the textbook, it would be good to add tags around particular words in the text that will become glossary terms (e.g., [[Def:Variance]]). Then, an admin could look at all the needed definitions and export/import the corresponding Wikipedia page, which our users could then modify/update as appropriate for our community.</ref>
 +
 
 +
==Pages in the namespaces Introductory, Intermediate, and Advanced==
 +
Each page in one of these namespaces will be the core of the textbook. The pages should contain the smallest unit possible that might need to be combined to form a custom textbook chapter.<ref>OPOSSEM editors will need to write up Manual of Style and related instructions about how these namespaces/pages differ, including guidelines about their organization.</ref> Pages will have the following content or design features:
 +
 
 +
*Subpages:
 +
#Examples
 +
#Questions
 +
*Additional content based on a custom extension like the Cite extenstion, which allows a user to tag certain text in the main part of an article but have formatted content appear after a subheading at the end of the article:
 +
#List of math notations that appear in the topic
 +
#List of keywords or glossary terms used in the topic (with linked to glossary entries)
 +
#References
 +
 
 +
==User created books and User bookshelf==
  
==Optimization and security==
+
Users must be able to select a list of pages (including pages they have created in their user area, such as [[User:Michelle_Dion/POLS784courseoutline#Course_Policies]]) and easily (re)organize these pages in a customized order to form a book, which can then: be saved to the User's "bookshelf," a separate area to house their personalized collections of pages. All books on the bookshelf will be public, and any visitor can browse the books on user bookshelves.<ref>'''QUESTION for TEAM: Should users be able to make their own books "private"? And, how to handle hosting books for students, but also potentially giving the option of restricting access on our site to registered users? Thoughts? ''' [PAS: If it isn't much trouble, seems fairly harmless to me. Doubt that many people will use it but I could imagine someone might --  e.g. sort of as an internal library and avoiding cluttering things for others. But not a priority]
The site must be optimized to minimize server calls and facilitate fast page loading. The site must be secure.
 
  
==Single-sign-on (SSO)==
+
(SN, personally, I wouldn't see myself using it. If I'm going to use a saved version of the text for class, I'm likely going to download it as a pdf or other file type and then post it in D2L/blackboard/etc.  I see it as a place for me to get the version of the book I want and then give it to my students rather than sending them straight to the site. But I don't see a downside to allowing others to do it if it is relatively easy to do so. I think we should encourage people to share their version as good citizens of an open source community.)  '''MD: OK. I'm going to leave it all public.'''</ref>
The site must implement single-sign-on using cookies (not LDAP, not OpenID, not Shibboleth, etc.) with our existing Drupal site (opossem.org), using Bakery or another similar tool. Users will sign-on only through the Drupal site (opossem.org, master) and be redirected to the Wiki (wiki.opossem.org, slave). Users will not be allowed to modify their user name or password from within the wiki, and this function should be disabled in the wiki. Any changes must be made on the Drupal site and then propagated to the Wiki site in a true "sync." That is, changes to the user name, email, or password on the Drupal site must be updated to the Wiki automatically without admin intervention nor the creation of duplicate accounts.
 
  
==User page and talk==
+
Registered users should be able to "save" (by copying) someone else's book to their own bookshelf. It should be a copy so that if the first user deletes the book, the  copy remains.
  
The user page in the Wiki (for example, User:Michelle_Dion) should be pre-populated with a link to the user's profile page on the main site (http://opossem.org/content/michelle-dion), if possible. The user talk page will keep its default features.  
+
These books should also be available to be downloaded as:
 +
#LaTeX (cf: http://www.mediawiki.org/wiki/Extension:Wiki2LaTeX)
 +
#Acrobat .pdf
 +
#epub (cf: http://www.mediawiki.org/wiki/Extension:EPubExport)
 +
#Open document format (.odt) (cf: http://www.mediawiki.org/wiki/Extension:OpenDocument_Export, although the new version of Extensions:Collection claims to include this, too)
 +
#HTML5<ref>'''[By registered users only? Or anyone? Or user has option to choose?]''' [PAS: See comments above: if we've got LaTeX, pdf and epub, there are converters into any other other format that is reasonably widespread, and otherwise we are opening a can of worms.]
  
Users should be able to customize the notification settings for their talk pages, but they should not be able to change the email address to which notifications are sent. These should always go to registered email address in the Drupal database, which is kept in sync with the user tables in the Wiki.
+
(SN: I think you should have to be a registered user to download the text but obviously the whole site is available for viewing to non-registered users.  I don't know why this is my preference as I can't think of any specific downside to everyone being able to download, but it would be my first instinct.) '''MD: Ok, I think I'll leave it "open" for now, in case instructors want to refer their students directly to their bookshelf.'''</ref>
  
==User roles & permissions==
+
These features should be like those available in the [http://www.mediawiki.org/wiki/Extension:Collection%7C Create Book tool], but with the added provision that books are automatically be saved as associated with a particular user, and then are stored in a standardized location, named the User's bookshelf. Users should also be able to easily save someone else's book to their own bookshelf, and then have the option to edit their own version of it. Again, it looks like [http://www.mediawiki.org/wiki/Collection_Extension_2 a proposed revision of Collection] would have many of these features included.  
User roles will be defined in the Drupal site and should be copied to the user table of the Wiki site, where they will inherit Wiki permissions defined below (or in the sections on the different features).  
 
  
===admin===
+
There must also be the capacity to run a query (perhaps using http://www.mediawiki.org/wiki/Extension:Validator) that audits the created textbook to ensure all internal references work (e.g. that all pages or subpages referenced in included material are included), so people don't end up with incomplete books. The query would return a list of missing pages and provide the user with the option of adding those pages.
  
===editor===
+
The default output for the [http://www.mediawiki.org/wiki/Extension:Collection%7C Create Book tool] includes a list of contributors to the individual pages. For example: [[File:Contributors.png]]
  
===member===
+
This must be modified to include after each contributor's name in parentheses the percentage of the character count contributed by that user. The contributors should be listed in descending order of percentage contribution (i.e., with the person with the greatest percentage contribution listed first). In particular, the percentage should be calculated as = # of characters contributed by user/the total number of characters on the page.
  
== Future updates ==
+
In addition, as explain above, the Notes and References for each page should appear ''at the end of the chapter'', rather than after the page. In addition, all notation that appears in the chapter should also appear again after a Subheading "Notation."
  
Whenever possible, customization to standard extensions should be minimized so that the site is easily maintained. Any customization or modification to existing extensions must be documented.  
+
All words tagged as definitions should also appear at the end of the chapter after a subheading "Definitions."<ref>Should this be "Glossary Terms" or some other name?</ref> This should just be a display list at the end of the Chapter. At the end of the Book, all the words that appear on any page should be listed under a Heading as Definitions, and the full text of the Definition entry should be printed there.
  
== Download/Output options  ==
+
A user's book should include either the live or the stable version of the book they have chosen to include, and it should be static as long as it is saved on their bookshelf. There should be the option (perhaps a button) when they "open" the book, to run a query that will look to see whether there have been a) any revisions to the pages in their book and b) which of those revisions are new stable versions. If the query returns links to both the current version and the most recent "approved" version, then registered users should then be able to visit that updated page and replace it in their book. <ref>(SN: Query: What happens if I have my saved version of the book, which only includes the sections I find relevant, and then the static version of the text changes to include the new revisions? Will my book now have all of the sections I chose but with the most current revisions, or will it have the revisions as of the time I created my book? If I plan to use the same version year to year, I can see the advantages of both. It would be nice if when I created my book I had the option of whether or not I wanted revisions to automatically be updated or not or perhaps just an email or a message the next time I logged in that asks if I want to incorporate the revisions into my version.) MD: Does this address your concern? </ref>
  
Users should be able to download any page, or collection of pages (see books below), in each of the following formats:
+
== Illustration of how page content should be stored or available for editing ==
 +
*Blue = main page
 +
*Red = subpages of main page  
 +
*Green = display of any Notation namespace pages transcluded anywhere in the main page, in order of transclusion on the page
 +
*Teal = list of words in page with an internal link to a page in the Def namespace
 +
*Orange = Standardized references using the Cite.php extension
  
#XML
 
#LaTeX
 
#Acrobat .pdf
 
#epub
 
#Kindle
 
#mobi?
 
#'''OTHERS?'''
 
  
==User created books and User bookshelf==
+
[[File:Textbook editing.png|RTENOTITLE]]
  
Users must be able to select a list of pages (including pages they have created in their user area, such as [[User:Michelle_Dion/POLS784courseoutline#Course_Policies]]) and easily (re)organize these pages in a customized order to form a book, which can then: be saved to the User's "bookshelf," a separate area to house their personalized collections of pages. All books on the bookshelf will be public, and any visitor can browse the books on user bookshelves.
+
== Example of how a registered user should be able to organize content into a new page, or chapter ==
  
'''QUESTION for TEAM: Should users be able to make their own books "private"? And, how to handle hosting books for students, but also potentially giving the option of restricting access on our site to registered users? Thoughts?''' 
+
Users should be able to combine pages using a custom extension (similar in function to [http://www.mediawiki.org/wiki/Extension:Collection Extension:Collection]), but with hierarchy that will allow groups of pages to be combined into a "chapter" (really a page with the other pages transcluded in it) where the new page or chapter has the following format: 
  
Registered users should be able to "save" someone else's book to their bookshelf.  
+
[[File:Textbook-saving.png|RTENOTITLE]]
  
These books should also be available to be downloaded as XML, LaTex, or Acrobat.pdf and '''(OTHER FORMATS??)''' [By registered users only? Or anyone? Or user has option to choose?]
+
The key difference here is that the notation, glossary, and references would all be combined and grouped at the end of a collection of pages.  
  
These features should be like those available in the Create Book tool, but with the added provision that books are automatically be saved as associated with a particular user, and then are stored in a standardized location, or the User's bookshelf. Users should also be able to easily save someone else's book to their own bookshelf, and then have the option to edit their own version of it.  
+
It seems there is already an effort underway to support the [http://www.mediawiki.org/wiki/Collection_Extension_2 revision of the Collection Extension], and many of the proposed features would be things we would like our custom extension to do.
  
 
==OPOSSEM library==
 
==OPOSSEM library==
Line 71: Line 96:
 
*Book Title
 
*Book Title
  
==Functions that allow contributors to easily add and organize new content==
+
Ideally, next to each title/book, there would be a "downloads" count displayed.
 +
 
 +
==Creating and organizing new content==
 +
===Preloaded content for pages in particular namespaces===
 +
 
 +
# New pages in the main content namespaces (Main, Introductory, Intermediate, and Advanced) should be preloaded with the content necessary to execute all the features needed. For now, an example, using the [http://www.mediawiki.org/wiki/Extension:Preloader Preloader Extension], can be found at [[Template:New_page | here]].
 +
# New pages in the Def namespace should be preloaded with the contents of [[Template:Definition]].
 +
# New pages in the Notation namesapace should be preloaded with the contents of [[Template:Equation]], but this template should be re-named Template:Notation.
  
===Equations===
+
===Notation (formerly Equations)===
Equations must have a separate namespace and must be protected so that only editors can change equations. All textbook pages must include hidden text (that is, that can be viewed only when editing) that advises those that edit pages on how to use existing equations in their page and where to look up the list of existing equations.  
+
Notation must have a separate namespace and must be protected so that only editors can change the contents. All textbook pages must have a hidden banner (that is, that can be viewed only when editing) that advises those that edit pages on how to use existing notation in their page and where to look up the list of existing notation.
  
 
===Glossary===
 
===Glossary===
A separate namespace will be needed for keyword definitions or glossary terms. In the text, these keywords will be marked, and should automatically be transcluded to the bottom of any page on which the section of text appears (like the reference system).  
+
A separate namespace will be needed for keyword definitions or glossary terms. In the text, these keywords will be marked, and should automatically be transcluded to the bottom of any page on which the section of text appears (like the reference system).
 +
 
 +
We will provide an extensive list of keywords, and the most recent Wikipedia definition for these keywords should be imported to the OPOSSEM glossary to provide a starting point for our community to edit the definitions.<ref>[PAS Query: Is the updating from Wikipedia automatic or something that we trigger manually? We would also want the option of ''not'' updating from Wikipedia to deal with situations where the Wikipedia definitions diverge (probably by getting too complex) from what we find useful, though in that instance we would probably still want to include a Wikipedia link](SN: I think the idea was just to grab some content for the definitions initially that could be edited with no further linkage or regular updating of wikipedia content intended.  I could be wrong though) '''MD here: Yes, the idea is to import some initial content from wikipedia, which our community would then prune/edit for our purposes.'''</ref>
 +
 
 +
===Examples, Problems and Questions===
 +
Examples, problems and/or questions should also be associated with each section of text, and be included as subpages of the main page/section of text. The main page should display at the bottom of the electronic version a list of the subpages below that page. This can be accomplished with the [http://www.mediawiki.org/wiki/Extension:SubPageList Extension:SubPageList] and code like
 +
 
 +
<nowiki>= Examples, Problems and Questions =
  
We will provide an extensive list of keywords, and the most recent Wikipedia definition for these keywords should be imported to the OPOSSEM glossary to provide a starting point for our community to edit the definitions. 
+
<subpages format="ol" pathstyle="no" showpage="no" kidsonly="no" /></nowiki>
  
===Problems/Questions===
+
This list should appear in the online version, but should be excluded from the print or book version (see [http://en.wikipedia.org/wiki/Category:Exclude_in_print Category:Exclude_in_print). Users will still have the option of manually choosing or adding the questions, examples, etc. included as subpages to their books for printing/downloading.
Problems and/or questions should also be associated with each section of text, and these, too, should automatically 'follow' the text and be transcluded (wc?) to the bottom of whatever new page they appear upon. Again, this would be similar to the reference system.  
 
  
===Examples===
+
Example subpages should be tagged by field and subfield (e.g. sociology, Canadian politics, etc.) using categories.<ref>NOTE: This is another custom/manual item that will need to be explained in the OPOSSEM documentation by someone.</ref>
Examples should also be associated with each section of text, and these, too, should automatically 'follow' the text and be transcluded (wc?) to the bottom of whatever new page they appear upon. Again, this would be similar to the reference system.
 
  
==Specific pages that should be created==
+
===Forking/Branching Pages<ref>Please see if my edits below capture the intent.</ref>===
  
===Main Page===
+
A custom extension (perhaps based on [http://www.mediawiki.org/wiki/Extension:Duplicator Extension:Duplicator]) should be developed to have the following features/options:
  
What should this have on it?
+
# In the toolbox on each page in the Main, Introductory, Intermediate, and Advanced namespaces, a link should appear that says "Copy page." When clicked, this should take the user to the Special:Duplicator page, and prepopulate the page to be copied in the appropriate field.
 +
# The Special:Duplicator page should give the user two options (as toggle buttons) for where to save the new copy of the page: as a subpage of the original page being copied OR as a subpage in the user's storage area. Above or below these two options should appear the following text: "You are about to create a new copy of this page. Before you do so, please review the related pages in the other Namespaces to see whether they might meet your needs. If you believe there is an error on this page or that it could be improved, please consider editing the page itself or start a discussion its Talk page. If you ''must'' create a new copy, please store personal versions in your user storage area. If you believe your new version is an appropriate fork or variation, please save it as a subpage of the page you are copying."
 +
# The copied page should retain all the revision history and contributor information, for attribution purposes.
  
===How to get involved===
+
=Wiki Functional Requirements and Features=
This page will have text that invites OPOSSEM community members to get involved, with a number of suggestions.  
+
 
 +
==Hosting configuration==
 +
Currently, the site is hosted/configured at wiki.opossem.org. However, to conform with current recommended practice, the site should be hosted at opossem.org/wiki.
 +
 
 +
The project already has hosting provided on a virtual server through McMaster University Library, and developers will be provided with the required shell and FTP access to develop and deploy the site. Upon completion of development, University staff will become responsible for updates and maintenance.
 +
 
 +
== Updates ==
 +
Mediawiki should be updated to the most stable recent release that will sustain the required extensions. Whenever possible, customization of standard extensions should be minimized so that the site is easily maintained. Any customization or modification to existing extensions must be documented.
 +
 
 +
== Math ==
 +
The latest versions of Mediawiki have removed the Math feature from the core. However, our users need the ability to use the <nowiki><math></nowiki> tags to add mathematical notation using LaTeX. Any security issues [http://www.mediawiki.org/wiki/Extension:TrustedMath ??] should be addressed to allow LaTeX markup to be used. Or use alternative LaTeX editors (e.g., http://www.mediawiki.org/wiki/Extension:MathJax) as required to facilitate editing in LaTeX.
 +
 
 +
== Extensions & Templates ==
 +
All the templates necessary to ensure proper function of an installed Extension should be imported and revised as necessary for use in OPOSSEM.
 +
 
 +
== Distribution of custom extensions or features ==
 +
The developer is encouraged to contribute any custom extensions or tools developed for the OPOSSEM wiki to any and all relevant open source repositories. It is requested that the extension files acknowledge support from the OPOSSEM project (opossem.org) and the Centre for Leadership in Learning at McMaster University (cll.mcmaster.ca).
 +
 
 +
==Optimization and security==
 +
The site must be optimized to minimize server calls and facilitate fast page loading. The site must be secure.
 +
 
 +
==File uploads==
 +
Image and other file uploads should be configured to allow the largest upload allowed by the McMaster virtual server configuration, and the file upload page should include this file size limit. It is currently 7MB, but ideally would be up to 15MB.<ref>Michelle needs to check with John to see what the limit is.</ref>
 +
 
 +
Currently, the permitted file types include: png, gif, jpg, jpeg, doc, xls, mpp, pdf, ppt, tiff, bmp, docx, xlsx, pptx, ps, odt, ods, odp, odg.
 +
 
 +
To this list should be added the following file extensions:<ref>Team: what other file types might we need/allow? As an aside, we had a discussion in Toronto about developing a recommended practice of uploading one-off images or files directly to the wiki, but that if a user had a custom dataset or .do file to modify a publicly available dataset for the purpose of contributing multiple examples to the textbook, they should add the files to the "intstructional materials" part of the main site, and link to those anywhere in the textbook that the files are used.</ref>
 +
 
 +
In addition, the Licensing fields of the [[Special:Upload]] page should be configured to include the following options:
 +
*CC BY-NC-SA (set as default)
 +
*CC BY-NC-ND
 +
and
 +
*No copyright (e.g., http://creativecommons.org/publicdomain/mark/1.0/)
 +
 
 +
On the [[Special:Upload]] page, below the Licensing field, there should be the following text:
 +
Additional information about Creative Commons license options can be found [http://creativecommons.org/licenses/ here].
 +
 
 +
==Single-sign-on (SSO)==
 +
The site must implement single-sign-on using cookies (not LDAP, not OpenID, not Shibboleth, etc.) with our existing Drupal site (opossem.org), using Bakery or another similar tool. Users will sign-on only through the Drupal site (opossem.org, master) and be redirected to the Wiki (wiki.opossem.org, slave). Users will not be allowed to modify their user name or password from within the wiki, and this function should be disabled in the wiki. Any changes must be made on the Drupal site and then propagated to the Wiki site in a true "sync." Fields that should be synced automatically without admin intervention nor the creation of duplicate accounts:
 +
*user name,
 +
*first name
 +
*last name,
 +
*email, and
 +
*user roles (Contributor, Editor, Admin).
 +
 
 +
Clicking "login" on the wiki site should redirect to the Drupal login page, and likewise, clicking logout on either site should logout the user.
 +
 
 +
==Display names/attribution==
 +
Rather than the username, the fields for FirstName and LastName should be used throughout for author attribution.
 +
 
 +
==User page and talk==
 +
The user talk page will keep its default features. Users should be able to customize the notification settings for their talk pages, but they should ''not'' be able to change the email address to which notifications are sent. These should always go to registered email address in the Drupal database, which is kept in sync with the user tables in the Wiki.
 +
 
 +
== Official page versions ==
 +
 
 +
The [http://www.mediawiki.org/wiki/Extension:FlaggedRevs Flagged Revisions Extension] (or a comparable alternative) should be used so that Editors can approve changes to particular pages in the Main, Introductory, Intermediate, and Advanced namespaces. The default view of any page should be the "live" wiki version of the page (including any changes that have yet to be approved).
 +
 
 +
Each summer (and perhaps winter, too), editors will review changes to pages since the last official version of the page and "approve" changes to create the official/protected version of the page.
 +
 
 +
The [http://www.mediawiki.org/wiki/Extension:FlaggedRevs Flagged Revisions Extension] may need to be customized or modified to archive each of these "approved" versions, which should be stamped with the year/issue of the revision. For instance, the "official" versions will numbered:
 +
* 2012.1
 +
* 2012.2
 +
* 2012.3
 +
* 2013.1
 +
 
 +
This will allow users to find the most recent "stable" version, but also have a numbering system that is flexible enough for editors to adjust the "issue" or version timing.<ref> '''Question for Team: Need to figure out how to explain this because we'll want annual editions of the textbook to stay static.''' [PAS: Correct, and version control is really important, but I'm guessing that in the early stages, annual will be too infrequent -- what about starting at least with the assumption of two updates a year, 1 Jan and 1 July, or maybe 1 Dec and 1 June so people have some time to get changes in place before the start of the winter semester/quarter]. '''MD:''' You're right, Phil. And we can decide how frequently the review/approved versions get updated later. Right now, we need to provide feedback about how we would like these archived versions to be organized/stored. '''In particular,''' we need to decide if we want to request custom categories of review status (see http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology, for the defaults), or if we just want to tell the wiki developers that we want the 'stable' version to be based on the most recent version of a page that meets some certain threshold across the 3 categories, for example: Accurate, Moderate, Good.</ref>
 +
 
 +
There will need to be a Special:Page (or some other type of page) that allows users to view:
 +
* all the most recent stable/official versions (as opposed to the live version)
 +
* choose a specific official version (e.g., 2012.1) and see a link to all pages that were included in that version.<ref>Does this make sense? How could it be clearer?</ref>
 +
 
 +
There will need to be the possibility for a registered user to view/download/save to their book collection any of the prior "stable" versions of their choosing.
 +
 
 +
== Download/Output options  ==
 +
 
 +
Users should be able to download any page, or collection of pages (see books below), in each of the following formats:
 +
 +
#LaTeX (cf: http://www.mediawiki.org/wiki/Extension:Wiki2LaTeX)
 +
#Acrobat .pdf
 +
#epub (cf: http://www.mediawiki.org/wiki/Extension:EPubExport)
 +
#Open document format (.odt) (cf: http://www.mediawiki.org/wiki/Extension:OpenDocument_Export, although the new version of Extensions:Collection claims to include this, too)
 +
#HTML5 + CSS<ref>[PAS: So, here's my read on this situation, but I'm not an expert on it and would be happy to hear other opinions.
 +
 
 +
It ''seems'' as though epub is clearly emerging as the dominant non-proprietary standard (and seems stable), and then there are converters which can go from epub to Kindle and mobi -- in particular, calibre, which is open source. The only major platform that currently doesn't support epub is, of course, the Kindle, but it is possible Amazon will stop being jackasses and do so, particularly since Apple and Android do support it. So seems to me we assume that epub is our "core" e-book format, and then just use converters, even though the results might not be quite a slick (though .mobi seems mostly to support a bunch of things we wouldn't use anyway). My sense -- and I say this as someone who uses Kindle software on my phone and laptop almost daily -- is that for the student audience, making sure it works on the iPad and on small laptops (MacAir and the various Windows equivalents) is more important than working on the Kindle or phones -- in particular, graphics and anything except simple equations will be really hard on a phone. And Kindles seem more common for leisure reading, and of course the older Kindles don't support color. The new "Fire" does, but seems to have disabled epub support despite running on the Android system. Though they are getting a lot of flak for this from users. But they are Amazon.
 +
 
 +
By "XML", do you mean the raw Wiki text? The other format that might be useful would be HTML5, though that might be subsumed under the XML format, and there are also LaTeX to HTML programs.
 +
'''MD:''' Ok, so after consulting with my in-house Information Professional (i.e. grad student husband) it seems that most people wouldn't have a need for the XML, and anyone geeky enough to need it would be able to figure out that you can already export any mediawiki page as XML using [[Special:Export]]. HTML5 would be good, however, because I might imaging someone wanting to export the textbook (or parts) as HTML5, which they then upload as a page to the proprietary Desire2Learn, Blackboard, etc. system. Again, happy to hear other opinions.]
 +
(SN: As long as people have the option to convert easily (i.e. not having to download a random converter they are unlikely to use for much else), I would support the less is more approach.  As an instructor, I would be more likely to use my kindle, but I agree that my students likely wouldn't.)
 +
CNL: Seems to me we'd want to include PDF as an option just simply because it should be the easiest for someone to put on dead trees without having to find any fancy converter software.  These days you can dump a PDF on a flash drive and plug it directly into a laser printer... not so much with Word files or HTML or epub...
 +
</ref>
 +
 
 +
Most of these output types are included in the updated version of http://www.mediawiki.org/wiki/Extension:Collection.
 +
 
 +
== Ability to process/translate .odt and LaTeX files into MediaWiki markup ==
 +
 
 +
Ideally, it would be possible for users to contribute content as new pages or parts of existing pages based on documents they already have in another file/syntax format, including .odt, .doc, and/or .tex.
 +
 
 +
If possible, a custom tool to translate such content into in mediawiki markup, which the user could then copy/paste into the relevant pages, would be ideal.
 +
 
 +
This could be a Special:Page where registered users copy/paste OR upload the document, it is processed by the server, and then displayed in mediawiki markup for them to copy/paste into the desired page.
  
This page must also include lists of the following pages:
+
(see, for example: http://www.mediawiki.org/wiki/Extension:Word2MediaWikiPlus)
  
All the pages in the OPOSSEM namespace
+
==Banners==
 +
*See [[OPOSSEM:Specifications/CleanupBanners| list of Cleanup Banners]] to be imported (some with modifications) from Wikipedia.
 +
For reference: [[wikipedia:Wikipedia:Template_messages/Cleanup]]
 +
===Additional banners that should be created for OPOSSEM use===
 +
*All pages in Namespaces:Introductory,Intermediate, and Advanced should have a banner (that can be dismissed) that appears only on the edit page above the edit box that says:
 +
#Before editing, please consult the OPOSSEM Manual of Style.
 +
#Use of inline notation should be limited. Instead, notation should be added to Namespace:Notation and transcluded here with tags. 
 +
* Banner to warn that there is inline notation on a page, perhaps based on [http://en.wikipedia.org/wiki/Template:Cleanup-remainder this cleanup template].
 +
* All pages in Namespace:Notation should have a banner that displays on the Namespace page but that is not transcluded with the text that says: "Warning: You are about to edit notation that may appear on multiple pages throughout the site. Please make sure any edits conform with OPOSSEM's Manual of Style."<ref>Team: Any other banners or special headlines that we might need to appear on the site?</ref>
  
All the pages listed in the Maintenance reports section of [[Special:SpecialPages]]
+
==User roles & permissions==
 +
Visitors to the site who are not registered users (through the main Drupal site) may read pages and browse the OPOSSEM library (including downloading versions of collections/books listed there). They should also be able to "export" pages using the export function. They should not, however, be able to create collections/books or edit any pages.
  
All the pages listed in the List of pages section of [[Special:SpecialPages]]
+
Other user roles for registered users will be assigned in the Drupal site and should be synced to the user table of the Wiki site, where they will inherit Wiki permissions defined below. Additional permissions/restrictions are included in descriptions of specific extensions/functions elsewhere in this document. 
  
===Tools for Editors===
+
Since all users will inherit their user group from the Drupal site, the [[Special:UserRights]] page should be disabled for all users except Admins.
This page should include the relevant links for editors to use. This includes all the links in the '''Quality Assurance''' section of [[Special:SpecialPages]].
 
  
Anything an editor can do but that no other users can do should appear on this page to make it easier for editors to see what tools they have.
+
Users should be able to belong to multiple groups, or inherit rights of the group below them where the hierarchy is:
 +
# Admin,
 +
# Editor, and
 +
# Contributor,
  
===Official page versions===
+
unless an exception/deviation is noted below.<ref>See [[Special:ListGroupRights]] for a list of group rights.</ref>
Each July 1 (or thereabouts), editors will review changes to the pages since the last official version of the page and "approve" changes to create the official/protected version of the page.  
 
  
Visitors and members can view either the current version of the "official/protected" or 'flagged' version of pages.  
+
{| class="wikitable"
 +
|-
 +
! action
 +
! Admin
 +
! Editor
 +
! Contributor
 +
|-
 +
| Inherit all default Bureaucrat rights
 +
| X
 +
|
 +
|
 +
|-
 +
| Inherit all default Reviewer rights
 +
| X
 +
| X
 +
|
 +
|-
 +
| Inherit all default User rights
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Edit pages (in default & main Namespaces, including Intro, Intermediate, Advanced, etc.)
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Edit templates
 +
| X
 +
| X
 +
|
 +
|-
 +
| Create pages (in default & main Namespaces, including Intro, Intermediate, Advanced, etc.)
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Create templates
 +
| X
 +
| X
 +
|
 +
|-
 +
| Create notation
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Edit notation
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Create definitions
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Edit definitions
 +
| X
 +
| X
 +
| X
 +
|-
 +
| Import pages
 +
| X
 +
| X
 +
|
 +
|-
 +
| Delete pages
 +
| X
 +
|
 +
|
 +
|-
 +
| Protect pages*
 +
| X
 +
| X
 +
|
 +
|}
  
There must be a page that lists all "flagged" or reviewed pages, with the date of their most recent review.  
+
<nowiki>*</nowiki>This is a deviation from the usual group permissions.
  
See [[Special:ReviewedPages]]. '''Question for Team: Need to figure out how to explain this because we'll want annual editions of the textbook to stay static.'''  
+
== User contributions ==
  
=== User contributions ===
+
User contributions must be displayed in a way that is easy for external reviewers/department chairs to "see" and evaluate. The default page view for User contributions (e.g., [[Special:Contributions/Michelle Dion]]) does not meet this requirement.<ref>[PAS: Have we had any further feedback on what reviewers/chairs would ''like'' to see in this regard? I could drop a line to the PolMeth fellows list --- which has a lot of former administrators, but mostly research universities --- and see if I get any ideas; is there something comparable we could get on the liberal arts college side? Also if we need some customized code for this part, I'm willing to put some work in on this piece (all the more so if that code could be perl or Python...) '''MD here:''' No, we haven't had any feedback on this specific feature. My thinking was that we needed to have a way to show a list of pages to which a person has contributed, and then, each page should clearly show what portions of the text was contributed by the particular user (as opposed to others). So, that was the goal of the formatting below. All this content is stored in the database, it's just a matter of having the programmer put together a custom view that pulls the various pieces together as needed. I think this is something the developer(s) should be able to do.]</ref>
  
User contributions must be displayed in a way that is easy for external reviewers/department chairs to "see" and evaluate. The default page view for User contributions (e.g., [[Special:Contributions/Michelle Dion]]) does not meet this requirement.
 
  
In addition to the default contributions view, a custom view should be created for each user that will each page the user has edited. When the link to that page is clicked from this list, it will return a copy of the current page with the following characteristics:
+
In addition to the default contributions view (for example, [[Special:Contributions/Michelle_Dion]]), a custom page/view should be created for each user that will list each page or subpage the user has edited. Next to the title of the page on this list, the names of all the contributors to the page in descending order of percentage contribution (like the printed book contribution section: [[OPOSSEM:Specifications#User_created_books_and_User_bookshelf]]) should be listed. After each name, it should also include the date of the most recent revision to the page by each user. For instance: Michelle Dion (55%, 2012 May 10), Phil Schrodt (28%, 2012 May 5), and Shane Nordyke (17%, 2012 May 6). Those who have contributed fewer than 3% of the characters and/or all of whom's edits were marked as "minor edits" should be excluded from the calculation and list. In addition, there should be a link to "Download .pdf version" in this list, which when clicked would produce a .pdf version like that described below.
  
 +
When the link to that page is clicked from this list, it will return a copy of the current page with the following characteristics:
 
Display <ins>current</ins> version of page with content contributed by user (black) and others (grey) plus:  
 
Display <ins>current</ins> version of page with content contributed by user (black) and others (grey) plus:  
  
Line 135: Line 359:
 
*Grey text = Contributed by another user  
 
*Grey text = Contributed by another user  
 
*Black text with strikeout = Text contributed by user and deleted by another user  
 
*Black text with strikeout = Text contributed by user and deleted by another user  
*Grey text with strikeout = Texas contributed by another user and deleted by user
+
*Grey text with strikeout = Text contributed by another user and deleted by user
  
Example  
+
===Example ===
  
{| width="90%" border="1" align="left" cellpadding="1" cellspacing="1"
+
{| width="100%" border="1" align="left" cellpadding="1" cellspacing="1"
 
|-
 
|-
 
|  
 
|  
<span style="line-height: 19px;">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur bibendum ullamcorper viverra. Donec malesuada nulla nec augue aliquam eget mattis justo lacinia. Nunc mattis tempor lorem nec scelerisque. Donec aliquam tincidunt arcu, a egestas ante ultrices eget.&nbsp;</span><span style="line-height: 19px; color: rgb(191, 191, 191);">Curabitur neque orci, rhoncus vitae gravida eu, blandit in nisl.</span><span style="line-height: 19px;">&nbsp;Aliquam dui nisi, tincidunt sit amet lobortis gravida, rutrum eu elit. Donec lacinia, ante dignissim auctor dapibus, nulla nunc accumsan enim, eget vestibulum nibh est at mi. Ut enim eros, iaculis et fringilla sit amet, ullamcorper non urna. Nunc id semper sapien. </span>
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur bibendum ullamcorper viverra. Donec malesuada nulla nec augue aliquam eget mattis justo lacinia. Nunc mattis tempor lorem nec scelerisque. Donec aliquam tincidunt arcu, a egestas ante ultrices eget.&nbsp;<span style="line-height: 19px; color: rgb(191, 191, 191);">Curabitur neque orci, rhoncus vitae gravida eu, blandit in nisl. Aliquam dui nisi, tincidunt sit amet lobortis gravida, rutrum eu elit. Donec lacinia, ante dignissim auctor dapibus, nulla nunc accumsan enim, eget vestibulum nibh est at mi. Ut enim eros, iaculis et fringilla sit amet, ullamcorper non urna. Nunc id semper sapien.
  
<span style="line-height: 19px;" /><span style="line-height: 19px;">Cras faucibus malesuada pellentesque. Phasellus vitae magna diam, non iaculis dui. Aliquam hendrerit pellentesque ipsum, quis accumsan risus adipiscing nec.&nbsp;</span><span style="line-height: 19px; color: rgb(191, 191, 191);">In vel tellus orci. Donec libero nunc, tristique non bibendum viverra, fermentum ut leo. Cras porta pharetra justo. Nulla aliquam placerat leo, a eleifend ligula tincidunt in.&nbsp;<del>Maecenas dapibus, urna quis varius tincidunt, diam magna hendrerit massa, eget eleifend sem ante et massa</del></span><span style="line-height: 19px;">. In et lacus ut quam venenatis consequat sit amet vitae eros. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin vulputate imperdiet nulla vel varius. Sed porttitor suscipit venenatis.&nbsp;</span><del style="line-height: 19px;">Aenean tortor velit, sodales porttitor dapibus non, rhoncus ac lacus. Quisque aliquam adipiscing nisl at adipiscing. Pellentesque sodales sem a quam consequat tincidunt. Etiam orci eros, placerat in rhoncus a, tempor ut sapien.</del><span style="line-height: 19px;">&nbsp;</span>
+
Cras faucibus malesuada pellentesque. Phasellus vitae magna diam, non iaculis dui. Aliquam hendrerit pellentesque ipsum, quis accumsan risus adipiscing nec.<span style="line-height: 19px; color: rgb(191, 191, 191);">In vel tellus orci. Donec libero nunc, tristique non bibendum viverra, fermentum ut leo. Cras porta pharetra justo. Nulla aliquam placerat leo, a eleifend ligula tincidunt in.&nbsp;<del>Maecenas dapibus, urna quis varius tincidunt, diam magna hendrerit massa, eget eleifend sem ante et massa</del></span><span style="line-height: 19px;">. In et lacus ut quam venenatis consequat sit amet vitae eros. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin vulputate imperdiet nulla vel varius. Sed porttitor suscipit venenatis.&nbsp;</span><del style="line-height: 19px;">Aenean tortor velit, sodales porttitor dapibus non, rhoncus ac lacus. Quisque aliquam adipiscing nisl at adipiscing. Pellentesque sodales sem a quam consequat tincidunt. Etiam orci eros, placerat in rhoncus a, tempor ut sapien.</del>
  
 
<span style="line-height: 19px;">Morbi tempor libero vitae neque consequat tristique. Morbi nisi dui, egestas at faucibus sed, tempor eu risus. Quisque faucibus molestie lectus, quis feugiat metus lobortis sit amet. Aenean et fringilla est. Sed turpis est, tempus ut aliquam id, consequat sed enim. Suspendisse interdum arcu sit amet tellus fermentum nec egestas purus scelerisque. Praesent at molestie quam. Proin eget augue vitae justo porttitor sodales. Nunc et lectus vitae nulla fringilla interdum non sit amet ante. Sed nec nibh ligula, non venenatis mi. Curabitur ultrices, nisl id faucibus laoreet, purus mi tempor tellus, id iaculis ipsum eros sed turpis. Curabitur luctus erat fermentum augue mattis ac dapibus mi lacinia.</span>
 
<span style="line-height: 19px;">Morbi tempor libero vitae neque consequat tristique. Morbi nisi dui, egestas at faucibus sed, tempor eu risus. Quisque faucibus molestie lectus, quis feugiat metus lobortis sit amet. Aenean et fringilla est. Sed turpis est, tempus ut aliquam id, consequat sed enim. Suspendisse interdum arcu sit amet tellus fermentum nec egestas purus scelerisque. Praesent at molestie quam. Proin eget augue vitae justo porttitor sodales. Nunc et lectus vitae nulla fringilla interdum non sit amet ante. Sed nec nibh ligula, non venenatis mi. Curabitur ultrices, nisl id faucibus laoreet, purus mi tempor tellus, id iaculis ipsum eros sed turpis. Curabitur luctus erat fermentum augue mattis ac dapibus mi lacinia.</span>
 +
|}
 +
 +
<br> <br>
 +
At the bottom of the online page view, it should display a list all the contributors to the page in descending order of percentage contribution (like the printed book contribution section: [[OPOSSEM:Specifications#User_created_books_and_User_bookshelf]]. After each name, it should also include the date of the most recent revision to the page by each user. For instance: Michelle Dion (55%, 2012 May 10), Phil Schrodt (28%, 2012 May 5), and Shane Nordyke (17%, 2012 May 6). Those who have contributed fewer than 3% of the characters and/or all of whom's edits were marked as "minor edits" should be excluded from the calculation and list.
 +
 +
In addition, there should be a list of the collections/books of which the page is a part, which would provide an additonal measure of use or impact of the particular page.
  
|}
+
The page should also have a button at the top or bottom of the page that says "Download this page," and when clicked, it would produce a .pdf version of the page to be viewed in a new browser window or downloaded, and the downloaded page should also include the formatted list of contributors, including their percentages, and the list of books mod which it is a part.<ref>
<blockquote><br></blockquote>  
+
'''Question for team:''' Should dates be included?? How/where?(SN:  I think dates are a good idea, and the field will already be collected.  Could we have the date show up when you scroll over the edit with your mouse?  That seems like the most convenient place, but it wouldn't be printable.)'''MD:'''Does this address the issue sufficiently?</ref>
<br>  
+
 
 +
=Specific pages that should be created=
 +
 
 +
==Main Page==
 +
 
 +
The main page should have a brief overview of the textbook project (e.g., http://wiki.opossem.org/index.php?title=OPOSSEM:Specifications#Wiki_Objectives). In addition, the main page should provide a clear link to "Login" [which will redirect to the Drupal site]. It should also have a prominent link to the "How to get involved page" (below).<ref>(SN: I think it would be useful to have a brief history of the what and why.  At the CanCon conference there was a lot of discussion the first day on what added value this project had to what was already available and how it fit into other markets.  I assumed that a lot of the value added was relatively obvious, but it wasn't so we should take time to explain that somewhere.</ref>
 +
 
 +
It should also perhaps have links to the top five pages in each of the following categories/page types:
 +
5 most recently updated pages
 +
5 users that have most recently updated a page
 +
5 users with the greatest number of pages revised
 +
5 users with the greatest number of new pages created<ref>Any others that might appeal to user vanity?</ref> 
 +
 
 +
It should also have a link to the OPOSSEM library, and ideally, would list the 5 most downloaded "books" in the collective library.
 +
 
 +
Once someone is logged in, this page should have a direct link to their bookshelf, and, if possible, it would be nice to have a memory built in so that you could see your most recent activity on the book (last page edited, etc.)
 +
 
 +
==How to get involved==
 +
This page will have text that invites OPOSSEM community members to get involved, with a number of suggestions.
 +
 
 +
This page must also include a list of links to the following custom pages:
 +
 
 +
# A page that lists all the pages in the OPOSSEM namespace
 +
# A page that lists all the pages in the Help namespace
 +
# A page that lists all the pages in the Introductory namespace
 +
# A page that lists all the pages in the Intermediate namespace
 +
# A page that lists all the pages in the Advanced namespace
 +
# [[Special:FewestRevisions]]
 +
# [[Special:ShortPages]]
 +
# [[Special:UnwatchedPages]]
 +
# [[Special:WantedPages]]
 +
# A page that lists all the pages tagged with one of the cleanup banners
 +
# A page that lists all the pages that have been marked by Editors as sighted, basic, or good (or lower) (see: http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology Flagged Revisions Terminology]
 +
# [[Special:UnreviewedPages]]
 +
 
 +
 
 +
All the pages listed in the Maintenance reports section of [[Special:SpecialPages]]
 +
 
 +
All the pages listed in the List of pages section of [[Special:SpecialPages]]
  
<br>
+
==Tools for Editors==
 +
This page should include the relevant links for editors to use. This includes all the links in the '''Quality Assurance''' section of [[Special:SpecialPages]].
  
<br>
+
Anything an editor can do but that no other users can do should appear on this page to make it easier for editors to see what tools they have.
  
<br>
+
There should also be a link to a list of Special pages generated by the [http://www.mediawiki.org/wiki/Extension:FlaggedRevs Flagged Revisions Extension], including:
 +
* [[Special:ReviewedPages]]] - pages which have a stable version
 +
* [[Special:OldReviewedPages]] - pages that have pending changes from the stable version.
 +
* [[Special:ProblemChanges]] - pages that have pending changes from the stable version that also have recent changes tags.
 +
* [[Special:UnreviewedPages]] - pages that have no reviewed stable version.
  
<br>
+
These links will enable editors to quickly find a list of pages that need review since the last set of reviews.
  
'''Question for team:''' Should dates be included?? How/where?
+
In addition, there should be a link to view all pages tagged with banners that warn of inappropriate content. Editors should automatically be notified by email when any page gets one of those banners added.<ref>PAS:We need a facility for sending alerts to the editors in case of incorrect/inappropriate content. '''MD:''' I think this should work. However, we need to identify a list of the banners that we think we should be notified about. Here's an annotated list of available clean up banners: [http://en.wikipedia.org/wiki/Cleanup_templates ], many of which (and some others), I've already identified to be imported and/or modified for our use (see [[OPOSSEM:Specifications/CleanupBanners]]. Once development begins, someone will need to let the developer know which of these clean up banners should trigger a notification. </ref>
  
===Others?===
+
==Others?==
  
=Wiki design=
+
=Wiki visual design=
 
The MediaWiki skin or website design must incorporate design elements from the existing OPOSSEM Drupal site. In particular, the Wiki site must:  
 
The MediaWiki skin or website design must incorporate design elements from the existing OPOSSEM Drupal site. In particular, the Wiki site must:  
 
# Use visual elements, the logo, and colors already in use on the Drupal site
 
# Use visual elements, the logo, and colors already in use on the Drupal site
Line 170: Line 443:
  
 
The wiki need not look ''exactly'' like the Drupal site and indeed should look more like a book or wiki site than the main Drupal site. That is, the Wiki theme need not be fully integrated into the main Drupal site, but the two sites should share common design elements and a similar 'look'.
 
The wiki need not look ''exactly'' like the Drupal site and indeed should look more like a book or wiki site than the main Drupal site. That is, the Wiki theme need not be fully integrated into the main Drupal site, but the two sites should share common design elements and a similar 'look'.
 +
 +
==Skins==
 +
[http://gomediawiki.com/wiki/Free_wiki_skin Free Wiki Skin] seems fairly similar already to the main site, and perhaps could be easily adapted for OPOSSEM. Another skin that has a very different feel from Wikipedia and would perhaps be easy to adapt to look like OPOSSEM is [http://www.unifiedrepublicofstars.com/reference/The_Unified_Republic_of_Stars:Skin Erudite].
 +
 +
=Wiki extensions=
 +
All active extensions are listed on the [[Special:Version]] page.
 +
 +
List of special extensions for reference:
 +
*Collection - create books
 +
*Delete Batch - deletes a batch of pages
 +
*Flagged Revisions - Gives Editors and Reviewers the ability to review revisions and stabilize pages
 +
*Nuke - Gives administrators the ability to mass delete pages
 +
*SpecialInterwiki - Adds a special page to view and edit the interwiki table
 +
*User Merge and Delete - Merges references from one user to another user in the wiki database - will also delete old users following merge. Requires usermerge privileges
 +
*AuthDrupal - Signin integration for MediaWiki as slave of Drupal.
 +
*Category Tree - The CategoryTree extension provides a dynamic view of the wiki's category structure as a tree
 +
*Cite - Adds <ref[ name=id]> and references /> tags, for citations
 +
*InputBox - Allow inclusion of predefined HTML forms
 +
*ParserFunctions - Enhance parser with logical functions
 +
*SyntaxHighlight - Provides syntax highlighting using GeSHi Highlighter
 +
*WYSIWYG extension - Extension for editing wiki pages (WYSIWYG editor) [The newer versions of Mediawiki have a built in WYSIWYG editor.]
 +
*Preloader - Provides customisable per-namespace boilerplate text for new pages
 +
*SubPageList - Provides facility to list subpages on their parent page
 +
*Validator - supports SubPageList
 +
 +
=Notes=
 +
{{reflist}}

Latest revision as of 11:51, 21 May 2012

This page lists the proposed specifications for the development of the OPOSSEM wiki.

The OPOSSEM project is currently (as of 21 May 2012) accepting bids from experienced mediawiki developers interested in completing the development described below. Interested individuals or firms should contact Michelle Dion (dionm@mcmaster.ca) to express interest. Bids should include a total project cost, timeline, and links to examples of previous work, including any contributed extensions or skins. Our funding source requires payment of a fixed price contract for the completed work. We will begin reviewing bids on June 15, 2012. We hope to choose an individual or firm to start development beginning in July 2012.

Wiki Objectives[edit]

OPOSSEM, the Online Portal of Social Science Education in Methodology, is an online portal to facilitate sharing of various resources for teaching social science research methods (particularly statistical methods) among educators in secondary, undergraduate, and postgraduate settings. Little educational material is freely available to serve the needs of basic research methods courses in the social sciences, particularly political science. The creation of problem sets and lecture notes is time-intensive, and methods courses requiring such preparation are becoming more widespread across all types of institutions. This project seeks to reduce these start-up costs and enhance methods instruction by providing an online space in which instructors can share materials and information. Community members are able to post to the discussion forum, share teaching materials (syllabi, lecture notes, assignments, or working papers on teaching research methods), suggest external resources (online data source, resources for students or instructors, or published research on teaching research methods), or rate community content.

The proposed wiki-based, online textbook project responds to two needs. First, as suggested above, the range of textbook options for instructors of undergraduate research methods is quite limited. Instructors must take most textbooks as all or nothing propositions, without having flexibility to adjust content to their particular course’s learning objectives. The poor fit between the available texts and the learning objectives creates situations where students struggle not only to learn new quantitative methods that are unfamiliar and intimidating to them but must do so with examples that are not clearly related to their own political science or backgrounds. Student learning would be enhanced were they to have access to content that more clearly linked the research methods to the theories and approaches they learn in other political science class and to their own experiences.

Second, research methods textbooks are quite expensive for students, even though the core content (i.e., the equations, methods) in the text changes little from edition to edition. Compared to other textbooks in political science, research methods texts, with the costs of typesetting equations and the sometimes extensive use of figures, are often at least 50% more expensive for students. This creates a burden for students with limited resources, who cannot easily afford such texts.

The wiki-based textbook project will address both of these needs by enabling instructors to design a custom textbook option from the wiki-based content that will suit their particular course and to provide that textbook to their students in either Adobe Acrobat (.pdf) format or as a hardcopy distributed through their university bookstore at significantly reduced cost. However, before this is possible, the MediaWiki site hosting the textbook content must be developed and customized.

Wiki Content[edit]

Wiki content will include textbook topics related to social science research methods. The content will be written only by members of the OPOSSEM community, which includes both faculty and graduate students. This means editing access must be restricted to registered users.

The content will include a number of topics, ideally organized in the smallest possible units, so that instructors can combine the topics they want to have included or covered in their version of a methods textbook.

Custom OPOSSEM namespaces[edit]

In addition to the standard namespaces, OPOSSEM will have several custom namespaces:

  • Introductory: Folder in which secondary or basic undergraduate versions of textbook content should be stored. Introductory content should avoid the use of mathematical notation whenever possible.<ref>So what will be left in the "main" namespace? Or, should that be the default for the introductory level materials? CNL: wouldn't our boilerplate textbook stuff (preface, etc.) go in the main namespace?</ref>
  • Intermediate: Folder in which undergraduate versions of textbook content should be stored. Intermediate content may include mathematical notation when needed, but should not go beyond linear algebra (no calculus, no matrix algebra).
  • Advanced: Folder in which postgraduate versions of textbook content should be stored. Advanced content is likely to include mathematical notation, including those using calculus and/or maxtrix algebra.
  • Notation: This namespace holds snippets of code that format and display math notation on pages. By adding notation here, it ensures that consistent equations and notation are used throughout the text. A custom extension [similar in function to the reference systems] will be developed so that on each page where notation is displayed it adds a section at the bottom of the page labeled "Notation" that would list in one place all the notation used in the page/chapter as a reference. NOTE: This namespace will replace the existing Equation namespace. All the content of the Equation namespace must be moved to the new Notation namespace and all existing links to the moved pages will need to be updated.
  • Def: This namespace holds glossary terms and definitions. A custom extension would enable authors to 'tag' or mark any word in the text with a special link that would not only link to the definition hosted by OPOSSEM, but it would also automatically reproduce at the end of the page a list of the links to all the definitions tagged on that page (similar to the Cite extension functions).<ref>Note: One way to populate these pages would be to import the corresponding page from Wikipedia in a static version, which would provide a starting point for the OPOSSEM community to edit/refine the definition for our purposes. So during the initial drafting of the textbook, it would be good to add tags around particular words in the text that will become glossary terms (e.g., Def:Variance). Then, an admin could look at all the needed definitions and export/import the corresponding Wikipedia page, which our users could then modify/update as appropriate for our community.</ref>

Pages in the namespaces Introductory, Intermediate, and Advanced[edit]

Each page in one of these namespaces will be the core of the textbook. The pages should contain the smallest unit possible that might need to be combined to form a custom textbook chapter.<ref>OPOSSEM editors will need to write up Manual of Style and related instructions about how these namespaces/pages differ, including guidelines about their organization.</ref> Pages will have the following content or design features:

  • Subpages:
  1. Examples
  2. Questions
  • Additional content based on a custom extension like the Cite extenstion, which allows a user to tag certain text in the main part of an article but have formatted content appear after a subheading at the end of the article:
  1. List of math notations that appear in the topic
  2. List of keywords or glossary terms used in the topic (with linked to glossary entries)
  3. References

User created books and User bookshelf[edit]

Users must be able to select a list of pages (including pages they have created in their user area, such as User:Michelle_Dion/POLS784courseoutline#Course_Policies) and easily (re)organize these pages in a customized order to form a book, which can then: be saved to the User's "bookshelf," a separate area to house their personalized collections of pages. All books on the bookshelf will be public, and any visitor can browse the books on user bookshelves.<ref>QUESTION for TEAM: Should users be able to make their own books "private"? And, how to handle hosting books for students, but also potentially giving the option of restricting access on our site to registered users? Thoughts? [PAS: If it isn't much trouble, seems fairly harmless to me. Doubt that many people will use it but I could imagine someone might -- e.g. sort of as an internal library and avoiding cluttering things for others. But not a priority]

(SN, personally, I wouldn't see myself using it. If I'm going to use a saved version of the text for class, I'm likely going to download it as a pdf or other file type and then post it in D2L/blackboard/etc. I see it as a place for me to get the version of the book I want and then give it to my students rather than sending them straight to the site. But I don't see a downside to allowing others to do it if it is relatively easy to do so. I think we should encourage people to share their version as good citizens of an open source community.) MD: OK. I'm going to leave it all public.</ref>

Registered users should be able to "save" (by copying) someone else's book to their own bookshelf. It should be a copy so that if the first user deletes the book, the copy remains.

These books should also be available to be downloaded as:

  1. LaTeX (cf: http://www.mediawiki.org/wiki/Extension:Wiki2LaTeX)
  2. Acrobat .pdf
  3. epub (cf: http://www.mediawiki.org/wiki/Extension:EPubExport)
  4. Open document format (.odt) (cf: http://www.mediawiki.org/wiki/Extension:OpenDocument_Export, although the new version of Extensions:Collection claims to include this, too)
  5. HTML5<ref>[By registered users only? Or anyone? Or user has option to choose?] [PAS: See comments above: if we've got LaTeX, pdf and epub, there are converters into any other other format that is reasonably widespread, and otherwise we are opening a can of worms.]

(SN: I think you should have to be a registered user to download the text but obviously the whole site is available for viewing to non-registered users. I don't know why this is my preference as I can't think of any specific downside to everyone being able to download, but it would be my first instinct.) MD: Ok, I think I'll leave it "open" for now, in case instructors want to refer their students directly to their bookshelf.</ref>

These features should be like those available in the Create Book tool, but with the added provision that books are automatically be saved as associated with a particular user, and then are stored in a standardized location, named the User's bookshelf. Users should also be able to easily save someone else's book to their own bookshelf, and then have the option to edit their own version of it. Again, it looks like a proposed revision of Collection would have many of these features included.

There must also be the capacity to run a query (perhaps using http://www.mediawiki.org/wiki/Extension:Validator) that audits the created textbook to ensure all internal references work (e.g. that all pages or subpages referenced in included material are included), so people don't end up with incomplete books. The query would return a list of missing pages and provide the user with the option of adding those pages.

The default output for the Create Book tool includes a list of contributors to the individual pages. For example:
Error creating thumbnail: Unable to save thumbnail to destination

This must be modified to include after each contributor's name in parentheses the percentage of the character count contributed by that user. The contributors should be listed in descending order of percentage contribution (i.e., with the person with the greatest percentage contribution listed first). In particular, the percentage should be calculated as = # of characters contributed by user/the total number of characters on the page.

In addition, as explain above, the Notes and References for each page should appear at the end of the chapter, rather than after the page. In addition, all notation that appears in the chapter should also appear again after a Subheading "Notation."

All words tagged as definitions should also appear at the end of the chapter after a subheading "Definitions."<ref>Should this be "Glossary Terms" or some other name?</ref> This should just be a display list at the end of the Chapter. At the end of the Book, all the words that appear on any page should be listed under a Heading as Definitions, and the full text of the Definition entry should be printed there.

A user's book should include either the live or the stable version of the book they have chosen to include, and it should be static as long as it is saved on their bookshelf. There should be the option (perhaps a button) when they "open" the book, to run a query that will look to see whether there have been a) any revisions to the pages in their book and b) which of those revisions are new stable versions. If the query returns links to both the current version and the most recent "approved" version, then registered users should then be able to visit that updated page and replace it in their book. <ref>(SN: Query: What happens if I have my saved version of the book, which only includes the sections I find relevant, and then the static version of the text changes to include the new revisions? Will my book now have all of the sections I chose but with the most current revisions, or will it have the revisions as of the time I created my book? If I plan to use the same version year to year, I can see the advantages of both. It would be nice if when I created my book I had the option of whether or not I wanted revisions to automatically be updated or not or perhaps just an email or a message the next time I logged in that asks if I want to incorporate the revisions into my version.) MD: Does this address your concern? </ref>

Illustration of how page content should be stored or available for editing[edit]

  • Blue = main page
  • Red = subpages of main page
  • Green = display of any Notation namespace pages transcluded anywhere in the main page, in order of transclusion on the page
  • Teal = list of words in page with an internal link to a page in the Def namespace
  • Orange = Standardized references using the Cite.php extension


Error creating thumbnail: Unable to save thumbnail to destination

Example of how a registered user should be able to organize content into a new page, or chapter[edit]

Users should be able to combine pages using a custom extension (similar in function to Extension:Collection), but with hierarchy that will allow groups of pages to be combined into a "chapter" (really a page with the other pages transcluded in it) where the new page or chapter has the following format:

Error creating thumbnail: Unable to save thumbnail to destination

The key difference here is that the notation, glossary, and references would all be combined and grouped at the end of a collection of pages.

It seems there is already an effort underway to support the revision of the Collection Extension, and many of the proposed features would be things we would like our custom extension to do.

OPOSSEM library[edit]

Visitors must be able to browse the books that have been saved by users and the saved books should be listed (or sortable) by the following characteristics:

  • User name (the person on whose bookshelf the book resides)
  • Most viewed (or downloaded)
  • Most recently updated
  • Book Title

Ideally, next to each title/book, there would be a "downloads" count displayed.

Creating and organizing new content[edit]

Preloaded content for pages in particular namespaces[edit]

  1. New pages in the main content namespaces (Main, Introductory, Intermediate, and Advanced) should be preloaded with the content necessary to execute all the features needed. For now, an example, using the Preloader Extension, can be found at here.
  2. New pages in the Def namespace should be preloaded with the contents of Template:Definition.
  3. New pages in the Notation namesapace should be preloaded with the contents of Template:Equation, but this template should be re-named Template:Notation.

Notation (formerly Equations)[edit]

Notation must have a separate namespace and must be protected so that only editors can change the contents. All textbook pages must have a hidden banner (that is, that can be viewed only when editing) that advises those that edit pages on how to use existing notation in their page and where to look up the list of existing notation.

Glossary[edit]

A separate namespace will be needed for keyword definitions or glossary terms. In the text, these keywords will be marked, and should automatically be transcluded to the bottom of any page on which the section of text appears (like the reference system).

We will provide an extensive list of keywords, and the most recent Wikipedia definition for these keywords should be imported to the OPOSSEM glossary to provide a starting point for our community to edit the definitions.<ref>[PAS Query: Is the updating from Wikipedia automatic or something that we trigger manually? We would also want the option of not updating from Wikipedia to deal with situations where the Wikipedia definitions diverge (probably by getting too complex) from what we find useful, though in that instance we would probably still want to include a Wikipedia link](SN: I think the idea was just to grab some content for the definitions initially that could be edited with no further linkage or regular updating of wikipedia content intended. I could be wrong though) MD here: Yes, the idea is to import some initial content from wikipedia, which our community would then prune/edit for our purposes.</ref>

Examples, Problems and Questions[edit]

Examples, problems and/or questions should also be associated with each section of text, and be included as subpages of the main page/section of text. The main page should display at the bottom of the electronic version a list of the subpages below that page. This can be accomplished with the Extension:SubPageList and code like

= Examples, Problems and Questions = <subpages format="ol" pathstyle="no" showpage="no" kidsonly="no" />

This list should appear in the online version, but should be excluded from the print or book version (see [http://en.wikipedia.org/wiki/Category:Exclude_in_print Category:Exclude_in_print). Users will still have the option of manually choosing or adding the questions, examples, etc. included as subpages to their books for printing/downloading.

Example subpages should be tagged by field and subfield (e.g. sociology, Canadian politics, etc.) using categories.<ref>NOTE: This is another custom/manual item that will need to be explained in the OPOSSEM documentation by someone.</ref>

Forking/Branching Pages<ref>Please see if my edits below capture the intent.</ref>[edit]

A custom extension (perhaps based on Extension:Duplicator) should be developed to have the following features/options:

  1. In the toolbox on each page in the Main, Introductory, Intermediate, and Advanced namespaces, a link should appear that says "Copy page." When clicked, this should take the user to the Special:Duplicator page, and prepopulate the page to be copied in the appropriate field.
  2. The Special:Duplicator page should give the user two options (as toggle buttons) for where to save the new copy of the page: as a subpage of the original page being copied OR as a subpage in the user's storage area. Above or below these two options should appear the following text: "You are about to create a new copy of this page. Before you do so, please review the related pages in the other Namespaces to see whether they might meet your needs. If you believe there is an error on this page or that it could be improved, please consider editing the page itself or start a discussion its Talk page. If you must create a new copy, please store personal versions in your user storage area. If you believe your new version is an appropriate fork or variation, please save it as a subpage of the page you are copying."
  3. The copied page should retain all the revision history and contributor information, for attribution purposes.

Wiki Functional Requirements and Features[edit]

Hosting configuration[edit]

Currently, the site is hosted/configured at wiki.opossem.org. However, to conform with current recommended practice, the site should be hosted at opossem.org/wiki.

The project already has hosting provided on a virtual server through McMaster University Library, and developers will be provided with the required shell and FTP access to develop and deploy the site. Upon completion of development, University staff will become responsible for updates and maintenance.

Updates[edit]

Mediawiki should be updated to the most stable recent release that will sustain the required extensions. Whenever possible, customization of standard extensions should be minimized so that the site is easily maintained. Any customization or modification to existing extensions must be documented.

Math[edit]

The latest versions of Mediawiki have removed the Math feature from the core. However, our users need the ability to use the <math> tags to add mathematical notation using LaTeX. Any security issues ?? should be addressed to allow LaTeX markup to be used. Or use alternative LaTeX editors (e.g., http://www.mediawiki.org/wiki/Extension:MathJax) as required to facilitate editing in LaTeX.

Extensions & Templates[edit]

All the templates necessary to ensure proper function of an installed Extension should be imported and revised as necessary for use in OPOSSEM.

Distribution of custom extensions or features[edit]

The developer is encouraged to contribute any custom extensions or tools developed for the OPOSSEM wiki to any and all relevant open source repositories. It is requested that the extension files acknowledge support from the OPOSSEM project (opossem.org) and the Centre for Leadership in Learning at McMaster University (cll.mcmaster.ca).

Optimization and security[edit]

The site must be optimized to minimize server calls and facilitate fast page loading. The site must be secure.

File uploads[edit]

Image and other file uploads should be configured to allow the largest upload allowed by the McMaster virtual server configuration, and the file upload page should include this file size limit. It is currently 7MB, but ideally would be up to 15MB.<ref>Michelle needs to check with John to see what the limit is.</ref>

Currently, the permitted file types include: png, gif, jpg, jpeg, doc, xls, mpp, pdf, ppt, tiff, bmp, docx, xlsx, pptx, ps, odt, ods, odp, odg.

To this list should be added the following file extensions:<ref>Team: what other file types might we need/allow? As an aside, we had a discussion in Toronto about developing a recommended practice of uploading one-off images or files directly to the wiki, but that if a user had a custom dataset or .do file to modify a publicly available dataset for the purpose of contributing multiple examples to the textbook, they should add the files to the "intstructional materials" part of the main site, and link to those anywhere in the textbook that the files are used.</ref>

In addition, the Licensing fields of the Special:Upload page should be configured to include the following options:

  • CC BY-NC-SA (set as default)
  • CC BY-NC-ND

and

On the Special:Upload page, below the Licensing field, there should be the following text: Additional information about Creative Commons license options can be found here.

Single-sign-on (SSO)[edit]

The site must implement single-sign-on using cookies (not LDAP, not OpenID, not Shibboleth, etc.) with our existing Drupal site (opossem.org), using Bakery or another similar tool. Users will sign-on only through the Drupal site (opossem.org, master) and be redirected to the Wiki (wiki.opossem.org, slave). Users will not be allowed to modify their user name or password from within the wiki, and this function should be disabled in the wiki. Any changes must be made on the Drupal site and then propagated to the Wiki site in a true "sync." Fields that should be synced automatically without admin intervention nor the creation of duplicate accounts:

  • user name,
  • first name
  • last name,
  • email, and
  • user roles (Contributor, Editor, Admin).

Clicking "login" on the wiki site should redirect to the Drupal login page, and likewise, clicking logout on either site should logout the user.

Display names/attribution[edit]

Rather than the username, the fields for FirstName and LastName should be used throughout for author attribution.

User page and talk[edit]

The user talk page will keep its default features. Users should be able to customize the notification settings for their talk pages, but they should not be able to change the email address to which notifications are sent. These should always go to registered email address in the Drupal database, which is kept in sync with the user tables in the Wiki.

Official page versions[edit]

The Flagged Revisions Extension (or a comparable alternative) should be used so that Editors can approve changes to particular pages in the Main, Introductory, Intermediate, and Advanced namespaces. The default view of any page should be the "live" wiki version of the page (including any changes that have yet to be approved).

Each summer (and perhaps winter, too), editors will review changes to pages since the last official version of the page and "approve" changes to create the official/protected version of the page.

The Flagged Revisions Extension may need to be customized or modified to archive each of these "approved" versions, which should be stamped with the year/issue of the revision. For instance, the "official" versions will numbered:

  • 2012.1
  • 2012.2
  • 2012.3
  • 2013.1

This will allow users to find the most recent "stable" version, but also have a numbering system that is flexible enough for editors to adjust the "issue" or version timing.<ref> Question for Team: Need to figure out how to explain this because we'll want annual editions of the textbook to stay static. [PAS: Correct, and version control is really important, but I'm guessing that in the early stages, annual will be too infrequent -- what about starting at least with the assumption of two updates a year, 1 Jan and 1 July, or maybe 1 Dec and 1 June so people have some time to get changes in place before the start of the winter semester/quarter]. MD: You're right, Phil. And we can decide how frequently the review/approved versions get updated later. Right now, we need to provide feedback about how we would like these archived versions to be organized/stored. In particular, we need to decide if we want to request custom categories of review status (see http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology, for the defaults), or if we just want to tell the wiki developers that we want the 'stable' version to be based on the most recent version of a page that meets some certain threshold across the 3 categories, for example: Accurate, Moderate, Good.</ref>

There will need to be a Special:Page (or some other type of page) that allows users to view:

  • all the most recent stable/official versions (as opposed to the live version)
  • choose a specific official version (e.g., 2012.1) and see a link to all pages that were included in that version.<ref>Does this make sense? How could it be clearer?</ref>

There will need to be the possibility for a registered user to view/download/save to their book collection any of the prior "stable" versions of their choosing.

Download/Output options[edit]

Users should be able to download any page, or collection of pages (see books below), in each of the following formats:

  1. LaTeX (cf: http://www.mediawiki.org/wiki/Extension:Wiki2LaTeX)
  2. Acrobat .pdf
  3. epub (cf: http://www.mediawiki.org/wiki/Extension:EPubExport)
  4. Open document format (.odt) (cf: http://www.mediawiki.org/wiki/Extension:OpenDocument_Export, although the new version of Extensions:Collection claims to include this, too)
  5. HTML5 + CSS<ref>[PAS: So, here's my read on this situation, but I'm not an expert on it and would be happy to hear other opinions.

It seems as though epub is clearly emerging as the dominant non-proprietary standard (and seems stable), and then there are converters which can go from epub to Kindle and mobi -- in particular, calibre, which is open source. The only major platform that currently doesn't support epub is, of course, the Kindle, but it is possible Amazon will stop being jackasses and do so, particularly since Apple and Android do support it. So seems to me we assume that epub is our "core" e-book format, and then just use converters, even though the results might not be quite a slick (though .mobi seems mostly to support a bunch of things we wouldn't use anyway). My sense -- and I say this as someone who uses Kindle software on my phone and laptop almost daily -- is that for the student audience, making sure it works on the iPad and on small laptops (MacAir and the various Windows equivalents) is more important than working on the Kindle or phones -- in particular, graphics and anything except simple equations will be really hard on a phone. And Kindles seem more common for leisure reading, and of course the older Kindles don't support color. The new "Fire" does, but seems to have disabled epub support despite running on the Android system. Though they are getting a lot of flak for this from users. But they are Amazon.

By "XML", do you mean the raw Wiki text? The other format that might be useful would be HTML5, though that might be subsumed under the XML format, and there are also LaTeX to HTML programs. MD: Ok, so after consulting with my in-house Information Professional (i.e. grad student husband) it seems that most people wouldn't have a need for the XML, and anyone geeky enough to need it would be able to figure out that you can already export any mediawiki page as XML using Special:Export. HTML5 would be good, however, because I might imaging someone wanting to export the textbook (or parts) as HTML5, which they then upload as a page to the proprietary Desire2Learn, Blackboard, etc. system. Again, happy to hear other opinions.] (SN: As long as people have the option to convert easily (i.e. not having to download a random converter they are unlikely to use for much else), I would support the less is more approach. As an instructor, I would be more likely to use my kindle, but I agree that my students likely wouldn't.) CNL: Seems to me we'd want to include PDF as an option just simply because it should be the easiest for someone to put on dead trees without having to find any fancy converter software. These days you can dump a PDF on a flash drive and plug it directly into a laser printer... not so much with Word files or HTML or epub... </ref>

Most of these output types are included in the updated version of http://www.mediawiki.org/wiki/Extension:Collection.

Ability to process/translate .odt and LaTeX files into MediaWiki markup[edit]

Ideally, it would be possible for users to contribute content as new pages or parts of existing pages based on documents they already have in another file/syntax format, including .odt, .doc, and/or .tex.

If possible, a custom tool to translate such content into in mediawiki markup, which the user could then copy/paste into the relevant pages, would be ideal.

This could be a Special:Page where registered users copy/paste OR upload the document, it is processed by the server, and then displayed in mediawiki markup for them to copy/paste into the desired page.

(see, for example: http://www.mediawiki.org/wiki/Extension:Word2MediaWikiPlus)

Banners[edit]

For reference: wikipedia:Wikipedia:Template_messages/Cleanup

Additional banners that should be created for OPOSSEM use[edit]

  • All pages in Namespaces:Introductory,Intermediate, and Advanced should have a banner (that can be dismissed) that appears only on the edit page above the edit box that says:
  1. Before editing, please consult the OPOSSEM Manual of Style.
  2. Use of inline notation should be limited. Instead, notation should be added to Namespace:Notation and transcluded here with tags.
  • Banner to warn that there is inline notation on a page, perhaps based on this cleanup template.
  • All pages in Namespace:Notation should have a banner that displays on the Namespace page but that is not transcluded with the text that says: "Warning: You are about to edit notation that may appear on multiple pages throughout the site. Please make sure any edits conform with OPOSSEM's Manual of Style."<ref>Team: Any other banners or special headlines that we might need to appear on the site?</ref>

User roles & permissions[edit]

Visitors to the site who are not registered users (through the main Drupal site) may read pages and browse the OPOSSEM library (including downloading versions of collections/books listed there). They should also be able to "export" pages using the export function. They should not, however, be able to create collections/books or edit any pages.

Other user roles for registered users will be assigned in the Drupal site and should be synced to the user table of the Wiki site, where they will inherit Wiki permissions defined below. Additional permissions/restrictions are included in descriptions of specific extensions/functions elsewhere in this document.

Since all users will inherit their user group from the Drupal site, the Special:UserRights page should be disabled for all users except Admins.

Users should be able to belong to multiple groups, or inherit rights of the group below them where the hierarchy is:

  1. Admin,
  2. Editor, and
  3. Contributor,

unless an exception/deviation is noted below.<ref>See Special:ListGroupRights for a list of group rights.</ref>

action Admin Editor Contributor
Inherit all default Bureaucrat rights X
Inherit all default Reviewer rights X X
Inherit all default User rights X X X
Edit pages (in default & main Namespaces, including Intro, Intermediate, Advanced, etc.) X X X
Edit templates X X
Create pages (in default & main Namespaces, including Intro, Intermediate, Advanced, etc.) X X X
Create templates X X
Create notation X X X
Edit notation X X X
Create definitions X X X
Edit definitions X X X
Import pages X X
Delete pages X
Protect pages* X X

*This is a deviation from the usual group permissions.

User contributions[edit]

User contributions must be displayed in a way that is easy for external reviewers/department chairs to "see" and evaluate. The default page view for User contributions (e.g., Special:Contributions/Michelle Dion) does not meet this requirement.<ref>[PAS: Have we had any further feedback on what reviewers/chairs would like to see in this regard? I could drop a line to the PolMeth fellows list --- which has a lot of former administrators, but mostly research universities --- and see if I get any ideas; is there something comparable we could get on the liberal arts college side? Also if we need some customized code for this part, I'm willing to put some work in on this piece (all the more so if that code could be perl or Python...) MD here: No, we haven't had any feedback on this specific feature. My thinking was that we needed to have a way to show a list of pages to which a person has contributed, and then, each page should clearly show what portions of the text was contributed by the particular user (as opposed to others). So, that was the goal of the formatting below. All this content is stored in the database, it's just a matter of having the programmer put together a custom view that pulls the various pieces together as needed. I think this is something the developer(s) should be able to do.]</ref>


In addition to the default contributions view (for example, Special:Contributions/Michelle_Dion), a custom page/view should be created for each user that will list each page or subpage the user has edited. Next to the title of the page on this list, the names of all the contributors to the page in descending order of percentage contribution (like the printed book contribution section: OPOSSEM:Specifications#User_created_books_and_User_bookshelf) should be listed. After each name, it should also include the date of the most recent revision to the page by each user. For instance: Michelle Dion (55%, 2012 May 10), Phil Schrodt (28%, 2012 May 5), and Shane Nordyke (17%, 2012 May 6). Those who have contributed fewer than 3% of the characters and/or all of whom's edits were marked as "minor edits" should be excluded from the calculation and list. In addition, there should be a link to "Download .pdf version" in this list, which when clicked would produce a .pdf version like that described below.

When the link to that page is clicked from this list, it will return a copy of the current page with the following characteristics: Display current version of page with content contributed by user (black) and others (grey) plus:

  • Any text added by user that has been subsequently deleted by any other user (Black text with strikeout)
  • Any text that was added by another user that was deleted by user (Grey text with strikeout)
  • Any deleted text from other users should not be displayed.

Sample Color Key:

  • Black text = Contributed by user
  • Grey text = Contributed by another user
  • Black text with strikeout = Text contributed by user and deleted by another user
  • Grey text with strikeout = Text contributed by another user and deleted by user

Example[edit]

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur bibendum ullamcorper viverra. Donec malesuada nulla nec augue aliquam eget mattis justo lacinia. Nunc mattis tempor lorem nec scelerisque. Donec aliquam tincidunt arcu, a egestas ante ultrices eget. Curabitur neque orci, rhoncus vitae gravida eu, blandit in nisl. Aliquam dui nisi, tincidunt sit amet lobortis gravida, rutrum eu elit. Donec lacinia, ante dignissim auctor dapibus, nulla nunc accumsan enim, eget vestibulum nibh est at mi. Ut enim eros, iaculis et fringilla sit amet, ullamcorper non urna. Nunc id semper sapien.

Cras faucibus malesuada pellentesque. Phasellus vitae magna diam, non iaculis dui. Aliquam hendrerit pellentesque ipsum, quis accumsan risus adipiscing nec.In vel tellus orci. Donec libero nunc, tristique non bibendum viverra, fermentum ut leo. Cras porta pharetra justo. Nulla aliquam placerat leo, a eleifend ligula tincidunt in. Maecenas dapibus, urna quis varius tincidunt, diam magna hendrerit massa, eget eleifend sem ante et massa. In et lacus ut quam venenatis consequat sit amet vitae eros. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin vulputate imperdiet nulla vel varius. Sed porttitor suscipit venenatis. Aenean tortor velit, sodales porttitor dapibus non, rhoncus ac lacus. Quisque aliquam adipiscing nisl at adipiscing. Pellentesque sodales sem a quam consequat tincidunt. Etiam orci eros, placerat in rhoncus a, tempor ut sapien.

Morbi tempor libero vitae neque consequat tristique. Morbi nisi dui, egestas at faucibus sed, tempor eu risus. Quisque faucibus molestie lectus, quis feugiat metus lobortis sit amet. Aenean et fringilla est. Sed turpis est, tempus ut aliquam id, consequat sed enim. Suspendisse interdum arcu sit amet tellus fermentum nec egestas purus scelerisque. Praesent at molestie quam. Proin eget augue vitae justo porttitor sodales. Nunc et lectus vitae nulla fringilla interdum non sit amet ante. Sed nec nibh ligula, non venenatis mi. Curabitur ultrices, nisl id faucibus laoreet, purus mi tempor tellus, id iaculis ipsum eros sed turpis. Curabitur luctus erat fermentum augue mattis ac dapibus mi lacinia.



At the bottom of the online page view, it should display a list all the contributors to the page in descending order of percentage contribution (like the printed book contribution section: OPOSSEM:Specifications#User_created_books_and_User_bookshelf. After each name, it should also include the date of the most recent revision to the page by each user. For instance: Michelle Dion (55%, 2012 May 10), Phil Schrodt (28%, 2012 May 5), and Shane Nordyke (17%, 2012 May 6). Those who have contributed fewer than 3% of the characters and/or all of whom's edits were marked as "minor edits" should be excluded from the calculation and list.

In addition, there should be a list of the collections/books of which the page is a part, which would provide an additonal measure of use or impact of the particular page.

The page should also have a button at the top or bottom of the page that says "Download this page," and when clicked, it would produce a .pdf version of the page to be viewed in a new browser window or downloaded, and the downloaded page should also include the formatted list of contributors, including their percentages, and the list of books mod which it is a part.<ref> Question for team: Should dates be included?? How/where?(SN: I think dates are a good idea, and the field will already be collected. Could we have the date show up when you scroll over the edit with your mouse? That seems like the most convenient place, but it wouldn't be printable.)MD:Does this address the issue sufficiently?</ref>

Specific pages that should be created[edit]

Main Page[edit]

The main page should have a brief overview of the textbook project (e.g., http://wiki.opossem.org/index.php?title=OPOSSEM:Specifications#Wiki_Objectives). In addition, the main page should provide a clear link to "Login" [which will redirect to the Drupal site]. It should also have a prominent link to the "How to get involved page" (below).<ref>(SN: I think it would be useful to have a brief history of the what and why. At the CanCon conference there was a lot of discussion the first day on what added value this project had to what was already available and how it fit into other markets. I assumed that a lot of the value added was relatively obvious, but it wasn't so we should take time to explain that somewhere.</ref>

It should also perhaps have links to the top five pages in each of the following categories/page types: 5 most recently updated pages 5 users that have most recently updated a page 5 users with the greatest number of pages revised 5 users with the greatest number of new pages created<ref>Any others that might appeal to user vanity?</ref>

It should also have a link to the OPOSSEM library, and ideally, would list the 5 most downloaded "books" in the collective library.

Once someone is logged in, this page should have a direct link to their bookshelf, and, if possible, it would be nice to have a memory built in so that you could see your most recent activity on the book (last page edited, etc.)

How to get involved[edit]

This page will have text that invites OPOSSEM community members to get involved, with a number of suggestions.

This page must also include a list of links to the following custom pages:

  1. A page that lists all the pages in the OPOSSEM namespace
  2. A page that lists all the pages in the Help namespace
  3. A page that lists all the pages in the Introductory namespace
  4. A page that lists all the pages in the Intermediate namespace
  5. A page that lists all the pages in the Advanced namespace
  6. Special:FewestRevisions
  7. Special:ShortPages
  8. Special:UnwatchedPages
  9. Special:WantedPages
  10. A page that lists all the pages tagged with one of the cleanup banners
  11. A page that lists all the pages that have been marked by Editors as sighted, basic, or good (or lower) (see: http://www.mediawiki.org/wiki/Help:Extension:FlaggedRevs#Terminology Flagged Revisions Terminology]
  12. Special:UnreviewedPages


All the pages listed in the Maintenance reports section of Special:SpecialPages

All the pages listed in the List of pages section of Special:SpecialPages

Tools for Editors[edit]

This page should include the relevant links for editors to use. This includes all the links in the Quality Assurance section of Special:SpecialPages.

Anything an editor can do but that no other users can do should appear on this page to make it easier for editors to see what tools they have.

There should also be a link to a list of Special pages generated by the Flagged Revisions Extension, including:

These links will enable editors to quickly find a list of pages that need review since the last set of reviews.

In addition, there should be a link to view all pages tagged with banners that warn of inappropriate content. Editors should automatically be notified by email when any page gets one of those banners added.<ref>PAS:We need a facility for sending alerts to the editors in case of incorrect/inappropriate content. MD: I think this should work. However, we need to identify a list of the banners that we think we should be notified about. Here's an annotated list of available clean up banners: [1], many of which (and some others), I've already identified to be imported and/or modified for our use (see OPOSSEM:Specifications/CleanupBanners. Once development begins, someone will need to let the developer know which of these clean up banners should trigger a notification. </ref>

Others?[edit]

Wiki visual design[edit]

The MediaWiki skin or website design must incorporate design elements from the existing OPOSSEM Drupal site. In particular, the Wiki site must:

  1. Use visual elements, the logo, and colors already in use on the Drupal site
  2. Not use a theme that looks in any way like the default Wikipedia theme

The wiki need not look exactly like the Drupal site and indeed should look more like a book or wiki site than the main Drupal site. That is, the Wiki theme need not be fully integrated into the main Drupal site, but the two sites should share common design elements and a similar 'look'.

Skins[edit]

Free Wiki Skin seems fairly similar already to the main site, and perhaps could be easily adapted for OPOSSEM. Another skin that has a very different feel from Wikipedia and would perhaps be easy to adapt to look like OPOSSEM is Erudite.

Wiki extensions[edit]

All active extensions are listed on the Special:Version page.

List of special extensions for reference:

  • Collection - create books
  • Delete Batch - deletes a batch of pages
  • Flagged Revisions - Gives Editors and Reviewers the ability to review revisions and stabilize pages
  • Nuke - Gives administrators the ability to mass delete pages
  • SpecialInterwiki - Adds a special page to view and edit the interwiki table
  • User Merge and Delete - Merges references from one user to another user in the wiki database - will also delete old users following merge. Requires usermerge privileges
  • AuthDrupal - Signin integration for MediaWiki as slave of Drupal.
  • Category Tree - The CategoryTree extension provides a dynamic view of the wiki's category structure as a tree
  • Cite - Adds <ref[ name=id]> and references /> tags, for citations
  • InputBox - Allow inclusion of predefined HTML forms
  • ParserFunctions - Enhance parser with logical functions
  • SyntaxHighlight - Provides syntax highlighting using GeSHi Highlighter
  • WYSIWYG extension - Extension for editing wiki pages (WYSIWYG editor) [The newer versions of Mediawiki have a built in WYSIWYG editor.]
  • Preloader - Provides customisable per-namespace boilerplate text for new pages
  • SubPageList - Provides facility to list subpages on their parent page
  • Validator - supports SubPageList

Notes[edit]

<references group=""></references>